mulguard 1.1.6 → 1.1.7

package/dist/core/auth/otp.d.ts

@@ -0,0 +1,184 @@
+import { AuthResult, User, Session } from '../types';
+import { SecurityManager } from '../security/security-manager';
+import { Logger } from '../logger';
+/**
+ * OTP provider type.
+ */
+export type OTPProvider = 'email' | 'sms';
+/**
+ * OTP configuration.
+ */
+export interface OTPConfig {
+    readonly length?: number;
+    readonly expiresIn?: number;
+    readonly provider?: OTPProvider;
+    readonly security?: SecurityManager;
+    readonly logger?: Logger;
+}
+/**
+ * OTP storage adapter interface.
+ */
+export interface OTPStorageAdapter {
+    /**
+     * Stores an OTP code.
+     *
+     * @param email - User email
+     * @param code - OTP code
+     * @param expiresIn - Expiration time in seconds
+     */
+    set(email: string, code: string, expiresIn: number): Promise<void>;
+    /**
+     * Gets an OTP code.
+     *
+     * @param email - User email
+     * @returns OTP code or null if not found/expired
+     */
+    get(email: string): Promise<string | null>;
+    /**
+     * Deletes an OTP code.
+     *
+     * @param email - User email
+     */
+    delete(email: string): Promise<void>;
+}
+/**
+ * In-memory OTP storage adapter.
+ */
+export declare class MemoryOTPStorage implements OTPStorageAdapter {
+    private readonly storage;
+    set(email: string, code: string, expiresIn: number): Promise<void>;
+    get(email: string): Promise<string | null>;
+    delete(email: string): Promise<void>;
+}
+/**
+ * OTP authentication handler.
+ *
+ * Provides secure OTP generation, validation, and authentication.
+ *
+ * @example
+ * ```typescript
+ * const handler = new OTPAuth({
+ *   length: 6,
+ *   expiresIn: 600, // 10 minutes
+ *   provider: 'email',
+ * })
+ *
+ * // Generate OTP
+ * const code = await handler.generateOTP('user@example.com')
+ *
+ * // Verify OTP
+ * const result = await handler.verifyOTP('user@example.com', code, userLookup, createSession)
+ * ```
+ */
+export declare class OTPAuth {
+    private readonly config;
+    private readonly storage;
+    private readonly security;
+    constructor(config?: OTPConfig, storage?: OTPStorageAdapter);
+    /**
+     * Generates an OTP code for a user.
+     *
+     * @param email - User email
+     * @returns Generated OTP code
+     *
+     * @example
+     * ```typescript
+     * const code = await handler.generateOTP('user@example.com')
+     * // Send code via email/SMS
+     * ```
+     */
+    generateOTP(email: string): Promise<string>;
+    /**
+     * Verifies an OTP code and authenticates the user.
+     *
+     * @template TUser - User type
+     * @template TSession - Session type
+     * @param email - User email
+     * @param code - OTP code to verify
+     * @param userLookup - Function to lookup user by email
+     * @param createSession - Function to create session (optional)
+     * @returns Authentication result
+     *
+     * @example
+     * ```typescript
+     * const result = await handler.verifyOTP(
+     *   'user@example.com',
+     *   '123456',
+     *   async (email) => await db.user.findUnique({ where: { email } })
+     * )
+     * ```
+     */
+    verifyOTP<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(email: string, code: string, userLookup: (email: string) => Promise<TUser | null>, createSession?: (user: TUser) => Promise<TSession>): Promise<AuthResult<TUser, TSession>>;
+    /**
+     * Generates a numeric OTP code.
+     *
+     * @param length - Code length
+     * @returns Numeric code string
+     */
+    private generateNumericCode;
+    /**
+     * Constant-time string comparison to prevent timing attacks.
+     *
+     * @param a - First string
+     * @param b - Second string
+     * @returns True if strings match
+     */
+    private constantTimeCompare;
+}
+/**
+ * Creates an OTP authentication handler.
+ *
+ * @param config - OTP configuration
+ * @param storage - OTP storage adapter (optional)
+ * @returns OTP authentication handler
+ *
+ * @example
+ * ```typescript
+ * const handler = createOTPAuth({
+ *   length: 6,
+ *   expiresIn: 600,
+ *   provider: 'email',
+ * })
+ * ```
+ */
+export declare function createOTPAuth(config?: OTPConfig, storage?: OTPStorageAdapter): OTPAuth;
+/**
+ * TODO: Performance
+ * - [ ] Add OTP generation caching
+ * - [ ] Optimize storage lookups
+ * - [ ] Implement async code generation
+ *
+ * TODO: Features
+ * - [ ] Add SMS provider support
+ * - [ ] Implement OTP resend functionality
+ * - [ ] Add OTP rate limiting
+ * - [ ] Create OTP delivery tracking
+ * - [ ] Add OTP code hints (for testing)
+ *
+ * TODO: Security
+ * - [ ] Add OTP brute force protection
+ * - [ ] Implement OTP code rotation
+ * - [ ] Add OTP delivery verification
+ * - [ ] Create security event logging
+ *
+ * TODO: Type Safety
+ * - [ ] Add branded types for OTP codes
+ * - [ ] Create type-safe OTP storage
+ * - [ ] Implement compile-time validation
+ *
+ * TODO: Testing
+ * - [ ] Add comprehensive unit tests
+ * - [ ] Test OTP expiration
+ * - [ ] Test constant-time comparison
+ * - [ ] Add storage adapter tests
+ *
+ * TODO: Documentation
+ * - [ ] Document OTP flow
+ * - [ ] Add provider setup guide
+ * - [ ] Create security best practices guide
+ *
+ * TODO: Limitations
+ * - [ ] OTP storage is in-memory (consider Redis for production)
+ * - [ ] Code generation uses Math.random (consider crypto.randomInt)
+ * - [ ] No SMS provider implementation yet
+ */

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

@@ -0,0 +1,269 @@
+import { AuthErrorCode, AuthError as AuthErrorInterface, ErrorResult } from '../types/errors';
+/**
+ * Base authentication error class.
+ *
+ * Extends native Error with authentication-specific properties.
+ * All authentication errors should extend this class.
+ *
+ * @property code - Specific error code
+ * @property statusCode - HTTP status code (if applicable)
+ * @property details - Additional error details (optional)
+ *
+ * @example
+ * ```typescript
+ * throw new AuthError(
+ *   AuthErrorCode.INVALID_CREDENTIALS,
+ *   'Invalid email or password'
+ * )
+ * ```
+ */
+export declare class AuthError extends Error {
+    readonly code: AuthErrorCode;
+    readonly statusCode: number;
+    readonly details?: unknown;
+    constructor(code: AuthErrorCode, message: string, statusCode?: number, details?: unknown);
+    /**
+     * Converts error to plain object for serialization.
+     *
+     * @returns Plain error object
+     */
+    toJSON(): AuthErrorInterface;
+    /**
+     * Creates error result for failed operations.
+     *
+     * @returns ErrorResult object
+     */
+    toErrorResult(): ErrorResult;
+}
+/**
+ * Invalid credentials error.
+ *
+ * Thrown when email/password authentication fails.
+ */
+export declare class InvalidCredentialsError extends AuthError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * Account locked error.
+ *
+ * Thrown when account is temporarily locked due to failed attempts.
+ */
+export declare class AccountLockedError extends AuthError {
+    constructor(message?: string, unlockAt?: Date, details?: unknown);
+}
+/**
+ * Account inactive error.
+ *
+ * Thrown when account is inactive or disabled.
+ */
+export declare class AccountInactiveError extends AuthError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * Two-factor authentication required error.
+ *
+ * Thrown when 2FA verification is required after initial authentication.
+ */
+export declare class TwoFactorRequiredError extends AuthError {
+    readonly email: string;
+    readonly userId: string;
+    readonly twoFactorMethod?: 'totp' | 'sms' | 'email';
+    readonly challengeToken?: string;
+    constructor(email: string, userId: string, message?: string, twoFactorMethod?: 'totp' | 'sms' | 'email', challengeToken?: string, details?: unknown);
+}
+/**
+ * Invalid two-factor authentication code error.
+ *
+ * Thrown when 2FA code verification fails.
+ */
+export declare class InvalidTwoFactorCodeError extends AuthError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * Session expired error.
+ *
+ * Thrown when session has expired.
+ */
+export declare class SessionExpiredError extends AuthError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * Unauthorized error.
+ *
+ * Thrown when user is not authorized for an operation.
+ */
+export declare class UnauthorizedError extends AuthError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * Network error.
+ *
+ * Thrown when network or API communication fails.
+ */
+export declare class NetworkError extends AuthError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * Validation error.
+ *
+ * Thrown when input validation fails.
+ */
+export declare class ValidationError extends AuthError {
+    readonly fields?: ReadonlyArray<{
+        field: string;
+        message: string;
+    }>;
+    constructor(message?: string, fields?: ReadonlyArray<{
+        field: string;
+        message: string;
+    }>, details?: unknown);
+}
+/**
+ * Rate limit error.
+ *
+ * Thrown when rate limit is exceeded.
+ */
+export declare class RateLimitError extends AuthError {
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number, details?: unknown);
+}
+/**
+ * Creates an authentication error from error code and message.
+ *
+ * @param code - Error code
+ * @param message - Error message
+ * @param details - Additional error details (optional)
+ * @returns AuthError instance
+ *
+ * @example
+ * ```typescript
+ * const error = createError(
+ *   AuthErrorCode.INVALID_CREDENTIALS,
+ *   'Invalid email or password'
+ * )
+ * ```
+ */
+export declare function createError(code: AuthErrorCode, message: string, details?: unknown): AuthError;
+/**
+ * Creates an error result for failed 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>;
+/**
+ * Converts unknown error to AuthError.
+ *
+ * Handles various error types and converts them to AuthError.
+ *
+ * @param error - Unknown error value
+ * @param defaultCode - Default error code (optional)
+ * @param defaultMessage - Default error message (optional)
+ * @returns AuthError instance
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // Some operation
+ * } catch (error) {
+ *   const authError = toAuthError(error, AuthErrorCode.UNKNOWN_ERROR)
+ *   logger.error('Operation failed', authError)
+ * }
+ * ```
+ */
+export declare function toAuthError(error: unknown, defaultCode?: AuthErrorCode, defaultMessage?: string): AuthError;
+/**
+ * Checks if error is an authentication error.
+ *
+ * @param error - Error to check
+ * @returns True if error is AuthError
+ *
+ * @example
+ * ```typescript
+ * if (isAuthError(error)) {
+ *   // Handle authentication error
+ *   console.error(error.code, error.message)
+ * }
+ * ```
+ */
+export declare function isAuthError(error: unknown): error is AuthError;
+/**
+ * Gets error message from unknown error.
+ *
+ * @param error - Error to extract message from
+ * @param defaultMessage - Default message if extraction fails
+ * @returns Error message string
+ *
+ * @example
+ * ```typescript
+ * const message = getErrorMessage(error, 'Unknown error')
+ * ```
+ */
+export declare function getErrorMessage(error: unknown, defaultMessage?: string): string;
+/**
+ * Gets error code from unknown error.
+ *
+ * @param error - Error to extract code from
+ * @param defaultCode - Default code if extraction fails
+ * @returns Error code
+ *
+ * @example
+ * ```typescript
+ * const code = getErrorCode(error, AuthErrorCode.UNKNOWN_ERROR)
+ * ```
+ */
+export declare function getErrorCode(error: unknown, defaultCode?: AuthErrorCode): AuthErrorCode;
+export { AuthErrorCode, type AuthError as AuthErrorInterface, type ErrorResult, getErrorStatusCode, ERROR_STATUS_MAP, } from '../types/errors';
+/**
+ * TODO: Performance
+ * - [ ] Add error pooling for high-frequency error creation
+ * - [ ] Implement error serialization caching
+ * - [ ] Add error aggregation for batch operations
+ * - [ ] Consider using Error.cause for error chaining (Node.js 16.9+)
+ *
+ * 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.)
+ * - [ ] Implement error reporting integration (Sentry, etc.)
+ * - [ ] Add error context propagation
+ *
+ * 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
+ * - [ ] Add type-level error code to status code mapping
+ *
+ * TODO: Testing
+ * - [ ] Add unit tests for all error classes
+ * - [ ] Test error factory functions
+ * - [ ] Test error conversion utilities
+ * - [ ] Test error serialization
+ * - [ ] Add integration tests for error handling flow
+ *
+ * TODO: Documentation
+ * - [ ] Add examples for each error class
+ * - [ ] Document error handling best practices
+ * - [ ] Create error code reference guide
+ * - [ ] Add error handling patterns 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)
+ * - [ ] Stack trace capture may have performance impact
+ */

package/dist/core/index.d.ts

@@ -6,6 +6,4 @@ export type { MulguardConfig, SessionConfig, SecurityConfig, CallbacksConfig, Au
 export * from './security';
 export * from './utils/auth-helpers';
 export * from './auth/signin-unified';
-export * from './auth/oauth-providers';
-export * from './auth/oauth-state-store';
-export * from './auth/oauth-state-store-redis';
+export * from './auth/oauth';

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

@@ -0,0 +1,147 @@
+import { Logger, LoggerConfig, LogLevel } from '../utils/logger';
+/**
+ * Enhanced logging system for Mulguard Authentication Library.
+ *
+ * Provides structured logging with multiple adapters (Console, Pino) and
+ * comprehensive log sanitization for security.
+ *
+ * @module @mulguard/core/logger
+ */
+/**
+ * Logger adapter interface for different logging backends.
+ */
+export interface LoggerAdapter {
+    readonly debug: (message: string, data?: Readonly<Record<string, unknown>>) => void;
+    readonly info: (message: string, data?: Readonly<Record<string, unknown>>) => void;
+    readonly warn: (message: string, data?: Readonly<Record<string, unknown>>) => void;
+    readonly error: (message: string, error?: Error | Readonly<Record<string, unknown>>) => void;
+}
+/**
+ * Logger adapter type.
+ */
+export type LoggerAdapterType = 'console' | 'pino' | 'custom';
+/**
+ * Creates a console-based logger adapter.
+ *
+ * @param config - Logger configuration
+ * @returns Console logger adapter
+ */
+export declare function createConsoleAdapter(config?: LoggerConfig): LoggerAdapter;
+/**
+ * Creates a Pino-based logger adapter.
+ *
+ * Requires 'pino' package to be installed.
+ * Falls back to console adapter if Pino is not available.
+ *
+ * @param config - Logger configuration
+ * @returns Pino logger adapter or console fallback
+ *
+ * @example
+ * ```typescript
+ * const logger = createPinoAdapter({
+ *   level: 'info',
+ *   context: 'Auth'
+ * })
+ * ```
+ */
+export declare function createPinoAdapter(config?: LoggerConfig): LoggerAdapter;
+/**
+ * Enhanced logger configuration with adapter support.
+ */
+export interface EnhancedLoggerConfig {
+    readonly adapter?: LoggerAdapterType | LoggerAdapter;
+    readonly pinoOptions?: Record<string, unknown>;
+    readonly level?: LogLevel;
+    readonly context?: string;
+}
+/**
+ * Creates an enhanced logger instance with adapter support.
+ *
+ * @param config - Enhanced logger configuration
+ * @returns Logger instance
+ *
+ * @example
+ * ```typescript
+ * // Console adapter (default)
+ * const logger1 = createEnhancedLogger({ level: LogLevel.INFO })
+ *
+ * // Pino adapter
+ * const logger2 = createEnhancedLogger({ adapter: 'pino' })
+ *
+ * // Custom adapter
+ * const logger3 = createEnhancedLogger({ adapter: customAdapter })
+ * ```
+ */
+export declare function createEnhancedLogger(config?: EnhancedLoggerConfig): Logger;
+/**
+ * Default enhanced logger instance.
+ *
+ * Uses console adapter by default, can be configured via environment variables.
+ */
+export declare const logger: Logger;
+/**
+ * Creates a logger with context.
+ *
+ * @param context - Log context
+ * @param baseLogger - Base logger instance (optional)
+ * @returns Logger with context
+ *
+ * @example
+ * ```typescript
+ * const authLogger = createContextLogger('Auth', logger)
+ * authLogger.info('User signed in', { userId: '123' })
+ * // Output: [Auth] User signed in { userId: '123' }
+ * ```
+ */
+export declare function createContextLogger(context: string, baseLogger?: Logger): Logger;
+export type { Logger, LoggerConfig, LogEntry } from '../utils/logger';
+export { LogLevel, createLogger, isLogger } from '../utils/logger';
+/**
+ * TODO: Performance
+ * - [ ] Add log batching for high-frequency operations
+ * - [ ] Implement async logging for non-blocking operations
+ * - [ ] Add log rotation and cleanup
+ * - [ ] Consider log sampling for high-volume scenarios
+ * - [ ] Add log compression for file-based logging
+ *
+ * TODO: Features
+ * - [ ] Add Winston adapter support
+ * - [ ] Implement log transport abstraction (file, remote, etc.)
+ * - [ ] Add log correlation IDs (request IDs)
+ * - [ ] Create log aggregation support
+ * - [ ] Add performance metrics logging
+ * - [ ] Implement structured logging with schemas
+ * - [ ] Add log filtering by context/level
+ *
+ * TODO: Type Safety
+ * - [ ] Add type-safe log data validation
+ * - [ ] Create log schema definitions
+ * - [ ] Add compile-time log level checking
+ * - [ ] Implement type-safe log context
+ *
+ * TODO: Security
+ * - [ ] Enhance sensitive data detection
+ * - [ ] Add PII (Personally Identifiable Information) masking
+ * - [ ] Implement log encryption for sensitive logs
+ * - [ ] Add audit log support
+ * - [ ] Add log access control
+ *
+ * TODO: Testing
+ * - [ ] Add logger adapter unit tests
+ * - [ ] Test Pino adapter fallback
+ * - [ ] Test log sanitization
+ * - [ ] Test context logger
+ * - [ ] Add performance tests
+ *
+ * TODO: Documentation
+ * - [ ] Document adapter configuration
+ * - [ ] Add logging best practices guide
+ * - [ ] Document log levels and when to use them
+ * - [ ] Create adapter migration guide
+ *
+ * TODO: Limitations
+ * - [ ] Pino adapter requires 'pino' package (optional dependency)
+ * - [ ] Dynamic import may have performance impact
+ * - [ ] Log sanitization is basic (may need enhancement)
+ * - [ ] No log persistence (consider file/remote logging)
+ */