@majikah/majik-key 0.1.1 → 0.1.2

package/dist/majik-key.js

@@ -1,38 +1,56 @@
+/**
+ * MajikKey.ts
+ *
+ * Seed phrase account library for Majik Message.
+ *
+ * Every account stores TWO keypairs derived deterministically from the mnemonic:
+ *   1. X25519 (Curve25519)   — fingerprint, contact identity, legacy message compat
+ *   2. ML-KEM-768 (FIPS-203) — post-quantum key encapsulation for v3 envelopes
+ *
+ * Both are derived from the 64-byte BIP-39 seed:
+ *   seed[0..32]  → Ed25519 → X25519 via ed2curve
+ *   seed[0..64]  → ml_kem768.keygen(seed) — full seed, deterministic
+ *
+ * KDF versioning (passphrase encryption at rest):
+ *   v1 — PBKDF2-SHA256, 250k iterations   (legacy read-only)
+ *   v2 — Argon2id, 128 MB / 4t / 4p       (all new accounts)
+ *
+ * Migration policy:
+ *   Old accounts (v1, no ML-KEM keys) are fully upgraded on first import
+ *   via importFromMnemonicBackup(). The mnemonic is always available at that
+ *   point, so ML-KEM keys can be deterministically re-derived and stored.
+ *   No partial migration — either fully upgraded or not upgraded yet.
+ */
 import { generateMnemonic } from "@scure/bip39";
-import { aesGcmDecrypt, aesGcmEncrypt, deriveKeyFromMnemonic, deriveKeyFromPassphrase, generateRandomBytes, IV_LENGTH, } from "./core/crypto/crypto-provider";
+import { aesGcmDecrypt, aesGcmEncrypt, deriveKeyFromPassphraseArgon2, deriveKeyFromMnemonicArgon2, deriveKeyFromPassphrase, generateRandomBytes, IV_LENGTH, } from "./core/crypto/crypto-provider";
 import { EncryptionEngine } from "./core/crypto/encryption-engine";
 import { MajikContact } from "./core/majik-contact";
 import { arrayBufferToBase64, arrayToBase64, base64ToArrayBuffer, concatUint8Arrays, utf8ToBase64, base64ToUtf8, seedStringToArray, seedArrayToString, } from "./core/utils";
 import { wordlist } from "@scure/bip39/wordlists/english";
-import { KEY_ALGO, MAJIK_MNEMONIC_SALT, MAJIK_SALT, } from "./core/crypto/constants";
+import { KDF_VERSION, KEY_ALGO, MAJIK_MNEMONIC_SALT, } from "./core/crypto/constants";
 import { MajikKeyValidator } from "./core/validator";
 import { MajikKeyError } from "./core/error";
 import { MajikMessageIdentity } from "./core/database/system/identity";
-/**
- * MajikKey
- * ----------------
- * 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.
- */
+const SALT_SIZE = 32;
+// ─── MajikKey ─────────────────────────────────────────────────────────────────
 export class MajikKey {
-    // Immutable properties
     _id;
     _publicKey;
     _publicKeyBase64;
     _fingerprint;
     _backup;
     _timestamp;
-    // Mutable encrypted state
     _encryptedPrivateKey;
     _encryptedPrivateKeyBase64;
     _salt;
     _label;
-    // Unlocked state (optional - only present when unlocked)
+    _kdfVersion;
+    _mlKemPublicKey;
+    _mlKemSecretKey;
+    _encryptedMlKemSecretKey;
+    _encryptedMlKemSecretKeyBase64;
     _privateKey;
     _privateKeyBase64;
-    /* ================================
-     * Constructor
-     * ================================ */
     constructor(options) {
         this._id = options.id;
         this._publicKey = options.publicKey;
@@ -44,13 +62,15 @@ export class MajikKey {
         this._backup = options.backup;
         this._label = options.label || "";
         this._timestamp = options.timestamp || new Date();
-        // Optional unlocked state
+        this._kdfVersion = options.kdfVersion ?? KDF_VERSION.PBKDF2;
+        this._mlKemPublicKey = options.mlKemPublicKey;
+        this._mlKemSecretKey = options.mlKemSecretKey;
+        this._encryptedMlKemSecretKey = options.encryptedMlKemSecretKey;
+        this._encryptedMlKemSecretKeyBase64 = options.encryptedMlKemSecretKeyBase64;
         this._privateKey = options.privateKey;
         this._privateKeyBase64 = options.privateKeyBase64;
     }
-    /* ================================
-     * Public Getters
-     * ================================ */
+    // ── Getters ─────────────────────────────────────────────────────────────────
     get id() {
         return this._id;
     }
@@ -72,15 +92,30 @@ export class MajikKey {
     get timestamp() {
         return this._timestamp;
     }
+    get kdfVersion() {
+        return this._kdfVersion;
+    }
+    get isArgon2id() {
+        return this._kdfVersion === KDF_VERSION.ARGON2ID;
+    }
     get isLocked() {
         return this._privateKey === undefined;
     }
     get isUnlocked() {
         return this._privateKey !== undefined;
     }
-    /**
-     * Get safe metadata (no sensitive data)
-     */
+    get mlKemPublicKey() {
+        return this._mlKemPublicKey;
+    }
+    get mlKemSecretKey() {
+        return this._mlKemSecretKey;
+    }
+    get hasMlKem() {
+        return this._mlKemPublicKey !== undefined;
+    }
+    get isFullyUpgraded() {
+        return this.isArgon2id && this.hasMlKem;
+    }
     get metadata() {
         return {
             id: this.id,
@@ -88,34 +123,20 @@ export class MajikKey {
             label: this.label,
             timestamp: this.timestamp,
             isLocked: this.isLocked,
+            kdfVersion: this.kdfVersion,
+            hasMlKem: this.hasMlKem,
         };
     }
-    /* ================================
-     * CRUD Operations
-     * ================================ */
-    /**
-     * CREATE: Generate a new MajikKey from a mnemonic phrase.
-     * The key is created in an unlocked state with private keys available.
-     *
-     * @param mnemonic - BIP39 mnemonic phrase (12-24 words)
-     * @param passphrase - Passphrase to encrypt the private key at rest
-     * @param label - Optional label for the key
-     * @returns A new unlocked MajikKey instance
-     */
+    // ── CREATE ──────────────────────────────────────────────────────────────────
     static async create(mnemonic, passphrase, label) {
         try {
-            // Validate inputs
             MajikKeyValidator.validateMnemonic(mnemonic);
             MajikKeyValidator.validatePassphrase(passphrase);
             MajikKeyValidator.validateLabel(label);
-            // Create identity from mnemonic
-            const identity = await this.createIdentityFromMnemonic(mnemonic, passphrase);
-            // Export keys to base64
-            const privateKeyBase64 = await this.exportKeyToBase64(identity.privateKey);
-            const publicKeyBase64 = await this.exportKeyToBase64(identity.publicKey);
-            // Create backup
-            const backup = await this.exportIdentityMnemonicBackup(identity, mnemonic);
-            // Create and return unlocked instance
+            const identity = await MajikKey._deriveAndEncryptFromMnemonic(mnemonic, passphrase);
+            const privateKeyBase64 = await MajikKey._exportKeyToBase64(identity.privateKey);
+            const publicKeyBase64 = await MajikKey._exportKeyToBase64(identity.publicKey);
+            const backup = await MajikKey._exportMnemonicBackup(identity, mnemonic);
             return new MajikKey({
                 id: identity.id,
                 publicKey: identity.publicKey,
@@ -127,7 +148,11 @@ export class MajikKey {
                 backup,
                 label: label || "",
                 timestamp: new Date(),
-                // Unlocked state
+                kdfVersion: KDF_VERSION.ARGON2ID,
+                mlKemPublicKey: identity.mlKemPublicKey,
+                mlKemSecretKey: identity.mlKemSecretKey,
+                encryptedMlKemSecretKey: identity.encryptedMlKemSecretKey,
+                encryptedMlKemSecretKeyBase64: arrayBufferToBase64(identity.encryptedMlKemSecretKey),
                 privateKey: identity.privateKey,
                 privateKeyBase64,
             });
@@ -138,83 +163,24 @@ export class MajikKey {
             throw new MajikKeyError("Failed to create MajikKey", err);
         }
     }
-    /**
-     * Export this MajikKey to MnemonicJSON format.
-     * This format is useful for storing mnemonic data with an optional passphrase.
-     *
-     * @param mnemonic - The BIP39 mnemonic phrase
-     * @param passphrase - Optional passphrase (encryption password, not BIP39 passphrase)
-     * @returns MnemonicJSON object
-     */
-    toMnemonicJSON(mnemonic, passphrase) {
-        if (this.isLocked) {
-            throw new MajikKeyError("Cannot export locked MajikKey to MnemonicJSON. Unlock first.");
-        }
-        try {
-            // Validate mnemonic
-            MajikKeyValidator.validateMnemonic(mnemonic);
-            // Validate passphrase if provided
-            if (passphrase !== undefined) {
-                MajikKeyValidator.validatePassphrase(passphrase, "Passphrase");
-            }
-            return {
-                id: this._backup, // Use backup as identifier
-                seed: seedStringToArray(mnemonic.trim()),
-                phrase: passphrase?.trim() || undefined,
-            };
-        }
-        catch (err) {
-            if (err instanceof MajikKeyError)
-                throw err;
-            throw new MajikKeyError("Failed to create MnemonicJSON", err);
-        }
-    }
-    /**
-     * Create a MajikKey from MnemonicJSON format.
-     *
-     * @param mnemonicJson - MnemonicJSON object or string
-     * @param passphrase - Passphrase to encrypt the key at rest
-     * @param label - Optional label for the key
-     * @returns A new unlocked MajikKey instance
-     */
-    static async fromMnemonicJSON(mnemonicJson, passphrase, label) {
-        try {
-            // Parse if string
-            const parsed = typeof mnemonicJson === "string"
-                ? JSON.parse(mnemonicJson)
-                : mnemonicJson;
-            // Validate structure
-            if (!parsed.id || !parsed.seed || !Array.isArray(parsed.seed)) {
-                throw new MajikKeyError("Invalid MnemonicJSON: missing id or seed array");
-            }
-            // Convert seed array to mnemonic string
-            const mnemonic = seedArrayToString(parsed.seed);
-            // Validate the mnemonic
-            MajikKeyValidator.validateMnemonic(mnemonic);
-            // Create the MajikKey using the standard create method
-            return await this.create(mnemonic, passphrase, label);
-        }
-        catch (err) {
-            if (err instanceof MajikKeyError)
-                throw err;
-            throw new MajikKeyError("Failed to create MajikKey from MnemonicJSON", err);
-        }
-    }
-    /**
-     * READ: Load a MajikKey from JSON (locked state).
-     * The key must be unlocked with the unlock() method before accessing private keys.
-     *
-     * @param json - JSON string or object
-     * @returns A locked MajikKey instance
-     */
+    // ── READ ────────────────────────────────────────────────────────────────────
     static fromJSON(json) {
         try {
             const parsed = typeof json === "string" ? JSON.parse(json) : json;
             const validated = MajikKeyValidator.validateJSON(parsed);
-            // Convert base64 to CryptoKey/ArrayBuffer
+            const anyParsed = parsed;
             const publicKeyBuffer = base64ToArrayBuffer(validated.publicKey);
             const encryptedPrivateKeyBuffer = base64ToArrayBuffer(validated.encryptedPrivateKey);
-            // Create locked instance (no private key)
+            let mlKemPublicKey;
+            if (anyParsed.mlKemPublicKey) {
+                mlKemPublicKey = new Uint8Array(base64ToArrayBuffer(anyParsed.mlKemPublicKey));
+            }
+            let encryptedMlKemSecretKey;
+            let encryptedMlKemSecretKeyBase64;
+            if (anyParsed.encryptedMlKemSecretKey) {
+                encryptedMlKemSecretKeyBase64 = anyParsed.encryptedMlKemSecretKey;
+                encryptedMlKemSecretKey = base64ToArrayBuffer(anyParsed.encryptedMlKemSecretKey);
+            }
             return new MajikKey({
                 id: validated.id,
                 publicKey: { raw: new Uint8Array(publicKeyBuffer) },
@@ -226,7 +192,11 @@ export class MajikKey {
                 backup: validated.backup,
                 label: validated.label || "",
                 timestamp: new Date(validated.timestamp),
-                // No private key - locked state
+                kdfVersion: validated.kdfVersion ??
+                    KDF_VERSION.PBKDF2,
+                mlKemPublicKey,
+                encryptedMlKemSecretKey,
+                encryptedMlKemSecretKeyBase64,
             });
         }
         catch (err) {
@@ -235,45 +205,64 @@ export class MajikKey {
             throw new MajikKeyError("Failed to parse MajikKey from JSON", err);
         }
     }
-    /**
-     * UPDATE: Change the label of this MajikKey.
-     *
-     * @param newLabel - New label value
-     * @returns This instance for chaining
-     */
+    // ── MnemonicJSON ─────────────────────────────────────────────────────────────
+    toMnemonicJSON(mnemonic, passphrase) {
+        if (this.isLocked)
+            throw new MajikKeyError("Cannot export locked MajikKey to MnemonicJSON. Unlock first.");
+        MajikKeyValidator.validateMnemonic(mnemonic);
+        if (passphrase !== undefined)
+            MajikKeyValidator.validatePassphrase(passphrase, "Passphrase");
+        return {
+            id: this._backup,
+            seed: seedStringToArray(mnemonic.trim()),
+            phrase: passphrase?.trim() || undefined,
+        };
+    }
+    static async fromMnemonicJSON(mnemonicJson, passphrase, label) {
+        try {
+            const parsed = typeof mnemonicJson === "string"
+                ? JSON.parse(mnemonicJson)
+                : mnemonicJson;
+            if (!parsed.id || !parsed.seed || !Array.isArray(parsed.seed))
+                throw new MajikKeyError("Invalid MnemonicJSON");
+            const mnemonic = seedArrayToString(parsed.seed);
+            MajikKeyValidator.validateMnemonic(mnemonic);
+            return await MajikKey.create(mnemonic, passphrase, label);
+        }
+        catch (err) {
+            if (err instanceof MajikKeyError)
+                throw err;
+            throw new MajikKeyError("Failed to create MajikKey from MnemonicJSON", err);
+        }
+    }
+    // ── UPDATE ───────────────────────────────────────────────────────────────────
     updateLabel(newLabel) {
         MajikKeyValidator.validateLabel(newLabel);
         this._label = newLabel || "";
         return this;
     }
-    /**
-     * UPDATE: Change the passphrase used to encrypt the private key.
-     * Requires the current passphrase for verification.
-     *
-     * @param currentPassphrase - Current passphrase
-     * @param newPassphrase - New passphrase
-     * @returns This instance for chaining
-     */
     async updatePassphrase(currentPassphrase, newPassphrase) {
         try {
-            // Validate inputs
             MajikKeyValidator.validatePassphrase(currentPassphrase, "Current passphrase");
             MajikKeyValidator.validatePassphrase(newPassphrase, "New passphrase");
-            // Verify current passphrase
-            const isValid = await MajikKey.isPassphraseValid(this.toKeyIdentity(), currentPassphrase);
-            if (!isValid) {
-                throw new MajikKeyError("Current passphrase is incorrect");
-            }
-            // Decrypt with current passphrase
             const salt = new Uint8Array(base64ToArrayBuffer(this._salt));
-            const privateKeyBuffer = await MajikKey.decryptPrivateKey(this._encryptedPrivateKey, currentPassphrase, salt);
-            // Re-encrypt with new passphrase and new salt
-            const newSalt = generateRandomBytes(16);
-            const newEncryptedPrivateKey = await MajikKey.encryptPrivateKey(privateKeyBuffer, newPassphrase, newSalt);
-            // Update encrypted state
+            const privateKeyBuffer = await MajikKey._decryptPrivateKey(this._encryptedPrivateKey, currentPassphrase, salt, this._kdfVersion);
+            let mlKemSecretKeyBytes;
+            if (this._encryptedMlKemSecretKey) {
+                mlKemSecretKeyBytes = await MajikKey._decryptMlKemSecretKey(this._encryptedMlKemSecretKey, currentPassphrase, salt);
+            }
+            const newSalt = generateRandomBytes(SALT_SIZE);
+            const { blob: newEncryptedPrivateKey } = await MajikKey._encryptPrivateKey(privateKeyBuffer, newPassphrase, newSalt);
             this._encryptedPrivateKey = newEncryptedPrivateKey;
             this._encryptedPrivateKeyBase64 = arrayBufferToBase64(newEncryptedPrivateKey);
             this._salt = arrayToBase64(newSalt);
+            this._kdfVersion = KDF_VERSION.ARGON2ID;
+            if (mlKemSecretKeyBytes) {
+                const encMlKem = await MajikKey._encryptMlKemSecretKey(mlKemSecretKeyBytes, newPassphrase, newSalt);
+                this._encryptedMlKemSecretKey = encMlKem;
+                this._encryptedMlKemSecretKeyBase64 = arrayBufferToBase64(encMlKem);
+                this._mlKemSecretKey = mlKemSecretKeyBytes;
+            }
             return this;
         }
         catch (err) {
@@ -283,91 +272,95 @@ export class MajikKey {
         }
     }
     /**
-     * DELETE: Securely lock this MajikKey by clearing private keys from memory.
-     * The encrypted private key remains stored for future unlocking.
-     *
-     * @returns This instance for chaining
+     * Migrate KDF from PBKDF2 to Argon2id without changing passphrase.
+     * NOTE: Does not add ML-KEM keys — use importFromMnemonicBackup() for full upgrade.
      */
+    async migrate(passphrase) {
+        try {
+            MajikKeyValidator.validatePassphrase(passphrase);
+            if (this._kdfVersion === KDF_VERSION.ARGON2ID)
+                return this;
+            const salt = new Uint8Array(base64ToArrayBuffer(this._salt));
+            const privateKeyBuffer = await MajikKey._decryptPrivateKey(this._encryptedPrivateKey, passphrase, salt, KDF_VERSION.PBKDF2);
+            const newSalt = generateRandomBytes(SALT_SIZE);
+            const { blob } = await MajikKey._encryptPrivateKey(privateKeyBuffer, passphrase, newSalt);
+            this._encryptedPrivateKey = blob;
+            this._encryptedPrivateKeyBase64 = arrayBufferToBase64(blob);
+            this._salt = arrayToBase64(newSalt);
+            this._kdfVersion = KDF_VERSION.ARGON2ID;
+            return this;
+        }
+        catch (err) {
+            if (err instanceof MajikKeyError)
+                throw err;
+            throw new MajikKeyError("Failed to migrate MajikKey to Argon2id", err);
+        }
+    }
+    // ── LOCK / UNLOCK ────────────────────────────────────────────────────────────
     lock() {
-        // Clear private key from memory
         this._privateKey = undefined;
         this._privateKeyBase64 = undefined;
+        this._mlKemSecretKey = undefined;
         return this;
     }
-    /* ================================
-     * Unlock/Lock Operations
-     * ================================ */
-    /**
-     * Unlock this MajikKey by decrypting the private key with the passphrase.
-     * Sets the private key in memory for cryptographic operations.
-     *
-     * @param passphrase - Passphrase to decrypt the private key
-     * @returns This instance for chaining
-     * @throws MajikKeyError if passphrase is incorrect or key is already unlocked
-     */
     async unlock(passphrase) {
         try {
-            // Check if already unlocked
-            if (this.isUnlocked) {
+            if (this.isUnlocked)
                 throw new MajikKeyError("MajikKey is already unlocked");
-            }
-            // Validate passphrase
             MajikKeyValidator.validatePassphrase(passphrase);
-            // Decrypt private key
             const salt = new Uint8Array(base64ToArrayBuffer(this._salt));
-            const privateKeyBuffer = await MajikKey.decryptPrivateKey(this._encryptedPrivateKey, passphrase, salt);
-            // Import as CryptoKey
-            const privateKey = await crypto.subtle.importKey("raw", privateKeyBuffer, KEY_ALGO, true, ["sign"]);
-            // Set unlocked state
+            const privateKeyBuffer = await MajikKey._decryptPrivateKey(this._encryptedPrivateKey, passphrase, salt, this._kdfVersion);
+            let privateKey;
+            try {
+                privateKey = await crypto.subtle.importKey("raw", privateKeyBuffer, KEY_ALGO, true, ["sign"]);
+            }
+            catch {
+                privateKey = {
+                    type: "private",
+                    raw: new Uint8Array(privateKeyBuffer),
+                };
+            }
             this._privateKey = privateKey;
             this._privateKeyBase64 = arrayBufferToBase64(privateKeyBuffer);
+            if (this._encryptedMlKemSecretKey) {
+                this._mlKemSecretKey = await MajikKey._decryptMlKemSecretKey(this._encryptedMlKemSecretKey, passphrase, salt);
+            }
             return this;
         }
         catch (err) {
             if (err instanceof MajikKeyError)
                 throw err;
-            throw new MajikKeyError("Failed to unlock MajikKey - incorrect passphrase or corrupted data", err);
+            throw new MajikKeyError("Failed to unlock MajikKey — incorrect passphrase or corrupted data", err);
         }
     }
-    /**
-     * Verify that the encrypted private key can be decrypted with passphrase
-     */
     async verify(passphrase) {
-        return MajikKey.isPassphraseValid(this.toKeyIdentity(), passphrase);
+        try {
+            const salt = new Uint8Array(base64ToArrayBuffer(this._salt));
+            await MajikKey._decryptPrivateKey(this._encryptedPrivateKey, passphrase, salt, this._kdfVersion);
+            return true;
+        }
+        catch {
+            return false;
+        }
     }
-    /**
-     * Get the private key (only available when unlocked).
-     *
-     * @returns The private key
-     * @throws MajikKeyError if the key is locked
-     */
     getPrivateKey() {
-        if (this.isLocked) {
+        if (this.isLocked)
             throw new MajikKeyError("MajikKey is locked. Call unlock() first.");
-        }
         return this._privateKey;
     }
-    /**
-     * Get the private key as base64 (only available when unlocked).
-     *
-     * @returns The private key in base64 format
-     * @throws MajikKeyError if the key is locked
-     */
     getPrivateKeyBase64() {
-        if (this.isLocked) {
+        if (this.isLocked)
             throw new MajikKeyError("MajikKey is locked. Call unlock() first.");
-        }
         return this._privateKeyBase64;
     }
-    /* ================================
-     * Serialization
-     * ================================ */
-    /**
-     * Export this MajikKey to JSON format (safe for storage).
-     * Private keys are never included in the JSON output.
-     *
-     * @returns JSON representation of this MajikKey
-     */
+    getMlKemSecretKey() {
+        if (this.isLocked)
+            throw new MajikKeyError("MajikKey is locked. Call unlock() first.");
+        if (!this._mlKemSecretKey)
+            throw new MajikKeyError("No ML-KEM secret key — re-import via importFromMnemonicBackup() for full migration.");
+        return this._mlKemSecretKey;
+    }
+    // ── SERIALIZATION ────────────────────────────────────────────────────────────
     toJSON() {
         return {
             id: this._id,
@@ -378,38 +371,22 @@ export class MajikKey {
             salt: this._salt,
             backup: this._backup,
             timestamp: this._timestamp.toISOString(),
+            kdfVersion: this._kdfVersion,
+            mlKemPublicKey: this._mlKemPublicKey
+                ? arrayToBase64(this._mlKemPublicKey)
+                : undefined,
+            encryptedMlKemSecretKey: this._encryptedMlKemSecretKeyBase64,
         };
     }
-    /**
-     * Export this MajikKey to a JSON string.
-     *
-     * @param pretty - Whether to pretty-print the JSON
-     * @returns JSON string representation
-     */
     toString(pretty = false) {
         return JSON.stringify(this.toJSON(), null, pretty ? 2 : 0);
     }
-    /* ================================
-     * Utility Methods
-     * ================================ */
-    /**
-     * Generate a new BIP39 mnemonic phrase.
-     *
-     * @param strength - Entropy strength in bits (128 = 12 words, 256 = 24 words)
-     * @returns A new mnemonic phrase
-     */
+    // ── UTILITY ──────────────────────────────────────────────────────────────────
     static generateMnemonic(strength = 128) {
-        if (strength !== 128 && strength !== 256) {
-            throw new MajikKeyError("Strength must be 128 (12 words) or 256 (24 words)");
-        }
+        if (strength !== 128 && strength !== 256)
+            throw new MajikKeyError("Strength must be 128 or 256");
         return generateMnemonic(wordlist, strength);
     }
-    /**
-     * Validate a BIP39 mnemonic phrase.
-     *
-     * @param mnemonic - Mnemonic phrase to validate
-     * @returns true if valid, false otherwise
-     */
     static validateMnemonic(mnemonic) {
         try {
             MajikKeyValidator.validateMnemonic(mnemonic);
@@ -419,11 +396,6 @@ export class MajikKey {
             return false;
         }
     }
-    /**
-     * Create a MajikContact from this MajikKey.
-     *
-     * @returns A MajikContact instance
-     */
     toContact() {
         return new MajikContact({
             id: this._id,
@@ -432,16 +404,9 @@ export class MajikKey {
             meta: { label: this._label },
         });
     }
-    /**
-     * Convert to internal MajikKeyIdentity format (for backward compatibility).
-     * Note: Only includes privateKey if unlocked.
-     *
-     * @returns MajikKeyIdentity object
-     */
     toKeyIdentity() {
-        if (this.isLocked) {
+        if (this.isLocked)
             throw new MajikKeyError("Cannot convert locked MajikKey to KeyIdentity. Unlock first.");
-        }
         return {
             id: this._id,
             publicKey: this._publicKey,
@@ -449,17 +414,14 @@ export class MajikKey {
             privateKey: this._privateKey,
             encryptedPrivateKey: this._encryptedPrivateKey,
             salt: this._salt,
+            kdfVersion: this._kdfVersion,
+            mlKemPublicKey: this._mlKemPublicKey,
+            mlKemSecretKey: this._mlKemSecretKey,
         };
     }
-    /**
-     * Convert to internal SerializedIdentity format (for Majik Message).
-     *
-     * @returns SerializedIdentity object
-     */
     toSerializedIdentity() {
-        if (this.isLocked) {
+        if (this.isLocked)
             throw new MajikKeyError("Cannot convert locked MajikKey to SerializedIdentity. Unlock first.");
-        }
         return {
             id: this._id,
             publicKey: this._publicKeyBase64,
@@ -471,57 +433,37 @@ export class MajikKey {
     async toMajikMessageIdentity(user, options) {
         MajikKeyValidator.assert(user, "MajikUser is required");
         const userValidResult = user.validate();
-        if (!userValidResult.isValid) {
+        if (!userValidResult.isValid)
             throw new Error(`Invalid MajikUser: ${userValidResult.errors.join(", ")}`);
-        }
         const keyContact = await this.toContact().toJSON();
-        const newMajikMessageIdentity = MajikMessageIdentity.create(user, keyContact, options);
-        return newMajikMessageIdentity;
+        return MajikMessageIdentity.create(user, keyContact, options);
     }
-    /* ================================
-     * Static Backup Methods
-     * ================================ */
-    /**
-     * Export a mnemonic-encrypted backup for this MajikKey.
-     * Requires the key to be unlocked.
-     *
-     * @param mnemonic - The original mnemonic phrase
-     * @returns Base64-encoded backup string
-     */
+    // ── BACKUP ───────────────────────────────────────────────────────────────────
     async exportMnemonicBackup(mnemonic) {
-        try {
-            if (this.isLocked) {
-                throw new MajikKeyError("MajikKey must be unlocked to export backup");
-            }
-            MajikKeyValidator.validateMnemonic(mnemonic);
-            const identity = this.toKeyIdentity();
-            return await MajikKey.exportIdentityMnemonicBackup(identity, mnemonic);
-        }
-        catch (err) {
-            if (err instanceof MajikKeyError)
-                throw err;
-            throw new MajikKeyError("Failed to export mnemonic backup", err);
-        }
+        if (this.isLocked)
+            throw new MajikKeyError("MajikKey must be unlocked to export backup");
+        MajikKeyValidator.validateMnemonic(mnemonic);
+        return MajikKey._exportMnemonicBackup(this.toKeyIdentity(), mnemonic);
     }
     /**
      * Import a MajikKey from a mnemonic-encrypted backup.
      *
-     * @param backup - Base64-encoded backup string
-     * @param mnemonic - The mnemonic phrase used to encrypt the backup
-     * @param passphrase - Passphrase to encrypt the imported key
-     * @param label - Optional label for the imported key
-     * @returns A new unlocked MajikKey instance
+     * This is the FULL MIGRATION PATH for old accounts — Argon2id + ML-KEM in one step:
+     *   1. Verify the backup decrypts correctly (proves mnemonic is correct)
+     *   2. Re-derive the complete identity from the mnemonic (X25519 + ML-KEM-768)
+     *   3. Encrypt both private keys with Argon2id (v2) + fresh 32-byte salt
+     *   4. Return a fully-upgraded MajikKey with hasMlKem: true, isArgon2id: true
+     *
+     * Old accounts without ML-KEM keys become fully post-quantum capable
+     * automatically — no extra user steps. The mnemonic is the source of truth.
      */
     static async importFromMnemonicBackup(backup, mnemonic, passphrase, label) {
         try {
-            // Validate inputs
-            if (!backup || typeof backup !== "string") {
+            if (!backup || typeof backup !== "string")
                 throw new MajikKeyError("Backup must be a non-empty string");
-            }
             MajikKeyValidator.validateMnemonic(mnemonic);
             MajikKeyValidator.validatePassphrase(passphrase);
             MajikKeyValidator.validateLabel(label);
-            // Decode backup
             const backupJson = base64ToUtf8(backup);
             const parsed = JSON.parse(backupJson);
             if (!parsed.iv ||
@@ -530,55 +472,33 @@ export class MajikKey {
                 !parsed.fingerprint) {
                 throw new MajikKeyError("Invalid backup format");
             }
-            // Derive key from mnemonic
-            const fullKey = await this.deriveKeyFromMnemonic(mnemonic);
-            const iv = new Uint8Array(base64ToArrayBuffer(parsed.iv));
-            const ciphertext = base64ToArrayBuffer(parsed.ciphertext);
-            const rawPrivate = await crypto.subtle
-                .decrypt({ name: "AES-GCM", iv }, fullKey, ciphertext)
-                .catch((err) => {
-                throw new MajikKeyError("Failed to decrypt backup - invalid mnemonic or corrupted data", err);
-            });
-            let privateKey;
-            try {
-                privateKey = await crypto.subtle.importKey("raw", rawPrivate, KEY_ALGO, true, ["deriveKey", "deriveBits"]);
-            }
-            catch (e) {
-                // WebCrypto does not support X25519 – store raw key
-                privateKey = {
-                    type: "private",
-                    raw: new Uint8Array(rawPrivate),
-                };
-            }
-            let publicKey;
-            const rawPublic = base64ToArrayBuffer(parsed.publicKey);
-            try {
-                publicKey = await crypto.subtle.importKey("raw", rawPublic, KEY_ALGO, true, []);
-            }
-            catch (e) {
-                // WebCrypto may not support X25519; return a raw-key wrapper as fallback
-                const ua = new Uint8Array(rawPublic);
-                const wrapper = { type: "public", raw: ua };
-                publicKey = wrapper;
-            }
-            // Encrypt with new passphrase
-            const newSalt = generateRandomBytes(16);
-            const encryptedPrivateKey = await this.encryptPrivateKey(rawPrivate, passphrase, newSalt);
-            // Create unlocked instance
+            const backupKdfVersion = parsed.backupKdfVersion ??
+                KDF_VERSION.PBKDF2;
+            // Verify mnemonic is correct before doing expensive re-derivation
+            await MajikKey._verifyBackupDecryption(parsed.iv, parsed.ciphertext, mnemonic, backupKdfVersion);
+            // Re-derive complete identity from mnemonic — gets ML-KEM for free
+            const identity = await MajikKey._deriveAndEncryptFromMnemonic(mnemonic, passphrase);
+            const privateKeyBase64 = await MajikKey._exportKeyToBase64(identity.privateKey);
+            const publicKeyBase64 = await MajikKey._exportKeyToBase64(identity.publicKey);
+            const id = parsed.id || identity.id;
             return new MajikKey({
-                id: parsed?.id || parsed.fingerprint,
-                publicKey,
-                publicKeyBase64: parsed.publicKey,
-                fingerprint: parsed.fingerprint,
-                encryptedPrivateKey,
-                encryptedPrivateKeyBase64: arrayBufferToBase64(encryptedPrivateKey),
-                salt: arrayToBase64(newSalt),
+                id,
+                publicKey: identity.publicKey,
+                publicKeyBase64,
+                fingerprint: identity.fingerprint,
+                encryptedPrivateKey: identity.encryptedPrivateKey,
+                encryptedPrivateKeyBase64: arrayBufferToBase64(identity.encryptedPrivateKey),
+                salt: identity.salt,
                 backup,
                 label: label || "",
                 timestamp: new Date(),
-                // Unlocked state
-                privateKey,
-                privateKeyBase64: arrayBufferToBase64(rawPrivate),
+                kdfVersion: KDF_VERSION.ARGON2ID,
+                mlKemPublicKey: identity.mlKemPublicKey,
+                mlKemSecretKey: identity.mlKemSecretKey,
+                encryptedMlKemSecretKey: identity.encryptedMlKemSecretKey,
+                encryptedMlKemSecretKeyBase64: arrayBufferToBase64(identity.encryptedMlKemSecretKey),
+                privateKey: identity.privateKey,
+                privateKeyBase64,
             });
         }
         catch (err) {
@@ -587,177 +507,151 @@ export class MajikKey {
             throw new MajikKeyError("Failed to import from mnemonic backup", err);
         }
     }
-    /* ================================
-     * Private Static Helpers
-     * ================================ */
-    /**
-     * Create a deterministic identity from a mnemonic and encrypt it with passphrase.
-     * The identity `id` is set to the fingerprint for stable referencing.
-     */
-    static async createIdentityFromMnemonic(mnemonic, passphrase) {
+    // ── PRIVATE: Core Derivation ─────────────────────────────────────────────────
+    static async _deriveAndEncryptFromMnemonic(mnemonic, passphrase) {
+        const encIdentity = await EncryptionEngine.deriveIdentityFromMnemonic(mnemonic);
+        let exportedXPrivate;
         try {
-            const identity = await EncryptionEngine.deriveIdentityFromMnemonic(mnemonic);
-            const id = identity.fingerprint; // stable id
-            // Export private key
-            let exportedPrivate;
-            try {
-                exportedPrivate = await crypto.subtle.exportKey("raw", identity.privateKey);
+            exportedXPrivate = await crypto.subtle.exportKey("raw", encIdentity.privateKey);
+        }
+        catch {
+            const anyPriv = encIdentity.privateKey;
+            if (anyPriv?.raw instanceof Uint8Array) {
+                exportedXPrivate = anyPriv.raw.buffer.slice(anyPriv.raw.byteOffset, anyPriv.raw.byteOffset + anyPriv.raw.byteLength);
             }
-            catch (e) {
-                const anyPriv = identity.privateKey;
-                if (anyPriv?.raw instanceof Uint8Array) {
-                    exportedPrivate = anyPriv.raw.buffer.slice(anyPriv.raw.byteOffset, anyPriv.raw.byteOffset + anyPriv.raw.byteLength);
-                }
-                else {
-                    throw e;
-                }
+            else {
+                throw new MajikKeyError("Cannot export private key: unsupported format");
             }
-            // Encrypt private key
-            const salt = generateRandomBytes(16);
-            const encryptedPrivateKey = await this.encryptPrivateKey(exportedPrivate, passphrase, salt);
-            return {
-                id,
-                publicKey: identity.publicKey,
-                fingerprint: identity.fingerprint,
-                encryptedPrivateKey,
-                privateKey: identity.privateKey,
-                salt: arrayToBase64(salt),
-            };
-        }
-        catch (err) {
-            throw new MajikKeyError("Failed to create identity from mnemonic", err);
         }
+        // Single salt — one Argon2id derivation unlocks both keys
+        const salt = generateRandomBytes(SALT_SIZE);
+        const { blob: encryptedPrivateKey } = await MajikKey._encryptPrivateKey(exportedXPrivate, passphrase, salt);
+        const mlKemSecretKey = encIdentity.mlKemSecretKey;
+        const encryptedMlKemSecretKey = await MajikKey._encryptMlKemSecretKey(mlKemSecretKey, passphrase, salt);
+        return {
+            id: encIdentity.fingerprint,
+            publicKey: encIdentity.publicKey,
+            fingerprint: encIdentity.fingerprint,
+            privateKey: encIdentity.privateKey,
+            encryptedPrivateKey,
+            salt: arrayToBase64(salt),
+            kdfVersion: KDF_VERSION.ARGON2ID,
+            mlKemPublicKey: encIdentity.mlKemPublicKey,
+            mlKemSecretKey,
+            encryptedMlKemSecretKey,
+        };
+    }
+    // ── PRIVATE: Encryption/Decryption ───────────────────────────────────────────
+    static async _encryptPrivateKey(buffer, passphrase, salt) {
+        const keyBytes = deriveKeyFromPassphraseArgon2(passphrase, salt);
+        const iv = generateRandomBytes(IV_LENGTH);
+        const ciphertext = aesGcmEncrypt(keyBytes, iv, new Uint8Array(buffer));
+        return {
+            blob: concatUint8Arrays(iv, ciphertext).buffer,
+            kdfVersion: KDF_VERSION.ARGON2ID,
+        };
     }
     /**
-     * Export an identity encrypted with a mnemonic-derived key.
-     * Returns a base64 string containing iv+ciphertext and publicKey/fingerprint in JSON.
+     * Encrypt the ML-KEM secret key using the same Argon2id-derived key as X25519
+     * (same passphrase + same salt) but a DIFFERENT random IV. One Argon2id
+     * computation → two independently encrypted blobs.
      */
-    static async exportIdentityMnemonicBackup(identity, mnemonic) {
-        try {
-            if (!identity?.privateKey) {
-                throw new MajikKeyError("Identity must have privateKey to export backup");
-            }
-            // Export keys
-            let privRawBuf;
-            let pubRawBuf;
+    static async _encryptMlKemSecretKey(mlKemSecretKey, passphrase, salt) {
+        const keyBytes = deriveKeyFromPassphraseArgon2(passphrase, salt);
+        const iv = generateRandomBytes(IV_LENGTH); // different IV from X25519 blob
+        const ciphertext = aesGcmEncrypt(keyBytes, iv, mlKemSecretKey);
+        return concatUint8Arrays(iv, ciphertext).buffer;
+    }
+    static async _decryptPrivateKey(buffer, passphrase, salt, kdfVersion = KDF_VERSION.PBKDF2) {
+        const keyBytes = kdfVersion === KDF_VERSION.ARGON2ID
+            ? deriveKeyFromPassphraseArgon2(passphrase, salt)
+            : deriveKeyFromPassphrase(passphrase, salt);
+        const full = new Uint8Array(buffer);
+        const iv = full.slice(0, IV_LENGTH);
+        const ciphertext = full.slice(IV_LENGTH);
+        const plain = aesGcmDecrypt(keyBytes, iv, ciphertext);
+        if (!plain)
+            throw new MajikKeyError("Decryption failed — incorrect passphrase or corrupted data");
+        return plain.buffer;
+    }
+    static async _decryptMlKemSecretKey(buffer, passphrase, salt) {
+        // ML-KEM keys are only ever written by Argon2id (v2) code
+        const keyBytes = deriveKeyFromPassphraseArgon2(passphrase, salt);
+        const full = new Uint8Array(buffer);
+        const iv = full.slice(0, IV_LENGTH);
+        const ciphertext = full.slice(IV_LENGTH);
+        const plain = aesGcmDecrypt(keyBytes, iv, ciphertext);
+        if (!plain)
+            throw new MajikKeyError("Failed to decrypt ML-KEM secret key");
+        return plain;
+    }
+    // ── PRIVATE: Backup ──────────────────────────────────────────────────────────
+    static async _verifyBackupDecryption(ivBase64, ciphertextBase64, mnemonic, backupKdfVersion) {
+        const iv = new Uint8Array(base64ToArrayBuffer(ivBase64));
+        const ciphertext = base64ToArrayBuffer(ciphertextBase64);
+        const mnemonicSalt = new TextEncoder().encode(MAJIK_MNEMONIC_SALT);
+        if (backupKdfVersion === KDF_VERSION.ARGON2ID) {
+            const keyBytes = deriveKeyFromMnemonicArgon2(mnemonic, mnemonicSalt);
+            const plain = aesGcmDecrypt(keyBytes, iv, new Uint8Array(ciphertext));
+            if (!plain)
+                throw new MajikKeyError("Failed to decrypt backup — invalid mnemonic or corrupted data");
+        }
+        else {
+            const legacyKey = await MajikKey._deriveLegacyMnemonicKey(mnemonic);
             try {
-                privRawBuf = await crypto.subtle.exportKey("raw", identity.privateKey);
-                pubRawBuf = await crypto.subtle.exportKey("raw", identity.publicKey);
+                await crypto.subtle.decrypt({ name: "AES-GCM", iv }, legacyKey, ciphertext);
             }
-            catch (e) {
-                const anyPriv = identity.privateKey;
-                const anyPub = identity.publicKey;
-                if (anyPriv?.raw instanceof Uint8Array) {
-                    privRawBuf = anyPriv.raw.buffer.slice(anyPriv.raw.byteOffset, anyPriv.raw.byteOffset + anyPriv.raw.byteLength);
-                }
-                else {
-                    throw e;
-                }
-                if (anyPub?.raw instanceof Uint8Array) {
-                    pubRawBuf = anyPub.raw.buffer.slice(anyPub.raw.byteOffset, anyPub.raw.byteOffset + anyPub.raw.byteLength);
-                }
-                else {
-                    throw e;
-                }
+            catch {
+                throw new MajikKeyError("Failed to decrypt backup — invalid mnemonic or corrupted data");
             }
-            // Derive AES key from mnemonic
-            const salt = new TextEncoder().encode(MAJIK_MNEMONIC_SALT);
-            const keyBytes = deriveKeyFromMnemonic(mnemonic, salt);
-            const iv = generateRandomBytes(IV_LENGTH);
-            const ciphertext = aesGcmEncrypt(keyBytes, iv, new Uint8Array(privRawBuf));
-            const packaged = {
-                id: identity.id,
-                iv: arrayToBase64(iv),
-                ciphertext: arrayToBase64(ciphertext),
-                publicKey: arrayBufferToBase64(pubRawBuf),
-                fingerprint: identity.fingerprint,
-            };
-            return utf8ToBase64(JSON.stringify(packaged));
-        }
-        catch (err) {
-            throw new MajikKeyError("Failed to export identity mnemonic backup", err);
         }
     }
-    /**
-     * Encrypt a private key with a passphrase.
-     */
-    static async encryptPrivateKey(buffer, passphrase, salt) {
+    static async _exportMnemonicBackup(identity, mnemonic) {
+        if (!identity?.privateKey)
+            throw new MajikKeyError("Identity must have privateKey to export backup");
+        let privRawBuf;
+        let pubRawBuf;
         try {
-            const keyBytes = deriveKeyFromPassphrase(passphrase, salt);
-            const iv = generateRandomBytes(IV_LENGTH);
-            const ciphertext = aesGcmEncrypt(keyBytes, iv, new Uint8Array(buffer));
-            return concatUint8Arrays(iv, ciphertext).buffer;
+            privRawBuf = await crypto.subtle.exportKey("raw", identity.privateKey);
+            pubRawBuf = await crypto.subtle.exportKey("raw", identity.publicKey);
         }
-        catch (err) {
-            throw new MajikKeyError("Failed to encrypt private key", err);
-        }
-    }
-    /**
-     * Decrypt a private key with a passphrase.
-     */
-    static async decryptPrivateKey(buffer, passphrase, salt) {
-        try {
-            const keyBytes = deriveKeyFromPassphrase(passphrase, salt);
-            const full = new Uint8Array(buffer);
-            const iv = full.slice(0, IV_LENGTH);
-            const ciphertext = full.slice(IV_LENGTH);
-            const plain = aesGcmDecrypt(keyBytes, iv, ciphertext);
-            if (!plain) {
-                throw new MajikKeyError("Decryption failed - authentication tag mismatch");
+        catch {
+            const anyPriv = identity.privateKey;
+            const anyPub = identity.publicKey;
+            if (anyPriv?.raw instanceof Uint8Array) {
+                privRawBuf = anyPriv.raw.buffer.slice(anyPriv.raw.byteOffset, anyPriv.raw.byteOffset + anyPriv.raw.byteLength);
             }
-            return plain.buffer;
-        }
-        catch (err) {
-            if (err instanceof MajikKeyError)
-                throw err;
-            throw new MajikKeyError("Failed to decrypt private key", err);
-        }
-    }
-    static async deriveKeyFromMnemonic(mnemonic) {
+            else
+                throw new MajikKeyError("Cannot export private key");
+            if (anyPub?.raw instanceof Uint8Array) {
+                pubRawBuf = anyPub.raw.buffer.slice(anyPub.raw.byteOffset, anyPub.raw.byteOffset + anyPub.raw.byteLength);
+            }
+            else
+                throw new MajikKeyError("Cannot export public key");
+        }
+        const mnemonicSalt = new TextEncoder().encode(MAJIK_MNEMONIC_SALT);
+        const keyBytes = deriveKeyFromMnemonicArgon2(mnemonic, mnemonicSalt);
+        const iv = generateRandomBytes(IV_LENGTH);
+        const ciphertext = aesGcmEncrypt(keyBytes, iv, new Uint8Array(privRawBuf));
+        return utf8ToBase64(JSON.stringify({
+            id: identity.id,
+            iv: arrayToBase64(iv),
+            ciphertext: arrayToBase64(ciphertext),
+            publicKey: arrayBufferToBase64(pubRawBuf),
+            fingerprint: identity.fingerprint,
+            backupKdfVersion: KDF_VERSION.ARGON2ID,
+        }));
+    }
+    static async _deriveLegacyMnemonicKey(mnemonic) {
         const salt = new TextEncoder().encode(MAJIK_MNEMONIC_SALT);
         const keyMaterial = await crypto.subtle.importKey("raw", new TextEncoder().encode(mnemonic), { name: "PBKDF2" }, false, ["deriveKey"]);
-        return crypto.subtle.deriveKey({
-            name: "PBKDF2",
-            salt,
-            iterations: 200_000,
-            hash: "SHA-256",
-        }, keyMaterial, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
-    }
-    /**
-     * Validate whether a passphrase can decrypt the stored private key.
-     * Does NOT unlock or mutate any in-memory state.
-     */
-    static async isPassphraseValid(identity, passphrase) {
-        if (!passphrase)
-            return false;
-        try {
-            if (!identity?.encryptedPrivateKey)
-                return false;
-            const salt = identity.salt
-                ? new Uint8Array(base64ToArrayBuffer(identity.salt))
-                : new TextEncoder().encode(MAJIK_SALT);
-            // Attempt authenticated decryption
-            await this.decryptPrivateKey(identity.encryptedPrivateKey, passphrase, salt);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-    /**
-     * Export a CryptoKey to base64 string.
-     */
-    static async exportKeyToBase64(key) {
-        try {
-            const anyKey = key;
-            if (anyKey && anyKey.raw instanceof Uint8Array) {
-                return arrayBufferToBase64(anyKey.raw.buffer);
-            }
-            const raw = await crypto.subtle.exportKey("raw", key);
-            return arrayBufferToBase64(raw);
-        }
-        catch (err) {
-            throw new MajikKeyError("Failed to export key to base64", err);
-        }
+        return crypto.subtle.deriveKey({ name: "PBKDF2", salt, iterations: 200_000, hash: "SHA-256" }, keyMaterial, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+    }
+    static async _exportKeyToBase64(key) {
+        const anyKey = key;
+        if (anyKey?.raw instanceof Uint8Array)
+            return arrayBufferToBase64(anyKey.raw.buffer);
+        const raw = await crypto.subtle.exportKey("raw", key);
+        return arrayBufferToBase64(raw);
     }
 }