@arcis/node 1.0.0 → 1.1.0

package/dist/index.mjs

@@ -1,3 +1,6 @@
+import { promises } from 'dns';
+import { createHash } from 'crypto';
+
 // src/core/constants.ts
 var INPUT = {
   /** Default maximum input size (1MB) */
@@ -1266,6 +1269,397 @@ function isDangerousExtension(filename) {
   return ext !== "" && DANGEROUS_EXTENSIONS.has(ext);
 }
 
+// src/validation/url.ts
+function validateUrl(url, options = {}) {
+  const {
+    allowedProtocols = ["http:", "https:"],
+    blockedHosts = [],
+    allowedHosts = [],
+    allowLocalhost = false,
+    allowPrivate = false
+  } = options;
+  if (typeof url !== "string" || url.trim() === "") {
+    return { safe: false, reason: "invalid URL: empty or not a string" };
+  }
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return { safe: false, reason: "invalid URL: failed to parse" };
+  }
+  if (!allowedProtocols.includes(parsed.protocol)) {
+    return { safe: false, reason: `disallowed protocol: ${parsed.protocol}` };
+  }
+  if (parsed.username || parsed.password) {
+    return { safe: false, reason: "URL contains credentials" };
+  }
+  const hostname = parsed.hostname.toLowerCase();
+  if (allowedHosts.some((h) => hostname === h.toLowerCase())) {
+    return { safe: true };
+  }
+  if (blockedHosts.some((h) => hostname === h.toLowerCase())) {
+    return { safe: false, reason: `blocked host: ${hostname}` };
+  }
+  if (!allowLocalhost) {
+    if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1" || hostname === "0.0.0.0" || hostname.endsWith(".localhost")) {
+      return { safe: false, reason: "loopback address" };
+    }
+    if (/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname)) {
+      return { safe: false, reason: "loopback address" };
+    }
+  }
+  if (!allowPrivate) {
+    const privateCheck = checkPrivateIp(hostname);
+    if (privateCheck) {
+      return { safe: false, reason: privateCheck };
+    }
+  }
+  return { safe: true };
+}
+function isUrlSafe(url, options = {}) {
+  return validateUrl(url, options).safe;
+}
+function checkPrivateIp(hostname) {
+  if (/^10\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname)) {
+    return "private address (10.0.0.0/8)";
+  }
+  const match172 = hostname.match(/^172\.(\d{1,3})\.\d{1,3}\.\d{1,3}$/);
+  if (match172) {
+    const second = parseInt(match172[1], 10);
+    if (second >= 16 && second <= 31) {
+      return "private address (172.16.0.0/12)";
+    }
+  }
+  if (/^192\.168\.\d{1,3}\.\d{1,3}$/.test(hostname)) {
+    return "private address (192.168.0.0/16)";
+  }
+  if (/^169\.254\.\d{1,3}\.\d{1,3}$/.test(hostname)) {
+    return "link-local address (169.254.0.0/16)";
+  }
+  if (/^0\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname)) {
+    return "current network address (0.0.0.0/8)";
+  }
+  if (hostname === "metadata.google.internal" || hostname === "metadata.internal") {
+    return "cloud metadata endpoint";
+  }
+  const ipv6 = hostname.replace(/^\[|\]$/g, "");
+  if (ipv6 === "::1" || ipv6 === "::" || ipv6.startsWith("fc") || ipv6.startsWith("fd") || ipv6.startsWith("fe80")) {
+    return "private IPv6 address";
+  }
+  return null;
+}
+
+// src/validation/redirect.ts
+var DANGEROUS_PROTOCOLS = /^(javascript|data|vbscript|blob):/i;
+var CONTROL_CHARS = /[\t\n\r]/g;
+function validateRedirect(url, options = {}) {
+  const {
+    allowedHosts = [],
+    allowProtocolRelative = false,
+    allowedProtocols = ["http:", "https:"]
+  } = options;
+  if (typeof url !== "string" || url.trim() === "") {
+    return { safe: false, reason: "invalid redirect: empty or not a string" };
+  }
+  const cleaned = url.replace(CONTROL_CHARS, "");
+  if (DANGEROUS_PROTOCOLS.test(cleaned)) {
+    const proto = cleaned.match(DANGEROUS_PROTOCOLS);
+    return { safe: false, reason: `dangerous protocol: ${proto[0]}` };
+  }
+  if (cleaned.startsWith("\\")) {
+    return { safe: false, reason: "backslash-prefixed URL (browser treats as protocol-relative)" };
+  }
+  if (cleaned.startsWith("//")) {
+    if (!allowProtocolRelative) {
+      const host2 = extractHost(cleaned);
+      if (host2 && allowedHosts.some((h) => host2 === h.toLowerCase())) {
+        return { safe: true };
+      }
+      return { safe: false, reason: "protocol-relative URL not in allowed hosts" };
+    }
+    const host = extractHost(cleaned);
+    if (host && allowedHosts.length > 0 && !allowedHosts.some((h) => host === h.toLowerCase())) {
+      return { safe: false, reason: "protocol-relative URL not in allowed hosts" };
+    }
+    return { safe: true };
+  }
+  let parsed;
+  try {
+    parsed = new URL(cleaned);
+  } catch {
+    return { safe: true };
+  }
+  if (!allowedProtocols.includes(parsed.protocol)) {
+    return { safe: false, reason: `disallowed protocol: ${parsed.protocol}` };
+  }
+  const hostname = parsed.hostname.toLowerCase();
+  if (allowedHosts.length === 0) {
+    return { safe: false, reason: "absolute URL not in allowed hosts" };
+  }
+  if (!allowedHosts.some((h) => hostname === h.toLowerCase())) {
+    return { safe: false, reason: `host not allowed: ${hostname}` };
+  }
+  return { safe: true };
+}
+function isRedirectSafe(url, options = {}) {
+  return validateRedirect(url, options).safe;
+}
+function extractHost(url) {
+  const match = url.match(/^\/\/([^/:?#]+)/);
+  return match ? match[1].toLowerCase() : null;
+}
+var MAX_EMAIL_LENGTH = 254;
+var MAX_LOCAL_LENGTH = 64;
+var MAX_DOMAIN_LENGTH = 255;
+var EMAIL_SYNTAX = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*\.[a-zA-Z]{2,}$/;
+var FREE_PROVIDERS = /* @__PURE__ */ new Set([
+  "gmail.com",
+  "yahoo.com",
+  "hotmail.com",
+  "outlook.com",
+  "aol.com",
+  "protonmail.com",
+  "proton.me",
+  "icloud.com",
+  "mail.com",
+  "zoho.com",
+  "yandex.com",
+  "gmx.com",
+  "gmx.net",
+  "live.com",
+  "msn.com",
+  "me.com",
+  "mac.com",
+  "fastmail.com",
+  "tutanota.com",
+  "hey.com"
+]);
+var DISPOSABLE_DOMAINS = /* @__PURE__ */ new Set([
+  // Popular disposable services
+  "guerrillamail.com",
+  "guerrillamail.net",
+  "guerrillamail.org",
+  "tempmail.com",
+  "temp-mail.org",
+  "temp-mail.io",
+  "throwaway.email",
+  "throwaway.com",
+  "mailinator.com",
+  "mailinator.net",
+  "yopmail.com",
+  "yopmail.fr",
+  "yopmail.net",
+  "sharklasers.com",
+  "grr.la",
+  "guerrillamail.info",
+  "guerrillamail.biz",
+  "guerrillamail.de",
+  "trashmail.com",
+  "trashmail.me",
+  "trashmail.net",
+  "dispostable.com",
+  "maildrop.cc",
+  "mailnesia.com",
+  "tempail.com",
+  "mohmal.com",
+  "getnada.com",
+  "emailondeck.com",
+  "discard.email",
+  "fakeinbox.com",
+  "mailcatch.com",
+  "mintemail.com",
+  "tempr.email",
+  "tempinbox.com",
+  "burnermail.io",
+  "mailsac.com",
+  "harakirimail.com",
+  "tempmailo.com",
+  "emailfake.com",
+  "crazymailing.com",
+  "armyspy.com",
+  "dayrep.com",
+  "einrot.com",
+  "fleckens.hu",
+  "gustr.com",
+  "jourrapide.com",
+  "rhyta.com",
+  "superrito.com",
+  "teleworm.us",
+  "10minutemail.com",
+  "10minutemail.net",
+  "minutemail.com",
+  "tempsky.com",
+  "spamgourmet.com",
+  "mytrashmail.com",
+  "mailexpire.com",
+  "safetymail.info",
+  "filzmail.com",
+  "trashymail.com",
+  "sharkmail.com",
+  "jetable.org",
+  "nospam.ze.tc",
+  "trash-me.com",
+  "dodgit.com",
+  "mailmoat.com",
+  "spamfree24.org",
+  "incognitomail.org",
+  "tempomail.fr",
+  "ephemail.net",
+  "hidemail.de",
+  "spaml.de",
+  "uggsrock.com",
+  "binkmail.com",
+  "suremail.info",
+  "bugmenot.com"
+]);
+var DOMAIN_TYPOS = {
+  "gmial.com": "gmail.com",
+  "gmaill.com": "gmail.com",
+  "gmai.com": "gmail.com",
+  "gamil.com": "gmail.com",
+  "gnail.com": "gmail.com",
+  "gmal.com": "gmail.com",
+  "gmil.com": "gmail.com",
+  "gmail.co": "gmail.com",
+  "gmail.cm": "gmail.com",
+  "gmail.om": "gmail.com",
+  "gmail.con": "gmail.com",
+  "gmail.cim": "gmail.com",
+  "gmail.comm": "gmail.com",
+  "yahooo.com": "yahoo.com",
+  "yaho.com": "yahoo.com",
+  "yahoo.co": "yahoo.com",
+  "yahoo.cm": "yahoo.com",
+  "yahoo.con": "yahoo.com",
+  "yahho.com": "yahoo.com",
+  "hotmial.com": "hotmail.com",
+  "hotmal.com": "hotmail.com",
+  "hotmai.com": "hotmail.com",
+  "hotmil.com": "hotmail.com",
+  "hotmail.co": "hotmail.com",
+  "hotmail.cm": "hotmail.com",
+  "hotmail.con": "hotmail.com",
+  "outlok.com": "outlook.com",
+  "outloo.com": "outlook.com",
+  "outlook.co": "outlook.com",
+  "outlook.cm": "outlook.com",
+  "protonmal.com": "protonmail.com",
+  "protonmail.co": "protonmail.com",
+  "icloud.co": "icloud.com",
+  "icloud.cm": "icloud.com",
+  "icoud.com": "icloud.com"
+};
+function invalidResult(reason, email) {
+  return {
+    valid: false,
+    reason,
+    suggestion: null,
+    isFree: false,
+    isDisposable: false,
+    normalized: email
+  };
+}
+function validateEmail(email, options = {}) {
+  const {
+    checkDisposable = true,
+    suggestTypoFix = true,
+    blockedDomains = [],
+    allowedDomains = []
+  } = options;
+  const normalized = email.trim().toLowerCase();
+  if (!normalized || normalized.length > MAX_EMAIL_LENGTH) {
+    return invalidResult("invalid_syntax", normalized);
+  }
+  const atIndex = normalized.lastIndexOf("@");
+  if (atIndex === -1) {
+    return invalidResult("invalid_syntax", normalized);
+  }
+  const localPart = normalized.slice(0, atIndex);
+  const domain = normalized.slice(atIndex + 1);
+  if (localPart.length === 0 || localPart.length > MAX_LOCAL_LENGTH) {
+    return invalidResult("invalid_syntax", normalized);
+  }
+  if (domain.length === 0 || domain.length > MAX_DOMAIN_LENGTH) {
+    return invalidResult("invalid_syntax", normalized);
+  }
+  if (localPart.includes("..")) {
+    return invalidResult("invalid_syntax", normalized);
+  }
+  if (localPart.startsWith(".") || localPart.endsWith(".")) {
+    return invalidResult("invalid_syntax", normalized);
+  }
+  if (!EMAIL_SYNTAX.test(normalized)) {
+    return invalidResult("invalid_syntax", normalized);
+  }
+  const allowedSet = new Set(allowedDomains.map((d) => d.toLowerCase()));
+  if (allowedSet.has(domain)) {
+    return {
+      valid: true,
+      reason: "valid",
+      suggestion: null,
+      isFree: FREE_PROVIDERS.has(domain),
+      isDisposable: false,
+      normalized
+    };
+  }
+  const blockedSet = new Set(blockedDomains.map((d) => d.toLowerCase()));
+  if (blockedSet.has(domain)) {
+    return invalidResult("blocked", normalized);
+  }
+  const isDisposable = DISPOSABLE_DOMAINS.has(domain);
+  if (checkDisposable && isDisposable) {
+    return {
+      valid: false,
+      reason: "disposable",
+      suggestion: null,
+      isFree: false,
+      isDisposable: true,
+      normalized
+    };
+  }
+  const isFree = FREE_PROVIDERS.has(domain);
+  if (suggestTypoFix && DOMAIN_TYPOS[domain]) {
+    const corrected = `${localPart}@${DOMAIN_TYPOS[domain]}`;
+    return {
+      valid: true,
+      reason: "typo",
+      suggestion: corrected,
+      isFree: FREE_PROVIDERS.has(DOMAIN_TYPOS[domain]),
+      isDisposable: false,
+      normalized
+    };
+  }
+  return {
+    valid: true,
+    reason: "valid",
+    suggestion: null,
+    isFree,
+    isDisposable,
+    normalized
+  };
+}
+async function verifyEmailMx(email) {
+  if (!isValidEmailSyntax(email)) return false;
+  const atIndex = email.lastIndexOf("@");
+  const domain = email.slice(atIndex + 1).trim().toLowerCase();
+  if (!domain) return false;
+  try {
+    const records = await promises.resolveMx(domain);
+    return records.length > 0;
+  } catch {
+    return false;
+  }
+}
+function isValidEmailSyntax(email) {
+  const normalized = email.trim().toLowerCase();
+  if (!normalized || normalized.length > MAX_EMAIL_LENGTH) return false;
+  const atIndex = normalized.lastIndexOf("@");
+  if (atIndex === -1) return false;
+  const localPart = normalized.slice(0, atIndex);
+  if (localPart.includes("..") || localPart.startsWith(".") || localPart.endsWith(".")) return false;
+  return EMAIL_SYNTAX.test(normalized);
+}
+
 // src/logging/redactor.ts
 function createSafeLogger(options = {}) {
   const {
@@ -1387,6 +1781,201 @@ 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;
+}
+function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return "0ms";
+  if (ms < 1e3) return `${ms}ms`;
+  const days = Math.floor(ms / 864e5);
+  const hours = Math.floor(ms % 864e5 / 36e5);
+  const minutes = Math.floor(ms % 36e5 / 6e4);
+  const seconds = Math.floor(ms % 6e4 / 1e3);
+  const parts = [];
+  if (days > 0) parts.push(`${days}d`);
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  if (seconds > 0) parts.push(`${seconds}s`);
+  return parts.join(" ") || "0ms";
+}
+
+// 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"];
@@ -1517,144 +2106,325 @@ function secureCookieDefaults(options = {}) {
 }
 var createSecureCookies = secureCookieDefaults;
 
-// src/validation/url.ts
-function validateUrl(url, options = {}) {
-  const {
-    allowedProtocols = ["http:", "https:"],
-    blockedHosts = [],
-    allowedHosts = [],
-    allowLocalhost = false,
-    allowPrivate = false
-  } = options;
-  if (typeof url !== "string" || url.trim() === "") {
-    return { safe: false, reason: "invalid URL: empty or not a string" };
+// 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");
   }
-  let parsed;
-  try {
-    parsed = new URL(url);
-  } catch {
-    return { safe: false, reason: "invalid URL: failed to parse" };
+  if (!headers["accept"]) {
+    signals.push("missing_accept");
   }
-  if (!allowedProtocols.includes(parsed.protocol)) {
-    return { safe: false, reason: `disallowed protocol: ${parsed.protocol}` };
+  if (!headers["accept-language"]) {
+    signals.push("missing_accept_language");
   }
-  if (parsed.username || parsed.password) {
-    return { safe: false, reason: "URL contains credentials" };
+  if (!headers["accept-encoding"]) {
+    signals.push("missing_accept_encoding");
   }
-  const hostname = parsed.hostname.toLowerCase();
-  if (allowedHosts.some((h) => hostname === h.toLowerCase())) {
-    return { safe: true };
+  if (headers["connection"] === "close") {
+    signals.push("connection_close");
   }
-  if (blockedHosts.some((h) => hostname === h.toLowerCase())) {
-    return { safe: false, reason: `blocked host: ${hostname}` };
+  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
+    };
   }
-  if (!allowLocalhost) {
-    if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1" || hostname === "0.0.0.0" || hostname.endsWith(".localhost")) {
-      return { safe: false, reason: "loopback address" };
-    }
-    if (/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname)) {
-      return { safe: false, reason: "loopback address" };
+  for (const bot of BOT_PATTERNS) {
+    if (bot.pattern.test(ua)) {
+      return {
+        isBot: true,
+        category: bot.category,
+        name: bot.name,
+        confidence: 0.95,
+        signals
+      };
     }
   }
-  if (!allowPrivate) {
-    const privateCheck = checkPrivateIp(hostname);
-    if (privateCheck) {
-      return { safe: false, reason: privateCheck };
-    }
+  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 { safe: true };
+  return {
+    isBot: false,
+    category: "HUMAN",
+    name: null,
+    confidence: Math.max(0, 1 - behaviorScore * 0.15),
+    signals
+  };
 }
-function isUrlSafe(url, options = {}) {
-  return validateUrl(url, options).safe;
+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();
+  };
 }
-function checkPrivateIp(hostname) {
-  if (/^10\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname)) {
-    return "private address (10.0.0.0/8)";
+
+// src/utils/ip.ts
+var PLATFORM_HEADERS = {
+  cloudflare: "cf-connecting-ip",
+  vercel: "x-real-ip",
+  flyio: "fly-client-ip",
+  render: "x-render-client-ip",
+  firebase: "x-appengine-user-ip",
+  "aws-alb": "x-forwarded-for"
+};
+function detectPlatform() {
+  const env = typeof process !== "undefined" ? process.env : {};
+  if (env.CF_PAGES || env.CF_WORKERS) return "cloudflare";
+  if (env.VERCEL) return "vercel";
+  if (env.FLY_APP_NAME) return "flyio";
+  if (env.RENDER) return "render";
+  if (env.FIREBASE_CONFIG || env.GCLOUD_PROJECT) return "firebase";
+  if (env.AWS_EXECUTION_ENV || env.AWS_LAMBDA_FUNCTION_NAME) return "aws-alb";
+  return "generic";
+}
+var _cachedPlatform = null;
+function getCachedPlatform() {
+  if (_cachedPlatform === null) {
+    _cachedPlatform = detectPlatform();
   }
-  const match172 = hostname.match(/^172\.(\d{1,3})\.\d{1,3}\.\d{1,3}$/);
-  if (match172) {
-    const second = parseInt(match172[1], 10);
-    if (second >= 16 && second <= 31) {
-      return "private address (172.16.0.0/12)";
+  return _cachedPlatform;
+}
+var MAX_IP_LENGTH = 45;
+function sanitizeIp(ip) {
+  const trimmed = ip.trim();
+  if (trimmed.length > MAX_IP_LENGTH) return trimmed.slice(0, MAX_IP_LENGTH);
+  return trimmed;
+}
+function getHeader(req, name) {
+  const val = req.headers[name];
+  if (Array.isArray(val)) return val[0];
+  return val;
+}
+function parseForwardedFor(header, trustedProxyCount) {
+  const ips = header.split(",").map((ip) => ip.trim()).filter(Boolean);
+  if (ips.length === 0) return void 0;
+  const clientIndex = Math.max(0, ips.length - trustedProxyCount);
+  return ips[clientIndex] || void 0;
+}
+function detectClientIp(req, options = {}) {
+  const { platform = "auto", trustedProxyCount = 1 } = options;
+  const r = req;
+  const resolvedPlatform = platform === "auto" ? getCachedPlatform() : platform;
+  if (resolvedPlatform !== "generic" && resolvedPlatform in PLATFORM_HEADERS) {
+    const headerName = PLATFORM_HEADERS[resolvedPlatform];
+    if (headerName) {
+      if (resolvedPlatform === "aws-alb") {
+        const xff2 = getHeader(r, "x-forwarded-for");
+        if (xff2) {
+          const ip = parseForwardedFor(xff2, trustedProxyCount);
+          if (ip) return sanitizeIp(ip);
+        }
+      } else {
+        const ip = getHeader(r, headerName);
+        if (ip) return sanitizeIp(ip);
+      }
     }
   }
-  if (/^192\.168\.\d{1,3}\.\d{1,3}$/.test(hostname)) {
-    return "private address (192.168.0.0/16)";
-  }
-  if (/^169\.254\.\d{1,3}\.\d{1,3}$/.test(hostname)) {
-    return "link-local address (169.254.0.0/16)";
-  }
-  if (/^0\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname)) {
-    return "current network address (0.0.0.0/8)";
+  if (r.ip) return sanitizeIp(r.ip);
+  const xff = getHeader(r, "x-forwarded-for");
+  if (xff) {
+    const ip = parseForwardedFor(xff, trustedProxyCount);
+    if (ip) return sanitizeIp(ip);
   }
-  if (hostname === "metadata.google.internal" || hostname === "metadata.internal") {
-    return "cloud metadata endpoint";
-  }
-  const ipv6 = hostname.replace(/^\[|\]$/g, "");
-  if (ipv6 === "::1" || ipv6 === "::" || ipv6.startsWith("fc") || ipv6.startsWith("fd") || ipv6.startsWith("fe80")) {
-    return "private IPv6 address";
-  }
-  return null;
+  const realIp = getHeader(r, "x-real-ip");
+  if (realIp) return sanitizeIp(realIp);
+  const socketIp = r.socket?.remoteAddress ?? r.connection?.remoteAddress;
+  if (socketIp) return sanitizeIp(socketIp);
+  return "unknown";
 }
-
-// src/validation/redirect.ts
-var DANGEROUS_PROTOCOLS = /^(javascript|data|vbscript|blob):/i;
-var CONTROL_CHARS = /[\t\n\r]/g;
-function validateRedirect(url, options = {}) {
+function isPrivateIp(ip) {
+  const normalized = ip.startsWith("::ffff:") ? ip.slice(7) : ip;
+  if (/^127\./.test(normalized)) return true;
+  if (/^10\./.test(normalized)) return true;
+  if (/^172\.(1[6-9]|2\d|3[01])\./.test(normalized)) return true;
+  if (/^192\.168\./.test(normalized)) return true;
+  if (/^169\.254\./.test(normalized)) return true;
+  if (/^0\./.test(normalized)) return true;
+  if (ip === "::1") return true;
+  if (/^fe80:/i.test(ip)) return true;
+  if (/^fc00:/i.test(ip)) return true;
+  if (/^fd/i.test(ip)) return true;
+  return false;
+}
+function getHeader2(req, name) {
+  const val = req.headers[name];
+  if (Array.isArray(val)) return val[0] ?? "";
+  return val ?? "";
+}
+function fingerprint(req, options = {}) {
   const {
-    allowedHosts = [],
-    allowProtocolRelative = false,
-    allowedProtocols = ["http:", "https:"]
+    ip = true,
+    userAgent = true,
+    accept = true,
+    acceptLanguage = true,
+    acceptEncoding = true,
+    custom = [],
+    ipOptions
   } = options;
-  if (typeof url !== "string" || url.trim() === "") {
-    return { safe: false, reason: "invalid redirect: empty or not a string" };
+  const components = [];
+  if (ip) {
+    components.push(`ip:${detectClientIp(req, ipOptions)}`);
   }
-  const cleaned = url.replace(CONTROL_CHARS, "");
-  if (DANGEROUS_PROTOCOLS.test(cleaned)) {
-    const proto = cleaned.match(DANGEROUS_PROTOCOLS);
-    return { safe: false, reason: `dangerous protocol: ${proto[0]}` };
-  }
-  if (cleaned.startsWith("\\")) {
-    return { safe: false, reason: "backslash-prefixed URL (browser treats as protocol-relative)" };
-  }
-  if (cleaned.startsWith("//")) {
-    if (!allowProtocolRelative) {
-      const host2 = extractHost(cleaned);
-      if (host2 && allowedHosts.some((h) => host2 === h.toLowerCase())) {
-        return { safe: true };
-      }
-      return { safe: false, reason: "protocol-relative URL not in allowed hosts" };
-    }
-    const host = extractHost(cleaned);
-    if (host && allowedHosts.length > 0 && !allowedHosts.some((h) => host === h.toLowerCase())) {
-      return { safe: false, reason: "protocol-relative URL not in allowed hosts" };
-    }
-    return { safe: true };
+  if (userAgent) {
+    components.push(`ua:${getHeader2(req, "user-agent")}`);
   }
-  let parsed;
-  try {
-    parsed = new URL(cleaned);
-  } catch {
-    return { safe: true };
+  if (accept) {
+    components.push(`accept:${getHeader2(req, "accept")}`);
   }
-  if (!allowedProtocols.includes(parsed.protocol)) {
-    return { safe: false, reason: `disallowed protocol: ${parsed.protocol}` };
+  if (acceptLanguage) {
+    components.push(`lang:${getHeader2(req, "accept-language")}`);
   }
-  const hostname = parsed.hostname.toLowerCase();
-  if (allowedHosts.length === 0) {
-    return { safe: false, reason: "absolute URL not in allowed hosts" };
+  if (acceptEncoding) {
+    components.push(`enc:${getHeader2(req, "accept-encoding")}`);
   }
-  if (!allowedHosts.some((h) => hostname === h.toLowerCase())) {
-    return { safe: false, reason: `host not allowed: ${hostname}` };
+  for (const c of custom) {
+    if (c != null) components.push(`custom:${c}`);
   }
-  return { safe: true };
-}
-function isRedirectSafe(url, options = {}) {
-  return validateRedirect(url, options).safe;
-}
-function extractHost(url) {
-  const match = url.match(/^\/\/([^/:?#]+)/);
-  return match ? match[1].toLowerCase() : null;
+  components.sort();
+  const hash = createHash("sha256");
+  hash.update(components.join("|"));
+  return hash.digest("hex");
 }
 
 // src/stores/memory.ts
@@ -1792,6 +2562,6 @@ function createRedisStore(options) {
   return new RedisStore(options);
 }
 
-export { ArcisError, ValidationError as ArcisValidationError, BLOCKED, ERRORS, HEADERS, INPUT, InputTooLargeError, MemoryStore, RATE_LIMIT, REDACTION, RateLimitError, RedisStore, SanitizationError, SecurityThreatError, VALIDATION, arcis, arcisWithMethods as arcisFunction, createCors, createErrorHandler, createHeaders, createRateLimiter, createRedactor, createRedisStore, createSafeLogger, createSanitizer, createSecureCookies, createValidator, main_default as default, detectCommandInjection, detectHeaderInjection, detectNoSqlInjection, detectPathTraversal, detectPrototypePollution, detectSql, detectXss, enforceSecureCookie, errorHandler, isDangerousExtension, isDangerousNoSqlKey, isDangerousProtoKey, isRedirectSafe, isUrlSafe, rateLimit, safeCors, safeLog, sanitizeCommand, sanitizeFilename, sanitizeHeaderValue, sanitizeHeaders, sanitizeObject, sanitizePath, sanitizeSql, sanitizeString, sanitizeXss, secureCookieDefaults, securityHeaders, validate, validateFile, validateRedirect, validateUrl };
+export { ArcisError, ValidationError as ArcisValidationError, BLOCKED, ERRORS, HEADERS, INPUT, InputTooLargeError, MemoryStore, RATE_LIMIT, REDACTION, RateLimitError, RedisStore, SanitizationError, SecurityThreatError, VALIDATION, arcis, arcisWithMethods as arcisFunction, botProtection, createCors, createErrorHandler, createHeaders, createRateLimiter, createRedactor, createRedisStore, createSafeLogger, createSanitizer, createSecureCookies, createSlidingWindowLimiter, createTokenBucketLimiter, createValidator, main_default as default, detectBot, detectClientIp, detectCommandInjection, detectHeaderInjection, detectNoSqlInjection, detectPathTraversal, detectPrototypePollution, detectSql, detectXss, enforceSecureCookie, errorHandler, fingerprint, formatDuration, isDangerousExtension, isDangerousNoSqlKey, isDangerousProtoKey, isPrivateIp, isRedirectSafe, isUrlSafe, isValidEmailSyntax, parseDuration, rateLimit, safeCors, safeLog, sanitizeCommand, sanitizeFilename, sanitizeHeaderValue, sanitizeHeaders, sanitizeObject, sanitizePath, sanitizeSql, sanitizeString, sanitizeXss, secureCookieDefaults, securityHeaders, validate, validateEmail, validateFile, validateRedirect, validateUrl, verifyEmailMx };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map