@majikah/majik-universal-id-client 0.0.1

package/dist/core/crypto/keystore.js

@@ -0,0 +1,575 @@
+/**
+ * MajikKeyStore.ts
+ *
+ * IDB persistence + in-memory cache layer for MajikKey accounts.
+ * Replaces MajikKeyStore as the account storage backend for MajikMessage.
+ *
+ */
+import { MajikKey } from "@majikah/majik-key";
+import { KDF_VERSION } from "./constants";
+// ─── IDB Config ───────────────────────────────────────────────────────────────
+const STORE_NAME = "majik-keys";
+const LEGACY_STORE_NAME = "identities"; // MajikKeyStore's old store — for migration reads
+const DB_VERSION = 2; // bump from MajikKeyStore's v1 to trigger onupgradeneeded
+export class MajikKeyStoreError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "MajikKeyStoreError";
+        this.cause = cause;
+    }
+}
+// ─── MajikKeyStore ────────────────────────────────────────────────────────────
+export class MajikKeyStore {
+    static _deviceID = "default";
+    static _dbPromise = null;
+    /**
+     * In-memory cache of all loaded MajikKey instances (locked or unlocked).
+     * Keyed by account ID. Unlocked state lives inside each MajikKey instance.
+     */
+    static _keys = new Map();
+    /**
+     * Optional callback invoked when UI needs to prompt for a passphrase.
+     * Should return the passphrase string or Promise<string>.
+     */
+    static onUnlockRequested;
+    // ── Init ───────────────────────────────────────────────────────────────────
+    /**
+     * Initialize the store with a device/user ID.
+     * Must be called before any other method.
+     */
+    static init(deviceID) {
+        this._deviceID = deviceID;
+        this._dbPromise = null; // reset DB connection on re-init
+        this._keys.clear();
+    }
+    // ── IDB ───────────────────────────────────────────────────────────────────
+    static async _getDB() {
+        if (this._dbPromise)
+            return this._dbPromise;
+        this._dbPromise = new Promise((resolve, reject) => {
+            const request = indexedDB.open(this._deviceID, DB_VERSION);
+            request.onupgradeneeded = (event) => {
+                const db = request.result;
+                const oldVersion = event.oldVersion;
+                // Create new store for MajikKeyJSON (v2+)
+                if (!db.objectStoreNames.contains(STORE_NAME)) {
+                    db.createObjectStore(STORE_NAME, { keyPath: "id" });
+                }
+                // Keep legacy "identities" store intact for migration reads
+                // (do not delete it — old data may need to be migrated on demand)
+                if (oldVersion < 1 &&
+                    !db.objectStoreNames.contains(LEGACY_STORE_NAME)) {
+                    db.createObjectStore(LEGACY_STORE_NAME, { keyPath: "id" });
+                }
+            };
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(new MajikKeyStoreError("IDB open failed", request.error));
+        });
+        return this._dbPromise;
+    }
+    static async _put(json) {
+        const db = await this._getDB();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(STORE_NAME, "readwrite");
+            const store = tx.objectStore(STORE_NAME);
+            const req = store.put(json);
+            req.onsuccess = () => resolve();
+            req.onerror = () => reject(new MajikKeyStoreError("Failed to store MajikKey", req.error));
+        });
+    }
+    static async _get(id) {
+        const db = await this._getDB();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(STORE_NAME, "readonly");
+            const store = tx.objectStore(STORE_NAME);
+            const req = store.get(id);
+            req.onsuccess = () => resolve(req.result || null);
+            req.onerror = () => reject(new MajikKeyStoreError("Failed to read MajikKey", req.error));
+        });
+    }
+    static async _getAll() {
+        const db = await this._getDB();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(STORE_NAME, "readonly");
+            const store = tx.objectStore(STORE_NAME);
+            const req = store.getAll();
+            req.onsuccess = () => resolve(req.result || []);
+            req.onerror = () => reject(new MajikKeyStoreError("Failed to list MajikKeys", req.error));
+        });
+    }
+    static async _delete(id) {
+        const db = await this._getDB();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(STORE_NAME, "readwrite");
+            const store = tx.objectStore(STORE_NAME);
+            const req = store.delete(id);
+            req.onsuccess = () => resolve();
+            req.onerror = () => reject(new MajikKeyStoreError("Failed to delete MajikKey", req.error));
+        });
+    }
+    // ── Legacy IDB (migration reads only) ─────────────────────────────────────
+    static async _getLegacy(id) {
+        try {
+            const db = await this._getDB();
+            if (!db.objectStoreNames.contains(LEGACY_STORE_NAME))
+                return null;
+            return new Promise((resolve) => {
+                const tx = db.transaction(LEGACY_STORE_NAME, "readonly");
+                const store = tx.objectStore(LEGACY_STORE_NAME);
+                const req = store.get(id);
+                req.onsuccess = () => resolve(req.result || null);
+                req.onerror = () => resolve(null);
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+    static async _getAllLegacy() {
+        try {
+            const db = await this._getDB();
+            if (!db.objectStoreNames.contains(LEGACY_STORE_NAME))
+                return [];
+            return new Promise((resolve) => {
+                const tx = db.transaction(LEGACY_STORE_NAME, "readonly");
+                const store = tx.objectStore(LEGACY_STORE_NAME);
+                const req = store.getAll();
+                req.onsuccess = () => resolve(req.result || []);
+                req.onerror = () => resolve([]);
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    // ── Core API ──────────────────────────────────────────────────────────────
+    /**
+     * Store a MajikKey in IDB and cache it in memory.
+     * The key must be unlocked (toKeyIdentity() is called to warm the memory cache).
+     * The full MajikKeyJSON is persisted — including ML-KEM keys and kdfVersion.
+     */
+    static async save(key) {
+        await this._put(key.toJSON());
+        this._keys.set(key.id, key);
+    }
+    /**
+     * Load a MajikKey by ID. Checks memory cache first, then IDB, then legacy IDB.
+     * Returns null if not found anywhere.
+     *
+     * Loaded keys are LOCKED. Call unlock(id, passphrase) to unlock.
+     */
+    static async load(id) {
+        // 1. Memory cache
+        const cached = this._keys.get(id);
+        if (cached)
+            return cached;
+        // 2. New IDB store (MajikKeyJSON)
+        const json = await this._get(id);
+        if (json) {
+            const key = MajikKey.fromJSON(json);
+            this._keys.set(id, key);
+            return key;
+        }
+        // 3. Legacy IDB store (MajikKeyStore format) — migrate on read
+        const legacy = await this._getLegacy(id);
+        if (legacy) {
+            const key = MajikKeyStore.fromLegacySerializedIdentity(legacy);
+            // Don't save yet — wait until the user unlocks and we can verify
+            this._keys.set(id, key);
+            return key;
+        }
+        return null;
+    }
+    /**
+     * Load all MajikKeys from IDB (new store + legacy store merged).
+     * Legacy accounts are included but NOT migrated until explicitly unlocked.
+     */
+    static async loadAll() {
+        const results = new Map();
+        // New store first
+        const allNew = await this._getAll();
+        for (const json of allNew) {
+            const key = MajikKey.fromJSON(json);
+            results.set(key.id, key);
+            this._keys.set(key.id, key);
+        }
+        // Legacy store — add any not already in new store
+        const allLegacy = await this._getAllLegacy();
+        for (const legacy of allLegacy) {
+            if (!results.has(legacy.id)) {
+                const key = MajikKeyStore.fromLegacySerializedIdentity(legacy);
+                results.set(key.id, key);
+                this._keys.set(key.id, key);
+            }
+        }
+        return [...results.values()];
+    }
+    static async getAccount(id) {
+        const key = await this.load(id);
+        if (!key)
+            throw new MajikKeyStoreError(`Account not found: ${id}`);
+        return key;
+    }
+    /**
+     * Unlock a stored MajikKey with the given passphrase.
+     * Automatically dispatches to the correct KDF (PBKDF2 for old accounts, Argon2id for new).
+     * Updates the in-memory cache with the unlocked instance.
+     */
+    static async unlock(id, passphrase) {
+        const key = await this.load(id);
+        if (!key)
+            throw new MajikKeyStoreError(`Account not found: ${id}`);
+        if (key.isUnlocked)
+            return key;
+        await key.unlock(passphrase);
+        this._keys.set(id, key);
+        return key;
+    }
+    /**
+     * Lock a MajikKey — clears private keys from memory.
+     */
+    static lock(id) {
+        const key = this._keys.get(id);
+        if (key)
+            key.lock();
+    }
+    /**
+     * Lock all loaded accounts.
+     */
+    static lockAll() {
+        for (const key of this._keys.values()) {
+            key.lock();
+        }
+    }
+    /**
+     * Get the private key of an unlocked account.
+     * Throws if not found or not unlocked — caller must call unlock() first.
+     */
+    static getPrivateKey(idOrFingerprint) {
+        // Check by ID
+        const byId = this._keys.get(idOrFingerprint);
+        if (byId?.isUnlocked)
+            return byId.getPrivateKey();
+        // Check by fingerprint
+        for (const key of this._keys.values()) {
+            if (key.fingerprint === idOrFingerprint && key.isUnlocked) {
+                return key.getPrivateKey();
+            }
+        }
+        throw new MajikKeyStoreError(`Account "${idOrFingerprint}" must be unlocked first via unlock()`);
+    }
+    /**
+     * Get the ML-KEM secret key of an unlocked account.
+     * Returns undefined if the account has no ML-KEM keys (pre-migration).
+     */
+    static getMlKemSecretKey(idOrFingerprint) {
+        const key = this._findKey(idOrFingerprint);
+        if (!key?.isUnlocked)
+            return undefined;
+        try {
+            return key.getMlKemSecretKey();
+        }
+        catch {
+            return undefined; // account exists but has no ML-KEM keys yet
+        }
+    }
+    /**
+     * Get a loaded MajikKey by ID or fingerprint.
+     */
+    static get(idOrFingerprint) {
+        return this._findKey(idOrFingerprint);
+    }
+    /**
+     * List all currently loaded MajikKey instances (locked + unlocked).
+     */
+    static list() {
+        return [...this._keys.values()];
+    }
+    /**
+     * Check whether an account exists by ID or fingerprint.
+     * Checks memory cache first, then IDB.
+     */
+    static async has(idOrFingerprint) {
+        // Memory cache
+        if (this._findKey(idOrFingerprint))
+            return true;
+        // IDB (new store)
+        const allNew = await this._getAll();
+        if (allNew.some((j) => j.id === idOrFingerprint || j.fingerprint === idOrFingerprint)) {
+            return true;
+        }
+        // Legacy IDB
+        const allLegacy = await this._getAllLegacy();
+        return allLegacy.some((l) => l.id === idOrFingerprint || l.fingerprint === idOrFingerprint);
+    }
+    /**
+     * Validate whether a passphrase can decrypt the stored account.
+     * Does NOT unlock or mutate any state.
+     */
+    static async isPassphraseValid(id, passphrase) {
+        const key = await this.load(id);
+        if (!key)
+            return false;
+        return key.verify(passphrase);
+    }
+    /**
+     * Delete an account from IDB and memory cache.
+     */
+    static async delete(id) {
+        await this._delete(id);
+        this._keys.delete(id);
+    }
+    /**
+     * Ensure an account is unlocked, prompting for passphrase if needed.
+     * Drop-in replacement for MajikMessage.ensureIdentityUnlocked().
+     *
+     * @param id - Account ID
+     * @param promptFn - Optional passphrase prompt function
+     * @returns The unlocked account's X25519 private key
+     */
+    static async ensureUnlocked(id, promptFn) {
+        // Try from memory first (already unlocked)
+        try {
+            return this.getPrivateKey(id);
+        }
+        catch {
+            /* not unlocked */
+        }
+        // Ask for passphrase
+        let passphrase = null;
+        if (promptFn) {
+            const res = promptFn(id);
+            passphrase = typeof res === "string" ? res : await res;
+        }
+        else if (this.onUnlockRequested) {
+            const res = this.onUnlockRequested(id);
+            passphrase = typeof res === "string" ? res : await res;
+        }
+        else if (typeof window !== "undefined" && window.prompt) {
+            passphrase = window.prompt("Enter passphrase to unlock account:", "");
+        }
+        if (!passphrase)
+            throw new MajikKeyStoreError("Unlock cancelled");
+        await this.unlock(id, passphrase);
+        return this.getPrivateKey(id);
+    }
+    // ── Migration: fromLegacySerializedIdentity ────────────────────────────────
+    /**
+     * Reconstruct a locked MajikKey from a MajikKeyStore SerializedIdentity.
+     *
+     * The legacy format has:
+     *   - id, publicKey (base64), fingerprint
+     *   - encryptedPrivateKey (base64, PBKDF2-encrypted)
+     *   - salt (base64, 16 bytes)
+     *   - NO: kdfVersion (implied PBKDF2), NO: ML-KEM keys, NO: label, NO: backup
+     *
+     * The resulting MajikKey will:
+     *   - Have kdfVersion: PBKDF2 (so unlock() uses the correct KDF)
+     *   - Have hasMlKem: false (until importFromMnemonicBackup() is called)
+     *   - Be locked (private key not in memory)
+     *
+     * After unlock(), MajikMessage can call key.migrate(passphrase) to upgrade
+     * the KDF to Argon2id. For full ML-KEM upgrade, importFromMnemonicBackup()
+     * is required (mnemonic needed).
+     *
+     * This method is also the answer to your question: it's how MajikKey
+     * accepts a SerializedIdentity from the existing MajikKeyStore IDB.
+     */
+    static fromLegacySerializedIdentity(si) {
+        if (!si.id || !si.publicKey || !si.fingerprint) {
+            throw new MajikKeyStoreError("Invalid legacy SerializedIdentity: missing required fields");
+        }
+        // // SerializedIdentity may or may not have encryptedPrivateKey
+        // // (some records were stored without it — public-key-only contacts)
+        // const encryptedPrivateKey = si.encryptedPrivateKey
+        //   ? base64ToArrayBuffer(si.encryptedPrivateKey)
+        //   : new ArrayBuffer(0);
+        // Reconstruct as a minimal MajikKeyJSON (v1 PBKDF2, no ML-KEM)
+        const json = {
+            id: si.id,
+            label: "",
+            publicKey: si.publicKey,
+            fingerprint: si.fingerprint,
+            encryptedPrivateKey: si.encryptedPrivateKey || "",
+            salt: si.salt || "",
+            backup: "_LEGACY", // no backup available from legacy format
+            timestamp: new Date().toISOString(),
+            kdfVersion: KDF_VERSION.PBKDF2, // legacy MajikKeyStore always used PBKDF2
+            // mlKemPublicKey: absent — hasMlKem will be false
+            // encryptedMlKemSecretKey: absent
+        };
+        return MajikKey.fromJSON(json);
+    }
+    /**
+     * Migrate all legacy MajikKeyStore accounts to the new MajikKeyJSON format.
+     *
+     * Reads all records from the old "identities" IDB store, reconstructs
+     * them as MajikKey instances, and writes them to the new "majik-keys" store.
+     * Does NOT upgrade KDF or add ML-KEM keys — that requires the passphrase/mnemonic.
+     *
+     * Call this once on app startup after MajikKeyStore → MajikKeyStore transition.
+     * Safe to call multiple times (already-migrated accounts are skipped).
+     */
+    static async migrateAllLegacy() {
+        const legacyAll = await this._getAllLegacy();
+        let migrated = 0;
+        let skipped = 0;
+        for (const legacy of legacyAll) {
+            // Skip if already in new store
+            const existing = await this._get(legacy.id);
+            if (existing) {
+                skipped++;
+                continue;
+            }
+            try {
+                const key = MajikKeyStore.fromLegacySerializedIdentity(legacy);
+                await this._put(key.toJSON());
+                this._keys.set(key.id, key);
+                migrated++;
+            }
+            catch (err) {
+                console.warn(`Failed to migrate legacy account ${legacy.id}:`, err);
+                skipped++;
+            }
+        }
+        return { migrated, skipped };
+    }
+    /**
+     * Migrate a legacy MajikKeyStore account to the new MajikKeyJSON format.
+     *
+     * Reconstructs them as MajikKey instances, and writes them to the new "majik-keys" store.
+     * Does NOT upgrade KDF or add ML-KEM keys — that requires the passphrase/mnemonic.
+     *
+     * Call this once on app startup after MajikKeyStore → MajikKeyStore transition.
+     * Safe to call multiple times (already-migrated accounts are skipped).
+     */
+    static async migrate(identity) {
+        try {
+            const key = MajikKeyStore.fromLegacySerializedIdentity(identity);
+            await this._put(key.toJSON());
+            this._keys.set(key.id, key);
+            return {
+                success: true,
+                message: `Successfully migrated ${identity.id}`,
+            };
+        }
+        catch (err) {
+            console.warn(`Failed to migrate legacy account ${identity.id}:`, err);
+            return {
+                success: false,
+                message: `Failed to migrate legacy account ${identity.id}: ${err}`,
+            };
+        }
+    }
+    // ── Drop-in replacements for MajikKeyStore methods used by MajikMessage ─────────
+    /**
+     * Drop-in for MajikKeyStore.addMajikKey().
+     * Saves the FULL MajikKeyJSON to IDB (not just 5 fields).
+     */
+    static async addMajikKey(key) {
+        return this.save(key);
+    }
+    /**
+     * Drop-in for MajikKeyStore.unlockIdentity().
+     */
+    static async unlockIdentity(id, passphrase) {
+        return this.unlock(id, passphrase);
+    }
+    /**
+     * Drop-in for MajikKeyStore.lockIdentity().
+     */
+    static lockIdentity(id) {
+        return this.lock(id);
+    }
+    /**
+     * Drop-in for MajikKeyStore.hasIdentity().
+     */
+    static async hasIdentity(fingerprint) {
+        return this.has(fingerprint);
+    }
+    /**
+     * Drop-in for MajikKeyStore.isPassphraseValid().
+     */
+    static async isPassphraseValidFor(id, passphrase) {
+        return this.isPassphraseValid(id, passphrase);
+    }
+    /**
+     * Drop-in for MajikKeyStore.updatePassphrase().
+     * Correctly upgrades KDF to Argon2id on re-encryption (MajikKeyStore never did this).
+     */
+    static async updatePassphrase(id, currentPassphrase, newPassphrase) {
+        const key = await this.load(id);
+        if (!key)
+            throw new MajikKeyStoreError(`Account not found: ${id}`);
+        await key.updatePassphrase(currentPassphrase, newPassphrase);
+        await this._put(key.toJSON()); // persist updated encrypted state
+    }
+    /**
+     * Drop-in for MajikKeyStore.listStoredIdentities().
+     * Returns all stored MajikKey instances (loaded from IDB if needed).
+     */
+    static async listStoredKeys() {
+        return this.loadAll();
+    }
+    /**
+     * Drop-in for MajikKeyStore.deleteIdentity().
+     */
+    static async deleteIdentity(id) {
+        return this.delete(id);
+    }
+    static async deleteAll() {
+        const db = await this._getDB();
+        const clearStore = (storeName) => new Promise((resolve, reject) => {
+            if (!db.objectStoreNames.contains(storeName))
+                return resolve();
+            const tx = db.transaction(storeName, "readwrite");
+            const req = tx.objectStore(storeName).clear();
+            req.onsuccess = () => resolve();
+            req.onerror = () => reject(new MajikKeyStoreError(`Failed to clear store: ${storeName}`, req.error));
+        });
+        await clearStore(STORE_NAME);
+        await clearStore(LEGACY_STORE_NAME);
+        this._keys.clear();
+    }
+    /**
+     * Drop-in for MajikKeyStore.generateMnemonic().
+     */
+    static generateMnemonic(strength = 128) {
+        return MajikKey.generateMnemonic(strength);
+    }
+    /**
+     * Drop-in for MajikKeyStore.exportIdentityMnemonicBackup().
+     * The account must be unlocked.
+     */
+    static async exportMnemonicBackup(id, mnemonic) {
+        const key = this._keys.get(id);
+        if (!key)
+            throw new MajikKeyStoreError(`Account not found: ${id}`);
+        if (key.isLocked)
+            throw new MajikKeyStoreError("Account must be unlocked to export backup");
+        return key.exportMnemonicBackup(mnemonic);
+    }
+    /**
+     * Drop-in for MajikKeyStore.importIdentityFromMnemonicBackup().
+     * Fully upgrades the account: Argon2id KDF + ML-KEM keys in one step.
+     */
+    static async importFromMnemonicBackup(backupBase64, mnemonic, passphrase, label) {
+        const key = await MajikKey.importFromMnemonicBackup(backupBase64, mnemonic, passphrase, label);
+        await this.save(key);
+        return key;
+    }
+    // ── Private helpers ────────────────────────────────────────────────────────
+    static _findKey(idOrFingerprint) {
+        // By ID
+        const byId = this._keys.get(idOrFingerprint);
+        if (byId)
+            return byId;
+        // By fingerprint
+        for (const key of this._keys.values()) {
+            if (key.fingerprint === idOrFingerprint)
+                return key;
+        }
+        return undefined;
+    }
+}

package/dist/core/identity.d.ts

@@ -0,0 +1,63 @@
+import { MajikUser } from "@thezelijah/majik-user";
+import { SerializedMajikContact } from "./contacts/majik-contact";
+export interface MajikMessageIdentityJSON {
+    id: string;
+    user_id: string;
+    public_key: string;
+    ml_key: string;
+    phash: string;
+    label: string;
+    timestamp: string;
+    restricted: boolean;
+}
+/**
+ * MajikMessageIdentity
+ * Immutable identity container with integrity verification
+ */
+export declare class MajikMessageIdentity {
+    private readonly _id;
+    private readonly _userId;
+    private readonly _publicKey;
+    private readonly _mlKey;
+    private readonly _phash;
+    private _label;
+    private readonly _timestamp;
+    private readonly _restricted;
+    /**
+     * Constructor is private to enforce controlled creation
+     */
+    private constructor();
+    /**
+     * Create a new immutable identity from MajikUser
+     */
+    static create(user: MajikUser, account: SerializedMajikContact, options?: {
+        label?: string;
+        restricted?: boolean;
+    }): MajikMessageIdentity;
+    get id(): string;
+    get userID(): string;
+    get publicKey(): string;
+    get phash(): string;
+    get label(): string;
+    get timestamp(): string;
+    get restricted(): boolean;
+    /**
+     * Only mutable field
+     */
+    set label(label: string);
+    /**
+     * Returns true if identity is restricted
+     */
+    isRestricted(): boolean;
+    /**
+     * Verify identity integrity
+     * Detects tampering of id/public_key
+     */
+    validateIntegrity(): boolean;
+    /**
+     * Explicit verification helper
+     */
+    matches(userId: string, publicKey: string): boolean;
+    toJSON(): MajikMessageIdentityJSON;
+    static fromJSON(json: string | MajikMessageIdentityJSON): MajikMessageIdentity;
+}