mulguard 1.1.6 → 1.1.7

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

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

package/dist/core/mulguard/oauth-handler.d.ts

@@ -1,5 +1,5 @@
 import { AuthResult, OAuthUserInfo, User, Session, OAuthProviderConfig, OAuthProvidersConfig, CallbacksConfig } from '../types';
-import { exchangeOAuthCode } from '../auth/oauth-providers';
+import { exchangeOAuthCode } from '../auth/oauth/providers';
 /**
  * OAuth handler configuration.
  */

package/dist/core/security/security-manager.d.ts

@@ -0,0 +1,236 @@
+import { CSRFTokenStore } from './csrf';
+import { ValidationResult } from './validation';
+import { Logger } from '../logger';
+/**
+ * Comprehensive security configuration.
+ */
+export interface SecurityConfig {
+    readonly csrfProtection?: {
+        readonly enabled: boolean;
+        readonly tokenLength?: number;
+        readonly expiresIn?: number;
+        readonly store?: CSRFTokenStore;
+    };
+    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 logger?: Logger;
+}
+/**
+ * Comprehensive security manager for authentication operations.
+ *
+ * Provides unified access to all security utilities with centralized configuration.
+ *
+ * @example
+ * ```typescript
+ * const security = new SecurityManager({
+ *   csrfProtection: { enabled: true },
+ *   rateLimiting: { enabled: true, maxAttempts: 5 },
+ * })
+ *
+ * // Validate email
+ * const emailResult = security.validateEmail('user@example.com')
+ *
+ * // Check rate limit
+ * const rateLimitResult = security.checkRateLimit('user@example.com')
+ * ```
+ */
+export declare class SecurityManager {
+    private readonly config;
+    private readonly csrfProtection;
+    private readonly rateLimiter;
+    constructor(config?: SecurityConfig);
+    /**
+     * Validates and sanitizes an email address.
+     *
+     * @param email - Email address to validate
+     * @returns Validation result with sanitized email if valid
+     * @throws ValidationError if validation fails and strict mode is enabled
+     *
+     * @example
+     * ```typescript
+     * const result = security.validateEmail('user@example.com')
+     * if (result.valid) {
+     *   console.log(result.sanitized) // 'user@example.com'
+     * }
+     * ```
+     */
+    validateEmail(email: unknown): ValidationResult<string>;
+    /**
+     * Validates and sanitizes a password with strength assessment.
+     *
+     * @param password - Password to validate
+     * @returns Validation result with strength indicator if valid
+     * @throws ValidationError if validation fails and strict mode is enabled
+     *
+     * @example
+     * ```typescript
+     * const result = security.validatePassword('MyP@ssw0rd!')
+     * if (result.valid) {
+     *   console.log(result.strength) // 'strong'
+     * }
+     * ```
+     */
+    validatePassword(password: unknown): ValidationResult<string>;
+    /**
+     * Validates and sanitizes a name.
+     *
+     * @param name - Name to validate
+     * @returns Validation result with sanitized name if valid
+     */
+    validateName(name: unknown): ValidationResult<string>;
+    /**
+     * Validates a token format.
+     *
+     * @param token - Token to validate
+     * @returns Validation result
+     */
+    validateToken(token: unknown): ValidationResult<string>;
+    /**
+     * Validates a URL.
+     *
+     * @param url - URL to validate
+     * @returns Validation result
+     */
+    validateURL(url: unknown): ValidationResult<string>;
+    /**
+     * Validates and sanitizes generic input with XSS prevention.
+     *
+     * @param input - Input to validate and sanitize
+     * @param options - Sanitization options
+     * @returns Validation result with sanitized input if valid
+     */
+    sanitizeInput(input: unknown, options?: {
+        maxLength?: number;
+        allowHtml?: boolean;
+        required?: boolean;
+    }): ValidationResult<string>;
+    /**
+     * Escapes HTML to prevent XSS.
+     *
+     * @param str - String to escape
+     * @returns Escaped string
+     */
+    escapeHTML(str: string): string;
+    /**
+     * Sanitizes user input with XSS prevention.
+     *
+     * @param input - Input to sanitize
+     * @returns Sanitized string
+     */
+    sanitizeUserInput(input: unknown): string;
+    /**
+     * Generates a CSRF token.
+     *
+     * @param key - Token key (e.g., session ID)
+     * @param expiresIn - Expiration time in milliseconds (optional)
+     * @returns CSRF token
+     * @throws Error if CSRF protection is disabled
+     */
+    generateCSRFToken(key: string, expiresIn?: number): string;
+    /**
+     * Validates a CSRF token.
+     *
+     * @param key - Token key (e.g., session ID)
+     * @param token - Token to validate
+     * @returns True if token is valid
+     */
+    validateCSRFToken(key: string, token: string): boolean;
+    /**
+     * Checks rate limit for a given key.
+     *
+     * @param key - Rate limit key (IP, user ID, email, etc.)
+     * @returns Rate limit result
+     * @throws RateLimitError if rate limit is exceeded
+     */
+    checkRateLimit(key: string): {
+        allowed: boolean;
+        remaining: number;
+        resetAt: Date;
+    };
+    /**
+     * Resets rate limit for a given key.
+     *
+     * @param key - Rate limit key
+     */
+    resetRateLimit(key: string): void;
+    /**
+     * Gets current security configuration.
+     *
+     * @returns Security configuration
+     */
+    getConfig(): Readonly<SecurityConfig>;
+}
+/**
+ * Creates a security manager instance.
+ *
+ * @param config - Security configuration
+ * @returns Security manager instance
+ *
+ * @example
+ * ```typescript
+ * const security = createSecurityManager({
+ *   csrfProtection: { enabled: true },
+ *   rateLimiting: { enabled: true, maxAttempts: 5 },
+ * })
+ * ```
+ */
+export declare function createSecurityManager(config?: SecurityConfig): SecurityManager;
+export * from './validation';
+export * from './csrf';
+export * from './rate-limit';
+export * from './xss';
+/**
+ * TODO: Performance
+ * - [ ] Add validation result caching (with TTL)
+ * - [ ] Optimize rate limiting with sliding window algorithm
+ * - [ ] Add batch validation support
+ * - [ ] Implement async validation for heavy operations
+ *
+ * TODO: Features
+ * - [ ] Add Redis-based rate limiting support
+ * - [ ] Implement distributed CSRF token storage
+ * - [ ] Add security event logging
+ * - [ ] Create security metrics collection
+ * - [ ] Add IP whitelist/blacklist support
+ * - [ ] Implement CAPTCHA integration
+ *
+ * TODO: Type Safety
+ * - [ ] Add branded types for validated inputs
+ * - [ ] Create type-safe security configuration
+ * - [ ] Implement compile-time validation rules
+ *
+ * TODO: Security
+ * - [ ] Add security headers management
+ * - [ ] Implement content security policy (CSP) helpers
+ * - [ ] Add security audit logging
+ * - [ ] Create security incident reporting
+ *
+ * TODO: Testing
+ * - [ ] Add comprehensive unit tests
+ * - [ ] Test rate limiting edge cases
+ * - [ ] Test CSRF token expiration
+ * - [ ] Add security fuzzing tests
+ *
+ * TODO: Documentation
+ * - [ ] Document security best practices
+ * - [ ] Add security configuration guide
+ * - [ ] Create security troubleshooting guide
+ *
+ * TODO: Limitations
+ * - [ ] Rate limiting is in-memory (consider Redis for distributed systems)
+ * - [ ] CSRF tokens are in-memory (consider persistent storage)
+ * - [ ] HTML sanitization is basic (consider DOMPurify for complex cases)
+ */

package/dist/core/session/session-manager.d.ts

@@ -0,0 +1,235 @@
+import { Session, User, SessionConfig } from '../types';
+import { Logger } from '../logger';
+/**
+ * Session storage adapter interface.
+ */
+export interface SessionStorageAdapter {
+    /**
+     * Gets a session by key.
+     *
+     * @param key - Session key
+     * @returns Session data or null if not found
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Sets a session.
+     *
+     * @param key - Session key
+     * @param value - Session data
+     * @param expiresIn - Expiration time in milliseconds
+     */
+    set(key: string, value: string, expiresIn: number): Promise<void>;
+    /**
+     * Deletes a session.
+     *
+     * @param key - Session key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clears all sessions (optional).
+     */
+    clear?(): Promise<void>;
+}
+/**
+ * Cookie-based session storage adapter.
+ *
+ * Uses browser/document.cookie for client-side or Next.js cookies() for server-side.
+ */
+export declare class CookieSessionStorage implements SessionStorageAdapter {
+    private readonly cookieName;
+    private readonly cookieOptions;
+    constructor(cookieName: string, options?: {
+        readonly httpOnly?: boolean;
+        readonly secure?: boolean;
+        readonly sameSite?: 'strict' | 'lax' | 'none';
+        readonly path?: string;
+        readonly domain?: string;
+    });
+    get(_key: string): Promise<string | null>;
+    set(_key: string, value: string, expiresIn: number): Promise<void>;
+    delete(_key: string): Promise<void>;
+}
+/**
+ * In-memory session storage adapter (for testing or development).
+ */
+export declare class MemorySessionStorage implements SessionStorageAdapter {
+    private readonly storage;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, expiresIn: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Session manager configuration.
+ */
+export interface SessionManagerConfig extends SessionConfig {
+    readonly storage?: SessionStorageAdapter;
+    readonly logger?: Logger;
+}
+/**
+ * Comprehensive session manager for authentication operations.
+ *
+ * Handles session creation, validation, storage, and expiration with
+ * support for multiple storage backends and caching.
+ *
+ * @example
+ * ```typescript
+ * const sessionManager = new SessionManager({
+ *   cookieName: '__mulguard_session',
+ *   expiresIn: 60 * 60 * 24 * 7, // 7 days
+ *   httpOnly: true,
+ *   secure: true,
+ * })
+ *
+ * // Create session
+ * const session = await sessionManager.createSession(user)
+ *
+ * // Get session
+ * const currentSession = await sessionManager.getSession()
+ * ```
+ */
+export declare class SessionManager {
+    private readonly config;
+    private readonly storage;
+    private readonly cache;
+    private readonly cacheTtl;
+    constructor(config: SessionManagerConfig);
+    /**
+     * Creates a new session for a user.
+     *
+     * @param user - User object
+     * @param additionalData - Additional session data (optional)
+     * @returns Created session
+     *
+     * @example
+     * ```typescript
+     * const session = await sessionManager.createSession(user, {
+     *   accessToken: 'token123',
+     * })
+     * ```
+     */
+    createSession<TUser extends User = User>(user: TUser, additionalData?: Partial<Omit<Session<TUser>, 'user' | 'expiresAt'>>): Promise<Session<TUser>>;
+    /**
+     * Gets the current session.
+     *
+     * Checks cache first, then storage, and validates expiration.
+     *
+     * @returns Current session or null if not found/expired
+     *
+     * @example
+     * ```typescript
+     * const session = await sessionManager.getSession()
+     * if (session) {
+     *   console.log('User:', session.user.email)
+     * }
+     * ```
+     */
+    getSession<TUser extends User = User>(): Promise<Session<TUser> | null>;
+    /**
+     * Saves a session to storage.
+     *
+     * @param session - Session to save
+     *
+     * @example
+     * ```typescript
+     * await sessionManager.saveSession(session)
+     * ```
+     */
+    saveSession<TUser extends User = User>(session: Session<TUser>): Promise<void>;
+    /**
+     * Deletes the current session.
+     *
+     * @example
+     * ```typescript
+     * await sessionManager.deleteSession()
+     * ```
+     */
+    deleteSession(): Promise<void>;
+    /**
+     * Validates a session.
+     *
+     * @param session - Session to validate
+     * @returns True if session is valid
+     *
+     * @example
+     * ```typescript
+     * if (sessionManager.validateSession(session)) {
+     *   // Session is valid
+     * }
+     * ```
+     */
+    validateSession<TUser extends User = User>(session: Session<TUser>): boolean;
+    /**
+     * Clears the session cache.
+     */
+    clearCache(): void;
+    /**
+     * Cleans up expired cache entries.
+     */
+    private cleanupCache;
+    /**
+     * Gets session configuration.
+     *
+     * @returns Session configuration
+     */
+    getConfig(): Readonly<SessionManagerConfig>;
+}
+/**
+ * Creates a session manager instance.
+ *
+ * @param config - Session manager configuration
+ * @returns Session manager instance
+ *
+ * @example
+ * ```typescript
+ * const sessionManager = createSessionManager({
+ *   cookieName: '__mulguard_session',
+ *   expiresIn: 60 * 60 * 24 * 7,
+ * })
+ * ```
+ */
+export declare function createSessionManager(config: SessionManagerConfig): SessionManager;
+export * from './index';
+/**
+ * TODO: Performance
+ * - [ ] Add session compression for large sessions
+ * - [ ] Implement session chunking for very large sessions
+ * - [ ] Add session indexing for faster lookups
+ * - [ ] Optimize cache eviction strategy
+ *
+ * TODO: Features
+ * - [ ] Add Redis-based session storage adapter
+ * - [ ] Implement database session storage adapter
+ * - [ ] Add session refresh mechanism
+ * - [ ] Create session migration support
+ * - [ ] Add session analytics
+ * - [ ] Implement session sharing across subdomains
+ *
+ * TODO: Type Safety
+ * - [ ] Add branded types for session IDs
+ * - [ ] Create type-safe session data validation
+ * - [ ] Implement compile-time session schema validation
+ *
+ * TODO: Security
+ * - [ ] Add session encryption support
+ * - [ ] Implement session signing
+ * - [ ] Add session fingerprinting
+ * - [ ] Create session audit logging
+ * - [ ] Add session hijacking detection
+ *
+ * TODO: Testing
+ * - [ ] Add comprehensive unit tests
+ * - [ ] Test session expiration handling
+ * - [ ] Test cache invalidation
+ * - [ ] Add storage adapter tests
+ *
+ * TODO: Documentation
+ * - [ ] Document session lifecycle
+ * - [ ] Add storage adapter guide
+ * - [ ] Create session best practices guide
+ *
+ * TODO: Limitations
+ * - [ ] Cookie storage has size limits (~4KB)
+ * - [ ] Memory storage is not persistent
+ * - [ ] Cache cleanup runs on interval (consider event-based)
+ */

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

@@ -182,14 +182,36 @@ export interface SessionConfig {
 /**
  * Security configuration options.
  *
- * @property csrfProtection - Enable CSRF protection (default: true)
- * @property rateLimiting - Enable rate limiting (default: true)
+ * 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?: boolean;
-    readonly rateLimiting?: boolean;
+    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[];
 }
@@ -281,7 +303,7 @@ export interface MulguardConfig<TUser extends User = User, TSession extends Sess
     readonly providers?: {
         readonly oauth?: OAuthProvidersConfig;
     };
-    readonly oauthStateStore?: import('../auth/oauth-state-store').OAuthStateStore;
+    readonly oauthStateStore?: import('../auth/oauth/state-store').OAuthStateStore;
     readonly sessionCacheTtl?: number;
 }
 export type { User, Session, AuthResult, SuccessfulAuthResult, FailedAuthResult, TwoFactorAuthResult, EmailCredentials, RegisterData, Verify2FAData, };