@majikah/majik-key 0.6.0 → 1.0.0

package/dist/core/backup/index.d.ts

@@ -1,4 +1,4 @@
-export { MajikKeyBackup } from "./majik-key-backup";
-export type { BackupSource, CreateBackupParams, ToZipOptions } from "./types";
-export { BACKUP_FORMAT_VERSION } from "./types";
-export { MajikKeyBackupError, MissingOptionalDependencyError, InvalidBackupJSONError, InvalidBackupPNGError, InvalidBackupZipError, BackupIntegrityMismatchError, } from "./error";
+export { MajikKeyBackup } from "./majik-key-backup.js";
+export type { BackupSource, CreateBackupParams, ToZipOptions } from "./types.js";
+export { BACKUP_FORMAT_VERSION } from "./types.js";
+export { MajikKeyBackupError, MissingOptionalDependencyError, InvalidBackupJSONError, InvalidBackupPNGError, InvalidBackupZipError, BackupIntegrityMismatchError, } from "./error.js";

package/dist/core/backup/index.js

@@ -1,3 +1,3 @@
-export { MajikKeyBackup } from "./majik-key-backup";
-export { BACKUP_FORMAT_VERSION } from "./types";
-export { MajikKeyBackupError, MissingOptionalDependencyError, InvalidBackupJSONError, InvalidBackupPNGError, InvalidBackupZipError, BackupIntegrityMismatchError, } from "./error";
+export { MajikKeyBackup } from "./majik-key-backup.js";
+export { BACKUP_FORMAT_VERSION } from "./types.js";
+export { MajikKeyBackupError, MissingOptionalDependencyError, InvalidBackupJSONError, InvalidBackupPNGError, InvalidBackupZipError, BackupIntegrityMismatchError, } from "./error.js";

package/dist/core/backup/majik-key-backup.d.ts

@@ -1,6 +1,6 @@
-import type { MnemonicLanguage } from "../crypto/wordlist";
-import { MnemonicJSON } from "../types";
-import { CreateBackupParams, ToZipOptions } from "./types";
+import type { MnemonicLanguage } from "../crypto/wordlist.js";
+import { MnemonicJSON } from "../types.js";
+import { CreateBackupParams, ToZipOptions } from "./types.js";
 /**
  * A validated Majik Key backup payload, and the single place that knows
  * how to read/write it as JSON, a MajikByte PNG, or a .zip archive

package/dist/core/backup/majik-key-backup.js

@@ -1,8 +1,8 @@
-import { validateMnemonicJSONShape } from "./validator";
-import { InvalidBackupPNGError, InvalidBackupZipError, BackupIntegrityMismatchError, } from "./error";
-import { getJSZip, getMajikBytes, looksLikePNG, toSafeFileName, buildReadmeText, } from "./utils";
-import { BACKUP_FORMAT_VERSION, } from "./types";
-import { base64ToUtf8, utf8ToBase64 } from "../utils";
+import { validateMnemonicJSONShape } from "./validator.js";
+import { InvalidBackupPNGError, InvalidBackupZipError, BackupIntegrityMismatchError, } from "./error.js";
+import { getJSZip, getMajikBytes, looksLikePNG, toSafeFileName, buildReadmeText, } from "./utils.js";
+import { BACKUP_FORMAT_VERSION, } from "./types.js";
+import { base64ToUtf8, utf8ToBase64 } from "../utils.js";
 const BACKUP_JSON_FILENAME = "backup.json";
 const BACKUP_PNG_FILENAME = "backup.png";
 const README_FILENAME = "IMPORTANT README.txt";

package/dist/core/backup/types.d.ts

@@ -1,4 +1,4 @@
-import type { MnemonicLanguage } from "../crypto/wordlist";
+import type { MnemonicLanguage } from "../crypto/wordlist.js";
 /**
  * Bump this whenever the *shape* of MnemonicJSON or the zip layout
  * changes in a way that could break parsing of older backups. Written

package/dist/core/backup/utils.js

@@ -1,4 +1,4 @@
-import { MissingOptionalDependencyError } from "./error";
+import { MissingOptionalDependencyError } from "./error.js";
 // ────────────────────────────────────────────────────────────────
 // Lazy-loaded optional dependencies
 // ────────────────────────────────────────────────────────────────

package/dist/core/backup/validator.d.ts

@@ -1,4 +1,4 @@
-import { MnemonicJSON } from "../types";
+import { MnemonicJSON } from "../types.js";
 /**
  * Single source of truth for "is this a structurally valid
  * MnemonicJSON". Called by `create`, `fromJSON`, `fromPNG` (post-decode),

package/dist/core/backup/validator.js

@@ -1,4 +1,4 @@
-import { InvalidBackupJSONError } from "./error";
+import { InvalidBackupJSONError } from "./error.js";
 /**
  * Single source of truth for "is this a structurally valid
  * MnemonicJSON". Called by `create`, `fromJSON`, `fromPNG` (post-decode),

package/dist/core/crypto/constants.d.ts

@@ -2,8 +2,40 @@ export declare const KEY_ALGO: {
     readonly name: "ECDH";
     readonly namedCurve: "X25519";
 };
-export declare const MAJIK_SALT = "MajikMessageSalt";
-export declare const MAJIK_MNEMONIC_SALT = "MajikMessageMnemonicSalt";
+export declare const MAJIK_SALT = "MajikKeySalt";
+export declare const MAJIK_MNEMONIC_SALT = "MajikKeyMnemonicSalt";
+/**
+ * @deprecated Pre-0.8 salts ("MajikMessage…"). READ-ONLY: kept so backups and
+ * data written by older versions still decrypt. Never use for new writes.
+ * Changing/removing these would make every existing mnemonic backup unreadable.
+ */
+export declare const LEGACY_MAJIK_SALT = "MajikMessageSalt";
+/** @deprecated See LEGACY_MAJIK_SALT. Existing mnemonic backups were encrypted with this salt. */
+export declare const LEGACY_MAJIK_MNEMONIC_SALT = "MajikMessageMnemonicSalt";
+/**
+ * Mnemonic-backup salt generations. The backup blob records which one it used
+ * (`backupSaltVersion`); blobs without the field are generation 1.
+ *   1 → LEGACY_MAJIK_MNEMONIC_SALT   (every backup written before 0.8)
+ *   2 → MAJIK_MNEMONIC_SALT          (written by 0.8+)
+ */
+export declare const BACKUP_SALT_VERSION: {
+    readonly LEGACY: 1;
+    readonly CURRENT: 2;
+};
+export type BACKUP_SALT_VERSION = (typeof BACKUP_SALT_VERSION)[keyof typeof BACKUP_SALT_VERSION];
+/**
+ * Which generation NEW backups are written with. Readers handle both.
+ * ⚠️ Older library versions (and any port that hasn't been updated, e.g.
+ * majik-key-rs) can only read generation 1. Flip to LEGACY to keep newly
+ * created backups readable by them until they ship the new reader.
+ */
+export declare const BACKUP_SALT_WRITE_VERSION: BACKUP_SALT_VERSION;
+export declare const backupSaltFor: (v: number | undefined) => string;
+/**
+ * ⚠️ FROZEN. This string is part of the legacy-v1 ML-DSA-87 derivation
+ * (sha256(seed || this)). Changing it changes every existing user's ML-DSA key.
+ * It intentionally still says "Majik…" and must NOT be renamed.
+ */
 export declare const MAJIK_SIGNATURE_SEED = "MajikSignatureSeedDSA";
 /**
  * KDF version identifiers.
@@ -15,15 +47,7 @@ export declare const KDF_VERSION: {
     readonly ARGON2ID: 2;
 };
 export type KDF_VERSION = (typeof KDF_VERSION)[keyof typeof KDF_VERSION];
-/**
- * Argon2id parameters.
- *
- * PASSPHRASE (protecting the private key at rest):
- *   m=131072 (64 MB) — double OWASP "high security" tier (64 MB)
- *   t=4               — 4 passes
- *   p=4               — 4 parallel lanes
- *
- */
+/** Argon2id parameters. */
 export declare const ARGON2_PARAMS: {
     readonly PASSPHRASE: {
         readonly m: 65536;

package/dist/core/crypto/constants.js

@@ -1,6 +1,36 @@
 export const KEY_ALGO = { name: "ECDH", namedCurve: "X25519" };
-export const MAJIK_SALT = "MajikMessageSalt";
-export const MAJIK_MNEMONIC_SALT = "MajikMessageMnemonicSalt";
+// ── Salts ─────────────────────────────────────────────────────────────────────
+// Current names (MajikKey). Used for everything written by this version.
+export const MAJIK_SALT = "MajikKeySalt";
+export const MAJIK_MNEMONIC_SALT = "MajikKeyMnemonicSalt";
+/**
+ * @deprecated Pre-0.8 salts ("MajikMessage…"). READ-ONLY: kept so backups and
+ * data written by older versions still decrypt. Never use for new writes.
+ * Changing/removing these would make every existing mnemonic backup unreadable.
+ */
+export const LEGACY_MAJIK_SALT = "MajikMessageSalt";
+/** @deprecated See LEGACY_MAJIK_SALT. Existing mnemonic backups were encrypted with this salt. */
+export const LEGACY_MAJIK_MNEMONIC_SALT = "MajikMessageMnemonicSalt";
+/**
+ * Mnemonic-backup salt generations. The backup blob records which one it used
+ * (`backupSaltVersion`); blobs without the field are generation 1.
+ *   1 → LEGACY_MAJIK_MNEMONIC_SALT   (every backup written before 0.8)
+ *   2 → MAJIK_MNEMONIC_SALT          (written by 0.8+)
+ */
+export const BACKUP_SALT_VERSION = { LEGACY: 1, CURRENT: 2 };
+/**
+ * Which generation NEW backups are written with. Readers handle both.
+ * ⚠️ Older library versions (and any port that hasn't been updated, e.g.
+ * majik-key-rs) can only read generation 1. Flip to LEGACY to keep newly
+ * created backups readable by them until they ship the new reader.
+ */
+export const BACKUP_SALT_WRITE_VERSION = BACKUP_SALT_VERSION.CURRENT;
+export const backupSaltFor = (v) => v === BACKUP_SALT_VERSION.CURRENT ? MAJIK_MNEMONIC_SALT : LEGACY_MAJIK_MNEMONIC_SALT;
+/**
+ * ⚠️ FROZEN. This string is part of the legacy-v1 ML-DSA-87 derivation
+ * (sha256(seed || this)). Changing it changes every existing user's ML-DSA key.
+ * It intentionally still says "Majik…" and must NOT be renamed.
+ */
 export const MAJIK_SIGNATURE_SEED = "MajikSignatureSeedDSA";
 /**
  * KDF version identifiers.
@@ -11,15 +41,7 @@ export const KDF_VERSION = {
     PBKDF2: 1, // legacy — read-only support for existing accounts
     ARGON2ID: 2, // current — all new accounts and re-encryptions
 };
-/**
- * Argon2id parameters.
- *
- * PASSPHRASE (protecting the private key at rest):
- *   m=131072 (64 MB) — double OWASP "high security" tier (64 MB)
- *   t=4               — 4 passes
- *   p=4               — 4 parallel lanes
- *
- */
+/** Argon2id parameters. */
 export const ARGON2_PARAMS = {
     PASSPHRASE: {
         m: 65536, // memory in KB (64 MB)

package/dist/core/crypto/crypto-provider.js

@@ -1,14 +1,14 @@
 // crypto-provider.ts from @majikah/majik-key
-import * as ed25519 from "@stablelib/ed25519";
+import * as ed25519 from "@stablelib/ed25519/ed25519.js";
 import ed2curve from "ed2curve";
-import { AES } from "@stablelib/aes";
-import { GCM } from "@stablelib/gcm";
-import { deriveKey } from "@stablelib/pbkdf2";
-import { hash, SHA256 } from "@stablelib/sha256";
-import * as x25519 from "@stablelib/x25519";
-import { arrayToBase64 } from "../utils";
+import { AES } from "@stablelib/aes/aes.js";
+import { GCM } from "@stablelib/gcm/gcm.js";
+import { deriveKey } from "@stablelib/pbkdf2/pbkdf2.js";
+import { hash, SHA256 } from "@stablelib/sha256/sha256.js";
+import * as x25519 from "@stablelib/x25519/x25519.js";
+import { arrayToBase64 } from "../utils.js";
 import { argon2id as nobleArgon2id } from "@noble/hashes/argon2.js";
-import { ARGON2_PARAMS } from "./constants";
+import { ARGON2_PARAMS } from "./constants.js";
 import { ml_kem768 } from "@noble/post-quantum/ml-kem.js";
 import { argon2id as hashWasmArgon2id } from "hash-wasm";
 const secureGetRandomValues = crypto.getRandomValues.bind(crypto);

package/dist/core/crypto/encryption-engine.d.ts

@@ -1,4 +1,4 @@
-import type { ED25519RawPublicKey, MajikKeyFingerprint, MLDSA87RawPublicKey, MLKEM768RawPublicKey, X25519RawKey } from "../types";
+import type { ED25519RawPublicKey, MajikKeyFingerprint, MLDSA87RawPublicKey, MLKEM768RawPublicKey, X25519RawKey } from "../types.js";
 export interface EncryptionIdentity {
     publicKey: X25519RawKey;
     privateKey: X25519RawKey;
@@ -17,22 +17,13 @@ export interface EncryptionIdentity {
  */
 export declare class EncryptionEngine {
     /**
-     * Derive a complete identity from a BIP-39 mnemonic.
+     * Derive the core identity (X25519, Ed25519, ML-KEM-768, ML-DSA-87) from a
+     * BIP-39 mnemonic.
      *
-     * Seed derivation:
-     *   mnemonicToSeedSync(mnemonic) → 64-byte BIP-39 seed
-     *
-     * X25519 derivation (unchanged from before):
-     *   seed[0..32] → Ed25519 keypair via generateKeyPairFromSeed
-     *              → X25519 via ed2curve conversion
-     *
-     * ML-KEM-768 derivation (new):
-     *   seed[0..64] → ml_kem768.keygen(seed)
-     *              → { publicKey: 1184 bytes, secretKey: 2400 bytes }
-     *
-     * The noble library accepts the full 64-byte BIP-39 seed directly.
-     * Internally it uses seed[0..32] for the lattice key matrix and
-     * seed[32..64] for the implicit rejection parameter `z`.
+     * Since 0.8 this DELEGATES to the key registry (core/keys/key-impls.ts),
+     * which is the single source of truth for every derivation recipe. Output is
+     * byte-for-byte identical to the previous implementation (pinned by
+     * vectors/legacy-v1.vectors.json).
      */
     static deriveIdentityFromMnemonic(mnemonic: string): Promise<EncryptionIdentity>;
     /**

package/dist/core/crypto/encryption-engine.js

@@ -1,12 +1,8 @@
 // encryption-engine.ts from @majikah/majik-key
 import { mnemonicToSeedSync } from "@scure/bip39";
-import * as ed25519 from "@stablelib/ed25519";
-import ed2curve from "ed2curve";
-import { ml_dsa87 } from "@noble/post-quantum/ml-dsa.js";
-import { deriveMlKemKeypairFromSeed, fingerprintFromPublicRaw, } from "./crypto-provider";
-import { concatUint8Arrays } from "../utils";
-import { hash } from "@stablelib/sha256";
-import { MAJIK_SIGNATURE_SEED } from "./constants";
+import { fingerprintFromPublicRaw } from "./crypto-provider.js";
+import { deriveKeys } from "../keys/key-impls.js";
+import { KeyId } from "../keys/key-id.js";
 const secureFill = Uint8Array.prototype.fill;
 /**
  * EncryptionEngine
@@ -14,66 +10,41 @@ const secureFill = Uint8Array.prototype.fill;
  * Core cryptographic engine.
  */
 export class EncryptionEngine {
-    /* ================================
-     * Identity
-     * ================================ */
     /**
-     * Derive a complete identity from a BIP-39 mnemonic.
-     *
-     * Seed derivation:
-     *   mnemonicToSeedSync(mnemonic) → 64-byte BIP-39 seed
-     *
-     * X25519 derivation (unchanged from before):
-     *   seed[0..32] → Ed25519 keypair via generateKeyPairFromSeed
-     *              → X25519 via ed2curve conversion
-     *
-     * ML-KEM-768 derivation (new):
-     *   seed[0..64] → ml_kem768.keygen(seed)
-     *              → { publicKey: 1184 bytes, secretKey: 2400 bytes }
+     * Derive the core identity (X25519, Ed25519, ML-KEM-768, ML-DSA-87) from a
+     * BIP-39 mnemonic.
      *
-     * The noble library accepts the full 64-byte BIP-39 seed directly.
-     * Internally it uses seed[0..32] for the lattice key matrix and
-     * seed[32..64] for the implicit rejection parameter `z`.
+     * Since 0.8 this DELEGATES to the key registry (core/keys/key-impls.ts),
+     * which is the single source of truth for every derivation recipe. Output is
+     * byte-for-byte identical to the previous implementation (pinned by
+     * vectors/legacy-v1.vectors.json).
      */
     static async deriveIdentityFromMnemonic(mnemonic) {
         if (typeof mnemonic !== "string" || mnemonic.trim().length === 0) {
             throw new CryptoError("Mnemonic must be a non-empty string");
         }
-        // Step 1: BIP-39 seed → 64 bytes
-        const seed = mnemonicToSeedSync(mnemonic); // returns Buffer (Node) or Uint8Array
-        const seed64 = new Uint8Array(seed); // normalize to Uint8Array
-        // Step 3: ML-KEM-768 keypair from FULL 64-byte seed (new)
-        // ml_kem768.keygen() accepts a 64-byte seed directly.
-        // seed[0..32] → lattice key matrix expansion (K-PKE keygen)
-        // seed[32..64] → implicit rejection parameter z (stored in secretKey)
-        const mlKemKeypair = deriveMlKemKeypairFromSeed(seed64);
-        const mlDsaSeedInput = concatUint8Arrays(seed64, new TextEncoder().encode(MAJIK_SIGNATURE_SEED));
-        const mlDsaSeed = hash(mlDsaSeedInput);
-        // Step 2: X25519 identity from first 32 bytes (existing path)
-        const seed32 = seed64.subarray(0, 32);
+        const seed64 = new Uint8Array(mnemonicToSeedSync(mnemonic));
         try {
-            const ed = ed25519.generateKeyPairFromSeed(seed32);
-            const skCurve = ed2curve.convertSecretKey(ed.secretKey);
-            const pkCurve = ed2curve.convertPublicKey(ed.publicKey);
-            if (!skCurve || !pkCurve) {
-                throw new CryptoError("Failed to convert derived Ed25519 keys to Curve25519");
-            }
-            const pkCurveBytes = new Uint8Array(pkCurve);
-            const skCurveBytes = new Uint8Array(skCurve);
-            const publicKey = { type: "public", raw: pkCurveBytes };
-            const privateKey = { type: "private", raw: skCurveBytes };
-            const fingerprint = fingerprintFromPublicRaw(pkCurveBytes);
-            const mlDsaKeypair = ml_dsa87.keygen(mlDsaSeed);
+            const k = deriveKeys(seed64, [
+                KeyId.X25519,
+                KeyId.ED25519,
+                KeyId.ML_KEM_768,
+                KeyId.ML_DSA_87,
+            ]);
+            const x = k.get(KeyId.X25519);
+            const ed = k.get(KeyId.ED25519);
+            const kem = k.get(KeyId.ML_KEM_768);
+            const dsa = k.get(KeyId.ML_DSA_87);
             return {
-                publicKey,
-                privateKey,
-                fingerprint,
-                mlKemPublicKey: mlKemKeypair.publicKey, // 1184 bytes
-                mlKemSecretKey: mlKemKeypair.secretKey, // 2400 bytes
+                publicKey: { type: "public", raw: x.publicKey },
+                privateKey: { type: "private", raw: x.secretKey },
+                fingerprint: fingerprintFromPublicRaw(x.publicKey),
+                mlKemPublicKey: kem.publicKey, // 1184 bytes
+                mlKemSecretKey: kem.secretKey, // 2400 bytes
                 edPublicKey: ed.publicKey, // 32 bytes
                 edSecretKey: ed.secretKey, // 64 bytes
-                mlDsaPublicKey: mlDsaKeypair.publicKey, // 2592 bytes
-                mlDsaSecretKey: mlDsaKeypair.secretKey, // 4896 bytes
+                mlDsaPublicKey: dsa.publicKey, // 2592 bytes
+                mlDsaSecretKey: dsa.secretKey, // 4896 bytes
             };
         }
         catch (err) {
@@ -81,11 +52,6 @@ export class EncryptionEngine {
         }
         finally {
             secureFill.call(seed64, 0);
-            secureFill.call(seed32, 0);
-            secureFill.call(mlDsaSeedInput, 0);
-            secureFill.call(mlDsaSeed, 0);
-            if (seed instanceof Uint8Array)
-                secureFill.call(seed, 0);
         }
     }
     /* ================================
@@ -95,7 +61,6 @@ export class EncryptionEngine {
      * Generates a SHA-256 fingerprint from a public key.
      */
     static async fingerprintFromPublicKey(publicKey) {
-        // Accept both CryptoKey and raw wrappers; use stablelib sha256 via provider
         const anyKey = publicKey;
         let rawBytes;
         if (anyKey && anyKey.raw instanceof Uint8Array) {

package/dist/core/database/system/identity.d.ts

@@ -1,5 +1,5 @@
-import { MajikUser } from "@thezelijah/majik-user";
-import { SerializedMajikContact } from "@majikah/majik-contact";
+import { MajikUser } from "@thezelijah/majik-user/dist/core/majik-user.js";
+import { SerializedMajikContact } from "@majikah/majik-contact/dist/types.js";
 export interface MajikMessageIdentityJSON {
     id: string;
     user_id: string;

package/dist/core/database/system/identity.js

@@ -1,5 +1,5 @@
-import { hash } from "@stablelib/sha256";
-import { arrayToBase64 } from "../../utils";
+import { hash } from "@stablelib/sha256/sha256.js";
+import { arrayToBase64 } from "../../utils.js";
 /**
  * Utility assertions
  */

package/dist/core/keys/hkdf-recipe.d.ts

@@ -0,0 +1,4 @@
+import type { KeyId } from "./key-id.js";
+export declare const HKDF_SALT = "MajikKey/hkdf-sha512/v1";
+export declare const hkdfInfo: (id: KeyId) => string;
+export declare function deriveSeedHkdf(seed64: Uint8Array, id: KeyId, length: number): Uint8Array;

package/dist/core/keys/hkdf-recipe.js

@@ -0,0 +1,26 @@
+/**
+ * hkdf-recipe.ts — the "hkdf-sha512-v1" derivation recipe for every key
+ * added AFTER the registry (phase 4+). Frozen once released: changing any
+ * constant here changes every key derived with it. Pinned by
+ * vectors/hkdf-v1.vectors.json.
+ *
+ *   seed_k = HKDF-SHA512( ikm  = 64-byte BIP-39 seed,
+ *                         salt = "MajikKey/hkdf-sha512/v1",
+ *                         info = "majik/v1/<namespaced key id>",
+ *                         L    = the algorithm's seed length )
+ *
+ * Domain separation is by `info`, so no two algorithms (or parameter sets of
+ * the same algorithm) ever receive related seed material, and adding a new
+ * algorithm can never change an existing key.
+ */
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { sha512 } from "@noble/hashes/sha2.js";
+import { MajikKeyError } from "../error.js";
+export const HKDF_SALT = "MajikKey/hkdf-sha512/v1";
+export const hkdfInfo = (id) => `majik/v1/${id}`;
+export function deriveSeedHkdf(seed64, id, length) {
+    if (seed64.length !== 64)
+        throw new MajikKeyError(`Expected the 64-byte BIP-39 seed, got ${seed64.length} bytes`);
+    const enc = new TextEncoder();
+    return hkdf(sha512, seed64, enc.encode(HKDF_SALT), enc.encode(hkdfInfo(id)), length);
+}

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

@@ -0,0 +1,50 @@
+/**
+ * key-id.ts
+ * Namespaced identifiers for every key algorithm the MajikKey registry knows.
+ * Format: "<family>:<name>". Adding an algorithm = one line here + one entry
+ * in registry.ts. Existence of an id does NOT mean it is usable — see
+ * `status` / `implemented` in registry.ts.
+ */
+export declare const KeyFamily: {
+    readonly CLASSIC: "classic";
+    readonly PQ: "pq";
+    readonly WEB3: "web3";
+};
+export type KeyFamily = (typeof KeyFamily)[keyof typeof KeyFamily];
+export declare const KeyId: {
+    readonly X25519: "classic:x25519";
+    readonly ED25519: "classic:ed25519";
+    readonly ML_KEM_512: "pq:ml-kem-512";
+    readonly ML_KEM_768: "pq:ml-kem-768";
+    readonly ML_KEM_1024: "pq:ml-kem-1024";
+    readonly HQC_128: "pq:hqc-128";
+    readonly HQC_192: "pq:hqc-192";
+    readonly HQC_256: "pq:hqc-256";
+    readonly ML_DSA_44: "pq:ml-dsa-44";
+    readonly ML_DSA_65: "pq:ml-dsa-65";
+    readonly ML_DSA_87: "pq:ml-dsa-87";
+    readonly SLH_DSA_SHA2_128S: "pq:slh-dsa-sha2-128s";
+    readonly SLH_DSA_SHA2_128F: "pq:slh-dsa-sha2-128f";
+    readonly SLH_DSA_SHA2_192S: "pq:slh-dsa-sha2-192s";
+    readonly SLH_DSA_SHA2_192F: "pq:slh-dsa-sha2-192f";
+    readonly SLH_DSA_SHA2_256S: "pq:slh-dsa-sha2-256s";
+    readonly SLH_DSA_SHA2_256F: "pq:slh-dsa-sha2-256f";
+    readonly SLH_DSA_SHAKE_128S: "pq:slh-dsa-shake-128s";
+    readonly SLH_DSA_SHAKE_128F: "pq:slh-dsa-shake-128f";
+    readonly SLH_DSA_SHAKE_192S: "pq:slh-dsa-shake-192s";
+    readonly SLH_DSA_SHAKE_192F: "pq:slh-dsa-shake-192f";
+    readonly SLH_DSA_SHAKE_256S: "pq:slh-dsa-shake-256s";
+    readonly SLH_DSA_SHAKE_256F: "pq:slh-dsa-shake-256f";
+    readonly FALCON_512: "pq:falcon-512";
+    readonly FALCON_1024: "pq:falcon-1024";
+    readonly FN_DSA_512: "pq:fn-dsa-512";
+    readonly FN_DSA_1024: "pq:fn-dsa-1024";
+    readonly LMS: "pq:lms";
+    readonly BTC: "web3:btc";
+    readonly ETH: "web3:eth";
+    readonly SOL: "web3:sol";
+};
+export type KeyId = (typeof KeyId)[keyof typeof KeyId];
+/** Keys every account must hold from this version on (backward-compat baseline). */
+export declare const CORE_KEYS: readonly ["classic:x25519", "classic:ed25519", "pq:ml-kem-768", "pq:ml-dsa-87"];
+export declare function keyFamilyOf(id: KeyId): KeyFamily;

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

@@ -0,0 +1,64 @@
+/**
+ * key-id.ts
+ * Namespaced identifiers for every key algorithm the MajikKey registry knows.
+ * Format: "<family>:<name>". Adding an algorithm = one line here + one entry
+ * in registry.ts. Existence of an id does NOT mean it is usable — see
+ * `status` / `implemented` in registry.ts.
+ */
+export const KeyFamily = {
+    CLASSIC: "classic",
+    PQ: "pq",
+    WEB3: "web3",
+};
+export const KeyId = {
+    // ── classic ──
+    X25519: "classic:x25519",
+    ED25519: "classic:ed25519",
+    // ── pq: KEM (FIPS 203) ──
+    ML_KEM_512: "pq:ml-kem-512",
+    ML_KEM_768: "pq:ml-kem-768",
+    ML_KEM_1024: "pq:ml-kem-1024",
+    // ── pq: KEM (HQC — NIST backup KEM, not yet final; no vetted JS impl) ──
+    HQC_128: "pq:hqc-128",
+    HQC_192: "pq:hqc-192",
+    HQC_256: "pq:hqc-256",
+    // ── pq: signatures (FIPS 204) ──
+    ML_DSA_44: "pq:ml-dsa-44",
+    ML_DSA_65: "pq:ml-dsa-65",
+    ML_DSA_87: "pq:ml-dsa-87",
+    // ── pq: signatures (FIPS 205, stateless hash-based) ──
+    SLH_DSA_SHA2_128S: "pq:slh-dsa-sha2-128s",
+    SLH_DSA_SHA2_128F: "pq:slh-dsa-sha2-128f",
+    SLH_DSA_SHA2_192S: "pq:slh-dsa-sha2-192s",
+    SLH_DSA_SHA2_192F: "pq:slh-dsa-sha2-192f",
+    SLH_DSA_SHA2_256S: "pq:slh-dsa-sha2-256s",
+    SLH_DSA_SHA2_256F: "pq:slh-dsa-sha2-256f",
+    SLH_DSA_SHAKE_128S: "pq:slh-dsa-shake-128s",
+    SLH_DSA_SHAKE_128F: "pq:slh-dsa-shake-128f",
+    SLH_DSA_SHAKE_192S: "pq:slh-dsa-shake-192s",
+    SLH_DSA_SHAKE_192F: "pq:slh-dsa-shake-192f",
+    SLH_DSA_SHAKE_256S: "pq:slh-dsa-shake-256s",
+    SLH_DSA_SHAKE_256F: "pq:slh-dsa-shake-256f",
+    // ── pq: Falcon Round 3 (what libraries ship today) ──
+    FALCON_512: "pq:falcon-512",
+    FALCON_1024: "pq:falcon-1024",
+    // ── pq: FN-DSA (FIPS 206) — RESERVED until the standard is final ──
+    FN_DSA_512: "pq:fn-dsa-512",
+    FN_DSA_1024: "pq:fn-dsa-1024",
+    // ── pq: stateful hash-based (NIST SP 800-208) — NOT SUPPORTED, see registry ──
+    LMS: "pq:lms",
+    // ── web3 ──
+    BTC: "web3:btc", // Majik domain-separated path (legacy default)
+    ETH: "web3:eth", // standard BIP-44 m/44'/60'/0'/0/0
+    SOL: "web3:sol", // derived view over classic:ed25519
+};
+/** Keys every account must hold from this version on (backward-compat baseline). */
+export const CORE_KEYS = [
+    KeyId.X25519,
+    KeyId.ED25519,
+    KeyId.ML_KEM_768,
+    KeyId.ML_DSA_87,
+];
+export function keyFamilyOf(id) {
+    return id.split(":")[0];
+}

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

@@ -0,0 +1,12 @@
+import { KeyId } from "./key-id.js";
+export interface DerivedKeypair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+export interface KeyImpl {
+    id: KeyId;
+    derive(seed64: Uint8Array): DerivedKeypair;
+}
+export declare const KEY_IMPLS: Readonly<Partial<Record<KeyId, KeyImpl>>>;
+/** Derive the requested STORED keys from one BIP-39 seed. Caller zeroizes the seed. */
+export declare function deriveKeys(seed64: Uint8Array, ids: readonly KeyId[]): Map<KeyId, DerivedKeypair>;