Majik Envelope is the core cryptographic engine of the Majik Message platform. It provides a post-quantum secure "envelope" format that handles message encryption, multi-recipient key encapsulation, and transparent compression using NIST-standardized algorithms.
- Majik Envelope
Majik Envelope implements Envelope Format, which exclusively uses ML-KEM-768 (FIPS-203) for post-quantum security. It abstracts away the complexity of managing shared secrets, AES-GCM initialization vectors, and multi-recipient key wrapping, allowing developers to focus on sending secure messages.
- Post-Quantum Security: Exclusively uses ML-KEM-768 for key encapsulation.
- Hybrid Encryption: Combines ML-KEM shared secrets with AES-256-GCM for high-speed content encryption.
- Group Messaging: Native support for 1-to-many encryption using a single-ciphertext, multi-key-wrap approach.
- Transparent Compression: Built-in Zstd and Gzip support via
MajikCompressorto reduce message size. - Strict Format: Binary-backed envelopes with a standardized Base64 string representation (
~*$MJKMSG:).
npm install @majikah/majik-envelope
The library automatically chooses between "Single" and "Group" logic based on the number of recipients.
import { MajikEnvelope } from "@majikah/majik-envelope";
const envelope = await MajikEnvelope.encrypt({
plaintext: "Hello, this is a quantum-safe secret.",
recipients: [{
fingerprint: "recipient_fingerprint_base64",
mlKemPublicKey: recipientPublicKeyBytes // Uint8Array (1184 bytes)
}],
compress: true // Default is true
});
// Convert to the scanner-ready string
const secretString = envelope.toString();
// Output: ~*$MJKMSG:AbC123...
For group messages, a senderFingerprint is required for metadata.
import { MajikEnvelope } from "@majikah/majik-envelope";
const groupEnvelope = await MajikEnvelope.encrypt({
plaintext: "Secret group meeting at midnight.",
senderFingerprint: "my_fingerprint_base64",
recipients: [
{ fingerprint: "alice_fp", mlKemPublicKey: alicePk },
{ fingerprint: "bob_fp", mlKemPublicKey: bobPk }
]
});
// Convert to the scanner-ready string
const secretString = groupEnvelope.toString();
// Output: ~*$MJKMSG:AbC123...
To decrypt, you simply provide the recipient's identity (their private ML-KEM key and fingerprint).
import { MajikEnvelope } from "@majikah/majik-envelope";
const identity = {
fingerprint: "my_fingerprint_base64",
mlKemSecretKey: mySecretKeyBytes // Uint8Array (2400 bytes)
};
try {
// Option 1: Decrypt from an existing instance
const decrypted = await envelope.decrypt(identity);
// Option 2: Parse from a string first
const parsedEnvelope = MajikEnvelope.fromString("~*$MJKMSG:...");
const text = await parsedEnvelope.decrypt(identity);
console.log(text); // "Hello, this is a quantum-safe secret."
} catch (error) {
console.error("Decryption failed: Unauthorized or tampered message.");
}Majik Envelope is designed to be Post-Quantum Secure (PQS) by default, moving away from classical ECC for key encapsulation.
| Component | Primitive | Implementation / Standard |
|---|---|---|
| Key Encapsulation (KEM) | ML-KEM-768 | FIPS-203 (formerly Kyber) |
| Symmetric Encryption | AES-256-GCM | NIST SP 800-38D |
| Hashing / Fingerprinting | SHA-256 | FIPS 180-4 |
| Key Derivation (KDF) | Argon2id | OWASP Recommended (v2 accounts) |
| Compression | Zstd / Gzip | @bokuweb/zstd-wasm / fflate |
The library produces a "Scanner-Ready" string. This is a Base64-encoded binary blob prefixed with a protocol identifier.
Format: ~*$MJKMSG:<Base64_Payload>
| Offset (Bytes) | Length | Field | Description |
|---|---|---|---|
0 |
1 | Version | Set to 0x03 for current PQ format. |
1 |
32 | Fingerprint | SHA-256 of the recipient (Single) or Sender (Group). |
33 |
Variable | Payload | UTF-8 JSON string containing IVs and ciphertexts. |
| Parameter | Value | Description |
|---|---|---|
ML_KEM_PK_LEN |
1184 bytes | ML-KEM-768 Public Key size. |
ML_KEM_SK_LEN |
2400 bytes | ML-KEM-768 Secret Key size. |
ML_KEM_CT_LEN |
1088 bytes | ML-KEM-768 Ciphertext (encapsulation). |
AES_KEY_LEN |
32 bytes | 256-bit symmetric key. |
IV_LENGTH |
12 bytes | Standard GCM Initialization Vector length. |
- Compress: Plaintext is compressed using Zstd (or Gzip fallback).
- Encapsulate: Generate a
sharedSecret(32b) andmlKemCipherText(1088b) using the recipient's Public Key. - Encrypt: Encrypt the compressed data via AES-256-GCM using the
sharedSecretas the key. - Pack: Encode the
iv,ciphertext, andmlKemCipherTextinto aSinglePayloadJSON object.
- Compress: Plaintext is compressed.
- Key Generation: Generate a random 32-byte
masterAesKey. - Encrypt: Encrypt the compressed data via AES-256-GCM using the
masterAesKey. - Wrap Keys: For each recipient:
- Perform ML-KEM encapsulation to get a unique
sharedSecret. encryptedAesKey = masterAesKey XOR sharedSecret.- Store the recipient's
fingerprint,mlKemCipherText, andencryptedAesKey.
- Perform ML-KEM encapsulation to get a unique
- Pack: Encode the
iv,ciphertext, and the array ofkeysinto aGroupPayloadJSON object.
- Authentication: AES-GCM provides AEAD (Authenticated Encryption with Associated Data). If a message is tampered with or the wrong key is used, decryption will throw an "Auth tag mismatch" error.
- Quantum Resistance: Because the symmetric key is derived via ML-KEM-768, the message remains secure even against future Shor's algorithm-based attacks that would break RSA or Elliptic Curve (X25519) systems.
- Graceful Degradation: The
MajikCompressorautomatically handles decompression by identifying themjkcmpmagic header, ensuring compatibility even if compression settings change.
Secure messaging platform using Majik Keys
Read more about Majik Message here
Click the image to try Majik Message live.
Also available on Microsoft Store for free.
Official Repository SDK Library
Majik Key is a seed phrase account library for creating, managing, and parsing mnemonic-based cryptographic accounts (Majik Keys). Generate deterministic key pairs from BIP39 seed phrases with simple, developer-friendly APIs. Now supports ML-KEM-768 post-quantum key derivation alongside X25519.
Read Docs Official Repository SDK Library
If you want to contribute or help extend support to more platforms, reach out via email. All contributions are welcome!
Apache-2.0 — free for personal and commercial use.
Made with 💙 by @thezelijah
- Developer: Josef Elijah Fabian
- GitHub: https://github.com/jedlsf
- Project Repository: https://github.com/Majikah/majik-envelope
- Business Email: business@thezelijah.world
- Official Website: https://www.thezelijah.world