@arcis/node 1.0.0 → 1.2.0

package/dist/index-CgK94hY_.d.mts

@@ -0,0 +1,532 @@
+import { b as ArcisOptions, o as ArcisMiddlewareStack, A as ArcisFunction, e as RateLimitOptions, h as RateLimiterMiddleware, H as HeaderOptions, E as ErrorHandlerOptions } from './types-CsOFHoD9.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 };