@majikah/majik-key 0.7.0 → 1.0.0

package/dist/majik-key.d.ts

@@ -2,104 +2,70 @@
  * 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 { MajikContact, MajikContactData, MajikContactMeta } from "@majikah/majik-contact";
-import { KDF_VERSION } from "./core/crypto/constants";
-import type { BitcoinRawPublicKey, ED25519RawPublicKey, MajikKeyAddress, MajikKeyDangerousJSON, MajikKeyFingerprint, MajikKeyJSON, MajikKeyMetadata, MLDSA87RawPublicKey, MLKEM768RawPublicKey, MnemonicJSON, X25519RawKey } from "./core/types";
-import { MajikMessageIdentity } from "./core/database/system/identity";
-import { MajikUser } from "@thezelijah/majik-user";
-import { MnemonicLanguage } from "./core/crypto/wordlist";
-import { MajikKeyWeb3Namespace, BitcoinDerivationOptions, BitcoinKeypairMaterial, SolanaKeypairMaterial } from "./core/web3";
+import { MajikContactData, MajikContactMeta } from "@majikah/majik-contact/dist/types.js";
+import { MajikContact } from "@majikah/majik-contact/dist/contacts/majik-contact.js";
+import { KDF_VERSION } from "./core/crypto/constants.js";
+import type { BitcoinRawPublicKey, ED25519RawPublicKey, MajikKeyAddress, MajikKeyDangerousJSON, MajikKeyFingerprint, MajikKeyJSON, MajikKeyMetadata, MLDSA87RawPublicKey, MLKEM768RawPublicKey, MnemonicJSON, X25519RawKey } from "./core/types.js";
+import { MajikMessageIdentity } from "./core/database/system/identity.js";
+import { MajikUser } from "@thezelijah/majik-user/dist/core/majik-user.js";
+import { MnemonicLanguage } from "./core/crypto/wordlist.js";
+import { MajikKeyWeb3Namespace, BitcoinDerivationOptions, BitcoinKeypairMaterial, SolanaKeypairMaterial, EthereumKeypairMaterial } from "./core/web3/index.js";
+import { KeyFamily, KeyId } from "./core/keys/key-id.js";
+import { KeyInfo, 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";
+export type { KeyInfo } from "./core/keys/keypair-handle.js";
 /**
- * In-memory identity bundle for an *unlocked* MajikKey — the raw CryptoKey/
- * Uint8Array material, not the encrypted-at-rest form. This is what
- * `toKeyIdentity()` returns, and what backup export starts from.
- *
- * `mlKemPublicKey`/`mlKemSecretKey` are required here because every account
- * (even ones mid-migration) is expected to carry ML-KEM material by the time
- * this shape is used. `ed*`, `mlDsa*`, and `btc*` are optional because
- * accounts imported before those key types existed may not have them yet —
- * check `hasSigningKeys` / `hasBitcoin` on the `MajikKey` instance before
- * relying on them.
+ * In-memory identity bundle for an *unlocked* MajikKey. Returned by
+ * `toKeyIdentity()`. Kept for backward compatibility; prefer the registry
+ * accessors (`getKeypair()`, `getPublicKey()`, `getPrivateKey(id)`).
  */
 export interface MajikKeyIdentity {
-    /** Account identifier. Equal to `fingerprint` for accounts created by this library. */
     id: MajikKeyFingerprint;
-    /** X25519 public key */
     publicKey: X25519RawKey;
-    /** SHA-256 fingerprint of `publicKey`. */
     fingerprint: MajikKeyFingerprint;
-    /** X25519 private key, decrypted into memory. ⚠️ Live key material — do not log or serialize directly. */
     privateKey: X25519RawKey;
-    /** AES-256-GCM-encrypted X25519 private key (IV + ciphertext), as stored at rest. */
     encryptedPrivateKey: ArrayBuffer;
-    /** Random salt used to derive the passphrase-based encryption key. Base64. */
     salt: string;
-    /** KDF used to encrypt the keys on this identity: `1` = legacy PBKDF2, `2` = Argon2id. */
     kdfVersion: KDF_VERSION;
-    /** ML-KEM-768 (FIPS-203) public key. Post-quantum key encapsulation. */
     mlKemPublicKey: Uint8Array;
-    /** ML-KEM-768 secret key, decrypted into memory. ⚠️ Live key material. */
     mlKemSecretKey?: Uint8Array;
-    /** Ed25519 public key. Classical signing — same keypair the X25519 identity key is converted from. */
     edPublicKey?: Uint8Array;
-    /** Ed25519 secret key, decrypted into memory. ⚠️ Live key material. */
     edSecretKey?: Uint8Array;
-    /** ML-DSA-87 (FIPS-204) public key. Post-quantum signing. */
     mlDsaPublicKey?: Uint8Array;
-    /** ML-DSA-87 secret key, decrypted into memory. ⚠️ Live key material. */
     mlDsaSecretKey?: Uint8Array;
-    /** @experimental secp256k1 Bitcoin public key. Domain-separated BIP-32/84 derivation by default. */
+    /** @experimental */
     btcPublicKey?: Uint8Array;
-    /** @experimental Bitcoin private key, decrypted into memory. ⚠️ Live key material. */
+    /** @experimental */
     btcSecretKey?: Uint8Array;
 }
-/**
- * `MajikKeyIdentity` immediately after fresh derivation from a mnemonic —
- * i.e. what `create()` and `importFromMnemonicBackup()` produce internally,
- * before the result is wrapped into a `MajikKey` instance.
- *
- * Unlike the base `MajikKeyIdentity`, every `encrypted*` field here is
- * required: a fresh derivation always re-derives and re-encrypts the full
- * key set (ML-KEM, Ed25519, ML-DSA, and Bitcoin) in one pass, so there's no
- * "partially migrated" state at this point in the flow.
- */
+/** @deprecated Pre-registry shape. No longer produced; kept so existing type imports keep compiling. */
 export type MajikKeyDerivedIdentity = MajikKeyIdentity & {
-    /** AES-256-GCM-encrypted ML-KEM-768 secret key, freshly re-encrypted. */
     encryptedMlKemSecretKey: ArrayBuffer;
-    /** AES-256-GCM-encrypted Ed25519 secret key, freshly re-encrypted. */
     encryptedEdSecretKey: ArrayBuffer;
-    /** AES-256-GCM-encrypted ML-DSA-87 secret key, freshly re-encrypted. */
     encryptedMlDsaSecretKey: ArrayBuffer;
-    /** @experimental AES-256-GCM-encrypted Bitcoin secret key, freshly re-encrypted. */
     encryptedBtcSecretKey?: ArrayBuffer;
 };
-/**
- * Minimal identity export — just enough to identify the account and, if
- * present, re-derive access to it. Lighter than `MajikKeyJSON`: no ML-KEM,
- * Ed25519, ML-DSA, or Bitcoin fields at all. Produced by
- * `toSerializedIdentity()` (unlocked keys only).
- */
 export interface SerializedIdentity {
     id: string;
-    /** X25519 public key, base64. */
     publicKey: MajikKeyAddress;
     fingerprint: MajikKeyFingerprint;
-    /** AES-256-GCM-encrypted X25519 private key, base64. Omitted in some contexts — check before use. */
     encryptedPrivateKey?: string;
-    /** Base64 salt paired with `encryptedPrivateKey`. Omitted in some contexts — check before use. */
     salt?: string;
 }
-/**
- * Internal constructor payload for `MajikKey` — every static factory
- * (`create()`, `fromJSON()`, `fromDangerousJSON()`, `importFromMnemonicBackup()`,
- * etc.) builds one of these and passes it to the private constructor.
- *
- * You won't normally build this by hand; it's exported mainly for type
- * inference around the factory methods. Fields mirror `MajikKeyJSON` plus
- * the live (decrypted) counterparts where a factory is constructing an
- * already-unlocked instance.
- */
+/** @deprecated Pre-registry constructor payload. The constructor now takes a KeyStore. */
 export interface MajikKeyConstructorOptions {
     id: string;
     publicKey: X25519RawKey;
@@ -108,18 +74,14 @@ export interface MajikKeyConstructorOptions {
     encryptedPrivateKey: ArrayBuffer;
     encryptedPrivateKeyBase64: string;
     salt: string;
-    /** Encrypted mnemonic-verification blob — see `MajikKeyJSON.backup`. */
     backup: string;
     label?: string;
     timestamp?: Date;
-    /** Defaults to legacy PBKDF2 (`KDF_VERSION.PBKDF2`) if omitted — see the private constructor. */
     kdfVersion?: KDF_VERSION;
     mlKemPublicKey: MLKEM768RawPublicKey;
-    /** Present only when constructing an already-unlocked instance. ⚠️ Live key material. */
     mlKemSecretKey?: Uint8Array;
     encryptedMlKemSecretKey?: ArrayBuffer;
     encryptedMlKemSecretKeyBase64?: string;
-    /** Present only when constructing an already-unlocked instance. ⚠️ Live key material. */
     privateKey?: X25519RawKey;
     edPublicKey?: ED25519RawPublicKey;
     encryptedEdSecretKey?: ArrayBuffer;
@@ -127,42 +89,38 @@ export interface MajikKeyConstructorOptions {
     mlDsaPublicKey?: MLDSA87RawPublicKey;
     encryptedMlDsaSecretKey?: ArrayBuffer;
     encryptedMlDsaSecretKeyBase64?: string;
-    /** Present only when constructing an already-unlocked instance. ⚠️ Live key material. */
     edSecretKey?: Uint8Array;
-    /** Present only when constructing an already-unlocked instance. ⚠️ Live key material. */
     mlDsaSecretKey?: Uint8Array;
-    /** @experimental secp256k1 Bitcoin public key. */
     btcPublicKey?: BitcoinRawPublicKey;
-    /** @experimental AES-256-GCM-encrypted Bitcoin private key. */
     encryptedBtcSecretKey?: ArrayBuffer;
-    /** @experimental Base64 form of `encryptedBtcSecretKey`. */
     encryptedBtcSecretKeyBase64?: string;
-    /** @experimental Present only when constructing an already-unlocked instance. ⚠️ Live key material. */
     btcSecretKey?: Uint8Array;
     mnemonicLanguage?: MnemonicLanguage;
 }
+/** Options for create(), fromMnemonicJSON() and importFromMnemonicBackup(). */
+export interface MajikKeyCreateOptions {
+    mnemonicLanguage?: MnemonicLanguage;
+    /**
+     * Extra keypairs to create ON TOP of the core four (always included).
+     * Defaults to none. e.g. `keys: [KeyId.BTC]`.
+     */
+    keys?: KeyId[];
+    /** @deprecated Use `keys: [KeyId.BTC]`. `true` adds `web3:btc`; omitted/false no longer derives it. */
+    deriveBitcoin?: boolean;
+}
+export interface MajikKeyToJSONOptions {
+    /**
+     * Also write the pre-registry flat fields (`encryptedMlKemSecretKey`, …)
+     * so older library versions / the Rust port can read the export.
+     * Defaults to TRUE in this release; planned to flip to false in the next major.
+     */
+    legacy?: boolean;
+}
 /**
  * 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 declare class MajikKey {
     private readonly _id;
@@ -172,187 +130,162 @@ export declare class MajikKey {
     private readonly _backup;
     private readonly _timestamp;
     private readonly _mnemonicLanguage;
-    private _encryptedPrivateKey;
-    private _encryptedPrivateKeyBase64;
+    private readonly _store;
     private _salt;
     private _label;
     private _kdfVersion;
-    private _mlKemPublicKey;
-    private _mlKemSecretKey?;
-    private _encryptedMlKemSecretKey?;
-    private _encryptedMlKemSecretKeyBase64?;
-    private _privateKey?;
-    private _edPublicKey?;
-    private _edSecretKey?;
-    private _encryptedEdSecretKey?;
-    private _encryptedEdSecretKeyBase64?;
-    private _mlDsaPublicKey?;
-    private _mlDsaSecretKey?;
-    private _encryptedMlDsaSecretKey?;
-    private _encryptedMlDsaSecretKeyBase64?;
-    /**
-     * @experimental
-     */
+    /** @experimental derived view over classic:ed25519; cached while unlocked */
     private _solanaKeypairMaterial?;
-    /**
-     * @experimental
-     */
-    private _btcPublicKey?;
-    /**
-     * @experimental
-     */
-    private _btcSecretKey?;
-    /**
-     * @experimental
-     */
-    private _encryptedBtcSecretKey?;
-    /**
-     * @experimental
-     */
-    private _encryptedBtcSecretKeyBase64?;
     private constructor();
-    /** Account identifier. Equal to `fingerprint` for accounts created by this library. */
     get id(): MajikKeyFingerprint;
-    /** SHA-256 fingerprint of the X25519 public key. Stable identity anchor for the account. */
     get fingerprint(): MajikKeyFingerprint;
     /** X25519 public key. Always available, even when locked. */
     get publicKey(): X25519RawKey;
-    /** X25519 public key, base64-encoded. Always available, even when locked. */
     get publicKeyBase64(): MajikKeyAddress;
-    /** Human-readable, user-editable account name. Update via `updateLabel()`. */
     get label(): string;
-    /** BIP-39 wordlist language this account's mnemonic was generated/validated against. */
     get mnemonicLanguage(): 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(): string;
-    /** Account creation time. */
     get timestamp(): Date;
-    /** KDF currently protecting every `encrypted*` field on this account: `1` = legacy PBKDF2, `2` = Argon2id. */
     get kdfVersion(): KDF_VERSION;
-    /** `true` if this account is on the current KDF (Argon2id). `false` means it's still on legacy PBKDF2 — see `migrate()` or `importFromMnemonicBackup()`. */
     get isArgon2id(): boolean;
-    /** `true` if private key material is currently purged from memory (i.e. `lock()` was called, or `unlock()` hasn't been called yet). */
     get isLocked(): boolean;
-    /** `true` if private key material is currently decrypted in memory. The inverse of `isLocked`. */
     get isUnlocked(): boolean;
-    /** ML-KEM-768 (FIPS-203) public key. Post-quantum key encapsulation. Always available, even when locked. */
-    get mlKemPublicKey(): MLKEM768RawPublicKey;
-    /** 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(): Uint8Array | undefined;
-    /** `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(): boolean;
-    /** `true` if this account is on Argon2id *and* has ML-KEM-768 keys — i.e. fully migrated, nothing left to upgrade. */
+    /** `true` if this account holds every key in CORE_KEYS. Legacy accounts may not — see `missingKeys()` / `addKeys()`. */
+    get isCoreComplete(): boolean;
+    /** `true` if this account is on Argon2id *and* has ML-KEM-768 keys. */
     get isFullyUpgraded(): boolean;
+    /** Is this key present on the account? Works while locked. Derived views (web3:sol) count when their source key exists. */
+    hasKey(id: KeyId): boolean;
+    hasKeys(ids: readonly KeyId[]): boolean;
+    /** Which of `ids` (default: the core four) are NOT on this account. */
+    missingKeys(ids?: readonly KeyId[]): KeyId[];
+    /** Namespaced ids of every key available on this account, in canonical order. */
+    availableKeys(options?: {
+        family?: KeyFamily;
+    }): KeyId[];
+    /** Metadata for every available key. No secret material. */
+    listKeys(): KeyInfo[];
+    /** Every algorithm id this library version can create/enable. */
+    static supportedKeys(): KeyId[];
+    /** Public key bytes for `id`. Works while locked (derived views need an unlocked account). */
+    getPublicKey(id: KeyId): Uint8Array;
     /**
-     * @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(): BitcoinRawPublicKey | undefined;
-    /** @experimental `true` if this account has a stored Bitcoin keypair. */
-    get hasBitcoin(): boolean;
-    /**
-     * 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.
+     * With no argument: the X25519 private key wrapper.
+     * @deprecated The no-argument form. Use `getPrivateKey(KeyId.X25519)`.
      */
-    get metadata(): MajikKeyMetadata;
-    /** Ed25519 public key. Classical signing — same keypair the X25519 identity key is converted from. Always available, even when locked. */
+    getPrivateKey(): X25519RawKey;
+    /** Secret key bytes for `id`. Throws if locked or absent. ⚠️ Live key material. */
+    getPrivateKey(id: KeyId): Uint8Array;
+    /** A live handle with `.public` / `.private` / `.publicBase64`. Reads through to the account, so it never goes stale across lock(). */
+    getKeypair(id: KeyId): MajikKeypair;
+    private _requireSecret;
+    /** @deprecated Use `getPublicKey(KeyId.ML_KEM_768)`. */
+    get mlKemPublicKey(): MLKEM768RawPublicKey;
+    /** @deprecated Use `getPrivateKey(KeyId.ML_KEM_768)`. */
+    get mlKemSecretKey(): Uint8Array | undefined;
+    /** @deprecated Use `hasKey(KeyId.ML_KEM_768)`. */
+    get hasMlKem(): boolean;
+    /** @deprecated Use `getPublicKey(KeyId.ED25519)`. */
     get edPublicKey(): ED25519RawPublicKey | undefined;
-    /** ML-DSA-87 (FIPS-204) public key. Post-quantum signing. Always available, even when locked. */
+    /** @deprecated Use `getPublicKey(KeyId.ML_DSA_87)`. */
     get mlDsaPublicKey(): MLDSA87RawPublicKey | undefined;
-    /** `true` if this account has both Ed25519 and ML-DSA-87 signing keys. `false` means it's a legacy account pending migration. */
+    /** @deprecated Use `hasKeys([KeyId.ED25519, KeyId.ML_DSA_87])`. */
     get hasSigningKeys(): boolean;
+    /** @experimental @deprecated Use `getPublicKey(KeyId.BTC)`. */
+    get btcPublicKey(): BitcoinRawPublicKey | undefined;
+    /** @experimental @deprecated Use `hasKey(KeyId.BTC)`. */
+    get hasBitcoin(): boolean;
+    /** @deprecated Use `getPrivateKey(KeyId.ML_KEM_768)`. */
+    getMlKemSecretKey(): Uint8Array;
+    /** @deprecated Use `getPrivateKey(KeyId.ED25519)`. */
+    getEdSecretKey(): Uint8Array;
+    /** @deprecated Use `getPrivateKey(KeyId.ML_DSA_87)`. */
+    getMlDsaSecretKey(): Uint8Array;
+    /** @experimental @deprecated Use `getPrivateKey(KeyId.BTC)`. */
+    getBtcSecretKey(): Uint8Array;
+    /** Non-secret snapshot of this account's state. */
+    get metadata(): MajikKeyMetadata;
     /**
-     * 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 create(mnemonic: string, passphrase: string, label?: string, options?: MajikKeyCreateOptions): Promise<MajikKey>;
+    private static _resolveCreateKeys;
+    /**
+     * 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 create(mnemonic: string, passphrase: string, label?: string, options?: {
-        mnemonicLanguage?: MnemonicLanguage;
-        /** @experimental Set `false` to skip deriving the Bitcoin keypair. Defaults to `true` for backward compatibility. */
-        deriveBitcoin?: boolean;
-    }): Promise<MajikKey>;
     static fromJSON(json: MajikKeyJSON | string): MajikKey;
+    private static _validateRegistryJSON;
     /**
      * 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(): MajikKeyDangerousJSON;
     /**
      * 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: MajikKeyDangerousJSON | string): MajikKey;
     toMnemonicJSON(mnemonic: string, passphrase?: string): MnemonicJSON;
-    static fromMnemonicJSON(mnemonicJson: MnemonicJSON | string, passphrase: string, label?: string, options?: {
-        mnemonicLanguage?: MnemonicLanguage;
-        /** @experimental Set `false` to skip deriving the Bitcoin keypair. Defaults to `true` for backward compatibility. */
-        deriveBitcoin?: boolean;
-    }): Promise<MajikKey>;
+    static fromMnemonicJSON(mnemonicJson: MnemonicJSON | string, passphrase: string, label?: string, options?: MajikKeyCreateOptions): Promise<MajikKey>;
     updateLabel(newLabel: string): this;
     updatePassphrase(currentPassphrase: string, newPassphrase: string): Promise<this>;
     /**
      * 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).
      */
     migrate(passphrase: string): Promise<this>;
+    /**
+     * 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
+     */
+    addKeys(ids: readonly KeyId[], mnemonic: string, passphrase: string): Promise<KeyId[]>;
     lock(): this;
+    /** One KDF run decrypts every key. Atomic: a failure leaves the account fully locked. */
     unlock(passphrase: string): Promise<this>;
     verify(passphrase: string): Promise<boolean>;
-    getPrivateKey(): X25519RawKey;
+    /** @deprecated Use `getPrivateKey(KeyId.X25519)`. */
     getPrivateKeyBase64(): string;
-    getMlKemSecretKey(): Uint8Array;
-    getEdSecretKey(): Uint8Array;
-    getMlDsaSecretKey(): Uint8Array;
     /**
      * 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 withAutoLock<T>(key: MajikKey, operation: (key: MajikKey) => T | Promise<T>): Promise<T>;
-    toJSON(): MajikKeyJSON;
+    private _hasNonX25519Blobs;
+    /**
+     * 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.
+     */
+    private _reencryptAll;
+    /**
+     * 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?: MajikKeyToJSONOptions | string): MajikKeyJSON;
     toString(pretty?: boolean): string;
     static generateMnemonic(strength?: 128 | 256, language?: MnemonicLanguage): Promise<string>;
     static validateMnemonic(mnemonic: string): boolean;
@@ -371,97 +304,62 @@ export declare class MajikKey {
     }): Promise<MajikMessageIdentity>;
     exportMnemonicBackup(mnemonic: string): Promise<string>;
     /**
-     * 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 importFromMnemonicBackup(backup: string, mnemonic: string, passphrase: string, label?: string, options?: {
-        mnemonicLanguage?: MnemonicLanguage;
-        /** @experimental Set `false` to skip deriving the Bitcoin keypair. Defaults to `true` for backward compatibility. */
-        deriveBitcoin?: boolean;
-    }): Promise<MajikKey>;
+    static importFromMnemonicBackup(backup: string, mnemonic: string, passphrase: string, label?: string, options?: MajikKeyCreateOptions): Promise<MajikKey>;
     private static _getWordlist;
     /**
-     * @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.
      */
-    private static _deriveAndEncryptFromMnemonic;
-    private static _encryptPrivateKey;
-    /**
-     * Encrypt the ML-KEM secret key using the same Argon2id-derived key as X25519
-     * (same passphrase + same salt) but a DIFFERENT random IV. One Argon2id
-     * computation → two independently encrypted blobs.
-     */
-    private static _encryptMlKemSecretKey;
-    private static _encryptSigningKey;
-    private static _decryptPrivateKey;
-    private static _decryptMlKemSecretKey;
-    private static _decryptSigningKey;
+    private static _deriveFromMnemonic;
+    /** One KDF run. kdfVersion 1 = legacy PBKDF2 (X25519 blob of old accounts only). */
+    private static _deriveVaultKey;
     private static _verifyBackupDecryption;
     private static _exportMnemonicBackup;
     private static _deriveLegacyMnemonicKey;
-    private static _exportKeyToBase64;
-    /**
-     * @experimental
-     */
-    getBtcSecretKey(): Uint8Array;
     /**
      * @experimental
      */
     get web3(): MajikKeyWeb3Namespace | undefined;
-    /**
-     * @experimental True if this MajikKey can currently produce Bitcoin
-     * material (i.e. it's unlocked and has a Bitcoin secret key).
-     */
+    /** @experimental True if this MajikKey can currently produce Bitcoin material (unlocked + has a Bitcoin key). */
     get hasBitcoinKeypair(): boolean;
     /**
-     * @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?: BitcoinDerivationOptions): BitcoinKeypairMaterial;
-    /**
-     * @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 deriveStandardBitcoinFromMnemonic(mnemonic: string, mnemonicLanguage?: MnemonicLanguage): Promise<BitcoinKeypairMaterial>;
-    /**
-     * @experimental WIF export of the default (domain-separated) Bitcoin key.
-     */
+    /** @experimental WIF export of the stored (domain-separated) Bitcoin key. */
     getBitcoinWIF(options?: {
         compressed?: boolean;
     }): string;
+    /** @experimental True if this account has a stored Ethereum key (works while locked). */
+    get hasEthereum(): boolean;
     /**
-     * @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(): string;
+    /** @experimental Raw Ethereum keypair material. Requires an unlocked account. */
+    getEthereumKeypairMaterial(): EthereumKeypairMaterial;
+    /** @experimental 0x-prefixed private key hex, for wallet "import private key". */
+    getEthereumPrivateKeyHex(): string;
+    /** @experimental True if this MajikKey can currently produce a Solana keypair (unlocked + has Ed25519). */
     get hasSolanaKeypair(): boolean;
     private _getOrDeriveSolanaMaterial;
-    /**
-     * @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?: {
         reuseMessageKey?: boolean;
     }): SolanaKeypairMaterial;
-    /**
-     * @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). */
     getSolanaKeypair(options?: {
         reuseMessageKey?: boolean;
     }): Promise<any>;
-    /**
-     * @experimental Base58 Solana address. Does NOT require @solana/kit.
-     */
+    /** @experimental Base58 Solana address. Does NOT require @solana/kit. */
     getSolanaAddress(options?: {
         reuseMessageKey?: boolean;
     }): string;