@cryptforge/auth 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,372 @@
+import { AuthAdapter, BlockchainAdapter, GenerateMnemonicOptions, CreateIdentityOptions, Identity, Keys, UnlockOptions, DeriveKeyOptions, DeriveDataKeyOptions, SignMessageOptions, SignTransactionOptions, AuthChangeCallback, Chain } from '@cryptforge/core';
+export { AuthAdapter, AuthChangeCallback, AuthEvent, AuthState, Chain, CreateIdentityOptions, DeriveDataKeyOptions, DeriveKeyOptions, GenerateMnemonicOptions, Identity, Keys, RestoreIdentityOptions, SignMessageOptions, SignTransactionOptions, StoredIdentity, UnlockOptions } from '@cryptforge/core';
+
+declare class AuthClient implements AuthAdapter {
+    private state;
+    private listeners;
+    private lockTimer?;
+    private decryptedMnemonic;
+    private adapters;
+    private currentAdapter;
+    /**
+     * Register a blockchain adapter for a specific chain
+     * @param chainId - Unique chain identifier (e.g., 'ethereum', 'bitcoin')
+     * @param adapter - BlockchainAdapter implementation
+     */
+    registerAdapter: (chainId: string, adapter: BlockchainAdapter) => void;
+    /**
+     * Get the adapter for a specific chain
+     * @param chainId - Chain identifier
+     * @returns BlockchainAdapter instance
+     * @throws Error if no adapter is registered for the chain
+     */
+    private getAdapter;
+    /**
+     * Get all registered chain IDs
+     * @returns Array of registered chain IDs
+     */
+    getRegisteredChains: () => string[];
+    /**
+     * Generates a BIP39 mnemonic phrase (12 or 24 words).
+     * @param options - Optional configuration for word count
+     * @returns BIP39 mnemonic phrase
+     */
+    generateMnemonic: (options?: GenerateMnemonicOptions) => string;
+    /**
+     * 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: (options: CreateIdentityOptions & {
+        chainId?: string;
+    }) => Promise<{
+        identity: Identity;
+        keys: Keys;
+    }>;
+    /**
+     * 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: (options: UnlockOptions) => Promise<{
+        keys: 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: () => Promise<void>;
+    /**
+     * 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: (chainId: string, password?: string) => Promise<{
+        keys: 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: (newDerivationPath?: string) => Promise<{
+        keys: 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: (options: DeriveKeyOptions) => Promise<{
+        privateKey: string;
+        publicKey: string;
+        address: string;
+        path: string;
+    }>;
+    /**
+     * 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: (options: {
+        appId: number;
+        account?: number;
+        purpose?: number;
+        index?: number;
+    }) => Promise<string>;
+    /**
+     * 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: (options: DeriveDataKeyOptions) => Promise<CryptoKey>;
+    /**
+     * 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: (chainId: string, index?: number) => Promise<{
+        address: string;
+        publicKey: string;
+        derivationPath: string;
+    }>;
+    /**
+     * Verify password without unlocking wallet
+     * Useful for transaction confirmation
+     * @param password - Password to verify
+     * @returns Promise resolving to true if password is correct
+     */
+    verifyPassword: (password: string) => Promise<boolean>;
+    /**
+     * 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: (options: SignMessageOptions) => Promise<{
+        signature: string;
+        address: string;
+        publicKey: string;
+    }>;
+    /**
+     * 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: (options: SignTransactionOptions) => Promise<{
+        signedTransaction: any;
+        signature: string;
+    }>;
+    /**
+     * 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: (message: string | Uint8Array, signature: string, publicKey: string) => Promise<boolean>;
+    /**
+     * Lists all identities stored in IndexedDB.
+     * @returns Promise resolving to array of all identities
+     */
+    listIdentities: () => Promise<Array<Identity>>;
+    /**
+     * 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: (identityId: string) => Promise<{
+        identity: 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: (identityId: string, updates: {
+        label?: string;
+        metadata?: Record<string, any>;
+    }) => Promise<{
+        identity: 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: (identityId: string, password: string) => Promise<void>;
+    /**
+     * 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: (identityId: string, oldPassword: string, newPassword: string) => Promise<void>;
+    /**
+     * 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: (identityId: string, password: string) => Promise<string>;
+    /**
+     * 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: (identityId: string) => Promise<string>;
+    /**
+     * 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: (identityId: string) => Promise<StoredIdentity>;
+    /**
+     * 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: (mnemonic: string, password: string, label?: string) => Promise<{
+        identity: 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: (keystoreJson: string, password: string, label?: string) => Promise<{
+        identity: 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: (storedIdentity: StoredIdentity) => Promise<{
+        identity: Identity;
+    }>;
+    /**
+     * 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: (chainId: string, start?: number, count?: number) => Promise<Array<{
+        address: string;
+        path: string;
+        index: number;
+    }>>;
+    /**
+     * 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: (chainId: string, checkBalance: (address: string) => Promise<boolean>) => Promise<Array<{
+        address: string;
+        path: string;
+        index: number;
+    }>>;
+    /**
+     * Subscribes to authentication state changes.
+     * @param callback - Function called on each auth event with event type and keys
+     * @returns Unsubscribe function
+     */
+    onAuthStateChange: (callback: AuthChangeCallback) => (() => void);
+    /** Gets the current active identity, or null if none selected. */
+    get currentIdentity(): Identity | null;
+    /** Gets the current derived keys, or null if wallet is locked. */
+    get currentKeys(): Keys | null;
+    /** Gets the current blockchain, or null if none selected. */
+    get currentChain(): Chain | null;
+    /** Gets the current blockchain address, or null if locked. */
+    get currentAddress(): string | null;
+    /** Gets the current public key as hex string, or null if locked. */
+    get currentPublicKey(): string | null;
+    /** Gets the key expiration date, or null if no expiration set. */
+    get currentExpiresAt(): Date | null;
+    /** Gets the remaining seconds until key expiration, or null if no expiration set. */
+    get currentExpiresIn(): number | null;
+    /** Returns true if wallet is locked (keys cleared from memory). */
+    get isLocked(): boolean;
+    /** Returns true if wallet is unlocked with active keys. */
+    get isUnlocked(): boolean;
+    /** Returns true if an identity has been created or selected. */
+    get hasIdentity(): boolean;
+    /**
+     * 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(): string | null;
+    private isKeysExpired;
+    private checkKeysExpiration;
+    private deriveKeysWithAdapter;
+    private notifyListeners;
+    private setAutoLockTimer;
+}
+declare const createAuthClient: () => AuthClient;
+interface StoredIdentity {
+    id: string;
+    fingerprint: string;
+    publicKey: string;
+    label?: string;
+    metadata: Record<string, any>;
+    keystore: string;
+    createdAt: string;
+    lastAccess?: string;
+}
+
+export { AuthClient, createAuthClient };