@arcis/node 1.0.0 → 1.1.0

package/README.md

@@ -1,11 +1,15 @@
 # Arcis
 
-arcis One-line security middleware for Node.js, Python, and Go.
+[![npm version](https://img.shields.io/npm/v/@arcis/node.svg)](https://www.npmjs.com/package/@arcis/node)
+[![PyPI version](https://img.shields.io/pypi/v/arcis.svg)](https://pypi.org/project/arcis/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/Gagancm/arcis/actions/workflows/ci.yml/badge.svg)](https://github.com/Gagancm/arcis/actions/workflows/ci.yml)
 
-Arcis protects your code like how Dependabot protects your dependencies.
+One-line security middleware for Node.js, Python, and Go.
 
+Arcis protects your code like how Dependabot protects your dependencies.
 
-**15 attack vectors handled so far.**
+**15 attack vectors handled. 1040+ tests. Zero dependencies.**
 
 | Category | What it stops |
 |----------|--------------|
@@ -25,8 +29,6 @@ Arcis protects your code like how Dependabot protects your dependencies.
 | Security Headers | CSP, HSTS, X-Frame-Options, 10 headers out of the box |
 | Input Validation | Type checking, ranges, enums, mass assignment prevention, safe logging |
 
-**1040+ tests** across Node.js (613) and Python (430).
-
 ## Install
 
 ```bash
@@ -35,19 +37,6 @@ pip install arcis                # Python
 go get github.com/GagancM/arcis  # Go
 ```
 
-**Install directly from GitHub:**
-
-```bash
-# Node.js
-npm install github:Gagancm/arcis#main --install-strategy=nested
-
-# Python
-pip install git+https://github.com/Gagancm/arcis.git#subdirectory=packages/arcis-python
-
-# Go
-go get github.com/Gagancm/arcis
-```
-
 ## Quick Start
 
 ### Node.js

package/dist/{index-BpT7flAQ.d.ts → index-BvcFpoR3.d.ts}

@@ -73,6 +73,103 @@ declare function createRateLimiter(options?: RateLimitOptions): RateLimiterMiddl
  */
 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
@@ -252,4 +349,90 @@ declare function secureCookieDefaults(options?: SecureCookieOptions): RequestHan
  */
 declare const createSecureCookies: typeof secureCookieDefaults;
 
-export { type CorsOptions as C, type SecureCookieOptions as S, arcis as a, arcisWithMethods as b, createCors as c, createErrorHandler as d, createHeaders as e, createRateLimiter as f, createSecureCookies as g, enforceSecureCookie as h, errorHandler as i, secureCookieDefaults as j, securityHeaders as k, rateLimit as r, safeCors as s };
+/**
+ * @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;
+
+export { 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 SlidingWindowMiddleware as c, type SlidingWindowOptions as d, type TokenBucketOptions as e, arcis as f, arcisWithMethods as g, botProtection as h, createCors as i, createErrorHandler as j, createHeaders as k, createRateLimiter as l, createSecureCookies as m, createSlidingWindowLimiter as n, createTokenBucketLimiter as o, detectBot as p, enforceSecureCookie as q, errorHandler as r, rateLimit as s, safeCors as t, secureCookieDefaults as u, securityHeaders as v };

package/dist/{index-JaFOUKyK.d.mts → index-CCcPuTBo.d.mts}

@@ -73,6 +73,103 @@ declare function createRateLimiter(options?: RateLimitOptions): RateLimiterMiddl
  */
 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
@@ -252,4 +349,90 @@ declare function secureCookieDefaults(options?: SecureCookieOptions): RequestHan
  */
 declare const createSecureCookies: typeof secureCookieDefaults;
 
-export { type CorsOptions as C, type SecureCookieOptions as S, arcis as a, arcisWithMethods as b, createCors as c, createErrorHandler as d, createHeaders as e, createRateLimiter as f, createSecureCookies as g, enforceSecureCookie as h, errorHandler as i, secureCookieDefaults as j, securityHeaders as k, rateLimit as r, safeCors as s };
+/**
+ * @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;
+
+export { 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 SlidingWindowMiddleware as c, type SlidingWindowOptions as d, type TokenBucketOptions as e, arcis as f, arcisWithMethods as g, botProtection as h, createCors as i, createErrorHandler as j, createHeaders as k, createRateLimiter as l, createSecureCookies as m, createSlidingWindowLimiter as n, createTokenBucketLimiter as o, detectBot as p, enforceSecureCookie as q, errorHandler as r, rateLimit as s, safeCors as t, secureCookieDefaults as u, securityHeaders as v };