@majikah/majik-key 0.7.0 → 1.0.1

package/dist/majik-key.js

@@ -2,42 +2,43 @@
  * MajikKey.ts
  * Seed phrase account library for the Majikah ecosystem.
  *
+ * v0.8 — key REGISTRY. Every account stores a set of keypairs in a KeyStore,
+ * addressed by namespaced id (see core/keys/key-id.ts). The core four
+ * (classic:x25519, classic:ed25519, pq:ml-kem-768, pq:ml-dsa-87) are always
+ * present on new accounts; anything else is opt-in via `keys` / `addKeys()`.
+ *
+ * The pre-registry per-algorithm getters still work and are marked
+ * @deprecated: they are thin wrappers over the registry accessors.
+ *
+ * Derivation (all deterministic from the BIP-39 mnemonic) lives in
+ * core/keys/key-impls.ts. Frozen "legacy-v1" recipes are pinned by
+ * vectors/legacy-v1.vectors.json.
  */
 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";
-import { arrayBufferToBase64, arrayToBase64, base64ToArrayBuffer, concatUint8Arrays, utf8ToBase64, base64ToUtf8, seedStringToArray, seedArrayToString, base64ToUint8Array, } from "./core/utils";
-import { KDF_VERSION, MAJIK_MNEMONIC_SALT } from "./core/crypto/constants";
-import { MajikKeyValidator } from "./core/validator";
-import { MajikKeyError } from "./core/error";
-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";
+import { aesGcmDecrypt, aesGcmEncrypt, deriveKeyFromPassphraseArgon2, deriveKeyFromMnemonicArgon2, deriveKeyFromPassphrase, fingerprintFromPublicRaw, generateRandomBytes, IV_LENGTH, } from "./core/crypto/crypto-provider.js";
+import { MajikContact } from "@majikah/majik-contact/dist/contacts/majik-contact.js";
+import { arrayToBase64, base64ToArrayBuffer, utf8ToBase64, base64ToUtf8, seedStringToArray, seedArrayToString, base64ToUint8Array, } from "./core/utils.js";
+import { KDF_VERSION, LEGACY_MAJIK_MNEMONIC_SALT, BACKUP_SALT_WRITE_VERSION, backupSaltFor, } from "./core/crypto/constants.js";
+import { MajikKeyValidator } from "./core/validator.js";
+import { MajikKeyError } from "./core/error.js";
+import { MajikMessageIdentity } from "./core/database/system/identity.js";
+import { WORDLISTS } from "./core/crypto/wordlist.js";
+import { deriveBitcoinKeypairFromSeed, signWithBitcoinMaterial, toBitcoinAddress, toWIF, deriveSolanaKeypairFromEdSecretKey, signWithSolanaMaterial, solanaAddressFromPublicKey, solanaMaterialFromEd25519SecretKey, toSolanaAddress, toSolanaKeyPairSigner, ethereumAddressFromPublicKey, signEthereumHash, signEthereumMessage, toEthereumPrivateKeyHex, } from "./core/web3/index.js";
+import { CORE_KEYS, KeyId } from "./core/keys/key-id.js";
+import { KEY_ALGORITHMS, enableableKeyIds, getAlgorithm, knownKeyIds, resolveRequestedKeys, } from "./core/keys/registry.js";
+import { deriveKeys } from "./core/keys/key-impls.js";
+import { KeyStore } from "./core/keys/key-store.js";
+import { MajikKeypair } from "./core/keys/keypair-handle.js";
+export { KeyId, KeyFamily, CORE_KEYS } from "./core/keys/key-id.js";
+export { MajikKeypair } from "./core/keys/keypair-handle.js";
 const secureFill = Uint8Array.prototype.fill;
 const SALT_SIZE = 32;
+const KEYS_VERSION = 1;
 /**
  * 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
- *
+ * Registry of keypairs deterministically derived from one BIP-39 mnemonic.
+ * See core/keys/registry.ts for every supported algorithm and its status.
  */
 export class MajikKey {
     _id;
@@ -47,81 +48,30 @@ export class MajikKey {
     _backup;
     _timestamp;
     _mnemonicLanguage;
-    _encryptedPrivateKey;
-    _encryptedPrivateKeyBase64;
+    _store;
     _salt;
     _label;
     _kdfVersion;
-    _mlKemPublicKey;
-    _mlKemSecretKey;
-    _encryptedMlKemSecretKey;
-    _encryptedMlKemSecretKeyBase64;
-    _privateKey;
-    _edPublicKey;
-    _edSecretKey;
-    _encryptedEdSecretKey;
-    _encryptedEdSecretKeyBase64;
-    _mlDsaPublicKey;
-    _mlDsaSecretKey;
-    _encryptedMlDsaSecretKey;
-    _encryptedMlDsaSecretKeyBase64;
-    /**
-     * @experimental
-     */
+    /** @experimental derived view over classic:ed25519; cached while unlocked */
     _solanaKeypairMaterial;
-    /**
-     * @experimental
-     */
-    _btcPublicKey;
-    /**
-     * @experimental
-     */
-    _btcSecretKey;
-    /**
-     * @experimental
-     */
-    _encryptedBtcSecretKey;
-    /**
-     * @experimental
-     */
-    _encryptedBtcSecretKeyBase64;
-    constructor(options) {
-        this._id = options.id;
-        this._publicKey = options.publicKey;
-        this._publicKeyBase64 = options.publicKeyBase64;
-        this._fingerprint = options.fingerprint;
-        this._encryptedPrivateKey = options.encryptedPrivateKey;
-        this._encryptedPrivateKeyBase64 = options.encryptedPrivateKeyBase64;
-        this._salt = options.salt;
-        this._backup = options.backup;
-        this._label = options.label || "";
-        this._timestamp = options.timestamp || new Date();
-        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._edPublicKey = options.edPublicKey;
-        this._encryptedEdSecretKey = options.encryptedEdSecretKey;
-        this._encryptedEdSecretKeyBase64 = options.encryptedEdSecretKeyBase64;
-        this._mlDsaPublicKey = options.mlDsaPublicKey;
-        this._encryptedMlDsaSecretKey = options.encryptedMlDsaSecretKey;
-        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";
+    constructor(init) {
+        this._id = init.id;
+        this._store = init.store;
+        const xPub = init.store.getPublicKey(KeyId.X25519);
+        this._publicKey = { raw: xPub };
+        this._publicKeyBase64 = arrayToBase64(xPub);
+        this._fingerprint = init.fingerprint;
+        this._salt = init.salt;
+        this._backup = init.backup;
+        this._label = init.label || "";
+        this._timestamp = init.timestamp || new Date();
+        this._kdfVersion = init.kdfVersion ?? KDF_VERSION.PBKDF2;
+        this._mnemonicLanguage = init.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;
     }
@@ -129,80 +79,186 @@ export class MajikKey {
     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;
+        return !this._store.isUnlocked;
     }
-    /** `true` if private key material is currently decrypted in memory. The inverse of `isLocked`. */
     get isUnlocked() {
-        return this._privateKey !== undefined;
+        return this._store.isUnlocked;
     }
-    /** ML-KEM-768 (FIPS-203) public key. Post-quantum key encapsulation. Always available, even when locked. */
+    /** `true` if this account holds every key in CORE_KEYS. Legacy accounts may not — see `missingKeys()` / `addKeys()`. */
+    get isCoreComplete() {
+        return this._store.hasAll(CORE_KEYS);
+    }
+    /** `true` if this account is on Argon2id *and* has ML-KEM-768 keys. */
+    get isFullyUpgraded() {
+        return this.isArgon2id && this.hasMlKem;
+    }
+    // ── Registry accessors ──────────────────────────────────────────────────────
+    /** Is this key present on the account? Works while locked. Derived views (web3:sol) count when their source key exists. */
+    hasKey(id) {
+        if (this._store.has(id))
+            return true;
+        const def = getAlgorithm(id);
+        return (!!def &&
+            def.kind === "derived" &&
+            !!def.derivedFrom &&
+            this._store.has(def.derivedFrom));
+    }
+    hasKeys(ids) {
+        return ids.every((id) => this.hasKey(id));
+    }
+    /** Which of `ids` (default: the core four) are NOT on this account. */
+    missingKeys(ids = CORE_KEYS) {
+        return ids.filter((id) => !this.hasKey(id));
+    }
+    /** Namespaced ids of every key available on this account, in canonical order. */
+    availableKeys(options) {
+        return knownKeyIds(options?.family).filter((id) => this.hasKey(id));
+    }
+    /** Metadata for every available key. No secret material. */
+    listKeys() {
+        return this.availableKeys().map((id) => {
+            const def = KEY_ALGORITHMS[id];
+            let pub;
+            try {
+                pub = arrayToBase64(this.getPublicKey(id));
+            }
+            catch {
+                pub = undefined; // derived view while locked
+            }
+            return {
+                id,
+                family: def.family,
+                purpose: def.purpose,
+                kind: def.kind,
+                status: def.status,
+                publicKeyBase64: pub,
+            };
+        });
+    }
+    /** Every algorithm id this library version can create/enable. */
+    static supportedKeys() {
+        return enableableKeyIds();
+    }
+    /** Public key bytes for `id`. Works while locked (derived views need an unlocked account). */
+    getPublicKey(id) {
+        if (this._store.has(id))
+            return this._store.getPublicKey(id);
+        if (id === KeyId.SOL && this._store.has(KeyId.ED25519))
+            return this.getSolanaKeypairMaterial().publicKey;
+        throw new MajikKeyError(`No "${id}" key on this account`);
+    }
+    getPrivateKey(id) {
+        if (id === undefined)
+            return { raw: this._requireSecret(KeyId.X25519) };
+        if (id === KeyId.SOL && this._store.has(KeyId.ED25519))
+            return this.getSolanaKeypairMaterial().secretKey;
+        return this._requireSecret(id);
+    }
+    /** A live handle with `.public` / `.private` / `.publicBase64`. Reads through to the account, so it never goes stale across lock(). */
+    getKeypair(id) {
+        if (!this.hasKey(id))
+            throw new MajikKeyError(`No "${id}" key on this account`);
+        return new MajikKeypair(id, () => this.getPublicKey(id), () => this.getPrivateKey(id), () => this.isUnlocked);
+    }
+    _requireSecret(id, missingMessage) {
+        if (this.isLocked) {
+            throw new MajikKeyError("MajikKey is locked. Call unlock() first.");
+        }
+        const slot = this._store.slot(id);
+        if (!slot) {
+            throw new MajikKeyError(missingMessage ??
+                `No "${id}" key on this account — add it with addKeys(), which requires the mnemonic.`);
+        }
+        const secret = this._store.peekSecretKey(id);
+        if (!secret) {
+            if (id === KeyId.BTC) {
+                throw new MajikKeyError("Bitcoin private key material is unavailable; re-import via importFromMnemonicBackup.");
+            }
+            throw new MajikKeyError(missingMessage ??
+                `Private key material for "${id}" is unavailable. Re-import the account from its mnemonic backup.`);
+        }
+        return secret;
+    }
+    // ── Deprecated per-algorithm getters (wrappers over the registry) ───────────
+    /** @deprecated Use `getPublicKey(KeyId.ML_KEM_768)`. */
     get mlKemPublicKey() {
-        return this._mlKemPublicKey;
+        return (this._store.has(KeyId.ML_KEM_768)
+            ? this._store.getPublicKey(KeyId.ML_KEM_768)
+            : undefined);
     }
-    /** 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. */
+    /** @deprecated Use `getPrivateKey(KeyId.ML_KEM_768)`. */
     get mlKemSecretKey() {
-        return this._mlKemSecretKey;
+        return this._store.peekSecretKey(KeyId.ML_KEM_768);
     }
-    /** `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. */
+    /** @deprecated Use `hasKey(KeyId.ML_KEM_768)`. */
     get hasMlKem() {
-        return this._mlKemPublicKey !== undefined;
+        return this._store.has(KeyId.ML_KEM_768);
     }
-    /** `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;
+    /** @deprecated Use `getPublicKey(KeyId.ED25519)`. */
+    get edPublicKey() {
+        return this._store.has(KeyId.ED25519)
+            ? this._store.getPublicKey(KeyId.ED25519)
+            : undefined;
     }
-    /**
-     * @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()`).
-     */
+    /** @deprecated Use `getPublicKey(KeyId.ML_DSA_87)`. */
+    get mlDsaPublicKey() {
+        return this._store.has(KeyId.ML_DSA_87)
+            ? this._store.getPublicKey(KeyId.ML_DSA_87)
+            : undefined;
+    }
+    /** @deprecated Use `hasKeys([KeyId.ED25519, KeyId.ML_DSA_87])`. */
+    get hasSigningKeys() {
+        return this._store.has(KeyId.ED25519) && this._store.has(KeyId.ML_DSA_87);
+    }
+    /** @experimental @deprecated Use `getPublicKey(KeyId.BTC)`. */
     get btcPublicKey() {
-        return this._btcPublicKey;
+        return this._store.has(KeyId.BTC)
+            ? this._store.getPublicKey(KeyId.BTC)
+            : undefined;
     }
-    /** @experimental `true` if this account has a stored Bitcoin keypair. */
+    /** @experimental @deprecated Use `hasKey(KeyId.BTC)`. */
     get hasBitcoin() {
-        return this._btcPublicKey !== undefined;
+        return this._store.has(KeyId.BTC);
     }
-    /**
-     * 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.
-     */
+    /** @deprecated Use `getPrivateKey(KeyId.ML_KEM_768)`. */
+    getMlKemSecretKey() {
+        return this._requireSecret(KeyId.ML_KEM_768, "No ML-KEM secret key — add it with addKeys() (requires the mnemonic).");
+    }
+    /** @deprecated Use `getPrivateKey(KeyId.ED25519)`. */
+    getEdSecretKey() {
+        return this._requireSecret(KeyId.ED25519, "No Ed25519 secret key — add it with addKeys() (requires the mnemonic).");
+    }
+    /** @deprecated Use `getPrivateKey(KeyId.ML_DSA_87)`. */
+    getMlDsaSecretKey() {
+        return this._requireSecret(KeyId.ML_DSA_87, "No ML-DSA secret key — add it with addKeys() (requires the mnemonic).");
+    }
+    /** @experimental @deprecated Use `getPrivateKey(KeyId.BTC)`. */
+    getBtcSecretKey() {
+        return this._requireSecret(KeyId.BTC, "No Bitcoin secret key — add it with addKeys([KeyId.BTC], mnemonic, passphrase).");
+    }
+    /** Non-secret snapshot of this account's state. */
     get metadata() {
         return {
             id: this.id,
@@ -213,91 +269,53 @@ export class MajikKey {
             kdfVersion: this.kdfVersion,
             hasMlKem: this.hasMlKem,
             web3: {
+                hasEthereum: this.hasEthereum,
                 hasBitcoin: this.hasBitcoin,
                 hasSolana: this.hasSolanaKeypair,
             },
+            keys: this.availableKeys(),
             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 ──────────────────────────────────────────────────────────────────
     /**
-     * Creates a brand-new MajikKey account from a BIP-39 mnemonic.
+     * Creates a brand-new MajikKey from a BIP-39 mnemonic and returns it UNLOCKED.
+     *
+     * Always derives the core four (X25519, Ed25519, ML-KEM-768, ML-DSA-87).
+     * Pass `options.keys` for more, e.g. `{ keys: [KeyId.BTC] }`.
      *
-     * 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()`).
+     * ⚠️ Behavior change vs 0.7: Bitcoin is no longer derived by default.
      *
-     * @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.
+     * @throws {MajikKeyError} on invalid mnemonic/passphrase/label or unusable key ids.
      */
-    static async create(mnemonic, passphrase, label, options = {
-        deriveBitcoin: true,
-        mnemonicLanguage: "en",
-    }) {
+    static async create(mnemonic, passphrase, label, options = {}) {
         try {
             MajikKeyValidator.validateMnemonic(mnemonic);
             MajikKeyValidator.validatePassphrase(passphrase);
             MajikKeyValidator.validateLabel(label);
-            const { deriveBitcoin, mnemonicLanguage } = options;
-            const wordlist = await MajikKey._getWordlist(mnemonicLanguage || "en");
+            const mnemonicLanguage = options.mnemonicLanguage || "en";
+            const ids = MajikKey._resolveCreateKeys(options);
+            const wordlist = await MajikKey._getWordlist(mnemonicLanguage);
             if (!validateMnemonic(mnemonic, wordlist)) {
                 throw new MajikKeyError("Invalid BIP39 mnemonic phrase");
             }
-            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);
+            const d = await MajikKey._deriveFromMnemonic(mnemonic, passphrase, ids);
+            const backup = await MajikKey._exportMnemonicBackup({
+                id: d.fingerprint,
+                fingerprint: d.fingerprint,
+                publicRaw: d.xPublic,
+                privateRaw: d.xSecret,
+            }, mnemonic);
             return new MajikKey({
-                id: identity.id,
-                publicKey: identity.publicKey,
-                publicKeyBase64,
-                fingerprint: identity.fingerprint,
-                encryptedPrivateKey: identity.encryptedPrivateKey,
-                encryptedPrivateKeyBase64: arrayBufferToBase64(identity.encryptedPrivateKey),
-                salt: identity.salt,
+                id: d.fingerprint,
+                fingerprint: d.fingerprint,
+                salt: d.salt,
                 backup,
                 label: label || "",
                 timestamp: new Date(),
                 kdfVersion: KDF_VERSION.ARGON2ID,
-                mlKemPublicKey: identity.mlKemPublicKey,
-                mlKemSecretKey: identity.mlKemSecretKey,
-                encryptedMlKemSecretKey: identity.encryptedMlKemSecretKey,
-                encryptedMlKemSecretKeyBase64: arrayBufferToBase64(identity.encryptedMlKemSecretKey),
-                privateKey: identity.privateKey,
-                edPublicKey: identity.edPublicKey,
-                encryptedEdSecretKey: identity.encryptedEdSecretKey,
-                encryptedEdSecretKeyBase64: arrayBufferToBase64(identity.encryptedEdSecretKey),
-                mlDsaPublicKey: identity.mlDsaPublicKey,
-                encryptedMlDsaSecretKey: identity.encryptedMlDsaSecretKey,
-                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,
+                mnemonicLanguage,
+                store: d.store,
             });
         }
         catch (err) {
@@ -306,74 +324,56 @@ export class MajikKey {
             throw new MajikKeyError("Failed to create MajikKey", err);
         }
     }
+    static _resolveCreateKeys(options) {
+        const requested = [...(options.keys ?? [])];
+        if (options.deriveBitcoin === true)
+            requested.push(KeyId.BTC);
+        return resolveRequestedKeys(requested);
+    }
     // ── READ ────────────────────────────────────────────────────────────────────
+    /**
+     * Parse a MajikKey from JSON. Accepts BOTH shapes:
+     *  - registry JSON (has `keys`)  → used as-is
+     *  - legacy flat JSON (no `keys`) → auto-migrated in memory (no secrets, no
+     *    passphrase, no mnemonic needed). Re-serialize with toJSON() to persist
+     *    the upgraded shape.
+     */
     static fromJSON(json) {
         try {
             const parsed = typeof json === "string" ? JSON.parse(json) : json;
-            const validated = MajikKeyValidator.validateJSON(parsed);
             const anyParsed = parsed;
-            const publicKeyBuffer = base64ToArrayBuffer(validated.publicKey);
-            const encryptedPrivateKeyBuffer = base64ToArrayBuffer(validated.encryptedPrivateKey);
-            const mlKemPublicKey = base64ToUint8Array(anyParsed.mlKemPublicKey);
-            let encryptedMlKemSecretKey;
-            let encryptedMlKemSecretKeyBase64;
-            if (anyParsed.encryptedMlKemSecretKey) {
-                encryptedMlKemSecretKeyBase64 = anyParsed.encryptedMlKemSecretKey;
-                encryptedMlKemSecretKey = base64ToArrayBuffer(anyParsed.encryptedMlKemSecretKey);
-            }
-            const edPublicKey = anyParsed.edPublicKey
-                ? base64ToUint8Array(anyParsed.edPublicKey)
-                : undefined;
-            let encryptedEdSecretKey;
-            let encryptedEdSecretKeyBase64;
-            if (anyParsed.encryptedEdSecretKey) {
-                encryptedEdSecretKeyBase64 = anyParsed.encryptedEdSecretKey;
-                encryptedEdSecretKey = base64ToArrayBuffer(anyParsed.encryptedEdSecretKey);
+            let store;
+            let base;
+            if (Array.isArray(anyParsed.keys)) {
+                base = MajikKey._validateRegistryJSON(anyParsed);
+                store = KeyStore.fromEntries(anyParsed.keys);
+                if (!store.has(KeyId.X25519))
+                    throw new MajikKeyError("Invalid MajikKey JSON: `keys` has no classic:x25519 entry");
+                // If the flat legacy field is also present it must agree (corruption/tamper check).
+                if (anyParsed.publicKey &&
+                    anyParsed.publicKey !==
+                        arrayToBase64(store.getPublicKey(KeyId.X25519)))
+                    throw new MajikKeyError("Invalid MajikKey JSON: `publicKey` does not match the classic:x25519 entry");
             }
-            const mlDsaPublicKey = anyParsed.mlDsaPublicKey
-                ? base64ToUint8Array(anyParsed.mlDsaPublicKey)
-                : undefined;
-            let encryptedMlDsaSecretKey;
-            let encryptedMlDsaSecretKeyBase64;
-            if (anyParsed.encryptedMlDsaSecretKey) {
-                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);
+            else {
+                const validated = MajikKeyValidator.validateJSON(parsed);
+                base = validated;
+                store = KeyStore.fromLegacyJSON({
+                    ...anyParsed,
+                    publicKey: validated.publicKey,
+                    encryptedPrivateKey: validated.encryptedPrivateKey,
+                });
             }
             return new MajikKey({
-                id: validated.id,
-                publicKey: { raw: new Uint8Array(publicKeyBuffer) },
-                publicKeyBase64: validated.publicKey,
-                fingerprint: validated.fingerprint,
-                encryptedPrivateKey: encryptedPrivateKeyBuffer,
-                encryptedPrivateKeyBase64: validated.encryptedPrivateKey,
-                salt: validated.salt,
-                backup: validated.backup,
-                label: validated.label || "",
-                timestamp: new Date(validated.timestamp),
-                kdfVersion: validated.kdfVersion ??
-                    KDF_VERSION.PBKDF2,
-                mlKemPublicKey,
-                encryptedMlKemSecretKey,
-                encryptedMlKemSecretKeyBase64,
-                edPublicKey,
-                encryptedEdSecretKey,
-                encryptedEdSecretKeyBase64,
-                mlDsaPublicKey,
-                encryptedMlDsaSecretKey,
-                encryptedMlDsaSecretKeyBase64,
-                btcPublicKey,
-                encryptedBtcSecretKey,
-                encryptedBtcSecretKeyBase64,
-                mnemonicLanguage: validated?.mnemonicLanguage || "en",
+                id: base.id,
+                fingerprint: base.fingerprint,
+                salt: base.salt,
+                backup: base.backup,
+                label: base.label || "",
+                timestamp: new Date(base.timestamp),
+                kdfVersion: base.kdfVersion ?? KDF_VERSION.PBKDF2,
+                mnemonicLanguage: base.mnemonicLanguage || "en",
+                store,
             });
         }
         catch (err) {
@@ -382,35 +382,44 @@ export class MajikKey {
             throw new MajikKeyError("Failed to parse MajikKey from JSON", err);
         }
     }
+    static _validateRegistryJSON(j) {
+        for (const f of ["id", "fingerprint", "salt", "backup", "timestamp"]) {
+            if (typeof j[f] !== "string" || !j[f])
+                throw new MajikKeyError(`Invalid MajikKey JSON: missing "${f}"`);
+        }
+        if (j.keysVersion !== undefined && j.keysVersion > KEYS_VERSION)
+            throw new MajikKeyError(`This MajikKey JSON uses keys schema v${j.keysVersion}; this library supports up to v${KEYS_VERSION}. Upgrade the library.`);
+        return j;
+    }
     /**
      * Export a fully unlocked MajikKey with all raw private keys.
      * ⚠️ DANGEROUS — output contains unencrypted private key material.
      * Only use for server-side secrets injection.
-     * Never log, store in a database, or transmit over the network.
      */
     toDangerousJSON() {
         if (this.isLocked)
             throw new MajikKeyError("MajikKey must be unlocked to export dangerous JSON.");
-        if (!this._edSecretKey ||
-            !this._mlDsaSecretKey ||
-            !this._mlKemSecretKey ||
-            !this._privateKey)
-            throw new MajikKeyError("MajikKey is missing secret keys — re-import via importFromMnemonicBackup() first.");
+        if (!this.hasKeys(CORE_KEYS))
+            throw new MajikKeyError("MajikKey is missing core keys — add them with addKeys(CORE_KEYS, mnemonic, passphrase) first.");
+        const secretKeys = {};
+        for (const [id, secret] of this._store.exportSecrets())
+            secretKeys[id] = arrayToBase64(secret);
+        const s = (id) => this._store.getSecretKey(id);
         return {
             ...this.toJSON(),
-            privateKeyBase64: arrayToBase64(this._privateKey.raw),
-            mlKemSecretKeyBase64: arrayToBase64(this._mlKemSecretKey),
-            edSecretKeyBase64: arrayToBase64(this._edSecretKey),
-            mlDsaSecretKeyBase64: arrayToBase64(this._mlDsaSecretKey),
-            btcSecretKeyBase64: this._btcSecretKey
-                ? arrayToBase64(this._btcSecretKey)
+            privateKeyBase64: arrayToBase64(s(KeyId.X25519)),
+            mlKemSecretKeyBase64: arrayToBase64(s(KeyId.ML_KEM_768)),
+            edSecretKeyBase64: arrayToBase64(s(KeyId.ED25519)),
+            mlDsaSecretKeyBase64: arrayToBase64(s(KeyId.ML_DSA_87)),
+            btcSecretKeyBase64: this._store.has(KeyId.BTC)
+                ? arrayToBase64(s(KeyId.BTC))
                 : undefined,
+            secretKeys,
         };
     }
     /**
      * Reconstruct a fully unlocked MajikKey from a dangerous JSON export.
      * ⚠️ DANGEROUS — input contains unencrypted private key material.
-     * Intended for server-side use only (e.g. TSA signing key loaded from Cloudflare Secrets).
      * No KDF is involved — reconstruction is instant.
      */
     static fromDangerousJSON(json) {
@@ -427,38 +436,34 @@ export class MajikKey {
                 !parsed.mlKemPublicKey ||
                 !parsed.mlKemSecretKeyBase64)
                 throw new MajikKeyError("Invalid MajikKeyDangerousJSON — missing required fields");
-            const privateKeyBytes = base64ToUint8Array(parsed.privateKeyBase64);
-            const edPublicKey = base64ToUint8Array(parsed.edPublicKey);
-            const edSecretKey = base64ToUint8Array(parsed.edSecretKeyBase64);
-            const mlDsaPublicKey = base64ToUint8Array(parsed.mlDsaPublicKey);
-            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;
+            const anyParsed = parsed;
+            const store = Array.isArray(anyParsed.keys)
+                ? KeyStore.fromEntries(anyParsed.keys)
+                : KeyStore.fromLegacyJSON(parsed);
+            const secrets = new Map();
+            const put = (id, b64) => {
+                if (b64 && store.has(id))
+                    secrets.set(id, base64ToUint8Array(b64));
+            };
+            put(KeyId.X25519, parsed.privateKeyBase64);
+            put(KeyId.ML_KEM_768, parsed.mlKemSecretKeyBase64);
+            put(KeyId.ED25519, parsed.edSecretKeyBase64);
+            put(KeyId.ML_DSA_87, parsed.mlDsaSecretKeyBase64);
+            put(KeyId.BTC, parsed.btcSecretKeyBase64);
+            for (const [id, b64] of Object.entries(parsed.secretKeys ?? {}))
+                if (store.has(id))
+                    secrets.set(id, base64ToUint8Array(b64));
+            store.attachSecrets(secrets);
             return new MajikKey({
                 id: parsed.id,
                 fingerprint: parsed.fingerprint,
-                publicKey: { raw: base64ToUint8Array(parsed.publicKey) },
-                publicKeyBase64: parsed.publicKey,
-                privateKey: { raw: privateKeyBytes },
-                encryptedPrivateKey: new ArrayBuffer(0),
-                encryptedPrivateKeyBase64: parsed.encryptedPrivateKey,
                 salt: parsed.salt,
                 backup: parsed.backup,
+                label: parsed.label || "",
+                timestamp: parsed.timestamp ? new Date(parsed.timestamp) : undefined,
                 kdfVersion: parsed?.kdfVersion || KDF_VERSION.ARGON2ID,
-                mlKemPublicKey,
-                mlKemSecretKey,
-                edPublicKey,
-                edSecretKey,
-                mlDsaPublicKey,
-                mlDsaSecretKey,
-                btcPublicKey,
-                btcSecretKey,
+                mnemonicLanguage: parsed.mnemonicLanguage,
+                store,
             });
         }
         catch (err) {
@@ -481,24 +486,37 @@ export class MajikKey {
             language: this._mnemonicLanguage,
         };
     }
-    static async fromMnemonicJSON(mnemonicJson, passphrase, label, options = {
-        deriveBitcoin: true,
-        mnemonicLanguage: "en",
-    }) {
+    static async fromMnemonicJSON(mnemonicJson, passphrase, label, options = {}) {
         try {
             const parsed = typeof mnemonicJson === "string"
                 ? JSON.parse(mnemonicJson)
                 : mnemonicJson;
-            if (!parsed.id || !parsed.seed || !Array.isArray(parsed.seed))
+            if (!parsed ||
+                !parsed.id ||
+                !Array.isArray(parsed.seed) ||
+                parsed.seed.length === 0) {
                 throw new MajikKeyError("Invalid MnemonicJSON");
+            }
             const mnemonic = seedArrayToString(parsed.seed);
             MajikKeyValidator.validateMnemonic(mnemonic);
-            return await MajikKey.create(mnemonic, passphrase, label, options);
+            // Explicit caller option wins.
+            // Otherwise preserve the language embedded
+            // in the MnemonicJSON.
+            const mnemonicLanguage = options.mnemonicLanguage ?? parsed.language ?? "en";
+            const wordlist = await MajikKey._getWordlist(mnemonicLanguage);
+            if (!validateMnemonic(mnemonic, wordlist)) {
+                throw new MajikKeyError("Invalid BIP39 mnemonic phrase");
+            }
+            return await MajikKey.create(mnemonic, passphrase, label, {
+                ...options,
+                mnemonicLanguage,
+            });
         }
         catch (err) {
-            if (err instanceof MajikKeyError)
+            if (err instanceof MajikKeyError) {
                 throw err;
-            throw new MajikKeyError("Failed to create MajikKey from MnemonicJSON", err);
+            }
+            throw new MajikKeyError("Failed to import MnemonicJSON", err);
         }
     }
     // ── UPDATE ───────────────────────────────────────────────────────────────────
@@ -512,54 +530,8 @@ export class MajikKey {
             throw new MajikKeyError("MajikKey must be unlocked to update passphrase");
         MajikKeyValidator.validatePassphrase(currentPassphrase, "Current passphrase");
         MajikKeyValidator.validatePassphrase(newPassphrase, "New passphrase");
-        const salt = new Uint8Array(base64ToArrayBuffer(this._salt));
-        const privateKeyBuffer = await MajikKey._decryptPrivateKey(this._encryptedPrivateKey, currentPassphrase, salt, this._kdfVersion);
         try {
-            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);
-                if (this._mlKemSecretKey)
-                    secureFill.call(this._mlKemSecretKey, 0);
-                this._mlKemSecretKey = mlKemSecretKeyBytes;
-            }
-            if (this._encryptedEdSecretKey) {
-                const edSecretKeyBytes = await MajikKey._decryptSigningKey(this._encryptedEdSecretKey, currentPassphrase, salt);
-                const encEd = await MajikKey._encryptSigningKey(edSecretKeyBytes, newPassphrase, newSalt);
-                this._encryptedEdSecretKey = encEd;
-                this._encryptedEdSecretKeyBase64 = arrayBufferToBase64(encEd);
-                if (this._edSecretKey)
-                    secureFill.call(this._edSecretKey, 0);
-                this._edSecretKey = edSecretKeyBytes;
-            }
-            if (this._encryptedMlDsaSecretKey) {
-                const mlDsaSecretKeyBytes = await MajikKey._decryptSigningKey(this._encryptedMlDsaSecretKey, currentPassphrase, salt);
-                const encDsa = await MajikKey._encryptSigningKey(mlDsaSecretKeyBytes, newPassphrase, newSalt);
-                this._encryptedMlDsaSecretKey = encDsa;
-                this._encryptedMlDsaSecretKeyBase64 = arrayBufferToBase64(encDsa);
-                if (this._mlDsaSecretKey)
-                    secureFill.call(this._mlDsaSecretKey, 0);
-                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);
-                if (this._btcSecretKey)
-                    secureFill.call(this._btcSecretKey, 0);
-                this._btcSecretKey = btcSecretKeyBytes;
-            }
+            await this._reencryptAll(currentPassphrase, newPassphrase);
             return this;
         }
         catch (err) {
@@ -567,30 +539,17 @@ export class MajikKey {
                 throw err;
             throw new MajikKeyError("Failed to update passphrase", err);
         }
-        finally {
-            // Clear the temporary unencrypted buffer
-            secureFill.call(new Uint8Array(privateKeyBuffer), 0);
-            secureFill.call(salt, 0);
-        }
     }
     /**
      * Migrate KDF from PBKDF2 to Argon2id without changing passphrase.
-     * NOTE: Does not add ML-KEM keys — use importFromMnemonicBackup() for full upgrade.
+     * Does not add new key types — use addKeys() (requires the mnemonic).
      */
     async migrate(passphrase) {
         MajikKeyValidator.validatePassphrase(passphrase);
         if (this._kdfVersion === KDF_VERSION.ARGON2ID)
             return this;
-        const salt = new Uint8Array(base64ToArrayBuffer(this._salt));
-        let privateKeyBuffer;
         try {
-            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;
+            await this._reencryptAll(passphrase, passphrase);
             return this;
         }
         catch (err) {
@@ -598,66 +557,107 @@ export class MajikKey {
                 throw err;
             throw new MajikKeyError("Failed to migrate MajikKey to Argon2id", err);
         }
-        finally {
-            if (privateKeyBuffer)
-                secureFill.call(new Uint8Array(privateKeyBuffer), 0);
-            secureFill.call(salt, 0);
+    }
+    /**
+     * Add keypairs this account doesn't have yet (new algorithms, or core keys
+     * missing on a legacy account). Requires the original MNEMONIC: new keys are
+     * derived from the seed, which is never stored. Also requires the current
+     * passphrase (to encrypt the new keys under the account's existing salt).
+     *
+     * Safe by construction: the mnemonic must reproduce this account's X25519
+     * key, and the passphrase must decrypt it, before anything is added.
+     * Keys already present are skipped. Account must be on Argon2id — call
+     * `migrate(passphrase)` first if `isArgon2id` is false.
+     *
+     * @returns the ids that were added
+     */
+    async addKeys(ids, mnemonic, passphrase) {
+        try {
+            MajikKeyValidator.validateMnemonic(mnemonic);
+            MajikKeyValidator.validatePassphrase(passphrase);
+            if (!this.isArgon2id)
+                throw new MajikKeyError("Account is on the legacy KDF. Call migrate(passphrase) before addKeys().");
+            // resolveRequestedKeys validates status/implementation; we only add what was asked for AND is missing.
+            const resolved = resolveRequestedKeys(ids);
+            const toAdd = [...new Set(ids)].filter((id) => resolved.includes(id) && !this._store.has(id));
+            if (toAdd.length === 0)
+                return [];
+            const wordlist = await MajikKey._getWordlist(this._mnemonicLanguage);
+            if (!validateMnemonic(mnemonic, wordlist))
+                throw new MajikKeyError("Invalid BIP39 mnemonic phrase");
+            const salt = new Uint8Array(base64ToArrayBuffer(this._salt));
+            const aesKey = await MajikKey._deriveVaultKey(passphrase, salt);
+            const seed64 = await mnemonicToSeed(mnemonic);
+            try {
+                // 1) passphrase must be right
+                const xBlob = this._store.slot(KeyId.X25519).encryptedSecretKey;
+                if (!xBlob)
+                    throw new MajikKeyError("Account has no encrypted X25519 key");
+                KeyStore.open(aesKey, xBlob, "classic:x25519 secret key");
+                // 2) mnemonic must belong to this account
+                const probe = deriveKeys(seed64, [KeyId.X25519]).get(KeyId.X25519);
+                if (fingerprintFromPublicRaw(probe.publicKey) !== this._fingerprint)
+                    throw new MajikKeyError("That mnemonic does not belong to this account");
+                // 3) derive + seal + add
+                const derived = deriveKeys(seed64, toAdd);
+                for (const [id, kp] of derived) {
+                    const slot = {
+                        id,
+                        publicKey: kp.publicKey,
+                        encryptedSecretKey: KeyStore.seal(aesKey, kp.secretKey),
+                        derivation: KEY_ALGORITHMS[id].derivation,
+                        createdAt: new Date().toISOString(),
+                    };
+                    if (this.isUnlocked)
+                        slot.secretKey = kp.secretKey;
+                    else
+                        secureFill.call(kp.secretKey, 0);
+                    this._store.add(slot);
+                }
+                return toAdd;
+            }
+            finally {
+                secureFill.call(aesKey, 0);
+                secureFill.call(seed64, 0);
+                secureFill.call(salt, 0);
+            }
+        }
+        catch (err) {
+            if (err instanceof MajikKeyError)
+                throw err;
+            throw new MajikKeyError("Failed to add keys", err);
         }
     }
     // ── LOCK / UNLOCK ────────────────────────────────────────────────────────────
-    // required
     lock() {
-        // 1. Zeroize raw bytes of all active keys
-        // Apply the secure fill using .call(targetArray, value)
-        if (this._privateKey &&
-            "raw" in this._privateKey &&
-            this._privateKey.raw instanceof Uint8Array) {
-            secureFill.call(this._privateKey.raw, 0);
-        }
-        if (this._mlKemSecretKey)
-            secureFill.call(this._mlKemSecretKey, 0);
-        if (this._edSecretKey)
-            secureFill.call(this._edSecretKey, 0);
-        if (this._mlDsaSecretKey)
-            secureFill.call(this._mlDsaSecretKey, 0);
-        if (this._btcSecretKey)
-            secureFill.call(this._btcSecretKey, 0);
+        this._store.lock();
         if (this._solanaKeypairMaterial) {
             secureFill.call(this._solanaKeypairMaterial.secretKey, 0);
         }
-        this._privateKey = undefined;
-        this._mlKemSecretKey = undefined;
-        this._edSecretKey = undefined;
-        this._mlDsaSecretKey = undefined;
-        this._btcSecretKey = undefined;
         this._solanaKeypairMaterial = undefined;
         return this;
     }
+    /** One KDF run decrypts every key. Atomic: a failure leaves the account fully locked. */
     async unlock(passphrase) {
         try {
             if (this.isUnlocked)
                 throw new MajikKeyError("MajikKey is already unlocked");
             MajikKeyValidator.validatePassphrase(passphrase);
             const salt = new Uint8Array(base64ToArrayBuffer(this._salt));
-            const privateKeyBuffer = await MajikKey._decryptPrivateKey(this._encryptedPrivateKey, passphrase, salt, this._kdfVersion);
-            const privateKey = {
-                type: "private",
-                raw: new Uint8Array(privateKeyBuffer),
-            };
-            this._privateKey = privateKey;
-            if (this._encryptedMlKemSecretKey) {
-                this._mlKemSecretKey = await MajikKey._decryptMlKemSecretKey(this._encryptedMlKemSecretKey, passphrase, salt);
-            }
-            if (this._encryptedEdSecretKey) {
-                this._edSecretKey = await MajikKey._decryptSigningKey(this._encryptedEdSecretKey, passphrase, salt);
-            }
-            if (this._encryptedMlDsaSecretKey) {
-                this._mlDsaSecretKey = await MajikKey._decryptSigningKey(this._encryptedMlDsaSecretKey, passphrase, salt);
+            const primaryKey = await MajikKey._deriveVaultKey(passphrase, salt, this._kdfVersion);
+            let argonKey = this._kdfVersion === KDF_VERSION.ARGON2ID ? primaryKey : undefined;
+            try {
+                if (!argonKey && this._hasNonX25519Blobs())
+                    argonKey = await MajikKey._deriveVaultKey(passphrase, salt, KDF_VERSION.ARGON2ID);
+                this._store.unlock((slot) => slot.id === KeyId.X25519 ? primaryKey : argonKey);
+                return this;
             }
-            if (this._encryptedBtcSecretKey) {
-                this._btcSecretKey = await MajikKey._decryptSigningKey(this._encryptedBtcSecretKey, passphrase, salt);
+            finally {
+                secureFill.call(primaryKey, 0);
+                if (argonKey && argonKey !== primaryKey)
+                    secureFill.call(argonKey, 0);
+                secureFill.call(salt, 0);
             }
-            return this;
         }
         catch (err) {
             if (err instanceof MajikKeyError)
@@ -668,68 +668,26 @@ export class MajikKey {
     async verify(passphrase) {
         try {
             const salt = new Uint8Array(base64ToArrayBuffer(this._salt));
-            await MajikKey._decryptPrivateKey(this._encryptedPrivateKey, passphrase, salt, this._kdfVersion);
-            return true;
+            const key = await MajikKey._deriveVaultKey(passphrase, salt, this._kdfVersion);
+            try {
+                KeyStore.open(key, this._store.slot(KeyId.X25519).encryptedSecretKey, "private key");
+                return true;
+            }
+            finally {
+                secureFill.call(key, 0);
+            }
         }
         catch {
             return false;
         }
     }
-    getPrivateKey() {
-        if (this.isLocked)
-            throw new MajikKeyError("MajikKey is locked. Call unlock() first.");
-        return this._privateKey;
-    }
+    /** @deprecated Use `getPrivateKey(KeyId.X25519)`. */
     getPrivateKeyBase64() {
-        if (this.isLocked)
-            throw new MajikKeyError("MajikKey is locked. Call unlock() first.");
-        return arrayToBase64(this._privateKey.raw);
-    }
-    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;
-    }
-    getEdSecretKey() {
-        if (this.isLocked)
-            throw new MajikKeyError("MajikKey is locked. Call unlock() first.");
-        if (!this._edSecretKey)
-            throw new MajikKeyError("No Ed25519 secret key — re-import via importFromMnemonicBackup() for full migration.");
-        return this._edSecretKey;
-    }
-    getMlDsaSecretKey() {
-        if (this.isLocked)
-            throw new MajikKeyError("MajikKey is locked. Call unlock() first.");
-        if (!this._mlDsaSecretKey)
-            throw new MajikKeyError("No ML-DSA secret key — re-import via importFromMnemonicBackup() for full migration.");
-        return this._mlDsaSecretKey;
+        return arrayToBase64(this._requireSecret(KeyId.X25519));
     }
     /**
      * Executes an operation against an already-unlocked MajikKey and
-     * automatically locks the key when the operation completes.
-     *
-     * The key is always locked after the operation, including when the
-     * operation throws or rejects.
-     *
-     * @param key - An already-unlocked MajikKey instance.
-     * @param operation - Synchronous or asynchronous operation to execute.
-     * @returns The result returned by the operation.
-     *
-     * @throws {MajikKeyError} If the key is locked.
-     * @throws {MajikKeyError} If `operation` is not a function.
-     *
-     * @example
-     * ```ts
-     * await key.unlock(passphrase);
-     *
-     * const signature = await MajikKey.withAutoLock(key, async (key) => {
-     *   return sign(key.getEdSecretKey(), message);
-     * });
-     *
-     * // key.isLocked === true
-     * ```
+     * automatically locks the key when the operation completes (even on throw).
      */
     static async withAutoLock(key, operation) {
         if (!(key instanceof MajikKey)) {
@@ -748,35 +706,66 @@ export class MajikKey {
             key.lock();
         }
     }
+    _hasNonX25519Blobs() {
+        return this._store
+            .ids()
+            .some((id) => id !== KeyId.X25519 && !!this._store.slot(id)?.encryptedSecretKey);
+    }
+    /**
+     * Decrypt every blob under (current passphrase, current salt/KDF), re-encrypt
+     * under (new passphrase, fresh salt, Argon2id), then commit atomically.
+     * Does not need the account to be unlocked and never touches plaintext in memory.
+     */
+    async _reencryptAll(currentPassphrase, newPassphrase) {
+        const oldSalt = new Uint8Array(base64ToArrayBuffer(this._salt));
+        const newSalt = generateRandomBytes(SALT_SIZE);
+        let oldPrimary;
+        let oldArgon;
+        let newKey;
+        try {
+            oldPrimary = await MajikKey._deriveVaultKey(currentPassphrase, oldSalt, this._kdfVersion);
+            oldArgon =
+                this._kdfVersion === KDF_VERSION.ARGON2ID ? oldPrimary : undefined;
+            if (!oldArgon && this._hasNonX25519Blobs())
+                oldArgon = await MajikKey._deriveVaultKey(currentPassphrase, oldSalt, KDF_VERSION.ARGON2ID);
+            newKey = await MajikKey._deriveVaultKey(newPassphrase, newSalt, KDF_VERSION.ARGON2ID);
+            const blobs = this._store.prepareReseal((slot) => (slot.id === KeyId.X25519 ? oldPrimary : oldArgon), newKey);
+            this._store.commitReseal(blobs);
+            this._salt = arrayToBase64(newSalt);
+            this._kdfVersion = KDF_VERSION.ARGON2ID;
+        }
+        finally {
+            if (oldPrimary)
+                secureFill.call(oldPrimary, 0);
+            if (oldArgon && oldArgon !== oldPrimary)
+                secureFill.call(oldArgon, 0);
+            if (newKey)
+                secureFill.call(newKey, 0);
+            secureFill.call(oldSalt, 0);
+        }
+    }
     // ── SERIALIZATION ────────────────────────────────────────────────────────────
-    toJSON() {
+    /**
+     * Serialize (safe at rest: only passphrase-encrypted secrets).
+     * Writes the registry (`keys`) AND, by default, the pre-registry flat fields
+     * for compatibility. Pass `{ legacy: false }` for registry-only output.
+     * (JSON.stringify passes a string here; that is treated as "defaults".)
+     */
+    toJSON(options) {
+        const legacy = !(typeof options === "object" && options?.legacy === false);
         return {
             id: this._id,
             label: this._label,
             publicKey: this._publicKeyBase64,
             fingerprint: this._fingerprint,
-            encryptedPrivateKey: this._encryptedPrivateKeyBase64,
             salt: this._salt,
             backup: this._backup,
             timestamp: this._timestamp.toISOString(),
             kdfVersion: this._kdfVersion,
-            mlKemPublicKey: this._mlKemPublicKey
-                ? arrayToBase64(this._mlKemPublicKey)
-                : undefined,
-            encryptedMlKemSecretKey: this._encryptedMlKemSecretKeyBase64,
-            edPublicKey: this._edPublicKey
-                ? arrayToBase64(this._edPublicKey)
-                : undefined,
-            encryptedEdSecretKey: this._encryptedEdSecretKeyBase64,
-            mlDsaPublicKey: this._mlDsaPublicKey
-                ? arrayToBase64(this._mlDsaPublicKey)
-                : undefined,
-            encryptedMlDsaSecretKey: this._encryptedMlDsaSecretKeyBase64,
-            btcPublicKey: this._btcPublicKey
-                ? arrayToBase64(this._btcPublicKey)
-                : undefined,
-            encryptedBtcSecretKey: this._encryptedBtcSecretKeyBase64,
             mnemonicLanguage: this._mnemonicLanguage,
+            keysVersion: KEYS_VERSION,
+            keys: this._store.toEntries(),
+            ...(legacy ? this._store.toLegacyJSON() : {}),
         };
     }
     toString(pretty = false) {
@@ -810,27 +799,34 @@ export class MajikKey {
             fingerprint: this._fingerprint,
             meta: { label: this._label, ...initialMeta },
             mlKey: arrayToBase64(this.mlKemPublicKey),
-            edPublicKeyBase64: this._edPublicKey
-                ? arrayToBase64(this._edPublicKey)
+            edPublicKeyBase64: this.edPublicKey
+                ? arrayToBase64(this.edPublicKey)
                 : undefined,
-            mlDsaPublicKeyBase64: this._mlDsaPublicKey
-                ? arrayToBase64(this._mlDsaPublicKey)
+            mlDsaPublicKeyBase64: this.mlDsaPublicKey
+                ? arrayToBase64(this.mlDsaPublicKey)
                 : undefined,
         });
     }
     toKeyIdentity() {
         if (this.isLocked)
             throw new MajikKeyError("Cannot convert locked MajikKey to KeyIdentity. Unlock first.");
+        const blob = this._store.slot(KeyId.X25519).encryptedSecretKey;
         return {
             id: this._id,
             publicKey: this._publicKey,
             fingerprint: this._fingerprint,
-            privateKey: this._privateKey,
-            encryptedPrivateKey: this._encryptedPrivateKey,
+            privateKey: { raw: this._requireSecret(KeyId.X25519) },
+            encryptedPrivateKey: blob.slice().buffer,
             salt: this._salt,
             kdfVersion: this._kdfVersion,
-            mlKemPublicKey: this._mlKemPublicKey,
-            mlKemSecretKey: this._mlKemSecretKey,
+            mlKemPublicKey: this.mlKemPublicKey,
+            mlKemSecretKey: this.mlKemSecretKey,
+            edPublicKey: this.edPublicKey,
+            edSecretKey: this._store.peekSecretKey(KeyId.ED25519),
+            mlDsaPublicKey: this.mlDsaPublicKey,
+            mlDsaSecretKey: this._store.peekSecretKey(KeyId.ML_DSA_87),
+            btcPublicKey: this.btcPublicKey,
+            btcSecretKey: this._store.peekSecretKey(KeyId.BTC),
         };
     }
     toSerializedIdentity() {
@@ -840,7 +836,7 @@ export class MajikKey {
             id: this._id,
             publicKey: this._publicKeyBase64,
             fingerprint: this._fingerprint,
-            encryptedPrivateKey: this._encryptedPrivateKeyBase64,
+            encryptedPrivateKey: arrayToBase64(this._store.slot(KeyId.X25519).encryptedSecretKey),
             salt: this._salt,
         };
     }
@@ -857,24 +853,27 @@ export class MajikKey {
         if (this.isLocked)
             throw new MajikKeyError("MajikKey must be unlocked to export backup");
         MajikKeyValidator.validateMnemonic(mnemonic);
-        return MajikKey._exportMnemonicBackup(this.toKeyIdentity(), mnemonic);
+        return MajikKey._exportMnemonicBackup({
+            id: this._id,
+            fingerprint: this._fingerprint,
+            publicRaw: this._publicKey.raw,
+            privateRaw: this._requireSecret(KeyId.X25519),
+        }, mnemonic);
     }
     /**
-     * Import a MajikKey from a mnemonic-encrypted backup.
-     *
+     * Import a MajikKey from a mnemonic-encrypted backup. Re-derives the account
+     * from the mnemonic: the core four (plus `options.keys`) under a new passphrase.
      */
-    static async importFromMnemonicBackup(backup, mnemonic, passphrase, label, options = {
-        deriveBitcoin: true,
-        mnemonicLanguage: "en",
-    }) {
+    static async importFromMnemonicBackup(backup, mnemonic, passphrase, label, options = {}) {
         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 { deriveBitcoin, mnemonicLanguage } = options;
-            const wordlist = await MajikKey._getWordlist(mnemonicLanguage || "en");
+            const mnemonicLanguage = options.mnemonicLanguage || "en";
+            const ids = MajikKey._resolveCreateKeys(options);
+            const wordlist = await MajikKey._getWordlist(mnemonicLanguage);
             if (!validateMnemonic(mnemonic, wordlist)) {
                 throw new MajikKeyError("Invalid BIP39 mnemonic phrase");
             }
@@ -889,43 +888,18 @@ export class MajikKey {
             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, { deriveBitcoin: deriveBitcoin });
-            const privateKeyBase64 = await MajikKey._exportKeyToBase64(identity.privateKey);
-            const publicKeyBase64 = await MajikKey._exportKeyToBase64(identity.publicKey);
-            const id = parsed.id || identity.id;
+            await MajikKey._verifyBackupDecryption(parsed.iv, parsed.ciphertext, mnemonic, backupKdfVersion, parsed.backupSaltVersion);
+            const d = await MajikKey._deriveFromMnemonic(mnemonic, passphrase, ids);
             return new MajikKey({
-                id,
-                publicKey: identity.publicKey,
-                publicKeyBase64,
-                fingerprint: identity.fingerprint,
-                encryptedPrivateKey: identity.encryptedPrivateKey,
-                encryptedPrivateKeyBase64: arrayBufferToBase64(identity.encryptedPrivateKey),
-                salt: identity.salt,
+                id: parsed.id || d.fingerprint,
+                fingerprint: d.fingerprint,
+                salt: d.salt,
                 backup,
                 label: label || "",
                 timestamp: new Date(),
                 kdfVersion: KDF_VERSION.ARGON2ID,
-                mlKemPublicKey: identity.mlKemPublicKey,
-                mlKemSecretKey: identity.mlKemSecretKey,
-                encryptedMlKemSecretKey: identity.encryptedMlKemSecretKey,
-                encryptedMlKemSecretKeyBase64: arrayBufferToBase64(identity.encryptedMlKemSecretKey),
-                privateKey: identity.privateKey,
-                edPublicKey: identity.edPublicKey,
-                encryptedEdSecretKey: identity.encryptedEdSecretKey,
-                encryptedEdSecretKeyBase64: arrayBufferToBase64(identity.encryptedEdSecretKey),
-                mlDsaPublicKey: identity.mlDsaPublicKey,
-                encryptedMlDsaSecretKey: identity.encryptedMlDsaSecretKey,
-                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, // fix: previously dropped, silently resetting to "en"
+                store: d.store,
             });
         }
         catch (err) {
@@ -934,138 +908,68 @@ export class MajikKey {
             throw new MajikKeyError("Failed to import from mnemonic backup", err);
         }
     }
-    // ── PRIVATE: Core Derivation ─────────────────────────────────────────────────
+    // ── PRIVATE: derivation + vault crypto ───────────────────────────────────────
     static async _getWordlist(language) {
+        const supported = [
+            "en",
+            "fr",
+            "es",
+            "it",
+            "ja",
+            "ko",
+            "czech",
+            "pt",
+            "zh-cn",
+            "zh-tw",
+        ];
+        if (!supported.includes(language)) {
+            throw new MajikKeyError(`Unsupported language: ${String(language)}`);
+        }
         const loader = WORDLISTS[language] ?? WORDLISTS.en;
         const mod = await loader();
         return mod.wordlist;
     }
     /**
-     * @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`.
+     * Derive `ids` from the mnemonic and seal each secret under ONE Argon2id
+     * key (single salt, single KDF run). Returns an UNLOCKED store.
      */
-    static async _deriveAndEncryptFromMnemonic(mnemonic, passphrase, options) {
-        const deriveBitcoin = options?.deriveBitcoin ?? true;
-        const encIdentity = await EncryptionEngine.deriveIdentityFromMnemonic(mnemonic);
-        const anyPriv = encIdentity.privateKey;
-        const exportedXPrivate = anyPriv.raw.buffer.slice(anyPriv.raw.byteOffset, anyPriv.raw.byteOffset + anyPriv.raw.byteLength);
-        // 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);
-        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);
+    static async _deriveFromMnemonic(mnemonic, passphrase, ids) {
+        const seed64 = await mnemonicToSeed(mnemonic);
+        let derived;
+        try {
+            derived = deriveKeys(seed64, ids);
         }
-        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,
-            edPublicKey: encIdentity.edPublicKey,
-            edSecretKey,
-            encryptedEdSecretKey,
-            mlDsaPublicKey: encIdentity.mlDsaPublicKey,
-            mlDsaSecretKey,
-            encryptedMlDsaSecretKey,
-            btcPublicKey,
-            btcSecretKey,
-            encryptedBtcSecretKey,
-        };
-    }
-    // ── PRIVATE: Encryption/Decryption ───────────────────────────────────────────
-    static async _encryptPrivateKey(buffer, passphrase, salt) {
-        const keyBytes = await 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,
-        };
-    }
-    /**
-     * 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 _encryptMlKemSecretKey(mlKemSecretKey, passphrase, salt) {
-        const keyBytes = await 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 _encryptSigningKey(keyBytes_, passphrase, salt) {
-        const aesKey = await deriveKeyFromPassphraseArgon2(passphrase, salt);
-        const iv = generateRandomBytes(IV_LENGTH);
-        const ciphertext = aesGcmEncrypt(aesKey, iv, keyBytes_);
-        return concatUint8Arrays(iv, ciphertext).buffer;
-    }
-    static async _decryptPrivateKey(buffer, passphrase, salt, kdfVersion = KDF_VERSION.PBKDF2) {
-        const keyBytes = kdfVersion === KDF_VERSION.ARGON2ID
-            ? await 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 = await 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;
-    }
-    static async _decryptSigningKey(buffer, passphrase, salt) {
-        const keyBytes = await deriveKeyFromPassphraseArgon2(passphrase, salt);
+        finally {
+            secureFill.call(seed64, 0);
+        }
+        const salt = generateRandomBytes(SALT_SIZE);
+        const aesKey = await MajikKey._deriveVaultKey(passphrase, salt);
         try {
-            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 signing key");
-            return plain;
+            const store = KeyStore.fromDerived(derived, aesKey);
+            const x = derived.get(KeyId.X25519);
+            return {
+                store,
+                salt: arrayToBase64(salt),
+                fingerprint: fingerprintFromPublicRaw(x.publicKey),
+                xPublic: x.publicKey,
+                xSecret: x.secretKey,
+            };
         }
         finally {
-            secureFill.call(keyBytes, 0);
+            secureFill.call(aesKey, 0);
         }
     }
+    /** One KDF run. kdfVersion 1 = legacy PBKDF2 (X25519 blob of old accounts only). */
+    static async _deriveVaultKey(passphrase, salt, kdfVersion = KDF_VERSION.ARGON2ID) {
+        return kdfVersion === KDF_VERSION.ARGON2ID
+            ? deriveKeyFromPassphraseArgon2(passphrase, salt)
+            : deriveKeyFromPassphrase(passphrase, salt);
+    }
     // ── PRIVATE: Backup ──────────────────────────────────────────────────────────
-    static async _verifyBackupDecryption(ivBase64, ciphertextBase64, mnemonic, backupKdfVersion) {
+    static async _verifyBackupDecryption(ivBase64, ciphertextBase64, mnemonic, backupKdfVersion, backupSaltVersion) {
         const iv = new Uint8Array(base64ToArrayBuffer(ivBase64));
         const ciphertext = base64ToArrayBuffer(ciphertextBase64);
-        const mnemonicSalt = new TextEncoder().encode(MAJIK_MNEMONIC_SALT);
+        const mnemonicSalt = new TextEncoder().encode(backupSaltFor(backupSaltVersion));
         if (backupKdfVersion === KDF_VERSION.ARGON2ID) {
             const keyBytes = await deriveKeyFromMnemonicArgon2(mnemonic, mnemonicSalt);
             const plain = aesGcmDecrypt(keyBytes, iv, new Uint8Array(ciphertext));
@@ -1073,6 +977,7 @@ export class MajikKey {
                 throw new MajikKeyError("Failed to decrypt backup — invalid mnemonic or corrupted data");
         }
         else {
+            // PBKDF2 backups predate salt versioning: always the legacy salt.
             const legacyKey = await MajikKey._deriveLegacyMnemonicKey(mnemonic);
             try {
                 await crypto.subtle.decrypt({ name: "AES-GCM", iv }, legacyKey, ciphertext);
@@ -1083,49 +988,26 @@ export class MajikKey {
         }
     }
     static async _exportMnemonicBackup(identity, mnemonic) {
-        if (!identity?.privateKey)
-            throw new MajikKeyError("Identity must have privateKey to export backup");
-        const anyPriv = identity.privateKey;
-        const anyPub = identity.publicKey;
-        const privRawBuf = anyPriv.raw.buffer.slice(anyPriv.raw.byteOffset, anyPriv.raw.byteOffset + anyPriv.raw.byteLength);
-        const pubRawBuf = anyPub.raw.buffer.slice(anyPub.raw.byteOffset, anyPub.raw.byteOffset + anyPub.raw.byteLength);
-        const mnemonicSalt = new TextEncoder().encode(MAJIK_MNEMONIC_SALT);
+        const mnemonicSalt = new TextEncoder().encode(backupSaltFor(BACKUP_SALT_WRITE_VERSION));
         const keyBytes = await deriveKeyFromMnemonicArgon2(mnemonic, mnemonicSalt);
         const iv = generateRandomBytes(IV_LENGTH);
-        const ciphertext = aesGcmEncrypt(keyBytes, iv, new Uint8Array(privRawBuf));
+        const ciphertext = aesGcmEncrypt(keyBytes, iv, identity.privateRaw);
         return utf8ToBase64(JSON.stringify({
             id: identity.id,
             iv: arrayToBase64(iv),
             ciphertext: arrayToBase64(ciphertext),
-            publicKey: arrayBufferToBase64(pubRawBuf),
+            publicKey: arrayToBase64(identity.publicRaw),
             fingerprint: identity.fingerprint,
             backupKdfVersion: KDF_VERSION.ARGON2ID,
+            backupSaltVersion: BACKUP_SALT_WRITE_VERSION,
         }));
     }
     static async _deriveLegacyMnemonicKey(mnemonic) {
-        const salt = new TextEncoder().encode(MAJIK_MNEMONIC_SALT);
+        const salt = new TextEncoder().encode(LEGACY_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"]);
     }
-    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);
-    }
     // ── WEB3 (EXPERIMENTAL) ─────────────────────────────────────────────────────
-    /**
-     * @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
      */
@@ -1133,8 +1015,19 @@ export class MajikKey {
         if (!this.hasSolanaKeypair)
             return undefined;
         const solanaMaterial = this._getOrDeriveSolanaMaterial();
-        const btcMaterial = this._btcSecretKey && this._btcPublicKey
-            ? { privateKey: this._btcSecretKey, publicKey: this._btcPublicKey }
+        const btcSecret = this._store.peekSecretKey(KeyId.BTC);
+        const btcMaterial = btcSecret && this._store.has(KeyId.BTC)
+            ? {
+                privateKey: btcSecret,
+                publicKey: this._store.getPublicKey(KeyId.BTC),
+            }
+            : undefined;
+        const ethSecret = this._store.peekSecretKey(KeyId.ETH);
+        const ethMaterial = ethSecret && this._store.has(KeyId.ETH)
+            ? {
+                privateKey: ethSecret,
+                publicKey: this._store.getPublicKey(KeyId.ETH),
+            }
             : undefined;
         return {
             solana: {
@@ -1152,42 +1045,39 @@ export class MajikKey {
                 getWIF: (options) => toWIF(btcMaterial, options),
                 sign: (hash, scheme) => signWithBitcoinMaterial(btcMaterial, hash, scheme),
             },
+            ethereum: ethMaterial && {
+                publicKey: ethMaterial.publicKey,
+                privateKey: ethMaterial.privateKey,
+                address: ethereumAddressFromPublicKey(ethMaterial.publicKey),
+                getPrivateKeyHex: () => toEthereumPrivateKeyHex(ethMaterial),
+                signHash: (hash32) => signEthereumHash(ethMaterial, hash32),
+                signMessage: (message) => signEthereumMessage(ethMaterial, message),
+            },
         };
     }
-    // ── BITCON (EXPERIMENTAL)  ────────────────────────────────────
-    /**
-     * @experimental True if this MajikKey can currently produce Bitcoin
-     * material (i.e. it's unlocked and has a Bitcoin secret key).
-     */
+    // ── BITCOIN (EXPERIMENTAL) ──────────────────────────────────────────────────
+    /** @experimental True if this MajikKey can currently produce Bitcoin material (unlocked + has a Bitcoin key). */
     get hasBitcoinKeypair() {
-        return this.isUnlocked && this._btcSecretKey !== undefined;
+        return this._store.peekSecretKey(KeyId.BTC) !== 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.
+     * @experimental Raw Bitcoin keypair material for the stored (domain-separated)
+     * key. The REAL BIP-84 key needs the mnemonic:
+     * use `MajikKey.deriveStandardBitcoinFromMnemonic(mnemonic)`.
      */
     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 };
+            return {
+                privateKey: this.getBtcSecretKey(),
+                publicKey: this._store.getPublicKey(KeyId.BTC),
+            };
         }
         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.
-     */
+    /** @experimental Derive the REAL BIP-84 mainnet Bitcoin keypair straight from a mnemonic. */
     static async deriveStandardBitcoinFromMnemonic(mnemonic, mnemonicLanguage = "en") {
         MajikKeyValidator.validateMnemonic(mnemonic);
         const wordlist = await MajikKey._getWordlist(mnemonicLanguage);
@@ -1197,55 +1087,61 @@ export class MajikKey {
         const seed = await mnemonicToSeed(mnemonic);
         return deriveBitcoinKeypairFromSeed(seed, { standard: true });
     }
-    /**
-     * @experimental WIF export of the default (domain-separated) Bitcoin key.
-     */
+    /** @experimental WIF export of the stored (domain-separated) Bitcoin key. */
     getBitcoinWIF(options) {
-        const material = this.getBitcoinKeypairMaterial();
-        return toWIF(material, options);
+        return toWIF(this.getBitcoinKeypairMaterial(), options);
+    }
+    // ── ETHEREUM (EXPERIMENTAL) ─────────────────────────────────────────────────
+    /** @experimental True if this account has a stored Ethereum key (works while locked). */
+    get hasEthereum() {
+        return this._store.has(KeyId.ETH);
     }
-    // ── SOLANA (EXPERIMENTAL)  ────────────────────────────────────
     /**
-     * @experimental True if this MajikKey can currently produce a Solana
-     * keypair (i.e. it's unlocked and has an Ed25519 signing key).
+     * @experimental EIP-55 Ethereum address (standard m/44'/60'/0'/0/0 — the same
+     * address MetaMask shows for this mnemonic). Public-only, so it works while locked.
      */
+    getEthereumAddress() {
+        if (!this._store.has(KeyId.ETH))
+            throw new MajikKeyError("No Ethereum key — add it with addKeys([KeyId.ETH], mnemonic, passphrase).");
+        return ethereumAddressFromPublicKey(this._store.getPublicKey(KeyId.ETH));
+    }
+    /** @experimental Raw Ethereum keypair material. Requires an unlocked account. */
+    getEthereumKeypairMaterial() {
+        return {
+            privateKey: this._requireSecret(KeyId.ETH),
+            publicKey: this._store.getPublicKey(KeyId.ETH),
+        };
+    }
+    /** @experimental 0x-prefixed private key hex, for wallet "import private key". */
+    getEthereumPrivateKeyHex() {
+        return toEthereumPrivateKeyHex(this.getEthereumKeypairMaterial());
+    }
+    // ── SOLANA (EXPERIMENTAL) ───────────────────────────────────────────────────
+    /** @experimental True if this MajikKey can currently produce a Solana keypair (unlocked + has Ed25519). */
     get hasSolanaKeypair() {
-        return this.isUnlocked && this._edSecretKey !== undefined;
+        return this._store.peekSecretKey(KeyId.ED25519) !== undefined;
     }
     _getOrDeriveSolanaMaterial() {
-        if (!this._edSecretKey)
+        const ed = this._store.peekSecretKey(KeyId.ED25519);
+        if (!ed)
             throw new MajikKeyError("No Ed25519 secret key — MajikKey must be unlocked and have signing keys.");
         if (!this._solanaKeypairMaterial) {
-            this._solanaKeypairMaterial = deriveSolanaKeypairFromEdSecretKey(this._edSecretKey);
+            this._solanaKeypairMaterial = deriveSolanaKeypairFromEdSecretKey(ed);
         }
         return this._solanaKeypairMaterial;
     }
-    /**
-     * @experimental Raw Solana keypair material (public/secret key bytes).
-     * Pass `{ reuseMessageKey: true }` to reuse the MajikKey's message signing
-     * Ed25519 key directly instead of the domain-separated derivation.
-     */
+    /** @experimental Raw Solana keypair material. `reuseMessageKey: true` reuses the message-signing Ed25519 key. */
     getSolanaKeypairMaterial(options) {
-        if (this.isLocked)
-            throw new MajikKeyError("MajikKey is locked. Call unlock() first.");
-        if (!this._edSecretKey)
-            throw new MajikKeyError("No Ed25519 secret key — re-import via importFromMnemonicBackup() first.");
-        if (options?.reuseMessageKey) {
-            return solanaMaterialFromEd25519SecretKey(this._edSecretKey);
-        }
+        const ed = this._requireSecret(KeyId.ED25519, "No Ed25519 secret key — add it with addKeys() (requires the mnemonic).");
+        if (options?.reuseMessageKey)
+            return solanaMaterialFromEd25519SecretKey(ed);
         return this._getOrDeriveSolanaMaterial();
     }
-    /**
-     * @experimental Real @solana/kit Keypair instance. Lazily loads
-     * @solana/kit — throws a MajikKeyError with install instructions if
-     * it isn't present in the consuming project.
-     */
+    /** @experimental Real @solana/kit Keypair instance (lazy-loads @solana/kit). */
     async getSolanaKeypair(options) {
         return toSolanaKeyPairSigner(this.getSolanaKeypairMaterial(options));
     }
-    /**
-     * @experimental Base58 Solana address. Does NOT require @solana/kit.
-     */
+    /** @experimental Base58 Solana address. Does NOT require @solana/kit. */
     getSolanaAddress(options) {
         return solanaAddressFromPublicKey(this.getSolanaKeypairMaterial(options).publicKey);
     }