@arcis/node 1.0.0 → 1.1.0

package/dist/middleware/index.d.mts

@@ -1,3 +1,3 @@
-export { 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 { f as arcis, g as arcisFunction, h as botProtection, i as createCors, j as createErrorHandler, k as createHeaders, l as createRateLimiter, m as createSecureCookies, n as createSlidingWindowLimiter, o as createTokenBucketLimiter, g as default, p as detectBot, q as enforceSecureCookie, r as errorHandler, s as rateLimit, t as safeCors, u as secureCookieDefaults, v as securityHeaders } from '../index-CCcPuTBo.mjs';
 import '../types-BOdL3ZWo.mjs';
 import 'express';

package/dist/middleware/index.d.ts

@@ -1,3 +1,3 @@
-export { 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 { f as arcis, g as arcisFunction, h as botProtection, i as createCors, j as createErrorHandler, k as createHeaders, l as createRateLimiter, m as createSecureCookies, n as createSlidingWindowLimiter, o as createTokenBucketLimiter, g as default, p as detectBot, q as enforceSecureCookie, r as errorHandler, s as rateLimit, t as safeCors, u as secureCookieDefaults, v as securityHeaders } from '../index-BvcFpoR3.js';
 import '../types-BOdL3ZWo.js';
 import 'express';

package/dist/middleware/index.js

@@ -1025,6 +1025,187 @@ arcisWithMethods.logger = createSafeLogger;
 arcisWithMethods.errorHandler = createErrorHandler;
 var main_default = arcisWithMethods;
 
+// src/utils/duration.ts
+var MAX_DURATION_MS = 4294967295;
+var DURATION_REGEX = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/i;
+var UNIT_TO_MS = {
+  ms: 1,
+  s: 1e3,
+  m: 6e4,
+  h: 36e5,
+  d: 864e5
+};
+function parseDuration(value) {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new Error(`Invalid duration: ${value}. Must be a non-negative finite number.`);
+    }
+    return Math.min(Math.floor(value), MAX_DURATION_MS);
+  }
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`Invalid duration: "${value}". Expected a duration string (e.g. "5m", "2h") or number.`);
+  }
+  const match = value.trim().match(DURATION_REGEX);
+  if (!match) {
+    throw new Error(
+      `Invalid duration: "${value}". Expected format: <number><unit> where unit is ms, s, m, h, or d.`
+    );
+  }
+  const amount = parseFloat(match[1]);
+  const unit = match[2].toLowerCase();
+  const ms = Math.floor(amount * UNIT_TO_MS[unit]);
+  if (ms < 0 || ms > MAX_DURATION_MS) {
+    throw new Error(`Duration "${value}" exceeds maximum allowed (${MAX_DURATION_MS}ms / ~49.7 days).`);
+  }
+  return ms;
+}
+
+// src/middleware/rate-limit-sliding.ts
+function createSlidingWindowLimiter(options = {}) {
+  const {
+    max = RATE_LIMIT.DEFAULT_MAX_REQUESTS,
+    window: windowOpt = RATE_LIMIT.DEFAULT_WINDOW_MS,
+    message = RATE_LIMIT.DEFAULT_MESSAGE,
+    statusCode = RATE_LIMIT.DEFAULT_STATUS_CODE,
+    keyGenerator = (req) => req.ip ?? req.socket?.remoteAddress ?? "unknown",
+    skip
+  } = options;
+  const windowMs = parseDuration(windowOpt);
+  const currentWindows = /* @__PURE__ */ Object.create(null);
+  const previousWindows = /* @__PURE__ */ Object.create(null);
+  const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    const cutoff = now - windowMs * 2;
+    for (const key of Object.keys(previousWindows)) {
+      if (previousWindows[key].startTime < cutoff) {
+        delete previousWindows[key];
+      }
+    }
+    for (const key of Object.keys(currentWindows)) {
+      if (currentWindows[key].startTime < cutoff) {
+        delete currentWindows[key];
+      }
+    }
+  }, windowMs);
+  if (typeof cleanupInterval.unref === "function") {
+    cleanupInterval.unref();
+  }
+  const handler = (req, res, next) => {
+    try {
+      if (skip?.(req)) return next();
+      const key = keyGenerator(req);
+      const now = Date.now();
+      const windowStart = Math.floor(now / windowMs) * windowMs;
+      if (!currentWindows[key] || currentWindows[key].startTime < windowStart) {
+        if (currentWindows[key]) {
+          previousWindows[key] = currentWindows[key];
+        }
+        currentWindows[key] = { count: 0, startTime: windowStart };
+      }
+      const elapsed = now - windowStart;
+      const weight = Math.max(0, (windowMs - elapsed) / windowMs);
+      const prevCount = previousWindows[key]?.count ?? 0;
+      const estimatedCount = prevCount * weight + currentWindows[key].count + 1;
+      const remaining = Math.max(0, Math.floor(max - estimatedCount));
+      const resetMs = windowStart + windowMs - now;
+      const resetSeconds = Math.max(1, Math.ceil(resetMs / 1e3));
+      res.setHeader("X-RateLimit-Limit", max.toString());
+      res.setHeader("X-RateLimit-Remaining", remaining.toString());
+      res.setHeader("X-RateLimit-Reset", resetSeconds.toString());
+      res.setHeader("X-RateLimit-Policy", `${max};w=${Math.floor(windowMs / 1e3)}`);
+      if (estimatedCount > max) {
+        res.setHeader("Retry-After", resetSeconds.toString());
+        res.status(statusCode).json({
+          error: message,
+          retryAfter: resetSeconds
+        });
+        return;
+      }
+      currentWindows[key].count++;
+      next();
+    } catch (error) {
+      console.error("[arcis] Sliding window rate limiter error:", error);
+      next();
+    }
+  };
+  const middleware = handler;
+  middleware.close = () => {
+    clearInterval(cleanupInterval);
+  };
+  return middleware;
+}
+
+// src/middleware/rate-limit-token.ts
+function createTokenBucketLimiter(options = {}) {
+  const {
+    capacity = 100,
+    refillRate = 10,
+    cost = 1,
+    message = RATE_LIMIT.DEFAULT_MESSAGE,
+    statusCode = RATE_LIMIT.DEFAULT_STATUS_CODE,
+    keyGenerator = (req) => req.ip ?? req.socket?.remoteAddress ?? "unknown",
+    skip
+  } = options;
+  if (capacity < 1) throw new RangeError(`Token bucket capacity must be >= 1, got ${capacity}`);
+  if (refillRate <= 0) throw new RangeError(`Token bucket refillRate must be > 0, got ${refillRate}`);
+  if (cost < 1) throw new RangeError(`Token bucket cost must be >= 1, got ${cost}`);
+  if (cost > capacity) throw new RangeError(`Token bucket cost (${cost}) must be <= capacity (${capacity}), otherwise all requests are permanently denied`);
+  const buckets = /* @__PURE__ */ Object.create(null);
+  const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    const staleThreshold = capacity / refillRate * 1e3 * 2;
+    for (const key of Object.keys(buckets)) {
+      if (now - buckets[key].lastRefill > staleThreshold) {
+        delete buckets[key];
+      }
+    }
+  }, 6e4);
+  if (typeof cleanupInterval.unref === "function") {
+    cleanupInterval.unref();
+  }
+  function refillBucket(bucket, now) {
+    const elapsed = (now - bucket.lastRefill) / 1e3;
+    const tokensToAdd = elapsed * refillRate;
+    bucket.tokens = Math.min(capacity, bucket.tokens + tokensToAdd);
+    bucket.lastRefill = now;
+  }
+  const handler = (req, res, next) => {
+    try {
+      if (skip?.(req)) return next();
+      const key = keyGenerator(req);
+      const now = Date.now();
+      if (!buckets[key]) {
+        buckets[key] = { tokens: capacity, lastRefill: now };
+      }
+      const bucket = buckets[key];
+      refillBucket(bucket, now);
+      const retryAfterSec = bucket.tokens < cost ? Math.ceil((cost - bucket.tokens) / refillRate) : 0;
+      res.setHeader("X-RateLimit-Limit", capacity.toString());
+      res.setHeader("X-RateLimit-Remaining", Math.floor(Math.max(0, bucket.tokens - cost)).toString());
+      res.setHeader("X-RateLimit-Policy", `${capacity};w=${Math.floor(capacity / refillRate)};burst=${capacity}`);
+      if (bucket.tokens < cost) {
+        res.setHeader("Retry-After", retryAfterSec.toString());
+        res.setHeader("X-RateLimit-Reset", retryAfterSec.toString());
+        res.status(statusCode).json({
+          error: message,
+          retryAfter: retryAfterSec
+        });
+        return;
+      }
+      bucket.tokens -= cost;
+      next();
+    } catch (error) {
+      console.error("[arcis] Token bucket rate limiter error:", error);
+      next();
+    }
+  };
+  const middleware = handler;
+  middleware.close = () => {
+    clearInterval(cleanupInterval);
+  };
+  return middleware;
+}
+
 // src/middleware/cors.ts
 var DEFAULT_METHODS = ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE"];
 var DEFAULT_HEADERS = ["Content-Type", "Authorization"];
@@ -1155,14 +1336,211 @@ function secureCookieDefaults(options = {}) {
 }
 var createSecureCookies = secureCookieDefaults;
 
+// src/middleware/bot-detection.ts
+var BOT_PATTERNS = [
+  // --- SEARCH ENGINES (specific variants before generic) ---
+  { pattern: /Googlebot-Image/i, name: "Googlebot-Image", category: "SEARCH_ENGINE" },
+  { pattern: /Googlebot-Video/i, name: "Googlebot-Video", category: "SEARCH_ENGINE" },
+  { pattern: /Googlebot-News/i, name: "Googlebot-News", category: "SEARCH_ENGINE" },
+  { pattern: /Googlebot/i, name: "Googlebot", category: "SEARCH_ENGINE" },
+  { pattern: /AdsBot-Google/i, name: "AdsBot-Google", category: "SEARCH_ENGINE" },
+  { pattern: /Mediapartners-Google/i, name: "Mediapartners-Google", category: "SEARCH_ENGINE" },
+  { pattern: /Bingbot/i, name: "Bingbot", category: "SEARCH_ENGINE" },
+  { pattern: /msnbot/i, name: "msnbot", category: "SEARCH_ENGINE" },
+  { pattern: /Slurp/i, name: "Yahoo Slurp", category: "SEARCH_ENGINE" },
+  { pattern: /DuckDuckBot/i, name: "DuckDuckBot", category: "SEARCH_ENGINE" },
+  { pattern: /Baiduspider/i, name: "Baiduspider", category: "SEARCH_ENGINE" },
+  { pattern: /YandexBot/i, name: "YandexBot", category: "SEARCH_ENGINE" },
+  { pattern: /YandexImages/i, name: "YandexImages", category: "SEARCH_ENGINE" },
+  { pattern: /Sogou/i, name: "Sogou", category: "SEARCH_ENGINE" },
+  { pattern: /Exabot/i, name: "Exabot", category: "SEARCH_ENGINE" },
+  { pattern: /ia_archiver/i, name: "Alexa", category: "SEARCH_ENGINE" },
+  { pattern: /Applebot/i, name: "Applebot", category: "SEARCH_ENGINE" },
+  { pattern: /Qwantify/i, name: "Qwantify", category: "SEARCH_ENGINE" },
+  { pattern: /PetalBot/i, name: "PetalBot", category: "SEARCH_ENGINE" },
+  { pattern: /SeznamBot/i, name: "SeznamBot", category: "SEARCH_ENGINE" },
+  // --- SOCIAL ---
+  { pattern: /Twitterbot/i, name: "Twitterbot", category: "SOCIAL" },
+  { pattern: /facebookexternalhit/i, name: "Facebook", category: "SOCIAL" },
+  { pattern: /Facebot/i, name: "Facebot", category: "SOCIAL" },
+  { pattern: /LinkedInBot/i, name: "LinkedInBot", category: "SOCIAL" },
+  { pattern: /Pinterest/i, name: "Pinterest", category: "SOCIAL" },
+  { pattern: /Slackbot/i, name: "Slackbot", category: "SOCIAL" },
+  { pattern: /TelegramBot/i, name: "TelegramBot", category: "SOCIAL" },
+  { pattern: /WhatsApp/i, name: "WhatsApp", category: "SOCIAL" },
+  { pattern: /Discordbot/i, name: "Discordbot", category: "SOCIAL" },
+  { pattern: /Redditbot/i, name: "Redditbot", category: "SOCIAL" },
+  { pattern: /Embedly/i, name: "Embedly", category: "SOCIAL" },
+  { pattern: /Quora Link Preview/i, name: "Quora", category: "SOCIAL" },
+  { pattern: /Mastodon/i, name: "Mastodon", category: "SOCIAL" },
+  // --- MONITORING ---
+  { pattern: /UptimeRobot/i, name: "UptimeRobot", category: "MONITORING" },
+  { pattern: /Pingdom/i, name: "Pingdom", category: "MONITORING" },
+  { pattern: /Site24x7/i, name: "Site24x7", category: "MONITORING" },
+  { pattern: /StatusCake/i, name: "StatusCake", category: "MONITORING" },
+  { pattern: /Datadog/i, name: "Datadog", category: "MONITORING" },
+  { pattern: /NewRelicPinger/i, name: "New Relic", category: "MONITORING" },
+  { pattern: /Better Uptime Bot/i, name: "Better Uptime", category: "MONITORING" },
+  { pattern: /GTmetrix/i, name: "GTmetrix", category: "MONITORING" },
+  { pattern: /PageSpeed/i, name: "PageSpeed Insights", category: "MONITORING" },
+  // --- AI CRAWLERS ---
+  { pattern: /GPTBot/i, name: "GPTBot", category: "AI_CRAWLER" },
+  { pattern: /ChatGPT-User/i, name: "ChatGPT-User", category: "AI_CRAWLER" },
+  { pattern: /Claude-Web/i, name: "Claude-Web", category: "AI_CRAWLER" },
+  { pattern: /ClaudeBot/i, name: "ClaudeBot", category: "AI_CRAWLER" },
+  { pattern: /anthropic-ai/i, name: "Anthropic", category: "AI_CRAWLER" },
+  { pattern: /Bytespider/i, name: "Bytespider", category: "AI_CRAWLER" },
+  { pattern: /CCBot/i, name: "CCBot", category: "AI_CRAWLER" },
+  { pattern: /cohere-ai/i, name: "Cohere", category: "AI_CRAWLER" },
+  { pattern: /PerplexityBot/i, name: "PerplexityBot", category: "AI_CRAWLER" },
+  { pattern: /YouBot/i, name: "YouBot", category: "AI_CRAWLER" },
+  { pattern: /Google-Extended/i, name: "Google-Extended", category: "AI_CRAWLER" },
+  { pattern: /Diffbot/i, name: "Diffbot", category: "AI_CRAWLER" },
+  { pattern: /Amazonbot/i, name: "Amazonbot", category: "AI_CRAWLER" },
+  { pattern: /meta-externalagent/i, name: "Meta AI", category: "AI_CRAWLER" },
+  // --- AUTOMATED TOOLS (headless browsers, testing frameworks) ---
+  { pattern: /HeadlessChrome/i, name: "Headless Chrome", category: "AUTOMATED" },
+  { pattern: /PhantomJS/i, name: "PhantomJS", category: "AUTOMATED" },
+  { pattern: /Selenium/i, name: "Selenium", category: "AUTOMATED" },
+  { pattern: /Puppeteer/i, name: "Puppeteer", category: "AUTOMATED" },
+  { pattern: /Playwright/i, name: "Playwright", category: "AUTOMATED" },
+  { pattern: /Cypress/i, name: "Cypress", category: "AUTOMATED" },
+  { pattern: /webdriver/i, name: "WebDriver", category: "AUTOMATED" },
+  { pattern: /MSIE 6\.0/i, name: "Fake IE6", category: "AUTOMATED" },
+  // --- SCRAPERS / CLI TOOLS ---
+  { pattern: /^curl\//i, name: "curl", category: "SCRAPER" },
+  { pattern: /^wget\//i, name: "wget", category: "SCRAPER" },
+  { pattern: /^python-requests\//i, name: "python-requests", category: "SCRAPER" },
+  { pattern: /^python-httpx\//i, name: "python-httpx", category: "SCRAPER" },
+  { pattern: /^Python-urllib/i, name: "Python-urllib", category: "SCRAPER" },
+  { pattern: /^aiohttp\//i, name: "aiohttp", category: "SCRAPER" },
+  { pattern: /^Go-http-client/i, name: "Go-http-client", category: "SCRAPER" },
+  { pattern: /^Java\//i, name: "Java HttpClient", category: "SCRAPER" },
+  { pattern: /^Apache-HttpClient/i, name: "Apache HttpClient", category: "SCRAPER" },
+  { pattern: /^okhttp\//i, name: "OkHttp", category: "SCRAPER" },
+  { pattern: /^node-fetch\//i, name: "node-fetch", category: "SCRAPER" },
+  { pattern: /^axios\//i, name: "axios", category: "SCRAPER" },
+  { pattern: /^got\//i, name: "got", category: "SCRAPER" },
+  { pattern: /^libwww-perl/i, name: "libwww-perl", category: "SCRAPER" },
+  { pattern: /^Ruby/i, name: "Ruby", category: "SCRAPER" },
+  { pattern: /^PHP\//i, name: "PHP", category: "SCRAPER" },
+  { pattern: /Scrapy/i, name: "Scrapy", category: "SCRAPER" },
+  { pattern: /^Postman/i, name: "Postman", category: "SCRAPER" },
+  { pattern: /^Insomnia/i, name: "Insomnia", category: "SCRAPER" },
+  { pattern: /^HTTPie\//i, name: "HTTPie", category: "SCRAPER" }
+];
+function detectBehavioralSignals(req) {
+  const signals = [];
+  const headers = req.headers;
+  if (!headers["user-agent"]) {
+    signals.push("missing_user_agent");
+  }
+  if (!headers["accept"]) {
+    signals.push("missing_accept");
+  }
+  if (!headers["accept-language"]) {
+    signals.push("missing_accept_language");
+  }
+  if (!headers["accept-encoding"]) {
+    signals.push("missing_accept_encoding");
+  }
+  if (headers["connection"] === "close") {
+    signals.push("connection_close");
+  }
+  return signals;
+}
+function detectBot(req) {
+  const rawUa = req.headers["user-agent"] ?? "";
+  const ua = rawUa.length > 2048 ? rawUa.slice(0, 2048) : rawUa;
+  const signals = detectBehavioralSignals(req);
+  if (!ua) {
+    return {
+      isBot: true,
+      category: "UNKNOWN",
+      name: null,
+      confidence: 0.8,
+      signals
+    };
+  }
+  for (const bot of BOT_PATTERNS) {
+    if (bot.pattern.test(ua)) {
+      return {
+        isBot: true,
+        category: bot.category,
+        name: bot.name,
+        confidence: 0.95,
+        signals
+      };
+    }
+  }
+  const behaviorScore = signals.length;
+  if (behaviorScore >= 3) {
+    return {
+      isBot: true,
+      category: "UNKNOWN",
+      name: null,
+      confidence: Math.min(1, 0.6 + behaviorScore * 0.1),
+      signals
+    };
+  }
+  return {
+    isBot: false,
+    category: "HUMAN",
+    name: null,
+    confidence: Math.max(0, 1 - behaviorScore * 0.15),
+    signals
+  };
+}
+function botProtection(options = {}) {
+  const {
+    allow = ["SEARCH_ENGINE", "SOCIAL", "MONITORING"],
+    deny = ["AUTOMATED"],
+    defaultAction = "allow",
+    statusCode = 403,
+    message = "Access denied.",
+    onDetected
+  } = options;
+  const allowSet = new Set(allow);
+  const denySet = new Set(deny);
+  return (req, res, next) => {
+    const result = detectBot(req);
+    req.botDetection = result;
+    if (!result.isBot) {
+      return next();
+    }
+    if (allowSet.has(result.category)) {
+      return next();
+    }
+    if (denySet.has(result.category)) {
+      if (onDetected) {
+        return onDetected(req, res, result);
+      }
+      res.status(statusCode).json({ error: message });
+      return;
+    }
+    if (defaultAction === "deny") {
+      if (onDetected) {
+        return onDetected(req, res, result);
+      }
+      res.status(statusCode).json({ error: message });
+      return;
+    }
+    next();
+  };
+}
+
 exports.arcis = arcis;
 exports.arcisFunction = arcisWithMethods;
+exports.botProtection = botProtection;
 exports.createCors = createCors;
 exports.createErrorHandler = createErrorHandler;
 exports.createHeaders = createHeaders;
 exports.createRateLimiter = createRateLimiter;
 exports.createSecureCookies = createSecureCookies;
+exports.createSlidingWindowLimiter = createSlidingWindowLimiter;
+exports.createTokenBucketLimiter = createTokenBucketLimiter;
 exports.default = main_default;
+exports.detectBot = detectBot;
 exports.enforceSecureCookie = enforceSecureCookie;
 exports.errorHandler = errorHandler;
 exports.rateLimit = rateLimit;