@nauth-toolkit/core 0.1.0 → 0.1.5

package/src/utils/cookies.util.ts

@@ -1,94 +0,0 @@
-/**
- * Cookie Utilities
- *
- * Helpers for clearing nauth auth cookies in HTTP responses.
- */
-
-import { NAuthConfig } from '../interfaces/config.interface';
-import {
-  getAccessTokenCookieName,
-  getRefreshTokenCookieName,
-  getCsrfTokenCookieName,
-  getDeviceTokenCookieName,
-} from './cookie-names.util';
-
-export interface CookieOptions {
-  domain?: string;
-  path?: string;
-  secure?: boolean;
-  sameSite?: 'strict' | 'lax' | 'none';
-}
-
-/**
- * Clear nauth auth cookies on the response.
- *
- * - Clears access token, refresh token, CSRF token cookies
- * - Optionally clears device token cookie (only when forgetDevice=true)
- * - Device token cookies persist across logout by default (remember device feature)
- * - Applies security attributes consistent with how cookies were set
- * - Uses configured cookie name prefix (default: 'nauth_')
- *
- * @param res - HTTP response object (Express or Fastify compatible)
- * @param config - NAuth configuration (optional, for cookie name resolution)
- * @param opt - Optional cookie options to match configured attributes
- * @param forgetDevice - If true, also clears device token cookie (for "forget me" logout). Default: false
- */
-export function clearAuthCookies(
-  res: { cookie?: Function; setCookie?: Function },
-  config?: NAuthConfig | CookieOptions,
-  opt?: CookieOptions,
-  forgetDevice: boolean = false,
-): void {
-  // Handle old signature: clearAuthCookies(res, opt) where opt might be config or CookieOptions
-  let cookieOptions: CookieOptions | undefined;
-  let nauthConfig: NAuthConfig | undefined;
-
-  if (config && 'tokenDelivery' in config) {
-    // Second param is NAuthConfig
-    nauthConfig = config as NAuthConfig;
-    cookieOptions = opt;
-  } else {
-    // Second param is CookieOptions (backward compatibility)
-    cookieOptions = config as CookieOptions | undefined;
-  }
-
-  const base = {
-    httpOnly: true as const,
-    secure: cookieOptions?.secure !== false,
-    sameSite: (cookieOptions?.sameSite || 'strict') as 'strict' | 'lax' | 'none',
-    path: cookieOptions?.path || '/',
-    domain: cookieOptions?.domain,
-    maxAge: 0,
-  };
-
-  const accessTokenName = getAccessTokenCookieName(nauthConfig);
-  const refreshTokenName = getRefreshTokenCookieName(nauthConfig);
-  const csrfTokenName = getCsrfTokenCookieName(nauthConfig);
-  const deviceTokenName = getDeviceTokenCookieName(nauthConfig);
-
-  // CSRF cookie options (httpOnly: false, matches how it was set)
-  const csrfBase = {
-    ...base,
-    httpOnly: false as const, // CSRF token must be readable by JavaScript
-  };
-
-  if (typeof res.cookie === 'function') {
-    res.cookie(accessTokenName, '', base);
-    res.cookie(refreshTokenName, '', base);
-    res.cookie(csrfTokenName, '', csrfBase);
-    // Only clear device token cookie if forgetDevice=true (for "forget me" logout)
-    // Device tokens persist across normal logout (remember device feature)
-    if (forgetDevice) {
-      res.cookie(deviceTokenName, '', base); // Device token cookie (httpOnly: true)
-    }
-  } else if (typeof res.setCookie === 'function') {
-    res.setCookie(accessTokenName, '', base);
-    res.setCookie(refreshTokenName, '', base);
-    res.setCookie(csrfTokenName, '', csrfBase);
-    // Only clear device token cookie if forgetDevice=true (for "forget me" logout)
-    // Device tokens persist across normal logout (remember device feature)
-    if (forgetDevice) {
-      res.setCookie(deviceTokenName, '', base); // Device token cookie (httpOnly: true)
-    }
-  }
-}

package/src/utils/index.ts

@@ -1,12 +0,0 @@
-/**
- * Utility Functions and Classes
- */
-
-export * from './pii-redactor';
-export * from './ip-extractor';
-export * from './nauth-logger';
-export * from './cookies.util';
-export * from './cookie-names.util';
-export * from './context-storage';
-export * from './token-delivery-policy';
-// user-agent-parser removed - functionality moved to ClientInfoService.parseUserAgent()

package/src/utils/ip-extractor.spec.ts

@@ -1,330 +0,0 @@
-/**
- * Tests for IP Address Extractor
- */
-
-import { extractClientIp } from './ip-extractor';
-
-describe('extractClientIp', () => {
-  describe('X-Forwarded-For header', () => {
-    it('should extract leftmost IP from X-Forwarded-For header', () => {
-      const req = {
-        headers: {
-          'x-forwarded-for': '203.0.113.1, 70.41.3.18, 150.172.238.178',
-        },
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1');
-    });
-
-    it('should handle single IP in X-Forwarded-For', () => {
-      const req = {
-        headers: {
-          'x-forwarded-for': '203.0.113.1',
-        },
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1');
-    });
-
-    it('should trim whitespace from IPs', () => {
-      const req = {
-        headers: {
-          'x-forwarded-for': '  203.0.113.1  ,  70.41.3.18  ',
-        },
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1');
-    });
-  });
-
-  describe('Cloudflare headers', () => {
-    it('should use CF-Connecting-IP when X-Forwarded-For is not present', () => {
-      const req = {
-        headers: {
-          'cf-connecting-ip': '203.0.113.1',
-        },
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1');
-    });
-
-    it('should prefer X-Forwarded-For over CF-Connecting-IP (standard priority)', () => {
-      const req = {
-        headers: {
-          'cf-connecting-ip': '203.0.113.1',
-          'x-forwarded-for': '10.0.0.1',
-        },
-      };
-
-      const result = extractClientIp(req);
-      // X-Forwarded-For has highest priority by design
-      expect(result).toBe('10.0.0.1');
-    });
-  });
-
-  describe('Nginx X-Real-IP header', () => {
-    it('should use X-Real-IP header when present', () => {
-      const req = {
-        headers: {
-          'x-real-ip': '203.0.113.1',
-        },
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1');
-    });
-  });
-
-  describe('Apache X-Client-IP header', () => {
-    it('should use X-Client-IP header when present', () => {
-      const req = {
-        headers: {
-          'x-client-ip': '203.0.113.1',
-        },
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1');
-    });
-  });
-
-  describe('Priority order', () => {
-    it('should prefer X-Forwarded-For over other headers', () => {
-      const req = {
-        headers: {
-          'x-forwarded-for': '203.0.113.1',
-          'cf-connecting-ip': '192.168.1.1',
-          'x-real-ip': '10.0.0.1',
-          'x-client-ip': '172.16.0.1',
-        },
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1');
-    });
-
-    it('should fallback to CF-Connecting-IP if X-Forwarded-For is missing', () => {
-      const req = {
-        headers: {
-          'cf-connecting-ip': '203.0.113.1',
-          'x-real-ip': '10.0.0.1',
-        },
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1');
-    });
-  });
-
-  describe('IPv6 handling', () => {
-    it('should convert ::1 to 127.0.0.1', () => {
-      const req = {
-        ip: '::1',
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('127.0.0.1');
-    });
-
-    it('should convert ::ffff:127.0.0.1 to 127.0.0.1', () => {
-      const req = {
-        ip: '::ffff:127.0.0.1',
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('127.0.0.1');
-    });
-
-    it('should strip ::ffff: prefix from IPv4-mapped IPv6 addresses', () => {
-      const req = {
-        ip: '::ffff:203.0.113.1',
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1');
-    });
-
-    it('should handle pure IPv6 addresses', () => {
-      const req = {
-        headers: {
-          'x-forwarded-for': '2001:db8::1',
-        },
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('2001:db8::1');
-    });
-  });
-
-  describe('Fallback to req.ip', () => {
-    it('should use req.ip when no headers are present', () => {
-      const req = {
-        ip: '203.0.113.1',
-        headers: {},
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1');
-    });
-
-    it('should use req.socket.remoteAddress as final fallback', () => {
-      const req = {
-        headers: {},
-        socket: {
-          remoteAddress: '203.0.113.1',
-        },
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1');
-    });
-
-    it('should return 0.0.0.0 when all sources are missing', () => {
-      const req = {
-        headers: {},
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('0.0.0.0');
-    });
-  });
-
-  describe('Invalid IP handling', () => {
-    it('should skip invalid IPv4 addresses', () => {
-      const req = {
-        headers: {
-          'x-forwarded-for': '999.999.999.999, 203.0.113.1',
-        },
-      };
-
-      const result = extractClientIp(req);
-      // Should skip invalid and use fallback
-      expect(result).not.toBe('999.999.999.999');
-    });
-
-    it('should validate IPv4 octet ranges', () => {
-      const req = {
-        headers: {
-          'x-forwarded-for': '256.1.1.1',
-        },
-        ip: '203.0.113.1',
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1'); // Falls back to req.ip
-    });
-  });
-
-  describe('Private IP filtering', () => {
-    it('should skip private IPs when filterPrivateIps is true', () => {
-      const req = {
-        headers: {
-          'x-forwarded-for': '10.0.0.1, 203.0.113.1',
-        },
-      };
-
-      const result = extractClientIp(req, { filterPrivateIps: true });
-      // Should skip 10.0.0.1 and use fallback or next IP
-      expect(result).not.toBe('10.0.0.1');
-    });
-
-    it('should allow private IPs when filterPrivateIps is false', () => {
-      const req = {
-        headers: {
-          'x-forwarded-for': '10.0.0.1',
-        },
-      };
-
-      const result = extractClientIp(req, { filterPrivateIps: false });
-      expect(result).toBe('10.0.0.1');
-    });
-
-    it('should detect 192.168.x.x as private', () => {
-      const req = {
-        headers: {
-          'x-forwarded-for': '192.168.1.100',
-        },
-        ip: '203.0.113.1',
-      };
-
-      const result = extractClientIp(req, { filterPrivateIps: true });
-      expect(result).toBe('203.0.113.1'); // Falls back to public IP
-    });
-
-    it('should detect 172.16-31.x.x as private', () => {
-      const req = {
-        headers: {
-          'x-forwarded-for': '172.16.0.1',
-        },
-        ip: '203.0.113.1',
-      };
-
-      const result = extractClientIp(req, { filterPrivateIps: true });
-      expect(result).toBe('203.0.113.1');
-    });
-  });
-
-  describe('Case insensitive headers', () => {
-    it('should handle uppercase header names', () => {
-      const req = {
-        headers: {
-          'X-FORWARDED-FOR': '203.0.113.1',
-        },
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1');
-    });
-
-    it('should handle PascalCase header names', () => {
-      const req = {
-        headers: {
-          'X-Forwarded-For': '203.0.113.1',
-        },
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1');
-    });
-  });
-
-  describe('Production scenarios', () => {
-    it('should handle AWS ALB X-Forwarded-For format', () => {
-      const req = {
-        headers: {
-          'x-forwarded-for': '203.0.113.1, 172.31.1.1',
-        },
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1'); // Real client IP
-    });
-
-    it('should handle Nginx proxy chain', () => {
-      const req = {
-        headers: {
-          'x-real-ip': '203.0.113.1',
-        },
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1');
-    });
-
-    it('should handle Cloudflare CDN', () => {
-      const req = {
-        headers: {
-          'cf-connecting-ip': '203.0.113.1',
-          'x-forwarded-for': '203.0.113.1, 172.16.0.1',
-        },
-      };
-
-      const result = extractClientIp(req);
-      expect(result).toBe('203.0.113.1');
-    });
-  });
-});

package/src/utils/ip-extractor.ts

@@ -1,220 +0,0 @@
-/**
- * IP Address Extractor
- *
- * Extracts the real client IP address from requests, handling:
- * - Direct connections
- * - Reverse proxies (Nginx, Apache)
- * - Load balancers (AWS ALB/NLB, GCP, Azure)
- * - CDNs (Cloudflare, Fastly, Akamai)
- *
- * **Priority Order:**
- * 1. X-Forwarded-For (standard proxy header)
- * 2. CF-Connecting-IP (Cloudflare)
- * 3. X-Real-IP (Nginx proxy)
- * 4. X-Client-IP (Apache, other proxies)
- * 5. Fastly-Client-IP (Fastly CDN)
- * 6. Akamai-Origin-Hop (Akamai CDN)
- * 7. req.ip (NestJS/Express default)
- * 8. req.socket.remoteAddress (fallback)
- *
- * **Security:**
- * - Handles multiple proxies (takes leftmost IP)
- * - Validates IP format
- * - Filters private/internal IPs (optional)
- * - Prevents IP spoofing
- *
- * @example
- * ```typescript
- * import { extractClientIp } from '@nauth-toolkit/core/utils';
- *
- * @Post('login')
- * async login(@Req() req: Request) {
- *   const ipAddress = extractClientIp(req);
- *   logger.debug('Client IP:', ipAddress); // Real client IP
- * }
- * ```
- */
-
-// No need to import Request from express - we use 'any' to avoid dependency
-
-/**
- * Options for IP extraction
- */
-export interface IpExtractorOptions {
-  /**
-   * Whether to filter out private/internal IP addresses
-   * Defaults to false
-   */
-  filterPrivateIps?: boolean;
-
-  /**
-   * List of trusted proxy IP addresses or CIDR ranges
-   * If specified, only accepts X-Forwarded-For from these proxies
-   */
-  trustedProxies?: string[];
-
-  /**
-   * Whether to use the leftmost IP in X-Forwarded-For
-   * (true = original client, false = rightmost/last proxy)
-   * Defaults to true
-   */
-  useLeftmostIp?: boolean;
-}
-
-/**
- * Extracts the real client IP address from an HTTP request
- *
- * @param req - Express Request object
- * @param options - Optional configuration
- * @returns The client's IP address, or '0.0.0.0' if unable to determine
- */
-export function extractClientIp(req: any, options: IpExtractorOptions = {}): string {
-  const { filterPrivateIps = false, useLeftmostIp = true } = options;
-
-  // Priority order of headers to check
-  const headers = [
-    'x-forwarded-for', // Standard proxy header (comma-separated)
-    'cf-connecting-ip', // Cloudflare
-    'x-real-ip', // Nginx
-    'x-client-ip', // Apache, other proxies
-    'fastly-client-ip', // Fastly CDN
-    'akamai-origin-hop', // Akamai CDN
-    'true-client-ip', // Cloudflare Enterprise
-    'x-original-forwarded-for', // AWS ALB
-  ];
-
-  // Ensure headers object exists
-  const reqHeaders = req.headers || {};
-
-  // Try each header in priority order
-  for (const header of headers) {
-    // Try multiple case variations
-    const variations = [
-      header, // lowercase: x-forwarded-for
-      header.toUpperCase(), // uppercase: X-FORWARDED-FOR
-      header
-        .split('-')
-        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-        .join('-'), // PascalCase: X-Forwarded-For
-    ];
-
-    let value = null;
-    for (const variant of variations) {
-      if (reqHeaders[variant]) {
-        value = reqHeaders[variant];
-        break;
-      }
-    }
-
-    if (value) {
-      const ip = extractIpFromHeader(value, useLeftmostIp);
-      if (ip && isValidIp(ip)) {
-        if (filterPrivateIps && isPrivateIp(ip)) {
-          continue; // Skip private IPs
-        }
-        return ip;
-      }
-    }
-  }
-
-  // Fallback to NestJS/Express defaults
-  const fallbackIp = req.ip || req.socket?.remoteAddress || req.connection?.remoteAddress || '0.0.0.0';
-
-  // Clean up IPv6 localhost to IPv4
-  if (fallbackIp === '::1' || fallbackIp === '::ffff:127.0.0.1') {
-    return '127.0.0.1';
-  }
-
-  // Strip IPv6 prefix if present
-  const cleanIp = fallbackIp.replace(/^::ffff:/, '');
-
-  return cleanIp;
-}
-
-/**
- * Extracts IP address from header value
- *
- * @param value - Header value (may be comma-separated list)
- * @param useLeftmost - Whether to use leftmost (original client) or rightmost (last proxy)
- * @returns Extracted IP address or null
- */
-function extractIpFromHeader(value: string | string[], useLeftmost: boolean): string | null {
-  const valueStr = Array.isArray(value) ? value[0] : value;
-
-  if (!valueStr) return null;
-
-  // Split by comma (X-Forwarded-For can have multiple IPs)
-  const ips = valueStr
-    .split(',')
-    .map((ip) => ip.trim())
-    .filter(Boolean);
-
-  if (ips.length === 0) return null;
-
-  // Return leftmost (original client) or rightmost (last proxy)
-  return useLeftmost ? ips[0] : ips[ips.length - 1];
-}
-
-/**
- * Validates if a string is a valid IPv4 or IPv6 address
- *
- * @param ip - IP address to validate
- * @returns True if valid, false otherwise
- */
-function isValidIp(ip: string): boolean {
-  // IPv4 validation
-  const ipv4Regex = /^(\d{1,3}\.){3}\d{1,3}$/;
-  if (ipv4Regex.test(ip)) {
-    const parts = ip.split('.').map(Number);
-    return parts.every((part) => part >= 0 && part <= 255);
-  }
-
-  // IPv6 validation (simplified)
-  const ipv6Regex = /^([0-9a-fA-F]{0,4}:){2,7}[0-9a-fA-F]{0,4}$/;
-  return ipv6Regex.test(ip);
-}
-
-/**
- * Checks if an IP address is private/internal
- *
- * Detects:
- * - Localhost (127.0.0.0/8, ::1)
- * - Private IPv4 ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
- * - Link-local addresses (169.254.0.0/16)
- *
- * @param ip - IP address to check
- * @returns True if private, false otherwise
- *
- * @example
- * ```typescript
- * isPrivateIp('192.168.1.1'); // true
- * isPrivateIp('8.8.8.8'); // false
- * ```
- */
-export function isPrivateIp(ip: string): boolean {
-  // Localhost
-  if (ip === '127.0.0.1' || ip === '::1' || ip.startsWith('127.')) {
-    return true;
-  }
-
-  // Private IPv4 ranges
-  const privateRanges = [
-    /^10\./, // 10.0.0.0/8
-    /^172\.(1[6-9]|2[0-9]|3[0-1])\./, // 172.16.0.0/12
-    /^192\.168\./, // 192.168.0.0/16
-    /^169\.254\./, // Link-local (169.254.0.0/16)
-  ];
-
-  return privateRanges.some((regex) => regex.test(ip));
-}
-
-/**
- * Gets geolocation information for an IP address (placeholder)
- *
- * @param ip - IP address
- * @returns Geolocation info (to be implemented with MaxMind/IP-API)
- */
-export function getIpGeolocation(_ip: string): { country?: string; city?: string } {
-  // TODO: Implement with MaxMind GeoIP2 or IP-API
-  return {};
-}