@arcis/node 1.0.0 → 1.2.0

package/dist/index.d.mts

@@ -1,139 +1,175 @@
-export { C as CorsOptions, S as SecureCookieOptions, a as arcis, b as arcisFunction, c as createCors, d as createErrorHandler, e as createHeaders, f as createRateLimiter, g as createSecureCookies, b as default, h as enforceSecureCookie, i as errorHandler, r as rateLimit, s as safeCors, j as secureCookieDefaults, k as securityHeaders } from './index-JaFOUKyK.mjs';
-export { c as createSanitizer, d as detectCommandInjection, a as detectHeaderInjection, b as detectNoSqlInjection, e as detectPathTraversal, f as detectPrototypePollution, g as detectSql, h as detectXss, k as isDangerousNoSqlKey, l as isDangerousProtoKey, s as sanitizeCommand, m as sanitizeHeaderValue, n as sanitizeHeaders, o as sanitizeObject, p as sanitizePath, q as sanitizeSql, r as sanitizeString, t as sanitizeXss } from './headers-DBQedhrb.mjs';
-export { F as FileInput, V as ValidateFileOptions, a as ValidateFileResult, c as createValidator, i as isDangerousExtension, s as sanitizeFilename, v as validate, b as validateFile } from './index-nAgXexwD.mjs';
+export { B as BotCategory, a as BotDetectionResult, b as BotProtectionOptions, C as CorsOptions, c as CsrfOptions, S as SecureCookieOptions, d as SlidingWindowMiddleware, e as SlidingWindowOptions, T as TokenBucketMiddleware, f as TokenBucketOptions, g as arcis, h as arcisFunction, i as botProtection, j as createCors, k as createCsrf, l as createErrorHandler, m as createHeaders, n as createRateLimiter, o as createSecureCookies, p as createSlidingWindowLimiter, q as createTokenBucketLimiter, r as csrfProtection, h as default, s as detectBot, t as enforceSecureCookie, u as errorHandler, v as generateCsrfToken, w as rateLimit, x as safeCors, y as secureCookieDefaults, z as securityHeaders, A as validateCsrfToken } from './index-CgK94hY_.mjs';
+export { P as PiiMatch, F as PiiRedactOptions, G as PiiScanOptions, H as PiiType, c as createSanitizer, d as detectCommandInjection, a as detectHeaderInjection, b as detectJsonpInjection, e as detectNoSqlInjection, f as detectPathTraversal, g as detectPii, h as detectPrototypePollution, i as detectSql, j as detectSsti, k as detectXss, l as detectXxe, o as isDangerousNoSqlKey, p as isDangerousProtoKey, r as redactObjectPii, q as redactPii, s as sanitizeCommand, t as sanitizeHeaderValue, u as sanitizeHeaders, v as sanitizeJsonpCallback, w as sanitizeObject, x as sanitizePath, y as sanitizeSql, z as sanitizeSsti, A as sanitizeString, B as sanitizeXss, C as sanitizeXxe, D as scanObjectPii, E as scanPii } from './pii-CXcHMlnX.mjs';
+export { E as EmailValidationOptions, a as EmailValidationResult, F as FileInput, V as ValidateFileOptions, b as ValidateFileResult, c as ValidateRedirectOptions, d as ValidateRedirectResult, e as ValidateUrlOptions, f as ValidateUrlResult, g as createValidator, i as isDangerousExtension, h as isRedirectSafe, j as isUrlSafe, k as isValidEmailSyntax, s as sanitizeFilename, v as validate, l as validateEmail, m as validateFile, n as validateRedirect, o as validateUrl, p as verifyEmailMx } from './index-A-m-pPeW.mjs';
+import { IncomingMessage } from 'http';
 export { createRedactor, createSafeLogger, safeLog } from './logging/index.mjs';
 export { MemoryStore, RedisClientLike, RedisStore, RedisStoreOptions, createRedisStore } from './stores/index.mjs';
-export { A as ArcisFunction, a as ArcisMiddleware, b as ArcisOptions, E as ErrorHandlerOptions, F as FieldValidator, H as HeaderOptions, c as HstsOptions, d as HttpError, L as LogOptions, R as RateLimitEntry, e as RateLimitOptions, f as RateLimitResult, g as RateLimitStore, h as RateLimiterMiddleware, S as SafeLogger, i as SanitizeOptions, j as SanitizeResult, T as ThreatInfo, k as ThreatType, V as ValidationConfig, l as ValidationError, m as ValidationResult, n as ValidationSchema } from './types-BOdL3ZWo.mjs';
+export { A as ArcisFunction, a as ArcisMiddleware, b as ArcisOptions, E as ErrorHandlerOptions, F as FieldValidator, H as HeaderOptions, c as HstsOptions, d as HttpError, L as LogOptions, R as RateLimitEntry, e as RateLimitOptions, f as RateLimitResult, g as RateLimitStore, h as RateLimiterMiddleware, S as SafeLogger, i as SanitizeOptions, j as SanitizeResult, T as ThreatInfo, k as ThreatType, V as ValidationConfig, l as ValidationError, m as ValidationResult, n as ValidationSchema } from './types-CsOFHoD9.mjs';
 export { ArcisError, ArcisValidationError, BLOCKED, ERRORS, HEADERS, INPUT, InputTooLargeError, RATE_LIMIT, REDACTION, RateLimitError, SanitizationError, SecurityThreatError, VALIDATION } from './core/index.mjs';
 import 'express';
 
 /**
- * @module @arcis/node/validation/url
- * SSRF (Server-Side Request Forgery) prevention
+ * @module @arcis/node/utils/duration
+ * Parse human-readable duration strings into milliseconds.
  *
- * Validates URLs to ensure they don't target private/internal networks,
- * localhost, cloud metadata endpoints, or use dangerous protocols.
+ * Supports: ms, s, m, h, d
  *
  * @example
- * import { validateUrl } from '@arcis/node';
+ * parseDuration('5m')    // 300000
+ * parseDuration('2h')    // 7200000
+ * parseDuration(60000)   // 60000 (passthrough)
+ * parseDuration('500ms') // 500
+ */
+/**
+ * Parse a duration string or number into milliseconds.
  *
- * // Block SSRF attempts
- * validateUrl('http://169.254.169.254/latest/meta-data/')  // { safe: false, reason: 'link-local address' }
- * validateUrl('http://10.0.0.1/admin')                     // { safe: false, reason: 'private address (10.0.0.0/8)' }
- * validateUrl('http://localhost/secret')                    // { safe: false, reason: 'loopback address' }
- * validateUrl('file:///etc/passwd')                         // { safe: false, reason: 'disallowed protocol: file:' }
+ * @param value - Duration string (e.g. "5m", "2h", "30s") or number (ms)
+ * @returns Duration in milliseconds
+ * @throws {Error} If the value is not a valid duration
  *
- * // Allow safe URLs
- * validateUrl('https://api.example.com/data')               // { safe: true }
+ * @example
+ * parseDuration('15m')   // 900000
+ * parseDuration('1d')    // 86400000
+ * parseDuration('500ms') // 500
+ * parseDuration(60000)   // 60000
  */
-/** Options for URL validation */
-interface ValidateUrlOptions {
-    /** Allowed protocols. Default: ['http:', 'https:'] */
-    allowedProtocols?: string[];
-    /** Additional hostnames to block (e.g., internal service names) */
-    blockedHosts?: string[];
-    /** Additional hostnames to always allow (bypass IP checks) */
-    allowedHosts?: string[];
-    /** Allow localhost/loopback. Default: false */
-    allowLocalhost?: boolean;
-    /** Allow private/internal IPs. Default: false */
-    allowPrivate?: boolean;
-}
-/** Result of URL validation */
-interface ValidateUrlResult {
-    /** Whether the URL is safe to fetch */
-    safe: boolean;
-    /** Reason the URL was blocked (only set when safe=false) */
-    reason?: string;
-}
+declare function parseDuration(value: string | number): number;
 /**
- * Validate a URL for SSRF safety.
- *
- * Checks:
- * 1. Valid URL format
- * 2. Allowed protocol (default: http, https only)
- * 3. Not localhost/loopback (127.x.x.x, ::1, localhost)
- * 4. Not private IP (10.x, 172.16-31.x, 192.168.x)
- * 5. Not link-local (169.254.x.x — includes AWS/GCP/Azure metadata)
- * 6. Not blocked hostname
- * 7. No credentials in URL (user:pass@host)
- *
- * @param url - The URL string to validate
- * @param options - Validation options
- * @returns Validation result with safe flag and optional reason
+ * Format milliseconds into a human-readable duration string.
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Human-readable string (e.g. "5m", "2h 30m")
  */
-declare function validateUrl(url: string, options?: ValidateUrlOptions): ValidateUrlResult;
+declare function formatDuration(ms: number): string;
+
 /**
- * Convenience wrapper that returns true/false.
+ * @module @arcis/node/utils/ip
+ * Platform-aware client IP detection.
  *
- * @param url - The URL to check
- * @param options - Validation options
- * @returns true if the URL is safe to fetch
+ * Prevents IP spoofing by reading platform-specific headers
+ * instead of blindly trusting X-Forwarded-For.
+ *
+ * @example
+ * // Auto-detect platform from environment
+ * const ip = detectClientIp(req);
+ *
+ * // Explicit platform
+ * const ip = detectClientIp(req, { platform: 'cloudflare' });
  */
-declare function isUrlSafe(url: string, options?: ValidateUrlOptions): boolean;
 
+type Platform = 'auto' | 'cloudflare' | 'vercel' | 'flyio' | 'render' | 'firebase' | 'aws-alb' | 'generic';
+interface DetectIpOptions {
+    /** Platform to use for header selection. Default: 'auto' */
+    platform?: Platform;
+    /** Number of trusted proxies (for X-Forwarded-For parsing). Default: 1 */
+    trustedProxyCount?: number;
+}
+interface RequestLike$1 {
+    headers: Record<string, string | string[] | undefined>;
+    socket?: {
+        remoteAddress?: string;
+    };
+    connection?: {
+        remoteAddress?: string;
+    };
+    ip?: string;
+}
 /**
- * @module @arcis/node/validation/redirect
- * Open Redirect prevention
+ * Detect the real client IP address from a request.
+ *
+ * Uses platform-specific headers when available to prevent IP spoofing.
+ * Falls back to X-Forwarded-For (parsed from the right) and then
+ * the socket remote address.
  *
- * Prevents attackers from using your app to redirect users to malicious sites
- * via manipulated query parameters like ?returnUrl=http://evil.com
+ * @param req - HTTP request object (Express, raw http, etc.)
+ * @param options - Detection options
+ * @returns Client IP address, or 'unknown' if unresolvable
  *
  * @example
- * import { validateRedirect, isRedirectSafe } from '@arcis/node';
+ * // Auto-detect platform
+ * app.use((req, res, next) => {
+ *   const clientIp = detectClientIp(req);
+ *   console.log('Client IP:', clientIp);
+ *   next();
+ * });
  *
- * // Block open redirects
- * validateRedirect('http://evil.com')                    // { safe: false, reason: 'absolute URL not in allowed hosts' }
- * validateRedirect('//evil.com')                         // { safe: false, reason: 'protocol-relative URL not in allowed hosts' }
- * validateRedirect('javascript:alert(1)')                // { safe: false, reason: 'dangerous protocol: javascript:' }
+ * @example
+ * // Behind Cloudflare
+ * const ip = detectClientIp(req, { platform: 'cloudflare' });
  *
- * // Allow safe redirects
- * validateRedirect('/dashboard')                         // { safe: true }
- * validateRedirect('/users?page=2')                      // { safe: true }
- * validateRedirect('https://myapp.com/home', { allowedHosts: ['myapp.com'] })  // { safe: true }
+ * @example
+ * // Behind 2 proxies (e.g. CDN + load balancer)
+ * const ip = detectClientIp(req, { trustedProxyCount: 2 });
  */
-/** Options for redirect validation */
-interface ValidateRedirectOptions {
-    /** Hostnames that are allowed for absolute URL redirects */
-    allowedHosts?: string[];
-    /** Allow protocol-relative URLs (//example.com). Default: false */
-    allowProtocolRelative?: boolean;
-    /** Allowed protocols for absolute URLs. Default: ['http:', 'https:'] */
-    allowedProtocols?: string[];
-}
-/** Result of redirect validation */
-interface ValidateRedirectResult {
-    /** Whether the redirect URL is safe */
-    safe: boolean;
-    /** Reason the redirect was blocked (only set when safe=false) */
-    reason?: string;
-}
+declare function detectClientIp(req: RequestLike$1 | IncomingMessage, options?: DetectIpOptions): string;
 /**
- * Validate a redirect URL to prevent open redirect attacks.
- *
- * Safe redirects:
- * - Relative paths: /dashboard, /users?page=2, ../settings
- * - Absolute URLs to allowed hosts (when configured)
- *
- * Blocked redirects:
- * - Absolute URLs to unknown hosts
- * - Protocol-relative URLs (//evil.com)
- * - javascript:, data:, vbscript:, blob: protocols
- * - Backslash-prefixed paths (\\evil.com — browser treats as //)
- * - URLs with control characters that could disguise the target
- *
- * @param url - The redirect target URL to validate
- * @param options - Validation options
- * @returns Validation result with safe flag and optional reason
+ * Check if an IP address is a private/internal address.
+ *
+ * Detects: loopback, private ranges (RFC 1918), link-local, IPv6 equivalents.
  */
-declare function validateRedirect(url: string, options?: ValidateRedirectOptions): ValidateRedirectResult;
+declare function isPrivateIp(ip: string): boolean;
+
 /**
- * Convenience wrapper that returns true/false.
+ * @module @arcis/node/utils/fingerprint
+ * Deterministic request fingerprinting via SHA-256.
+ *
+ * Generates a stable hash from request characteristics for
+ * rate limiting keys, abuse detection, and analytics.
  *
- * @param url - The redirect URL to check
- * @param options - Validation options
- * @returns true if the redirect is safe
+ * @example
+ * const fp = await fingerprint(req);
+ * // "a3f2b8c1d4e5..."
+ */
+
+interface FingerprintOptions {
+    /** Include IP address in fingerprint. Default: true */
+    ip?: boolean;
+    /** Include User-Agent header. Default: true */
+    userAgent?: boolean;
+    /** Include Accept header. Default: true */
+    accept?: boolean;
+    /** Include Accept-Language header. Default: true */
+    acceptLanguage?: boolean;
+    /** Include Accept-Encoding header. Default: true */
+    acceptEncoding?: boolean;
+    /** Additional custom components to include */
+    custom?: string[];
+    /** IP detection options */
+    ipOptions?: DetectIpOptions;
+}
+interface RequestLike {
+    headers: Record<string, string | string[] | undefined>;
+    socket?: {
+        remoteAddress?: string;
+    };
+    connection?: {
+        remoteAddress?: string;
+    };
+    ip?: string;
+}
+/**
+ * Generate a deterministic fingerprint for a request.
+ *
+ * Creates a SHA-256 hash from configurable request components.
+ * The fingerprint is stable across requests from the same client
+ * (same IP, browser, language settings).
+ *
+ * @param req - HTTP request object
+ * @param options - Fingerprint configuration
+ * @returns Hex-encoded SHA-256 hash (64 characters)
+ *
+ * @example
+ * // Default fingerprint (IP + UA + Accept headers)
+ * const fp = fingerprint(req);
+ *
+ * @example
+ * // IP-only fingerprint (for simple rate limiting)
+ * const fp = fingerprint(req, { userAgent: false, accept: false, acceptLanguage: false, acceptEncoding: false });
+ *
+ * @example
+ * // With custom components
+ * const fp = fingerprint(req, { custom: [req.body?.userId] });
  */
-declare function isRedirectSafe(url: string, options?: ValidateRedirectOptions): boolean;
+declare function fingerprint(req: RequestLike, options?: FingerprintOptions): string;
 
-export { type ValidateRedirectOptions, type ValidateRedirectResult, type ValidateUrlOptions, type ValidateUrlResult, isRedirectSafe, isUrlSafe, validateRedirect, validateUrl };
+export { type DetectIpOptions, type FingerprintOptions, type Platform, detectClientIp, fingerprint, formatDuration, isPrivateIp, parseDuration };

package/dist/index.d.ts

@@ -1,139 +1,175 @@
-export { C as CorsOptions, S as SecureCookieOptions, a as arcis, b as arcisFunction, c as createCors, d as createErrorHandler, e as createHeaders, f as createRateLimiter, g as createSecureCookies, b as default, h as enforceSecureCookie, i as errorHandler, r as rateLimit, s as safeCors, j as secureCookieDefaults, k as securityHeaders } from './index-BpT7flAQ.js';
-export { c as createSanitizer, d as detectCommandInjection, a as detectHeaderInjection, b as detectNoSqlInjection, e as detectPathTraversal, f as detectPrototypePollution, g as detectSql, h as detectXss, k as isDangerousNoSqlKey, l as isDangerousProtoKey, s as sanitizeCommand, m as sanitizeHeaderValue, n as sanitizeHeaders, o as sanitizeObject, p as sanitizePath, q as sanitizeSql, r as sanitizeString, t as sanitizeXss } from './headers-BJq2OA0i.js';
-export { F as FileInput, V as ValidateFileOptions, a as ValidateFileResult, c as createValidator, i as isDangerousExtension, s as sanitizeFilename, v as validate, b as validateFile } from './index-BgHPM7LC.js';
+export { B as BotCategory, a as BotDetectionResult, b as BotProtectionOptions, C as CorsOptions, c as CsrfOptions, S as SecureCookieOptions, d as SlidingWindowMiddleware, e as SlidingWindowOptions, T as TokenBucketMiddleware, f as TokenBucketOptions, g as arcis, h as arcisFunction, i as botProtection, j as createCors, k as createCsrf, l as createErrorHandler, m as createHeaders, n as createRateLimiter, o as createSecureCookies, p as createSlidingWindowLimiter, q as createTokenBucketLimiter, r as csrfProtection, h as default, s as detectBot, t as enforceSecureCookie, u as errorHandler, v as generateCsrfToken, w as rateLimit, x as safeCors, y as secureCookieDefaults, z as securityHeaders, A as validateCsrfToken } from './index-D_bdJcF0.js';
+export { P as PiiMatch, F as PiiRedactOptions, G as PiiScanOptions, H as PiiType, c as createSanitizer, d as detectCommandInjection, a as detectHeaderInjection, b as detectJsonpInjection, e as detectNoSqlInjection, f as detectPathTraversal, g as detectPii, h as detectPrototypePollution, i as detectSql, j as detectSsti, k as detectXss, l as detectXxe, o as isDangerousNoSqlKey, p as isDangerousProtoKey, r as redactObjectPii, q as redactPii, s as sanitizeCommand, t as sanitizeHeaderValue, u as sanitizeHeaders, v as sanitizeJsonpCallback, w as sanitizeObject, x as sanitizePath, y as sanitizeSql, z as sanitizeSsti, A as sanitizeString, B as sanitizeXss, C as sanitizeXxe, D as scanObjectPii, E as scanPii } from './pii-DhNpl7M3.js';
+export { E as EmailValidationOptions, a as EmailValidationResult, F as FileInput, V as ValidateFileOptions, b as ValidateFileResult, c as ValidateRedirectOptions, d as ValidateRedirectResult, e as ValidateUrlOptions, f as ValidateUrlResult, g as createValidator, i as isDangerousExtension, h as isRedirectSafe, j as isUrlSafe, k as isValidEmailSyntax, s as sanitizeFilename, v as validate, l as validateEmail, m as validateFile, n as validateRedirect, o as validateUrl, p as verifyEmailMx } from './index-Co5kPRZz.js';
+import { IncomingMessage } from 'http';
 export { createRedactor, createSafeLogger, safeLog } from './logging/index.js';
 export { MemoryStore, RedisClientLike, RedisStore, RedisStoreOptions, createRedisStore } from './stores/index.js';
-export { A as ArcisFunction, a as ArcisMiddleware, b as ArcisOptions, E as ErrorHandlerOptions, F as FieldValidator, H as HeaderOptions, c as HstsOptions, d as HttpError, L as LogOptions, R as RateLimitEntry, e as RateLimitOptions, f as RateLimitResult, g as RateLimitStore, h as RateLimiterMiddleware, S as SafeLogger, i as SanitizeOptions, j as SanitizeResult, T as ThreatInfo, k as ThreatType, V as ValidationConfig, l as ValidationError, m as ValidationResult, n as ValidationSchema } from './types-BOdL3ZWo.js';
+export { A as ArcisFunction, a as ArcisMiddleware, b as ArcisOptions, E as ErrorHandlerOptions, F as FieldValidator, H as HeaderOptions, c as HstsOptions, d as HttpError, L as LogOptions, R as RateLimitEntry, e as RateLimitOptions, f as RateLimitResult, g as RateLimitStore, h as RateLimiterMiddleware, S as SafeLogger, i as SanitizeOptions, j as SanitizeResult, T as ThreatInfo, k as ThreatType, V as ValidationConfig, l as ValidationError, m as ValidationResult, n as ValidationSchema } from './types-CsOFHoD9.js';
 export { ArcisError, ArcisValidationError, BLOCKED, ERRORS, HEADERS, INPUT, InputTooLargeError, RATE_LIMIT, REDACTION, RateLimitError, SanitizationError, SecurityThreatError, VALIDATION } from './core/index.js';
 import 'express';
 
 /**
- * @module @arcis/node/validation/url
- * SSRF (Server-Side Request Forgery) prevention
+ * @module @arcis/node/utils/duration
+ * Parse human-readable duration strings into milliseconds.
  *
- * Validates URLs to ensure they don't target private/internal networks,
- * localhost, cloud metadata endpoints, or use dangerous protocols.
+ * Supports: ms, s, m, h, d
  *
  * @example
- * import { validateUrl } from '@arcis/node';
+ * parseDuration('5m')    // 300000
+ * parseDuration('2h')    // 7200000
+ * parseDuration(60000)   // 60000 (passthrough)
+ * parseDuration('500ms') // 500
+ */
+/**
+ * Parse a duration string or number into milliseconds.
  *
- * // Block SSRF attempts
- * validateUrl('http://169.254.169.254/latest/meta-data/')  // { safe: false, reason: 'link-local address' }
- * validateUrl('http://10.0.0.1/admin')                     // { safe: false, reason: 'private address (10.0.0.0/8)' }
- * validateUrl('http://localhost/secret')                    // { safe: false, reason: 'loopback address' }
- * validateUrl('file:///etc/passwd')                         // { safe: false, reason: 'disallowed protocol: file:' }
+ * @param value - Duration string (e.g. "5m", "2h", "30s") or number (ms)
+ * @returns Duration in milliseconds
+ * @throws {Error} If the value is not a valid duration
  *
- * // Allow safe URLs
- * validateUrl('https://api.example.com/data')               // { safe: true }
+ * @example
+ * parseDuration('15m')   // 900000
+ * parseDuration('1d')    // 86400000
+ * parseDuration('500ms') // 500
+ * parseDuration(60000)   // 60000
  */
-/** Options for URL validation */
-interface ValidateUrlOptions {
-    /** Allowed protocols. Default: ['http:', 'https:'] */
-    allowedProtocols?: string[];
-    /** Additional hostnames to block (e.g., internal service names) */
-    blockedHosts?: string[];
-    /** Additional hostnames to always allow (bypass IP checks) */
-    allowedHosts?: string[];
-    /** Allow localhost/loopback. Default: false */
-    allowLocalhost?: boolean;
-    /** Allow private/internal IPs. Default: false */
-    allowPrivate?: boolean;
-}
-/** Result of URL validation */
-interface ValidateUrlResult {
-    /** Whether the URL is safe to fetch */
-    safe: boolean;
-    /** Reason the URL was blocked (only set when safe=false) */
-    reason?: string;
-}
+declare function parseDuration(value: string | number): number;
 /**
- * Validate a URL for SSRF safety.
- *
- * Checks:
- * 1. Valid URL format
- * 2. Allowed protocol (default: http, https only)
- * 3. Not localhost/loopback (127.x.x.x, ::1, localhost)
- * 4. Not private IP (10.x, 172.16-31.x, 192.168.x)
- * 5. Not link-local (169.254.x.x — includes AWS/GCP/Azure metadata)
- * 6. Not blocked hostname
- * 7. No credentials in URL (user:pass@host)
- *
- * @param url - The URL string to validate
- * @param options - Validation options
- * @returns Validation result with safe flag and optional reason
+ * Format milliseconds into a human-readable duration string.
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Human-readable string (e.g. "5m", "2h 30m")
  */
-declare function validateUrl(url: string, options?: ValidateUrlOptions): ValidateUrlResult;
+declare function formatDuration(ms: number): string;
+
 /**
- * Convenience wrapper that returns true/false.
+ * @module @arcis/node/utils/ip
+ * Platform-aware client IP detection.
  *
- * @param url - The URL to check
- * @param options - Validation options
- * @returns true if the URL is safe to fetch
+ * Prevents IP spoofing by reading platform-specific headers
+ * instead of blindly trusting X-Forwarded-For.
+ *
+ * @example
+ * // Auto-detect platform from environment
+ * const ip = detectClientIp(req);
+ *
+ * // Explicit platform
+ * const ip = detectClientIp(req, { platform: 'cloudflare' });
  */
-declare function isUrlSafe(url: string, options?: ValidateUrlOptions): boolean;
 
+type Platform = 'auto' | 'cloudflare' | 'vercel' | 'flyio' | 'render' | 'firebase' | 'aws-alb' | 'generic';
+interface DetectIpOptions {
+    /** Platform to use for header selection. Default: 'auto' */
+    platform?: Platform;
+    /** Number of trusted proxies (for X-Forwarded-For parsing). Default: 1 */
+    trustedProxyCount?: number;
+}
+interface RequestLike$1 {
+    headers: Record<string, string | string[] | undefined>;
+    socket?: {
+        remoteAddress?: string;
+    };
+    connection?: {
+        remoteAddress?: string;
+    };
+    ip?: string;
+}
 /**
- * @module @arcis/node/validation/redirect
- * Open Redirect prevention
+ * Detect the real client IP address from a request.
+ *
+ * Uses platform-specific headers when available to prevent IP spoofing.
+ * Falls back to X-Forwarded-For (parsed from the right) and then
+ * the socket remote address.
  *
- * Prevents attackers from using your app to redirect users to malicious sites
- * via manipulated query parameters like ?returnUrl=http://evil.com
+ * @param req - HTTP request object (Express, raw http, etc.)
+ * @param options - Detection options
+ * @returns Client IP address, or 'unknown' if unresolvable
  *
  * @example
- * import { validateRedirect, isRedirectSafe } from '@arcis/node';
+ * // Auto-detect platform
+ * app.use((req, res, next) => {
+ *   const clientIp = detectClientIp(req);
+ *   console.log('Client IP:', clientIp);
+ *   next();
+ * });
  *
- * // Block open redirects
- * validateRedirect('http://evil.com')                    // { safe: false, reason: 'absolute URL not in allowed hosts' }
- * validateRedirect('//evil.com')                         // { safe: false, reason: 'protocol-relative URL not in allowed hosts' }
- * validateRedirect('javascript:alert(1)')                // { safe: false, reason: 'dangerous protocol: javascript:' }
+ * @example
+ * // Behind Cloudflare
+ * const ip = detectClientIp(req, { platform: 'cloudflare' });
  *
- * // Allow safe redirects
- * validateRedirect('/dashboard')                         // { safe: true }
- * validateRedirect('/users?page=2')                      // { safe: true }
- * validateRedirect('https://myapp.com/home', { allowedHosts: ['myapp.com'] })  // { safe: true }
+ * @example
+ * // Behind 2 proxies (e.g. CDN + load balancer)
+ * const ip = detectClientIp(req, { trustedProxyCount: 2 });
  */
-/** Options for redirect validation */
-interface ValidateRedirectOptions {
-    /** Hostnames that are allowed for absolute URL redirects */
-    allowedHosts?: string[];
-    /** Allow protocol-relative URLs (//example.com). Default: false */
-    allowProtocolRelative?: boolean;
-    /** Allowed protocols for absolute URLs. Default: ['http:', 'https:'] */
-    allowedProtocols?: string[];
-}
-/** Result of redirect validation */
-interface ValidateRedirectResult {
-    /** Whether the redirect URL is safe */
-    safe: boolean;
-    /** Reason the redirect was blocked (only set when safe=false) */
-    reason?: string;
-}
+declare function detectClientIp(req: RequestLike$1 | IncomingMessage, options?: DetectIpOptions): string;
 /**
- * Validate a redirect URL to prevent open redirect attacks.
- *
- * Safe redirects:
- * - Relative paths: /dashboard, /users?page=2, ../settings
- * - Absolute URLs to allowed hosts (when configured)
- *
- * Blocked redirects:
- * - Absolute URLs to unknown hosts
- * - Protocol-relative URLs (//evil.com)
- * - javascript:, data:, vbscript:, blob: protocols
- * - Backslash-prefixed paths (\\evil.com — browser treats as //)
- * - URLs with control characters that could disguise the target
- *
- * @param url - The redirect target URL to validate
- * @param options - Validation options
- * @returns Validation result with safe flag and optional reason
+ * Check if an IP address is a private/internal address.
+ *
+ * Detects: loopback, private ranges (RFC 1918), link-local, IPv6 equivalents.
  */
-declare function validateRedirect(url: string, options?: ValidateRedirectOptions): ValidateRedirectResult;
+declare function isPrivateIp(ip: string): boolean;
+
 /**
- * Convenience wrapper that returns true/false.
+ * @module @arcis/node/utils/fingerprint
+ * Deterministic request fingerprinting via SHA-256.
+ *
+ * Generates a stable hash from request characteristics for
+ * rate limiting keys, abuse detection, and analytics.
  *
- * @param url - The redirect URL to check
- * @param options - Validation options
- * @returns true if the redirect is safe
+ * @example
+ * const fp = await fingerprint(req);
+ * // "a3f2b8c1d4e5..."
+ */
+
+interface FingerprintOptions {
+    /** Include IP address in fingerprint. Default: true */
+    ip?: boolean;
+    /** Include User-Agent header. Default: true */
+    userAgent?: boolean;
+    /** Include Accept header. Default: true */
+    accept?: boolean;
+    /** Include Accept-Language header. Default: true */
+    acceptLanguage?: boolean;
+    /** Include Accept-Encoding header. Default: true */
+    acceptEncoding?: boolean;
+    /** Additional custom components to include */
+    custom?: string[];
+    /** IP detection options */
+    ipOptions?: DetectIpOptions;
+}
+interface RequestLike {
+    headers: Record<string, string | string[] | undefined>;
+    socket?: {
+        remoteAddress?: string;
+    };
+    connection?: {
+        remoteAddress?: string;
+    };
+    ip?: string;
+}
+/**
+ * Generate a deterministic fingerprint for a request.
+ *
+ * Creates a SHA-256 hash from configurable request components.
+ * The fingerprint is stable across requests from the same client
+ * (same IP, browser, language settings).
+ *
+ * @param req - HTTP request object
+ * @param options - Fingerprint configuration
+ * @returns Hex-encoded SHA-256 hash (64 characters)
+ *
+ * @example
+ * // Default fingerprint (IP + UA + Accept headers)
+ * const fp = fingerprint(req);
+ *
+ * @example
+ * // IP-only fingerprint (for simple rate limiting)
+ * const fp = fingerprint(req, { userAgent: false, accept: false, acceptLanguage: false, acceptEncoding: false });
+ *
+ * @example
+ * // With custom components
+ * const fp = fingerprint(req, { custom: [req.body?.userId] });
  */
-declare function isRedirectSafe(url: string, options?: ValidateRedirectOptions): boolean;
+declare function fingerprint(req: RequestLike, options?: FingerprintOptions): string;
 
-export { type ValidateRedirectOptions, type ValidateRedirectResult, type ValidateUrlOptions, type ValidateUrlResult, isRedirectSafe, isUrlSafe, validateRedirect, validateUrl };
+export { type DetectIpOptions, type FingerprintOptions, type Platform, detectClientIp, fingerprint, formatDuration, isPrivateIp, parseDuration };