@majikah/majik-key 0.1.1 → 0.1.2

package/README.md

@@ -2,22 +2,26 @@
 
 [![Developed by Zelijah](https://img.shields.io/badge/Developed%20by-Zelijah-red?logo=github&logoColor=white)](https://thezelijah.world) ![GitHub Sponsors](https://img.shields.io/github/sponsors/jedlsf?style=plastic&label=Sponsors&link=https%3A%2F%2Fgithub.com%2Fsponsors%2Fjedlsf)
 
-**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.
+**Majik Key** is a next-generation seed phrase account library for creating and managing mnemonic-based identities. It provides a post-quantum ready, high-security bridge between BIP39 mnemonics and the Majikah ecosystem.
 
-![npm](https://img.shields.io/npm/v/@majikah/majik-key) ![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-key) ![npm bundle size](https://img.shields.io/bundlephobia/min/%40thezelijah%2Fmajik-key) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
+![npm](https://img.shields.io/npm/v/@majikah/majik-key) ![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-key) ![npm bundle size](https://img.shields.io/bundlephobia/min/%40majikah%2Fmajik-key) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
 
 
 
 ---
 - [Majik Key](#majik-key)
+  - [Next-Gen Security Architecture](#next-gen-security-architecture)
+    - [1. Post-Quantum Ready (ML-KEM)](#1-post-quantum-ready-ml-kem)
+    - [2. Argon2id Key Derivation](#2-argon2id-key-derivation)
+    - [3. Seamless Auto-Migration](#3-seamless-auto-migration)
   - [Overview](#overview)
     - [What is a Majik Key?](#what-is-a-majik-key)
     - [Use Cases](#use-cases)
   - [Features](#features)
-    - [Security First](#security-first)
-    - [BIP39 Compliance](#bip39-compliance)
-    - [Developer Friendly](#developer-friendly)
-    - [Import/Export](#importexport)
+    - [Security \& Post-Quantum Readiness](#security--post-quantum-readiness)
+    - [BIP39 Compliance \& Key Derivation](#bip39-compliance--key-derivation)
+    - [Developer Experience](#developer-experience)
+    - [Import / Export \& Storage](#import--export--storage)
     - [Interoperability](#interoperability)
   - [Installation](#installation)
   - [Quick Start](#quick-start)
@@ -65,7 +69,6 @@
     - [Converting to Majik Message Identity](#converting-to-majik-message-identity)
   - [Security Considerations](#security-considerations)
     - [Best Practices](#best-practices)
-    - [Security Features](#security-features)
     - [What NOT to Do](#what-not-to-do)
     - [What TO Do](#what-to-do)
     - [Tips \& Reminders](#tips--reminders)
@@ -80,8 +83,33 @@
   - [Contact](#contact)
 
 
+
+
 ---
 
+## Next-Gen Security Architecture
+
+Majik Key has been upgraded to meet modern and future cryptographic standards.
+
+### 1. Post-Quantum Ready (ML-KEM)
+Every identity now generates a dual-key system derived deterministically from a 64-byte BIP39 seed:
+* **X25519 (Curve25519):** Derived from the first 32 bytes of the seed. Used for fingerprints, contact identity, and legacy compatibility.
+* **ML-KEM-768 (FIPS-203):** Derived from the full 64-byte seed. Provides post-quantum key encapsulation for "v3" secure envelopes.
+
+### 2. Argon2id Key Derivation
+We have transitioned to **Argon2id** (KDF v2) for encrypting private keys at rest.
+* **Memory-Hard:** Configured with 128 MB of memory, 4 iterations, and 4 parallelism factors.
+* **Brute-Force Resistant:** Engineered to defeat GPU and ASIC-based cracking attempts that easily bypass older PBKDF2 implementations.
+
+### 3. Seamless Auto-Migration
+The library handles "Security Debt" automatically during standard workflows:
+* **On Import:** `importFromMnemonicBackup()` detects v1 (PBKDF2) accounts and performs a full upgrade to v2. 
+* **Deterministic Recovery:** If ML-KEM keys are missing from an old backup, they are re-derived from the mnemonic during the upgrade process.
+* **Password Updates:** Changing a passphrase via `updatePassphrase()` automatically migrates the account to the latest Argon2id standard.
+---
+
+
+
 ## Overview
 
 **Majik Key** is a comprehensive library for managing seed phrase-based cryptographic accounts. It provides a secure, intuitive way to create, store, and manage mnemonic-based identities with built-in encryption, backup, and recovery features.
@@ -107,33 +135,35 @@ A Majik Key is a seed phrase account that:
 
 ## Features
 
-### Security First
-- **Encrypted at Rest**: Private keys are encrypted with PBKDF2-derived keys (200,000 iterations)
-- **AES-GCM Encryption**: Industry-standard authenticated encryption
-- **Locked/Unlocked States**: Private keys only exist in memory when explicitly unlocked
-- **Per-Identity Salts**: Each account uses a unique salt for encryption
-
-### BIP39 Compliance
-- **Standard Mnemonic Generation**: Generate 12 or 24-word seed phrases
-- **Mnemonic Validation**: Built-in BIP39 validation
-- **Deterministic Key Derivation**: Same mnemonic always produces the same keys
-
-### Developer Friendly
-- **TypeScript Support**: Full type definitions included
-- **Simple API**: Intuitive CRUD operations
-- **Error Handling**: Comprehensive error messages with `MajikKeyError`
-- **Method Chaining**: Fluent API for common operations
-
-### Import/Export
-- **JSON Serialization**: Safe storage format (no private keys exposed)
-- **Mnemonic Backup**: Export/import encrypted backups using mnemonic phrases
-- **MnemonicJSON Format**: Compatible format for seed phrase storage
+### Security & Post-Quantum Readiness
+- **Post-Quantum Ready**: Implements **ML-KEM-768 (FIPS-203)** for key encapsulation, ensuring identities are secure against future quantum computing threats.
+- **Argon2id Key Derivation**: Uses memory-hard **Argon2id** (KDF v2) for passphrase encryption (128 MB / 4 iterations / 4 parallelism), providing industry-leading resistance to GPU/ASIC brute-force attacks.
+- **Seamless Auto-Migration**: Automatically detects and upgrades legacy v1 (PBKDF2) accounts to v2 (Argon2id) during import, re-deriving missing ML-KEM keys deterministically from the seed.
+- **AES-GCM Authenticated Encryption**: Industry-standard encryption for private keys at rest with unique, per-identity salts and random IVs.
+- **Locked/Unlocked States**: Private keys are only decrypted into memory when explicitly unlocked and are purged immediately upon calling `.lock()`.
+
+### BIP39 Compliance & Key Derivation
+- **Standard Mnemonic Generation**: Generate high-entropy 12 or 24-word seed phrases (128/256-bit strength).
+- **Deterministic Multi-Key Derivation**: 
+    - **X25519 (Curve25519)**: Derived from the first 32 bytes of the seed for legacy compatibility and fingerprints.
+    - **ML-KEM-768**: Derived from the full 64-byte seed for post-quantum security.
+- **Built-in Validation**: Full BIP39 mnemonic validation and error handling.
+
+### Developer Experience
+- **First-Class TypeScript Support**: Full type definitions included for all interfaces and classes.
+- **Fluent API**: Intuitive method chaining for common operations (e.g., `key.unlock(p).updateLabel(l)`).
+- **Comprehensive Error Handling**: Specialized `MajikKeyError` and `CryptoError` classes for precise debugging.
+- **Isomorphic Support**: Works across Node.js and modern browser environments.
+
+### Import / Export & Storage
+- **Security-Minded JSON Serialization**: Export accounts to JSON format for storage without ever exposing raw private keys or seed phrases.
+- **MnemonicJSON Format**: A secure, portable format for seed phrase storage and recovery.
+- **Mnemonic-Encrypted Backups**: Export and import specialized backup strings that utilize the mnemonic as a secondary encryption layer.
 
 ### Interoperability
-- **Majik Message Compatible**: Seamlessly import/export to Majik Message
-- **Majik Contact Integration**: Convert keys to contact format
-- **Majikah Ecosystem**: Works across all Majikah products
-
+- **Majik Message Integration**: Native support for exporting identities compatible with **Majik Message v3** envelopes.
+- **Contact Portability**: Convert Majik Keys directly into contact formats for easy sharing of public identities.
+- **Ecosystem Ready**: Designed as the core identity provider for all current and future Majikah products.
 ---
 
 ## Installation
@@ -156,14 +186,12 @@ const mnemonic = MajikKey.generateMnemonic(); // 12 words
 console.log('Save this mnemonic:', mnemonic);
 
 // Create a new Majik Key (unlocked state)
-const key = await MajikKey.create(
-  mnemonic,
-  'my-secure-passphrase',
-  'My First Key'
-);
+const key = await MajikKey.create(mnemonic, 'secure-passphrase', 'My PQ Account');
 
-console.log('Key ID:', key.id);
+// 2. Access your keys (requires unlock)
 console.log('Fingerprint:', key.fingerprint);
+console.log('PQ Ready:', key.metadata.kdfVersion); // 'argon2id'
+console.log('Key ID:', key.id);
 console.log('Is Unlocked:', key.isUnlocked); // true
 
 // Lock the key (clear private keys from memory)
@@ -194,7 +222,7 @@ await loadedKey.unlock('my-secure-passphrase');
 ### Static Methods
 
 #### `MajikKey.create(mnemonic, passphrase, label?)`
-Create a new Majik Key from a mnemonic phrase.
+Create a new Majik Key from a mnemonic phrase. Generates a new Argon2id-protected account.
 
 **Parameters:**
 - `mnemonic: string` - BIP39 mnemonic phrase (12-24 words)
@@ -230,7 +258,7 @@ await key.unlock('my-password');
 ---
 
 #### `MajikKey.fromMnemonicJSON(mnemonicJson, passphrase, label?)`
-Create a Majik Key from MnemonicJSON format.
+Create a Majik Key from MnemonicJSON format. Auto-migrates legacy PBKDF2 accounts to Argon2id + ML-KEM.
 
 **Parameters:**
 - `mnemonicJson: MnemonicJSON | string` - MnemonicJSON object or string
@@ -253,7 +281,7 @@ const key = await MajikKey.fromMnemonicJSON(mnemonicData, 'my-password');
 ---
 
 #### `MajikKey.importFromMnemonicBackup(backup, mnemonic, passphrase, label?)`
-Import a Majik Key from a mnemonic-encrypted backup.
+Import a Majik Key from a mnemonic-encrypted backup. Auto-migrates legacy PBKDF2 accounts to Argon2id + ML-KEM.
 
 **Parameters:**
 - `backup: string` - Base64-encoded backup string
@@ -310,7 +338,7 @@ const isValid = MajikKey.validateMnemonic('witch collapse practice...');
 ### Instance Methods
 
 #### `unlock(passphrase)`
-Unlock the Majik Key by decrypting the private key.
+Unlock the Majik Key by decrypting the private key. Decrypts X25519 and ML-KEM private keys into memory.
 
 **Parameters:**
 - `passphrase: string` - Passphrase to decrypt the private key
@@ -369,7 +397,7 @@ key.updateLabel('Work Account');
 ---
 
 #### `updatePassphrase(currentPassphrase, newPassphrase)`
-Change the passphrase used to encrypt the private key.
+Change the passphrase used to encrypt the private key. Re-encrypts keys and triggers an auto-migration to KDF v2.
 
 **Parameters:**
 - `currentPassphrase: string` - Current passphrase
@@ -798,23 +826,20 @@ async function createMessageIdentity() {
 
 ### Best Practices
 
-1. **Never expose mnemonics**: Treat mnemonic phrases like passwords. Never log, transmit, or store them unencrypted.
+1. **Never expose mnemonics**: Treat mnemonic phrases like root passwords. Never log or store them unencrypted.
 
-2. **Use strong passphrases**: Choose passphrases with high entropy (mix of letters, numbers, symbols).
+2. **Lock when not in use**: Always call .lock() when private key access is no longer required to purge the heap.
 
-3. **Lock when not in use**: Always lock keys when private key access is not needed.
+3. **PQ Readiness**: For all new communication protocols, ensure you are utilizing the mlKemPublicKey.
 
-4. **Secure storage**: Store JSON exports in secure locations (encrypted databases, secure storage APIs).
+Security Summary
+- **Primary KDF**: Argon2id (128MB / 4t / 4p).
 
-5. **Backup mnemonics**: Store mnemonic phrases in multiple secure locations (password manager, paper backup, hardware wallet).
+- **Legacy KDF**: PBKDF2-SHA256 (250,000 iterations).
 
-### Security Features
+- **Encryption**: AES-256-GCM with unique salts and IVs.
 
-- **PBKDF2 Key Derivation**: 200,000 iterations with SHA-256
-- **AES-GCM Encryption**: Authenticated encryption with random IVs
-- **Per-Identity Salts**: Unique salt for each key prevents rainbow table attacks
-- **No Private Key Exposure**: Private keys never included in JSON exports
-- **Memory Management**: Private keys cleared from memory when locked
+- **Post-Quantum**: ML-KEM-768 (Lattice-based cryptography).
 
 ### What NOT to Do
 

package/dist/core/crypto/constants.d.ts

@@ -4,3 +4,53 @@ export declare const KEY_ALGO: {
 };
 export declare const MAJIK_SALT = "MajikMessageSalt";
 export declare const MAJIK_MNEMONIC_SALT = "MajikMessageMnemonicSalt";
+/**
+ * KDF version identifiers.
+ * Stored alongside every encrypted private key blob so the correct
+ * derivation function is always used on decryption.
+ */
+export declare const KDF_VERSION: {
+    readonly PBKDF2: 1;
+    readonly ARGON2ID: 2;
+};
+export type KDF_VERSION = (typeof KDF_VERSION)[keyof typeof KDF_VERSION];
+/**
+ * Argon2id parameters.
+ *
+ * PASSPHRASE (protecting the private key at rest):
+ *   m=131072 (128 MB) — double OWASP "high security" tier (64 MB)
+ *   t=4               — 4 passes
+ *   p=4               — 4 parallel lanes
+ *
+ * Benchmark targets (approximate):
+ *   Modern laptop (2020+):          ~600–900ms  ✓
+ *   Mid-range desktop (2018):       ~800–1200ms ✓
+ *   Low-end / older machine:        ~1500–2500ms — acceptable for a one-time unlock
+ *   RTX 4090 brute-force attack:    ~1–3 guesses/sec vs ~400,000/sec for PBKDF2
+ *   Improvement over current PBKDF2: ~100,000–400,000×
+ *
+ * MNEMONIC BACKUP (protecting exported backup files):
+ *   m=65536 (64 MB) — lower because the mnemonic itself is 128-bit entropy;
+ *                     the KDF is a domain separator, not a weak-password defense.
+ *   t=3
+ *   p=2
+ *
+ * If benchmarks on your lowest-spec target device exceed 3s for the passphrase
+ * parameters, reduce m to 65536 (64 MB) and t to 3. That is still ~50,000×
+ * harder than the current PBKDF2 setup.
+ */
+export declare const ARGON2_PARAMS: {
+    readonly PASSPHRASE: {
+        readonly m: 131072;
+        readonly t: 4;
+        readonly p: 4;
+        readonly dkLen: 32;
+    };
+    readonly MNEMONIC: {
+        readonly m: 65536;
+        readonly t: 3;
+        readonly p: 2;
+        readonly dkLen: 32;
+    };
+};
+export type ARGON2_PARAMS = (typeof ARGON2_PARAMS)[keyof typeof ARGON2_PARAMS];

package/dist/core/crypto/constants.js

@@ -1,3 +1,51 @@
 export const KEY_ALGO = { name: "ECDH", namedCurve: "X25519" };
 export const MAJIK_SALT = "MajikMessageSalt";
 export const MAJIK_MNEMONIC_SALT = "MajikMessageMnemonicSalt";
+/**
+ * KDF version identifiers.
+ * Stored alongside every encrypted private key blob so the correct
+ * derivation function is always used on decryption.
+ */
+export const KDF_VERSION = {
+    PBKDF2: 1, // legacy — read-only support for existing accounts
+    ARGON2ID: 2, // current — all new accounts and re-encryptions
+};
+/**
+ * Argon2id parameters.
+ *
+ * PASSPHRASE (protecting the private key at rest):
+ *   m=131072 (128 MB) — double OWASP "high security" tier (64 MB)
+ *   t=4               — 4 passes
+ *   p=4               — 4 parallel lanes
+ *
+ * Benchmark targets (approximate):
+ *   Modern laptop (2020+):          ~600–900ms  ✓
+ *   Mid-range desktop (2018):       ~800–1200ms ✓
+ *   Low-end / older machine:        ~1500–2500ms — acceptable for a one-time unlock
+ *   RTX 4090 brute-force attack:    ~1–3 guesses/sec vs ~400,000/sec for PBKDF2
+ *   Improvement over current PBKDF2: ~100,000–400,000×
+ *
+ * MNEMONIC BACKUP (protecting exported backup files):
+ *   m=65536 (64 MB) — lower because the mnemonic itself is 128-bit entropy;
+ *                     the KDF is a domain separator, not a weak-password defense.
+ *   t=3
+ *   p=2
+ *
+ * If benchmarks on your lowest-spec target device exceed 3s for the passphrase
+ * parameters, reduce m to 65536 (64 MB) and t to 3. That is still ~50,000×
+ * harder than the current PBKDF2 setup.
+ */
+export const ARGON2_PARAMS = {
+    PASSPHRASE: {
+        m: 131072, // memory in KB (128 MB)
+        t: 4, // time cost (passes)
+        p: 4, // parallelism (lanes)
+        dkLen: 32, // output length in bytes (256-bit AES key)
+    },
+    MNEMONIC: {
+        m: 65536, // 64 MB
+        t: 3,
+        p: 2,
+        dkLen: 32,
+    },
+};

package/dist/core/crypto/crypto-provider.d.ts

@@ -15,7 +15,104 @@ export declare function deriveEd25519FromSeed(seed32: Uint8Array): {
 export declare function fingerprintFromPublicRaw(rawPublic: Uint8Array): string;
 export declare function aesGcmEncrypt(keyBytes: Uint8Array, iv: Uint8Array, plaintext: Uint8Array): Uint8Array;
 export declare function aesGcmDecrypt(keyBytes: Uint8Array, iv: Uint8Array, ciphertext: Uint8Array): Uint8Array | null;
+/**
+ * Derive a 32-byte AES key from a user passphrase using Argon2id.
+ *
+ * Use this for all NEW account creation and any re-encryption operations.
+ * Works in browser, Node.js, Electron, and Chrome Extension environments.
+ *
+ * @param passphrase - The user's passphrase (plaintext string)
+ * @param salt       - Per-identity random salt (32 bytes recommended)
+ * @returns          - 32-byte key suitable for AES-256-GCM
+ */
+export declare function deriveKeyFromPassphraseArgon2(passphrase: string, salt: Uint8Array): Uint8Array;
+/**
+ * Derive a 32-byte AES key from a BIP-39 mnemonic using Argon2id.
+ *
+ * Used for encrypting and decrypting mnemonic backup exports.
+ * Lower memory parameters than the passphrase KDF because the mnemonic
+ * itself provides 128-bit entropy — brute-force is infeasible regardless.
+ *
+ * @param mnemonic - The 12-word BIP-39 mnemonic (plaintext string)
+ * @param salt     - Domain-separator salt (can be a fixed constant)
+ * @returns        - 32-byte key suitable for AES-256-GCM
+ */
+export declare function deriveKeyFromMnemonicArgon2(mnemonic: string, salt: Uint8Array): Uint8Array;
+/**
+ * @deprecated KDF v1. Kept for reading existing accounts created before the
+ * Argon2id migration. Do NOT use this for new key derivation or re-encryption.
+ * When an existing account's passphrase is changed, it will automatically
+ * be re-encrypted with Argon2id (kdfVersion: 2).
+ */
 export declare function deriveKeyFromPassphrase(passphrase: string, salt: Uint8Array, iterations?: number, keyLen?: number): Uint8Array;
+/**
+ * @deprecated KDF v1. Kept for importing mnemonic backups created before the
+ * Argon2id migration. Do NOT use this for new backup exports.
+ */
 export declare function deriveKeyFromMnemonic(mnemonic: string, salt: Uint8Array, iterations?: number, keyLen?: number): Uint8Array;
 export declare function x25519SharedSecret(privRaw: Uint8Array, pubRaw: Uint8Array): Uint8Array;
 export declare function sha256(input: string): string;
+/**
+ * Derive a deterministic ML-KEM-768 keypair from a BIP-39 mnemonic seed.
+ *
+ * How the seed mapping works (from the noble source):
+ *   ml_kem768.keygen(seed) where seed = 64 bytes
+ *   └── seed.subarray(0, 32) → KPKE key generation (lattice matrix expansion)
+ *   └── seed.subarray(32)    → stored as `z` in secret key (implicit rejection)
+ *
+ * BIP-39 seed mapping:
+ *   mnemonicToSeedSync(mnemonic) → 64 bytes (PBKDF2-SHA512 of mnemonic)
+ *   ├── seed[0..32]  → Ed25519 keypair → X25519 via ed2curve  (existing)
+ *   └── seed[0..64]  → ML-KEM-768 keypair                     (new, uses full 64 bytes)
+ *
+ * IMPORTANT: ML-KEM gets the FULL 64-byte BIP-39 seed, not just the first 32.
+ * This gives ML-KEM its own 64 bits of additional entropy (seed[32..64]) for
+ * the implicit rejection parameter `z`, completely independent of the X25519 key.
+ *
+ * Both keypairs are deterministically derived from the same mnemonic — so
+ * recovering the mnemonic recovers both X25519 and ML-KEM keys automatically.
+ *
+ * @param bip39Seed - Full 64-byte BIP-39 seed from mnemonicToSeedSync()
+ * @returns ML-KEM-768 keypair
+ */
+export declare function deriveMlKemKeypairFromSeed(bip39Seed: Uint8Array): {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+};
+/**
+ * Generate a random ML-KEM-768 keypair.
+ * Use this for testing only — production identities should use
+ * deriveMlKemKeypairFromSeed() for deterministic derivation from mnemonic.
+ */
+export declare function generateMlKemKeypair(): {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+};
+/**
+ * ML-KEM encapsulation: generate a shared secret and ciphertext.
+ *
+ * The post-quantum replacement for X25519 ephemeral key exchange.
+ * The sender calls this with the recipient's ML-KEM public key.
+ * Only the holder of the corresponding ML-KEM secret key can decapsulate.
+ *
+ * @param recipientPublicKey - ML-KEM-768 public key (1184 bytes)
+ * @returns { sharedSecret: 32 bytes, cipherText: 1088 bytes }
+ *
+ * Note: The noble library uses `cipherText` (camelCase T) — not `ciphertext`.
+ */
+export declare function mlKemEncapsulate(recipientPublicKey: Uint8Array): {
+    sharedSecret: Uint8Array;
+    cipherText: Uint8Array;
+};
+/**
+ * ML-KEM decapsulation: recover the shared secret from ciphertext.
+ *
+ * IMPORTANT: ML-KEM decapsulation NEVER throws on wrong key — it returns
+ * a different (useless) shared secret instead. AES-GCM authentication will
+ * catch this: decryption will fail with an auth tag mismatch.
+ *
+ * @param cipherText         - ML-KEM-768 ciphertext (1088 bytes)
+ * @param recipientSecretKey - ML-KEM-768 secret key (2400 bytes)
+ * @returns sharedSecret (32 bytes)
+ */
+export declare function mlKemDecapsulate(cipherText: Uint8Array, recipientSecretKey: Uint8Array): Uint8Array;

package/dist/core/crypto/crypto-provider.js

@@ -6,6 +6,9 @@ import { deriveKey } from "@stablelib/pbkdf2";
 import { hash, SHA256 } from "@stablelib/sha256";
 import * as x25519 from "@stablelib/x25519";
 import { arrayToBase64 } from "../utils";
+import { argon2id } from "@noble/hashes/argon2.js";
+import { ARGON2_PARAMS } from "./constants";
+import { ml_kem768 } from "@noble/post-quantum/ml-kem.js";
 export const IV_LENGTH = 12;
 export function generateRandomBytes(len) {
     const b = new Uint8Array(len);
@@ -48,10 +51,51 @@ export function aesGcmDecrypt(keyBytes, iv, ciphertext) {
     const gcm = new GCM(aes);
     return gcm.open(iv, ciphertext);
 }
+// ─── KDF v2: Argon2id (current) ───────────────────────────────────────────────
+/**
+ * Derive a 32-byte AES key from a user passphrase using Argon2id.
+ *
+ * Use this for all NEW account creation and any re-encryption operations.
+ * Works in browser, Node.js, Electron, and Chrome Extension environments.
+ *
+ * @param passphrase - The user's passphrase (plaintext string)
+ * @param salt       - Per-identity random salt (32 bytes recommended)
+ * @returns          - 32-byte key suitable for AES-256-GCM
+ */
+export function deriveKeyFromPassphraseArgon2(passphrase, salt) {
+    const pw = new TextEncoder().encode(passphrase);
+    return argon2id(pw, salt, ARGON2_PARAMS.PASSPHRASE);
+}
+/**
+ * Derive a 32-byte AES key from a BIP-39 mnemonic using Argon2id.
+ *
+ * Used for encrypting and decrypting mnemonic backup exports.
+ * Lower memory parameters than the passphrase KDF because the mnemonic
+ * itself provides 128-bit entropy — brute-force is infeasible regardless.
+ *
+ * @param mnemonic - The 12-word BIP-39 mnemonic (plaintext string)
+ * @param salt     - Domain-separator salt (can be a fixed constant)
+ * @returns        - 32-byte key suitable for AES-256-GCM
+ */
+export function deriveKeyFromMnemonicArgon2(mnemonic, salt) {
+    const m = new TextEncoder().encode(mnemonic);
+    return argon2id(m, salt, ARGON2_PARAMS.MNEMONIC);
+}
+// ─── KDF v1: PBKDF2-SHA256 (legacy — do not use for new operations) ───────────
+/**
+ * @deprecated KDF v1. Kept for reading existing accounts created before the
+ * Argon2id migration. Do NOT use this for new key derivation or re-encryption.
+ * When an existing account's passphrase is changed, it will automatically
+ * be re-encrypted with Argon2id (kdfVersion: 2).
+ */
 export function deriveKeyFromPassphrase(passphrase, salt, iterations = 250000, keyLen = 32) {
     const pw = new TextEncoder().encode(passphrase);
     return deriveKey(SHA256, pw, salt, iterations, keyLen);
 }
+/**
+ * @deprecated KDF v1. Kept for importing mnemonic backups created before the
+ * Argon2id migration. Do NOT use this for new backup exports.
+ */
 export function deriveKeyFromMnemonic(mnemonic, salt, iterations = 200000, keyLen = 32) {
     const m = new TextEncoder().encode(mnemonic);
     return deriveKey(SHA256, m, salt, iterations, keyLen);
@@ -72,3 +116,71 @@ export function sha256(input) {
     const hashed = hash(new TextEncoder().encode(input));
     return arrayToBase64(hashed);
 }
+// ─── ML-KEM-768: Post-Quantum Key Encapsulation ───────────────────────────────
+/**
+ * Derive a deterministic ML-KEM-768 keypair from a BIP-39 mnemonic seed.
+ *
+ * How the seed mapping works (from the noble source):
+ *   ml_kem768.keygen(seed) where seed = 64 bytes
+ *   └── seed.subarray(0, 32) → KPKE key generation (lattice matrix expansion)
+ *   └── seed.subarray(32)    → stored as `z` in secret key (implicit rejection)
+ *
+ * BIP-39 seed mapping:
+ *   mnemonicToSeedSync(mnemonic) → 64 bytes (PBKDF2-SHA512 of mnemonic)
+ *   ├── seed[0..32]  → Ed25519 keypair → X25519 via ed2curve  (existing)
+ *   └── seed[0..64]  → ML-KEM-768 keypair                     (new, uses full 64 bytes)
+ *
+ * IMPORTANT: ML-KEM gets the FULL 64-byte BIP-39 seed, not just the first 32.
+ * This gives ML-KEM its own 64 bits of additional entropy (seed[32..64]) for
+ * the implicit rejection parameter `z`, completely independent of the X25519 key.
+ *
+ * Both keypairs are deterministically derived from the same mnemonic — so
+ * recovering the mnemonic recovers both X25519 and ML-KEM keys automatically.
+ *
+ * @param bip39Seed - Full 64-byte BIP-39 seed from mnemonicToSeedSync()
+ * @returns ML-KEM-768 keypair
+ */
+export function deriveMlKemKeypairFromSeed(bip39Seed) {
+    if (bip39Seed.length !== 64) {
+        throw new Error(`ML-KEM seed must be 64 bytes (got ${bip39Seed.length}). ` +
+            `Pass the full output of mnemonicToSeedSync(), not a truncated slice.`);
+    }
+    return ml_kem768.keygen(bip39Seed);
+}
+/**
+ * Generate a random ML-KEM-768 keypair.
+ * Use this for testing only — production identities should use
+ * deriveMlKemKeypairFromSeed() for deterministic derivation from mnemonic.
+ */
+export function generateMlKemKeypair() {
+    return ml_kem768.keygen(); // uses crypto.getRandomValues() internally
+}
+/**
+ * ML-KEM encapsulation: generate a shared secret and ciphertext.
+ *
+ * The post-quantum replacement for X25519 ephemeral key exchange.
+ * The sender calls this with the recipient's ML-KEM public key.
+ * Only the holder of the corresponding ML-KEM secret key can decapsulate.
+ *
+ * @param recipientPublicKey - ML-KEM-768 public key (1184 bytes)
+ * @returns { sharedSecret: 32 bytes, cipherText: 1088 bytes }
+ *
+ * Note: The noble library uses `cipherText` (camelCase T) — not `ciphertext`.
+ */
+export function mlKemEncapsulate(recipientPublicKey) {
+    return ml_kem768.encapsulate(recipientPublicKey);
+}
+/**
+ * ML-KEM decapsulation: recover the shared secret from ciphertext.
+ *
+ * IMPORTANT: ML-KEM decapsulation NEVER throws on wrong key — it returns
+ * a different (useless) shared secret instead. AES-GCM authentication will
+ * catch this: decryption will fail with an auth tag mismatch.
+ *
+ * @param cipherText         - ML-KEM-768 ciphertext (1088 bytes)
+ * @param recipientSecretKey - ML-KEM-768 secret key (2400 bytes)
+ * @returns sharedSecret (32 bytes)
+ */
+export function mlKemDecapsulate(cipherText, recipientSecretKey) {
+    return ml_kem768.decapsulate(cipherText, recipientSecretKey);
+}

package/dist/core/crypto/encryption-engine.d.ts

@@ -6,6 +6,8 @@ export interface EncryptionIdentity {
         raw: Uint8Array;
     };
     fingerprint: string;
+    mlKemPublicKey?: Uint8Array;
+    mlKemSecretKey?: Uint8Array;
 }
 /**
  * EncryptionEngine
@@ -14,12 +16,28 @@ export interface EncryptionIdentity {
  */
 export declare class EncryptionEngine {
     /**
-     * Generates a long-term X25519 identity keypair.
+     * Generates a random long-term identity keypair (X25519 only).
+     * ML-KEM keys are not generated here since random identities
+     * cannot be deterministically recovered from a mnemonic.
      */
     static generateIdentity(): Promise<EncryptionIdentity>;
     /**
-     * Derive an identity deterministically from a BIP39 mnemonic.
-     * Uses Stablelib Ed25519 to derive a keypair from seed and converts to X25519.
+     * Derive a complete identity from a BIP-39 mnemonic.
+     *
+     * Seed derivation:
+     *   mnemonicToSeedSync(mnemonic) → 64-byte BIP-39 seed
+     *
+     * X25519 derivation (unchanged from before):
+     *   seed[0..32] → Ed25519 keypair via generateKeyPairFromSeed
+     *              → X25519 via ed2curve conversion
+     *
+     * ML-KEM-768 derivation (new):
+     *   seed[0..64] → ml_kem768.keygen(seed)
+     *              → { publicKey: 1184 bytes, secretKey: 2400 bytes }
+     *
+     * The noble library accepts the full 64-byte BIP-39 seed directly.
+     * Internally it uses seed[0..32] for the lattice key matrix and
+     * seed[32..64] for the implicit rejection parameter `z`.
      */
     static deriveIdentityFromMnemonic(mnemonic: string): Promise<EncryptionIdentity>;
     /**