mulguard 1.1.6 → 1.1.8

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

@@ -1,200 +0,0 @@
-/**
- * Authentication error codes and error handling types.
- *
- * @module @mulguard/core/types/errors
- */
-/**
- * Authentication error code enumeration.
- *
- * Provides specific error codes for programmatic error handling.
- *
- * @example
- * ```typescript
- * if (result.errorCode === AuthErrorCode.INVALID_CREDENTIALS) {
- *   // Handle invalid credentials
- * } else if (result.errorCode === AuthErrorCode.TWO_FA_REQUIRED) {
- *   // Handle 2FA requirement
- * }
- * ```
- */
-export declare enum AuthErrorCode {
-    /** Invalid email or password credentials */
-    INVALID_CREDENTIALS = "INVALID_CREDENTIALS",
-    /** Account is temporarily locked due to failed attempts */
-    ACCOUNT_LOCKED = "ACCOUNT_LOCKED",
-    /** Account is inactive or disabled */
-    ACCOUNT_INACTIVE = "ACCOUNT_INACTIVE",
-    /** Two-factor authentication is required */
-    TWO_FA_REQUIRED = "TWO_FA_REQUIRED",
-    /** Invalid two-factor authentication code */
-    INVALID_TWO_FA_CODE = "INVALID_TWO_FA_CODE",
-    /** Session has expired */
-    SESSION_EXPIRED = "SESSION_EXPIRED",
-    /** User is not authorized for this operation */
-    UNAUTHORIZED = "UNAUTHORIZED",
-    /** Network or API communication error */
-    NETWORK_ERROR = "NETWORK_ERROR",
-    /** Input validation error */
-    VALIDATION_ERROR = "VALIDATION_ERROR",
-    /** Rate limit exceeded */
-    RATE_LIMITED = "RATE_LIMITED",
-    /** Unknown or unexpected error */
-    UNKNOWN_ERROR = "UNKNOWN_ERROR"
-}
-/**
- * Authentication error interface.
- *
- * Provides structured error information with code, message, and optional metadata.
- *
- * @property code - Specific error code
- * @property message - Human-readable error message
- * @property statusCode - HTTP status code (if applicable)
- * @property details - Additional error details (optional)
- *
- * @example
- * ```typescript
- * const error: AuthError = {
- *   code: AuthErrorCode.INVALID_CREDENTIALS,
- *   message: 'Invalid email or password',
- *   statusCode: 401
- * }
- * ```
- */
-export interface AuthError {
-    readonly code: AuthErrorCode;
-    readonly message: string;
-    readonly statusCode?: number;
-    readonly details?: unknown;
-}
-/**
- * Error result type for failed operations.
- *
- * @template TCode - Error code type (defaults to AuthErrorCode)
- */
-export type ErrorResult<TCode extends AuthErrorCode = AuthErrorCode> = {
-    readonly success: false;
-    readonly error: string;
-    readonly errorCode: TCode;
-    readonly details?: unknown;
-};
-/**
- * Creates an authentication error object.
- *
- * @param code - Error code
- * @param message - Human-readable error message
- * @param statusCode - HTTP status code (optional)
- * @param details - Additional error details (optional)
- * @returns AuthError object
- *
- * @example
- * ```typescript
- * const error = createAuthError(
- *   AuthErrorCode.INVALID_CREDENTIALS,
- *   'Invalid email or password',
- *   401
- * )
- * ```
- */
-export declare function createAuthError(code: AuthErrorCode, message: string, statusCode?: number, details?: unknown): AuthError;
-/**
- * Creates an error result for failed authentication operations.
- *
- * @template TCode - Error code type
- * @param code - Error code
- * @param message - Error message
- * @param details - Additional error details (optional)
- * @returns ErrorResult object
- *
- * @example
- * ```typescript
- * const result = createErrorResult(
- *   AuthErrorCode.INVALID_CREDENTIALS,
- *   'Invalid email or password'
- * )
- * ```
- */
-export declare function createErrorResult<TCode extends AuthErrorCode = AuthErrorCode>(code: TCode, message: string, details?: unknown): ErrorResult<TCode>;
-/**
- * HTTP status code mapping for error codes.
- *
- * Maps authentication error codes to appropriate HTTP status codes.
- */
-export declare const ERROR_STATUS_MAP: Readonly<Record<AuthErrorCode, number>>;
-/**
- * Gets the HTTP status code for an error code.
- *
- * @param code - Error code
- * @returns HTTP status code
- *
- * @example
- * ```typescript
- * const statusCode = getErrorStatusCode(AuthErrorCode.INVALID_CREDENTIALS)
- * // Returns 401
- * ```
- */
-export declare function getErrorStatusCode(code: AuthErrorCode): number;
-/**
- * Type predicate to check if a value is an AuthError.
- *
- * @param value - Value to check
- * @returns True if value is an AuthError
- *
- * @example
- * ```typescript
- * if (isAuthError(error)) {
- *   // TypeScript knows error is AuthError here
- *   console.log(error.code, error.message)
- * }
- * ```
- */
-export declare function isAuthError(value: unknown): value is AuthError;
-/**
- * Type predicate to check if a value is an ErrorResult.
- *
- * @param value - Value to check
- * @returns True if value is an ErrorResult
- *
- * @example
- * ```typescript
- * if (isErrorResult(result)) {
- *   // TypeScript knows result is ErrorResult here
- *   console.log(result.errorCode, result.error)
- * }
- * ```
- */
-export declare function isErrorResult(value: unknown): value is ErrorResult;
-/**
- * TODO: Performance
- * - [ ] Consider using const assertions for error code strings
- * - [ ] Add type-level validation for error code mappings
- * - [ ] Implement compile-time error code exhaustiveness checking
- *
- * TODO: Features
- * - [ ] Add error recovery strategies
- * - [ ] Implement error code hierarchies/categories
- * - [ ] Add localized error messages support
- * - [ ] Create error code to user-friendly message mapping
- * - [ ] Add error code metadata (retryable, transient, etc.)
- *
- * TODO: Type Safety
- * - [ ] Add branded types for error codes
- * - [ ] Implement type-safe error code unions
- * - [ ] Add exhaustiveness checking for error handling
- * - [ ] Create type-safe error code validation
- *
- * TODO: Testing
- * - [ ] Add tests for error code mappings
- * - [ ] Test type guards with various inputs
- * - [ ] Verify error result type narrowing
- * - [ ] Test error factory functions
- *
- * TODO: Documentation
- * - [ ] Add examples for each error code
- * - [ ] Document error handling best practices
- * - [ ] Create error code reference guide
- *
- * TODO: Limitations
- * - [ ] Error code enum may need extension for custom errors
- * - [ ] Status code mapping is fixed (consider configurable)
- * - [ ] Error details type is unknown (consider generic)
- */

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

@@ -1,462 +0,0 @@
-import { User, Session, AuthResult, SuccessfulAuthResult, FailedAuthResult, TwoFactorAuthResult, EmailCredentials, RegisterData, Verify2FAData } from './auth';
-/**
- * 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';
-/**
- * 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 request */
-    get: <TResponse = unknown>(url: string, config?: unknown) => Promise<{
-        data: TResponse;
-    }>;
-    /** POST request */
-    post: <TResponse = unknown, TRequest = unknown>(url: string, data?: TRequest, config?: unknown) => Promise<{
-        data: TResponse;
-    }>;
-    /** PUT request */
-    put: <TResponse = unknown, TRequest = unknown>(url: string, data?: TRequest, config?: unknown) => Promise<{
-        data: TResponse;
-    }>;
-    /** DELETE request */
-    delete: <TResponse = unknown>(url: string, config?: unknown) => Promise<{
-        data: TResponse;
-    }>;
-}
-/**
- * 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 {
-    readonly userId: string;
-    readonly email: string;
-    readonly name: string;
-    readonly avatar?: string;
-    readonly provider: AuthProvider;
-    readonly lastLoginAt: Date;
-}
-/**
- * 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 {
-    readonly clientId: string;
-    readonly clientSecret?: string;
-    readonly redirectUri?: string;
-    readonly scopes?: readonly string[];
-    readonly params?: Readonly<Record<string, string>>;
-}
-/**
- * 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 {
-    readonly google?: OAuthProviderConfig;
-    readonly github?: OAuthProviderConfig;
-    readonly apple?: OAuthProviderConfig;
-    readonly facebook?: OAuthProviderConfig;
-    readonly [key: string]: OAuthProviderConfig | undefined;
-}
-/**
- * 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 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;
-}
-/**
- * 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 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 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 {
-    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 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 {
-    readonly csrfProtection?: boolean;
-    readonly rateLimiting?: boolean;
-    readonly requireHttps?: boolean;
-    readonly allowedOrigins?: readonly string[];
-}
-/**
- * OAuth provider identifier.
- */
-export type OAuthProviderId = 'google' | 'github' | 'apple' | 'facebook' | string;
-/**
- * Sign-in provider type.
- */
-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;
-    }>;
-}
-/**
- * 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 {
-    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>;
-}
-/**
- * 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 RequestContext {
-    readonly headers: Headers;
-    readonly cookies: ReadonlyMap<string, string>;
-    readonly ip?: string;
-    readonly userAgent?: string;
-}
-/**
- * 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 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';
-/**
- * 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 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>>;
-}
-/**
- * Sign-in actions interface.
- *
- * @template TUser - User type
- * @template TSession - Session type
- */
-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>>;
-}
-/**
- * Passkey actions interface.
- *
- * @template TUser - User type
- * @template TSession - Session type
- */
-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;
-    }>;
-}
-/**
- * Two-factor authentication actions interface.
- *
- * @template TUser - User type
- * @template TSession - Session type
- */
-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
- */