SOURCE_URL: https://majikah.solutions/products/majik-buwiz/docs/buwiz-security-overview

---
title: "Security Architecture of Majik Buwiz"
id: "buwiz-security-overview"
group: "majik-buwiz"
type: "products"
version: "0.1.1"
lastUpdated: "2026-05-13T00:00:00.000Z"
difficulty: "Intermediate"
time: "8–12 minutes"
tags: [security, cryptography, post-quantum, ed25519, ml-dsa-87, fips-204, ml-kem-768, fips-203, aes-256-gcm, argon2id, sha-256, sha3-512, dual-signature, zero-knowledge, offline-first]
---

# Security Architecture of Majik Buwiz

> How Majik Buwiz protects your invoices — the full cryptographic stack explained

## Overview
A technical reference for the cryptographic architecture of Majik Buwiz — covering dual digital signatures, optional encryption, key derivation, seal integrity, and the zero-knowledge relay design. All algorithms referenced here are drawn directly from the production codebase.

### Why cryptographic invoices?

A standard invoice is just a document — there is nothing stopping a malicious actor from creating a convincing copy, changing the amounts, swapping bank details, or issuing invoices in your name entirely. Majik Buwiz addresses this by sealing every invoice with a digital signature the moment it is issued. If the invoice is modified after signing — any field, any amount, any recipient — the signature fails verification immediately. No one can issue a valid Majik Buwiz invoice on your behalf without your private key, which never leaves your device.

### Dual digital signatures on every invoice

Every invoice in Majik Buwiz is signed with two independent algorithms simultaneously: Ed25519 (a classical elliptic-curve signature algorithm with a long track record in production systems) and ML-DSA-87 (CRYSTALS-Dilithium, standardized by NIST as FIPS-204, a post-quantum signature algorithm resistant to attacks from quantum computers). Both signatures are computed over the same canonical content and stored together in the invoice's integrity block. Either algorithm alone would be sufficient by today's standards — having both means the invoice remains verifiable even if one algorithm is later broken.

> **NOTE:** The signature covers the financial content of the invoice only — line items, taxes, parties, dates, currency, invoice number, references, and payment terms. Fields that change after signing as part of normal workflow — status, notes, tags, metadata, proof-of-payment records, and timestamps — are intentionally excluded. This means a signed invoice can move through its lifecycle (draft → issued → sent → paid) without invalidating the original signature.

### How signing works internally

When you sign an invoice, Majik Buwiz serializes the financial fields into a deterministic canonical JSON (keys sorted alphabetically, no whitespace) and computes a SHA-256 hash of those bytes. That hash is then combined with the invoice ID into a signing input in the form "majik-invoice-v1:" + JSON({ contentHash, id }), which is what both Ed25519 and ML-DSA-87 sign. The resulting signature entry contains the signer's Ed25519 public key, their ML-DSA-87 public key, the signer ID (fingerprint), a timestamp, and both signature values — everything a recipient needs to verify the invoice independently.

### Signing algorithms

| Algorithm | Standard | Type | Role |
| --- | --- | --- | --- |
| Ed25519 | RFC 8032 | Classical elliptic-curve | Fast, widely trusted signature standard |
| ML-DSA-87 (CRYSTALS-Dilithium) | NIST FIPS-204 | Post-quantum lattice-based | Forgery-resistant against quantum and classical attacks |

*Caption: Both algorithms are applied to every invoice automatically.*

### Sealing an invoice

After all expected signers have signed, the issuer can seal the invoice. A sealed invoice is permanently locked — no further signatures can be added or modified. The seal itself is computed as a SHA3-512 hash over all signature entries (sorted by signer ID) combined with a seal timestamp and a domain separator. This seal hash is stored alongside the invoice so any party can verify the seal independently. Once sealed, the invoice's cryptographic state is final.

### Optional encryption for confidential invoices

When full confidentiality is required, Majik Buwiz adds an encryption layer on top of signing. The encryption scheme uses ML-KEM-768 (CRYSTALS-Kyber, standardized by NIST as FIPS-203) for key encapsulation and AES-256-GCM for symmetric encryption of the invoice payload.

### How encryption works internally

For a single recipient, ML-KEM-768 encapsulation is run against the recipient's public key, producing a 32-byte shared secret and a 1088-byte ciphertext. That 32-byte shared secret is used directly as the AES-256-GCM key — no additional KDF step. A 12-byte IV is generated using a cryptographically secure random number generator for each encryption operation. The invoice JSON is compressed before encryption (transparent to the user). For multi-recipient invoices, a random 32-byte AES key is generated once, the message is encrypted with it, and each recipient's share of that AES key is XOR-masked with their individual ML-KEM shared secret. ML-KEM decapsulation never throws on a wrong key — it silently returns a garbage shared secret, which causes AES-GCM authentication tag verification to fail, surfacing as a decryption error.

### Encryption algorithms

| Algorithm | Standard | Type | Role |
| --- | --- | --- | --- |
| ML-KEM-768 (CRYSTALS-Kyber) | NIST FIPS-203 | Post-quantum lattice-based KEM | Key encapsulation — produces the shared secret used as the AES key |
| AES-256-GCM | NIST FIPS-197 / SP 800-38D | Classical symmetric encryption | Authenticated encryption of the invoice payload |

*Caption: Used only when encryption mode is selected or when sending via the Invoice Cloud Exchange.*

> **NOTE:** Even on encrypted invoices, a minimal public summary remains plaintext — issuer name, recipient name, currency, total amount, invoice type, issue date, and status. This is intentional: it allows recipients to identify and preview an invoice before committing to the decryption operation. No line-item detail or sensitive financial data is exposed in the public summary.

### How your private keys are protected locally

Your Majik Key is a seed-phrase-based account (BIP-39, 12 words). From the 64-byte BIP-39 seed, two keypairs are derived deterministically: an Ed25519 keypair (converted to X25519 via the ed2curve transform for encryption use) from the first 32 bytes of the seed, and an ML-KEM-768 keypair from the full 64 bytes of the seed. An ML-DSA-87 keypair is derived separately using a domain-separated 32-byte seed. All private key material is encrypted at rest using AES-256-GCM with a 32-byte key derived from your passphrase via Argon2id. The Argon2id parameters are tuned for memory-hardness to resist brute-force attacks. The passphrase itself is never stored — only the Argon2id-derived wrapping key is used to encrypt the key material, and only for the duration of the operation. Existing accounts created before the Argon2id migration are automatically re-encrypted with Argon2id the next time a passphrase change is performed.

### Key derivation summary

| Key | Derived from | Used for |
| --- | --- | --- |
| Ed25519 signing keypair | BIP-39 seed bytes 0–31 | Invoice signing (classical) |
| X25519 encryption keypair | Ed25519 keypair via ed2curve | Fingerprint generation and legacy envelope compatibility |
| ML-KEM-768 keypair | Full 64-byte BIP-39 seed | Post-quantum key encapsulation (encryption) |
| ML-DSA-87 keypair | Domain-separated 32-byte seed | Invoice signing (post-quantum) |

*Caption: All keys are derived deterministically from the 12-word seed phrase.*

### Session model

When you open Majik Buwiz and enter your passphrase, the key is decrypted into memory for that session only. The in-memory key state is cleared when the app is closed or restarted. There is no persistent unlocked state between sessions. For encrypted invoices, a decrypted cache is held in memory only for the duration of the current session — calling secureLock() explicitly clears it. The key is never written to disk in plaintext at any point.

### Zero-knowledge relay

The Invoice Cloud Exchange operates as a zero-knowledge relay — the Majikah server stores only the encrypted invoice envelope and the public summary. It cannot read invoice contents. All invoices sent through the Exchange are automatically upgraded to encrypted-and-signed mode before transmission, regardless of their local mode. Encrypted invoice data is automatically deleted from the relay after 30 days unless updated by participants. Users are responsible for syncing and storing received invoices to their local database before that window closes.

> **NOTE:** Majik Buwiz uses NIST-standardized post-quantum algorithms (FIPS-203 for ML-KEM-768, FIPS-204 for ML-DSA-87). No formal third-party security audit has been conducted and no FIPS compliance certification is claimed. The implementation uses @noble/post-quantum and @stablelib libraries for all cryptographic primitives.

### Complete cryptographic stack

| Algorithm | Purpose | Library |
| --- | --- | --- |
| Ed25519 | Classical invoice signing | @stablelib/ed25519 |
| ML-DSA-87 (FIPS-204) | Post-quantum invoice signing | @noble/post-quantum |
| ML-KEM-768 (FIPS-203) | Post-quantum key encapsulation | @noble/post-quantum |
| AES-256-GCM | Symmetric invoice payload encryption | @stablelib/aes + @stablelib/gcm |
| SHA-256 | Content hash for signing commitment | @stablelib/sha256 |
| SHA3-512 | Seal hash computation | @noble/hashes |
| Argon2id | Passphrase-based key derivation (key protection) | @noble/hashes |
| BIP-39 (PBKDF2-SHA512) | Seed phrase to 64-byte seed derivation | bip39 |

*Caption: Every algorithm used in Majik Buwiz and its purpose.*