@majikah/majik-key 0.2.13 → 0.3.0

package/dist/majik-key.js

@@ -1,25 +1,7 @@
 /**
  * MajikKey.ts
+ * Seed phrase account library for the Majikah ecosystem.
  *
- * 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 as bip39GenerateMnemonic, mnemonicToSeed, validateMnemonic, } from "@scure/bip39";
 import { aesGcmDecrypt, aesGcmEncrypt, deriveKeyFromPassphraseArgon2, deriveKeyFromMnemonicArgon2, deriveKeyFromPassphrase, generateRandomBytes, IV_LENGTH, } from "./core/crypto/crypto-provider";
@@ -33,7 +15,29 @@ import { MajikMessageIdentity } from "./core/database/system/identity";
 import { WORDLISTS } from "./core/crypto/wordlist";
 import { deriveBitcoinKeypairFromSeed, signWithBitcoinMaterial, toBitcoinAddress, toWIF, deriveSolanaKeypairFromEdSecretKey, signWithSolanaMaterial, solanaAddressFromPublicKey, solanaMaterialFromEd25519SecretKey, toSolanaAddress, toSolanaKeyPairSigner, } from "./core/web3";
 const SALT_SIZE = 32;
-// ─── MajikKey ─────────────────────────────────────────────────────────────────
+/**
+ * MajikKey
+ * ---
+ *
+ * Seed phrase account library for the Majikah ecosystem.
+ *
+ * Every account stores FIVE keypairs, all deterministically derived from a
+ * single BIP-39 mnemonic:
+ *   1. X25519 (Curve25519)   — fingerprint, contact identity, legacy message compat
+ *   2. ML-KEM-768 (FIPS-203) — post-quantum key encapsulation for v3 envelopes
+ *   3. Ed25519               — classical signing
+ *   4. ML-DSA-87 (FIPS-204)  — post-quantum signing
+ *   5. Bitcoin (secp256k1)   — BIP-32/84 HD key, domain-separated by default (experimental)
+ *
+ * All derived from the 64-byte BIP-39 seed:
+ *   seed[0..32]  → Ed25519 keypair — used directly for signing, AND converted
+ *                  to X25519 via ed2curve for the encryption/identity keypair
+ *                  (one Ed25519 keypair, two roles)
+ *   seed[0..64]  → ml_kem768.keygen(seed) — full seed, deterministic
+ *   hash(seed || "MajikSignatureSeedDSA") → 32-byte seed → ml_dsa87.keygen()
+ *   seed[0..64]  → HDKey.fromMasterSeed(seed).derive(path) — BIP-32/84 Bitcoin key
+ *
+ */
 export class MajikKey {
     _id;
     _publicKey;
@@ -61,11 +65,25 @@ export class MajikKey {
     _mlDsaSecretKey;
     _encryptedMlDsaSecretKey;
     _encryptedMlDsaSecretKeyBase64;
-    //Experimental
+    /**
+     * @experimental
+     */
     _solanaKeypairMaterial;
+    /**
+     * @experimental
+     */
     _btcPublicKey;
+    /**
+     * @experimental
+     */
     _btcSecretKey;
+    /**
+     * @experimental
+     */
     _encryptedBtcSecretKey;
+    /**
+     * @experimental
+     */
     _encryptedBtcSecretKeyBase64;
     constructor(options) {
         this._id = options.id;
@@ -100,60 +118,92 @@ export class MajikKey {
         this._mnemonicLanguage = options.mnemonicLanguage || "en";
     }
     // ── Getters ─────────────────────────────────────────────────────────────────
+    /** Account identifier. Equal to `fingerprint` for accounts created by this library. */
     get id() {
         return this._id;
     }
+    /** SHA-256 fingerprint of the X25519 public key. Stable identity anchor for the account. */
     get fingerprint() {
         return this._fingerprint;
     }
+    /** X25519 public key — native `CryptoKey` where WebCrypto supports it, otherwise a raw-bytes wrapper. Always available, even when locked. */
     get publicKey() {
         return this._publicKey;
     }
+    /** X25519 public key, base64-encoded. Always available, even when locked. */
     get publicKeyBase64() {
         return this._publicKeyBase64;
     }
+    /** Human-readable, user-editable account name. Update via `updateLabel()`. */
     get label() {
         return this._label;
     }
+    /** BIP-39 wordlist language this account's mnemonic was generated/validated against. */
     get mnemonicLanguage() {
         return this._mnemonicLanguage;
     }
+    /**
+     * Encrypted mnemonic-verification blob (base64 JSON). Decryptable only
+     * with the original mnemonic — used internally to verify a supplied
+     * mnemonic before `importFromMnemonicBackup()` re-derives the full
+     * identity. Not a general-purpose private-key backup.
+     */
     get backup() {
         return this._backup;
     }
+    /** Account creation time. */
     get timestamp() {
         return this._timestamp;
     }
+    /** KDF currently protecting every `encrypted*` field on this account: `1` = legacy PBKDF2, `2` = Argon2id. */
     get kdfVersion() {
         return this._kdfVersion;
     }
+    /** `true` if this account is on the current KDF (Argon2id). `false` means it's still on legacy PBKDF2 — see `migrate()` or `importFromMnemonicBackup()`. */
     get isArgon2id() {
         return this._kdfVersion === KDF_VERSION.ARGON2ID;
     }
+    /** `true` if private key material is currently purged from memory (i.e. `lock()` was called, or `unlock()` hasn't been called yet). */
     get isLocked() {
         return this._privateKey === undefined;
     }
+    /** `true` if private key material is currently decrypted in memory. The inverse of `isLocked`. */
     get isUnlocked() {
         return this._privateKey !== undefined;
     }
+    /** ML-KEM-768 (FIPS-203) public key. Post-quantum key encapsulation. Always available, even when locked. */
     get mlKemPublicKey() {
         return this._mlKemPublicKey;
     }
+    /** ML-KEM-768 secret key. `undefined` unless the account is unlocked. ⚠️ Live key material — prefer `getMlKemSecretKey()` if you want a thrown error instead of `undefined` on locked accounts. */
     get mlKemSecretKey() {
         return this._mlKemSecretKey;
     }
+    /** `true` if this account has ML-KEM-768 keys (i.e. is post-quantum-encryption capable). `false` means it's a legacy account pending migration. */
     get hasMlKem() {
         return this._mlKemPublicKey !== undefined;
     }
+    /** `true` if this account is on Argon2id *and* has ML-KEM-768 keys — i.e. fully migrated, nothing left to upgrade. */
     get isFullyUpgraded() {
         return this.isArgon2id && this.hasMlKem;
     }
+    /**
+     * @experimental secp256k1 Bitcoin public key. `undefined` if this account
+     * has no stored Bitcoin key material (e.g. it predates Web3 support and
+     * hasn't been re-imported via `importFromMnemonicBackup()`).
+     */
     get btcPublicKey() {
         return this._btcPublicKey;
     }
+    /** @experimental `true` if this account has a stored Bitcoin keypair. */
     get hasBitcoin() {
         return this._btcPublicKey !== undefined;
     }
+    /**
+     * Lightweight, non-secret snapshot of this account's state — no key bytes
+     * at all, encrypted or otherwise. Useful for account pickers, dashboards,
+     * or anywhere you want to display status without touching key material.
+     */
     get metadata() {
         return {
             id: this.id,
@@ -170,26 +220,50 @@ export class MajikKey {
             mnemonicLanguage: this.mnemonicLanguage || "en",
         };
     }
+    /** Ed25519 public key. Classical signing — same keypair the X25519 identity key is converted from. Always available, even when locked. */
     get edPublicKey() {
         return this._edPublicKey;
     }
+    /** ML-DSA-87 (FIPS-204) public key. Post-quantum signing. Always available, even when locked. */
     get mlDsaPublicKey() {
         return this._mlDsaPublicKey;
     }
+    /** `true` if this account has both Ed25519 and ML-DSA-87 signing keys. `false` means it's a legacy account pending migration. */
     get hasSigningKeys() {
         return (this._edPublicKey !== undefined && this._mlDsaPublicKey !== undefined);
     }
     // ── CREATE ──────────────────────────────────────────────────────────────────
-    static async create(mnemonic, passphrase, label, mnemonicLanguage = "en") {
+    /**
+     * Creates a brand-new MajikKey account from a BIP-39 mnemonic.
+     *
+     * Derives the full key set in one pass — X25519, ML-KEM-768, Ed25519,
+     * ML-DSA-87, and a domain-separated Bitcoin key (see `MAJIK_BITCOIN_DOMAIN_PATH`)
+     * — encrypts every private key with Argon2id (KDF v2), and returns an
+     * **already-unlocked** instance (no `unlock()` call needed right after
+     * `create()`).
+     *
+     * @param mnemonic - A valid BIP-39 mnemonic phrase (12 or 24 words), matching `mnemonicLanguage`. Generate one with `MajikKey.generateMnemonic()`.
+     * @param passphrase - Passphrase used to derive the Argon2id encryption key for every private key on this account. This is *not* the mnemonic — losing it without the mnemonic makes the account unrecoverable.
+     * @param label - Optional human-readable account name. Defaults to an empty string. Update later via `updateLabel()`.
+     * @param mnemonicLanguage - BIP-39 wordlist to validate `mnemonic` against. Defaults to `"en"`.
+     * @param options.deriveBitcoin - @experimental Set `false` to skip deriving the Bitcoin keypair. Defaults to `true`.
+     * @returns An unlocked `MajikKey` instance, ready for immediate use — call `.lock()` when you're done with it.
+     * @throws {MajikKeyError} If `mnemonic` fails validation, `passphrase`/`label` fail their validators, or `mnemonic` doesn't match `mnemonicLanguage`'s wordlist.
+     */
+    static async create(mnemonic, passphrase, label, options = {
+        deriveBitcoin: true,
+        mnemonicLanguage: "en",
+    }) {
         try {
             MajikKeyValidator.validateMnemonic(mnemonic);
             MajikKeyValidator.validatePassphrase(passphrase);
             MajikKeyValidator.validateLabel(label);
-            const wordlist = await MajikKey._getWordlist(mnemonicLanguage);
+            const { deriveBitcoin, mnemonicLanguage } = options;
+            const wordlist = await MajikKey._getWordlist(mnemonicLanguage || "en");
             if (!validateMnemonic(mnemonic, wordlist)) {
                 throw new MajikKeyError("Invalid BIP39 mnemonic phrase");
             }
-            const identity = await MajikKey._deriveAndEncryptFromMnemonic(mnemonic, passphrase);
+            const identity = await MajikKey._deriveAndEncryptFromMnemonic(mnemonic, passphrase, { deriveBitcoin: deriveBitcoin });
             const privateKeyBase64 = await MajikKey._exportKeyToBase64(identity.privateKey);
             const publicKeyBase64 = await MajikKey._exportKeyToBase64(identity.publicKey);
             const backup = await MajikKey._exportMnemonicBackup(identity, mnemonic);
@@ -221,7 +295,9 @@ export class MajikKey {
                 mlDsaSecretKey: identity.mlDsaSecretKey,
                 btcPublicKey: identity.btcPublicKey,
                 encryptedBtcSecretKey: identity.encryptedBtcSecretKey,
-                encryptedBtcSecretKeyBase64: arrayBufferToBase64(identity.encryptedBtcSecretKey),
+                encryptedBtcSecretKeyBase64: identity.encryptedBtcSecretKey
+                    ? arrayBufferToBase64(identity.encryptedBtcSecretKey)
+                    : undefined,
                 btcSecretKey: identity.btcSecretKey,
                 mnemonicLanguage: mnemonicLanguage,
             });
@@ -720,23 +796,19 @@ export class MajikKey {
     /**
      * Import a MajikKey from a mnemonic-encrypted backup.
      *
-     * 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, mnemonicLanguage = "en") {
+    static async importFromMnemonicBackup(backup, mnemonic, passphrase, label, options = {
+        deriveBitcoin: true,
+        mnemonicLanguage: "en",
+    }) {
         try {
             if (!backup || typeof backup !== "string")
                 throw new MajikKeyError("Backup must be a non-empty string");
             MajikKeyValidator.validateMnemonic(mnemonic);
             MajikKeyValidator.validatePassphrase(passphrase);
             MajikKeyValidator.validateLabel(label);
-            const wordlist = await MajikKey._getWordlist(mnemonicLanguage);
+            const { deriveBitcoin, mnemonicLanguage } = options;
+            const wordlist = await MajikKey._getWordlist(mnemonicLanguage || "en");
             if (!validateMnemonic(mnemonic, wordlist)) {
                 throw new MajikKeyError("Invalid BIP39 mnemonic phrase");
             }
@@ -753,7 +825,7 @@ export class MajikKey {
             // 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 identity = await MajikKey._deriveAndEncryptFromMnemonic(mnemonic, passphrase, { deriveBitcoin: deriveBitcoin });
             const privateKeyBase64 = await MajikKey._exportKeyToBase64(identity.privateKey);
             const publicKeyBase64 = await MajikKey._exportKeyToBase64(identity.publicKey);
             const id = parsed.id || identity.id;
@@ -785,7 +857,9 @@ export class MajikKey {
                 mlDsaSecretKey: identity.mlDsaSecretKey,
                 btcPublicKey: identity.btcPublicKey,
                 encryptedBtcSecretKey: identity.encryptedBtcSecretKey,
-                encryptedBtcSecretKeyBase64: arrayBufferToBase64(identity.encryptedBtcSecretKey),
+                encryptedBtcSecretKeyBase64: identity.encryptedBtcSecretKey
+                    ? arrayBufferToBase64(identity.encryptedBtcSecretKey)
+                    : undefined,
                 btcSecretKey: identity.btcSecretKey,
             });
         }
@@ -801,7 +875,13 @@ export class MajikKey {
         const mod = await loader();
         return mod.wordlist;
     }
-    static async _deriveAndEncryptFromMnemonic(mnemonic, passphrase) {
+    /**
+     * @param mnemonic - BIP-39 mnemonic to derive the full key set from.
+     * @param passphrase - Passphrase used to derive the Argon2id encryption key shared by every private key produced here.
+     * @param options.deriveBitcoin - @experimental Set `false` to skip deriving the Bitcoin keypair. Defaults to `true`.
+     */
+    static async _deriveAndEncryptFromMnemonic(mnemonic, passphrase, options) {
+        const deriveBitcoin = options?.deriveBitcoin ?? true;
         const encIdentity = await EncryptionEngine.deriveIdentityFromMnemonic(mnemonic);
         let exportedXPrivate;
         try {
@@ -816,22 +896,30 @@ export class MajikKey {
                 throw new MajikKeyError("Cannot export private key: unsupported format");
             }
         }
-        // Single salt — one Argon2id derivation unlocks both keys
+        // Single salt — one Argon2id derivation unlocks every key below
         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);
-        // after the existing ML-KEM encryption block:
         const edSecretKey = encIdentity.edSecretKey;
         const encryptedEdSecretKey = await MajikKey._encryptSigningKey(edSecretKey, passphrase, salt);
         const mlDsaSecretKey = encIdentity.mlDsaSecretKey;
         const encryptedMlDsaSecretKey = await MajikKey._encryptSigningKey(mlDsaSecretKey, passphrase, salt);
-        // Bitcoin — real BIP-32/BIP-84 off the raw 64-byte BIP-39 seed, using
-        // Majik's domain-separated path by default. Same salt, different IV,
-        // same pattern as ML-KEM/Ed25519/ML-DSA above.
-        const rawSeed = await mnemonicToSeed(mnemonic);
-        const btcMaterial = deriveBitcoinKeypairFromSeed(rawSeed);
-        const encryptedBtcSecretKey = await MajikKey._encryptSigningKey(btcMaterial.privateKey, passphrase, salt);
+        // @experimental Bitcoin — real BIP-32/BIP-84 off the raw 64-byte BIP-39
+        // seed, using Majik's domain-separated path by default. Same salt,
+        // different IV, same pattern as ML-KEM/Ed25519/ML-DSA above. Skipped
+        // entirely when `deriveBitcoin` is false — no derivation cost paid,
+        // no key material generated.
+        let btcPublicKey;
+        let btcSecretKey;
+        let encryptedBtcSecretKey;
+        if (deriveBitcoin) {
+            const rawSeed = await mnemonicToSeed(mnemonic);
+            const btcMaterial = deriveBitcoinKeypairFromSeed(rawSeed);
+            btcPublicKey = btcMaterial.publicKey;
+            btcSecretKey = btcMaterial.privateKey;
+            encryptedBtcSecretKey = await MajikKey._encryptSigningKey(btcMaterial.privateKey, passphrase, salt);
+        }
         return {
             id: encIdentity.fingerprint,
             publicKey: encIdentity.publicKey,
@@ -849,8 +937,8 @@ export class MajikKey {
             mlDsaPublicKey: encIdentity.mlDsaPublicKey,
             mlDsaSecretKey,
             encryptedMlDsaSecretKey,
-            btcPublicKey: btcMaterial.publicKey,
-            btcSecretKey: btcMaterial.privateKey,
+            btcPublicKey,
+            btcSecretKey,
             encryptedBtcSecretKey,
         };
     }
@@ -984,6 +1072,9 @@ export class MajikKey {
         return arrayBufferToBase64(raw);
     }
     // ── WEB3 (EXPERIMENTAL) ─────────────────────────────────────────────────────
+    /**
+     * @experimental
+     */
     getBtcSecretKey() {
         if (this.isLocked)
             throw new MajikKeyError("MajikKey is locked. Call unlock() first.");
@@ -992,6 +1083,9 @@ export class MajikKey {
         return this._btcSecretKey;
     }
     // ── WEB3 (EXPERIMENTAL) — updated getter ────────────────────────────────────
+    /**
+     * @experimental
+     */
     get web3() {
         if (!this.hasSolanaKeypair)
             return undefined;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@majikah/majik-key",
   "type": "module",
   "description": "A post-quantum ready seed phrase account library for the Majikah ecosystem. Manages deterministic X25519 and ML-KEM-768 identities with Argon2id protection and seamless legacy account migration.",
-  "version": "0.2.13",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",