@ursalock/client 0.2.2

package/dist/index.d.ts

@@ -0,0 +1,583 @@
+import { ZKCredential } from '@z-base/zero-knowledge-credentials';
+export { ZKCredential } from '@z-base/zero-knowledge-credentials';
+
+/**
+ * Common types for auth
+ */
+
+/** User object returned by auth */
+interface User {
+    id: string;
+    email?: string;
+    createdAt: number;
+}
+/** Current authentication state */
+interface AuthState {
+    /** Whether user is authenticated */
+    isAuthenticated: boolean;
+    /** Current user (if authenticated) */
+    user: User | null;
+    /** Whether auth is still loading */
+    isLoading: boolean;
+    /** Auth error (if any) */
+    error: Error | null;
+    /** ZK Credential with derived keys (if authenticated with passkey) */
+    credential: ZKCredential | null;
+}
+/** Auth provider interface */
+interface AuthProvider {
+    /** Sign up a new user */
+    signUp(options: SignUpOptions): Promise<ZKAuthResult$1>;
+    /** Sign in an existing user */
+    signIn(options: SignInOptions): Promise<ZKAuthResult$1>;
+    /** Sign out the current user */
+    signOut(): Promise<void>;
+    /** Get current auth state */
+    getState(): AuthState;
+    /** Subscribe to auth state changes */
+    subscribe(callback: (state: AuthState) => void): () => void;
+}
+/** Sign up options */
+interface SignUpOptions {
+    email?: string;
+    password?: string;
+    /** Use passkey instead of email/password */
+    usePasskey?: boolean;
+}
+/** Sign in options */
+interface SignInOptions {
+    email?: string;
+    password?: string;
+    /** Use passkey instead of email/password */
+    usePasskey?: boolean;
+}
+/** Result of auth operations (legacy, for email/password) */
+interface AuthResult {
+    success: boolean;
+    user?: User;
+    token?: string;
+    error?: string;
+}
+/** Result of ZK auth operations (passkey with PRF) */
+interface ZKAuthResult$1 {
+    success: boolean;
+    user?: User;
+    token?: string;
+    /** ZK Credential with derived encryption keys */
+    credential?: ZKCredential;
+    error?: string;
+}
+
+/**
+ * Auth provider interfaces
+ * Follows Open/Closed Principle - easy to add new auth methods
+ * Follows Dependency Inversion - VaultClient depends on abstractions
+ */
+
+/**
+ * Extended auth result that includes optional ZK credential
+ * Used by providers that support zero-knowledge encryption (like passkey)
+ */
+interface ZKAuthResult extends AuthResult {
+    /** ZK credential with encryption keys (optional) */
+    credential?: ZKCredential;
+}
+/**
+ * Base auth provider interface
+ * All auth methods must implement this interface
+ */
+interface IAuthProvider {
+    /**
+     * Sign up a new user
+     * @param options Provider-specific signup options
+     * @returns Auth result with user and token
+     */
+    signUp(options: unknown): Promise<ZKAuthResult>;
+    /**
+     * Sign in an existing user
+     * @param options Provider-specific signin options
+     * @returns Auth result with user and token
+     */
+    signIn(options: unknown): Promise<ZKAuthResult>;
+    /**
+     * Check if this auth method is supported in the current environment
+     */
+    isSupported(): boolean;
+    /**
+     * Get the provider name/type
+     */
+    getName(): string;
+}
+/**
+ * Passkey-specific signup options
+ */
+interface PasskeySignUpOptions {
+    displayName?: string;
+}
+/**
+ * Email-specific signup options
+ */
+interface EmailSignUpOptions {
+    email: string;
+    password: string;
+}
+/**
+ * Email-specific signin options
+ */
+interface EmailSignInOptions {
+    email: string;
+    password: string;
+}
+
+/**
+ * HTTP client interface for VaultClient
+ * Follows Dependency Inversion Principle
+ */
+/**
+ * HTTP client interface
+ * Abstracts fetch API for testing and alternative implementations
+ */
+interface IHttpClient {
+    /**
+     * Make an HTTP request
+     * @param url Full URL or path (will be prefixed with serverUrl if path)
+     * @param options Fetch options
+     * @returns Response
+     */
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+/**
+ * Default fetch-based HTTP client
+ */
+declare class FetchHttpClient implements IHttpClient {
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+
+/**
+ * Passkey (WebAuthn PRF) Authentication
+ * Uses @z-base/zero-knowledge-credentials for PRF-based key derivation
+ *
+ * Refactored to follow SOLID principles:
+ * - Implements IAuthProvider interface (Dependency Inversion + Open/Closed)
+ * - Injectable HTTP client (Dependency Inversion)
+ */
+
+interface PasskeyAuthOptions {
+    /** Server URL for WebAuthn endpoints */
+    serverUrl: string;
+    /** RP (Relying Party) name shown to user */
+    rpName?: string;
+    /** HTTP client for making requests (default: FetchHttpClient) */
+    httpClient?: IHttpClient;
+}
+/**
+ * Passkey authentication using WebAuthn PRF extension
+ * Derives encryption keys directly from the passkey - no recovery key needed
+ * Implements IAuthProvider for pluggable auth (Open/Closed Principle)
+ */
+declare class PasskeyAuth implements IAuthProvider {
+    private options;
+    private httpClient;
+    constructor(options: PasskeyAuthOptions);
+    getName(): string;
+    /**
+     * Check if passkeys with PRF are supported in this browser
+     * Implements IAuthProvider.isSupported
+     */
+    isSupported(): boolean;
+    /**
+     * Check if passkeys with PRF are supported in this browser (static helper)
+     */
+    static isSupported(): boolean;
+    /**
+     * Sign up - Register a new passkey
+     * Creates a passkey with PRF extension and derives encryption keys
+     * Implements IAuthProvider.signUp
+     */
+    signUp(options: unknown): Promise<ZKAuthResult>;
+    /**
+     * Legacy method - kept for backward compatibility
+     * @deprecated Use signUp() instead
+     */
+    register(displayName?: string): Promise<ZKAuthResult>;
+    /**
+     * Sign in - Authenticate with an existing passkey
+     * Uses discoverCredential to authenticate and derive keys
+     * Implements IAuthProvider.signIn
+     */
+    signIn(_options: unknown): Promise<ZKAuthResult>;
+    /**
+     * Legacy method - kept for backward compatibility
+     * @deprecated Use signIn() instead
+     */
+    authenticate(): Promise<ZKAuthResult>;
+    /**
+     * Check if user has any registered passkeys
+     */
+    hasPasskey(opaqueId: string): Promise<boolean>;
+}
+
+/**
+ * Main Vault Client
+ * Combines auth (passkey + email) with API access
+ */
+
+interface VaultClientOptions {
+    /** Server URL */
+    serverUrl: string;
+    /** RP name for passkeys (default: 'ursalock') */
+    rpName?: string;
+    /** Prefer passkey over email (default: true) */
+    preferPasskey?: boolean;
+    /** Storage key for auth (default: 'ursalock:auth') */
+    storageKey?: string;
+}
+/**
+ * Unified client for ursalock auth and API
+ */
+declare class VaultClient {
+    private options;
+    private passkeyAuth;
+    private emailAuth;
+    private tokenManager;
+    private state;
+    private listeners;
+    constructor(options: VaultClientOptions);
+    /**
+     * Sign up a new user
+     */
+    signUp(options?: {
+        email?: string;
+        password?: string;
+        usePasskey?: boolean;
+        displayName?: string;
+    }): Promise<ZKAuthResult$1>;
+    /**
+     * Sign in an existing user
+     */
+    signIn(options?: {
+        email?: string;
+        password?: string;
+        usePasskey?: boolean;
+    }): Promise<ZKAuthResult$1>;
+    /**
+     * Sign out
+     */
+    signOut(): Promise<void>;
+    /**
+     * Check if passkeys are supported
+     */
+    supportsPasskey(): boolean;
+    /**
+     * Get current auth state
+     * Returns the same reference unless state changes (required for useSyncExternalStore)
+     */
+    getState(): AuthState;
+    /**
+     * Get current user
+     */
+    getUser(): User | null;
+    /**
+     * Get current ZK credential (with encryption keys)
+     */
+    getCredential(): ZKCredential | null;
+    /**
+     * Check if authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Subscribe to auth state changes
+     */
+    subscribe(callback: (state: AuthState) => void): () => void;
+    /**
+     * Get authorization header
+     */
+    getAuthHeader(): Record<string, string>;
+    /**
+     * Make authenticated API request
+     */
+    fetch(path: string, options?: RequestInit): Promise<Response>;
+    private initialize;
+    private handleAuthSuccess;
+    private handleTokenExpire;
+    private updateState;
+    private saveUserToStorage;
+    private loadUserFromStorage;
+    private clearUserFromStorage;
+}
+
+/**
+ * Email/Password Authentication (fallback)
+ * Note: Email auth doesn't provide PRF-derived encryption keys.
+ * For E2EE, use passkey authentication instead.
+ *
+ * Refactored to follow SOLID principles:
+ * - Implements IAuthProvider interface (Open/Closed + Dependency Inversion)
+ * - Injectable HTTP client (Dependency Inversion)
+ */
+
+interface EmailCredentials {
+    email: string;
+    password: string;
+}
+interface EmailAuthOptions {
+    /** Server URL for auth endpoints */
+    serverUrl: string;
+    /** HTTP client for making requests (default: FetchHttpClient) */
+    httpClient?: IHttpClient;
+}
+/**
+ * Email/password authentication (fallback for non-passkey browsers)
+ * Note: Email auth doesn't derive encryption keys - use passkeys for E2EE
+ * Implements IAuthProvider for pluggable auth (Open/Closed Principle)
+ */
+declare class EmailAuth implements IAuthProvider {
+    private options;
+    private httpClient;
+    constructor(options: EmailAuthOptions);
+    getName(): string;
+    isSupported(): boolean;
+    /**
+     * Sign up - Register a new account with email/password
+     * Implements IAuthProvider.signUp
+     */
+    signUp(options: unknown): Promise<ZKAuthResult>;
+    /**
+     * Sign in - Authenticate with email/password
+     * Implements IAuthProvider.signIn
+     */
+    signIn(options: unknown): Promise<ZKAuthResult>;
+    /**
+     * Legacy method - kept for backward compatibility
+     * @deprecated Use signUp() instead
+     */
+    register(credentials: EmailCredentials): Promise<ZKAuthResult>;
+    /**
+     * Request password reset email
+     */
+    forgotPassword(email: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Reset password with token
+     */
+    resetPassword(token: string, newPassword: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Change password (when logged in)
+     */
+    changePassword(currentPassword: string, newPassword: string, authToken: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Validate email format
+     */
+    private isValidEmail;
+}
+
+/**
+ * JWT Token Manager
+ * Handles token storage, refresh, and expiry
+ */
+interface Token {
+    /** JWT access token */
+    accessToken: string;
+    /** Token expiry timestamp (ms) */
+    expiresAt: number;
+    /** Refresh token (if available) */
+    refreshToken?: string;
+}
+interface TokenManagerOptions {
+    /** Storage key for token */
+    storageKey?: string;
+    /** Server URL for token refresh */
+    serverUrl?: string;
+    /** Callback when token expires (and refresh fails) */
+    onExpire?: () => void;
+    /** Refresh token before expiry (ms before expiry, default: 5min) */
+    refreshBuffer?: number;
+    /** Enable auto-refresh (default: true if serverUrl provided) */
+    autoRefresh?: boolean;
+}
+/**
+ * Manages JWT tokens with automatic refresh
+ */
+declare class TokenManager {
+    private token;
+    private refreshTimer;
+    private options;
+    private listeners;
+    private isRefreshing;
+    constructor(options?: TokenManagerOptions);
+    /**
+     * Set a new token
+     */
+    setToken(token: Token): void;
+    /**
+     * Get current token
+     */
+    getToken(): Token | null;
+    /**
+     * Get access token string (convenience method)
+     */
+    getAccessToken(): string | null;
+    /**
+     * Check if token is valid
+     */
+    isValid(): boolean;
+    /**
+     * Clear token
+     */
+    clearToken(): void;
+    /**
+     * Subscribe to token changes
+     */
+    subscribe(callback: (token: Token | null) => void): () => void;
+    /**
+     * Manually refresh the token
+     * Returns true if refresh succeeded
+     */
+    refresh(): Promise<boolean>;
+    /**
+     * Parse JWT payload (without verification)
+     */
+    static parseToken(token: string): Record<string, unknown> | null;
+    private loadFromStorage;
+    private saveToStorage;
+    private removeFromStorage;
+    private scheduleRefresh;
+    private clearRefreshTimer;
+    private notifyListeners;
+}
+
+/**
+ * Hook to subscribe to auth state from VaultClient
+ *
+ * @example
+ * ```tsx
+ * const client = new VaultClient({ serverUrl: '...' })
+ *
+ * function App() {
+ *   const { isAuthenticated, user, isLoading, credential } = useAuth(client)
+ *
+ *   if (isLoading) return <Loading />
+ *   if (!isAuthenticated) return <Login />
+ *   return <Dashboard user={user} credential={credential} />
+ * }
+ * ```
+ */
+declare function useAuth(client: VaultClient): AuthState;
+/**
+ * Hook for sign up action
+ * Returns ZKAuthResult with credential containing encryption keys
+ *
+ * @example
+ * ```tsx
+ * const { signUp, isLoading, error } = useSignUp(client)
+ *
+ * const handleSubmit = async () => {
+ *   const result = await signUp({ usePasskey: true })
+ *   if (result.success && result.credential) {
+ *     // Use credential.cipherJwk for encryption
+ *     initializeVault(result.credential.cipherJwk)
+ *   }
+ * }
+ * ```
+ */
+declare function useSignUp(client: VaultClient): {
+    signUp: (options?: {
+        email?: string;
+        password?: string;
+        usePasskey?: boolean;
+        displayName?: string;
+    }) => Promise<ZKAuthResult$1>;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * Hook for sign in action
+ * Returns ZKAuthResult with credential containing encryption keys
+ *
+ * @example
+ * ```tsx
+ * const { signIn, isLoading, error } = useSignIn(client)
+ *
+ * const handleLogin = async () => {
+ *   const result = await signIn({ usePasskey: true })
+ *   if (result.success && result.credential) {
+ *     // Use credential.cipherJwk for encryption
+ *     initializeVault(result.credential.cipherJwk)
+ *   }
+ * }
+ * ```
+ */
+declare function useSignIn(client: VaultClient): {
+    signIn: (options?: {
+        email?: string;
+        password?: string;
+        usePasskey?: boolean;
+    }) => Promise<ZKAuthResult$1>;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * Hook for sign out action
+ *
+ * @example
+ * ```tsx
+ * const signOut = useSignOut(client)
+ *
+ * <button onClick={signOut}>Sign Out</button>
+ * ```
+ */
+declare function useSignOut(client: VaultClient): () => Promise<void>;
+/**
+ * Hook for current user
+ * Returns null if not authenticated
+ *
+ * @example
+ * ```tsx
+ * const user = useUser(client)
+ *
+ * if (user) {
+ *   return <span>Hello, {user.email}</span>
+ * }
+ * ```
+ */
+declare function useUser(client: VaultClient): User | null;
+/**
+ * Hook for current ZK credential (encryption keys)
+ * Returns null if not authenticated or no credential available
+ *
+ * @example
+ * ```tsx
+ * const credential = useCredential(client)
+ *
+ * if (credential) {
+ *   // credential.cipherJwk - AES-GCM key for encryption
+ *   // credential.hmacJwk - HMAC key for signing
+ * }
+ * ```
+ */
+declare function useCredential(client: VaultClient): ZKCredential | null;
+/**
+ * Hook to check passkey support
+ *
+ * @example
+ * ```tsx
+ * const supportsPasskey = usePasskeySupport(client)
+ *
+ * {supportsPasskey ? (
+ *   <PasskeyButton />
+ * ) : (
+ *   <EmailPasswordForm />
+ * )}
+ * ```
+ */
+declare function usePasskeySupport(client: VaultClient): boolean;
+
+export { type AuthProvider, type AuthResult, type AuthState, EmailAuth, type EmailAuthOptions, type EmailCredentials, type EmailSignInOptions, type EmailSignUpOptions, FetchHttpClient, type IAuthProvider, type IHttpClient, PasskeyAuth, type PasskeyAuthOptions, type PasskeySignUpOptions, type Token, TokenManager, type TokenManagerOptions, type User, VaultClient, type VaultClientOptions, type ZKAuthResult, useAuth, useCredential, usePasskeySupport, useSignIn, useSignOut, useSignUp, useUser };