@arcis/node 1.4.2 → 1.4.4

package/dist/middleware/index.js

@@ -44,11 +44,47 @@ var HEADERS = {
   /** Default Cache-Control value for security */
   CACHE_CONTROL: "no-store, no-cache, must-revalidate, proxy-revalidate"
 };
+var XSS_PATTERNS = [
+  /** Script tags (ReDoS-safe version) */
+  /<script[^>]*>[\s\S]*?<\/script>/gi,
+  /** javascript: protocol (allow optional spaces before colon) */
+  /javascript\s*:/gi,
+  /** vbscript: protocol */
+  /vbscript\s*:/gi,
+  /** Event handlers (onclick, onerror, etc.) — any separator before attribute */
+  /(?:[\s/])on\w+\s*=/gi,
+  /** iframe tags */
+  /<iframe/gi,
+  /** object tags */
+  /<object/gi,
+  /** embed tags */
+  /<embed/gi,
+  /** data: URIs (only dangerous ones, avoid false positives) */
+  /(?:^|[\s"'=])data:/gi,
+  /** URL-encoded script tags */
+  /%3Cscript/gi,
+  /** SVG with onload */
+  /<svg[^>]*onload/gi,
+  /** form tags — phishing/credential harvesting via action= redirection */
+  /<form[\s>]/gi,
+  /** meta tags — http-equiv refresh redirects or CSP bypass */
+  /<meta[\s>]/gi,
+  /** base href hijacking — redirects all relative URLs to attacker domain */
+  /<base[\s>]/gi,
+  /** link tag injection — stylesheet or preload CSRF attacks */
+  /<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,
@@ -361,13 +397,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
@@ -559,6 +595,80 @@ var SecurityThreatError = 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;");
@@ -604,6 +714,20 @@ function sanitizeXss(input, collectThreats = false, htmlEncode = false) {
   }
   return value;
 }
+function detectXss(input) {
+  if (typeof input !== "string") return false;
+  if (/\s+on\w+\s*=/i.test(input)) return true;
+  if (/javascript\s*:/i.test(input)) return true;
+  if (/vbscript\s*:/i.test(input)) return true;
+  if (/data\s*:\s*text\/html/i.test(input)) return true;
+  for (const pattern of XSS_PATTERNS) {
+    pattern.lastIndex = 0;
+    if (pattern.test(input)) {
+      return true;
+    }
+  }
+  return false;
+}
 
 // src/sanitizers/sql.ts
 function sanitizeSql(input, collectThreats = false) {
@@ -687,6 +811,17 @@ function sanitizePath(input, collectThreats = false) {
   }
   return value;
 }
+function detectPathTraversal(input) {
+  if (typeof input !== "string") return false;
+  const normalized = input.normalize("NFKC");
+  for (const pattern of PATH_PATTERNS) {
+    pattern.lastIndex = 0;
+    if (pattern.test(normalized)) {
+      return true;
+    }
+  }
+  return false;
+}
 
 // src/sanitizers/command.ts
 function sanitizeCommand(input, collectThreats = false) {
@@ -732,6 +867,60 @@ function detectCommandInjection(input) {
   return false;
 }
 
+// src/sanitizers/ssti.ts
+var SSTI_DETECT_PATTERNS = [
+  /** Jinja2 / Twig / Nunjucks: {{ ... }} */
+  /\{\{.*?\}\}/g,
+  /** Freemarker / Thymeleaf / Spring EL: ${ ... } */
+  /\$\{.*?\}/g,
+  /** ERB / EJS: <%= ... %> or <% ... %> */
+  /<%[=\-]?.*?%>/gs,
+  /** Pug / Jade / Slim: #{ ... } */
+  /#\{.*?\}/g,
+  /** Python dunder sandbox escape */
+  /__(?:class|mro|subclasses|globals|builtins|import)__/gi,
+  /** Jinja2 config leak: {{config.X}} or {{config['X']}} */
+  /\{\{\s*config[.\[]/gi,
+  /** Jinja2 built-in objects */
+  /\{\{\s*(?:self|request|lipsum|cycler|joiner|namespace|range)\b/gi
+];
+function detectSsti(input) {
+  if (typeof input !== "string") return false;
+  for (const pattern of SSTI_DETECT_PATTERNS) {
+    pattern.lastIndex = 0;
+    if (pattern.test(input)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// src/sanitizers/xxe.ts
+var XXE_DETECT_PATTERNS = [
+  /** DOCTYPE declaration */
+  /<!DOCTYPE\b/gi,
+  /** ENTITY declaration */
+  /<!ENTITY\b/gi,
+  /** SYSTEM keyword with URI */
+  /\bSYSTEM\s+["']/gi,
+  /** PUBLIC keyword with URI */
+  /\bPUBLIC\s+["']/gi,
+  /** Parameter entity reference (%entity;) */
+  /%\s*\w+\s*;/g,
+  /** CDATA section (often used to smuggle payloads) */
+  /<!\[CDATA\[/gi
+];
+function detectXxe(input) {
+  if (typeof input !== "string") return false;
+  for (const pattern of XXE_DETECT_PATTERNS) {
+    pattern.lastIndex = 0;
+    if (pattern.test(input)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 // src/sanitizers/sanitize.ts
 function sanitizeString(value, options = {}) {
   if (typeof value !== "string") return value;
@@ -801,9 +990,73 @@ function sanitizeObjectDepth(obj, options, depth) {
   }
   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) => {
+  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);
       }
@@ -993,6 +1246,238 @@ function validateField(field, value, rules) {
   // Audio/Video
   "audio/mpeg": [Buffer.from([255, 251]), Buffer.from([255, 243]), Buffer.from([73, 68, 51])]});
 
+// src/validation/email.ts
+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
+  };
+}
+
 // src/logging/redactor.ts
 var LOG_LEVELS = {
   debug: 0,
@@ -1065,10 +1550,213 @@ function redactString(str, maxLength, patterns) {
   return safe;
 }
 
+// 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));
@@ -1080,8 +1768,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 = () => {
@@ -1394,6 +2086,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) {
@@ -1526,7 +2228,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 {
@@ -1587,6 +2298,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);
       }
@@ -1594,6 +2312,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);
       }
@@ -1647,7 +2372,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."
@@ -1690,6 +2422,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();
   };
 }
@@ -1724,9 +2460,93 @@ function escapeRegex(str) {
 }
 var createCsrf = csrfProtection;
 
+// 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;
+}
+
 exports.arcis = arcis;
 exports.arcisFunction = arcisWithMethods;
 exports.botProtection = botProtection;
+exports.checkSignup = checkSignup;
 exports.createCors = createCors;
 exports.createCsrf = createCsrf;
 exports.createErrorHandler = createErrorHandler;
@@ -1745,6 +2565,7 @@ exports.rateLimit = rateLimit;
 exports.safeCors = safeCors;
 exports.secureCookieDefaults = secureCookieDefaults;
 exports.securityHeaders = securityHeaders;
+exports.signupProtection = signupProtection;
 exports.validateCsrfToken = validateCsrfToken;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map