@cryptforge/auth 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1174 @@
+// src/AuthClient.ts
+import {
+  generateMnemonic,
+  validateMnemonic,
+  mnemonicToSeedSync
+} from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english.js";
+import { HDKey } from "@scure/bip32";
+var AuthClient = class {
+  state = {
+    identity: null,
+    keys: null,
+    currentChain: null,
+    isLocked: true
+  };
+  listeners = /* @__PURE__ */ new Set();
+  lockTimer;
+  decryptedMnemonic = null;
+  // Blockchain adapter registry
+  adapters = /* @__PURE__ */ new Map();
+  currentAdapter = null;
+  /**
+   * Register a blockchain adapter for a specific chain
+   * @param chainId - Unique chain identifier (e.g., 'ethereum', 'bitcoin')
+   * @param adapter - BlockchainAdapter implementation
+   */
+  registerAdapter = (chainId, adapter) => {
+    this.adapters.set(chainId, adapter);
+  };
+  /**
+   * Get the adapter for a specific chain
+   * @param chainId - Chain identifier
+   * @returns BlockchainAdapter instance
+   * @throws Error if no adapter is registered for the chain
+   */
+  getAdapter(chainId) {
+    const adapter = this.adapters.get(chainId);
+    if (!adapter) {
+      throw new Error(
+        `No adapter registered for chain: ${chainId}. Please register an adapter using registerAdapter().`
+      );
+    }
+    return adapter;
+  }
+  /**
+   * Get all registered chain IDs
+   * @returns Array of registered chain IDs
+   */
+  getRegisteredChains = () => {
+    return Array.from(this.adapters.keys());
+  };
+  // Identity Creation & Restoration
+  /**
+   * Generates a BIP39 mnemonic phrase (12 or 24 words).
+   * @param options - Optional configuration for word count
+   * @returns BIP39 mnemonic phrase
+   */
+  generateMnemonic = (options) => {
+    const wordCount = options?.wordCount || 12;
+    const strength = wordCount === 24 ? 256 : 128;
+    return generateMnemonic(wordlist, strength);
+  };
+  /**
+   * Creates a new identity from a mnemonic and encrypts it with a password.
+   * Optionally unlocks with a specific blockchain.
+   * @param options - Identity creation options including mnemonic, password, and optional chainId
+   * @returns Promise resolving to the created identity and keys
+   * @throws {Error} If mnemonic is invalid
+   */
+  createIdentity = async (options) => {
+    const { mnemonic, password, label, metadata = {}, chainId } = options;
+    if (!validateMnemonic(mnemonic, wordlist)) {
+      throw new Error("Invalid mnemonic");
+    }
+    const fingerprint = getMasterFingerprint(mnemonic);
+    const publicKey = getMasterPublicKey(mnemonic);
+    const id = "identity_" + fingerprint;
+    const keystoreJson = await encryptMnemonic(mnemonic, password);
+    const storedIdentity = {
+      id,
+      fingerprint,
+      publicKey,
+      label: label || "Unnamed Wallet",
+      metadata,
+      keystore: keystoreJson,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      lastAccess: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await saveIdentityToDB(storedIdentity);
+    const identity = {
+      id: storedIdentity.id,
+      publicKey: storedIdentity.publicKey,
+      fingerprint: storedIdentity.fingerprint,
+      label: storedIdentity.label,
+      metadata: storedIdentity.metadata,
+      createdAt: new Date(storedIdentity.createdAt),
+      lastAccess: storedIdentity.lastAccess ? new Date(storedIdentity.lastAccess) : void 0
+    };
+    this.state.identity = identity;
+    this.decryptedMnemonic = mnemonic;
+    let keys = null;
+    let chain = null;
+    if (chainId) {
+      const adapter = this.getAdapter(chainId);
+      keys = await this.deriveKeysWithAdapter(
+        mnemonic,
+        chainId,
+        adapter,
+        identity
+      );
+      chain = {
+        id: chainId,
+        name: adapter.chainData.name,
+        symbol: adapter.chainData.symbol
+      };
+      this.state.keys = keys;
+      this.state.currentChain = chain;
+      this.currentAdapter = adapter;
+      this.state.isLocked = false;
+    } else {
+      this.state.isLocked = true;
+    }
+    this.notifyListeners("IDENTITY_CREATED", keys);
+    return { identity, keys };
+  };
+  // Key Management
+  /**
+   * Unlocks the wallet by decrypting the keystore and deriving keys for a blockchain.
+   * @param options - Unlock options including password, chainId, and optional duration
+   * @returns Promise resolving to the derived keys
+   * @throws {Error} If password is incorrect or no identity is selected
+   */
+  unlock = async (options) => {
+    const { password, identityId, chainId, duration } = options;
+    let stored;
+    if (identityId) {
+      stored = await getIdentityFromDB(identityId);
+    } else if (this.state.identity) {
+      stored = await getIdentityFromDB(this.state.identity.id);
+    }
+    if (!stored) throw new Error("No identity selected");
+    const mnemonic = await decryptMnemonic(stored.keystore, password);
+    if (!validateMnemonic(mnemonic, wordlist)) {
+      throw new Error("Decrypted mnemonic is invalid");
+    }
+    this.decryptedMnemonic = mnemonic;
+    const identity = {
+      id: stored.id,
+      publicKey: stored.publicKey,
+      fingerprint: stored.fingerprint,
+      label: stored.label,
+      metadata: stored.metadata,
+      createdAt: new Date(stored.createdAt),
+      lastAccess: stored.lastAccess ? new Date(stored.lastAccess) : void 0
+    };
+    if (!chainId) {
+      throw new Error(
+        "chainId is required to unlock. Please specify which blockchain to use."
+      );
+    }
+    const adapter = this.getAdapter(chainId);
+    const keys = await this.deriveKeysWithAdapter(
+      mnemonic,
+      chainId,
+      adapter,
+      identity,
+      duration
+      // Pass duration to keys
+    );
+    const targetChain = {
+      id: chainId,
+      name: adapter.chainData.name,
+      symbol: adapter.chainData.symbol
+    };
+    this.state.identity = identity;
+    this.state.keys = keys;
+    this.state.currentChain = targetChain;
+    this.currentAdapter = adapter;
+    this.state.isLocked = false;
+    stored.lastAccess = (/* @__PURE__ */ new Date()).toISOString();
+    await saveIdentityToDB(stored);
+    if (duration) {
+      this.setAutoLockTimer(duration);
+    }
+    this.notifyListeners("UNLOCKED", keys);
+    return { keys };
+  };
+  /**
+   * Locks the wallet and clears all keys from memory.
+   * The encrypted keystore remains in IndexedDB.
+   * @returns Promise that resolves when wallet is locked
+   */
+  lock = async () => {
+    if (this.decryptedMnemonic) {
+      this.decryptedMnemonic = null;
+    }
+    this.state.keys = null;
+    this.state.isLocked = true;
+    if (this.lockTimer) {
+      clearTimeout(this.lockTimer);
+      this.lockTimer = void 0;
+    }
+    this.notifyListeners("LOCKED", null);
+  };
+  /**
+   * Switches to a different blockchain while preserving the same identity.
+   * @param chainId - Target blockchain identifier
+   * @param password - Optional password if wallet is locked
+   * @returns Promise resolving to keys for the new chain
+   * @throws {Error} If locked without password or adapter not registered
+   */
+  switchChain = async (chainId, password) => {
+    if (this.state.isLocked && !password) {
+      throw new Error(
+        "Identity is locked. Password required to switch chains."
+      );
+    }
+    let mnemonic = this.decryptedMnemonic;
+    if (!mnemonic && password && this.state.identity) {
+      const stored = await getIdentityFromDB(this.state.identity.id);
+      if (!stored) throw new Error("Identity not found");
+      mnemonic = await decryptMnemonic(stored.keystore, password);
+      this.decryptedMnemonic = mnemonic;
+    }
+    if (!mnemonic || !this.state.identity) {
+      throw new Error("No active identity or mnemonic");
+    }
+    const adapter = this.getAdapter(chainId);
+    const duration = this.state.keys ? this.state.keys.expiresAt.getTime() - Date.now() : void 0;
+    const keys = await this.deriveKeysWithAdapter(
+      mnemonic,
+      chainId,
+      adapter,
+      this.state.identity,
+      duration && duration > 0 ? duration : void 0
+    );
+    const newChain = {
+      id: chainId,
+      name: adapter.chainData.name,
+      symbol: adapter.chainData.symbol
+    };
+    this.state.keys = keys;
+    this.state.currentChain = newChain;
+    this.currentAdapter = adapter;
+    this.state.isLocked = false;
+    this.notifyListeners("CHAIN_SWITCHED", keys);
+    return { keys };
+  };
+  /**
+   * Rotates to a new set of keys at the next address index or custom path.
+   * Preserves key expiration times from current session.
+   * @param newDerivationPath - Optional custom BIP44 path (defaults to next index)
+   * @returns Promise resolving to the new keys
+   * @throws {Error} If wallet is locked
+   */
+  rotateKeys = async (newDerivationPath) => {
+    if (this.state.isLocked || !this.decryptedMnemonic || !this.state.identity || !this.currentAdapter || !this.state.currentChain) {
+      throw new Error("Identity must be unlocked to rotate keys");
+    }
+    if (newDerivationPath) {
+      const keyData2 = await this.currentAdapter.deriveKeysAtPath(
+        this.decryptedMnemonic,
+        newDerivationPath
+      );
+      const expiresAt2 = this.state.keys?.expiresAt || new Date(Date.now() + 36e5);
+      const expiresIn2 = this.state.keys?.expiresIn || 3600;
+      const keys2 = {
+        privateKey: keyData2.privateKey,
+        privateKeyHex: keyData2.privateKeyHex,
+        publicKey: keyData2.publicKey,
+        publicKeyHex: keyData2.publicKeyHex,
+        address: keyData2.address,
+        derivationPath: keyData2.path,
+        chain: this.state.currentChain,
+        expiresAt: expiresAt2,
+        expiresIn: expiresIn2,
+        identity: this.state.identity
+      };
+      this.state.keys = keys2;
+      this.notifyListeners("KEYS_ROTATED", keys2);
+      return { keys: keys2 };
+    }
+    const currentPath = this.state.keys?.derivationPath || "";
+    const pathParts = currentPath.split("/");
+    const lastIndex = parseInt(pathParts[pathParts.length - 1]) || 0;
+    const newIndex = lastIndex + 1;
+    const keyData = await this.currentAdapter.deriveKeysAtIndex(
+      this.decryptedMnemonic,
+      newIndex
+    );
+    const expiresAt = this.state.keys?.expiresAt || new Date(Date.now() + 36e5);
+    const expiresIn = this.state.keys?.expiresIn || 3600;
+    const keys = {
+      privateKey: keyData.privateKey,
+      privateKeyHex: keyData.privateKeyHex,
+      publicKey: keyData.publicKey,
+      publicKeyHex: keyData.publicKeyHex,
+      address: keyData.address,
+      derivationPath: keyData.path,
+      chain: this.state.currentChain,
+      expiresAt,
+      expiresIn,
+      identity: this.state.identity
+    };
+    this.state.keys = keys;
+    this.notifyListeners("KEYS_ROTATED", keys);
+    return { keys };
+  };
+  /**
+   * Derives a one-time key at a custom BIP44 path without storing it in the session.
+   * Useful for signing with different addresses or accounts.
+   * @param options - Derivation options with custom path
+   * @returns Promise resolving to the derived key data
+   * @throws {Error} If wallet is locked
+   */
+  deriveKey = async (options) => {
+    if (this.state.isLocked || !this.decryptedMnemonic || !this.currentAdapter) {
+      throw new Error("Identity must be unlocked to derive keys");
+    }
+    const keyData = await this.currentAdapter.deriveKeysAtPath(
+      this.decryptedMnemonic,
+      options.path
+    );
+    return {
+      privateKey: keyData.privateKeyHex,
+      publicKey: keyData.publicKeyHex,
+      address: keyData.address,
+      path: keyData.path
+    };
+  };
+  /**
+   * Derives a deterministic document ID using BIP44-style hierarchical derivation.
+   * Returns a hex-encoded ID (32 bytes / 64 hex characters).
+   * Path: m/44'/[appId]'/[account]'/[purpose]/[index]
+   * @param options - BIP44 derivation parameters (appId required, others default to 0)
+   * @returns Promise resolving to hex-encoded document ID (64 characters)
+   * @throws {Error} If wallet is locked or parameters are out of range
+   */
+  deriveBIP44DocumentID = async (options) => {
+    if (this.state.isLocked || !this.decryptedMnemonic) {
+      throw new Error(
+        "Wallet is locked. Call unlock() first to derive document IDs."
+      );
+    }
+    const { appId, account = 0, purpose = 0, index = 0 } = options;
+    if (appId === void 0 || appId === null) {
+      throw new Error(
+        "appId is required but was undefined. Please provide a valid appId number."
+      );
+    }
+    if (typeof appId !== "number" || isNaN(appId)) {
+      throw new Error(
+        `appId must be a valid number, received: ${typeof appId}`
+      );
+    }
+    const MAX_HARDENED = 2147483647;
+    if (appId < 0 || appId > MAX_HARDENED) {
+      throw new Error(
+        `Invalid appId: ${appId}. Must be between 0 and ${MAX_HARDENED}`
+      );
+    }
+    if (account < 0 || account > MAX_HARDENED) {
+      throw new Error(
+        `Invalid account: ${account}. Must be between 0 and ${MAX_HARDENED}`
+      );
+    }
+    if (purpose < 0 || purpose > MAX_HARDENED) {
+      throw new Error(
+        `Invalid purpose: ${purpose}. Must be between 0 and ${MAX_HARDENED}`
+      );
+    }
+    if (index < 0 || index > MAX_HARDENED) {
+      throw new Error(
+        `Invalid index: ${index}. Must be between 0 and ${MAX_HARDENED}`
+      );
+    }
+    const path = `m/44'/${appId}'/${account}'/${purpose}/${index}`;
+    const seed = mnemonicToSeedSync(this.decryptedMnemonic);
+    const masterKey = HDKey.fromMasterSeed(seed);
+    const derivedKey = masterKey.derive(path);
+    if (!derivedKey.publicKey) {
+      throw new Error(`Failed to derive key at path: ${path}`);
+    }
+    const publicKeyBuffer = new Uint8Array(derivedKey.publicKey);
+    const hashBuffer = await crypto.subtle.digest("SHA-256", publicKeyBuffer);
+    const hash = new Uint8Array(hashBuffer);
+    return bufferToHex(hash);
+  };
+  /**
+   * Derives a data encryption key using HKDF for encrypting/decrypting data.
+   * This key is deterministic (derived from mnemonic) and chain-independent.
+   * Perfect for document encryption, file storage, etc.
+   *
+   * @param options - Derivation options including purpose, version, algorithm
+   * @returns CryptoKey ready for use with Web Crypto API
+   *
+   * @example
+   * ```typescript
+   * const key = await auth.deriveDataEncryptionKey({
+   *   purpose: 'automerge-documents',
+   *   version: 1,
+   * });
+   *
+   * // Use with Web Crypto API
+   * const encrypted = await crypto.subtle.encrypt(
+   *   { name: 'AES-GCM', iv },
+   *   key,
+   *   data
+   * );
+   * ```
+   */
+  deriveDataEncryptionKey = async (options) => {
+    if (this.state.isLocked || !this.decryptedMnemonic) {
+      throw new Error(
+        "Wallet is locked. Call unlock() first to derive data encryption keys."
+      );
+    }
+    const purpose = options.purpose;
+    const version = options.version || 1;
+    const algorithm = options.algorithm || "AES-GCM";
+    const length = options.length || 256;
+    const extractable = options.extractable || false;
+    const seed = mnemonicToSeedSync(this.decryptedMnemonic);
+    const info = new TextEncoder().encode(`CryptForge-${purpose}-v${version}`);
+    const seedBuffer = new Uint8Array(seed);
+    const keyMaterial = await crypto.subtle.importKey(
+      "raw",
+      seedBuffer,
+      "HKDF",
+      false,
+      ["deriveKey"]
+    );
+    const key = await crypto.subtle.deriveKey(
+      {
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: new Uint8Array(),
+        // Empty salt (could be customized if needed)
+        info
+      },
+      keyMaterial,
+      {
+        name: algorithm,
+        length
+      },
+      extractable,
+      ["encrypt", "decrypt"]
+    );
+    return key;
+  };
+  /**
+   * Gets the address for a specific blockchain at a given index.
+   * @param chainId - Blockchain identifier
+   * @param index - Address index (default: 0)
+   * @returns Promise resolving to address, public key, and derivation path
+   * @throws {Error} If wallet is locked or adapter not registered
+   */
+  getAddressForChain = async (chainId, index = 0) => {
+    if (this.state.isLocked || !this.decryptedMnemonic) {
+      throw new Error("Identity must be unlocked to get addresses");
+    }
+    const adapter = this.getAdapter(chainId);
+    const result = await adapter.getAddressAtIndex(
+      this.decryptedMnemonic,
+      index
+    );
+    return {
+      address: result.address,
+      publicKey: result.publicKey,
+      derivationPath: result.path
+    };
+  };
+  /**
+   * Verify password without unlocking wallet
+   * Useful for transaction confirmation
+   * @param password - Password to verify
+   * @returns Promise resolving to true if password is correct
+   */
+  verifyPassword = async (password) => {
+    if (!this.state.identity) {
+      throw new Error("No identity selected");
+    }
+    try {
+      const stored = await getIdentityFromDB(this.state.identity.id);
+      if (!stored) return false;
+      await decryptMnemonic(stored.keystore, password);
+      return true;
+    } catch (error) {
+      return false;
+    }
+  };
+  // Cryptographic Operations
+  /**
+   * Signs a message using the current or specified private key.
+   * Performs soft expiration check (warns but doesn't block).
+   * @param options - Message and optional derivation path
+   * @returns Promise resolving to signature, address, and public key
+   * @throws {Error} If wallet is locked
+   */
+  signMessage = async (options) => {
+    if (this.state.isLocked || !this.state.keys || !this.currentAdapter) {
+      throw new Error("Identity must be unlocked to sign messages");
+    }
+    this.checkKeysExpiration();
+    let privateKey = this.state.keys.privateKey;
+    let address = this.state.keys.address;
+    let publicKey = this.state.keys.publicKeyHex;
+    if (options.derivationPath && this.decryptedMnemonic) {
+      const keyData = await this.currentAdapter.deriveKeysAtPath(
+        this.decryptedMnemonic,
+        options.derivationPath
+      );
+      privateKey = keyData.privateKey;
+      address = keyData.address;
+      publicKey = keyData.publicKeyHex;
+    }
+    const result = await this.currentAdapter.signMessage(
+      privateKey,
+      options.message
+    );
+    return {
+      signature: result.signature,
+      address,
+      publicKey
+    };
+  };
+  /**
+   * Signs a blockchain transaction using the current or specified private key.
+   * Performs soft expiration check (warns but doesn't block).
+   * @param options - Transaction object and optional derivation path
+   * @returns Promise resolving to signed transaction and signature
+   * @throws {Error} If wallet is locked
+   */
+  signTransaction = async (options) => {
+    if (this.state.isLocked || !this.state.keys || !this.currentAdapter) {
+      throw new Error("Identity must be unlocked to sign transactions");
+    }
+    this.checkKeysExpiration();
+    let privateKey = this.state.keys.privateKey;
+    if (options.derivationPath && this.decryptedMnemonic) {
+      const keyData = await this.currentAdapter.deriveKeysAtPath(
+        this.decryptedMnemonic,
+        options.derivationPath
+      );
+      privateKey = keyData.privateKey;
+    }
+    const result = await this.currentAdapter.signTransaction(
+      privateKey,
+      options.transaction
+    );
+    return {
+      signedTransaction: result.signedTransaction,
+      signature: result.signature
+    };
+  };
+  /**
+   * Verifies a signature against a message and public key using the current adapter.
+   * @param message - Message that was signed (string or bytes)
+   * @param signature - Signature to verify
+   * @param publicKey - Public key to verify against
+   * @returns Promise resolving to true if signature is valid
+   * @throws {Error} If no adapter is selected
+   */
+  verifySignature = async (message, signature, publicKey) => {
+    if (!this.currentAdapter) {
+      throw new Error("No adapter selected. Please unlock with a chain first.");
+    }
+    return this.currentAdapter.verifySignature(message, signature, publicKey);
+  };
+  // Identity Management
+  /**
+   * Lists all identities stored in IndexedDB.
+   * @returns Promise resolving to array of all identities
+   */
+  listIdentities = async () => {
+    const stored = await getAllIdentitiesFromDB();
+    return stored.map((s) => ({
+      id: s.id,
+      publicKey: s.publicKey,
+      fingerprint: s.fingerprint,
+      label: s.label,
+      metadata: s.metadata,
+      createdAt: new Date(s.createdAt),
+      lastAccess: s.lastAccess ? new Date(s.lastAccess) : void 0
+    }));
+  };
+  /**
+   * Switches to a different identity. Locks the current wallet first.
+   * @param identityId - ID of the identity to switch to
+   * @returns Promise resolving to the selected identity
+   * @throws {Error} If identity not found
+   */
+  switchIdentity = async (identityId) => {
+    const stored = await getIdentityFromDB(identityId);
+    if (!stored) throw new Error("Identity not found");
+    await this.lock();
+    const identity = {
+      id: stored.id,
+      publicKey: stored.publicKey,
+      fingerprint: stored.fingerprint,
+      label: stored.label,
+      metadata: stored.metadata,
+      createdAt: new Date(stored.createdAt),
+      lastAccess: stored.lastAccess ? new Date(stored.lastAccess) : void 0
+    };
+    this.state.identity = identity;
+    this.notifyListeners("IDENTITY_SWITCHED", null);
+    return { identity };
+  };
+  /**
+   * Updates the label or metadata for an identity.
+   * @param identityId - ID of the identity to update
+   * @param updates - Label and/or metadata to update
+   * @returns Promise resolving to the updated identity
+   * @throws {Error} If identity not found
+   */
+  updateIdentity = async (identityId, updates) => {
+    const stored = await getIdentityFromDB(identityId);
+    if (!stored) throw new Error("Identity not found");
+    if (updates.label !== void 0) {
+      stored.label = updates.label;
+    }
+    if (updates.metadata !== void 0) {
+      stored.metadata = { ...stored.metadata, ...updates.metadata };
+    }
+    await saveIdentityToDB(stored);
+    const identity = {
+      id: stored.id,
+      publicKey: stored.publicKey,
+      fingerprint: stored.fingerprint,
+      label: stored.label,
+      metadata: stored.metadata,
+      createdAt: new Date(stored.createdAt),
+      lastAccess: stored.lastAccess ? new Date(stored.lastAccess) : void 0
+    };
+    if (this.state.identity?.id === identityId) {
+      this.state.identity = identity;
+    }
+    this.notifyListeners("IDENTITY_UPDATED", this.state.keys);
+    return { identity };
+  };
+  /**
+   * Permanently deletes an identity from IndexedDB. Requires password verification.
+   * Locks wallet if deleting current identity.
+   * @param identityId - ID of the identity to delete
+   * @param password - Password to verify ownership
+   * @returns Promise that resolves when deleted
+   * @throws {Error} If identity not found or password incorrect
+   */
+  deleteIdentity = async (identityId, password) => {
+    const stored = await getIdentityFromDB(identityId);
+    if (!stored) throw new Error("Identity not found");
+    try {
+      await decryptMnemonic(stored.keystore, password);
+    } catch (e) {
+      throw new Error("Invalid password");
+    }
+    if (this.state.identity?.id === identityId) {
+      await this.lock();
+      this.state.identity = null;
+    }
+    await deleteIdentityFromDB(identityId);
+    this.notifyListeners("IDENTITY_DELETED", this.state.keys);
+  };
+  /**
+   * Changes the password for an identity's encrypted keystore.
+   * Re-encrypts the mnemonic with the new password.
+   * @param identityId - ID of the identity
+   * @param oldPassword - Current password
+   * @param newPassword - New password
+   * @returns Promise that resolves when password is changed
+   * @throws {Error} If identity not found or old password incorrect
+   */
+  changePassword = async (identityId, oldPassword, newPassword) => {
+    const stored = await getIdentityFromDB(identityId);
+    if (!stored) throw new Error("Identity not found");
+    const mnemonic = await decryptMnemonic(stored.keystore, oldPassword);
+    const newKeystore = await encryptMnemonic(mnemonic, newPassword);
+    stored.keystore = newKeystore;
+    await saveIdentityToDB(stored);
+    this.notifyListeners("PASSWORD_CHANGED", this.state.keys);
+  };
+  // Import/Export
+  /**
+   * Exports the mnemonic phrase for an identity.
+   * Requires password verification to decrypt the keystore.
+   * ⚠️ Security: Only export mnemonics to secure locations (password managers, paper backup).
+   * @param identityId - ID of the identity to export
+   * @param password - Password to decrypt the keystore
+   * @returns Promise resolving to the mnemonic phrase
+   * @throws {Error} If identity not found or password incorrect
+   */
+  exportMnemonic = async (identityId, password) => {
+    const stored = await getIdentityFromDB(identityId);
+    if (!stored) throw new Error("Identity not found");
+    const mnemonic = await decryptMnemonic(stored.keystore, password);
+    return mnemonic;
+  };
+  /**
+   * Exports the encrypted keystore JSON for an identity.
+   * No password required - keystore is already encrypted.
+   * Perfect for encrypted backup files.
+   * @param identityId - ID of the identity to export
+   * @returns Promise resolving to encrypted keystore JSON string
+   * @throws {Error} If identity not found
+   */
+  exportKeystore = async (identityId) => {
+    const stored = await getIdentityFromDB(identityId);
+    if (!stored) throw new Error("Identity not found");
+    return stored.keystore;
+  };
+  /**
+   * Exports the complete StoredIdentity object including metadata.
+   * No password required - keystore within is already encrypted.
+   * Perfect for migrating identities between devices/browsers with all metadata intact.
+   * @param identityId - ID of the identity to export
+   * @returns Promise resolving to complete StoredIdentity object
+   * @throws {Error} If identity not found
+   */
+  exportIdentity = async (identityId) => {
+    const stored = await getIdentityFromDB(identityId);
+    if (!stored) throw new Error("Identity not found");
+    return stored;
+  };
+  /**
+   * Imports an identity from a mnemonic phrase.
+   * Creates and encrypts a new identity in IndexedDB with the provided password.
+   * @param mnemonic - BIP39 mnemonic phrase (12 or 24 words)
+   * @param password - Password to encrypt the new identity
+   * @param label - Optional label for the wallet (default: "Imported Wallet")
+   * @returns Promise resolving to the created identity
+   * @throws {Error} If mnemonic is invalid
+   */
+  importMnemonic = async (mnemonic, password, label) => {
+    const trimmedMnemonic = mnemonic.trim();
+    if (!validateMnemonic(trimmedMnemonic, wordlist)) {
+      throw new Error("Invalid mnemonic phrase");
+    }
+    const result = await this.createIdentity({
+      mnemonic: trimmedMnemonic,
+      password,
+      label: label || "Imported Wallet"
+    });
+    return { identity: result.identity };
+  };
+  /**
+   * Imports an identity from an encrypted keystore JSON.
+   * Decrypts the keystore and creates a new identity in IndexedDB.
+   * @param keystoreJson - Encrypted keystore JSON string
+   * @param password - Password to decrypt the keystore
+   * @param label - Optional label for the wallet (default: "Imported Wallet")
+   * @returns Promise resolving to the created identity
+   * @throws {Error} If keystore is invalid or password incorrect
+   */
+  importKeystore = async (keystoreJson, password, label) => {
+    const mnemonic = await decryptMnemonic(keystoreJson, password);
+    if (!validateMnemonic(mnemonic, wordlist)) {
+      throw new Error("Decrypted mnemonic is invalid");
+    }
+    const result = await this.createIdentity({
+      mnemonic,
+      password,
+      label: label || "Imported Wallet"
+    });
+    return { identity: result.identity };
+  };
+  /**
+   * Imports a complete StoredIdentity object.
+   * No password required - keystore is already encrypted.
+   * Perfect for migrating identities between devices/browsers with all metadata intact.
+   * Note: This will overwrite any existing identity with the same ID.
+   * @param storedIdentity - Complete StoredIdentity object to import
+   * @returns Promise resolving to the imported identity
+   * @throws {Error} If stored identity data is invalid
+   */
+  importIdentity = async (storedIdentity) => {
+    if (!storedIdentity.id || !storedIdentity.keystore || !storedIdentity.fingerprint) {
+      throw new Error(
+        "Invalid StoredIdentity object - missing required fields"
+      );
+    }
+    await saveIdentityToDB(storedIdentity);
+    const identity = {
+      id: storedIdentity.id,
+      publicKey: storedIdentity.publicKey,
+      fingerprint: storedIdentity.fingerprint,
+      label: storedIdentity.label,
+      metadata: storedIdentity.metadata,
+      createdAt: new Date(storedIdentity.createdAt),
+      lastAccess: storedIdentity.lastAccess ? new Date(storedIdentity.lastAccess) : void 0
+    };
+    this.notifyListeners("IDENTITY_IMPORTED", null);
+    return { identity };
+  };
+  // Address Management
+  /**
+   * Gets multiple addresses for a blockchain starting from a specific index.
+   * @param chainId - Blockchain identifier
+   * @param start - Starting index (default: 0)
+   * @param count - Number of addresses to generate (default: 20)
+   * @returns Promise resolving to array of addresses with paths
+   * @throws {Error} If wallet is locked or adapter not registered
+   */
+  getAddresses = async (chainId, start = 0, count = 20) => {
+    if (this.state.isLocked || !this.decryptedMnemonic) {
+      throw new Error("Identity must be unlocked to get addresses");
+    }
+    const adapter = this.getAdapter(chainId);
+    return adapter.getAddresses(this.decryptedMnemonic, start, count);
+  };
+  /**
+   * Finds all used addresses by checking balances with BIP44 gap limit of 20.
+   * Useful for account discovery when restoring wallets.
+   * @param chainId - Blockchain identifier
+   * @param checkBalance - Function that returns true if address has balance
+   * @returns Promise resolving to array of used addresses
+   * @throws {Error} If wallet is locked or adapter not registered
+   */
+  findUsedAddresses = async (chainId, checkBalance) => {
+    if (this.state.isLocked || !this.decryptedMnemonic) {
+      throw new Error("Identity must be unlocked to find addresses");
+    }
+    const adapter = this.getAdapter(chainId);
+    const usedAddresses = [];
+    let gapCount = 0;
+    const gapLimit = 20;
+    let index = 0;
+    while (gapCount < gapLimit) {
+      const addresses = await adapter.getAddresses(
+        this.decryptedMnemonic,
+        index,
+        1
+      );
+      const addressData = addresses[0];
+      const hasBalance = await checkBalance(addressData.address);
+      if (hasBalance) {
+        usedAddresses.push(addressData);
+        gapCount = 0;
+      } else {
+        gapCount++;
+      }
+      index++;
+    }
+    return usedAddresses;
+  };
+  // State Management
+  /**
+   * Subscribes to authentication state changes.
+   * @param callback - Function called on each auth event with event type and keys
+   * @returns Unsubscribe function
+   */
+  onAuthStateChange = (callback) => {
+    this.listeners.add(callback);
+    return () => {
+      this.listeners.delete(callback);
+    };
+  };
+  // Getters for current state
+  /** Gets the current active identity, or null if none selected. */
+  get currentIdentity() {
+    return this.state.identity;
+  }
+  /** Gets the current derived keys, or null if wallet is locked. */
+  get currentKeys() {
+    return this.state.keys;
+  }
+  /** Gets the current blockchain, or null if none selected. */
+  get currentChain() {
+    return this.state.currentChain;
+  }
+  /** Gets the current blockchain address, or null if locked. */
+  get currentAddress() {
+    return this.state.keys?.address ?? null;
+  }
+  /** Gets the current public key as hex string, or null if locked. */
+  get currentPublicKey() {
+    return this.state.keys?.publicKeyHex ?? null;
+  }
+  /** Gets the key expiration date, or null if no expiration set. */
+  get currentExpiresAt() {
+    return this.state.keys?.expiresAt ?? null;
+  }
+  /** Gets the remaining seconds until key expiration, or null if no expiration set. */
+  get currentExpiresIn() {
+    if (!this.state.keys?.expiresAt) return null;
+    const remaining = Math.floor(
+      (this.state.keys.expiresAt.getTime() - Date.now()) / 1e3
+    );
+    return Math.max(0, remaining);
+  }
+  /** Returns true if wallet is locked (keys cleared from memory). */
+  get isLocked() {
+    return this.state.isLocked;
+  }
+  /** Returns true if wallet is unlocked with active keys. */
+  get isUnlocked() {
+    return !this.state.isLocked && this.state.keys !== null;
+  }
+  /** Returns true if an identity has been created or selected. */
+  get hasIdentity() {
+    return this.state.identity !== null;
+  }
+  /**
+   * Gets the chain-independent master public key (33 bytes, compressed secp256k1).
+   * Safe to expose publicly - does NOT include chaincode.
+   * Perfect for document ownership and cross-chain identity verification.
+   * @returns Hex-encoded master public key, or null if locked
+   */
+  get masterPublicKey() {
+    if (this.state.isLocked || !this.decryptedMnemonic) {
+      return null;
+    }
+    const seed = mnemonicToSeedSync(this.decryptedMnemonic);
+    const masterNode = HDKey.fromMasterSeed(seed);
+    return bufferToHex(masterNode.publicKey);
+  }
+  // Private Methods
+  isKeysExpired() {
+    if (!this.state.keys?.expiresAt) return false;
+    return Date.now() >= this.state.keys.expiresAt.getTime();
+  }
+  checkKeysExpiration() {
+    if (this.isKeysExpired()) {
+      console.warn(
+        "CryptForge: Keys have expired. Consider unlocking again for security."
+      );
+      this.notifyListeners("KEYS_EXPIRED", null);
+    }
+  }
+  async deriveKeysWithAdapter(mnemonic, chainId, adapter, identity, duration) {
+    const keyData = await adapter.deriveKeys(mnemonic);
+    const durationMs = duration || 36e5;
+    const expiresAt = new Date(Date.now() + durationMs);
+    const expiresIn = Math.floor(durationMs / 1e3);
+    return {
+      privateKey: keyData.privateKey,
+      privateKeyHex: keyData.privateKeyHex,
+      publicKey: keyData.publicKey,
+      publicKeyHex: keyData.publicKeyHex,
+      address: keyData.address,
+      derivationPath: keyData.path,
+      chain: {
+        id: chainId,
+        name: adapter.chainData.name,
+        symbol: adapter.chainData.symbol
+      },
+      expiresAt,
+      expiresIn,
+      identity
+    };
+  }
+  notifyListeners(event, keys) {
+    this.listeners.forEach((callback) => callback(event, keys));
+  }
+  setAutoLockTimer(duration) {
+    if (this.lockTimer) {
+      window.clearTimeout(this.lockTimer);
+    }
+    this.lockTimer = window.setTimeout(() => this.lock(), duration);
+  }
+};
+var createAuthClient = () => {
+  return new AuthClient();
+};
+var getMasterNode = (mnemonic) => {
+  const seed = mnemonicToSeedSync(mnemonic);
+  return HDKey.fromMasterSeed(seed);
+};
+var getMasterFingerprint = (mnemonic) => {
+  const root = getMasterNode(mnemonic);
+  return root.fingerprint.toString(16).padStart(8, "0").toUpperCase();
+};
+var getMasterPublicKey = (mnemonic) => {
+  const root = getMasterNode(mnemonic);
+  return bufferToHex(root.publicKey);
+};
+function bufferToHex(buf) {
+  return Array.from(buf).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function concatUint8(a, b) {
+  const c = new Uint8Array(a.length + b.length);
+  c.set(a, 0);
+  c.set(b, a.length);
+  return c;
+}
+function hexToUint8(hex) {
+  if (hex.length % 2 !== 0) throw new Error("Invalid hex string");
+  const arr = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < arr.length; i++) {
+    arr[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return arr;
+}
+function arraysEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+var PBKDF2_ITERATIONS = 1e5;
+var KEY_LENGTH = 32;
+function randomBytes(length) {
+  const arr = new Uint8Array(length);
+  crypto.getRandomValues(arr);
+  return arr;
+}
+var encryptMnemonic = async (mnemonic, password) => {
+  const salt = randomBytes(32);
+  const iv = randomBytes(16);
+  const keyMaterial = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(password),
+    "PBKDF2",
+    false,
+    ["deriveKey"]
+  );
+  const key = await crypto.subtle.deriveKey(
+    {
+      name: "PBKDF2",
+      salt,
+      iterations: PBKDF2_ITERATIONS,
+      hash: "SHA-256"
+    },
+    keyMaterial,
+    { name: "AES-CBC", length: 256 },
+    true,
+    ["encrypt", "decrypt"]
+  );
+  const encryptedBuffer = await crypto.subtle.encrypt(
+    { name: "AES-CBC", iv },
+    key,
+    new TextEncoder().encode(mnemonic)
+  );
+  const ciphertext = new Uint8Array(encryptedBuffer);
+  const macKey = await crypto.subtle.importKey(
+    "raw",
+    await crypto.subtle.exportKey("raw", key),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const macBuffer = await crypto.subtle.sign(
+    "HMAC",
+    macKey,
+    concatUint8(ciphertext, iv)
+  );
+  const keystore = {
+    version: 1,
+    id: bufferToHex(randomBytes(16)),
+    crypto: {
+      cipher: "aes-256-cbc",
+      ciphertext: bufferToHex(ciphertext),
+      cipherparams: { iv: bufferToHex(iv) },
+      kdf: "pbkdf2",
+      kdfparams: {
+        salt: bufferToHex(salt),
+        iterations: PBKDF2_ITERATIONS,
+        keylen: KEY_LENGTH
+      },
+      mac: bufferToHex(new Uint8Array(macBuffer))
+    }
+  };
+  return JSON.stringify(keystore);
+};
+async function decryptMnemonic(keystoreJson, password) {
+  const keystore = JSON.parse(keystoreJson);
+  const salt = hexToUint8(keystore.crypto.kdfparams.salt);
+  const iv = hexToUint8(keystore.crypto.cipherparams.iv);
+  const ciphertext = hexToUint8(keystore.crypto.ciphertext);
+  const storedMac = hexToUint8(keystore.crypto.mac);
+  const keyMaterial = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(password),
+    "PBKDF2",
+    false,
+    ["deriveKey"]
+  );
+  const key = await crypto.subtle.deriveKey(
+    {
+      name: "PBKDF2",
+      salt,
+      iterations: keystore.crypto.kdfparams.iterations,
+      hash: "SHA-256"
+    },
+    keyMaterial,
+    { name: "AES-CBC", length: 256 },
+    true,
+    ["encrypt", "decrypt"]
+  );
+  const macKey = await crypto.subtle.importKey(
+    "raw",
+    await crypto.subtle.exportKey("raw", key),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const computedMacBuffer = await crypto.subtle.sign(
+    "HMAC",
+    macKey,
+    concatUint8(ciphertext, iv)
+  );
+  const computedMac = new Uint8Array(computedMacBuffer);
+  if (!arraysEqual(computedMac, storedMac)) {
+    throw new Error("Invalid password - MAC verification failed");
+  }
+  const decryptedBuffer = await crypto.subtle.decrypt(
+    { name: "AES-CBC", iv },
+    key,
+    ciphertext
+  );
+  const mnemonic = new TextDecoder().decode(decryptedBuffer);
+  if (!mnemonic) {
+    throw new Error("Invalid password - decryption failed");
+  }
+  return mnemonic;
+}
+var DB_NAME = "CryptoAuthDB";
+var STORE_NAME = "identities";
+var openDB = () => {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(DB_NAME, 1);
+    request.onerror = () => reject(request.error);
+    request.onsuccess = () => resolve(request.result);
+    request.onupgradeneeded = (event) => {
+      const db = event.target.result;
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        db.createObjectStore(STORE_NAME, { keyPath: "id" });
+      }
+    };
+  });
+};
+var saveIdentityToDB = async (identity) => {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const transaction = db.transaction([STORE_NAME], "readwrite");
+    const store = transaction.objectStore(STORE_NAME);
+    const request = store.put(identity);
+    request.onsuccess = () => resolve();
+    request.onerror = () => reject(request.error);
+  });
+};
+var getAllIdentitiesFromDB = async () => {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const transaction = db.transaction([STORE_NAME], "readonly");
+    const store = transaction.objectStore(STORE_NAME);
+    const request = store.getAll();
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+};
+var getIdentityFromDB = async (id) => {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const transaction = db.transaction([STORE_NAME], "readonly");
+    const store = transaction.objectStore(STORE_NAME);
+    const request = store.get(id);
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+};
+var deleteIdentityFromDB = async (id) => {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const transaction = db.transaction([STORE_NAME], "readwrite");
+    const store = transaction.objectStore(STORE_NAME);
+    const request = store.delete(id);
+    request.onsuccess = () => resolve();
+    request.onerror = () => reject(request.error);
+  });
+};
+export {
+  AuthClient,
+  createAuthClient
+};