@majikah/majik-universal-id-client 0.0.1

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

@@ -0,0 +1,228 @@
+/**
+ * MajikKeyStore.ts
+ *
+ * IDB persistence + in-memory cache layer for MajikKey accounts.
+ * Replaces MajikKeyStore as the account storage backend for MajikMessage.
+ *
+ */
+import { MajikKey, SerializedIdentity } from "@majikah/majik-key";
+/**
+ * The legacy SerializedIdentity shape from MajikKeyStore.
+ * Used only for reading old IDB records during migration.
+ */
+interface LegacySerializedIdentity {
+    id: string;
+    publicKey: string;
+    fingerprint: string;
+    encryptedPrivateKey?: string;
+    salt?: string;
+}
+export declare class MajikKeyStoreError extends Error {
+    cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export declare class MajikKeyStore {
+    private static _deviceID;
+    private static _dbPromise;
+    /**
+     * In-memory cache of all loaded MajikKey instances (locked or unlocked).
+     * Keyed by account ID. Unlocked state lives inside each MajikKey instance.
+     */
+    private static _keys;
+    /**
+     * Optional callback invoked when UI needs to prompt for a passphrase.
+     * Should return the passphrase string or Promise<string>.
+     */
+    static onUnlockRequested?: (id: string) => string | Promise<string>;
+    /**
+     * Initialize the store with a device/user ID.
+     * Must be called before any other method.
+     */
+    static init(deviceID: string): void;
+    private static _getDB;
+    private static _put;
+    private static _get;
+    private static _getAll;
+    private static _delete;
+    private static _getLegacy;
+    private static _getAllLegacy;
+    /**
+     * 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 save(key: MajikKey): Promise<void>;
+    /**
+     * 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 load(id: string): Promise<MajikKey | null>;
+    /**
+     * Load all MajikKeys from IDB (new store + legacy store merged).
+     * Legacy accounts are included but NOT migrated until explicitly unlocked.
+     */
+    static loadAll(): Promise<MajikKey[]>;
+    static getAccount(id: string): Promise<MajikKey>;
+    /**
+     * 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 unlock(id: string, passphrase: string): Promise<MajikKey>;
+    /**
+     * Lock a MajikKey — clears private keys from memory.
+     */
+    static lock(id: string): void;
+    /**
+     * Lock all loaded accounts.
+     */
+    static lockAll(): void;
+    /**
+     * Get the private key of an unlocked account.
+     * Throws if not found or not unlocked — caller must call unlock() first.
+     */
+    static getPrivateKey(idOrFingerprint: string): CryptoKey | {
+        raw: Uint8Array;
+    };
+    /**
+     * 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: string): Uint8Array | undefined;
+    /**
+     * Get a loaded MajikKey by ID or fingerprint.
+     */
+    static get(idOrFingerprint: string): MajikKey | undefined;
+    /**
+     * List all currently loaded MajikKey instances (locked + unlocked).
+     */
+    static list(): MajikKey[];
+    /**
+     * Check whether an account exists by ID or fingerprint.
+     * Checks memory cache first, then IDB.
+     */
+    static has(idOrFingerprint: string): Promise<boolean>;
+    /**
+     * Validate whether a passphrase can decrypt the stored account.
+     * Does NOT unlock or mutate any state.
+     */
+    static isPassphraseValid(id: string, passphrase: string): Promise<boolean>;
+    /**
+     * Delete an account from IDB and memory cache.
+     */
+    static delete(id: string): Promise<void>;
+    /**
+     * 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 ensureUnlocked(id: string, promptFn?: (id: string) => string | Promise<string>): Promise<CryptoKey | {
+        raw: Uint8Array;
+    }>;
+    /**
+     * 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: LegacySerializedIdentity): MajikKey;
+    /**
+     * 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 migrateAllLegacy(): Promise<{
+        migrated: number;
+        skipped: number;
+    }>;
+    /**
+     * 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 migrate(identity: SerializedIdentity): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Drop-in for MajikKeyStore.addMajikKey().
+     * Saves the FULL MajikKeyJSON to IDB (not just 5 fields).
+     */
+    static addMajikKey(key: MajikKey): Promise<void>;
+    /**
+     * Drop-in for MajikKeyStore.unlockIdentity().
+     */
+    static unlockIdentity(id: string, passphrase: string): Promise<MajikKey>;
+    /**
+     * Drop-in for MajikKeyStore.lockIdentity().
+     */
+    static lockIdentity(id: string): void;
+    /**
+     * Drop-in for MajikKeyStore.hasIdentity().
+     */
+    static hasIdentity(fingerprint: string): Promise<boolean>;
+    /**
+     * Drop-in for MajikKeyStore.isPassphraseValid().
+     */
+    static isPassphraseValidFor(id: string, passphrase: string): Promise<boolean>;
+    /**
+     * Drop-in for MajikKeyStore.updatePassphrase().
+     * Correctly upgrades KDF to Argon2id on re-encryption (MajikKeyStore never did this).
+     */
+    static updatePassphrase(id: string, currentPassphrase: string, newPassphrase: string): Promise<void>;
+    /**
+     * Drop-in for MajikKeyStore.listStoredIdentities().
+     * Returns all stored MajikKey instances (loaded from IDB if needed).
+     */
+    static listStoredKeys(): Promise<MajikKey[]>;
+    /**
+     * Drop-in for MajikKeyStore.deleteIdentity().
+     */
+    static deleteIdentity(id: string): Promise<void>;
+    static deleteAll(): Promise<void>;
+    /**
+     * Drop-in for MajikKeyStore.generateMnemonic().
+     */
+    static generateMnemonic(strength?: 128 | 256): string;
+    /**
+     * Drop-in for MajikKeyStore.exportIdentityMnemonicBackup().
+     * The account must be unlocked.
+     */
+    static exportMnemonicBackup(id: string, mnemonic: string): Promise<string>;
+    /**
+     * Drop-in for MajikKeyStore.importIdentityFromMnemonicBackup().
+     * Fully upgrades the account: Argon2id KDF + ML-KEM keys in one step.
+     */
+    static importFromMnemonicBackup(backupBase64: string, mnemonic: string, passphrase: string, label?: string): Promise<MajikKey>;
+    private static _findKey;
+}
+export {};