@arcis/node 1.4.2 → 1.4.4

package/dist/index.js

@@ -78,13 +78,19 @@ var XSS_PATTERNS = [
   /** base href hijacking — redirects all relative URLs to attacker domain */
   /<base[\s>]/gi,
   /** link tag injection — stylesheet or preload CSRF attacks */
-  /<link[\s>]/gi
+  /<link[\s>]/gi,
+  /** style tag — CSS expression() / behavior: / IE-era attacks. Mirrors
+   *  Python's xss-style-tag from packages/core/patterns.json. */
+  /<style[\s>]/gi
 ];
 var XSS_REMOVE_PATTERNS = [
   /** Full script blocks (content + tags) */
   /<script[^>]*>[\s\S]*?<\/script>/gi,
   /** Standalone/unclosed script tags */
   /<script[^>]*>/gi,
+  /** style — CSS expression() and behavior: attacks (IE-era but still relevant) */
+  /<style[^>]*>[\s\S]*?<\/style>/gi,
+  /<style[^>]*/gi,
   /** iframe — full block and partial/unclosed */
   /<iframe[^>]*>[\s\S]*?<\/iframe>/gi,
   /<iframe[^>]*/gi,
@@ -400,13 +406,13 @@ function createRateLimiter(options = {}) {
     statusCode = RATE_LIMIT.DEFAULT_STATUS_CODE,
     keyGenerator = (req) => {
       const ip = req.ip ?? req.socket?.remoteAddress;
-      if (!ip) {
-        console.warn(
-          "[arcis] Rate limiter: cannot resolve client IP. All unresolvable clients share one counter. Set Express trust proxy if behind a reverse proxy."
-        );
-        return "unknown";
-      }
-      return ip;
+      if (ip) return ip;
+      const ua = req.headers["user-agent"] ?? "";
+      const lang = req.headers["accept-language"] ?? "";
+      const fp = `${ua}|${lang}`;
+      let hash = 0;
+      for (let i = 0; i < fp.length; i++) hash = (hash << 5) - hash + fp.charCodeAt(i) | 0;
+      return `unknown:${hash.toString(36)}`;
     },
     skip,
     store: externalStore
@@ -618,6 +624,80 @@ var SanitizationError = class extends ArcisError {
   }
 };
 
+// src/middleware/telemetry.ts
+var THREAT_TO_VECTOR = {
+  xss: "xss",
+  sql_injection: "sql",
+  nosql_injection: "nosql",
+  path_traversal: "path",
+  command_injection: "command",
+  prototype_pollution: "prototype",
+  header_injection: "header",
+  ssti: "ssti",
+  xxe: "xxe"
+};
+function createTelemetryEmitter(client) {
+  return (req, res, next) => {
+    const start = performance.now();
+    res.on("finish", () => {
+      try {
+        const event = buildEvent(req, res.statusCode, performance.now() - start);
+        client.record(event);
+      } catch {
+      }
+    });
+    next();
+  };
+}
+function tapSanitizerThreats(handler) {
+  return (req, res, next) => {
+    handler(req, res, (err) => {
+      if (err instanceof SecurityThreatError) {
+        const vector = THREAT_TO_VECTOR[err.threatType] ?? err.threatType;
+        req.__arcis = {
+          vector,
+          rule: `${vector}/match`,
+          severity: "high",
+          matchedPattern: err.pattern,
+          reason: err.message,
+          decision: "deny"
+        };
+      }
+      next(err);
+    });
+  };
+}
+function buildEvent(req, status, latencyMs) {
+  const marker = req.__arcis;
+  const decision = marker?.decision ?? inferDecision(status);
+  return {
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    ip: extractIp(req),
+    method: (req.method ?? "GET").toUpperCase(),
+    path: req.path ?? req.url ?? "/",
+    decision,
+    vector: marker?.vector ?? (status === 429 ? "rate-limit" : void 0),
+    rule: marker?.rule ?? (status === 429 ? "rate-limit/exceeded" : void 0),
+    severity: marker?.severity ?? (status === 429 ? "medium" : void 0),
+    userAgent: typeof req.headers?.["user-agent"] === "string" ? req.headers["user-agent"] : "",
+    reason: marker?.reason,
+    status,
+    matchedPattern: marker?.matchedPattern,
+    latencyMs: Math.max(0, latencyMs)
+  };
+}
+function inferDecision(status) {
+  if (status === 429) return "deny";
+  if (status === 400) return "deny";
+  if (status === 403) return "deny";
+  return "allow";
+}
+function extractIp(req) {
+  if (typeof req.ip === "string" && req.ip.length > 0) return req.ip;
+  const remote = req.socket?.remoteAddress;
+  return typeof remote === "string" ? remote : "0.0.0.0";
+}
+
 // src/sanitizers/utils.ts
 function encodeHtmlEntities(str) {
   return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#x27;");
@@ -816,144 +896,6 @@ function detectCommandInjection(input) {
   return false;
 }
 
-// src/sanitizers/sanitize.ts
-function sanitizeString(value, options = {}) {
-  if (typeof value !== "string") return value;
-  const maxSize = options.maxSize ?? INPUT.DEFAULT_MAX_SIZE;
-  if (value.length > maxSize) {
-    throw new InputTooLargeError(maxSize, value.length);
-  }
-  const reject = options.mode === "reject";
-  let result = value;
-  if (options.sql !== false) {
-    if (reject) {
-      if (detectSql(result)) {
-        throw new SecurityThreatError("sql_injection", "SQL pattern detected in input");
-      }
-    } else {
-      result = sanitizeSql(result);
-    }
-  }
-  if (options.path !== false) {
-    result = sanitizePath(result);
-  }
-  if (options.command !== false) {
-    if (reject) {
-      if (detectCommandInjection(result)) {
-        throw new SecurityThreatError("command_injection", "Shell metacharacter detected in input");
-      }
-    } else {
-      result = sanitizeCommand(result);
-    }
-  }
-  if (options.xss !== false) {
-    result = sanitizeXss(result, false, options.htmlEncode ?? false);
-  }
-  return result;
-}
-function sanitizeObject(obj, options = {}) {
-  if (obj === null || obj === void 0) return obj;
-  if (typeof obj === "string") return sanitizeString(obj, options);
-  if (typeof obj !== "object") return obj;
-  if (Array.isArray(obj)) return obj.map((item) => sanitizeObject(item, options));
-  const result = sanitizeObjectDepth(obj, options, 0);
-  return options.freeze ? Object.freeze(result) : result;
-}
-function sanitizeObjectDepth(obj, options, depth) {
-  if (depth >= INPUT.MAX_RECURSION_DEPTH) return obj;
-  const result = {};
-  for (const key of Object.keys(obj)) {
-    if (options.proto !== false && DANGEROUS_PROTO_KEYS.has(key.toLowerCase())) {
-      continue;
-    }
-    if (options.nosql !== false && NOSQL_DANGEROUS_KEYS.has(key)) {
-      continue;
-    }
-    const sanitizedKey = sanitizeString(key, options);
-    const value = obj[key];
-    if (value === null || value === void 0) {
-      result[sanitizedKey] = value;
-    } else if (typeof value === "string") {
-      result[sanitizedKey] = sanitizeString(value, options);
-    } else if (Array.isArray(value)) {
-      result[sanitizedKey] = value.map((item) => sanitizeObject(item, options));
-    } else if (typeof value === "object") {
-      result[sanitizedKey] = sanitizeObjectDepth(value, options, depth + 1);
-    } else {
-      result[sanitizedKey] = value;
-    }
-  }
-  return result;
-}
-function createSanitizer(options = {}) {
-  return (req, _res, next) => {
-    try {
-      if (req.body && typeof req.body === "object") {
-        req.body = sanitizeObject(req.body, options);
-      }
-      if (req.query && typeof req.query === "object") {
-        const sanitizedQuery = sanitizeObject(req.query, options);
-        Object.defineProperty(req, "query", { value: sanitizedQuery, writable: true, configurable: true });
-      }
-      if (req.params && typeof req.params === "object") {
-        const sanitizedParams = sanitizeObject(req.params, options);
-        Object.defineProperty(req, "params", { value: sanitizedParams, writable: true, configurable: true });
-      }
-      next();
-    } catch (err) {
-      next(err);
-    }
-  };
-}
-
-// src/sanitizers/nosql.ts
-function isDangerousNoSqlKey(key) {
-  return NOSQL_DANGEROUS_KEYS.has(key);
-}
-function detectNoSqlInjection(obj, maxDepth = 10) {
-  if (maxDepth <= 0) return false;
-  if (obj === null || typeof obj !== "object") return false;
-  if (Array.isArray(obj)) {
-    return obj.some((item) => detectNoSqlInjection(item, maxDepth - 1));
-  }
-  for (const key of Object.keys(obj)) {
-    if (isDangerousNoSqlKey(key)) {
-      return true;
-    }
-    const value = obj[key];
-    if (typeof value === "object" && value !== null) {
-      if (detectNoSqlInjection(value, maxDepth - 1)) {
-        return true;
-      }
-    }
-  }
-  return false;
-}
-
-// src/sanitizers/prototype.ts
-function isDangerousProtoKey(key) {
-  return DANGEROUS_PROTO_KEYS.has(key.toLowerCase());
-}
-function detectPrototypePollution(obj, maxDepth = 10) {
-  if (maxDepth <= 0) return false;
-  if (obj === null || typeof obj !== "object") return false;
-  if (Array.isArray(obj)) {
-    return obj.some((item) => detectPrototypePollution(item, maxDepth - 1));
-  }
-  for (const key of Object.keys(obj)) {
-    if (DANGEROUS_PROTO_KEYS.has(key.toLowerCase())) {
-      return true;
-    }
-    const value = obj[key];
-    if (typeof value === "object" && value !== null) {
-      if (detectPrototypePollution(value, maxDepth - 1)) {
-        return true;
-      }
-    }
-  }
-  return false;
-}
-
 // src/sanitizers/ssti.ts
 var SSTI_DETECT_PATTERNS = [
   /** Jinja2 / Twig / Nunjucks: {{ ... }} */
@@ -975,17 +917,19 @@ var SSTI_REMOVE_PATTERNS = [
   /** Jinja2 / Twig: {{ ... }} — always strip (not valid in any JS context) */
   /\{\{.*?\}\}/g,
   /**
-   * Freemarker / Spring EL: ${...} — only strip when the expression contains
-   * operators (?!*+-/), method calls (), or known-dangerous prefixes.
+   * Freemarker / Spring EL: ${...} — strip when expression contains operators,
+   * method calls, or Python dunder patterns (sandbox escape).
    * Bare ${name} and ${user.name} are left intact (JS template literal syntax).
    */
+  /\$\{[^}]*__\w+__[^}]*\}/g,
   /\$\{[^}]*[?!()*+\-/][^}]*\}/g,
   /** ERB / EJS: <%= ... %> */
   /<%[=\-]?.*?%>/gs,
   /**
-   * Pug / Jade: #{...} — same narrowing as ${ above.
+   * Pug / Jade: #{...} — same narrowing as ${ above, plus dunder detection.
    * #{name} output expressions are left intact.
    */
+  /#\{[^}]*__\w+__[^}]*\}/g,
   /#\{[^}]*[?!()*+\-/][^}]*\}/g,
   /** Python dunder sandbox escape — always strip */
   /__(?:class|mro|subclasses|globals|builtins|import)__/gi
@@ -1034,6 +978,8 @@ function detectSsti(input) {
 }
 
 // src/sanitizers/xxe.ts
+var MAX_XXE_INPUT_BYTES = 1e6;
+var MAX_ENTITY_REFERENCES = 64;
 var XXE_DETECT_PATTERNS = [
   /** DOCTYPE declaration */
   /<!DOCTYPE\b/gi,
@@ -1063,6 +1009,19 @@ function sanitizeXxe(input, collectThreats = false) {
   const threats = [];
   let value = input;
   let wasSanitized = false;
+  if (value.length > MAX_XXE_INPUT_BYTES) {
+    if (collectThreats) {
+      threats.push({ type: "xxe", pattern: "oversize_input", original: `length=${value.length}` });
+    }
+    return collectThreats ? { value: "", wasSanitized: true, threats } : "";
+  }
+  const entityRefs = value.match(/&\w+;/g);
+  if (entityRefs && entityRefs.length > MAX_ENTITY_REFERENCES) {
+    if (collectThreats) {
+      threats.push({ type: "xxe", pattern: "entity_expansion", original: `count=${entityRefs.length}` });
+    }
+    return collectThreats ? { value: "", wasSanitized: true, threats } : "";
+  }
   for (const pattern of XXE_REMOVE_PATTERNS) {
     pattern.lastIndex = 0;
     if (pattern.test(value)) {
@@ -1099,13 +1058,213 @@ function detectXxe(input) {
   return false;
 }
 
+// src/sanitizers/sanitize.ts
+function sanitizeString(value, options = {}) {
+  if (typeof value !== "string") return value;
+  const maxSize = options.maxSize ?? INPUT.DEFAULT_MAX_SIZE;
+  if (value.length > maxSize) {
+    throw new InputTooLargeError(maxSize, value.length);
+  }
+  const reject = options.mode === "reject";
+  let result = value;
+  if (options.sql !== false) {
+    if (reject) {
+      if (detectSql(result)) {
+        throw new SecurityThreatError("sql_injection", "SQL pattern detected in input");
+      }
+    } else {
+      result = sanitizeSql(result);
+    }
+  }
+  if (options.path !== false) {
+    result = sanitizePath(result);
+  }
+  if (options.command !== false) {
+    if (reject) {
+      if (detectCommandInjection(result)) {
+        throw new SecurityThreatError("command_injection", "Shell metacharacter detected in input");
+      }
+    } else {
+      result = sanitizeCommand(result);
+    }
+  }
+  if (options.xss !== false) {
+    result = sanitizeXss(result, false, options.htmlEncode ?? false);
+  }
+  return result;
+}
+function sanitizeObject(obj, options = {}) {
+  if (obj === null || obj === void 0) return obj;
+  if (typeof obj === "string") return sanitizeString(obj, options);
+  if (typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) return obj.map((item) => sanitizeObject(item, options));
+  const result = sanitizeObjectDepth(obj, options, 0);
+  return options.freeze ? Object.freeze(result) : result;
+}
+function sanitizeObjectDepth(obj, options, depth) {
+  if (depth >= INPUT.MAX_RECURSION_DEPTH) return obj;
+  const result = {};
+  for (const key of Object.keys(obj)) {
+    if (options.proto !== false && DANGEROUS_PROTO_KEYS.has(key.toLowerCase())) {
+      continue;
+    }
+    if (options.nosql !== false && NOSQL_DANGEROUS_KEYS.has(key)) {
+      continue;
+    }
+    const sanitizedKey = sanitizeString(key, options);
+    const value = obj[key];
+    if (value === null || value === void 0) {
+      result[sanitizedKey] = value;
+    } else if (typeof value === "string") {
+      result[sanitizedKey] = sanitizeString(value, options);
+    } else if (Array.isArray(value)) {
+      result[sanitizedKey] = value.map((item) => sanitizeObject(item, options));
+    } else if (typeof value === "object") {
+      result[sanitizedKey] = sanitizeObjectDepth(value, options, depth + 1);
+    } else {
+      result[sanitizedKey] = value;
+    }
+  }
+  return result;
+}
+function scanThreats(data, depth = 0) {
+  if (depth > INPUT.MAX_RECURSION_DEPTH) return null;
+  if (data && typeof data === "object" && !Array.isArray(data)) {
+    for (const key of Object.keys(data)) {
+      const lower = key.toLowerCase();
+      if (DANGEROUS_PROTO_KEYS.has(lower)) {
+        return { vector: "prototype", rule: "prototype/match", matchedPattern: key };
+      }
+      if (NOSQL_DANGEROUS_KEYS.has(key)) {
+        return { vector: "nosql", rule: "nosql/match", matchedPattern: key };
+      }
+      const inner = scanThreats(data[key], depth + 1);
+      if (inner) return inner;
+    }
+    return null;
+  }
+  if (Array.isArray(data)) {
+    for (const item of data) {
+      const inner = scanThreats(item, depth + 1);
+      if (inner) return inner;
+    }
+    return null;
+  }
+  if (typeof data !== "string") return null;
+  const sample = data.slice(0, 80);
+  if (detectXss(data)) {
+    return { vector: "xss", rule: "xss/match", matchedPattern: sample };
+  }
+  if (detectSsti(data)) {
+    return { vector: "ssti", rule: "ssti/match", matchedPattern: sample };
+  }
+  if (detectXxe(data)) {
+    return { vector: "xxe", rule: "xxe/match", matchedPattern: sample };
+  }
+  if (detectSql(data)) {
+    return { vector: "sql", rule: "sql/match", matchedPattern: sample };
+  }
+  if (detectPathTraversal(data)) {
+    return { vector: "path", rule: "path/match", matchedPattern: sample };
+  }
+  if (detectCommandInjection(data)) {
+    return { vector: "command", rule: "command/match", matchedPattern: sample };
+  }
+  return null;
+}
+function createSanitizer(options = {}) {
+  return (req, res, next) => {
+    try {
+      if (options.block) {
+        const hit = scanThreats(req.body) || scanThreats(req.query) || scanThreats(req.params) || scanThreats(req.path);
+        if (hit) {
+          req.__arcis = {
+            vector: hit.vector,
+            rule: hit.rule,
+            severity: "high",
+            matchedPattern: hit.matchedPattern,
+            reason: `${hit.vector} pattern detected in request`,
+            decision: "deny"
+          };
+          res.status(403).json({
+            error: "Request blocked for security reasons",
+            code: "SECURITY_THREAT",
+            vector: hit.vector
+          });
+          return;
+        }
+      }
+      if (req.body && typeof req.body === "object") {
+        req.body = sanitizeObject(req.body, options);
+      }
+      if (req.query && typeof req.query === "object") {
+        const sanitizedQuery = sanitizeObject(req.query, options);
+        Object.defineProperty(req, "query", { value: sanitizedQuery, writable: true, configurable: true });
+      }
+      if (req.params && typeof req.params === "object") {
+        const sanitizedParams = sanitizeObject(req.params, options);
+        Object.defineProperty(req, "params", { value: sanitizedParams, writable: true, configurable: true });
+      }
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+// src/sanitizers/nosql.ts
+function isDangerousNoSqlKey(key) {
+  return NOSQL_DANGEROUS_KEYS.has(key);
+}
+function detectNoSqlInjection(obj, maxDepth = 10) {
+  if (maxDepth <= 0) return false;
+  if (obj === null || typeof obj !== "object") return false;
+  if (Array.isArray(obj)) {
+    return obj.some((item) => detectNoSqlInjection(item, maxDepth - 1));
+  }
+  for (const key of Object.keys(obj)) {
+    if (isDangerousNoSqlKey(key)) {
+      return true;
+    }
+    const value = obj[key];
+    if (typeof value === "object" && value !== null) {
+      if (detectNoSqlInjection(value, maxDepth - 1)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+// src/sanitizers/prototype.ts
+function isDangerousProtoKey(key) {
+  return DANGEROUS_PROTO_KEYS.has(key.toLowerCase());
+}
+function detectPrototypePollution(obj, maxDepth = 10) {
+  if (maxDepth <= 0) return false;
+  if (obj === null || typeof obj !== "object") return false;
+  if (Array.isArray(obj)) {
+    return obj.some((item) => detectPrototypePollution(item, maxDepth - 1));
+  }
+  for (const key of Object.keys(obj)) {
+    if (DANGEROUS_PROTO_KEYS.has(key.toLowerCase())) {
+      return true;
+    }
+    const value = obj[key];
+    if (typeof value === "object" && value !== null) {
+      if (detectPrototypePollution(value, maxDepth - 1)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
 // src/sanitizers/jsonp.ts
-var SAFE_CALLBACK_PATTERN = /^[a-zA-Z_$][a-zA-Z0-9_$.[\]]*$/;
+var SAFE_CALLBACK_PATTERN = /^[a-zA-Z_$][a-zA-Z0-9_$.]*$/;
 var DANGEROUS_CALLBACK_PATTERNS = [
-  /\.\./,
+  /\.\./
   // prototype chain traversal
-  /\[\s*\]/
-  // empty bracket access
 ];
 function sanitizeJsonpCallback(callback, maxLength = 128) {
   if (typeof callback !== "string" || callback.length === 0) {
@@ -1190,7 +1349,7 @@ function detectHeaderInjection(input) {
 
 // src/sanitizers/pii.ts
 var EMAIL_RE = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z]{2,})+/g;
-var PHONE_RE = /(?:\+?1[-.\s]?)?\(?[2-9]\d{2}\)?[-.\s]?\d{3}[-.\s]?\d{4}/g;
+var PHONE_RE = /(?<!\d)(?:\+?1[-.\s]?)?\(?[2-9]\d{2}\)?[-.\s]?\d{3}[-.\s]?\d{4}(?!\d)/g;
 var CREDIT_CARD_RE = /\b(?:\d[ -]*?){13,19}\b/g;
 var SSN_RE = /\b\d{3}[-\s]\d{2}[-\s]\d{4}\b/g;
 var IPV4_RE = /\b(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\b/g;
@@ -2314,10 +2473,213 @@ function createRedactor(sensitiveKeys = []) {
 }
 var safeLog = createSafeLogger;
 
+// src/telemetry/client.ts
+var DEFAULT_BATCH_SIZE = 50;
+var MAX_BATCH_SIZE = 500;
+var DEFAULT_FLUSH_INTERVAL_MS = 5e3;
+var MIN_FLUSH_INTERVAL_MS = 500;
+var FLUSH_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_QUEUE_SIZE = 1e4;
+var TelemetryClient = class {
+  constructor(options) {
+    this.queue = [];
+    this.flushing = false;
+    this.closed = false;
+    // Counts events dropped since the last successful flush. Resets to 0
+    // each flush so onQueueOverflow callbacks see "drops in this window"
+    // rather than a monotonic lifetime counter.
+    this.droppedSinceLastFlush = 0;
+    if (!options.endpoint || typeof options.endpoint !== "string") {
+      throw new TypeError("TelemetryClient: `endpoint` is required");
+    }
+    this.endpoint = options.endpoint;
+    this.apiKey = options.apiKey;
+    this.workspaceId = options.workspaceId;
+    this.batchSize = clamp(
+      options.batchSize ?? DEFAULT_BATCH_SIZE,
+      1,
+      MAX_BATCH_SIZE
+    );
+    this.flushIntervalMs = Math.max(
+      options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS,
+      MIN_FLUSH_INTERVAL_MS
+    );
+    this.maxQueueSize = Math.max(
+      options.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE,
+      this.batchSize
+    );
+    this.onError = options.onError ?? (() => {
+    });
+    this.onQueueOverflow = options.onQueueOverflow ?? (() => {
+    });
+    this.startTimer();
+  }
+  /**
+   * Enqueue an event. Fast, synchronous, cannot throw.
+   * Triggers a flush if the queue has reached `batchSize`.
+   */
+  record(event) {
+    if (this.closed) return;
+    this.queue.push(event);
+    if (this.queue.length > this.maxQueueSize) {
+      const drop = this.queue.length - this.maxQueueSize;
+      this.queue.splice(0, drop);
+      this.droppedSinceLastFlush += drop;
+      try {
+        this.onQueueOverflow(this.droppedSinceLastFlush);
+      } catch {
+      }
+    }
+    if (this.queue.length >= this.batchSize) {
+      void this.flush();
+    }
+  }
+  /**
+   * Manually flush the queue. Pulls up to `batchSize` events into a batch and
+   * POSTs them. Returns a resolved promise on success OR on handled failure.
+   * Never throws.
+   */
+  async flush() {
+    if (this.flushing) return;
+    if (this.queue.length === 0) return;
+    this.flushing = true;
+    try {
+      const batch = this.queue.splice(0, this.batchSize);
+      await this.send(batch);
+      this.droppedSinceLastFlush = 0;
+    } catch (err) {
+      this.safeNotify(err);
+    } finally {
+      this.flushing = false;
+    }
+    if (!this.closed && this.queue.length > 0) {
+      void this.flush();
+    }
+  }
+  /**
+   * Shut down: stop the interval timer and attempt one final flush.
+   * Safe to call multiple times.
+   */
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.timer !== void 0) {
+      clearInterval(this.timer);
+      this.timer = void 0;
+    }
+    if (this.signalHandler !== void 0) {
+      process.off("SIGTERM", this.signalHandler);
+      process.off("SIGINT", this.signalHandler);
+      this.signalHandler = void 0;
+    }
+    try {
+      await this.flush();
+    } catch {
+    }
+  }
+  /**
+   * Register `SIGTERM` / `SIGINT` handlers that call `close()` to drain
+   * the queue on graceful shutdown. Opt-in — libraries should not silently
+   * attach global signal handlers. Safe to call multiple times.
+   */
+  installShutdownHooks() {
+    if (this.signalHandler !== void 0 || this.closed) return;
+    const handler = () => {
+      void this.close();
+    };
+    this.signalHandler = handler;
+    process.once("SIGTERM", handler);
+    process.once("SIGINT", handler);
+  }
+  /** Count of events currently waiting to be sent. Useful for tests. */
+  get pendingCount() {
+    return this.queue.length;
+  }
+  // ── internals ─────────────────────────────────────────────────────────
+  async send(batch) {
+    const headers = {
+      "content-type": "application/json"
+    };
+    if (this.apiKey) headers["authorization"] = `Bearer ${this.apiKey}`;
+    if (this.workspaceId) headers["x-workspace-id"] = this.workspaceId;
+    const controller = new AbortController();
+    const abortTimer = setTimeout(() => controller.abort(), FLUSH_TIMEOUT_MS);
+    try {
+      const res = await fetch(this.endpoint, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ events: batch }),
+        signal: controller.signal
+      });
+      if (!res.ok) {
+        const text = await safeReadBody(res);
+        throw new TelemetryHttpError(res.status, text);
+      }
+    } finally {
+      clearTimeout(abortTimer);
+    }
+  }
+  startTimer() {
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.flushIntervalMs);
+    this.timer.unref?.();
+  }
+  safeNotify(err) {
+    try {
+      this.onError(err instanceof Error ? err : new Error(String(err)));
+    } catch {
+    }
+  }
+};
+var TelemetryHttpError = class extends Error {
+  constructor(status, responseBody) {
+    super(`Telemetry ingest returned HTTP ${status}`);
+    this.status = status;
+    this.responseBody = responseBody;
+    this.name = "TelemetryHttpError";
+  }
+};
+function clamp(value, min, max) {
+  if (!Number.isFinite(value)) return min;
+  return Math.max(min, Math.min(max, Math.trunc(value)));
+}
+async function safeReadBody(res) {
+  try {
+    const text = await res.text();
+    return text.slice(0, 500);
+  } catch {
+    return "";
+  }
+}
+
 // src/middleware/main.ts
+function buildTelemetryFromEnv() {
+  const env = typeof process !== "undefined" ? process.env : void 0;
+  const endpoint = env?.ARCIS_ENDPOINT;
+  if (!endpoint) return void 0;
+  const opts = { endpoint };
+  if (env?.ARCIS_WORKSPACE_ID) opts.workspaceId = env.ARCIS_WORKSPACE_ID;
+  if (env?.ARCIS_KEY) opts.apiKey = env.ARCIS_KEY;
+  const batch = env?.ARCIS_BATCH_SIZE ? parseInt(env.ARCIS_BATCH_SIZE, 10) : NaN;
+  if (!Number.isNaN(batch)) opts.batchSize = batch;
+  const flush = env?.ARCIS_FLUSH_INTERVAL_MS ? parseInt(env.ARCIS_FLUSH_INTERVAL_MS, 10) : NaN;
+  if (!Number.isNaN(flush)) opts.flushIntervalMs = flush;
+  return opts;
+}
 function arcis(options = {}) {
   const middlewares = [];
   const cleanupFns = [];
+  let telemetryClient;
+  const telemetryOpts = options.telemetry?.endpoint ? options.telemetry : buildTelemetryFromEnv();
+  if (telemetryOpts) {
+    const client = new TelemetryClient(telemetryOpts);
+    telemetryClient = client;
+    middlewares.push(createTelemetryEmitter(client));
+    cleanupFns.push(() => {
+      void client.close();
+    });
+  }
   if (options.headers !== false) {
     const headerOpts = typeof options.headers === "object" ? options.headers : {};
     middlewares.push(createHeaders(headerOpts));
@@ -2329,8 +2691,12 @@ function arcis(options = {}) {
     cleanupFns.push(() => rateLimiter.close());
   }
   if (options.sanitize !== false) {
-    const sanitizeOpts = typeof options.sanitize === "object" ? options.sanitize : {};
-    middlewares.push(createSanitizer(sanitizeOpts));
+    const sanitizeOpts = typeof options.sanitize === "object" ? { ...options.sanitize } : {};
+    if (options.block && sanitizeOpts.block === void 0) {
+      sanitizeOpts.block = true;
+    }
+    const sanitizer = createSanitizer(sanitizeOpts);
+    middlewares.push(telemetryClient ? tapSanitizerThreats(sanitizer) : sanitizer);
   }
   const result = middlewares;
   result.close = () => {
@@ -2657,6 +3023,16 @@ function secureCookieDefaults(options = {}) {
     sameSite: options.sameSite ?? "Lax",
     path: options.path
   };
+  if (resolved.sameSite === "None" && resolved.secure === false) {
+    throw new Error(
+      "[arcis] secureCookieDefaults: sameSite=None requires secure=true (modern browsers reject the cookie otherwise)"
+    );
+  }
+  if (resolved.httpOnly === false && resolved.secure === false && isProduction) {
+    console.warn(
+      "[arcis] secureCookieDefaults: httpOnly and secure are both disabled in production \u2014 cookies will be readable by JS and sent over HTTP"
+    );
+  }
   return (_req, res, next) => {
     const originalSetHeader = res.setHeader.bind(res);
     res.setHeader = function patchedSetHeader(name, value) {
@@ -2789,7 +3165,16 @@ function detectBehavioralSignals(req) {
 }
 function detectBot(req) {
   const rawUa = req.headers["user-agent"] ?? "";
-  const ua = rawUa.length > 2048 ? rawUa.slice(0, 2048) : rawUa;
+  if (rawUa.length > 2048) {
+    return {
+      isBot: true,
+      category: "UNKNOWN",
+      name: null,
+      confidence: 0.9,
+      signals: detectBehavioralSignals(req)
+    };
+  }
+  const ua = rawUa;
   const signals = detectBehavioralSignals(req);
   if (!ua) {
     return {
@@ -2850,6 +3235,13 @@ function botProtection(options = {}) {
       return next();
     }
     if (denySet.has(result.category)) {
+      req.__arcis = {
+        vector: "bot",
+        rule: `bot/${result.category.toLowerCase()}`,
+        severity: "medium",
+        reason: result.name ? `Bot detected: ${result.name}` : "Bot detected",
+        decision: "deny"
+      };
       if (onDetected) {
         return onDetected(req, res, result);
       }
@@ -2857,6 +3249,13 @@ function botProtection(options = {}) {
       return;
     }
     if (defaultAction === "deny") {
+      req.__arcis = {
+        vector: "bot",
+        rule: "bot/uncategorized",
+        severity: "medium",
+        reason: "Uncategorized bot under defaultAction=deny",
+        decision: "deny"
+      };
       if (onDetected) {
         return onDetected(req, res, result);
       }
@@ -2910,7 +3309,14 @@ function csrfProtection(options = {}) {
     sameSite: options.cookie?.sameSite ?? "Lax",
     domain: options.cookie?.domain
   };
-  const defaultOnError = (_req, res, _next) => {
+  const defaultOnError = (req, res, _next) => {
+    req.__arcis = {
+      vector: "csrf",
+      rule: "csrf/token-mismatch",
+      severity: "high",
+      reason: "CSRF token missing or invalid",
+      decision: "deny"
+    };
     res.status(403).json({
       error: "CSRF token validation failed",
       message: "Invalid or missing CSRF token. Include the token from the cookie in the X-CSRF-Token header."
@@ -2953,6 +3359,10 @@ function csrfProtection(options = {}) {
     if (!validateCsrfToken(cookieToken, requestToken)) {
       return onError(req, res, next);
     }
+    if (options.rotateOnUse) {
+      const freshToken = generateCsrfToken(tokenLength);
+      setCsrfCookie(res, cookieName, freshToken, cookieOpts);
+    }
     next();
   };
 }
@@ -2989,7 +3399,7 @@ var createCsrf = csrfProtection;
 
 // src/middleware/hpp.ts
 function hpp(options = {}) {
-  const whitelist = new Set(options.whitelist ?? []);
+  const whitelist = new Set((options.whitelist ?? []).map((k) => k.toLowerCase()));
   const checkQuery = options.checkQuery ?? true;
   const checkBody = options.checkBody ?? true;
   return (req, _res, next) => {
@@ -2999,7 +3409,7 @@ function hpp(options = {}) {
       for (const [key, value] of Object.entries(req.query)) {
         if (Array.isArray(value)) {
           const strings = value.filter((v) => typeof v === "string");
-          if (whitelist.has(key)) {
+          if (whitelist.has(key.toLowerCase())) {
             clean[key] = strings;
           } else {
             polluted[key] = strings;
@@ -3017,7 +3427,7 @@ function hpp(options = {}) {
       const clean = {};
       for (const [key, value] of Object.entries(req.body)) {
         if (Array.isArray(value)) {
-          if (whitelist.has(key)) {
+          if (whitelist.has(key.toLowerCase())) {
             clean[key] = value;
           } else {
             polluted[key] = value;
@@ -3035,6 +3445,89 @@ function hpp(options = {}) {
 }
 var createHpp = hpp;
 
+// src/middleware/signup-protection.ts
+function checkSignup(req, options = {}) {
+  const {
+    emailField = "email",
+    checkEmail = true,
+    blockDisposable = true,
+    checkBot = true,
+    allowedBotCategories = [],
+    allowedEmailDomains = [],
+    blockedEmailDomains = []
+  } = options;
+  if (checkBot) {
+    const bot = detectBot(req);
+    if (bot.isBot && !allowedBotCategories.includes(bot.category)) {
+      return {
+        allowed: false,
+        reason: "bot",
+        details: { category: bot.category, name: bot.name, confidence: bot.confidence }
+      };
+    }
+  }
+  if (checkEmail) {
+    const email = req.body?.[emailField];
+    if (typeof email !== "string" || email.length === 0) {
+      return { allowed: false, reason: "missing_email" };
+    }
+    const result = validateEmail(email, {
+      checkDisposable: blockDisposable,
+      allowedDomains: allowedEmailDomains,
+      blockedDomains: blockedEmailDomains
+    });
+    if (!result.valid) {
+      const reason = result.reason === "disposable" ? "disposable_email" : "invalid_email";
+      return { allowed: false, reason, details: { emailReason: result.reason } };
+    }
+  }
+  return { allowed: true, reason: "ok" };
+}
+function signupProtection(options = {}) {
+  const rateLimitCfg = options.rateLimit;
+  const limiter = rateLimitCfg === false ? null : createRateLimiter({
+    max: rateLimitCfg?.max ?? 5,
+    windowMs: rateLimitCfg?.windowMs ?? 6e4,
+    message: "Too many signup attempts"
+  });
+  const handler = (req, res, next) => {
+    const result = checkSignup(req, options);
+    if (!result.allowed) {
+      options.onBlocked?.(req, result);
+      const status = result.reason === "bot" ? 403 : 400;
+      res.status(status).json({ error: "signup_blocked", reason: result.reason });
+      return;
+    }
+    if (limiter) {
+      let rateLimited = false;
+      const rateLimitNext = (err) => {
+        if (err) return next(err);
+        if (!rateLimited) next();
+      };
+      const patchedRes = new Proxy(res, {
+        get(target, prop) {
+          if (prop === "status") {
+            return (code) => {
+              if (code === 429) {
+                rateLimited = true;
+                options.onBlocked?.(req, { allowed: false, reason: "rate_limited" });
+              }
+              return target.status.call(target, code);
+            };
+          }
+          return Reflect.get(target, prop);
+        }
+      });
+      limiter(req, patchedRes, rateLimitNext);
+      return;
+    }
+    next();
+  };
+  const middleware = handler;
+  middleware.close = () => limiter?.close();
+  return middleware;
+}
+
 // src/utils/ip.ts
 var PLATFORM_HEADERS = {
   cloudflare: "cf-connecting-ip",
@@ -3332,10 +3825,13 @@ exports.RateLimitError = RateLimitError;
 exports.RedisStore = RedisStore;
 exports.SanitizationError = SanitizationError;
 exports.SecurityThreatError = SecurityThreatError;
+exports.TelemetryClient = TelemetryClient;
+exports.TelemetryHttpError = TelemetryHttpError;
 exports.VALIDATION = VALIDATION;
 exports.arcis = arcis;
 exports.arcisFunction = arcisWithMethods;
 exports.botProtection = botProtection;
+exports.checkSignup = checkSignup;
 exports.createCors = createCors;
 exports.createCsrf = createCsrf;
 exports.createErrorHandler = createErrorHandler;
@@ -3405,6 +3901,7 @@ exports.scanObjectPii = scanObjectPii;
 exports.scanPii = scanPii;
 exports.secureCookieDefaults = secureCookieDefaults;
 exports.securityHeaders = securityHeaders;
+exports.signupProtection = signupProtection;
 exports.validate = validate;
 exports.validateCsrfToken = validateCsrfToken;
 exports.validateEmail = validateEmail;