@majikah/majik-key 0.2.12 → 0.2.13

package/dist/majik-key.js

@@ -21,7 +21,7 @@
  *   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, validateMnemonic, } from "@scure/bip39";
+import { generateMnemonic as bip39GenerateMnemonic, mnemonicToSeed, validateMnemonic, } from "@scure/bip39";
 import { aesGcmDecrypt, aesGcmEncrypt, deriveKeyFromPassphraseArgon2, deriveKeyFromMnemonicArgon2, deriveKeyFromPassphrase, generateRandomBytes, IV_LENGTH, } from "./core/crypto/crypto-provider";
 import { EncryptionEngine } from "./core/crypto/encryption-engine";
 import { MajikContact } from "@majikah/majik-contact";
@@ -31,7 +31,7 @@ import { MajikKeyValidator } from "./core/validator";
 import { MajikKeyError } from "./core/error";
 import { MajikMessageIdentity } from "./core/database/system/identity";
 import { WORDLISTS } from "./core/crypto/wordlist";
-import { deriveSolanaKeypairFromEdSecretKey, signWithSolanaMaterial, solanaAddressFromPublicKey, solanaMaterialFromEd25519SecretKey, toSolanaAddress, toSolanaKeyPairSigner, } from "./core/web3/solana";
+import { deriveBitcoinKeypairFromSeed, signWithBitcoinMaterial, toBitcoinAddress, toWIF, deriveSolanaKeypairFromEdSecretKey, signWithSolanaMaterial, solanaAddressFromPublicKey, solanaMaterialFromEd25519SecretKey, toSolanaAddress, toSolanaKeyPairSigner, } from "./core/web3";
 const SALT_SIZE = 32;
 // ─── MajikKey ─────────────────────────────────────────────────────────────────
 export class MajikKey {
@@ -63,6 +63,10 @@ export class MajikKey {
     _encryptedMlDsaSecretKeyBase64;
     //Experimental
     _solanaKeypairMaterial;
+    _btcPublicKey;
+    _btcSecretKey;
+    _encryptedBtcSecretKey;
+    _encryptedBtcSecretKeyBase64;
     constructor(options) {
         this._id = options.id;
         this._publicKey = options.publicKey;
@@ -89,6 +93,10 @@ export class MajikKey {
         this._encryptedMlDsaSecretKeyBase64 = options.encryptedMlDsaSecretKeyBase64;
         this._edSecretKey = options.edSecretKey;
         this._mlDsaSecretKey = options.mlDsaSecretKey;
+        this._btcPublicKey = options.btcPublicKey;
+        this._btcSecretKey = options.btcSecretKey;
+        this._encryptedBtcSecretKey = options.encryptedBtcSecretKey;
+        this._encryptedBtcSecretKeyBase64 = options.encryptedBtcSecretKeyBase64;
         this._mnemonicLanguage = options.mnemonicLanguage || "en";
     }
     // ── Getters ─────────────────────────────────────────────────────────────────
@@ -140,6 +148,12 @@ export class MajikKey {
     get isFullyUpgraded() {
         return this.isArgon2id && this.hasMlKem;
     }
+    get btcPublicKey() {
+        return this._btcPublicKey;
+    }
+    get hasBitcoin() {
+        return this._btcPublicKey !== undefined;
+    }
     get metadata() {
         return {
             id: this.id,
@@ -149,6 +163,10 @@ export class MajikKey {
             isLocked: this.isLocked,
             kdfVersion: this.kdfVersion,
             hasMlKem: this.hasMlKem,
+            web3: {
+                hasBitcoin: this.hasBitcoin,
+                hasSolana: this.hasSolanaKeypair,
+            },
             mnemonicLanguage: this.mnemonicLanguage || "en",
         };
     }
@@ -201,6 +219,10 @@ export class MajikKey {
                 encryptedMlDsaSecretKeyBase64: arrayBufferToBase64(identity.encryptedMlDsaSecretKey),
                 edSecretKey: identity.edSecretKey,
                 mlDsaSecretKey: identity.mlDsaSecretKey,
+                btcPublicKey: identity.btcPublicKey,
+                encryptedBtcSecretKey: identity.encryptedBtcSecretKey,
+                encryptedBtcSecretKeyBase64: arrayBufferToBase64(identity.encryptedBtcSecretKey),
+                btcSecretKey: identity.btcSecretKey,
                 mnemonicLanguage: mnemonicLanguage,
             });
         }
@@ -243,6 +265,15 @@ export class MajikKey {
                 encryptedMlDsaSecretKeyBase64 = anyParsed.encryptedMlDsaSecretKey;
                 encryptedMlDsaSecretKey = base64ToArrayBuffer(anyParsed.encryptedMlDsaSecretKey);
             }
+            const btcPublicKey = anyParsed.btcPublicKey
+                ? base64ToUint8Array(anyParsed.btcPublicKey)
+                : undefined;
+            let encryptedBtcSecretKey;
+            let encryptedBtcSecretKeyBase64;
+            if (anyParsed.encryptedBtcSecretKey) {
+                encryptedBtcSecretKeyBase64 = anyParsed.encryptedBtcSecretKey;
+                encryptedBtcSecretKey = base64ToArrayBuffer(anyParsed.encryptedBtcSecretKey);
+            }
             return new MajikKey({
                 id: validated.id,
                 publicKey: { raw: new Uint8Array(publicKeyBuffer) },
@@ -265,6 +296,9 @@ export class MajikKey {
                 mlDsaPublicKey,
                 encryptedMlDsaSecretKey,
                 encryptedMlDsaSecretKeyBase64,
+                btcPublicKey,
+                encryptedBtcSecretKey,
+                encryptedBtcSecretKeyBase64,
                 mnemonicLanguage: validated?.mnemonicLanguage || "en",
             });
         }
@@ -294,6 +328,9 @@ export class MajikKey {
             mlKemSecretKeyBase64: arrayToBase64(this._mlKemSecretKey),
             edSecretKeyBase64: arrayToBase64(this._edSecretKey),
             mlDsaSecretKeyBase64: arrayToBase64(this._mlDsaSecretKey),
+            btcSecretKeyBase64: this._btcSecretKey
+                ? arrayToBase64(this._btcSecretKey)
+                : undefined,
         };
     }
     /**
@@ -323,6 +360,12 @@ export class MajikKey {
             const mlDsaSecretKey = base64ToUint8Array(parsed.mlDsaSecretKeyBase64);
             const mlKemPublicKey = base64ToUint8Array(parsed.mlKemPublicKey);
             const mlKemSecretKey = base64ToUint8Array(parsed.mlKemSecretKeyBase64);
+            const btcPublicKey = parsed.btcPublicKey
+                ? base64ToUint8Array(parsed.btcPublicKey)
+                : undefined;
+            const btcSecretKey = parsed.btcSecretKeyBase64
+                ? base64ToUint8Array(parsed.btcSecretKeyBase64)
+                : undefined;
             return new MajikKey({
                 id: parsed.id,
                 fingerprint: parsed.fingerprint,
@@ -341,6 +384,8 @@ export class MajikKey {
                 edSecretKey,
                 mlDsaPublicKey,
                 mlDsaSecretKey,
+                btcPublicKey,
+                btcSecretKey,
             });
         }
         catch (err) {
@@ -421,6 +466,13 @@ export class MajikKey {
                 this._encryptedMlDsaSecretKeyBase64 = arrayBufferToBase64(encDsa);
                 this._mlDsaSecretKey = mlDsaSecretKeyBytes;
             }
+            if (this._encryptedBtcSecretKey) {
+                const btcSecretKeyBytes = await MajikKey._decryptSigningKey(this._encryptedBtcSecretKey, currentPassphrase, salt);
+                const encBtc = await MajikKey._encryptSigningKey(btcSecretKeyBytes, newPassphrase, newSalt);
+                this._encryptedBtcSecretKey = encBtc;
+                this._encryptedBtcSecretKeyBase64 = arrayBufferToBase64(encBtc);
+                this._btcSecretKey = btcSecretKeyBytes;
+            }
             return this;
         }
         catch (err) {
@@ -462,6 +514,7 @@ export class MajikKey {
         this._mlKemSecretKey = undefined;
         this._edSecretKey = undefined;
         this._mlDsaSecretKey = undefined;
+        this._btcSecretKey = undefined;
         this._solanaKeypairMaterial = undefined;
         return this;
     }
@@ -493,6 +546,9 @@ export class MajikKey {
             if (this._encryptedMlDsaSecretKey) {
                 this._mlDsaSecretKey = await MajikKey._decryptSigningKey(this._encryptedMlDsaSecretKey, passphrase, salt);
             }
+            if (this._encryptedBtcSecretKey) {
+                this._btcSecretKey = await MajikKey._decryptSigningKey(this._encryptedBtcSecretKey, passphrase, salt);
+            }
             return this;
         }
         catch (err) {
@@ -566,6 +622,10 @@ export class MajikKey {
                 ? arrayToBase64(this._mlDsaPublicKey)
                 : undefined,
             encryptedMlDsaSecretKey: this._encryptedMlDsaSecretKeyBase64,
+            btcPublicKey: this._btcPublicKey
+                ? arrayToBase64(this._btcPublicKey)
+                : undefined,
+            encryptedBtcSecretKey: this._encryptedBtcSecretKeyBase64,
             mnemonicLanguage: this._mnemonicLanguage,
         };
     }
@@ -723,6 +783,10 @@ export class MajikKey {
                 encryptedMlDsaSecretKeyBase64: arrayBufferToBase64(identity.encryptedMlDsaSecretKey),
                 edSecretKey: identity.edSecretKey,
                 mlDsaSecretKey: identity.mlDsaSecretKey,
+                btcPublicKey: identity.btcPublicKey,
+                encryptedBtcSecretKey: identity.encryptedBtcSecretKey,
+                encryptedBtcSecretKeyBase64: arrayBufferToBase64(identity.encryptedBtcSecretKey),
+                btcSecretKey: identity.btcSecretKey,
             });
         }
         catch (err) {
@@ -762,6 +826,12 @@ export class MajikKey {
         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);
         return {
             id: encIdentity.fingerprint,
             publicKey: encIdentity.publicKey,
@@ -779,6 +849,9 @@ export class MajikKey {
             mlDsaPublicKey: encIdentity.mlDsaPublicKey,
             mlDsaSecretKey,
             encryptedMlDsaSecretKey,
+            btcPublicKey: btcMaterial.publicKey,
+            btcSecretKey: btcMaterial.privateKey,
+            encryptedBtcSecretKey,
         };
     }
     // ── PRIVATE: Encryption/Decryption ───────────────────────────────────────────
@@ -911,31 +984,90 @@ export class MajikKey {
         return arrayBufferToBase64(raw);
     }
     // ── WEB3 (EXPERIMENTAL) ─────────────────────────────────────────────────────
-    /**
-     * @experimental Blockchain/web3 integrations are experimental — this API
-     * may change without notice. `undefined` when the MajikKey is locked or
-     * has no Ed25519 signing key to derive from.
-     *
-     * By default `web3.solana` is DOMAIN-SEPARATED from the MajikKey's message
-     * signing key (see deriveSolanaKeypairFromEdSecretKey). Use
-     * `getSolanaKeypairMaterial({ reuseMessageKey: true })` if you specifically
-     * want the identical key reused for Solana instead.
-     */
+    getBtcSecretKey() {
+        if (this.isLocked)
+            throw new MajikKeyError("MajikKey is locked. Call unlock() first.");
+        if (!this._btcSecretKey)
+            throw new MajikKeyError("No Bitcoin secret key — re-import via importFromMnemonicBackup() for full migration.");
+        return this._btcSecretKey;
+    }
+    // ── WEB3 (EXPERIMENTAL) — updated getter ────────────────────────────────────
     get web3() {
         if (!this.hasSolanaKeypair)
             return undefined;
-        const material = this._getOrDeriveSolanaMaterial();
+        const solanaMaterial = this._getOrDeriveSolanaMaterial();
+        const btcMaterial = this._btcSecretKey && this._btcPublicKey
+            ? { privateKey: this._btcSecretKey, publicKey: this._btcPublicKey }
+            : undefined;
         return {
             solana: {
-                publicKey: material.publicKey,
-                secretKey: material.secretKey,
-                address: solanaAddressFromPublicKey(material.publicKey),
-                getSolanaKeypair: () => toSolanaKeyPairSigner(material),
-                getSolanaAddress: () => toSolanaAddress(material),
-                sign: (message) => signWithSolanaMaterial(material, message),
+                publicKey: solanaMaterial.publicKey,
+                secretKey: solanaMaterial.secretKey,
+                address: solanaAddressFromPublicKey(solanaMaterial.publicKey),
+                getSolanaKeypair: () => toSolanaKeyPairSigner(solanaMaterial),
+                getSolanaAddress: () => toSolanaAddress(solanaMaterial),
+                sign: (message) => signWithSolanaMaterial(solanaMaterial, message),
+            },
+            bitcoin: btcMaterial && {
+                publicKey: btcMaterial.publicKey,
+                privateKey: btcMaterial.privateKey,
+                getBitcoinAddress: () => toBitcoinAddress(btcMaterial),
+                getWIF: (options) => toWIF(btcMaterial, options),
+                sign: (hash, scheme) => signWithBitcoinMaterial(btcMaterial, hash, scheme),
             },
         };
     }
+    // ── BITCON (EXPERIMENTAL)  ────────────────────────────────────
+    /**
+     * @experimental True if this MajikKey can currently produce Bitcoin
+     * material (i.e. it's unlocked and has a Bitcoin secret key).
+     */
+    get hasBitcoinKeypair() {
+        return this.isUnlocked && this._btcSecretKey !== undefined;
+    }
+    /**
+     * @experimental Raw Bitcoin keypair material. Pass `{ standard: true }` to
+     * get the REAL BIP-84 mainnet key (recoverable in any standard wallet from
+     * the mnemonic alone) instead of Majik's default domain-separated key.
+     *
+     * NOTE: `{ standard: true }` re-derives from the raw seed on demand and is
+     * NOT the same key as `web3.bitcoin` (which is always the stored,
+     * domain-separated default) — it requires the mnemonic to reproduce again
+     * outside Majik, whereas the stored default does not.
+     */
+    getBitcoinKeypairMaterial(options) {
+        if (this.isLocked)
+            throw new MajikKeyError("MajikKey is locked. Call unlock() first.");
+        if (!options?.standard && !options?.path) {
+            if (!this._btcSecretKey || !this._btcPublicKey)
+                throw new MajikKeyError("No Bitcoin secret key — re-import via importFromMnemonicBackup() first.");
+            return { privateKey: this._btcSecretKey, publicKey: this._btcPublicKey };
+        }
+        throw new MajikKeyError("Deriving the standard BIP-84 path requires the mnemonic — " +
+            "use MajikKey.deriveStandardBitcoinFromMnemonic(mnemonic) instead.");
+    }
+    /**
+     * @experimental Derive the REAL BIP-84 mainnet Bitcoin keypair straight
+     * from a mnemonic — for one-off export/verification. Does not require
+     * an unlocked MajikKey instance.
+     */
+    static async deriveStandardBitcoinFromMnemonic(mnemonic, mnemonicLanguage = "en") {
+        MajikKeyValidator.validateMnemonic(mnemonic);
+        const wordlist = await MajikKey._getWordlist(mnemonicLanguage);
+        if (!validateMnemonic(mnemonic, wordlist)) {
+            throw new MajikKeyError("Invalid BIP39 mnemonic phrase");
+        }
+        const seed = await mnemonicToSeed(mnemonic);
+        return deriveBitcoinKeypairFromSeed(seed, { standard: true });
+    }
+    /**
+     * @experimental WIF export of the default (domain-separated) Bitcoin key.
+     */
+    getBitcoinWIF(options) {
+        const material = this.getBitcoinKeypairMaterial();
+        return toWIF(material, options);
+    }
+    // ── SOLANA (EXPERIMENTAL)  ────────────────────────────────────
     /**
      * @experimental True if this MajikKey can currently produce a Solana
      * keypair (i.e. it's unlocked and has an Ed25519 signing key).

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.12",
+  "version": "0.2.13",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",
@@ -47,12 +47,18 @@
     "prepublishOnly": "npm run build",
     "package": "npm run build && npm version patch && git push && git push --tags",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "test:web3:bitcoin": "npx vitest test/majik-key-bitcoin.test.ts",
+    "test:web3:solana": "npx vitest test/majik-key-solana.test.ts",
+    "test:web3": "npx vitest test/majik-key-bitcoin.test.ts test/majik-key-solana.test.ts",
+    "test:core": "npx vitest test/majik-key.test.ts"
   },
   "dependencies": {
     "@majikah/majik-contact": "^0.0.6",
+    "@noble/curves": "^2.2.0",
     "@noble/hashes": "^2.2.0",
     "@noble/post-quantum": "^0.6.1",
+    "@scure/bip32": "^2.2.0",
     "@scure/bip39": "^2.2.0",
     "@stablelib/aes": "^2.0.1",
     "@stablelib/ed25519": "^2.1.0",
@@ -65,6 +71,7 @@
     "hash-wasm": "^4.12.0"
   },
   "devDependencies": {
+    "@scure/btc-signer": "^2.2.0",
     "@solana/kit": "^7.0.0",
     "@types/ed2curve": "^0.2.4",
     "@types/node": "^26.1.0",
@@ -72,11 +79,15 @@
     "vitest": "^4.1.9"
   },
   "peerDependencies": {
+    "@scure/btc-signer": "^2.2.0",
     "@solana/kit": "^7.0.0"
   },
   "peerDependenciesMeta": {
     "@solana/kit": {
       "optional": true
+    },
+    "@scure/btc-signer": {
+      "optional": true
     }
   }
 }