@veridex/sdk 1.0.0-beta.1

package/dist/index-0NXfbk0z.d.ts

@@ -0,0 +1,637 @@
+import { RegisterSessionParams, RevokeSessionParams, SessionValidationResult, SessionKey as SessionKey$1, IdentityState } from './types.js';
+import { ethers } from 'ethers';
+import { C as ChainClient, a as ChainConfig, T as TransferParams, E as ExecuteParams, B as BridgeParams, W as WebAuthnSignature$1, D as DispatchResult, V as VaultCreationResult } from './types-ChIsqCiw.js';
+import { b as SessionConfig, d as SessionManagerConfig, S as SessionKey, A as ActionParams, c as SessionSignature, g as SessionSignedAction, f as SessionEventCallback } from './types-FJL7j6gQ.js';
+
+/**
+ * Veridex Protocol SDK - Passkey Manager
+ *
+ * Chain-agnostic WebAuthn/Passkey credential management
+ */
+interface PasskeyCredential {
+    credentialId: string;
+    publicKeyX: bigint;
+    publicKeyY: bigint;
+    keyHash: string;
+}
+interface WebAuthnSignature {
+    authenticatorData: string;
+    clientDataJSON: string;
+    challengeIndex: number;
+    typeIndex: number;
+    r: bigint;
+    s: bigint;
+}
+interface PasskeyManagerConfig {
+    rpName?: string;
+    rpId?: string;
+    timeout?: number;
+    userVerification?: 'required' | 'preferred' | 'discouraged';
+    authenticatorAttachment?: 'platform' | 'cross-platform';
+    /** Relayer API URL for cross-device credential recovery */
+    relayerUrl?: string;
+}
+/**
+ * Manages WebAuthn passkey credentials for Veridex Protocol
+ */
+declare class PasskeyManager {
+    private config;
+    private credential;
+    constructor(config?: PasskeyManagerConfig);
+    static isSupported(): boolean;
+    static isPlatformAuthenticatorAvailable(): Promise<boolean>;
+    register(username: string, displayName: string): Promise<PasskeyCredential>;
+    sign(challenge: Uint8Array): Promise<WebAuthnSignature>;
+    /**
+     * Authenticate using a discoverable credential (passkey)
+     * This allows sign-in without knowing the credential ID ahead of time.
+     * The authenticator will show all available passkeys for this RP.
+     *
+     * @param challenge - Optional challenge bytes. If not provided, a random challenge is used.
+     * @returns The credential that was used to authenticate, along with the signature
+     */
+    authenticate(challenge?: Uint8Array): Promise<{
+        credential: PasskeyCredential;
+        signature: WebAuthnSignature;
+    }>;
+    /**
+     * Load a credential by its ID from localStorage
+     * Used for discoverable credential authentication
+     */
+    private loadCredentialById;
+    /**
+     * Check if there's a stored credential for this RP
+     */
+    hasStoredCredential(key?: string): boolean;
+    getCredential(): PasskeyCredential | null;
+    setCredential(credential: PasskeyCredential): void;
+    createCredentialFromPublicKey(credentialId: string, publicKeyX: bigint, publicKeyY: bigint): PasskeyCredential;
+    clearCredential(): void;
+    saveToLocalStorage(key?: string): void;
+    loadFromLocalStorage(key?: string): PasskeyCredential | null;
+    removeFromLocalStorage(key?: string): void;
+    /**
+     * Save the current credential to the relayer for cross-device recovery.
+     * This should be called after registration.
+     */
+    saveCredentialToRelayer(): Promise<boolean>;
+    /**
+     * Load a credential from the relayer by credential ID.
+     * Used during discoverable credential authentication when localStorage is empty.
+     */
+    loadCredentialFromRelayer(credentialId: string): Promise<PasskeyCredential | null>;
+    /**
+     * Load a credential from the relayer by keyHash.
+     * Useful when you know the user's keyHash but not their credential ID.
+     */
+    loadCredentialFromRelayerByKeyHash(keyHash: string): Promise<PasskeyCredential | null>;
+    private extractPublicKeyFromAttestation;
+    private parseCOSEKey;
+    private tryParseCOSEKeyStrategies;
+    private parseCOSEKeyWithCBORStructure;
+    private tryParseASN1Structure;
+    private find32ByteSequences;
+    private isValidCoordinate;
+    private bytesToBigInt;
+    private bytesToHex;
+    private analyzeCOSEStructure;
+    private parseAuthenticationResponse;
+}
+
+/**
+ * Veridex Protocol SDK - Session Manager
+ *
+ * Manages ephemeral session keys for fast, native L1-speed transactions
+ * after initial biometric authentication.
+ *
+ * Key Features:
+ * - One-time Passkey auth to create session
+ * - Instant software-backed signing for subsequent transactions
+ * - Query-based validation on Spokes (no VAA wait)
+ * - ~400ms transactions after initial setup
+ * - Secure encrypted storage (AES-GCM)
+ * - Auto-refresh before expiry
+ * - Per-session value limits
+ */
+
+/**
+ * Interface for Hub contract interactions
+ *
+ * This should be implemented by chain clients (e.g., EVMHubClientAdapter).
+ */
+interface HubClient {
+    /**
+     * Register a session on the Hub
+     *
+     * @param params Registration parameters with Passkey signature
+     * @returns Promise that resolves when registration completes
+     */
+    registerSession(params: RegisterSessionParams): Promise<void>;
+    /**
+     * Revoke a session on the Hub
+     *
+     * @param params Revocation parameters with Passkey signature
+     * @returns Promise that resolves when revocation completes
+     */
+    revokeSession(params: RevokeSessionParams): Promise<void>;
+}
+/**
+ * Manages session key lifecycle and signing operations
+ *
+ * Usage:
+ * ```typescript
+ * const manager = new SessionManager(credential, hubClient, passkeySign, config);
+ *
+ * // Create session (requires biometric)
+ * const session = await manager.createSession();
+ *
+ * // Sign actions instantly (no biometric)
+ * const signature = await manager.signWithSession(action);
+ *
+ * // Revoke session (requires biometric)
+ * await manager.revokeSession();
+ * ```
+ */
+declare class SessionManager {
+    private credential;
+    private hubClient;
+    private passkeySign;
+    private currentSession;
+    private storage;
+    private config;
+    private refreshTimer;
+    private eventCallbacks;
+    private debug;
+    /**
+     * @param credential User's Passkey credential (for Hub interaction)
+     * @param hubClient Hub client for on-chain session operations
+     * @param passkeySign Function to sign challenges with Passkey
+     * @param config Session configuration
+     * @param managerConfig SessionManager configuration
+     */
+    constructor(credential: PasskeyCredential, hubClient: HubClient, passkeySign: (challenge: Uint8Array) => Promise<any>, config: Partial<SessionConfig>, managerConfig?: SessionManagerConfig);
+    /**
+     * Create a new session (requires biometric authentication)
+     *
+     * Steps:
+     * 1. Generate ephemeral secp256k1 key pair
+     * 2. Sign session registration with Passkey
+     * 3. Register session on Hub contract
+     * 4. Store session securely (encrypted)
+     * 5. Start auto-refresh timer (if enabled)
+     *
+     * @returns Created session key
+     * @throws SessionError if registration fails
+     */
+    createSession(): Promise<SessionKey>;
+    /**
+     * Load existing session from storage
+     *
+     * @returns Loaded session or null if no valid session exists
+     */
+    loadSession(): Promise<SessionKey | null>;
+    /**
+     * Revoke the current session (requires biometric authentication)
+     *
+     * @throws SessionError if no active session or revocation fails
+     */
+    revokeSession(): Promise<void>;
+    /**
+     * Sign an action with the session key (instant, no biometric)
+     *
+     * @param action Action parameters to sign
+     * @returns Session signature
+     * @throws SessionError if no active session, expired, or value exceeds limit
+     */
+    signWithSession(action: ActionParams): Promise<SessionSignature>;
+    /**
+     * Sign an action and prepare for submission
+     *
+     * @param action Action parameters
+     * @returns Session-signed action ready for submission
+     */
+    signAction(action: ActionParams): Promise<SessionSignedAction>;
+    /**
+     * Check if a session is currently active
+     *
+     * @returns True if an active, non-expired session exists
+     */
+    isActive(): boolean;
+    /**
+     * Get current session information (if active)
+     *
+     * @returns Current session or null
+     */
+    getSession(): SessionKey | null;
+    /**
+     * Get time remaining until session expiry (in seconds)
+     *
+     * @returns Seconds until expiry, or 0 if no active session
+     */
+    getTimeRemaining(): number;
+    /**
+     * Schedule automatic session refresh
+     */
+    private scheduleRefresh;
+    /**
+     * Refresh the current session (creates a new session)
+     *
+     * @returns New session key
+     */
+    refreshSession(): Promise<SessionKey>;
+    /**
+     * Register an event callback
+     */
+    on(callback: SessionEventCallback): void;
+    /**
+     * Unregister an event callback
+     */
+    off(callback: SessionEventCallback): void;
+    /**
+     * Emit a session event
+     */
+    private emit;
+    /**
+     * Log debug message (if debug enabled)
+     */
+    private log;
+    /**
+     * Cleanup resources
+     */
+    dispose(): void;
+}
+
+interface EVMClientConfig {
+    chainId: number;
+    wormholeChainId: number;
+    rpcUrl: string;
+    hubContractAddress: string;
+    wormholeCoreBridge: string;
+    name?: string;
+    explorerUrl?: string;
+    vaultFactory?: string;
+    vaultImplementation?: string;
+    tokenBridge?: string;
+}
+/**
+ * EVM implementation of the ChainClient interface
+ */
+declare class EVMClient implements ChainClient {
+    private config;
+    private provider;
+    private hubContract;
+    private factoryContract;
+    private cachedImplementation;
+    constructor(config: EVMClientConfig);
+    getConfig(): ChainConfig;
+    getNonce(userKeyHash: string): Promise<bigint>;
+    /**
+     * Get user state from Hub (Issue #9/#10)
+     * Returns comprehensive state including last action hash
+     */
+    getUserState(userKeyHash: string): Promise<{
+        keyHash: string;
+        nonce: bigint;
+        lastActionHash: string;
+    }>;
+    /**
+     * Get user's last action hash from Hub (Issue #9/#10)
+     * Returns zero hash if user has no actions yet
+     */
+    getUserLastActionHash(userKeyHash: string): Promise<string>;
+    /**
+     * Register a new session key for temporary authentication
+     * Enables native L1 speed for repeat transactions without biometric auth
+     *
+     * @param params Session registration parameters
+     * @param signer Ethereum signer to pay gas
+     * @returns Transaction receipt
+     */
+    registerSession(params: RegisterSessionParams, signer: ethers.Signer): Promise<ethers.TransactionReceipt>;
+    /**
+     * Check if a session is currently active (queryable via Wormhole CCQ)
+     *
+     * @param userKeyHash Hash of the user's Passkey public key
+     * @param sessionKeyHash Hash of the session key to check
+     * @returns Session validation result
+     */
+    isSessionActive(userKeyHash: string, sessionKeyHash: string): Promise<SessionValidationResult>;
+    /**
+     * Revoke a session key immediately
+     *
+     * @param params Session revocation parameters
+     * @param signer Ethereum signer to pay gas
+     * @returns Transaction receipt
+     */
+    revokeSession(params: RevokeSessionParams, signer: ethers.Signer): Promise<ethers.TransactionReceipt>;
+    /**
+     * Get all sessions for a user
+     *
+     * @param userKeyHash Hash of the user's Passkey public key
+     * @returns Array of all sessions (active and expired/revoked)
+     */
+    getUserSessions(userKeyHash: string): Promise<SessionKey$1[]>;
+    /**
+     * Get the number of sessions for a user
+     *
+     * @param userKeyHash Hash of the user's Passkey public key
+     * @returns Number of sessions
+     */
+    getUserSessionCount(userKeyHash: string): Promise<number>;
+    getMessageFee(): Promise<bigint>;
+    buildTransferPayload(params: TransferParams): Promise<string>;
+    buildExecutePayload(params: ExecuteParams): Promise<string>;
+    buildBridgePayload(params: BridgeParams): Promise<string>;
+    dispatch(signature: WebAuthnSignature$1, publicKeyX: bigint, publicKeyY: bigint, targetChain: number, actionPayload: string, nonce: bigint, signer: ethers.Signer): Promise<DispatchResult>;
+    /**
+     * Dispatch an action to the Hub via relayer (gasless)
+     * The relayer pays for gas and submits the transaction on behalf of the user
+     */
+    dispatchGasless(signature: WebAuthnSignature$1, publicKeyX: bigint, publicKeyY: bigint, targetChain: number, actionPayload: string, nonce: bigint, relayerUrl: string): Promise<DispatchResult>;
+    getVaultAddress(userKeyHash: string): Promise<string | null>;
+    /**
+     * Compute vault address deterministically without querying the chain
+     * Uses CREATE2 with EIP-1167 minimal proxy pattern
+     */
+    computeVaultAddress(userKeyHash: string): string;
+    /**
+     * Build EIP-1167 minimal proxy initcode
+     */
+    private buildProxyInitCode;
+    vaultExists(userKeyHash: string): Promise<boolean>;
+    createVault(userKeyHash: string, signer: ethers.Signer): Promise<VaultCreationResult>;
+    /**
+     * Create a vault with a sponsor wallet paying for gas
+     *
+     * @param userKeyHash - The user's passkey hash
+     * @param sponsorPrivateKey - Private key of the wallet that will pay gas
+     * @param rpcUrl - Optional RPC URL to use (defaults to client's RPC)
+     * @returns VaultCreationResult with address and transaction details
+     */
+    createVaultSponsored(userKeyHash: string, sponsorPrivateKey: string, rpcUrl?: string): Promise<VaultCreationResult>;
+    estimateVaultCreationGas(userKeyHash: string): Promise<bigint>;
+    getFactoryAddress(): string | undefined;
+    getImplementationAddress(): string | undefined;
+    /**
+     * Fetch implementation address from factory contract
+     */
+    fetchImplementationAddress(): Promise<string | null>;
+    /**
+     * Get the provider instance
+     */
+    getProvider(): ethers.JsonRpcProvider;
+    /**
+     * Get native token balance for an address
+     */
+    getNativeBalance(address: string): Promise<bigint>;
+    /**
+     * Get ERC20 token balance for an address
+     */
+    getTokenBalance(tokenAddress: string, ownerAddress: string): Promise<bigint>;
+    /**
+     * Get token allowance
+     */
+    getTokenAllowance(tokenAddress: string, ownerAddress: string, spenderAddress: string): Promise<bigint>;
+    /**
+     * Estimate gas for a dispatch transaction
+     */
+    estimateDispatchGas(signature: WebAuthnSignature$1, publicKeyX: bigint, publicKeyY: bigint, targetChain: number, actionPayload: string, nonce: bigint): Promise<bigint>;
+    /**
+     * Get current gas price
+     */
+    getGasPrice(): Promise<bigint>;
+    /**
+     * Get current block number
+     */
+    getBlockNumber(): Promise<number>;
+    /**
+     * Get transaction receipt
+     */
+    getTransactionReceipt(hash: string): Promise<ethers.TransactionReceipt | null>;
+    /**
+     * Wait for transaction confirmation
+     */
+    waitForTransaction(hash: string, confirmations?: number): Promise<ethers.TransactionReceipt | null>;
+    /**
+     * Get the identity for a given key hash
+     * Returns zero hash if key is not registered to any identity
+     *
+     * @param keyHash Hash of the passkey to look up
+     * @returns Identity (first passkey's keyHash) or zero hash
+     */
+    getIdentityForKey(keyHash: string): Promise<string>;
+    /**
+     * Get all authorized keys for an identity
+     *
+     * @param identity The identity key hash (first passkey's keyHash)
+     * @returns Array of authorized key hashes
+     */
+    getAuthorizedKeys(identity: string): Promise<string[]>;
+    /**
+     * Get count of authorized keys for an identity
+     *
+     * @param identity The identity key hash
+     * @returns Number of authorized keys
+     */
+    getAuthorizedKeyCount(identity: string): Promise<number>;
+    /**
+     * Check if a key is authorized for an identity
+     *
+     * @param identity The identity key hash
+     * @param keyHash The key hash to check
+     * @returns Whether the key is authorized
+     */
+    isAuthorizedForIdentity(identity: string, keyHash: string): Promise<boolean>;
+    /**
+     * Check if a key is the root identity key
+     *
+     * @param keyHash The key hash to check
+     * @returns Whether the key is a root identity
+     */
+    isIdentityRootKey(keyHash: string): Promise<boolean>;
+    /**
+     * Get comprehensive identity state for a key
+     *
+     * @param keyHash Hash of any key in the identity
+     * @returns Identity state including count, max, and root status
+     */
+    getIdentityState(keyHash: string): Promise<IdentityState>;
+    /**
+     * Register a new identity with the first passkey
+     * This makes the passkey the root identity key
+     *
+     * @param signature WebAuthn signature
+     * @param publicKeyX Passkey public key X coordinate
+     * @param publicKeyY Passkey public key Y coordinate
+     * @param signer Ethereum signer to pay gas
+     * @returns Transaction receipt and identity hash
+     */
+    registerIdentity(signature: WebAuthnSignature$1, publicKeyX: bigint, publicKeyY: bigint, signer: ethers.Signer): Promise<{
+        receipt: ethers.TransactionReceipt;
+        identity: string;
+    }>;
+    /**
+     * Add a backup passkey to an existing identity
+     * Requires WebAuthn signature from an authorized key
+     *
+     * @param signature WebAuthn signature from existing authorized key
+     * @param publicKeyX Existing key's X coordinate
+     * @param publicKeyY Existing key's Y coordinate
+     * @param newPublicKeyX New backup key's X coordinate
+     * @param newPublicKeyY New backup key's Y coordinate
+     * @param nonce Current nonce for the signing key
+     * @param signer Ethereum signer to pay gas
+     * @returns Transaction receipt and sequence number
+     */
+    addBackupKey(signature: WebAuthnSignature$1, publicKeyX: bigint, publicKeyY: bigint, newPublicKeyX: bigint, newPublicKeyY: bigint, nonce: bigint, signer: ethers.Signer): Promise<{
+        receipt: ethers.TransactionReceipt;
+        sequence: bigint;
+    }>;
+    /**
+     * Remove a passkey from an identity
+     * Cannot remove the last remaining key
+     *
+     * @param signature WebAuthn signature from an authorized key
+     * @param publicKeyX Signing key's X coordinate
+     * @param publicKeyY Signing key's Y coordinate
+     * @param keyToRemove Hash of the key to remove
+     * @param nonce Current nonce for the signing key
+     * @param signer Ethereum signer to pay gas
+     * @returns Transaction receipt and sequence number
+     */
+    removeKey(signature: WebAuthnSignature$1, publicKeyX: bigint, publicKeyY: bigint, keyToRemove: string, nonce: bigint, signer: ethers.Signer): Promise<{
+        receipt: ethers.TransactionReceipt;
+        sequence: bigint;
+    }>;
+    /**
+     * Setup guardians for an identity
+     * @param signature WebAuthn signature from owner
+     * @param publicKeyX Owner's public key X coordinate
+     * @param publicKeyY Owner's public key Y coordinate
+     * @param guardians Array of guardian key hashes
+     * @param threshold Required approvals for recovery
+     * @param signer Ethers signer for transaction
+     */
+    setupGuardians(signature: WebAuthnSignature$1, publicKeyX: bigint, publicKeyY: bigint, guardians: string[], threshold: bigint, signer: ethers.Signer): Promise<{
+        receipt: ethers.TransactionReceipt;
+        sequence: bigint;
+    }>;
+    /**
+     * Add a guardian to an identity
+     */
+    addGuardian(signature: WebAuthnSignature$1, publicKeyX: bigint, publicKeyY: bigint, guardianKeyHash: string, signer: ethers.Signer): Promise<{
+        receipt: ethers.TransactionReceipt;
+        sequence: bigint;
+    }>;
+    /**
+     * Remove a guardian from an identity
+     */
+    removeGuardian(signature: WebAuthnSignature$1, publicKeyX: bigint, publicKeyY: bigint, guardianKeyHash: string, signer: ethers.Signer): Promise<{
+        receipt: ethers.TransactionReceipt;
+        sequence: bigint;
+    }>;
+    /**
+     * Initiate recovery as a guardian
+     */
+    initiateRecovery(signature: WebAuthnSignature$1, publicKeyX: bigint, publicKeyY: bigint, identityToRecover: string, newOwnerKeyHash: string, signer: ethers.Signer): Promise<{
+        receipt: ethers.TransactionReceipt;
+        sequence: bigint;
+    }>;
+    /**
+     * Approve recovery as a guardian
+     */
+    approveRecovery(signature: WebAuthnSignature$1, publicKeyX: bigint, publicKeyY: bigint, identityToRecover: string, signer: ethers.Signer): Promise<{
+        receipt: ethers.TransactionReceipt;
+        sequence: bigint;
+    }>;
+    /**
+     * Execute recovery after timelock (anyone can call)
+     */
+    executeRecovery(identityToRecover: string, newPublicKeyX: bigint, newPublicKeyY: bigint, signer: ethers.Signer): Promise<{
+        receipt: ethers.TransactionReceipt;
+        sequence: bigint;
+    }>;
+    /**
+     * Cancel recovery as owner
+     */
+    cancelRecovery(signature: WebAuthnSignature$1, publicKeyX: bigint, publicKeyY: bigint, signer: ethers.Signer): Promise<{
+        receipt: ethers.TransactionReceipt;
+        sequence: bigint;
+    }>;
+    /**
+     * Get guardians for an identity
+     */
+    getGuardians(identityKeyHash: string): Promise<{
+        guardians: string[];
+        threshold: bigint;
+        isConfigured: boolean;
+    }>;
+    /**
+     * Get recovery status for an identity
+     */
+    getRecoveryStatus(identityKeyHash: string): Promise<{
+        isActive: boolean;
+        newOwnerKeyHash: string;
+        initiatedAt: bigint;
+        approvalCount: bigint;
+        threshold: bigint;
+        canExecuteAt: bigint;
+        expiresAt: bigint;
+    }>;
+    /**
+     * Check if a guardian has approved recovery
+     */
+    hasGuardianApproved(identityKeyHash: string, guardianKeyHash: string): Promise<boolean>;
+    /**
+     * Helper to extract sequence from transaction receipt
+     */
+    private _extractSequenceFromReceipt;
+}
+
+/**
+ * Veridex Protocol SDK - EVM Hub Client Adapter
+ *
+ * Adapts EVMClient to work with SessionManager's HubClient interface.
+ * Provides a clean integration layer between session management and chain clients.
+ */
+
+/**
+ * Adapter that makes EVMClient compatible with SessionManager's HubClient interface
+ *
+ * Usage:
+ * ```typescript
+ * const hubAdapter = new EVMHubClientAdapter(evmClient, signer);
+ * const sessionManager = new SessionManager(
+ *   credential,
+ *   hubAdapter,
+ *   config
+ * );
+ * ```
+ */
+declare class EVMHubClientAdapter implements HubClient {
+    private evmClient;
+    private signer;
+    constructor(evmClient: EVMClient, signer: ethers.Signer);
+    /**
+     * Register a session on the Hub
+     *
+     * @param params Registration parameters with Passkey signature
+     * @returns Promise that resolves when registration completes
+     */
+    registerSession(params: RegisterSessionParams): Promise<void>;
+    /**
+     * Revoke a session on the Hub
+     *
+     * @param params Revocation parameters with Passkey signature
+     * @returns Promise that resolves when revocation completes
+     */
+    revokeSession(params: RevokeSessionParams): Promise<void>;
+    /**
+     * Update the signer (e.g., when switching accounts)
+     *
+     * @param signer New Ethereum signer
+     */
+    updateSigner(signer: ethers.Signer): void;
+}
+
+export { EVMHubClientAdapter as E, type HubClient as H, PasskeyManager as P, SessionManager as S, EVMClient as a, type EVMClientConfig as b };