@majikah/majik-key 0.7.0 → 1.0.0

package/dist/core/keys/key-impls.js

@@ -0,0 +1,163 @@
+/**
+ * key-impls.ts — Phase 2b: derivation implementations for registry keys.
+ *
+ * Every function here takes the 64-byte BIP-39 seed and returns a keypair.
+ * The "legacy-v1" recipes are FROZEN and deliberately inlined (domain strings,
+ * paths) instead of imported from constants files, so a refactor of a
+ * constants module can never silently change a derivation. They are pinned by
+ * vectors/legacy-v1.vectors.json (test/key-impls.test.ts + test-vectors.test.ts).
+ *
+ * New algorithms (phase 4) register here with the "hkdf-sha512-v1" recipe.
+ * Derived views (web3:sol) are NOT stored keys and are not listed here.
+ */
+import * as ed25519 from "@stablelib/ed25519/ed25519.js";
+import ed2curve from "ed2curve";
+import { hash } from "@stablelib/sha256/sha256.js";
+import { ml_kem512, ml_kem768, ml_kem1024, } from "@noble/post-quantum/ml-kem.js";
+import { ml_dsa44, ml_dsa65, ml_dsa87 } from "@noble/post-quantum/ml-dsa.js";
+import { slh_dsa_sha2_128s, slh_dsa_sha2_128f, slh_dsa_sha2_192s, slh_dsa_sha2_192f, slh_dsa_sha2_256s, slh_dsa_sha2_256f, slh_dsa_shake_128s, slh_dsa_shake_128f, slh_dsa_shake_192s, slh_dsa_shake_192f, slh_dsa_shake_256s, slh_dsa_shake_256f, } from "@noble/post-quantum/slh-dsa.js";
+import { falcon512, falcon1024 } from "@noble/post-quantum/falcon.js";
+import { deriveSeedHkdf } from "./hkdf-recipe.js";
+import { HDKey } from "@scure/bip32/index.js";
+import { MajikKeyError } from "../error.js";
+import { KeyId } from "./key-id.js";
+// ── frozen legacy-v1 recipe constants (do not "tidy" these) ──
+const LEGACY_DSA_DOMAIN = "MajikSignatureSeedDSA";
+const LEGACY_BTC_PATH = "m/84'/1971'/0'/0/0";
+// Standard Ethereum path (SLIP-44 coin 60): MetaMask / Ledger / Trezor compatible.
+const ETH_STANDARD_PATH = "m/44'/60'/0'/0/0";
+function assertSeed(seed64) {
+    if (seed64.length !== 64)
+        throw new MajikKeyError(`Expected the 64-byte BIP-39 seed, got ${seed64.length} bytes`);
+}
+/** Ed25519 from seed[0..32]; X25519 is converted from this same keypair. */
+function edFromSeed(seed64) {
+    return ed25519.generateKeyPairFromSeed(seed64.slice(0, 32));
+}
+const x25519Impl = {
+    id: KeyId.X25519,
+    derive(seed64) {
+        assertSeed(seed64);
+        const ed = edFromSeed(seed64);
+        const pk = ed2curve.convertPublicKey(ed.publicKey);
+        const sk = ed2curve.convertSecretKey(ed.secretKey);
+        if (!pk || !sk)
+            throw new MajikKeyError("Failed to convert derived Ed25519 keys to Curve25519");
+        return { publicKey: new Uint8Array(pk), secretKey: new Uint8Array(sk) };
+    },
+};
+const ed25519Impl = {
+    id: KeyId.ED25519,
+    derive(seed64) {
+        assertSeed(seed64);
+        const ed = edFromSeed(seed64);
+        return { publicKey: ed.publicKey, secretKey: ed.secretKey }; // 32 / 64 bytes
+    },
+};
+const mlKem768Impl = {
+    id: KeyId.ML_KEM_768,
+    derive(seed64) {
+        assertSeed(seed64);
+        return ml_kem768.keygen(seed64); // full 64-byte seed (legacy-v1)
+    },
+};
+const mlDsa87Impl = {
+    id: KeyId.ML_DSA_87,
+    derive(seed64) {
+        assertSeed(seed64);
+        const domain = new TextEncoder().encode(LEGACY_DSA_DOMAIN);
+        const input = new Uint8Array(seed64.length + domain.length);
+        input.set(seed64, 0);
+        input.set(domain, seed64.length);
+        try {
+            return ml_dsa87.keygen(hash(input)); // sha256(seed64 || domain) → 32-byte seed
+        }
+        finally {
+            input.fill(0);
+        }
+    },
+};
+const btcImpl = {
+    id: KeyId.BTC,
+    derive(seed64) {
+        assertSeed(seed64);
+        const child = HDKey.fromMasterSeed(seed64).derive(LEGACY_BTC_PATH);
+        if (!child.privateKey || !child.publicKey)
+            throw new MajikKeyError("Failed to derive Bitcoin keypair from seed");
+        return {
+            publicKey: child.publicKey.slice(),
+            secretKey: child.privateKey.slice(),
+        };
+    },
+};
+const ethImpl = {
+    id: KeyId.ETH,
+    derive(seed64) {
+        assertSeed(seed64);
+        const child = HDKey.fromMasterSeed(seed64).derive(ETH_STANDARD_PATH);
+        if (!child.privateKey || !child.publicKey)
+            throw new MajikKeyError("Failed to derive Ethereum keypair from seed");
+        return {
+            publicKey: child.publicKey.slice(),
+            secretKey: child.privateKey.slice(),
+        }; // 33 / 32 bytes
+    },
+};
+function hkdfImpl(id, algo, seedLength) {
+    return {
+        id,
+        derive(seed64) {
+            assertSeed(seed64);
+            if (algo.lengths.seed !== seedLength)
+                throw new MajikKeyError(`${id}: library seed length is ${algo.lengths.seed}, recipe expects ${seedLength}. Refusing to derive.`);
+            const seed = deriveSeedHkdf(seed64, id, seedLength);
+            try {
+                return algo.keygen(seed);
+            }
+            finally {
+                seed.fill(0);
+            }
+        },
+    };
+}
+const HKDF_IMPLS = [
+    hkdfImpl(KeyId.ML_KEM_512, ml_kem512, 64),
+    hkdfImpl(KeyId.ML_KEM_1024, ml_kem1024, 64),
+    hkdfImpl(KeyId.ML_DSA_44, ml_dsa44, 32),
+    hkdfImpl(KeyId.ML_DSA_65, ml_dsa65, 32),
+    hkdfImpl(KeyId.SLH_DSA_SHA2_128S, slh_dsa_sha2_128s, 48),
+    hkdfImpl(KeyId.SLH_DSA_SHA2_128F, slh_dsa_sha2_128f, 48),
+    hkdfImpl(KeyId.SLH_DSA_SHA2_192S, slh_dsa_sha2_192s, 72),
+    hkdfImpl(KeyId.SLH_DSA_SHA2_192F, slh_dsa_sha2_192f, 72),
+    hkdfImpl(KeyId.SLH_DSA_SHA2_256S, slh_dsa_sha2_256s, 96),
+    hkdfImpl(KeyId.SLH_DSA_SHA2_256F, slh_dsa_sha2_256f, 96),
+    hkdfImpl(KeyId.SLH_DSA_SHAKE_128S, slh_dsa_shake_128s, 48),
+    hkdfImpl(KeyId.SLH_DSA_SHAKE_128F, slh_dsa_shake_128f, 48),
+    hkdfImpl(KeyId.SLH_DSA_SHAKE_192S, slh_dsa_shake_192s, 72),
+    hkdfImpl(KeyId.SLH_DSA_SHAKE_192F, slh_dsa_shake_192f, 72),
+    hkdfImpl(KeyId.SLH_DSA_SHAKE_256S, slh_dsa_shake_256s, 96),
+    hkdfImpl(KeyId.SLH_DSA_SHAKE_256F, slh_dsa_shake_256f, 96),
+    // Falcon Round 3 (NOT FIPS 206) — experimental; ids are pq:falcon-*, not pq:fn-dsa-*
+    hkdfImpl(KeyId.FALCON_512, falcon512, 48),
+    hkdfImpl(KeyId.FALCON_1024, falcon1024, 48),
+];
+export const KEY_IMPLS = Object.freeze({
+    [KeyId.X25519]: x25519Impl,
+    [KeyId.ED25519]: ed25519Impl,
+    [KeyId.ML_KEM_768]: mlKem768Impl,
+    [KeyId.ML_DSA_87]: mlDsa87Impl,
+    [KeyId.BTC]: btcImpl,
+    [KeyId.ETH]: ethImpl,
+    ...Object.fromEntries(HKDF_IMPLS.map((i) => [i.id, i])),
+});
+/** Derive the requested STORED keys from one BIP-39 seed. Caller zeroizes the seed. */
+export function deriveKeys(seed64, ids) {
+    const out = new Map();
+    for (const id of ids) {
+        const impl = KEY_IMPLS[id];
+        if (!impl)
+            throw new MajikKeyError(`No derivation implementation registered for "${id}"`);
+        out.set(id, impl.derive(seed64));
+    }
+    return out;
+}

package/dist/core/keys/key-store.d.ts

@@ -0,0 +1,72 @@
+import { KeyId } from "./key-id.js";
+import type { DerivedKeypair } from "./key-impls.js";
+import type { KeyDerivation, KeyEntryJSON } from "./types.js";
+export interface KeySlot {
+    id: KeyId;
+    publicKey: Uint8Array;
+    /** IV(12) || AES-256-GCM ciphertext. Absent for public-only entries. */
+    encryptedSecretKey?: Uint8Array;
+    /** Raw secret. Present ONLY while the store is unlocked. */
+    secretKey?: Uint8Array;
+    derivation: KeyDerivation;
+    createdAt?: string;
+}
+/** Supplies the AES key for a slot (X25519 of legacy accounts may need PBKDF2, the rest Argon2id). */
+export type KeyResolver = (slot: KeySlot) => Uint8Array;
+/** The flat, pre-registry JSON fields (a subset of MajikKeyJSON). */
+export interface LegacyKeyJSON {
+    publicKey: string;
+    encryptedPrivateKey?: string;
+    mlKemPublicKey?: string;
+    encryptedMlKemSecretKey?: string;
+    edPublicKey?: string;
+    encryptedEdSecretKey?: string;
+    mlDsaPublicKey?: string;
+    encryptedMlDsaSecretKey?: string;
+    btcPublicKey?: string;
+    encryptedBtcSecretKey?: string;
+}
+export declare class KeyStore {
+    private readonly slots;
+    /** Entries whose id this library version doesn't know. Preserved verbatim. */
+    private readonly opaque;
+    private _unlocked;
+    static seal(aesKey: Uint8Array, plaintext: Uint8Array): Uint8Array;
+    static open(aesKey: Uint8Array, blob: Uint8Array, label: string): Uint8Array;
+    /** Fresh derivation (create / importFromMnemonicBackup): seals every secret, returns UNLOCKED. */
+    static fromDerived(derived: ReadonlyMap<KeyId, DerivedKeypair>, aesKey: Uint8Array): KeyStore;
+    /** From the new `keys` JSON field. Unknown ids are preserved opaquely. */
+    static fromEntries(entries: readonly KeyEntryJSON[]): KeyStore;
+    /** Tier 1 migration: wrap the flat pre-registry fields. No secrets, no KDF needed. */
+    static fromLegacyJSON(j: LegacyKeyJSON): KeyStore;
+    get isUnlocked(): boolean;
+    has(id: string): boolean;
+    hasAll(ids: readonly string[]): boolean;
+    missing(ids: readonly KeyId[]): KeyId[];
+    /** Stored ids in canonical registry order. */
+    ids(): KeyId[];
+    get hasOpaqueSecrets(): boolean;
+    slot(id: KeyId): KeySlot | undefined;
+    getPublicKey(id: string): Uint8Array;
+    getSecretKey(id: string): Uint8Array;
+    /** Non-throwing: the raw secret if the store is unlocked and the slot has one. */
+    peekSecretKey(id: string): Uint8Array | undefined;
+    /**
+     * Install raw secrets onto existing slots and mark the store unlocked
+     * (fromDangerousJSON). Every id must already have a slot.
+     */
+    attachSecrets(secrets: ReadonlyMap<string, Uint8Array>): void;
+    /** Raw secrets of every slot (only while unlocked). Used by toDangerousJSON. */
+    exportSecrets(): Map<KeyId, Uint8Array>;
+    /** Decrypt every secret into temporaries; commit only if ALL succeed. */
+    unlock(keyFor: KeyResolver): void;
+    lock(): void;
+    /** Returns freshly sealed blobs under `newKey`. Mutates nothing. */
+    prepareReseal(oldKeyFor: KeyResolver, newKey: Uint8Array): Map<KeyId, Uint8Array>;
+    commitReseal(blobs: ReadonlyMap<KeyId, Uint8Array>): void;
+    /** Add keys after the fact (addKeys()). Caller has already sealed `secretKey`. */
+    add(slot: KeySlot): void;
+    toEntries(): KeyEntryJSON[];
+    /** Flat pre-registry fields — for `toJSON({ legacy: true })` so older readers keep working. */
+    toLegacyJSON(): LegacyKeyJSON;
+}

package/dist/core/keys/key-store.js

@@ -0,0 +1,264 @@
+/**
+ * key-store.ts — Phase 2c core: the single in-memory + at-rest container for
+ * every key on a MajikKey account. MajikKey (phase 2c-wire) delegates to this
+ * instead of holding one private field per algorithm.
+ *
+ * Responsibilities
+ *  - hold one slot per KeyId: public key, encrypted secret (IV||AES-GCM),
+ *    and — only while unlocked — the raw secret
+ *  - atomic unlock / lock / re-encrypt (no half-states)
+ *  - (de)serialize to the new `keys` entries AND to the legacy flat JSON fields
+ *    (Tier 1 migration + optional legacy export)
+ *  - round-trip entries from NEWER library versions untouched (opaque
+ *    pass-through) so a downgrade-then-save never drops keys
+ *
+ * It never derives a KDF key itself: callers pass resolver functions, so the
+ * "one Argon2id run per operation" guarantee (phase 2a) stays in MajikKey.
+ */
+import { MajikKeyError } from "../error.js";
+import { aesGcmDecrypt, aesGcmEncrypt, generateRandomBytes, IV_LENGTH, } from "../crypto/crypto-provider.js";
+import { arrayToBase64, base64ToUint8Array } from "../utils.js";
+import { KeyId } from "./key-id.js";
+import { KEY_ALGORITHMS, getAlgorithm, knownKeyIds } from "./registry.js";
+const LEGACY_FIELDS = [
+    [KeyId.X25519, "publicKey", "encryptedPrivateKey"],
+    [KeyId.ML_KEM_768, "mlKemPublicKey", "encryptedMlKemSecretKey"],
+    [KeyId.ED25519, "edPublicKey", "encryptedEdSecretKey"],
+    [KeyId.ML_DSA_87, "mlDsaPublicKey", "encryptedMlDsaSecretKey"],
+    [KeyId.BTC, "btcPublicKey", "encryptedBtcSecretKey"],
+];
+const zero = (u) => u?.fill(0);
+export class KeyStore {
+    slots = new Map();
+    /** Entries whose id this library version doesn't know. Preserved verbatim. */
+    opaque = [];
+    _unlocked = false;
+    // ── crypto primitives (same on-disk format as every blob since v1) ────────
+    static seal(aesKey, plaintext) {
+        const iv = generateRandomBytes(IV_LENGTH);
+        const ct = aesGcmEncrypt(aesKey, iv, plaintext);
+        const out = new Uint8Array(iv.length + ct.length);
+        out.set(iv, 0);
+        out.set(ct, iv.length);
+        return out;
+    }
+    static open(aesKey, blob, label) {
+        const plain = aesGcmDecrypt(aesKey, blob.slice(0, IV_LENGTH), blob.slice(IV_LENGTH));
+        if (!plain)
+            throw new MajikKeyError(`Failed to decrypt ${label} — incorrect passphrase or corrupted data`);
+        return plain;
+    }
+    // ── construction ──────────────────────────────────────────────────────────
+    /** Fresh derivation (create / importFromMnemonicBackup): seals every secret, returns UNLOCKED. */
+    static fromDerived(derived, aesKey) {
+        const store = new KeyStore();
+        for (const [id, kp] of derived) {
+            store.slots.set(id, {
+                id,
+                publicKey: kp.publicKey,
+                secretKey: kp.secretKey,
+                encryptedSecretKey: KeyStore.seal(aesKey, kp.secretKey),
+                derivation: KEY_ALGORITHMS[id].derivation,
+                createdAt: new Date().toISOString(),
+            });
+        }
+        store._unlocked = true;
+        return store;
+    }
+    /** From the new `keys` JSON field. Unknown ids are preserved opaquely. */
+    static fromEntries(entries) {
+        const store = new KeyStore();
+        const seen = new Set();
+        for (const e of entries) {
+            if (!e || typeof e.id !== "string" || typeof e.publicKey !== "string")
+                throw new MajikKeyError("Invalid key entry in `keys`");
+            if (seen.has(e.id))
+                throw new MajikKeyError(`Duplicate key entry "${e.id}"`);
+            seen.add(e.id);
+            if (!getAlgorithm(e.id)) {
+                store.opaque.push(e); // from a newer version: keep, don't interpret
+                continue;
+            }
+            store.slots.set(e.id, {
+                id: e.id,
+                publicKey: base64ToUint8Array(e.publicKey),
+                encryptedSecretKey: e.encryptedSecretKey
+                    ? base64ToUint8Array(e.encryptedSecretKey)
+                    : undefined,
+                derivation: e.derivation,
+                createdAt: e.createdAt,
+            });
+        }
+        return store;
+    }
+    /** Tier 1 migration: wrap the flat pre-registry fields. No secrets, no KDF needed. */
+    static fromLegacyJSON(j) {
+        const store = new KeyStore();
+        for (const [id, pubField, encField] of LEGACY_FIELDS) {
+            const pub = j[pubField];
+            if (!pub)
+                continue;
+            const enc = j[encField];
+            store.slots.set(id, {
+                id,
+                publicKey: base64ToUint8Array(pub),
+                encryptedSecretKey: enc ? base64ToUint8Array(enc) : undefined,
+                derivation: KEY_ALGORITHMS[id].derivation,
+            });
+        }
+        if (!store.slots.has(KeyId.X25519))
+            throw new MajikKeyError("Legacy key JSON is missing the X25519 public key");
+        return store;
+    }
+    // ── queries ───────────────────────────────────────────────────────────────
+    get isUnlocked() {
+        return this._unlocked;
+    }
+    has(id) {
+        return this.slots.has(id);
+    }
+    hasAll(ids) {
+        return ids.every((i) => this.has(i));
+    }
+    missing(ids) {
+        return ids.filter((i) => !this.slots.has(i));
+    }
+    /** Stored ids in canonical registry order. */
+    ids() {
+        return knownKeyIds().filter((id) => this.slots.has(id));
+    }
+    get hasOpaqueSecrets() {
+        return this.opaque.some((e) => !!e.encryptedSecretKey);
+    }
+    slot(id) {
+        return this.slots.get(id);
+    }
+    getPublicKey(id) {
+        const s = this.slots.get(id);
+        if (!s)
+            throw new MajikKeyError(`No "${id}" key on this account`);
+        return s.publicKey;
+    }
+    getSecretKey(id) {
+        const s = this.slots.get(id);
+        if (!s)
+            throw new MajikKeyError(`No "${id}" key on this account`);
+        if (!this._unlocked || !s.secretKey)
+            throw new MajikKeyError("MajikKey is locked. Call unlock() first.");
+        return s.secretKey;
+    }
+    /** Non-throwing: the raw secret if the store is unlocked and the slot has one. */
+    peekSecretKey(id) {
+        return this._unlocked ? this.slots.get(id)?.secretKey : undefined;
+    }
+    /**
+     * Install raw secrets onto existing slots and mark the store unlocked
+     * (fromDangerousJSON). Every id must already have a slot.
+     */
+    attachSecrets(secrets) {
+        for (const [id, secret] of secrets) {
+            const s = this.slots.get(id);
+            if (!s)
+                throw new MajikKeyError(`Secret supplied for unknown key "${id}"`);
+            s.secretKey = secret;
+        }
+        this._unlocked = true;
+    }
+    /** Raw secrets of every slot (only while unlocked). Used by toDangerousJSON. */
+    exportSecrets() {
+        if (!this._unlocked)
+            throw new MajikKeyError("MajikKey is locked. Call unlock() first.");
+        const out = new Map();
+        for (const s of this.slots.values())
+            if (s.secretKey)
+                out.set(s.id, s.secretKey);
+        return out;
+    }
+    // ── lock / unlock (atomic) ────────────────────────────────────────────────
+    /** Decrypt every secret into temporaries; commit only if ALL succeed. */
+    unlock(keyFor) {
+        const staged = new Map();
+        try {
+            for (const slot of this.slots.values()) {
+                if (!slot.encryptedSecretKey)
+                    continue;
+                staged.set(slot.id, KeyStore.open(keyFor(slot), slot.encryptedSecretKey, `${slot.id} secret key`));
+            }
+        }
+        catch (e) {
+            for (const p of staged.values())
+                zero(p);
+            throw e;
+        }
+        for (const [id, secret] of staged)
+            this.slots.get(id).secretKey = secret;
+        this._unlocked = true;
+    }
+    lock() {
+        for (const s of this.slots.values()) {
+            zero(s.secretKey);
+            s.secretKey = undefined;
+        }
+        this._unlocked = false;
+    }
+    // ── passphrase change / KDF migration (decrypt all → seal all → commit) ───
+    /** Returns freshly sealed blobs under `newKey`. Mutates nothing. */
+    prepareReseal(oldKeyFor, newKey) {
+        if (this.hasOpaqueSecrets)
+            throw new MajikKeyError("This account holds keys from a newer library version. Upgrade the library before changing the passphrase.");
+        const out = new Map();
+        for (const slot of this.slots.values()) {
+            if (!slot.encryptedSecretKey)
+                continue;
+            const plain = KeyStore.open(oldKeyFor(slot), slot.encryptedSecretKey, `${slot.id} secret key`);
+            try {
+                out.set(slot.id, KeyStore.seal(newKey, plain));
+            }
+            finally {
+                zero(plain);
+            }
+        }
+        return out;
+    }
+    commitReseal(blobs) {
+        for (const [id, blob] of blobs)
+            this.slots.get(id).encryptedSecretKey = blob;
+    }
+    /** Add keys after the fact (addKeys()). Caller has already sealed `secretKey`. */
+    add(slot) {
+        if (this.slots.has(slot.id))
+            throw new MajikKeyError(`"${slot.id}" already exists on this account`);
+        this.slots.set(slot.id, slot);
+    }
+    // ── serialization ─────────────────────────────────────────────────────────
+    toEntries() {
+        const known = this.ids().map((id) => {
+            const s = this.slots.get(id);
+            return {
+                id,
+                publicKey: arrayToBase64(s.publicKey),
+                ...(s.encryptedSecretKey
+                    ? { encryptedSecretKey: arrayToBase64(s.encryptedSecretKey) }
+                    : {}),
+                derivation: s.derivation,
+                ...(s.createdAt ? { createdAt: s.createdAt } : {}),
+            };
+        });
+        return [...known, ...this.opaque];
+    }
+    /** Flat pre-registry fields — for `toJSON({ legacy: true })` so older readers keep working. */
+    toLegacyJSON() {
+        const out = {};
+        for (const [id, pubField, encField] of LEGACY_FIELDS) {
+            const s = this.slots.get(id);
+            if (!s)
+                continue;
+            out[pubField] = arrayToBase64(s.publicKey);
+            if (s.encryptedSecretKey)
+                out[encField] = arrayToBase64(s.encryptedSecretKey);
+        }
+        return out;
+    }
+}
+Object.freeze(KeyStore);
+Object.freeze(KeyStore.prototype);

package/dist/core/keys/keypair-handle.d.ts

@@ -0,0 +1,36 @@
+/**
+ * keypair-handle.ts — the object returned by MajikKey.getKeypair(id).
+ *
+ * It reads LIVE through accessor closures instead of copying key bytes, so a
+ * handle obtained before lock() can never expose stale (zeroized) material or
+ * keep secrets alive: after lock(), `.private` throws and `.public` still works.
+ */
+import type { KeyFamily, KeyId } from "./key-id.js";
+import type { KeyPurpose, KeyStatus } from "./types.js";
+export declare class MajikKeypair {
+    readonly id: KeyId;
+    private readonly readPublic;
+    private readonly readPrivate;
+    private readonly readUnlocked;
+    constructor(id: KeyId, readPublic: () => Uint8Array, readPrivate: () => Uint8Array, readUnlocked: () => boolean);
+    /** Namespaced algorithm id, e.g. "pq:ml-dsa-87". */
+    get algorithm(): KeyId;
+    get family(): KeyFamily;
+    get purpose(): KeyPurpose;
+    get status(): KeyStatus;
+    get isUnlocked(): boolean;
+    /** Public key bytes. Available while locked (except derived views like web3:sol). */
+    get public(): Uint8Array;
+    get publicBase64(): string;
+    /** Secret key bytes. Throws if the account is locked. ⚠️ Live key material. */
+    get private(): Uint8Array;
+}
+export interface KeyInfo {
+    id: KeyId;
+    family: KeyFamily;
+    purpose: KeyPurpose;
+    kind: "stored" | "derived";
+    status: KeyStatus;
+    /** Undefined for derived views while locked. */
+    publicKeyBase64?: string;
+}

package/dist/core/keys/keypair-handle.js

@@ -0,0 +1,43 @@
+import { KEY_ALGORITHMS } from "./registry.js";
+import { arrayToBase64 } from "../utils.js";
+export class MajikKeypair {
+    id;
+    readPublic;
+    readPrivate;
+    readUnlocked;
+    constructor(id, readPublic, readPrivate, readUnlocked) {
+        this.id = id;
+        this.readPublic = readPublic;
+        this.readPrivate = readPrivate;
+        this.readUnlocked = readUnlocked;
+    }
+    /** Namespaced algorithm id, e.g. "pq:ml-dsa-87". */
+    get algorithm() {
+        return this.id;
+    }
+    get family() {
+        return KEY_ALGORITHMS[this.id].family;
+    }
+    get purpose() {
+        return KEY_ALGORITHMS[this.id].purpose;
+    }
+    get status() {
+        return KEY_ALGORITHMS[this.id].status;
+    }
+    get isUnlocked() {
+        return this.readUnlocked();
+    }
+    /** Public key bytes. Available while locked (except derived views like web3:sol). */
+    get public() {
+        return this.readPublic();
+    }
+    get publicBase64() {
+        return arrayToBase64(this.readPublic());
+    }
+    /** Secret key bytes. Throws if the account is locked. ⚠️ Live key material. */
+    get private() {
+        return this.readPrivate();
+    }
+}
+Object.freeze(MajikKeypair);
+Object.freeze(MajikKeypair.prototype);

package/dist/core/keys/registry.d.ts

@@ -0,0 +1,16 @@
+import { KeyFamily, KeyId } from "./key-id.js";
+import type { KeyAlgorithmDefinition, KeyStatus } from "./types.js";
+export declare const KEY_ALGORITHMS: Readonly<Record<KeyId, KeyAlgorithmDefinition>>;
+export declare function getAlgorithm(id: string): KeyAlgorithmDefinition | undefined;
+/** Everything the registry knows, in canonical order (includes reserved/unsupported). */
+export declare function knownKeyIds(family?: KeyFamily): KeyId[];
+/** Ids that can actually be enabled today. */
+export declare function enableableKeyIds(): KeyId[];
+/**
+ * Validate a caller's `keys` option and return the STORED key ids to create:
+ * CORE_KEYS ∪ requested, de-duplicated, canonical order. Derived views
+ * (e.g. web3:sol) are accepted as no-ops because they require a stored key
+ * that is already in the core set.
+ */
+export declare function resolveRequestedKeys(requested?: readonly string[]): KeyId[];
+export type { KeyStatus };