mulguard 1.1.7 → 1.1.8

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

@@ -1,93 +0,0 @@
-import { AuthResult, OAuthUserInfo, User, Session, OAuthProviderConfig, OAuthProvidersConfig, CallbacksConfig } from '../types';
-import { exchangeOAuthCode } from '../auth/oauth/providers';
-/**
- * OAuth handler configuration.
- */
-export interface OAuthHandlerConfig<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> {
-    readonly oauthProviders: OAuthProvidersConfig;
-    readonly baseUrl: string;
-    readonly callbacks: CallbacksConfig;
-    readonly createSession: (user: TUser, userInfo: OAuthUserInfo, tokens: Awaited<ReturnType<typeof exchangeOAuthCode>>) => TSession;
-    readonly saveSession: (session: TSession) => Promise<void>;
-    readonly onError?: (error: Error, context: string) => Promise<void> | void;
-}
-/**
- * OAuth state validation function.
- */
-export type ValidateOAuthState = (state: string, provider: string) => Promise<boolean>;
-/**
- * Creates OAuth callback handler.
- *
- * Automatically handles:
- * 1. Code exchange for tokens
- * 2. User profile retrieval
- * 3. User creation/lookup via callback
- * 4. Session creation and storage
- *
- * @template TUser - User type
- * @template TSession - Session type
- * @param config - OAuth handler configuration
- * @param validateState - Function to validate OAuth state
- * @returns OAuth callback handler
- *
- * @example
- * ```typescript
- * const handler = createOAuthCallbackHandler(config, validateState)
- * const result = await handler('google', 'code123', 'state456')
- * ```
- */
-export declare function createOAuthCallbackHandler<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(config: OAuthHandlerConfig<TUser, TSession>, _validateState: ValidateOAuthState): (provider: string, code: string, _state: string) => Promise<AuthResult<TUser, TSession>>;
-/**
- * Creates OAuth initiation action if providers are configured.
- *
- * @param oauthProviders - OAuth providers configuration
- * @param baseUrl - Base URL for redirects
- * @param generateState - Function to generate CSRF state
- * @param buildAuthUrl - Function to build authorization URL
- * @returns OAuth initiation action or undefined
- */
-export declare function createOAuthInitiationAction(oauthProviders: OAuthProvidersConfig, baseUrl: string, generateState: () => string, buildAuthUrl: (provider: string, config: OAuthProviderConfig, baseUrl: string, state: string) => string): ((provider: string) => Promise<{
-    url: string;
-    state: string;
-}>) | undefined;
-/**
- * TODO: Performance
- * - [ ] Add token exchange result caching
- * - [ ] Implement request retry logic
- * - [ ] Add connection pooling for OAuth API calls
- * - [ ] Cache user profile data
- *
- * TODO: Features
- * - [ ] Add PKCE support
- * - [ ] Implement token refresh flow
- * - [ ] Add OAuth 2.1 compliance
- * - [ ] Support for OpenID Connect
- * - [ ] Add account linking
- *
- * TODO: Type Safety
- * - [ ] Add type-safe provider configuration
- * - [ ] Create type-level endpoint validation
- * - [ ] Implement compile-time provider validation
- *
- * TODO: Security
- * - [ ] Add token validation before use
- * - [ ] Implement token encryption
- * - [ ] Add request signing
- * - [ ] Create security audit logging
- *
- * TODO: Testing
- * - [ ] Add comprehensive OAuth handler tests
- * - [ ] Test all provider flows
- * - [ ] Test error handling
- * - [ ] Add integration tests
- *
- * TODO: Documentation
- * - [ ] Document OAuth flow
- * - [ ] Add provider setup guides
- * - [ ] Create troubleshooting guide
- *
- * TODO: Limitations
- * - [ ] No support for OAuth 1.0
- * - [ ] Token refresh not implemented
- * - [ ] No PKCE support yet
- */

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

@@ -1,94 +0,0 @@
-import { Session, SessionConfig } from '../types';
-/**
- * Session cache entry.
- */
-interface SessionCacheEntry {
-    readonly session: Session | null;
-    readonly timestamp: number;
-}
-/**
- * Session manager configuration.
- */
-export interface SessionManagerConfig {
-    readonly sessionConfig: SessionConfig;
-    readonly cacheTtl: number;
-    readonly getSessionAction?: () => Promise<Session | null>;
-    readonly onSessionExpired?: (session: Session) => Promise<void> | void;
-    readonly onError?: (error: Error, context: string) => Promise<void> | void;
-}
-/**
- * Session operation result.
- */
-export interface SessionResult {
-    readonly success: boolean;
-    readonly error?: string;
-    readonly warning?: string;
-}
-/**
- * Creates a session manager instance.
- *
- * @param config - Session manager configuration
- * @returns Session manager functions
- */
-export declare function createSessionManager(config: SessionManagerConfig): {
-    getSession: () => Promise<Session | null>;
-    setSession: (session: Session) => Promise<SessionResult>;
-    clearSessionCookie: () => Promise<void>;
-    getAccessToken: () => Promise<string | null>;
-    getRefreshToken: () => Promise<string | null>;
-    hasValidTokens: () => Promise<boolean>;
-    clearCache: () => void;
-    getSessionConfig: () => {
-        cookieName: string;
-        config: SessionConfig;
-    };
-};
-/**
- * Type predicate to check if a value is a valid session cache entry.
- *
- * @param value - Value to check
- * @returns True if value is a valid cache entry
- */
-export declare function isSessionCacheEntry(value: unknown): value is SessionCacheEntry;
-export {};
-/**
- * TODO: Performance
- * - [ ] Add session compression for large sessions
- * - [ ] Implement session chunking for very large sessions
- * - [ ] Add session cache invalidation strategies
- * - [ ] Consider using WeakMap for session references
- *
- * TODO: Features
- * - [ ] Add session encryption at rest
- * - [ ] Implement session rotation
- * - [ ] Add session fingerprinting
- * - [ ] Create session analytics
- * - [ ] Add session migration support
- *
- * TODO: Type Safety
- * - [ ] Add type-level session validation
- * - [ ] Create type-safe session builders
- * - [ ] Implement session schema validation
- *
- * TODO: Security
- * - [ ] Add session hijacking detection
- * - [ ] Implement session timeout warnings
- * - [ ] Add session audit logging
- * - [ ] Create session security monitoring
- *
- * TODO: Testing
- * - [ ] Add comprehensive session manager tests
- * - [ ] Test cache invalidation
- * - [ ] Test session expiration
- * - [ ] Test error handling
- *
- * TODO: Documentation
- * - [ ] Document session lifecycle
- * - [ ] Add session best practices guide
- * - [ ] Create troubleshooting guide
- *
- * TODO: Limitations
- * - [ ] Session cache is in-memory (not shared across instances)
- * - [ ] No session persistence (consider database-backed sessions)
- * - [ ] Session validation is basic (consider schema validation)
- */

package/dist/core/security/csrf.d.ts

@@ -1,46 +0,0 @@
-/**
- * CSRF Protection utilities
- */
-export interface CSRFTokenStore {
-    get(key: string): string | null;
-    set(key: string, value: string, expiresIn?: number): void;
-    delete(key: string): void;
-}
-/**
- * In-memory CSRF token store (for server-side)
- */
-export declare class MemoryCSRFStore implements CSRFTokenStore {
-    private tokens;
-    get(key: string): string | null;
-    set(key: string, value: string, expiresIn?: number): void;
-    delete(key: string): void;
-    clear(): void;
-}
-/**
- * CSRF Protection manager
- */
-export declare class CSRFProtection {
-    private store;
-    private tokenLength;
-    constructor(store?: CSRFTokenStore, tokenLength?: number);
-    /**
-     * Generate CSRF token
-     */
-    generateToken(key: string, expiresIn?: number): string;
-    /**
-     * Validate CSRF token
-     */
-    validateToken(key: string, token: string): boolean;
-    /**
-     * Get stored token without validating
-     */
-    getToken(key: string): string | null;
-    /**
-     * Delete token
-     */
-    deleteToken(key: string): void;
-}
-/**
- * Create CSRF protection instance
- */
-export declare function createCSRFProtection(store?: CSRFTokenStore): CSRFProtection;

package/dist/core/security/headers.d.ts

@@ -1,24 +0,0 @@
-/**
- * Security Headers utilities
- */
-export interface SecurityHeaders {
-    'X-Content-Type-Options'?: string;
-    'X-Frame-Options'?: string;
-    'X-XSS-Protection'?: string;
-    'Strict-Transport-Security'?: string;
-    'Content-Security-Policy'?: string;
-    'Referrer-Policy'?: string;
-    'Permissions-Policy'?: string;
-}
-/**
- * Default security headers
- */
-export declare const DEFAULT_SECURITY_HEADERS: SecurityHeaders;
-/**
- * Get security headers
- */
-export declare function getSecurityHeaders(custom?: Partial<SecurityHeaders>): SecurityHeaders;
-/**
- * Apply security headers to response
- */
-export declare function applySecurityHeaders(headers: Headers, custom?: Partial<SecurityHeaders>): void;

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

@@ -1,132 +0,0 @@
-/**
- * Security utilities for Mulguard Authentication Library.
- *
- * Provides token generation, CSRF protection, input sanitization, and validation.
- *
- * @module @mulguard/core/security
- */
-/**
- * Generates a cryptographically secure random token.
- *
- * @param length - Token length in bytes (default: 32)
- * @returns Base64url-encoded token
- *
- * @example
- * ```typescript
- * const token = generateToken(32)
- * // Returns: 'abc123xyz...' (base64url encoded)
- * ```
- */
-export declare function generateToken(length?: number): string;
-/**
- * Generates a CSRF token for state validation.
- *
- * @returns Base64url-encoded CSRF token
- *
- * @example
- * ```typescript
- * const state = generateCSRFToken()
- * // Store state for validation
- * ```
- */
-export declare function generateCSRFToken(): string;
-/**
- * Validates a CSRF token using constant-time comparison.
- *
- * Uses constant-time comparison to prevent timing attacks.
- *
- * @param token - Token to validate
- * @param expected - Expected token value
- * @returns True if tokens match
- *
- * @example
- * ```typescript
- * const isValid = validateCSRFToken(receivedToken, storedToken)
- * if (!isValid) {
- *   throw new Error('Invalid CSRF token')
- * }
- * ```
- */
-export declare function validateCSRFToken(token: unknown, expected: unknown): boolean;
-/**
- * Type predicate to check if CSRF token is valid.
- *
- * @param token - Token to check
- * @param expected - Expected token
- * @returns True if token is valid
- */
-export declare function isValidCSRFToken(token: unknown, expected: unknown): token is string;
-/**
- * Sanitizes string input by trimming and removing dangerous characters.
- *
- * @param input - Input to sanitize
- * @returns Sanitized string
- *
- * @example
- * ```typescript
- * const sanitized = sanitizeInput('  <script>alert("xss")</script>  ')
- * // Returns: 'scriptalert("xss")script'
- * ```
- */
-export declare function sanitizeInput(input: unknown): string;
-/**
- * Validates email format.
- *
- * @param email - Email to validate
- * @returns True if email is valid
- *
- * @example
- * ```typescript
- * if (isValidEmail('user@example.com')) {
- *   // Email is valid
- * }
- * ```
- */
-export declare function isValidEmail(email: unknown): email is string;
-export * from './rate-limit';
-export * from './headers';
-export * from './validation';
-export * from './csrf';
-export * from './xss';
-/**
- * TODO: Performance
- * - [ ] Add token generation caching for high-frequency operations
- * - [ ] Optimize constant-time comparison for very long tokens
- * - [ ] Consider using Web Crypto API for token generation
- * - [ ] Add input sanitization result caching
- *
- * TODO: Features
- * - [ ] Add token expiration validation
- * - [ ] Implement token rotation support
- * - [ ] Add rate limiting for token generation
- * - [ ] Create token strength scoring
- * - [ ] Add token format validation helpers
- *
- * TODO: Type Safety
- * - [ ] Add branded types for tokens
- * - [ ] Create type-safe token validation
- * - [ ] Add type guards for all security functions
- * - [ ] Implement type-level security constraints
- *
- * TODO: Security
- * - [ ] Add token generation logging (with masking)
- * - [ ] Implement token blacklisting
- * - [ ] Add security event monitoring
- * - [ ] Create security audit logging
- *
- * TODO: Testing
- * - [ ] Add comprehensive security tests
- * - [ ] Test timing attack resistance
- * - [ ] Test token generation randomness
- * - [ ] Add fuzzing tests
- *
- * TODO: Documentation
- * - [ ] Document security best practices
- * - [ ] Add security considerations guide
- * - [ ] Document token lifecycle
- *
- * TODO: Limitations
- * - [ ] Token generation uses Node.js Buffer (consider Web Crypto API for browsers)
- * - [ ] Constant-time comparison may have micro-optimizations
- * - [ ] Email validation is basic (use validation.ts for comprehensive validation)
- */

package/dist/core/security/rate-limit.d.ts

@@ -1,39 +0,0 @@
-/**
- * Rate Limiting utilities
- * Client-side rate limiting helpers (actual rate limiting should be on backend)
- */
-export interface RateLimitConfig {
-    maxAttempts: number;
-    windowMs: number;
-    keyPrefix?: string;
-}
-export interface RateLimitResult {
-    allowed: boolean;
-    remaining: number;
-    resetAt: Date;
-}
-/**
- * Client-side rate limit tracker
- * Note: This is just a helper. Real rate limiting must be enforced on the backend.
- */
-export declare class RateLimiter {
-    private attempts;
-    private config;
-    constructor(config: RateLimitConfig);
-    /**
-     * Check if request is allowed
-     */
-    check(key: string): RateLimitResult;
-    /**
-     * Reset rate limit for a key
-     */
-    reset(key: string): void;
-    /**
-     * Clear all rate limits
-     */
-    clear(): void;
-}
-/**
- * Create rate limiter instance
- */
-export declare function createRateLimiter(config: RateLimitConfig): RateLimiter;

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

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