@majikah/majik-key 0.2.12 → 0.2.14

package/dist/majik-key.js

@@ -1,27 +1,9 @@
 /**
  * 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, 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,9 +13,31 @@ 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 ─────────────────────────────────────────────────────────────────
+/**
+ * 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,8 +65,26 @@ export class MajikKey {
     _mlDsaSecretKey;
     _encryptedMlDsaSecretKey;
     _encryptedMlDsaSecretKeyBase64;
-    //Experimental
+    /**
+     * @experimental
+     */
     _solanaKeypairMaterial;
+    /**
+     * @experimental
+     */
+    _btcPublicKey;
+    /**
+     * @experimental
+     */
+    _btcSecretKey;
+    /**
+     * @experimental
+     */
+    _encryptedBtcSecretKey;
+    /**
+     * @experimental
+     */
+    _encryptedBtcSecretKeyBase64;
     constructor(options) {
         this._id = options.id;
         this._publicKey = options.publicKey;
@@ -89,57 +111,99 @@ 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 ─────────────────────────────────────────────────────────────────
+    /** 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,
@@ -149,29 +213,57 @@ export class MajikKey {
             isLocked: this.isLocked,
             kdfVersion: this.kdfVersion,
             hasMlKem: this.hasMlKem,
+            web3: {
+                hasBitcoin: this.hasBitcoin,
+                hasSolana: this.hasSolanaKeypair,
+            },
             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);
@@ -201,6 +293,12 @@ export class MajikKey {
                 encryptedMlDsaSecretKeyBase64: arrayBufferToBase64(identity.encryptedMlDsaSecretKey),
                 edSecretKey: identity.edSecretKey,
                 mlDsaSecretKey: identity.mlDsaSecretKey,
+                btcPublicKey: identity.btcPublicKey,
+                encryptedBtcSecretKey: identity.encryptedBtcSecretKey,
+                encryptedBtcSecretKeyBase64: identity.encryptedBtcSecretKey
+                    ? arrayBufferToBase64(identity.encryptedBtcSecretKey)
+                    : undefined,
+                btcSecretKey: identity.btcSecretKey,
                 mnemonicLanguage: mnemonicLanguage,
             });
         }
@@ -243,6 +341,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 +372,9 @@ export class MajikKey {
                 mlDsaPublicKey,
                 encryptedMlDsaSecretKey,
                 encryptedMlDsaSecretKeyBase64,
+                btcPublicKey,
+                encryptedBtcSecretKey,
+                encryptedBtcSecretKeyBase64,
                 mnemonicLanguage: validated?.mnemonicLanguage || "en",
             });
         }
@@ -294,6 +404,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 +436,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 +460,8 @@ export class MajikKey {
                 edSecretKey,
                 mlDsaPublicKey,
                 mlDsaSecretKey,
+                btcPublicKey,
+                btcSecretKey,
             });
         }
         catch (err) {
@@ -421,6 +542,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 +590,7 @@ export class MajikKey {
         this._mlKemSecretKey = undefined;
         this._edSecretKey = undefined;
         this._mlDsaSecretKey = undefined;
+        this._btcSecretKey = undefined;
         this._solanaKeypairMaterial = undefined;
         return this;
     }
@@ -493,6 +622,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 +698,10 @@ export class MajikKey {
                 ? arrayToBase64(this._mlDsaPublicKey)
                 : undefined,
             encryptedMlDsaSecretKey: this._encryptedMlDsaSecretKeyBase64,
+            btcPublicKey: this._btcPublicKey
+                ? arrayToBase64(this._btcPublicKey)
+                : undefined,
+            encryptedBtcSecretKey: this._encryptedBtcSecretKeyBase64,
             mnemonicLanguage: this._mnemonicLanguage,
         };
     }
@@ -660,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");
             }
@@ -693,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;
@@ -723,6 +855,12 @@ export class MajikKey {
                 encryptedMlDsaSecretKeyBase64: arrayBufferToBase64(identity.encryptedMlDsaSecretKey),
                 edSecretKey: identity.edSecretKey,
                 mlDsaSecretKey: identity.mlDsaSecretKey,
+                btcPublicKey: identity.btcPublicKey,
+                encryptedBtcSecretKey: identity.encryptedBtcSecretKey,
+                encryptedBtcSecretKeyBase64: identity.encryptedBtcSecretKey
+                    ? arrayBufferToBase64(identity.encryptedBtcSecretKey)
+                    : undefined,
+                btcSecretKey: identity.btcSecretKey,
             });
         }
         catch (err) {
@@ -737,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 {
@@ -752,16 +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);
+        // @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,
@@ -779,6 +937,9 @@ export class MajikKey {
             mlDsaPublicKey: encIdentity.mlDsaPublicKey,
             mlDsaSecretKey,
             encryptedMlDsaSecretKey,
+            btcPublicKey,
+            btcSecretKey,
+            encryptedBtcSecretKey,
         };
     }
     // ── PRIVATE: Encryption/Decryption ───────────────────────────────────────────
@@ -912,30 +1073,95 @@ export class MajikKey {
     }
     // ── 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.
+     * @experimental
+     */
+    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 ────────────────────────────────────
+    /**
+     * @experimental
      */
     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.14",
   "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
     }
   }
 }