mulguard 1.1.6 → 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/types/auth.d.ts

@@ -1,290 +0,0 @@
-import { AuthErrorCode } from './errors';
-/**
- * User interface representing an authenticated user.
- *
- * @property id - Unique user identifier
- * @property email - User email address
- * @property name - User display name
- * @property avatar - Optional avatar URL
- * @property roles - Optional user roles array
- * @property emailVerified - Email verification status
- *
- * @example
- * ```typescript
- * const user: User = {
- *   id: '123',
- *   email: 'user@example.com',
- *   name: 'John Doe',
- *   emailVerified: true
- * }
- * ```
- */
-export interface User {
-    readonly id: string;
-    readonly email: string;
-    readonly name: string;
-    readonly avatar?: string;
-    readonly roles?: readonly string[];
-    readonly emailVerified?: boolean;
-    readonly [key: string]: unknown;
-}
-/**
- * Session object containing user information and authentication tokens.
- *
- * @template TUser - User type (defaults to base User)
- *
- * @property user - User object with authentication information
- * @property expiresAt - Session expiration date/time
- * @property accessToken - Access token for API authentication (optional)
- * @property refreshToken - Refresh token for token refresh (optional)
- * @property tokenType - Type of token (default: 'Bearer')
- * @property expiresIn - Token expiration time in seconds (optional)
- * @property refreshTokenExpiresAt - Refresh token expiration date/time (optional)
- *
- * @example
- * ```typescript
- * const session: Session = {
- *   user: { id: '123', email: 'user@example.com', name: 'John' },
- *   expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
- *   accessToken: 'token123',
- *   tokenType: 'Bearer'
- * }
- * ```
- */
-export interface Session<TUser extends User = User> {
-    readonly user: TUser;
-    readonly expiresAt: Date | string;
-    readonly accessToken?: string;
-    readonly refreshToken?: string;
-    readonly tokenType?: 'Bearer' | 'Basic';
-    readonly expiresIn?: number;
-    readonly refreshTokenExpiresAt?: Date | string;
-    readonly [key: string]: unknown;
-}
-/**
- * Base authentication result type.
- *
- * @template TUser - User type (defaults to base User)
- * @template TSession - Session type (defaults to base Session)
- *
- * @property success - Whether the authentication was successful
- * @property user - User object if authentication succeeded
- * @property session - Session object if authentication succeeded
- * @property error - Error message if authentication failed
- * @property errorCode - Specific error code for programmatic error handling
- * @property requires2FA - Whether 2FA verification is required
- * @property email - Email address (required when requires2FA is true)
- * @property userId - User ID (required when requires2FA is true)
- *
- * @example
- * ```typescript
- * const result = await auth.signIn.email(credentials)
- * if (result.success) {
- *   // TypeScript knows result.user and result.session exist
- *   console.log(result.user.email)
- * } else if (result.requires2FA) {
- *   // TypeScript knows result.email and result.userId exist
- *   await auth.verify2FA({ email: result.email, userId: result.userId, code: '123456' })
- * }
- * ```
- */
-export interface AuthResult<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> {
-    readonly success: boolean;
-    readonly user?: TUser;
-    readonly session?: TSession;
-    readonly error?: string;
-    readonly errorCode?: AuthErrorCode;
-    readonly requires2FA?: boolean;
-    readonly email?: string;
-    readonly userId?: string;
-}
-/**
- * Successful authentication result type.
- *
- * @template TUser - User type
- * @template TSession - Session type
- */
-export type SuccessfulAuthResult<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> = AuthResult<TUser, TSession> & {
-    readonly success: true;
-    readonly user: TUser;
-    readonly session: TSession;
-};
-/**
- * Failed authentication result type.
- *
- * @template TUser - User type
- * @template TSession - Session type
- */
-export type FailedAuthResult<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> = AuthResult<TUser, TSession> & {
-    readonly success: false;
-    readonly error: string;
-};
-/**
- * Two-factor authentication required result type.
- *
- * This type is returned when 2FA verification is required after initial authentication.
- * Use the `isTwoFactorRequired()` type guard to narrow to this type.
- *
- * @template TUser - User type
- * @template TSession - Session type
- *
- * @property success - Always false
- * @property requires2FA - Always true
- * @property email - Email address of the user requiring 2FA
- * @property userId - User ID requiring 2FA
- * @property errorCode - Always AuthErrorCode.TWO_FA_REQUIRED
- * @property twoFactorMethod - Method of 2FA (optional)
- * @property challengeToken - Challenge token for 2FA verification (optional)
- *
- * @example
- * ```typescript
- * const result = await auth.signIn.email(credentials)
- * if (isTwoFactorRequired(result)) {
- *   // TypeScript knows result is TwoFactorAuthResult here
- *   console.log('2FA required for:', result.email)
- *   console.log('Method:', result.twoFactorMethod)
- * }
- * ```
- */
-export interface TwoFactorAuthResult<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> extends AuthResult<TUser, TSession> {
-    readonly success: false;
-    readonly requires2FA: true;
-    readonly email: string;
-    readonly userId: string;
-    readonly error: '2FA_REQUIRED';
-    readonly errorCode: AuthErrorCode.TWO_FA_REQUIRED;
-    readonly twoFactorMethod?: 'totp' | 'sms' | 'email';
-    readonly challengeToken?: string;
-}
-/**
- * Email and password credentials for authentication.
- *
- * @property email - User email address
- * @property password - User password
- */
-export interface EmailCredentials {
-    readonly email: string;
-    readonly password: string;
-}
-/**
- * User registration data.
- *
- * @property email - User email address
- * @property password - User password
- * @property name - User display name
- */
-export interface RegisterData {
-    readonly email: string;
-    readonly password: string;
-    readonly name: string;
-    readonly [key: string]: unknown;
-}
-/**
- * Data required for 2FA verification.
- *
- * @property email - User email address
- * @property userId - User ID
- * @property code - 2FA verification code
- */
-export interface Verify2FAData {
-    readonly email: string;
-    readonly userId: string;
-    readonly code: string;
-}
-/**
- * Type predicate to check if AuthResult indicates success.
- *
- * @template TUser - User type
- * @template TSession - Session type
- * @param result - AuthResult to check
- * @returns True if result is successful
- *
- * @example
- * ```typescript
- * const result = await auth.signIn.email(credentials)
- * if (isAuthSuccess(result)) {
- *   // TypeScript narrows to SuccessfulAuthResult
- *   console.log(result.user.email) // ✅ Type-safe
- *   console.log(result.session.expiresAt) // ✅ Type-safe
- * }
- * ```
- */
-export declare function isAuthSuccess<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(result: AuthResult<TUser, TSession>): result is SuccessfulAuthResult<TUser, TSession>;
-/**
- * Type predicate to check if AuthResult indicates failure.
- *
- * @template TUser - User type
- * @template TSession - Session type
- * @param result - AuthResult to check
- * @returns True if result indicates failure
- *
- * @example
- * ```typescript
- * const result = await auth.signIn.email(credentials)
- * if (isAuthFailure(result)) {
- *   // TypeScript narrows to FailedAuthResult
- *   console.error(result.error) // ✅ Type-safe
- * }
- * ```
- */
-export declare function isAuthFailure<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(result: AuthResult<TUser, TSession>): result is FailedAuthResult<TUser, TSession>;
-/**
- * Type predicate to check if AuthResult indicates 2FA is required.
- *
- * @template TUser - User type
- * @template TSession - Session type
- * @param result - AuthResult to check
- * @returns True if 2FA is required
- *
- * @example
- * ```typescript
- * const result = await auth.signIn.email(credentials)
- * if (isTwoFactorRequired(result)) {
- *   // TypeScript narrows to TwoFactorAuthResult
- *   await auth.verify2FA({
- *     email: result.email, // ✅ Type-safe
- *     userId: result.userId, // ✅ Type-safe
- *     code: '123456'
- *   })
- * }
- * ```
- */
-export declare function isTwoFactorRequired<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(result: AuthResult<TUser, TSession>): result is TwoFactorAuthResult<TUser, TSession>;
-/**
- * TODO: Performance
- * - [ ] Consider using branded types for User.id to prevent ID mixing
- * - [ ] Add type-level optimizations for discriminated unions
- * - [ ] Implement compile-time validation for email format
- * - [ ] Add type-level session expiration checking
- *
- * TODO: Features
- * - [ ] Add conditional types for provider-specific result variants
- * - [ ] Implement type-safe error handling with exhaustiveness checking
- * - [ ] Create type-level validation for credentials strength
- * - [ ] Add generic constraints for custom User/Session extensions
- * - [ ] Implement type-safe middleware chain types
- *
- * TODO: Type Safety
- * - [ ] Add branded types for sensitive data (tokens, passwords)
- * - [ ] Create type guards for all public interfaces
- * - [ ] Add type-level validation for registration data
- * - [ ] Implement type-safe error codes with const assertions
- *
- * TODO: Testing
- * - [ ] Add type-level tests using ts-expect
- * - [ ] Test type inference in various scenarios
- * - [ ] Verify type narrowing with type predicates
- * - [ ] Test generic constraints and conditional types
- * - [ ] Add tests for discriminated union narrowing
- *
- * TODO: Documentation
- * - [ ] Add more JSDoc examples for generic types
- * - [ ] Document type-level patterns and best practices
- * - [ ] Create migration guide for custom User/Session types
- *
- * TODO: Limitations
- * - [ ] Type inference may be limited with very deep generic chains
- * - [ ] Branded types add minimal runtime overhead
- * - [ ] Deep readonly types may impact performance with large objects
- * - [ ] Discriminated unions require explicit type guards for narrowing
- */