@nauth-toolkit/core 0.1.0 → 0.1.5

package/src/utils/common-passwords.spec.ts

@@ -1,230 +0,0 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import { loadCommonPasswords, isCommonPassword, getCommonPasswordCount } from './common-passwords';
-
-/**
- * Common Passwords Utility Tests
- *
- * Covers:
- * - Loading password list from file
- * - Fallback when file not found
- * - Password checking (case-insensitive)
- * - Performance characteristics
- * - Caching behavior
- */
-describe('Common Passwords Utility', () => {
-  // ============================================================================
-  // Loading and Initialization
-  // ============================================================================
-
-  describe('loadCommonPasswords', () => {
-    it('should load passwords into a Set', () => {
-      const passwords = loadCommonPasswords();
-
-      expect(passwords).toBeInstanceOf(Set);
-      expect(passwords.size).toBeGreaterThan(0);
-    });
-
-    it('should return cached instance on subsequent calls', () => {
-      const passwords1 = loadCommonPasswords();
-      const passwords2 = loadCommonPasswords();
-
-      // Should return exact same instance (not a copy)
-      expect(passwords1).toBe(passwords2);
-    });
-
-    it('should contain known common passwords', () => {
-      const passwords = loadCommonPasswords();
-
-      // These should always be in the list (either from file or fallback)
-      expect(passwords.has('password')).toBe(true);
-      expect(passwords.has('123456')).toBe(true);
-      expect(passwords.has('qwerty')).toBe(true);
-    });
-
-    it('should handle file loading gracefully', () => {
-      const filePath = path.join(__dirname, '../data/common-passwords-10000.txt');
-      const fileExists = fs.existsSync(filePath);
-
-      const passwords = loadCommonPasswords();
-
-      if (fileExists) {
-        // If file exists, should load 10K+ passwords
-        expect(passwords.size).toBeGreaterThanOrEqual(1000);
-      } else {
-        // If file missing, should use fallback list
-        expect(passwords.size).toBeGreaterThanOrEqual(10);
-      }
-    });
-  });
-
-  // ============================================================================
-  // Password Checking
-  // ============================================================================
-
-  describe('isCommonPassword', () => {
-    it('should identify common passwords', () => {
-      expect(isCommonPassword('password')).toBe(true);
-      expect(isCommonPassword('password123')).toBe(true);
-      expect(isCommonPassword('12345678')).toBe(true);
-      expect(isCommonPassword('qwerty')).toBe(true);
-    });
-
-    it('should be case-insensitive', () => {
-      expect(isCommonPassword('PASSWORD')).toBe(true);
-      expect(isCommonPassword('PaSsWoRd')).toBe(true);
-      expect(isCommonPassword('QWERTY')).toBe(true);
-    });
-
-    it('should reject strong passwords', () => {
-      // These strong passwords should NOT be in common password list
-      expect(isCommonPassword('Xy9$mK2#pLq8@vN3')).toBe(false);
-      expect(isCommonPassword('correct-horse-battery-staple-2024')).toBe(false);
-      expect(isCommonPassword('MyC0mpl3x!P@ssw0rd#2024')).toBe(false);
-    });
-
-    it('should handle empty string', () => {
-      expect(isCommonPassword('')).toBe(false);
-    });
-
-    it('should handle special characters', () => {
-      // Common passwords with numbers should be detected
-      expect(isCommonPassword('password1')).toBe(true);
-      expect(isCommonPassword('password123')).toBe(true);
-    });
-  });
-
-  // ============================================================================
-  // Performance and Count
-  // ============================================================================
-
-  describe('getCommonPasswordCount', () => {
-    it('should return positive number', () => {
-      const count = getCommonPasswordCount();
-
-      expect(count).toBeGreaterThan(0);
-      expect(typeof count).toBe('number');
-    });
-
-    it('should match loaded set size', () => {
-      const passwords = loadCommonPasswords();
-      const count = getCommonPasswordCount();
-
-      expect(count).toBe(passwords.size);
-    });
-
-    it('should have at least 10 passwords', () => {
-      // Even fallback list should have 10 passwords
-      const count = getCommonPasswordCount();
-
-      expect(count).toBeGreaterThanOrEqual(10);
-    });
-  });
-
-  // ============================================================================
-  // Performance Characteristics
-  // ============================================================================
-
-  describe('Performance', () => {
-    it('should check passwords in constant time (O(1) with Set)', () => {
-      const passwords = loadCommonPasswords();
-
-      // Measure lookup time for different passwords
-      const iterations = 100000; // Increased iterations for measurable time
-
-      const start1 = performance.now();
-      for (let i = 0; i < iterations; i++) {
-        passwords.has('password');
-      }
-      const time1 = performance.now() - start1;
-
-      const start2 = performance.now();
-      for (let i = 0; i < iterations; i++) {
-        passwords.has('very-secure-password-that-definitely-is-not-common-123456789');
-      }
-      const time2 = performance.now() - start2;
-
-      // Set lookup should be O(1), so both should complete in reasonable time
-      // Both lookups should take less than 2000ms for 100K iterations (lenient for CI/system load)
-      expect(time1).toBeLessThan(2000);
-      expect(time2).toBeLessThan(2000);
-
-      // Times should be similar (within 10x of each other for O(1) behavior)
-      // This is lenient to account for V8 optimization, system variance, and CI load
-      const ratio = Math.max(time1, time2) / Math.min(time1, time2);
-      expect(ratio).toBeLessThan(10);
-    });
-
-    it('should handle rapid consecutive checks', () => {
-      // Should not fail or slow down with many checks
-      const testPasswords = ['password', 'secure123', 'MySecureP@ssw0rd', 'qwerty', 'admin', 'Xy9$mK2#pLq8@vN3'];
-
-      for (let i = 0; i < 1000; i++) {
-        for (const pwd of testPasswords) {
-          isCommonPassword(pwd);
-        }
-      }
-
-      // If we get here without timeout, performance is acceptable
-      expect(true).toBe(true);
-    });
-  });
-
-  // ============================================================================
-  // Integration with Password Service
-  // ============================================================================
-
-  describe('Integration', () => {
-    it('should provide API that matches PasswordService expectations', () => {
-      // PasswordService calls loadCommonPasswords() once in constructor
-      const passwords = loadCommonPasswords();
-
-      // Then uses passwords.has(password.toLowerCase()) for checking
-      expect(typeof passwords.has).toBe('function');
-
-      const testPassword = 'password123';
-      const result = passwords.has(testPassword.toLowerCase());
-
-      expect(typeof result).toBe('boolean');
-      expect(result).toBe(true);
-    });
-
-    it('should handle all lowercase storage correctly', () => {
-      const passwords = loadCommonPasswords();
-
-      // List stores everything as lowercase
-      // So checking with original case should work via toLowerCase()
-      expect(passwords.has('password')).toBe(true);
-      expect(passwords.has('PASSWORD')).toBe(false); // Not in lowercase form
-      expect(passwords.has('password'.toLowerCase())).toBe(true); // Correct usage
-    });
-  });
-
-  // ============================================================================
-  // Environment Variable Control
-  // ============================================================================
-
-  describe('Debug Logging', () => {
-    const originalEnv = process.env.NAUTH_DEBUG;
-
-    afterEach(() => {
-      // Restore original environment
-      if (originalEnv !== undefined) {
-        process.env.NAUTH_DEBUG = originalEnv;
-      } else {
-        delete process.env.NAUTH_DEBUG;
-      }
-    });
-
-    it('should not throw errors regardless of NAUTH_DEBUG setting', () => {
-      process.env.NAUTH_DEBUG = 'true';
-      expect(() => loadCommonPasswords()).not.toThrow();
-
-      process.env.NAUTH_DEBUG = 'false';
-      expect(() => loadCommonPasswords()).not.toThrow();
-
-      delete process.env.NAUTH_DEBUG;
-      expect(() => loadCommonPasswords()).not.toThrow();
-    });
-  });
-});

package/src/utils/common-passwords.ts

@@ -1,170 +0,0 @@
-import * as fs from 'fs';
-import * as path from 'path';
-
-/**
- * Common Passwords Loader
- *
- * Loads a curated list of common passwords from bundled file at startup.
- * Platform-agnostic - works on Mac, Linux, Windows, Docker, serverless, etc.
- *
- * Security Features:
- * - One-time load on module initialization (memory cached)
- * - 10,000 most common passwords from SecLists
- * - O(1) lookup performance with Set
- * - Graceful fallback if file not found
- * - No runtime file I/O or network calls
- * - Silent by default (won't interfere with JSON logging)
- *
- * Memory footprint: ~200KB for 10K passwords in Set
- *
- * Environment Variables:
- * - NAUTH_DEBUG=true - Enable debug logging to stderr
- *
- * @example
- * ```typescript
- * const passwords = loadCommonPasswords();
- * if (passwords.has('password123')) {
- *   throw new Error('Password too common');
- * }
- * ```
- */
-
-let COMMON_PASSWORDS: Set<string> | null = null;
-
-/**
- * Internal logging helper
- *
- * Writes to stderr (not stdout) to avoid interfering with JSON logging.
- * Only logs if NAUTH_DEBUG environment variable is set.
- *
- * @param message - Message to log
- * @param isError - Whether this is an error/warning
- */
-function debugLog(message: string, isError: boolean = false): void {
-  if (process.env.NAUTH_DEBUG === 'true') {
-    const prefix = isError ? '[nauth-toolkit:WARN]' : '[nauth-toolkit:INFO]';
-    process.stderr.write(`${prefix} ${message}\n`);
-  }
-}
-
-/**
- * Minimal fallback password list
- *
- * Used if the main password file cannot be loaded.
- * Contains only the most common passwords.
- */
-const FALLBACK_PASSWORDS = [
-  'password',
-  'password123',
-  '123456',
-  '123456789',
-  '12345678',
-  '12345',
-  'qwerty',
-  'abc123',
-  'password1',
-  'admin',
-  'letmein',
-  'welcome',
-  '123123',
-  'monkey',
-  '1234567',
-  'password!',
-  'qwerty123',
-  '1q2w3e4r',
-  'admin123',
-  'root',
-];
-
-/**
- * Load common passwords from bundled file
- *
- * This function loads once on first call and caches the result.
- * Subsequent calls return the cached Set immediately.
- *
- * File location: packages/core/src/data/common-passwords-10000.txt
- * Format: One password per line, lowercase
- *
- * @returns Set of common passwords (lowercase)
- *
- * @example
- * ```typescript
- * // Load passwords (cached after first call)
- * const passwords = loadCommonPasswords();
- *
- * // Check if password is common
- * if (passwords.has('mypassword'.toLowerCase())) {
- *   console.log('Password is too common');
- * }
- * ```
- */
-export function loadCommonPasswords(): Set<string> {
-  // Return cached version if already loaded
-  if (COMMON_PASSWORDS) {
-    return COMMON_PASSWORDS;
-  }
-
-  try {
-    // Try to load from bundled file
-    const filePath = path.join(__dirname, '../data/common-passwords-10000.txt');
-
-    if (fs.existsSync(filePath)) {
-      const content = fs.readFileSync(filePath, 'utf-8');
-      COMMON_PASSWORDS = new Set(
-        content
-          .split('\n')
-          .map((p) => p.trim().toLowerCase())
-          .filter((p) => p.length > 0),
-      );
-
-      debugLog(`Loaded ${COMMON_PASSWORDS.size} common passwords from file`);
-      return COMMON_PASSWORDS;
-    } else {
-      debugLog(`Common passwords file not found at ${filePath}, using fallback list`, true);
-    }
-  } catch (error) {
-    debugLog('Could not load common passwords file, using fallback list', true);
-    if (error instanceof Error && process.env.NAUTH_DEBUG === 'true') {
-      debugLog(`Error details: ${error.message}`, true);
-    }
-  }
-
-  // Fallback to minimal list (silent by default)
-  COMMON_PASSWORDS = new Set(FALLBACK_PASSWORDS.map((p) => p.toLowerCase()));
-  debugLog(`Using fallback password list with ${COMMON_PASSWORDS.size} entries`, true);
-
-  return COMMON_PASSWORDS;
-}
-
-/**
- * Check if a password is in the common password list
- *
- * Case-insensitive comparison.
- *
- * @param password - Password to check
- * @returns True if password is common, false otherwise
- *
- * @example
- * ```typescript
- * if (isCommonPassword('Password123')) {
- *   throw new Error('Password is too common');
- * }
- * ```
- */
-export function isCommonPassword(password: string): boolean {
-  const passwords = loadCommonPasswords();
-  return passwords.has(password.toLowerCase());
-}
-
-/**
- * Get the size of the common password list
- *
- * @returns Number of passwords in the list
- */
-export function getCommonPasswordCount(): number {
-  const passwords = loadCommonPasswords();
-  return passwords.size;
-}
-
-// Load passwords on module import (cached for subsequent use)
-loadCommonPasswords();

package/src/utils/context-storage.ts

@@ -1,188 +0,0 @@
-import { AsyncLocalStorage } from 'async_hooks';
-
-/**
- * Context Storage - Platform-Agnostic Async Local Storage
- *
- * Provides request-scoped storage using Node.js AsyncLocalStorage.
- * Replaces nestjs-cls for platform-agnostic context management.
- *
- * **Features:**
- * - Request-scoped data storage
- * - Works across async boundaries
- * - No framework dependencies
- * - Type-safe storage and retrieval
- *
- * @example
- * ```typescript
- * // Store data in context
- * ContextStorage.run(() => {
- *   ContextStorage.set('userId', '123');
- *   ContextStorage.set('clientInfo', { ip: '1.2.3.4' });
- *
- *   // Access from any nested function
- *   const userId = ContextStorage.get<string>('userId');
- * });
- * ```
- */
-export class ContextStorage {
-  private static als = new AsyncLocalStorage<Map<string, unknown>>();
-
-  /**
-   * Run a callback within a new context
-   *
-   * Creates a new async local storage context for the callback.
-   * All ContextStorage operations within the callback will use this context.
-   *
-   * @param callback - Function to execute with context
-   * @returns Result of the callback
-   *
-   * @example
-   * ```typescript
-   * const result = ContextStorage.run(() => {
-   *   ContextStorage.set('key', 'value');
-   *   return processRequest();
-   * });
-   * ```
-   */
-  static run<T>(callback: () => T): T {
-    const store = new Map<string, unknown>();
-    return this.als.run(store, callback);
-  }
-
-  /**
-   * Store a value in the current context
-   *
-   * @param key - Storage key
-   * @param value - Value to store
-   * @throws Error if called outside of a context (ContextStorage.run not called)
-   *
-   * @example
-   * ```typescript
-   * ContextStorage.set('userId', '123');
-   * ContextStorage.set('clientInfo', { ip: '1.2.3.4', userAgent: 'Mozilla...' });
-   * ```
-   */
-  static set<T>(key: string, value: T): void {
-    const store = this.als.getStore();
-    if (!store) {
-      throw new Error('Context not initialized. Call ContextStorage.run() first.');
-    }
-    store.set(key, value);
-  }
-
-  /**
-   * Retrieve a value from the current context
-   *
-   * @param key - Storage key
-   * @returns Stored value or undefined if not found
-   *
-   * @example
-   * ```typescript
-   * const userId = ContextStorage.get<string>('userId');
-   * const clientInfo = ContextStorage.get<ClientInfo>('CLIENT_INFO');
-   * ```
-   */
-  static get<T>(key: string): T | undefined {
-    const store = this.als.getStore();
-    return store?.get(key) as T | undefined;
-  }
-
-  /**
-   * Check if a key exists in the current context
-   *
-   * @param key - Storage key
-   * @returns True if key exists, false otherwise
-   *
-   * @example
-   * ```typescript
-   * if (ContextStorage.has('userId')) {
-   *   const userId = ContextStorage.get<string>('userId');
-   * }
-   * ```
-   */
-  static has(key: string): boolean {
-    const store = this.als.getStore();
-    return store?.has(key) || false;
-  }
-
-  /**
-   * Delete a value from the current context
-   *
-   * @param key - Storage key
-   * @returns True if key was deleted, false if it didn't exist
-   *
-   * @example
-   * ```typescript
-   * ContextStorage.delete('temporaryData');
-   * ```
-   */
-  static delete(key: string): boolean {
-    const store = this.als.getStore();
-    if (!store) {
-      return false;
-    }
-    return store.delete(key);
-  }
-
-  /**
-   * Clear all values from the current context
-   *
-   * @example
-   * ```typescript
-   * ContextStorage.clear();
-   * ```
-   */
-  static clear(): void {
-    const store = this.als.getStore();
-    if (store) {
-      store.clear();
-    }
-  }
-
-  /**
-   * Get all keys in the current context
-   *
-   * @returns Array of storage keys
-   *
-   * @example
-   * ```typescript
-   * const keys = ContextStorage.keys();
-   * console.log('Stored keys:', keys);
-   * ```
-   */
-  static keys(): string[] {
-    const store = this.als.getStore();
-    if (!store) {
-      return [];
-    }
-    return Array.from(store.keys());
-  }
-
-  /**
-   * Get the current store instance
-   *
-   * This is useful for frameworks like Fastify where hooks run independently
-   * and you need to preserve the store across hook boundaries.
-   *
-   * @returns The current Map store or undefined
-   * @internal
-   */
-  static getStore(): Map<string, unknown> | undefined {
-    return this.als.getStore();
-  }
-
-  /**
-   * Enter an existing context store
-   *
-   * This allows re-entering a context that was created elsewhere,
-   * useful for frameworks where handlers run in separate scopes.
-   *
-   * @param store - The store to enter
-   * @param callback - Function to execute with the store
-   * @returns Result of the callback
-   * @internal
-   */
-  static enterStore<T>(store: Map<string, unknown>, callback: () => T): T {
-    return this.als.run(store, callback);
-  }
-}

package/src/utils/cookie-names.util.ts

@@ -1,67 +0,0 @@
-/**
- * Cookie Name Utilities
- *
- * Provides consistent cookie name generation using the configured prefix.
- * All cookie names are prefixed to avoid conflicts with other cookies.
- */
-
-import { NAuthConfig } from '../interfaces/config.interface';
-
-/**
- * Get the cookie name prefix from config
- * @param config - NAuth configuration
- * @returns Cookie name prefix (default: 'nauth_')
- */
-export function getCookieNamePrefix(config?: NAuthConfig): string {
-  return config?.tokenDelivery?.cookieNamePrefix || 'nauth_';
-}
-
-/**
- * Get the access token cookie name
- * @param config - NAuth configuration
- * @returns Access token cookie name (default: 'nauth_access_token')
- */
-export function getAccessTokenCookieName(config?: NAuthConfig): string {
-  const prefix = getCookieNamePrefix(config);
-  return `${prefix}access_token`;
-}
-
-/**
- * Get the refresh token cookie name
- * @param config - NAuth configuration
- * @returns Refresh token cookie name (default: 'nauth_refresh_token')
- */
-export function getRefreshTokenCookieName(config?: NAuthConfig): string {
-  const prefix = getCookieNamePrefix(config);
-  return `${prefix}refresh_token`;
-}
-
-/**
- * Get the device token cookie name
- * @param config - NAuth configuration
- * @returns Device token cookie name (default: 'nauth_device_token')
- */
-export function getDeviceTokenCookieName(config?: NAuthConfig): string {
-  const prefix = getCookieNamePrefix(config);
-  return `${prefix}device_token`;
-}
-
-/**
- * Get the CSRF token cookie name
- *
- * If explicitly configured via security.csrf.cookieName, uses that value.
- * Otherwise, uses the prefix: `${prefix}csrf_token`
- *
- * @param config - NAuth configuration
- * @returns CSRF token cookie name (default: 'nauth_csrf_token')
- */
-export function getCsrfTokenCookieName(config?: NAuthConfig): string {
-  // If explicitly configured, use it
-  if (config?.security?.csrf?.cookieName) {
-    return config.security.csrf.cookieName;
-  }
-
-  // Otherwise, use prefix
-  const prefix = getCookieNamePrefix(config);
-  return `${prefix}csrf_token`;
-}