mulguard 1.1.7 → 1.1.8

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

@@ -1,251 +0,0 @@
-/**
- * Input validation and sanitization utilities with type safety.
- *
- * @module @mulguard/core/security/validation
- */
-/**
- * Validation result type.
- *
- * @template T - Type of sanitized value
- */
-export interface ValidationResult<T = string> {
-    readonly valid: boolean;
-    readonly sanitized?: T;
-    readonly error?: string;
-}
-/**
- * Email validation result.
- */
-export type EmailValidationResult = ValidationResult<string>;
-/**
- * Password validation result with strength indicator.
- */
-export interface PasswordValidationResult extends ValidationResult<string> {
-    readonly strength?: 'weak' | 'medium' | 'strong';
-}
-/**
- * Name validation result.
- */
-export type NameValidationResult = ValidationResult<string>;
-/**
- * Token validation result.
- */
-export type TokenValidationResult = ValidationResult<string>;
-/**
- * URL validation result.
- */
-export type URLValidationResult = ValidationResult<string>;
-/**
- * Input sanitization options.
- */
-export interface SanitizeOptions {
-    readonly maxLength?: number;
-    readonly allowHtml?: boolean;
-    readonly required?: boolean;
-}
-/**
- * Validates and sanitizes an email address.
- *
- * @param email - Email address to validate
- * @returns Validation result with sanitized email if valid
- *
- * @example
- * ```typescript
- * const result = validateAndSanitizeEmail('  User@Example.COM  ')
- * if (result.valid) {
- *   console.log(result.sanitized) // 'user@example.com'
- * }
- * ```
- */
-export declare function validateAndSanitizeEmail(email: unknown): EmailValidationResult;
-/**
- * Type predicate to check if email validation result is valid.
- *
- * @param result - Validation result to check
- * @returns True if validation is successful
- *
- * @example
- * ```typescript
- * const result = validateAndSanitizeEmail(email)
- * if (isValidEmail(result)) {
- *   // TypeScript knows result.sanitized exists
- *   console.log(result.sanitized)
- * }
- * ```
- */
-export declare function isValidEmail(result: EmailValidationResult): result is EmailValidationResult & {
-    valid: true;
-    sanitized: string;
-};
-/**
- * Validates and sanitizes a password with strength assessment.
- *
- * @param password - Password to validate
- * @param minLength - Minimum password length (default: 8)
- * @returns Validation result with strength indicator if valid
- *
- * @example
- * ```typescript
- * const result = validateAndSanitizePassword('MyP@ssw0rd!')
- * if (result.valid) {
- *   console.log(result.strength) // 'strong'
- * }
- * ```
- */
-export declare function validateAndSanitizePassword(password: unknown, minLength?: number): PasswordValidationResult;
-/**
- * Type predicate to check if password validation result is valid.
- *
- * @param result - Validation result to check
- * @returns True if validation is successful
- */
-export declare function isValidPassword(result: PasswordValidationResult): result is PasswordValidationResult & {
-    valid: true;
-    sanitized: string;
-};
-/**
- * Validates and sanitizes a name.
- *
- * @param name - Name to validate
- * @returns Validation result with sanitized name if valid
- *
- * @example
- * ```typescript
- * const result = validateAndSanitizeName('  John Doe  ')
- * if (result.valid) {
- *   console.log(result.sanitized) // 'John Doe'
- * }
- * ```
- */
-export declare function validateAndSanitizeName(name: unknown): NameValidationResult;
-/**
- * Type predicate to check if name validation result is valid.
- *
- * @param result - Validation result to check
- * @returns True if validation is successful
- */
-export declare function isValidName(result: NameValidationResult): result is NameValidationResult & {
-    valid: true;
-    sanitized: string;
-};
-/**
- * Validates a URL.
- *
- * @param url - URL to validate
- * @returns Validation result
- *
- * @example
- * ```typescript
- * const result = validateURL('https://example.com')
- * if (result.valid) {
- *   // URL is valid
- * }
- * ```
- */
-export declare function validateURL(url: unknown): URLValidationResult;
-/**
- * Type predicate to check if URL validation result is valid.
- *
- * @param result - Validation result to check
- * @returns True if validation is successful
- */
-export declare function isValidURL(result: URLValidationResult): result is URLValidationResult & {
-    valid: true;
-    sanitized: string;
-};
-/**
- * Validates a token format with security checks.
- *
- * @param token - Token to validate
- * @param minLength - Minimum token length (default: 16)
- * @returns Validation result
- *
- * @example
- * ```typescript
- * const result = validateToken('abc123xyz')
- * if (result.valid) {
- *   // Token is valid
- * }
- * ```
- */
-export declare function validateToken(token: unknown, minLength?: number): TokenValidationResult;
-/**
- * Type predicate to check if token validation result is valid.
- *
- * @param result - Validation result to check
- * @returns True if validation is successful
- */
-export declare function isValidToken(result: TokenValidationResult): result is TokenValidationResult & {
-    valid: true;
-    sanitized: 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
- *
- * @example
- * ```typescript
- * const result = validateAndSanitizeInput('<script>alert("xss")</script>', { allowHtml: false })
- * if (result.valid) {
- *   console.log(result.sanitized) // HTML escaped
- * }
- * ```
- */
-export declare function validateAndSanitizeInput(input: unknown, options?: SanitizeOptions): ValidationResult<string>;
-/**
- * Type predicate to check if input validation result is valid.
- *
- * @param result - Validation result to check
- * @returns True if validation is successful
- */
-export declare function isValidInput(result: ValidationResult<string>): result is ValidationResult<string> & {
-    valid: true;
-    sanitized: string;
-};
-/**
- * TODO: Performance
- * - [ ] Cache compiled regex patterns
- * - [ ] Optimize password strength calculation
- * - [ ] Add input length pre-check before full validation
- * - [ ] Consider using Web Crypto API for token validation
- *
- * TODO: Features
- * - [ ] Add internationalized email validation (IDN support)
- * - [ ] Implement password breach checking (Have I Been Pwned API)
- * - [ ] Add phone number validation
- * - [ ] Create validation rule builder pattern
- * - [ ] Add custom validation rule support
- * - [ ] Implement validation result chaining
- *
- * TODO: Type Safety
- * - [ ] Add branded types for validated inputs
- * - [ ] Create type-level validation constraints
- * - [ ] Implement compile-time validation rules
- * - [ ] Add type guards for all validation results
- *
- * TODO: Security
- * - [ ] Add rate limiting for validation attempts
- * - [ ] Implement validation result caching (with TTL)
- * - [ ] Add validation logging for security monitoring
- * - [ ] Create validation error reporting
- *
- * TODO: Testing
- * - [ ] Add comprehensive unit tests for all validators
- * - [ ] Test edge cases (Unicode, emoji, etc.)
- * - [ ] Test performance with large inputs
- * - [ ] Add fuzzing tests for security
- *
- * TODO: Documentation
- * - [ ] Add more JSDoc examples
- * - [ ] Document validation rules and limits
- * - [ ] Create validation best practices guide
- *
- * TODO: Limitations
- * - [ ] Email validation is simplified (not full RFC 5322)
- * - [ ] Password strength is basic (consider zxcvbn library)
- * - [ ] HTML sanitization is basic (consider DOMPurify for complex cases)
- * - [ ] No support for custom validation rules yet
- */

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

@@ -1,20 +0,0 @@
-/**
- * XSS Protection utilities
- */
-/**
- * Escape HTML to prevent XSS
- */
-export declare function escapeHTML(str: string): string;
-/**
- * Sanitize HTML (basic)
- * Note: For production, use a proper HTML sanitizer library like DOMPurify
- */
-export declare function sanitizeHTML(html: string): string;
-/**
- * Validate and sanitize user input
- */
-export declare function sanitizeUserInput(input: unknown): string;
-/**
- * Check for potential XSS patterns
- */
-export declare function containsXSSPattern(input: string): boolean;

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

@@ -1,35 +0,0 @@
-/**
- * Session management utilities
- */
-export interface SessionStorage {
-    get(key: string): string | null;
-    set(key: string, value: string, options?: SessionCookieOptions): void;
-    remove(key: string): void;
-}
-export interface SessionCookieOptions {
-    expires?: Date | number;
-    maxAge?: number;
-    domain?: string;
-    path?: string;
-    secure?: boolean;
-    httpOnly?: boolean;
-    sameSite?: 'strict' | 'lax' | 'none';
-}
-/**
- * Cookie storage implementation (client-side only)
- * Note: This is for browser environments. Server-side should use Next.js cookies() API
- */
-export declare class CookieStorage implements SessionStorage {
-    get(key: string): string | null;
-    set(key: string, value: string, options?: SessionCookieOptions): void;
-    remove(key: string): void;
-}
-/**
- * Memory storage implementation (for testing)
- */
-export declare class MemoryStorage implements SessionStorage {
-    private storage;
-    get(key: string): string | null;
-    set(key: string, value: string): void;
-    remove(key: string): void;
-}

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

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