@nauth-toolkit/core 0.1.0

package/src/utils/cookies.util.ts

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

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

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

@@ -0,0 +1,220 @@
+/**
+ * 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 {};
+}