mulguard 1.1.1 → 1.1.3

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

@@ -1,28 +1,132 @@
 /**
- * Security utilities
+ * Security utilities for Mulguard Authentication Library.
+ *
+ * Provides token generation, CSRF protection, input sanitization, and validation.
+ *
+ * @module @mulguard/core/security
  */
 /**
- * Generate random token
+ * 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;
 /**
- * Generate CSRF token
+ * 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;
 /**
- * Validate CSRF token (constant-time comparison)
+ * 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: string, expected: string): boolean;
+export declare function validateCSRFToken(token: unknown, expected: unknown): boolean;
 /**
- * Sanitize string input
+ * 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 sanitizeInput(input: string): string;
+export declare function isValidCSRFToken(token: unknown, expected: unknown): token is string;
 /**
- * Validate email format
+ * 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 isValidEmail(email: string): boolean;
+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/validation.d.ts

@@ -1,53 +1,251 @@
 /**
- * Input validation utilities
+ * Input validation and sanitization utilities with type safety.
+ *
+ * @module @mulguard/core/security/validation
  */
 /**
- * Validate and sanitize email
+ * Validation result type.
+ *
+ * @template T - Type of sanitized value
  */
-export declare function validateAndSanitizeEmail(email: string): {
-    valid: boolean;
-    sanitized?: string;
-    error?: string;
+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;
 };
 /**
- * Validate and sanitize password with enhanced security checks
+ * 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 validateAndSanitizePassword(password: string, minLength?: number): {
-    valid: boolean;
-    error?: string;
-    strength?: 'weak' | 'medium' | 'strong';
+export declare function isValidPassword(result: PasswordValidationResult): result is PasswordValidationResult & {
+    valid: true;
+    sanitized: string;
 };
 /**
- * Validate and sanitize name
+ * 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: string): {
-    valid: boolean;
-    sanitized?: string;
-    error?: string;
+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;
 };
 /**
- * Validate URL
+ * 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 validateURL(url: string): {
-    valid: boolean;
-    error?: string;
+export declare function isValidURL(result: URLValidationResult): result is URLValidationResult & {
+    valid: true;
+    sanitized: string;
 };
 /**
- * Validate token format with enhanced security checks
+ * 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 validateToken(token: string, minLength?: number): {
-    valid: boolean;
-    error?: string;
+export declare function isValidToken(result: TokenValidationResult): result is TokenValidationResult & {
+    valid: true;
+    sanitized: string;
 };
 /**
- * Validate and sanitize input with XSS prevention
+ * 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: string, options?: {
-    maxLength?: number;
-    allowHtml?: boolean;
-    required?: boolean;
-}): {
-    valid: boolean;
-    sanitized?: string;
-    error?: string;
+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
+ */