@arcis/node 1.3.0 → 1.4.0

package/dist/index-DgJtWMSj.d.mts

@@ -1,532 +0,0 @@
-import { b as ArcisOptions, o as ArcisMiddlewareStack, A as ArcisFunction, e as RateLimitOptions, h as RateLimiterMiddleware, H as HeaderOptions, E as ErrorHandlerOptions } from './types-BOkx5YJc.mjs';
-import { RequestHandler, Request, Response, NextFunction } from 'express';
-
-/**
- * @module @arcis/node/middleware/main
- * Main arcis() middleware factory
- */
-
-/**
- * Create Arcis middleware with all protections enabled.
- *
- * @param options - Configuration options
- * @returns Array of Express middleware
- *
- * @example
- * // Full protection (recommended)
- * app.use(arcis());
- *
- * @example
- * // Custom configuration
- * app.use(arcis({
- *   rateLimit: { max: 50 },
- *   headers: { frameOptions: 'SAMEORIGIN' }
- * }));
- *
- * @example
- * // Disable specific features
- * app.use(arcis({
- *   rateLimit: false,
- *   sanitize: { sql: false }
- * }));
- *
- * @example
- * // Cleanup on shutdown
- * const middleware = arcis();
- * app.use(middleware);
- * process.on('SIGTERM', () => middleware.close());
- */
-declare function arcis(options?: ArcisOptions): ArcisMiddlewareStack;
-declare const arcisWithMethods: ArcisFunction;
-
-/**
- * @module @arcis/node/middleware/rate-limit
- * Rate limiting middleware
- */
-
-/**
- * Create Express middleware for rate limiting.
- *
- * @param options - Rate limit configuration
- * @returns Express middleware with cleanup method
- *
- * @example
- * app.use(createRateLimiter({ max: 100, windowMs: 60000 }));
- *
- * @example
- * // Skip rate limiting for certain routes
- * app.use(createRateLimiter({
- *   max: 50,
- *   skip: (req) => req.path === '/health'
- * }));
- *
- * @example
- * // Cleanup on shutdown
- * const limiter = createRateLimiter();
- * app.use(limiter);
- * process.on('SIGTERM', () => limiter.close());
- */
-declare function createRateLimiter(options?: RateLimitOptions): RateLimiterMiddleware;
-/**
- * Alias for createRateLimiter
- * @see createRateLimiter
- */
-declare const rateLimit: typeof createRateLimiter;
-
-/**
- * @module @arcis/node/middleware/rate-limit-sliding
- * Sliding window rate limiting middleware.
- *
- * More accurate than fixed window — uses a weighted sum of the previous
- * and current window to approximate a true sliding window.
- *
- * Algorithm:
- *   weight = (windowMs - elapsed) / windowMs
- *   count = (prevWindow * weight) + currentWindow
- *   allow = count < limit
- *
- * @example
- * app.use(createSlidingWindowLimiter({ max: 100, window: '15m' }));
- */
-
-interface SlidingWindowOptions {
-    /** Maximum requests per window. Default: 100 */
-    max?: number;
-    /** Window size in ms or duration string. Default: '1m' */
-    window?: string | number;
-    /** Error message when limit exceeded */
-    message?: string;
-    /** HTTP status code for rate limited responses. Default: 429 */
-    statusCode?: number;
-    /** Function to generate rate limit key from request */
-    keyGenerator?: (req: Request) => string;
-    /** Function to skip rate limiting for certain requests */
-    skip?: (req: Request) => boolean;
-}
-interface SlidingWindowMiddleware extends RequestHandler {
-    close: () => void;
-}
-/**
- * Create sliding window rate limiter middleware.
- *
- * @example
- * // 100 requests per 15 minutes
- * app.use(createSlidingWindowLimiter({ max: 100, window: '15m' }));
- *
- * @example
- * // Strict API limit
- * app.use('/api', createSlidingWindowLimiter({ max: 30, window: '1m' }));
- */
-declare function createSlidingWindowLimiter(options?: SlidingWindowOptions): SlidingWindowMiddleware;
-
-/**
- * @module @arcis/node/middleware/rate-limit-token
- * Token bucket rate limiting middleware.
- *
- * Allows burst traffic while enforcing an average rate.
- * Tokens refill at a steady rate. Each request costs 1 token.
- *
- * Algorithm:
- *   tokens = min(capacity, tokens + elapsed * refillRate)
- *   if tokens >= cost: allow, subtract cost
- *   else: deny
- *
- * @example
- * app.use(createTokenBucketLimiter({ capacity: 50, refillRate: 10 }));
- */
-
-interface TokenBucketOptions {
-    /** Maximum tokens (burst size). Default: 100 */
-    capacity?: number;
-    /** Tokens added per second. Default: 10 */
-    refillRate?: number;
-    /** Tokens consumed per request. Default: 1 */
-    cost?: number;
-    /** Error message when limit exceeded */
-    message?: string;
-    /** HTTP status code for rate limited responses. Default: 429 */
-    statusCode?: number;
-    /** Function to generate rate limit key from request */
-    keyGenerator?: (req: Request) => string;
-    /** Function to skip rate limiting for certain requests */
-    skip?: (req: Request) => boolean;
-}
-interface TokenBucketMiddleware extends RequestHandler {
-    close: () => void;
-}
-/**
- * Create token bucket rate limiter middleware.
- *
- * @example
- * // Allow bursts of 50, sustained rate of 10/sec
- * app.use(createTokenBucketLimiter({ capacity: 50, refillRate: 10 }));
- *
- * @example
- * // Strict API: 5 requests burst, 1/sec sustained
- * app.use('/api/expensive', createTokenBucketLimiter({
- *   capacity: 5,
- *   refillRate: 1,
- * }));
- */
-declare function createTokenBucketLimiter(options?: TokenBucketOptions): TokenBucketMiddleware;
-
-/**
- * @module @arcis/node/middleware/headers
- * Security headers middleware
- */
-
-/**
- * Create Express middleware for security headers.
- * Sets CSP, HSTS, X-Frame-Options, and other security headers.
- *
- * @param options - Header configuration
- * @returns Express middleware
- *
- * @example
- * app.use(createHeaders());
- *
- * @example
- * app.use(createHeaders({
- *   frameOptions: 'SAMEORIGIN',
- *   contentSecurityPolicy: "default-src 'self'"
- * }));
- */
-declare function createHeaders(options?: HeaderOptions): RequestHandler;
-/**
- * Alias for createHeaders
- * @see createHeaders
- */
-declare const securityHeaders: typeof createHeaders;
-
-/**
- * @module @arcis/node/middleware/error-handler
- * Production-safe error handler middleware
- */
-
-/**
- * Create Express error handler that hides sensitive details in production.
- *
- * Prevents information leakage by:
- * - Hiding stack traces in production
- * - Hiding error messages unless explicitly exposed
- * - Scrubbing database errors, connection strings, and internal IPs
- *
- * @param options - Error handler configuration (or boolean for isDev)
- * @returns Express error handling middleware
- *
- * @example
- * // Production mode (default) - hides error details
- * app.use(errorHandler());
- *
- * @example
- * // Development mode - shows error details and stack traces
- * app.use(errorHandler({ isDev: true }));
- *
- * @example
- * // With custom logger
- * app.use(errorHandler({
- *   isDev: false,
- *   logger: arcis.logger()
- * }));
- */
-declare function errorHandler(options?: ErrorHandlerOptions | boolean): (err: Error, req: Request, res: Response, next: NextFunction) => void;
-/**
- * Alias for errorHandler
- * @see errorHandler
- */
-declare const createErrorHandler: typeof errorHandler;
-
-/**
- * @module @arcis/node/middleware/cors
- * Safe CORS middleware with secure defaults
- */
-
-/** CORS configuration options */
-interface CorsOptions {
-    /**
-     * Allowed origins. Can be:
-     * - A string: exact match (e.g., 'https://example.com')
-     * - An array: whitelist of allowed origins
-     * - A RegExp: pattern match (use with care)
-     * - A function: custom validation `(origin) => boolean`
-     * - `true`: reflect the request origin (DANGEROUS — only for dev)
-     *
-     * Default: none (no origin allowed). You must explicitly set this.
-     */
-    origin: string | string[] | RegExp | ((origin: string) => boolean) | true;
-    /** Allowed HTTP methods. Default: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'] */
-    methods?: string[];
-    /** Allowed headers. Default: ['Content-Type', 'Authorization'] */
-    allowedHeaders?: string[];
-    /** Headers exposed to the browser. Default: [] */
-    exposedHeaders?: string[];
-    /** Allow credentials (cookies, authorization headers). Default: false */
-    credentials?: boolean;
-    /** Preflight cache duration in seconds. Default: 600 (10 minutes) */
-    maxAge?: number;
-    /** Respond to preflight with 204 (no content). Default: true */
-    preflightContinue?: boolean;
-}
-/**
- * Create safe CORS middleware.
- *
- * Unlike permissive CORS libraries, this enforces secure defaults:
- * - No wildcard `*` when credentials are enabled
- * - `null` origin is always blocked
- * - `Vary: Origin` is always set for proper caching
- * - You must explicitly configure allowed origins
- *
- * @param options - CORS configuration
- * @returns Express middleware
- *
- * @example
- * // Allow a single origin
- * app.use(safeCors({ origin: 'https://myapp.com' }));
- *
- * @example
- * // Allow multiple origins with credentials
- * app.use(safeCors({
- *   origin: ['https://myapp.com', 'https://admin.myapp.com'],
- *   credentials: true,
- * }));
- *
- * @example
- * // Development: allow all (NOT for production)
- * app.use(safeCors({ origin: true }));
- */
-declare function safeCors(options: CorsOptions): RequestHandler;
-/**
- * Alias for safeCors
- * @see safeCors
- */
-declare const createCors: typeof safeCors;
-
-/**
- * @module @arcis/node/middleware/cookies
- * Secure cookie defaults middleware
- */
-
-/** Cookie security configuration */
-interface SecureCookieOptions {
-    /** Force HttpOnly on all cookies. Default: true */
-    httpOnly?: boolean;
-    /** Force Secure flag (HTTPS only). Default: true in production, false in dev */
-    secure?: boolean;
-    /** SameSite attribute. Default: 'Lax' */
-    sameSite?: 'Strict' | 'Lax' | 'None' | false;
-    /** Override Path attribute. Default: undefined (keep original) */
-    path?: string;
-}
-/**
- * Enforce secure defaults on a Set-Cookie header value.
- */
-declare function enforceSecureCookie(cookieStr: string, options: Required<Omit<SecureCookieOptions, 'path'>> & {
-    path?: string;
-}): string;
-/**
- * Create middleware that enforces secure cookie defaults.
- *
- * Intercepts Set-Cookie headers and adds missing security attributes:
- * - HttpOnly: prevents JavaScript access (XSS cookie theft)
- * - Secure: cookies only sent over HTTPS
- * - SameSite: CSRF protection
- *
- * @param options - Cookie security configuration
- * @returns Express middleware
- *
- * @example
- * // Enforce defaults on all cookies
- * app.use(secureCookieDefaults());
- *
- * @example
- * // Strict SameSite for sensitive apps
- * app.use(secureCookieDefaults({ sameSite: 'Strict' }));
- */
-declare function secureCookieDefaults(options?: SecureCookieOptions): RequestHandler;
-/**
- * Alias for secureCookieDefaults
- * @see secureCookieDefaults
- */
-declare const createSecureCookies: typeof secureCookieDefaults;
-
-/**
- * @module @arcis/node/middleware/bot-detection
- * Local-only bot detection using User-Agent and behavioral signals.
- *
- * Categorizes requests into bot types and allows/denies based on config.
- * No cloud calls — everything runs locally.
- *
- * @example
- * // Block automated tools, allow search engines
- * app.use(botProtection({
- *   allow: ['SEARCH_ENGINE', 'SOCIAL', 'MONITORING'],
- *   deny: ['AUTOMATED', 'SCRAPER'],
- * }));
- */
-
-type BotCategory = 'SEARCH_ENGINE' | 'SOCIAL' | 'MONITORING' | 'AI_CRAWLER' | 'SCRAPER' | 'AUTOMATED' | 'UNKNOWN' | 'HUMAN';
-interface BotDetectionResult {
-    /** Whether the request appears to be from a bot */
-    isBot: boolean;
-    /** Bot category */
-    category: BotCategory;
-    /** Matched bot name (e.g. 'Googlebot', 'curl') or null */
-    name: string | null;
-    /** Confidence score: 0-1 */
-    confidence: number;
-    /** Behavioral signals detected */
-    signals: string[];
-}
-interface BotProtectionOptions {
-    /** Categories to explicitly allow. Default: ['SEARCH_ENGINE', 'SOCIAL', 'MONITORING'] */
-    allow?: BotCategory[];
-    /** Categories to explicitly deny. Default: ['AUTOMATED'] */
-    deny?: BotCategory[];
-    /** Action for categories not in allow or deny. Default: 'allow' */
-    defaultAction?: 'allow' | 'deny';
-    /** HTTP status code for denied bots. Default: 403 */
-    statusCode?: number;
-    /** Error message for denied bots */
-    message?: string;
-    /** Enable behavioral signal detection. Default: true */
-    detectBehavior?: boolean;
-    /** Custom handler called on detection (instead of default deny response) */
-    onDetected?: (req: Request, res: Response, result: BotDetectionResult) => void;
-}
-/**
- * Detect what kind of bot (if any) is making the request.
- *
- * @param req - HTTP request object
- * @returns Detection result with category, name, confidence, and signals
- *
- * @example
- * const result = detectBot(req);
- * if (result.isBot && result.category === 'AUTOMATED') {
- *   // Block automated tools
- * }
- */
-declare function detectBot(req: Request): BotDetectionResult;
-/**
- * Create Express middleware for bot protection.
- *
- * @example
- * // Block automated tools and scrapers
- * app.use(botProtection({
- *   allow: ['SEARCH_ENGINE', 'SOCIAL', 'MONITORING'],
- *   deny: ['AUTOMATED', 'SCRAPER'],
- * }));
- *
- * @example
- * // Block everything except search engines
- * app.use(botProtection({
- *   allow: ['SEARCH_ENGINE'],
- *   defaultAction: 'deny',
- * }));
- *
- * @example
- * // Custom handler
- * app.use(botProtection({
- *   deny: ['AUTOMATED'],
- *   onDetected: (req, res, result) => {
- *     console.log(`Bot blocked: ${result.name} (${result.category})`);
- *     res.status(403).json({ error: 'Bots not allowed' });
- *   },
- * }));
- */
-declare function botProtection(options?: BotProtectionOptions): RequestHandler;
-
-/**
- * @module @arcis/node/middleware/csrf
- * CSRF (Cross-Site Request Forgery) protection middleware
- *
- * Implements the double-submit cookie pattern:
- * 1. Server sets a CSRF token in a cookie
- * 2. Client must send the same token in a header or form field
- * 3. Middleware rejects requests where cookie token !== header/field token
- *
- * This works because an attacker's cross-origin form submission will include
- * the cookie automatically, but cannot read it (same-origin policy) to set
- * the matching header.
- */
-
-/** CSRF protection configuration */
-interface CsrfOptions {
-    /** Cookie name for the CSRF token. Default: '_csrf' */
-    cookieName?: string;
-    /** Header name to check for the token. Default: 'x-csrf-token' */
-    headerName?: string;
-    /** Form field name to check for the token. Default: '_csrf' */
-    fieldName?: string;
-    /** Token byte length (hex-encoded = 2x chars). Default: 32 */
-    tokenLength?: number;
-    /** HTTP methods to protect. Default: ['POST', 'PUT', 'PATCH', 'DELETE'] */
-    protectedMethods?: string[];
-    /** Paths to exclude from CSRF checks (e.g., webhook endpoints) */
-    excludePaths?: string[];
-    /** Cookie options */
-    cookie?: {
-        /** Cookie path. Default: '/' */
-        path?: string;
-        /** HttpOnly — set false so client JS can read it for headers. Default: false */
-        httpOnly?: boolean;
-        /** Secure flag (HTTPS only). Default: true in production */
-        secure?: boolean;
-        /** SameSite attribute. Default: 'Lax' */
-        sameSite?: 'Strict' | 'Lax' | 'None';
-        /** Cookie domain */
-        domain?: string;
-    };
-    /** Custom error handler when CSRF validation fails */
-    onError?: (req: Request, res: Response, next: NextFunction) => void;
-}
-/**
- * Generate a cryptographically random CSRF token.
- *
- * @param length - Byte length (output is hex, so 2x chars). Default: 32
- * @returns Hex-encoded random token
- *
- * @example
- * const token = generateCsrfToken(); // 64 hex chars
- */
-declare function generateCsrfToken(length?: number): string;
-/**
- * Validate that two CSRF tokens match using constant-time comparison.
- *
- * @param cookieToken - Token from the cookie
- * @param requestToken - Token from the header or form field
- * @returns true if tokens match
- */
-declare function validateCsrfToken(cookieToken: string, requestToken: string): boolean;
-/**
- * Create CSRF protection middleware using double-submit cookie pattern.
- *
- * For safe methods (GET, HEAD, OPTIONS), sets a CSRF token cookie if not present.
- * For unsafe methods (POST, PUT, PATCH, DELETE), validates the token.
- *
- * @param options - CSRF configuration
- * @returns Express middleware
- *
- * @example
- * // Basic usage
- * app.use(csrfProtection());
- *
- * @example
- * // Exclude webhook paths
- * app.use(csrfProtection({
- *   excludePaths: ['/api/webhooks/stripe', '/api/webhooks/github']
- * }));
- *
- * @example
- * // Client-side: read cookie + set header
- * const token = document.cookie.match(/_csrf=([^;]+)/)?.[1];
- * fetch('/api/data', {
- *   method: 'POST',
- *   headers: { 'X-CSRF-Token': token },
- *   credentials: 'same-origin'
- * });
- */
-declare function csrfProtection(options?: CsrfOptions): RequestHandler;
-/** Alias for csrfProtection */
-declare const createCsrf: typeof csrfProtection;
-
-export { validateCsrfToken as A, type BotCategory as B, type CorsOptions as C, type SecureCookieOptions as S, type TokenBucketMiddleware as T, type BotDetectionResult as a, type BotProtectionOptions as b, type CsrfOptions as c, type SlidingWindowMiddleware as d, type SlidingWindowOptions as e, type TokenBucketOptions as f, arcis as g, arcisWithMethods as h, botProtection as i, createCors as j, createCsrf as k, createErrorHandler as l, createHeaders as m, createRateLimiter as n, createSecureCookies as o, createSlidingWindowLimiter as p, createTokenBucketLimiter as q, csrfProtection as r, detectBot as s, enforceSecureCookie as t, errorHandler as u, generateCsrfToken as v, rateLimit as w, safeCors as x, secureCookieDefaults as y, securityHeaders as z };

package/dist/index.d.mts

@@ -1,175 +0,0 @@
-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-DgJtWMSj.mjs';
-export { P as PiiMatch, K as PiiRedactOptions, L as PiiScanOptions, M 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, m as encodeForAttribute, n as encodeForCss, o as encodeForHtml, p as encodeForJs, q as encodeForUrl, t as isDangerousNoSqlKey, u as isDangerousProtoKey, v as redactObjectPii, w as redactPii, x as sanitizeCommand, y as sanitizeHeaderValue, z as sanitizeHeaders, A as sanitizeJsonpCallback, B as sanitizeObject, C as sanitizePath, D as sanitizeSql, E as sanitizeSsti, F as sanitizeString, G as sanitizeXss, H as sanitizeXxe, I as scanObjectPii, J as scanPii } from './encode-CrQCGlBq.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-Cd02z-0j.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-BOkx5YJc.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/utils/duration
- * Parse human-readable duration strings into milliseconds.
- *
- * Supports: ms, s, m, h, d
- *
- * @example
- * parseDuration('5m')    // 300000
- * parseDuration('2h')    // 7200000
- * parseDuration(60000)   // 60000 (passthrough)
- * parseDuration('500ms') // 500
- */
-/**
- * Parse a duration string or number into milliseconds.
- *
- * @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
- *
- * @example
- * parseDuration('15m')   // 900000
- * parseDuration('1d')    // 86400000
- * parseDuration('500ms') // 500
- * parseDuration(60000)   // 60000
- */
-declare function parseDuration(value: string | number): number;
-/**
- * Format milliseconds into a human-readable duration string.
- *
- * @param ms - Duration in milliseconds
- * @returns Human-readable string (e.g. "5m", "2h 30m")
- */
-declare function formatDuration(ms: number): string;
-
-/**
- * @module @arcis/node/utils/ip
- * Platform-aware client IP detection.
- *
- * 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' });
- */
-
-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;
-}
-/**
- * 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.
- *
- * @param req - HTTP request object (Express, raw http, etc.)
- * @param options - Detection options
- * @returns Client IP address, or 'unknown' if unresolvable
- *
- * @example
- * // Auto-detect platform
- * app.use((req, res, next) => {
- *   const clientIp = detectClientIp(req);
- *   console.log('Client IP:', clientIp);
- *   next();
- * });
- *
- * @example
- * // Behind Cloudflare
- * const ip = detectClientIp(req, { platform: 'cloudflare' });
- *
- * @example
- * // Behind 2 proxies (e.g. CDN + load balancer)
- * const ip = detectClientIp(req, { trustedProxyCount: 2 });
- */
-declare function detectClientIp(req: RequestLike$1 | IncomingMessage, options?: DetectIpOptions): string;
-/**
- * Check if an IP address is a private/internal address.
- *
- * Detects: loopback, private ranges (RFC 1918), link-local, IPv6 equivalents.
- */
-declare function isPrivateIp(ip: string): boolean;
-
-/**
- * @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.
- *
- * @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 fingerprint(req: RequestLike, options?: FingerprintOptions): string;
-
-export { type DetectIpOptions, type FingerprintOptions, type Platform, detectClientIp, fingerprint, formatDuration, isPrivateIp, parseDuration };