kentucky-signer-viem 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,603 @@
+import { Address, Hex, LocalAccount } from 'viem';
+
+/**
+ * Configuration for Kentucky Signer client
+ */
+interface KentuckySignerConfig {
+    /** Base URL of the Kentucky Signer API (e.g., "https://signer.example.com") */
+    baseUrl: string;
+    /** Account ID (64-character hex string) */
+    accountId: string;
+}
+/**
+ * Authenticated session with Kentucky Signer
+ */
+interface AuthSession {
+    /** JWT access token */
+    token: string;
+    /** Account ID this session is authenticated for */
+    accountId: string;
+    /** EVM address derived from the account */
+    evmAddress: Address;
+    /** Bitcoin address derived from the account */
+    btcAddress?: string;
+    /** Solana address derived from the account */
+    solAddress?: string;
+    /** Token expiration timestamp (Unix ms) */
+    expiresAt: number;
+}
+/**
+ * Challenge response from Kentucky Signer
+ */
+interface ChallengeResponse {
+    success: boolean;
+    challenge: string;
+    expires_at: number;
+}
+/**
+ * Authentication response from Kentucky Signer
+ */
+interface AuthResponse {
+    success: boolean;
+    token: string;
+    expires_in: number;
+    account_id: string;
+}
+/**
+ * Account info response from Kentucky Signer
+ */
+interface AccountInfoResponse {
+    success: boolean;
+    account_id: string;
+    addresses: {
+        evm: string;
+        bitcoin: string;
+        solana: string;
+    };
+    passkeys: Array<{
+        credential_id: string;
+        created_at: number;
+    }>;
+}
+/**
+ * EVM signature response from Kentucky Signer
+ */
+interface EvmSignatureResponse {
+    success: boolean;
+    signature: {
+        r: Hex;
+        s: Hex;
+        v: number;
+        full: Hex;
+    };
+    chain_id: number;
+    signer_address: string;
+}
+/**
+ * Error response from Kentucky Signer API
+ */
+interface ApiErrorResponse {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        details?: string;
+    };
+}
+/**
+ * WebAuthn credential for passkey authentication
+ */
+interface PasskeyCredential {
+    /** Credential ID (base64url encoded) */
+    credentialId: string;
+    /** Client data JSON (base64url encoded) */
+    clientDataJSON: string;
+    /** Authenticator data (base64url encoded) */
+    authenticatorData: string;
+    /** Signature (base64url encoded) */
+    signature: string;
+    /** User handle (base64url encoded, optional) */
+    userHandle?: string;
+}
+/**
+ * Options for passkey authentication
+ */
+interface PasskeyAuthOptions {
+    /** Base URL of the Kentucky Signer API */
+    baseUrl: string;
+    /** Account ID to authenticate */
+    accountId: string;
+    /** Relying Party ID for WebAuthn (defaults to current domain) */
+    rpId?: string;
+    /** Credential IDs to allow (if known) */
+    allowCredentials?: string[];
+}
+/**
+ * Token storage interface for custom token persistence
+ */
+interface TokenStorage {
+    /** Get stored token */
+    getToken(): Promise<string | null>;
+    /** Store token */
+    setToken(token: string, expiresAt: number): Promise<void>;
+    /** Clear stored token */
+    clearToken(): Promise<void>;
+}
+/**
+ * Kentucky Signer client options
+ */
+interface ClientOptions {
+    /** Base URL of the Kentucky Signer API */
+    baseUrl: string;
+    /** Custom fetch implementation (for Node.js or testing) */
+    fetch?: typeof fetch;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Sign EVM transaction request
+ */
+interface SignEvmRequest {
+    /** Transaction hash to sign (32 bytes, hex encoded) */
+    tx_hash: Hex;
+    /** Chain ID */
+    chain_id: number;
+}
+/**
+ * Passkey registration options (for account creation)
+ */
+interface PasskeyRegistrationOptions {
+    /** Base URL of the Kentucky Signer API */
+    baseUrl: string;
+    /** Username for the account */
+    username?: string;
+    /** Relying Party ID for WebAuthn (defaults to current domain) */
+    rpId?: string;
+    /** Relying Party name for WebAuthn */
+    rpName?: string;
+}
+/**
+ * Account creation response
+ */
+interface AccountCreationResponse {
+    success: boolean;
+    account_id: string;
+    addresses: {
+        evm: string;
+        bitcoin: string;
+        solana: string;
+    };
+}
+/**
+ * Options for password authentication
+ */
+interface PasswordAuthOptions {
+    /** Base URL of the Kentucky Signer API */
+    baseUrl: string;
+    /** Account ID to authenticate */
+    accountId: string;
+    /** Password for authentication */
+    password: string;
+}
+/**
+ * Options for creating an account with password
+ */
+interface PasswordAccountCreationOptions {
+    /** Base URL of the Kentucky Signer API */
+    baseUrl: string;
+    /** Password for the account (8-128 characters) */
+    password: string;
+    /** Password confirmation (must match password) */
+    confirmation: string;
+}
+/**
+ * Password account creation request
+ */
+interface CreatePasswordAccountRequest {
+    /** Password for the account */
+    password: string;
+    /** Password confirmation */
+    confirmation: string;
+}
+/**
+ * Password authentication request
+ */
+interface PasswordAuthRequest {
+    /** Account ID */
+    account_id: string;
+    /** Password */
+    password: string;
+}
+
+/**
+ * Options for creating a Kentucky Signer account
+ */
+interface KentuckySignerAccountOptions {
+    /** Kentucky Signer configuration */
+    config: KentuckySignerConfig;
+    /** Authenticated session */
+    session: AuthSession;
+    /** Default chain ID for signing (can be overridden per-transaction) */
+    defaultChainId?: number;
+    /** Callback when session needs refresh */
+    onSessionExpired?: () => Promise<AuthSession>;
+}
+/**
+ * Extended account type with Kentucky Signer specific properties
+ */
+interface KentuckySignerAccount extends LocalAccount<'kentuckySigner'> {
+    /** Account ID */
+    accountId: string;
+    /** Current session */
+    session: AuthSession;
+    /** Update the session (e.g., after refresh) */
+    updateSession: (session: AuthSession) => void;
+}
+/**
+ * Create a custom Viem account backed by Kentucky Signer
+ *
+ * This account implementation uses the Kentucky Signer API to sign
+ * transactions, messages, and typed data using passkey authentication.
+ *
+ * @param options - Account options
+ * @returns Viem-compatible account
+ *
+ * @example
+ * ```typescript
+ * const account = createKentuckySignerAccount({
+ *   config: {
+ *     baseUrl: 'https://signer.example.com',
+ *     accountId: '0x...',
+ *   },
+ *   session: authenticatedSession,
+ *   defaultChainId: 1,
+ * })
+ *
+ * const walletClient = createWalletClient({
+ *   account,
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ *
+ * const hash = await walletClient.sendTransaction({
+ *   to: '0x...',
+ *   value: parseEther('0.1'),
+ * })
+ * ```
+ */
+declare function createKentuckySignerAccount(options: KentuckySignerAccountOptions): KentuckySignerAccount;
+/**
+ * Create a Kentucky Signer account for server-side use
+ *
+ * Convenience function for Node.js environments where you have
+ * a pre-existing JWT token.
+ *
+ * @param baseUrl - Kentucky Signer API URL
+ * @param accountId - Account ID
+ * @param token - JWT token
+ * @param evmAddress - EVM address for the account
+ * @param chainId - Default chain ID
+ * @returns Kentucky Signer account
+ */
+declare function createServerAccount(baseUrl: string, accountId: string, token: string, evmAddress: Address, chainId?: number): KentuckySignerAccount;
+
+/**
+ * Kentucky Signer API error
+ */
+declare class KentuckySignerError extends Error {
+    code: string;
+    details?: string | undefined;
+    constructor(message: string, code: string, details?: string | undefined);
+}
+/**
+ * Kentucky Signer API client
+ *
+ * Handles communication with the Kentucky Signer API for authentication,
+ * account management, and transaction signing.
+ */
+declare class KentuckySignerClient {
+    private baseUrl;
+    private fetchImpl;
+    private timeout;
+    constructor(options: ClientOptions);
+    /**
+     * Make an authenticated request to the API
+     */
+    private request;
+    /**
+     * Get a challenge for passkey authentication
+     *
+     * @param accountId - Account ID to authenticate
+     * @returns Challenge response with 32-byte challenge
+     */
+    getChallenge(accountId: string): Promise<ChallengeResponse>;
+    /**
+     * Authenticate with a passkey credential
+     *
+     * @param accountId - Account ID to authenticate
+     * @param credential - WebAuthn credential from navigator.credentials.get()
+     * @returns Authentication response with JWT token
+     */
+    authenticatePasskey(accountId: string, credential: PasskeyCredential): Promise<AuthResponse>;
+    /**
+     * Refresh an authentication token
+     *
+     * @param token - Current JWT token
+     * @returns New authentication response with fresh token
+     */
+    refreshToken(token: string): Promise<AuthResponse>;
+    /**
+     * Logout and invalidate token
+     *
+     * @param token - JWT token to invalidate
+     */
+    logout(token: string): Promise<void>;
+    /**
+     * Get account information
+     *
+     * @param accountId - Account ID
+     * @param token - JWT token
+     * @returns Account info with addresses and passkeys
+     */
+    getAccountInfo(accountId: string, token: string): Promise<AccountInfoResponse>;
+    /**
+     * Check if an account exists
+     *
+     * @param accountId - Account ID
+     * @param token - JWT token
+     * @returns True if account exists
+     */
+    accountExists(accountId: string, token: string): Promise<boolean>;
+    /**
+     * Sign an EVM transaction hash
+     *
+     * @param request - Sign request with tx_hash and chain_id
+     * @param token - JWT token
+     * @returns Signature response with r, s, v components
+     */
+    signEvmTransaction(request: SignEvmRequest, token: string): Promise<EvmSignatureResponse>;
+    /**
+     * Sign a raw hash for EVM
+     *
+     * Convenience method that wraps signEvmTransaction.
+     *
+     * @param hash - 32-byte hash to sign (hex encoded with 0x prefix)
+     * @param chainId - Chain ID
+     * @param token - JWT token
+     * @returns Full signature (hex encoded with 0x prefix)
+     */
+    signHash(hash: Hex, chainId: number, token: string): Promise<Hex>;
+    /**
+     * Create a new account with passkey authentication
+     *
+     * @param credential - WebAuthn credential from navigator.credentials.create()
+     * @returns Account creation response with account ID and addresses
+     */
+    createAccountWithPasskey(credential: PasskeyCredential & {
+        publicKey: string;
+    }): Promise<AccountCreationResponse>;
+    /**
+     * Create a new account with password authentication
+     *
+     * @param request - Password and confirmation
+     * @returns Account creation response with account ID and addresses
+     */
+    createAccountWithPassword(request: CreatePasswordAccountRequest): Promise<AccountCreationResponse>;
+    /**
+     * Authenticate with password
+     *
+     * @param request - Account ID and password
+     * @returns Authentication response with JWT token
+     */
+    authenticatePassword(request: PasswordAuthRequest): Promise<AuthResponse>;
+    /**
+     * Health check
+     *
+     * @returns True if the API is healthy
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Get API version
+     *
+     * @returns Version string
+     */
+    getVersion(): Promise<string>;
+}
+/**
+ * Create a new Kentucky Signer client
+ *
+ * @param options - Client options
+ * @returns Kentucky Signer client instance
+ */
+declare function createClient(options: ClientOptions): KentuckySignerClient;
+
+/**
+ * Check if WebAuthn is available in the current environment
+ */
+declare function isWebAuthnAvailable(): boolean;
+/**
+ * In-memory token storage (default implementation)
+ */
+declare class MemoryTokenStorage implements TokenStorage {
+    private token;
+    private expiresAt;
+    getToken(): Promise<string | null>;
+    setToken(token: string, expiresAt: number): Promise<void>;
+    clearToken(): Promise<void>;
+}
+/**
+ * Browser localStorage token storage
+ */
+declare class LocalStorageTokenStorage implements TokenStorage {
+    private keyPrefix;
+    constructor(keyPrefix?: string);
+    getToken(): Promise<string | null>;
+    setToken(token: string, expiresAt: number): Promise<void>;
+    clearToken(): Promise<void>;
+}
+/**
+ * Authenticate with a passkey (browser only)
+ *
+ * This function handles the full WebAuthn authentication flow:
+ * 1. Request a challenge from the Kentucky Signer
+ * 2. Prompt the user to authenticate with their passkey
+ * 3. Send the credential to the Kentucky Signer
+ * 4. Return an authenticated session
+ *
+ * @param options - Passkey authentication options
+ * @returns Authenticated session
+ */
+declare function authenticateWithPasskey(options: PasskeyAuthOptions): Promise<AuthSession>;
+/**
+ * Create an authenticated session from an existing JWT token (Node.js compatible)
+ *
+ * Use this for server-side applications where you already have a JWT token.
+ *
+ * @param baseUrl - Kentucky Signer API URL
+ * @param accountId - Account ID
+ * @param token - JWT token
+ * @param expiresAt - Token expiration timestamp (Unix ms), optional
+ * @returns Authenticated session
+ */
+declare function authenticateWithToken(baseUrl: string, accountId: string, token: string, expiresAt?: number): Promise<AuthSession>;
+/**
+ * Register a new passkey for account creation (browser only)
+ *
+ * @param options - Registration options
+ * @returns Registration credential with public key
+ */
+declare function registerPasskey(options: PasskeyRegistrationOptions): Promise<PasskeyCredential & {
+    publicKey: string;
+}>;
+/**
+ * Check if a session is still valid
+ *
+ * @param session - Session to check
+ * @param bufferMs - Buffer time before expiration (default 60 seconds)
+ * @returns True if session is valid
+ */
+declare function isSessionValid(session: AuthSession, bufferMs?: number): boolean;
+/**
+ * Refresh a session if needed
+ *
+ * @param session - Current session
+ * @param baseUrl - Kentucky Signer API URL
+ * @param bufferMs - Buffer time before expiration (default 60 seconds)
+ * @returns Updated session (or original if still valid)
+ */
+declare function refreshSessionIfNeeded(session: AuthSession, baseUrl: string, bufferMs?: number): Promise<AuthSession>;
+/**
+ * Authenticate with password (works in browser and Node.js)
+ *
+ * @param options - Password authentication options
+ * @returns Authenticated session
+ *
+ * @example
+ * ```typescript
+ * const session = await authenticateWithPassword({
+ *   baseUrl: 'https://signer.example.com',
+ *   accountId: '0123456789abcdef...',
+ *   password: 'your-secure-password',
+ * })
+ * ```
+ */
+declare function authenticateWithPassword(options: PasswordAuthOptions): Promise<AuthSession>;
+/**
+ * Create a new account with password authentication (works in browser and Node.js)
+ *
+ * @param options - Account creation options with password
+ * @returns Account creation response with account ID and addresses
+ *
+ * @example
+ * ```typescript
+ * const account = await createAccountWithPassword({
+ *   baseUrl: 'https://signer.example.com',
+ *   password: 'your-secure-password',
+ *   confirmation: 'your-secure-password',
+ * })
+ * console.log('Account ID:', account.account_id)
+ * console.log('EVM Address:', account.addresses.evm)
+ * ```
+ */
+declare function createAccountWithPassword(options: PasswordAccountCreationOptions): Promise<AccountCreationResponse>;
+
+/**
+ * Utility functions for Kentucky Signer Viem integration
+ */
+/**
+ * Base64URL encode a Uint8Array
+ *
+ * @param data - Data to encode
+ * @returns Base64URL encoded string (no padding)
+ */
+declare function base64UrlEncode(data: Uint8Array): string;
+/**
+ * Base64URL decode a string to Uint8Array
+ *
+ * @param str - Base64URL encoded string
+ * @returns Decoded bytes
+ */
+declare function base64UrlDecode(str: string): Uint8Array;
+/**
+ * Convert a hex string to Uint8Array
+ *
+ * @param hex - Hex string (with or without 0x prefix)
+ * @returns Byte array
+ */
+declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Convert a Uint8Array to hex string
+ *
+ * @param bytes - Byte array
+ * @param withPrefix - Include 0x prefix (default: true)
+ * @returns Hex string
+ */
+declare function bytesToHex(bytes: Uint8Array, withPrefix?: boolean): string;
+/**
+ * Validate an account ID format
+ *
+ * Account IDs are 64-character hex strings (32 bytes).
+ *
+ * @param accountId - Account ID to validate
+ * @returns True if valid
+ */
+declare function isValidAccountId(accountId: string): boolean;
+/**
+ * Validate an EVM address format
+ *
+ * @param address - Address to validate
+ * @returns True if valid
+ */
+declare function isValidEvmAddress(address: string): boolean;
+/**
+ * Retry a function with exponential backoff
+ *
+ * @param fn - Function to retry
+ * @param maxRetries - Maximum number of retries (default: 3)
+ * @param baseDelay - Base delay in ms (default: 1000)
+ * @returns Result of the function
+ */
+declare function withRetry<T>(fn: () => Promise<T>, maxRetries?: number, baseDelay?: number): Promise<T>;
+/**
+ * Parse a JWT token (without validation)
+ *
+ * @param token - JWT token string
+ * @returns Decoded payload
+ */
+declare function parseJwt(token: string): Record<string, unknown>;
+/**
+ * Get JWT expiration time
+ *
+ * @param token - JWT token string
+ * @returns Expiration timestamp in milliseconds, or null if no exp claim
+ */
+declare function getJwtExpiration(token: string): number | null;
+/**
+ * Format an error for display
+ *
+ * @param error - Error to format
+ * @returns Formatted error message
+ */
+declare function formatError(error: unknown): string;
+
+export { type AccountCreationResponse, type AccountInfoResponse, type ApiErrorResponse, type AuthResponse, type AuthSession, type ChallengeResponse, type ClientOptions, type CreatePasswordAccountRequest, type EvmSignatureResponse, type KentuckySignerAccount, type KentuckySignerAccountOptions, KentuckySignerClient, type KentuckySignerConfig, KentuckySignerError, LocalStorageTokenStorage, MemoryTokenStorage, type PasskeyAuthOptions, type PasskeyCredential, type PasskeyRegistrationOptions, type PasswordAccountCreationOptions, type PasswordAuthOptions, type PasswordAuthRequest, type SignEvmRequest, type TokenStorage, authenticateWithPasskey, authenticateWithPassword, authenticateWithToken, base64UrlDecode, base64UrlEncode, bytesToHex, createAccountWithPassword, createClient, createKentuckySignerAccount, createServerAccount, formatError, getJwtExpiration, hexToBytes, isSessionValid, isValidAccountId, isValidEvmAddress, isWebAuthnAvailable, parseJwt, refreshSessionIfNeeded, registerPasskey, withRetry };