Majik Envelope

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
  • Overview
    • Key Features
  • Installation
  • Usage Guide
    • Encrypting a Message (Single Recipient)
    • Encrypting for a Group (2+ Recipients)
    • Decrypting an Envelope
  • Technical Specifications Reference
    • 1. Cryptographic Stack (Envelope)
    • 2. Binary Structure & Framing
      • Internal Binary Layout (Decoded Base64):
    • 3. Primitive Parameters
    • 4. Encryption Logic Flows
      • A. Single-Recipient (Direct)
      • B. Multi-Recipient (Group)
    • 5. Implementation Notes
  • Related Projects
    • Majik Message
    • Majik Key
  • Contributing
  • License
  • Author
  • About the Developer
  • Contact

Overview

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.

Key Features

• 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 MajikCompressor to reduce message size.
• Strict Format: Binary-backed envelopes with a standardized Base64 string representation (~*$MJKMSG:).

Installation

npm install @majikah/majik-envelope

Usage Guide

Encrypting a Message (Single Recipient)

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...

Encrypting for a Group (2+ Recipients)

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...

Decrypting an Envelope

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.");
}

Technical Specifications Reference

1. Cryptographic Stack (Envelope)

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 |

2. Binary Structure & Framing

The library produces a "Scanner-Ready" string. This is a Base64-encoded binary blob prefixed with a protocol identifier.

Format: ~*$MJKMSG:<Base64_Payload>

Internal Binary Layout (Decoded Base64):

| 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. |

3. Primitive Parameters

| 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. |

4. Encryption Logic Flows

A. Single-Recipient (Direct)

1. Compress: Plaintext is compressed using Zstd (or Gzip fallback).
2. Encapsulate: Generate a sharedSecret (32b) and mlKemCipherText (1088b) using the recipient's Public Key.
3. Encrypt: Encrypt the compressed data via AES-256-GCM using the sharedSecret as the key.
4. Pack: Encode the iv, ciphertext, and mlKemCipherText into a SinglePayload JSON object.

B. Multi-Recipient (Group)

1. Compress: Plaintext is compressed.
2. Key Generation: Generate a random 32-byte masterAesKey.
3. Encrypt: Encrypt the compressed data via AES-256-GCM using the masterAesKey.
4. Wrap Keys: For each recipient:
   • Perform ML-KEM encapsulation to get a unique sharedSecret.
   • encryptedAesKey = masterAesKey XOR sharedSecret.
   • Store the recipient's fingerprint, mlKemCipherText, and encryptedAesKey.
5. Pack: Encode the iv, ciphertext, and the array of keys into a GroupPayload JSON object.

5. Implementation Notes

• 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 MajikCompressor automatically handles decompression by identifying the mjkcmp magic header, ensuring compatibility even if compression settings change.

Related Projects

Majik Message

Secure messaging platform using Majik Keys

Read more about Majik Message here

Click the image to try Majik Message live.

Read Docs

Also available on Microsoft Store for free.

Official Repository SDK Library

Majik Key

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

Contributing

If you want to contribute or help extend support to more platforms, reach out via email. All contributions are welcome!

License

Apache-2.0 — free for personal and commercial use.

Author

Made with 💙 by @thezelijah

About the Developer

• Developer: Josef Elijah Fabian
• GitHub: https://github.com/jedlsf
• Project Repository: https://github.com/Majikah/majik-envelope

Contact

• Business Email: [email protected]
• Official Website: https://www.thezelijah.world