mulguard 1.1.7 → 1.1.8

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

@@ -1,269 +0,0 @@
-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

@@ -1,9 +0,0 @@
-/**
- * Core authentication library - framework agnostic
- * Part of mulguard package
- */
-export type { MulguardConfig, SessionConfig, SecurityConfig, CallbacksConfig, AuthActions, Session, User, AuthResult, EmailCredentials, RegisterData, RequestContext, } from './types';
-export * from './security';
-export * from './utils/auth-helpers';
-export * from './auth/signin-unified';
-export * from './auth/oauth';

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

@@ -1,147 +0,0 @@
-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)
- */

package/dist/core/mulguard/auth-handlers.d.ts

@@ -1,100 +0,0 @@
-import { AuthResult, EmailCredentials, RegisterData, User, Session, AuthActions, CallbacksConfig } from '../types';
-/**
- * Authentication handlers configuration.
- */
-export interface AuthHandlersConfig<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> {
-    readonly actions: AuthActions<TUser, TSession>;
-    readonly callbacks: CallbacksConfig;
-    readonly saveSessionAfterAuth: (result: AuthResult<TUser, TSession>) => Promise<{
-        success: boolean;
-        error?: string;
-        warning?: string;
-    }>;
-    readonly onError?: (error: Error, context: string) => Promise<void> | void;
-}
-/**
- * Sign-in handlers result.
- */
-export interface SignInHandlers<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>>;
-}
-/**
- * Creates unified sign-in handler that supports both provider-based and direct method calls.
- *
- * @template TUser - User type
- * @template TSession - Session type
- * @param config - Handler configuration
- * @param storeOAuthState - Function to store OAuth state
- * @returns Unified sign-in handler
- */
-export declare function createUnifiedSignInHandler<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(config: AuthHandlersConfig<TUser, TSession>, storeOAuthState: (state: string, provider: string) => Promise<void>): SignInHandlers<TUser, TSession> & {
-    (provider: string): Promise<{
-        url: string;
-        state: string;
-    }>;
-    (provider: 'credentials', credentials: EmailCredentials): Promise<AuthResult<TUser, TSession>>;
-    (provider: 'otp', options: {
-        email: string;
-        code?: string;
-    }): Promise<AuthResult<TUser, TSession>>;
-    (provider: 'passkey', options?: {
-        userId?: string;
-    }): Promise<AuthResult<TUser, TSession>>;
-};
-/**
- * Creates sign-up handler.
- *
- * @template TUser - User type
- * @template TSession - Session type
- * @param config - Handler configuration
- * @returns Sign-up handler
- */
-export declare function createSignUpHandler<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(config: AuthHandlersConfig<TUser, TSession>): (data: RegisterData) => Promise<AuthResult<TUser, TSession>>;
-/**
- * TODO: Performance
- * - [ ] Add request deduplication for concurrent sign-in attempts
- * - [ ] Implement rate limiting per email/IP
- * - [ ] Add sign-in attempt caching
- * - [ ] Optimize validation logic
- *
- * TODO: Features
- * - [ ] Add social login account linking
- * - [ ] Implement sign-in with magic link
- * - [ ] Add biometric authentication support
- * - [ ] Create sign-in attempt tracking
- *
- * TODO: Type Safety
- * - [ ] Add runtime validation for all inputs
- * - [ ] Create type-safe credential builders
- * - [ ] Implement compile-time provider validation
- *
- * TODO: Security
- * - [ ] Add CAPTCHA support for repeated failures
- * - [ ] Implement account lockout after failed attempts
- * - [ ] Add device fingerprinting
- * - [ ] Create security event logging
- *
- * TODO: Testing
- * - [ ] Add comprehensive handler tests
- * - [ ] Test all validation scenarios
- * - [ ] Test error handling
- * - [ ] Add integration tests
- *
- * TODO: Documentation
- * - [ ] Document all sign-in methods
- * - [ ] Add usage examples
- * - [ ] Create troubleshooting guide
- *
- * TODO: Limitations
- * - [ ] Input validation is basic (consider schema validation)
- * - [ ] No support for custom validation rules
- * - [ ] Error messages may be too generic
- */

package/dist/core/mulguard/defaults.d.ts

@@ -1,58 +0,0 @@
-import { SessionConfig } from '../types';
-import { TokenRefreshConfig } from '../client/token-refresh-manager';
-/**
- * Default session configuration.
- *
- * Auto-detects environment and applies secure defaults.
- *
- * @returns Default session configuration
- */
-export declare function getDefaultSessionConfig(): SessionConfig;
-/**
- * Default token refresh configuration.
- *
- * Optimized to prevent infinite loops and improve performance.
- *
- * @returns Default token refresh configuration
- */
-export declare function getDefaultTokenRefreshConfig(): TokenRefreshConfig;
-/**
- * Gets the base URL for OAuth redirects.
- *
- * Detects the base URL from environment variables or defaults to localhost.
- *
- * @returns Base URL string
- */
-export declare function getBaseUrl(): string;
-/**
- * TODO: Performance
- * - [ ] Cache base URL detection result
- * - [ ] Add configuration validation at startup
- * - [ ] Implement configuration hot-reload support
- *
- * TODO: Features
- * - [ ] Add environment-specific configuration presets
- * - [ ] Create configuration builder pattern
- * - [ ] Add configuration schema validation
- * - [ ] Implement configuration inheritance
- *
- * TODO: Type Safety
- * - [ ] Add type-level validation for configuration values
- * - [ ] Create branded types for configuration
- * - [ ] Implement compile-time configuration checking
- *
- * TODO: Testing
- * - [ ] Add tests for default configurations
- * - [ ] Test environment detection
- * - [ ] Test configuration merging
- *
- * TODO: Documentation
- * - [ ] Document all default values
- * - [ ] Add configuration examples
- * - [ ] Create configuration reference guide
- *
- * TODO: Limitations
- * - [ ] Base URL detection is basic (consider more sophisticated detection)
- * - [ ] No configuration validation at runtime
- * - [ ] Defaults are fixed (consider configurable defaults)
- */

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

@@ -1,9 +0,0 @@
-/**
- * Mulguard core modules.
- *
- * @module @mulguard/core/mulguard
- */
-export * from './defaults';
-export * from './session-manager';
-export * from './auth-handlers';
-export * from './oauth-handler';

package/dist/core/mulguard/integration.d.ts

@@ -1,104 +0,0 @@
-import { MulguardConfig, User, Session, EmailCredentials } from '../types';
-import { SecurityManager } from '../security/security-manager';
-import { SessionManager as CoreSessionManager } from '../session/session-manager';
-import { EmailPasswordAuth } from '../auth/email-password';
-import { OTPAuth } from '../auth/otp';
-import { OAuthHandler } from '../auth/oauth/oauth-handler';
-import { Logger } from '../logger';
-/**
- * Core modules integration configuration.
- */
-export interface CoreModulesIntegrationConfig<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> {
-    readonly config: MulguardConfig<TUser, TSession>;
-    readonly baseUrl: string;
-}
-/**
- * Integrated core modules instance.
- */
-export interface IntegratedCoreModules {
-    readonly security: SecurityManager;
-    readonly session: CoreSessionManager;
-    readonly emailPassword: EmailPasswordAuth;
-    readonly otp: OTPAuth;
-    readonly oauth: OAuthHandler | null;
-    readonly logger: Logger;
-}
-/**
- * Creates integrated core modules for Mulguard instance.
- *
- * Initializes and configures all core modules with proper dependencies.
- *
- * @template TUser - User type
- * @template TSession - Session type
- * @param integrationConfig - Integration configuration
- * @returns Integrated core modules
- *
- * @example
- * ```typescript
- * const modules = createCoreModulesIntegration({
- *   config: mulguardConfig,
- *   baseUrl: 'https://example.com',
- * })
- *
- * // Use modules.security, modules.session, etc.
- * ```
- */
-export declare function createCoreModulesIntegration<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(integrationConfig: CoreModulesIntegrationConfig<TUser, TSession>): IntegratedCoreModules;
-/**
- * Creates a wrapper for custom email/password action that uses EmailPasswordAuth.
- *
- * @template TUser - User type
- * @template TSession - Session type
- * @param emailPassword - EmailPasswordAuth instance
- * @param customAction - Custom action from config
- * @returns Wrapped action that uses EmailPasswordAuth for validation
- */
-export declare function wrapEmailPasswordAction<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(emailPassword: EmailPasswordAuth, customAction: (credentials: EmailCredentials) => Promise<import('../types').AuthResult<TUser, TSession>>): (credentials: EmailCredentials) => Promise<import('../types').AuthResult<TUser, TSession>>;
-/**
- * Creates a wrapper for custom OTP action that uses OTPAuth.
- *
- * @template TUser - User type
- * @template TSession - Session type
- * @param otp - OTPAuth instance
- * @param customAction - Custom action from config
- * @returns Wrapped action that uses OTPAuth for validation
- */
-export declare function wrapOTPAction<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(otp: OTPAuth, customAction: (email: string, code?: string) => Promise<import('../types').AuthResult<TUser, TSession>>): (email: string, code?: string) => Promise<import('../types').AuthResult<TUser, TSession>>;
-export type { SecurityManager, SecurityConfig } from '../security/security-manager';
-export type { SessionManager, SessionManagerConfig } from '../session/session-manager';
-export type { EmailPasswordAuth, EmailPasswordConfig } from '../auth/email-password';
-export type { OTPAuth, OTPConfig } from '../auth/otp';
-export type { OAuthHandler, OAuthHandlerConfig } from '../auth/oauth/oauth-handler';
-/**
- * TODO: Performance
- * - [ ] Add module initialization caching
- * - [ ] Optimize module dependency resolution
- * - [ ] Add lazy module loading
- * - [ ] Implement module pooling
- *
- * TODO: Features
- * - [ ] Add module health checks
- * - [ ] Implement module reloading
- * - [ ] Create module dependency graph
- * - [ ] Add module metrics collection
- *
- * TODO: Type Safety
- * - [ ] Add type-safe module configuration
- * - [ ] Create compile-time module validation
- * - [ ] Implement type-level dependency checking
- *
- * TODO: Testing
- * - [ ] Add integration tests for module initialization
- * - [ ] Test module dependency resolution
- * - [ ] Test module error handling
- *
- * TODO: Documentation
- * - [ ] Document module integration flow
- * - [ ] Add module configuration guide
- * - [ ] Create module troubleshooting guide
- *
- * TODO: Limitations
- * - [ ] Module initialization is synchronous (consider async initialization)
- * - [ ] No module dependency validation at runtime
- * - [ ] Module configuration is fixed (consider dynamic configuration)
- */