mulguard 1.1.2 → 1.1.4

package/dist/core/types/index.d.ts

@@ -1,398 +1,462 @@
+import { User, Session, AuthResult, SuccessfulAuthResult, FailedAuthResult, TwoFactorAuthResult, EmailCredentials, RegisterData, Verify2FAData } from './auth';
 /**
- * Core types for Mulguard Authentication Library
- * Server Actions-based architecture with custom logic support
+ * Core type definitions for Mulguard Authentication Library
+ *
+ * @module @mulguard/core/types
+ * @see {@link https://github.com/mulguard/mulguard} for documentation
  */
 export * from './auth';
 export * from './errors';
 /**
- * API Client interface for making HTTP requests
- * Used internally by some auth methods
+ * Generic HTTP client interface for making API requests.
+ *
+ * @template TResponse - Response data type
+ * @template TRequest - Request data type (optional)
+ *
+ * @example
+ * ```typescript
+ * const client: ApiClient = {
+ *   get: async <T>(url: string) => ({ data: await fetch(url).then(r => r.json()) as T }),
+ *   post: async <T>(url: string, data?: unknown) => ({ data: await fetch(url, { method: 'POST', body: JSON.stringify(data) }).then(r => r.json()) as T }),
+ *   // ...
+ * }
+ * ```
  */
 export interface ApiClient {
-    get: <T>(url: string, config?: unknown) => Promise<{
-        data: T;
+    /** GET request */
+    get: <TResponse = unknown>(url: string, config?: unknown) => Promise<{
+        data: TResponse;
     }>;
-    post: <T>(url: string, data?: unknown, config?: unknown) => Promise<{
-        data: T;
+    /** POST request */
+    post: <TResponse = unknown, TRequest = unknown>(url: string, data?: TRequest, config?: unknown) => Promise<{
+        data: TResponse;
     }>;
-    put: <T>(url: string, data?: unknown, config?: unknown) => Promise<{
-        data: T;
+    /** PUT request */
+    put: <TResponse = unknown, TRequest = unknown>(url: string, data?: TRequest, config?: unknown) => Promise<{
+        data: TResponse;
     }>;
-    delete: <T>(url: string, config?: unknown) => Promise<{
-        data: T;
+    /** DELETE request */
+    delete: <TResponse = unknown>(url: string, config?: unknown) => Promise<{
+        data: TResponse;
     }>;
 }
 /**
- * Remembered user for account picker
+ * Authentication provider type.
+ */
+export type AuthProvider = 'email' | 'oauth' | 'passkey';
+/**
+ * Remembered user information for account picker functionality.
+ *
+ * @property userId - Unique user identifier
+ * @property email - User email address
+ * @property name - User display name
+ * @property avatar - Optional avatar URL
+ * @property provider - Authentication provider used
+ * @property lastLoginAt - Timestamp of last login
  */
 export interface RememberedUser {
-    userId: string;
-    email: string;
-    name: string;
-    avatar?: string;
-    provider: 'email' | 'oauth' | 'passkey';
-    lastLoginAt: Date;
+    readonly userId: string;
+    readonly email: string;
+    readonly name: string;
+    readonly avatar?: string;
+    readonly provider: AuthProvider;
+    readonly lastLoginAt: Date;
 }
 /**
- * OAuth Provider Configuration (auth.js-like)
- * Simple configuration - just clientId and clientSecret
+ * OAuth provider configuration.
+ *
+ * @property clientId - OAuth client identifier (required)
+ * @property clientSecret - OAuth client secret (server-side only, optional)
+ * @property redirectUri - Custom redirect URI (auto-generated if not provided)
+ * @property scopes - OAuth scopes (defaults provided per provider)
+ * @property params - Additional OAuth parameters
  */
 export interface OAuthProviderConfig {
-    /** OAuth client ID */
-    clientId: string;
-    /** OAuth client secret (server-side only) */
-    clientSecret?: string;
-    /** Custom redirect URI (optional, auto-generated if not provided) */
-    redirectUri?: string;
-    /** Custom scopes (optional, defaults provided) */
-    scopes?: string[];
-    /** Additional parameters */
-    params?: Record<string, string>;
+    readonly clientId: string;
+    readonly clientSecret?: string;
+    readonly redirectUri?: string;
+    readonly scopes?: readonly string[];
+    readonly params?: Readonly<Record<string, string>>;
 }
 /**
- * OAuth Providers Configuration
- * Simple auth.js-like interface
+ * OAuth providers configuration map.
+ *
+ * Supports built-in providers (google, github, apple, facebook) and custom providers.
+ *
+ * @example
+ * ```typescript
+ * const providers: OAuthProvidersConfig = {
+ *   google: { clientId: '...', clientSecret: '...' },
+ *   custom: { clientId: '...', scopes: ['read', 'write'] }
+ * }
+ * ```
  */
 export interface OAuthProvidersConfig {
-    google?: OAuthProviderConfig;
-    github?: OAuthProviderConfig;
-    apple?: OAuthProviderConfig;
-    facebook?: OAuthProviderConfig;
-    [key: string]: OAuthProviderConfig | undefined;
-}
-/**
- * Main configuration for Mulguard
- * User provides custom logic for each authentication method
- */
-export interface MulguardConfig {
-    /** Session configuration */
-    session?: SessionConfig;
-    /** Custom authentication logic - user writes their own implementation */
-    actions: AuthActions;
-    /** Callbacks for lifecycle events */
-    callbacks?: CallbacksConfig;
-    /** Security configuration */
-    security?: SecurityConfig;
-    /** Token refresh configuration */
-    tokenRefresh?: import('../client/token-refresh-manager').TokenRefreshConfig;
-    /** ✅ NEW: OAuth providers configuration (auth.js-like) */
-    providers?: {
-        oauth?: OAuthProvidersConfig;
-    };
-    /** ✅ NEW: OAuth state store (for production, use Redis/database-backed store) */
-    oauthStateStore?: import('../auth/oauth-state-store').OAuthStateStore;
-    /** ✅ NEW: Session cache TTL in milliseconds (default: 5000) */
-    sessionCacheTtl?: number;
+    readonly google?: OAuthProviderConfig;
+    readonly github?: OAuthProviderConfig;
+    readonly apple?: OAuthProviderConfig;
+    readonly facebook?: OAuthProviderConfig;
+    readonly [key: string]: OAuthProviderConfig | undefined;
 }
 /**
- * Sign in options for unified signIn interface
+ * OAuth token response from provider.
+ *
+ * @property access_token - Access token (required)
+ * @property refresh_token - Refresh token (optional)
+ * @property expires_in - Token expiration in seconds (optional)
+ * @property token_type - Token type, typically 'Bearer' (optional)
+ * @property id_token - ID token for OpenID Connect (optional)
+ * @property scope - Granted scopes (optional)
  */
-export type SignInProvider = 'google' | 'github' | 'apple' | 'facebook' | string;
-export interface SignInOptions {
-    provider: SignInProvider | 'credentials' | 'passkey' | 'otp';
-    credentials?: EmailCredentials;
-    formData?: FormData;
-    options?: {
-        userId?: string;
-        email?: string;
-        code?: string;
-    };
+export interface OAuthTokens {
+    readonly access_token: string;
+    readonly refresh_token?: string;
+    readonly expires_in?: number;
+    readonly token_type?: string;
+    readonly id_token?: string;
+    readonly scope?: string;
 }
 /**
- * Custom authentication actions - user implements these
- * All actions are Server Actions that run on the server
+ * Enhanced OAuth user information with tokens and provider metadata.
+ *
+ * This interface extends basic user info with OAuth-specific data required for
+ * backend API integration and advanced use cases.
+ *
+ * @property id - User ID from OAuth provider
+ * @property email - User email from OAuth provider
+ * @property name - User display name
+ * @property avatar - User avatar URL (optional)
+ * @property emailVerified - Email verification status (optional)
+ * @property provider - OAuth provider identifier (e.g., 'google', 'github')
+ * @property accessToken - OAuth access token (required for backend API)
+ * @property refreshToken - OAuth refresh token (optional)
+ * @property tokens - Complete OAuth tokens object
+ * @property rawProfile - Raw profile data from provider (for advanced use)
+ *
+ * @example
+ * ```typescript
+ * callbacks: {
+ *   onOAuthUser: async (userInfo) => {
+ *     // userInfo.accessToken available for backend API calls
+ *     // userInfo.rawProfile available for provider-specific data
+ *     return await createOrUpdateUser(userInfo)
+ *   }
+ * }
+ * ```
  */
-export interface AuthActions {
-    /**
-     * Sign in actions
-     */
-    signIn: {
-        /**
-         * Email/password sign in
-         * User implements custom logic here
-         */
-        email: (credentials: EmailCredentials) => Promise<AuthResult>;
-        /**
-         * OAuth sign in initiation
-         * Returns authorization URL and state
-         */
-        oauth?: (provider: string) => Promise<{
-            url: string;
-            state: string;
-        }>;
-        /**
-         * PassKey/WebAuthn sign in
-         */
-        passkey?: (options?: {
-            userId?: string;
-        }) => Promise<AuthResult>;
-        /**
-         * OTP sign in
-         */
-        otp?: (email: string, code?: string) => Promise<AuthResult>;
-    };
-    /**
-     * Sign up new user
-     * User implements custom logic here
-     */
-    signUp?: (data: RegisterData) => Promise<AuthResult>;
-    /**
-     * Sign out current session
-     * User implements custom logic here
-     */
-    signOut?: () => Promise<{
-        success: boolean;
-        error?: string;
-    }>;
-    /**
-     * Request password reset
-     * User implements custom logic here
-     */
-    resetPassword?: (email: string) => Promise<{
-        success: boolean;
-        error?: string;
-    }>;
-    /**
-     * Verify email address
-     * User implements custom logic here
-     */
-    verifyEmail?: (token: string) => Promise<{
-        success: boolean;
-        error?: string;
-    }>;
-    /**
-     * Get current session
-     * User implements custom logic here
-     */
-    getSession?: () => Promise<Session | null>;
-    /**
-     * Refresh session
-     * User implements custom logic here
-     */
-    refreshSession?: () => Promise<Session | null>;
-    /**
-     * OAuth callback handler
-     * User implements custom logic here
-     */
-    oauthCallback?: (provider: string, code: string, state: string) => Promise<AuthResult>;
-    /**
-     * PassKey methods
-     */
-    passkey?: {
-        register?: (options?: {
-            name?: string;
-            userId?: string;
-        }) => Promise<{
-            success: boolean;
-            passkeyId?: string;
-            error?: string;
-        }>;
-        authenticate?: (options?: {
-            userId?: string;
-        }) => Promise<AuthResult>;
-        list?: () => Promise<Array<{
-            id: string;
-            name: string;
-            createdAt: Date;
-            lastUsedAt?: Date;
-        }>>;
-        remove?: (passKeyId: string) => Promise<{
-            success: boolean;
-            error?: string;
-        }>;
-    };
-    /**
-     * Two-Factor Authentication methods
-     */
-    twoFactor?: {
-        enable?: () => Promise<{
-            success: boolean;
-            qrCode?: string;
-            secret?: string;
-            error?: string;
-        }>;
-        verify?: (code: string) => Promise<{
-            success: boolean;
-            backupCodes?: string[];
-            error?: string;
-        }>;
-        disable?: () => Promise<{
-            success: boolean;
-            error?: string;
-        }>;
-        generateBackupCodes?: () => Promise<{
-            success: boolean;
-            backupCodes?: string[];
-            error?: string;
-        }>;
-        isEnabled?: () => Promise<boolean>;
-        /**
-         * Verify 2FA code after initial sign in
-         * Used when signIn returns requires2FA: true
-         */
-        verify2FA?: (data: import('./auth').Verify2FAData) => Promise<import('./auth').AuthResult>;
-    };
-    /**
-     * Verify 2FA code after initial sign in (legacy - use twoFactor.verify2FA instead)
-     * Used when signIn returns requires2FA: true
-     */
-    verify2FA?: (data: import('./auth').Verify2FAData) => Promise<import('./auth').AuthResult>;
+export interface OAuthUserInfo {
+    readonly id: string;
+    readonly email: string;
+    readonly name: string;
+    readonly avatar?: string;
+    readonly emailVerified?: boolean;
+    readonly provider: string;
+    readonly accessToken: string;
+    readonly refreshToken?: string;
+    readonly tokens: OAuthTokens;
+    readonly rawProfile?: Readonly<Record<string, unknown>>;
+    readonly [key: string]: unknown;
 }
 /**
- * Session configuration
+ * Session cookie configuration.
+ *
+ * @property cookieName - Cookie name (default: '__mulguard_session')
+ * @property expiresIn - Session expiration in seconds (default: 7 days)
+ * @property httpOnly - HttpOnly flag (default: true)
+ * @property secure - Secure flag (default: true in production)
+ * @property sameSite - SameSite policy (default: 'lax')
+ * @property path - Cookie path (default: '/')
+ * @property domain - Cookie domain (optional)
+ * @property cacheTtl - Session cache TTL in milliseconds (default: 5000)
  */
 export interface SessionConfig {
-    /** Cookie name (default: '__mulguard_session') */
-    cookieName?: string;
-    /** Session expiration in seconds (default: 7 days) */
-    expiresIn?: number;
-    /** HttpOnly flag (default: true) */
-    httpOnly?: boolean;
-    /** Secure flag (default: true in production) */
-    secure?: boolean;
-    /** SameSite policy (default: 'lax') */
-    sameSite?: 'strict' | 'lax' | 'none';
-    /** Cookie path (default: '/') */
-    path?: string;
-    /** Cookie domain (optional) */
-    domain?: string;
-    /** Session cache TTL in milliseconds (default: 5000) */
-    cacheTtl?: number;
+    readonly cookieName?: string;
+    readonly expiresIn?: number;
+    readonly httpOnly?: boolean;
+    readonly secure?: boolean;
+    readonly sameSite?: 'strict' | 'lax' | 'none';
+    readonly path?: string;
+    readonly domain?: string;
+    readonly cacheTtl?: number;
 }
 /**
- * Security configuration
+ * Security configuration options.
+ *
+ * @property csrfProtection - Enable CSRF protection (default: true)
+ * @property rateLimiting - Enable rate limiting (default: true)
+ * @property requireHttps - Require HTTPS (default: true in production)
+ * @property allowedOrigins - Allowed origins for CORS
  */
 export interface SecurityConfig {
-    /** Enable CSRF protection (default: true) */
-    csrfProtection?: boolean;
-    /** Enable rate limiting (default: true) */
-    rateLimiting?: boolean;
-    /** Require HTTPS (default: true in production) */
-    requireHttps?: boolean;
-    /** Allowed origins for CORS */
-    allowedOrigins?: string[];
+    readonly csrfProtection?: boolean;
+    readonly rateLimiting?: boolean;
+    readonly requireHttps?: boolean;
+    readonly allowedOrigins?: readonly string[];
 }
 /**
- * OAuth tokens from provider
+ * OAuth provider identifier.
  */
-export interface OAuthTokens {
-    access_token: string;
-    refresh_token?: string;
-    expires_in?: number;
-    token_type?: string;
-    id_token?: string;
-    scope?: string;
-}
+export type OAuthProviderId = 'google' | 'github' | 'apple' | 'facebook' | string;
 /**
- * OAuth user info from provider
- * Enhanced with tokens and provider information for maximum flexibility
+ * Sign-in provider type.
  */
-export interface OAuthUserInfo {
-    /** User ID from OAuth provider */
-    id: string;
-    /** User email from OAuth provider */
-    email: string;
-    /** User name from OAuth provider */
-    name: string;
-    /** User avatar URL (optional) */
-    avatar?: string;
-    /** Whether email is verified (optional) */
-    emailVerified?: boolean;
-    /** ✅ NEW: OAuth provider name (e.g., 'google', 'github') */
-    provider: string;
-    /** ✅ NEW: Access token from OAuth provider (required for backend API integration) */
-    accessToken: string;
-    /** ✅ NEW: Refresh token from OAuth provider (optional, for token refresh) */
-    refreshToken?: string;
-    /** ✅ NEW: Complete tokens object with all token information */
-    tokens: OAuthTokens;
-    /** ✅ NEW: Raw profile data from OAuth provider (for advanced use cases) */
-    rawProfile?: Record<string, unknown>;
-    /** ✅ NEW: Additional provider-specific fields */
-    [key: string]: unknown;
+export type SignInProvider = OAuthProviderId | 'credentials' | 'passkey' | 'otp';
+/**
+ * Sign-in options for unified interface.
+ *
+ * @property provider - Authentication provider
+ * @property credentials - Email/password credentials (for 'credentials' provider)
+ * @property formData - Form data (alternative to credentials)
+ * @property options - Additional options (for 'otp' or 'passkey' providers)
+ */
+export interface SignInOptions {
+    readonly provider: SignInProvider;
+    readonly credentials?: Readonly<EmailCredentials>;
+    readonly formData?: FormData;
+    readonly options?: Readonly<{
+        userId?: string;
+        email?: string;
+        code?: string;
+    }>;
 }
 /**
- * Callbacks configuration
+ * Lifecycle callbacks configuration.
+ *
+ * All callbacks are optional and can be used to hook into authentication events.
+ *
+ * @property onSignIn - Called after successful sign-in
+ * @property onSignOut - Called after sign-out
+ * @property onSessionUpdate - Called when session is updated (can modify session)
+ * @property onError - Called on authentication errors
+ * @property onTokenRefresh - Called when tokens are refreshed
+ * @property onSessionExpired - Called when session expires
+ * @property onOAuthUser - Called when OAuth user is received (for user creation/lookup)
  */
 export interface CallbacksConfig {
-    /** Called after successful sign in */
-    onSignIn?: (user: User, session: Session) => Promise<void> | void;
-    /** Called after sign out */
-    onSignOut?: (user: User) => Promise<void> | void;
-    /** Called when session is updated */
-    onSessionUpdate?: (session: Session) => Promise<Session> | Session;
-    /** Called on error */
-    onError?: (error: Error, context?: string) => Promise<void> | void;
-    /** Called when token is refreshed */
-    onTokenRefresh?: (oldSession: Session, newSession: Session) => Promise<void> | void;
-    /** Called when session expires */
-    onSessionExpired?: (session: Session) => Promise<void> | void;
-    /** ✅ NEW: Called when OAuth user is received (for auto-generated OAuth callback) */
-    onOAuthUser?: (userInfo: OAuthUserInfo, provider: string) => Promise<User>;
+    readonly onSignIn?: (user: User, session: Session) => Promise<void> | void;
+    readonly onSignOut?: (user: User) => Promise<void> | void;
+    readonly onSessionUpdate?: (session: Session) => Promise<Session> | Session;
+    readonly onError?: (error: Error, context?: string) => Promise<void> | void;
+    readonly onTokenRefresh?: (oldSession: Session, newSession: Session) => Promise<void> | void;
+    readonly onSessionExpired?: (session: Session) => Promise<void> | void;
+    readonly onOAuthUser?: (userInfo: OAuthUserInfo, provider: string) => Promise<User>;
 }
 /**
- * User interface
+ * Request context for Server Actions.
+ *
+ * Provides access to request metadata for authentication operations.
+ *
+ * @property headers - Request headers
+ * @property cookies - Request cookies map
+ * @property ip - Client IP address (optional)
+ * @property userAgent - User agent string (optional)
  */
-export interface User {
-    id: string;
-    email: string;
-    name: string;
-    avatar?: string;
-    roles?: string[];
-    emailVerified?: boolean;
-    [key: string]: unknown;
+export interface RequestContext {
+    readonly headers: Headers;
+    readonly cookies: ReadonlyMap<string, string>;
+    readonly ip?: string;
+    readonly userAgent?: string;
 }
 /**
- * Session interface
+ * Main Mulguard configuration interface.
+ *
+ * @template TUser - User type (extends base User)
+ * @template TSession - Session type (extends base Session)
+ *
+ * @property session - Session configuration
+ * @property actions - Custom authentication actions (required)
+ * @property callbacks - Lifecycle callbacks (optional)
+ * @property security - Security configuration (optional)
+ * @property tokenRefresh - Token refresh configuration (optional)
+ * @property providers - OAuth providers configuration (optional)
+ * @property oauthStateStore - OAuth state store (optional, uses in-memory by default)
+ * @property sessionCacheTtl - Session cache TTL in milliseconds (optional)
  */
-export interface Session {
-    user: User;
-    expiresAt: Date | string;
-    [key: string]: unknown;
+export interface MulguardConfig<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> {
+    readonly session?: SessionConfig;
+    readonly actions: AuthActions<TUser, TSession>;
+    readonly callbacks?: CallbacksConfig;
+    readonly security?: SecurityConfig;
+    readonly tokenRefresh?: import('../client/token-refresh-manager').TokenRefreshConfig;
+    readonly providers?: {
+        readonly oauth?: OAuthProvidersConfig;
+    };
+    readonly oauthStateStore?: import('../auth/oauth-state-store').OAuthStateStore;
+    readonly sessionCacheTtl?: number;
 }
+export type { User, Session, AuthResult, SuccessfulAuthResult, FailedAuthResult, TwoFactorAuthResult, EmailCredentials, RegisterData, Verify2FAData, };
+export { isAuthSuccess, isAuthFailure, isTwoFactorRequired } from './auth';
 /**
- * Authentication result
+ * Custom authentication actions interface.
+ *
+ * Users implement these actions to provide custom authentication logic.
+ * All actions are Server Actions that run on the server.
+ *
+ * @template TUser - User type
+ * @template TSession - Session type
  */
-export interface AuthResult {
-    success: boolean;
-    user?: User;
-    session?: Session;
-    error?: string;
-    /** Error code for programmatic error handling */
-    errorCode?: import('./errors').AuthErrorCode;
-    /** Indicates if 2FA is required */
-    requires2FA?: boolean;
-    /** Email for 2FA flow */
-    email?: string;
-    /** User ID for 2FA flow */
-    userId?: string;
+export interface AuthActions<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> {
+    readonly signIn: SignInActions<TUser, TSession>;
+    readonly signUp?: (data: RegisterData) => Promise<AuthResult<TUser, TSession>>;
+    readonly signOut?: () => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    readonly resetPassword?: (email: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    readonly verifyEmail?: (token: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    readonly getSession?: () => Promise<TSession | null>;
+    readonly refreshSession?: () => Promise<TSession | null>;
+    readonly oauthCallback?: (provider: string, code: string, state: string) => Promise<AuthResult<TUser, TSession>>;
+    readonly passkey?: PasskeyActions<TUser, TSession>;
+    readonly twoFactor?: TwoFactorActions<TUser, TSession>;
+    readonly verify2FA?: (data: Verify2FAData) => Promise<AuthResult<TUser, TSession>>;
 }
 /**
- * Email credentials for sign in
+ * Sign-in actions interface.
+ *
+ * @template TUser - User type
+ * @template TSession - Session type
  */
-export interface EmailCredentials {
-    email: string;
-    password: string;
+export interface SignInActions<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> {
+    readonly email: (credentials: EmailCredentials) => Promise<AuthResult<TUser, TSession>>;
+    readonly oauth?: (provider: string) => Promise<{
+        url: string;
+        state: string;
+    }>;
+    readonly passkey?: (options?: {
+        userId?: string;
+    }) => Promise<AuthResult<TUser, TSession>>;
+    readonly otp?: (email: string, code?: string) => Promise<AuthResult<TUser, TSession>>;
 }
 /**
- * Registration data
+ * Passkey actions interface.
+ *
+ * @template TUser - User type
+ * @template TSession - Session type
  */
-export interface RegisterData {
-    email: string;
-    password: string;
-    name: string;
-    [key: string]: unknown;
+export interface PasskeyActions<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> {
+    readonly register?: (options?: {
+        name?: string;
+        userId?: string;
+    }) => Promise<{
+        success: boolean;
+        passkeyId?: string;
+        error?: string;
+    }>;
+    readonly authenticate?: (options?: {
+        userId?: string;
+    }) => Promise<AuthResult<TUser, TSession>>;
+    readonly list?: () => Promise<ReadonlyArray<{
+        id: string;
+        name: string;
+        createdAt: Date;
+        lastUsedAt?: Date;
+    }>>;
+    readonly remove?: (passKeyId: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
 }
 /**
- * Request context for Server Actions
+ * Two-factor authentication actions interface.
+ *
+ * @template TUser - User type
+ * @template TSession - Session type
  */
-export interface RequestContext {
-    /** Request headers */
-    headers: Headers;
-    /** Request cookies */
-    cookies: Map<string, string>;
-    /** Request IP address */
-    ip?: string;
-    /** Request user agent */
-    userAgent?: string;
+export interface TwoFactorActions<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> {
+    readonly enable?: () => Promise<{
+        success: boolean;
+        qrCode?: string;
+        secret?: string;
+        error?: string;
+    }>;
+    readonly verify?: (code: string) => Promise<{
+        success: boolean;
+        backupCodes?: string[];
+        error?: string;
+    }>;
+    readonly disable?: () => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    readonly generateBackupCodes?: () => Promise<{
+        success: boolean;
+        backupCodes?: string[];
+        error?: string;
+    }>;
+    readonly isEnabled?: () => Promise<boolean>;
+    readonly verify2FA?: (data: Verify2FAData) => Promise<AuthResult<TUser, TSession>>;
 }
+/**
+ * Type predicate to check if a value is a valid User object.
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid User
+ *
+ * @example
+ * ```typescript
+ * if (isUser(data)) {
+ *   // TypeScript knows data is User here
+ *   console.log(data.email)
+ * }
+ * ```
+ */
+export declare function isUser(value: unknown): value is User;
+/**
+ * Type predicate to check if a value is a valid Session object.
+ *
+ * @template TUser - User type
+ * @param value - Value to check
+ * @returns True if value is a valid Session
+ *
+ * @example
+ * ```typescript
+ * if (isSession(data)) {
+ *   // TypeScript knows data is Session here
+ *   console.log(data.user.email)
+ * }
+ * ```
+ */
+export declare function isSession<TUser extends User = User>(value: unknown): value is Session<TUser>;
+/**
+ * TODO: Performance
+ * - [ ] Add type-level optimizations for large union types
+ * - [ ] Consider using branded types for IDs to prevent mixing
+ * - [ ] Add type-level validation for configuration objects
+ * - [ ] Implement type-safe builder pattern for complex configurations
+ *
+ * TODO: Features
+ * - [ ] Add conditional types for provider-specific OAuth configs
+ * - [ ] Implement discriminated unions for AuthResult variants
+ * - [ ] Add type-level session expiration checking
+ * - [ ] Create type-safe middleware chain types
+ * - [ ] Add generic constraints for custom User/Session extensions
+ *
+ * TODO: Type Safety
+ * - [ ] Add branded types for sensitive data (tokens, passwords)
+ * - [ ] Implement type-level validation for email formats
+ * - [ ] Add type guards for all public interfaces
+ * - [ ] Create type-safe error handling with exhaustiveness checking
+ *
+ * TODO: Testing
+ * - [ ] Add type-level tests using ts-expect
+ * - [ ] Test type inference in various scenarios
+ * - [ ] Verify type narrowing with type predicates
+ * - [ ] Test generic constraints and conditional types
+ *
+ * TODO: Documentation
+ * - [ ] Add more JSDoc examples for complex types
+ * - [ ] Document type-level patterns and best practices
+ * - [ ] Create type usage guides
+ *
+ * TODO: Limitations
+ * - [ ] Type inference may be limited with very complex generic chains
+ * - [ ] Branded types add runtime overhead (consider compile-time only)
+ * - [ ] Deep readonly types may impact performance with large objects
+ */