@majikah/majik-key 0.1.1 → 0.1.3

package/dist/core/crypto/encryption-engine.js

@@ -1,22 +1,26 @@
 import { mnemonicToSeedSync } from "@scure/bip39";
 import * as ed25519 from "@stablelib/ed25519";
 import ed2curve from "ed2curve";
-import { fingerprintFromPublicRaw, } from "./crypto-provider";
+import { deriveMlKemKeypairFromSeed, fingerprintFromPublicRaw, } from "./crypto-provider";
 /**
  * EncryptionEngine
  * ----------------
  * Core cryptographic engine.
  */
 export class EncryptionEngine {
+    /* ================================
+     * Identity
+     * ================================ */
     /* ================================
      * Identity
      * ================================ */
     /**
-     * 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 async generateIdentity() {
         try {
-            // Generate an Ed25519 keypair (stablelib) and convert to Curve25519
             const ed = ed25519.generateKeyPair();
             const skCurve = ed2curve.convertSecretKey(ed.secretKey);
             const pkCurve = ed2curve.convertPublicKey(ed.publicKey);
@@ -25,7 +29,6 @@ export class EncryptionEngine {
             }
             const pkBytes = new Uint8Array(pkCurve);
             const skBytes = new Uint8Array(skCurve);
-            // Use raw key wrappers (Stablelib-backed) to avoid WebCrypto import variability
             const publicKey = { type: "public", raw: pkBytes };
             const privateKey = { type: "private", raw: skBytes };
             const fingerprint = fingerprintFromPublicRaw(pkBytes);
@@ -36,32 +39,56 @@ export class EncryptionEngine {
         }
     }
     /**
-     * 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 async deriveIdentityFromMnemonic(mnemonic) {
         try {
             if (typeof mnemonic !== "string" || mnemonic.trim().length === 0) {
                 throw new CryptoError("Mnemonic must be a non-empty string");
             }
-            // Convert mnemonic to seed (64 bytes) then reduce to 32 bytes
-            const seed = mnemonicToSeedSync(mnemonic); // Buffer
-            const seed32 = new Uint8Array(seed.slice(0, 32));
-            // Derive Ed25519 keypair from seed (stablelib)
+            // Step 1: BIP-39 seed → 64 bytes
+            const seed = mnemonicToSeedSync(mnemonic); // returns Buffer (Node) or Uint8Array
+            const seed64 = new Uint8Array(seed); // normalize to Uint8Array
+            // Step 2: X25519 identity from first 32 bytes (existing path)
+            const seed32 = seed64.subarray(0, 32);
             const ed = ed25519.generateKeyPairFromSeed(seed32);
-            // Convert Ed25519 keys to X25519 (curve25519)
             const skCurve = ed2curve.convertSecretKey(ed.secretKey);
             const pkCurve = ed2curve.convertPublicKey(ed.publicKey);
             if (!skCurve || !pkCurve) {
                 throw new CryptoError("Failed to convert derived Ed25519 keys to Curve25519");
             }
-            // Ensure plain Uint8Array
             const pkCurveBytes = new Uint8Array(pkCurve);
             const skCurveBytes = new Uint8Array(skCurve);
             const publicKey = { type: "public", raw: pkCurveBytes };
             const privateKey = { type: "private", raw: skCurveBytes };
             const fingerprint = fingerprintFromPublicRaw(pkCurveBytes);
-            return { publicKey, privateKey, fingerprint };
+            // Step 3: ML-KEM-768 keypair from FULL 64-byte seed (new)
+            // ml_kem768.keygen() accepts a 64-byte seed directly.
+            // seed[0..32] → lattice key matrix expansion (K-PKE keygen)
+            // seed[32..64] → implicit rejection parameter z (stored in secretKey)
+            const mlKemKeypair = deriveMlKemKeypairFromSeed(seed64);
+            return {
+                publicKey,
+                privateKey,
+                fingerprint,
+                mlKemPublicKey: mlKemKeypair.publicKey, // 1184 bytes
+                mlKemSecretKey: mlKemKeypair.secretKey, // 2400 bytes
+            };
         }
         catch (err) {
             throw new CryptoError("Failed to derive identity from mnemonic", err);

package/dist/core/database/system/identity.d.ts

@@ -8,6 +8,7 @@ export interface MajikMessageIdentityJSON {
     label: string;
     timestamp: string;
     restricted: boolean;
+    kdfVersion?: number;
 }
 /**
  * MajikMessageIdentity

package/dist/core/types.d.ts

@@ -11,6 +11,18 @@ export interface MajikKeyJSON {
     salt: string;
     backup: string;
     timestamp: string;
+    kdfVersion?: number;
+    mlKemPublicKey?: string;
+    encryptedMlKemSecretKey?: string;
+}
+export interface MajikKeyMetadata {
+    id: string;
+    fingerprint: string;
+    label: string;
+    timestamp: Date;
+    isLocked: boolean;
+    kdfVersion: number;
+    hasMlKem: boolean;
 }
 export interface MnemonicJSON {
     seed: string[];

package/dist/majik-key.d.ts

@@ -1,5 +1,29 @@
+/**
+ * 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 { MajikContact } from "./core/majik-contact";
-import { MajikKeyJSON, MnemonicJSON } from "./core/types";
+import { KDF_VERSION } from "./core/crypto/constants";
+import type { MajikKeyJSON, MajikKeyMetadata, MnemonicJSON } from "./core/types";
 import { MajikMessageIdentity } from "./core/database/system/identity";
 import { MajikUser } from "@thezelijah/majik-user";
 export interface MajikKeyIdentity {
@@ -13,6 +37,9 @@ export interface MajikKeyIdentity {
     };
     encryptedPrivateKey: ArrayBuffer;
     salt: string;
+    kdfVersion: KDF_VERSION;
+    mlKemPublicKey?: Uint8Array;
+    mlKemSecretKey?: Uint8Array;
 }
 export interface SerializedIdentity {
     id: string;
@@ -34,24 +61,16 @@ export interface MajikKeyConstructorOptions {
     backup: string;
     label?: string;
     timestamp?: Date;
+    kdfVersion?: KDF_VERSION;
+    mlKemPublicKey?: Uint8Array;
+    mlKemSecretKey?: Uint8Array;
+    encryptedMlKemSecretKey?: ArrayBuffer;
+    encryptedMlKemSecretKeyBase64?: string;
     privateKey?: CryptoKey | {
         raw: Uint8Array;
     };
     privateKeyBase64?: string;
 }
-export interface MajikKeyMetadata {
-    id: string;
-    fingerprint: string;
-    label: string;
-    timestamp: Date;
-    isLocked: boolean;
-}
-/**
- * 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.
- */
 export declare class MajikKey {
     private readonly _id;
     private readonly _publicKey;
@@ -63,6 +82,11 @@ export declare class MajikKey {
     private _encryptedPrivateKeyBase64;
     private _salt;
     private _label;
+    private _kdfVersion;
+    private _mlKemPublicKey?;
+    private _mlKemSecretKey?;
+    private _encryptedMlKemSecretKey?;
+    private _encryptedMlKemSecretKeyBase64?;
     private _privateKey?;
     private _privateKeyBase64?;
     private constructor();
@@ -75,195 +99,71 @@ export declare class MajikKey {
     get label(): string;
     get backup(): string;
     get timestamp(): Date;
+    get kdfVersion(): KDF_VERSION;
+    get isArgon2id(): boolean;
     get isLocked(): boolean;
     get isUnlocked(): boolean;
-    /**
-     * Get safe metadata (no sensitive data)
-     */
+    get mlKemPublicKey(): Uint8Array | undefined;
+    get mlKemSecretKey(): Uint8Array | undefined;
+    get hasMlKem(): boolean;
+    get isFullyUpgraded(): boolean;
     get metadata(): MajikKeyMetadata;
-    /**
-     * 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
-     */
     static create(mnemonic: string, passphrase: string, label?: string): Promise<MajikKey>;
-    /**
-     * 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
-     */
+    static fromJSON(json: MajikKeyJSON | string): MajikKey;
     toMnemonicJSON(mnemonic: string, passphrase?: string): MnemonicJSON;
-    /**
-     * 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 fromMnemonicJSON(mnemonicJson: MnemonicJSON | string, passphrase: string, label?: string): Promise<MajikKey>;
-    /**
-     * 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
-     */
-    static fromJSON(json: MajikKeyJSON | string): MajikKey;
-    /**
-     * UPDATE: Change the label of this MajikKey.
-     *
-     * @param newLabel - New label value
-     * @returns This instance for chaining
-     */
     updateLabel(newLabel: string): 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
-     */
     updatePassphrase(currentPassphrase: string, newPassphrase: string): Promise<this>;
     /**
-     * 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.
      */
+    migrate(passphrase: string): Promise<this>;
     lock(): this;
-    /**
-     * 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
-     */
     unlock(passphrase: string): Promise<this>;
-    /**
-     * Verify that the encrypted private key can be decrypted with passphrase
-     */
     verify(passphrase: string): Promise<boolean>;
-    /**
-     * Get the private key (only available when unlocked).
-     *
-     * @returns The private key
-     * @throws MajikKeyError if the key is locked
-     */
     getPrivateKey(): CryptoKey | {
         raw: Uint8Array;
     };
-    /**
-     * 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(): string;
-    /**
-     * 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(): Uint8Array;
     toJSON(): MajikKeyJSON;
-    /**
-     * Export this MajikKey to a JSON string.
-     *
-     * @param pretty - Whether to pretty-print the JSON
-     * @returns JSON string representation
-     */
     toString(pretty?: boolean): string;
-    /**
-     * Generate a new BIP39 mnemonic phrase.
-     *
-     * @param strength - Entropy strength in bits (128 = 12 words, 256 = 24 words)
-     * @returns A new mnemonic phrase
-     */
     static generateMnemonic(strength?: 128 | 256): string;
-    /**
-     * Validate a BIP39 mnemonic phrase.
-     *
-     * @param mnemonic - Mnemonic phrase to validate
-     * @returns true if valid, false otherwise
-     */
     static validateMnemonic(mnemonic: string): boolean;
-    /**
-     * Create a MajikContact from this MajikKey.
-     *
-     * @returns A MajikContact instance
-     */
     toContact(): MajikContact;
-    /**
-     * Convert to internal MajikKeyIdentity format (for backward compatibility).
-     * Note: Only includes privateKey if unlocked.
-     *
-     * @returns MajikKeyIdentity object
-     */
     toKeyIdentity(): MajikKeyIdentity;
-    /**
-     * Convert to internal SerializedIdentity format (for Majik Message).
-     *
-     * @returns SerializedIdentity object
-     */
     toSerializedIdentity(): SerializedIdentity;
     toMajikMessageIdentity(user: MajikUser, options?: {
         label?: string;
         restricted?: boolean;
     }): Promise<MajikMessageIdentity>;
-    /**
-     * 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
-     */
     exportMnemonicBackup(mnemonic: string): Promise<string>;
     /**
      * 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 importFromMnemonicBackup(backup: string, mnemonic: string, passphrase: string, label?: string): Promise<MajikKey>;
-    /**
-     * Create a deterministic identity from a mnemonic and encrypt it with passphrase.
-     * The identity `id` is set to the fingerprint for stable referencing.
-     */
-    private static createIdentityFromMnemonic;
-    /**
-     * Export an identity encrypted with a mnemonic-derived key.
-     * Returns a base64 string containing iv+ciphertext and publicKey/fingerprint in JSON.
-     */
-    private static exportIdentityMnemonicBackup;
-    /**
-     * Encrypt a private key with a passphrase.
-     */
-    private static encryptPrivateKey;
-    /**
-     * Decrypt a private key with a passphrase.
-     */
-    private static decryptPrivateKey;
-    private static deriveKeyFromMnemonic;
-    /**
-     * Validate whether a passphrase can decrypt the stored private key.
-     * Does NOT unlock or mutate any in-memory state.
-     */
-    private static isPassphraseValid;
-    /**
-     * Export a CryptoKey to base64 string.
-     */
-    private static exportKeyToBase64;
+    private static _deriveAndEncryptFromMnemonic;
+    private static _encryptPrivateKey;
+    /**
+     * 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.
+     */
+    private static _encryptMlKemSecretKey;
+    private static _decryptPrivateKey;
+    private static _decryptMlKemSecretKey;
+    private static _verifyBackupDecryption;
+    private static _exportMnemonicBackup;
+    private static _deriveLegacyMnemonicKey;
+    private static _exportKeyToBase64;
 }