mulguard 1.1.7 → 1.1.8

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

@@ -1,484 +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.
- *
- * Enhanced with comprehensive security settings from SecurityManager.
- *
- * @property csrfProtection - CSRF protection configuration
- * @property rateLimiting - Rate limiting configuration
- * @property validation - Input validation configuration
- * @property xssProtection - XSS protection configuration
- * @property requireHttps - Require HTTPS (default: true in production)
- * @property allowedOrigins - Allowed origins for CORS
- */
-export interface SecurityConfig {
-    readonly csrfProtection?: {
-        readonly enabled?: boolean;
-        readonly tokenLength?: number;
-        readonly expiresIn?: number;
-    };
-    readonly rateLimiting?: {
-        readonly enabled?: boolean;
-        readonly maxAttempts?: number;
-        readonly windowMs?: number;
-        readonly strategy?: 'ip' | 'user' | 'email';
-    };
-    readonly validation?: {
-        readonly strictEmail?: boolean;
-        readonly minPasswordLength?: number;
-        readonly requireStrongPassword?: boolean;
-    };
-    readonly xssProtection?: {
-        readonly enabled?: boolean;
-        readonly sanitizeHtml?: 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
- */

package/dist/core/utils/auth-helpers.d.ts

@@ -1,136 +0,0 @@
-import { AuthResult, TwoFactorAuthResult } from '../types/auth';
-import { AuthErrorCode } from '../types/errors';
-/**
- * Check if an authentication result indicates an error
- *
- * @param result - Authentication result to check
- * @returns True if the result indicates an error
- *
- * @example
- * ```typescript
- * const result = await auth.signIn.email(credentials)
- * if (isAuthError(result)) {
- *   console.error('Authentication failed:', result.error)
- * }
- * ```
- */
-export declare function isAuthError(result: AuthResult): boolean;
-/**
- * Type guard to check if 2FA is required
- *
- * This function narrows the type to TwoFactorAuthResult when true,
- * making it easier to work with 2FA flows in TypeScript.
- *
- * @param result - Authentication result to check
- * @returns True if 2FA is required (type guard)
- *
- * @example
- * ```typescript
- * const result = await auth.signIn.email(credentials)
- * if (isTwoFactorRequired(result)) {
- *   // TypeScript knows result is TwoFactorAuthResult here
- *   console.log('2FA required for:', result.email)
- *   // Can safely access result.email, result.userId, result.twoFactorMethod
- * }
- * ```
- */
-export declare function isTwoFactorRequired(result: AuthResult): result is TwoFactorAuthResult;
-/**
- * Get error message from authentication result
- *
- * @param result - Authentication result
- * @param defaultMessage - Default message if no error is present
- * @returns Error message or default message
- *
- * @example
- * ```typescript
- * const result = await auth.signIn.email(credentials)
- * if (!result.success) {
- *   const message = getErrorMessage(result, 'Authentication failed')
- *   showToast(message)
- * }
- * ```
- */
-export declare function getErrorMessage(result: AuthResult, defaultMessage?: string): string;
-/**
- * Get error code from authentication result
- *
- * @param result - Authentication result
- * @returns Error code or undefined
- *
- * @example
- * ```typescript
- * const result = await auth.signIn.email(credentials)
- * const errorCode = getErrorCode(result)
- * if (errorCode === AuthErrorCode.ACCOUNT_LOCKED) {
- *   showAccountLockedMessage()
- * }
- * ```
- */
-export declare function getErrorCode(result: AuthResult): AuthErrorCode | undefined;
-/**
- * Check if authentication was successful
- *
- * @param result - Authentication result to check
- * @returns True if authentication was successful
- *
- * @example
- * ```typescript
- * const result = await auth.signIn.email(credentials)
- * if (isAuthSuccess(result)) {
- *   console.log('Welcome,', result.user?.name)
- * }
- * ```
- */
-export declare function isAuthSuccess(result: AuthResult): boolean;
-/**
- * Check if a specific error code matches
- *
- * @param result - Authentication result
- * @param code - Error code to check for
- * @returns True if the error code matches
- *
- * @example
- * ```typescript
- * const result = await auth.signIn.email(credentials)
- * if (hasErrorCode(result, AuthErrorCode.ACCOUNT_LOCKED)) {
- *   showAccountLockedMessage()
- * }
- * ```
- */
-export declare function hasErrorCode(result: AuthResult, code: AuthErrorCode): boolean;
-/**
- * Check if the error is retryable
- *
- * Some errors (like network errors or rate limits) may be retryable,
- * while others (like invalid credentials) should not be retried.
- *
- * @param result - Authentication result
- * @returns True if the error is retryable
- *
- * @example
- * ```typescript
- * const result = await auth.signIn.email(credentials)
- * if (isAuthError(result) && isRetryableError(result)) {
- *   // Show retry button
- *   showRetryButton()
- * }
- * ```
- */
-export declare function isRetryableError(result: AuthResult): boolean;
-/**
- * Get user-friendly error message based on error code
- *
- * @param result - Authentication result
- * @returns User-friendly error message
- *
- * @example
- * ```typescript
- * const result = await auth.signIn.email(credentials)
- * if (!result.success) {
- *   const message = getUserFriendlyError(result)
- *   showToast(message)
- * }
- * ```
- */
-export declare function getUserFriendlyError(result: AuthResult): string;