@camada/node 0.3.1 → 0.4.0

package/dist/nest.cjs

@@ -46,10 +46,15 @@ var import_common = require("@nestjs/common");
 // src/camada.ts
 var import_node_crypto2 = require("crypto");
 var import_core3 = require("@camada/core");
+var import_node_net = require("net");
 var import_iife_string = __toESM(require("@camada/browser/iife-string"), 1);
 
 // src/env.ts
 var import_core = require("@camada/core");
+function parseTlsxHeader(raw) {
+  const n = (raw ?? "").trim().toLowerCase();
+  return /^[a-z0-9!#$%&'*+.^_`|~-]+$/.test(n) ? n : null;
+}
 function resolveEnv(env = process.env) {
   const key = (0, import_core.parseKey)(env.CAMADA_KEY);
   const ingestToken = key?.ingestToken ?? env.CAMADA_TOKEN;
@@ -63,7 +68,8 @@ function resolveEnv(env = process.env) {
     secret: env.CAMADA_KEY || `${ingestToken}.${snapToken}`,
     snapshotUrl: env.CAMADA_SNAPSHOT_URL || `${ingestUrl}/snapshot`,
     serverless: env.CAMADA_SERVERLESS === "1",
-    trustedProxy: (0, import_core.parseTrustedProxyEnv)(env.CAMADA_TRUSTED_PROXY)
+    trustedProxy: (0, import_core.parseTrustedProxyEnv)(env.CAMADA_TRUSTED_PROXY),
+    tlsxHeader: parseTlsxHeader(env.CAMADA_TLSX_HEADER)
   };
 }
 
@@ -95,18 +101,45 @@ function readBody(req, done) {
   req.on("end", () => done(dead ? "" : Buffer.concat(chunks).toString("utf8")));
   req.on("error", () => done(""));
 }
-var isHttps = (req) => !!req.socket?.encrypted || req.headers["x-forwarded-proto"] === "https";
-function writeChallengePage(res, html) {
-  res.writeHead(403, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "x-camada-challenge": "1" });
-  res.end(html);
+var FORM_FIELDS = ["nonce", "solution", "to"];
+function parsedBody(req) {
+  const b = req.body;
+  if (typeof b === "string") return b;
+  if (Buffer.isBuffer(b)) return b.toString("utf8");
+  return b && typeof b === "object" ? b : null;
+}
+function readForm(req, done) {
+  if (!req.readableEnded) {
+    readBody(req, (body) => done((0, import_core2.parseFormBody)(body)));
+    return;
+  }
+  const b = parsedBody(req);
+  if (typeof b === "string") {
+    done(b.length > BODY_MAX ? {} : (0, import_core2.parseFormBody)(b));
+    return;
+  }
+  const form = /* @__PURE__ */ Object.create(null);
+  for (const k of FORM_FIELDS) {
+    const v = b?.[k];
+    if (typeof v === "string") form[k] = v;
+  }
+  done(form);
 }
-function writeChallengeJson(res) {
-  res.writeHead(403, { "content-type": "application/json", "cache-control": "no-store", "x-camada-challenge": "1" });
-  res.end('{"error":"challenge_required"}');
+var isHttps = (req) => !!req.socket?.encrypted || req.headers["x-forwarded-proto"] === "https";
+function writeChallengePage(res, o) {
+  res.removeHeader("content-security-policy");
+  res.removeHeader("content-security-policy-report-only");
+  res.writeHead(403, {
+    "content-type": "text/html; charset=utf-8",
+    "cache-control": "no-store",
+    "x-camada-challenge": "1",
+    "content-security-policy": (0, import_core2.challengePageCsp)(o.bits)
+  });
+  res.end((0, import_core2.challengePage)(o));
 }
 
 // package.json
-var version = "0.3.1";
+var version = "0.4.0";
 var name = "@camada/node";
 
 // src/version.ts
@@ -117,11 +150,40 @@ var SESSION_COOKIE = "_sfp";
 var SCRIPT_PATH = "/_cam/b.js";
 var FP_PATH = "/_cam/fp";
 var FP_MAX = 32 * 1024;
+function isLoopbackPeer(peer) {
+  const k = (0, import_node_net.isIP)(peer);
+  if (k === 4) return peer.startsWith("127.");
+  return k !== 6 || peer === "::1" || /^::ffff:127\./i.test(peer);
+}
+var TLSX_RE = /^[A-Za-z0-9+/=_-]+$/;
 var ATTACHED = /* @__PURE__ */ Symbol.for("camada.attached");
 var headerReader = (req) => (name2) => {
   const v = req.headers[name2];
   return v == null ? null : Array.isArray(v) ? v.join(", ") : v;
 };
+var splitUrl = (raw) => {
+  const qi = raw.indexOf("?");
+  return qi === -1 ? { path: raw, query: "" } : { path: raw.slice(0, qi), query: raw.slice(qi) };
+};
+var isPage = (req) => (0, import_core3.wantsHtml)(req.headers.accept ?? null, req.headers["sec-fetch-dest"] ?? null);
+function pathAndQuery(req) {
+  return splitUrl(req.originalUrl || req.url || "/");
+}
+var atEndpoint = (req, path, endpoint) => path === endpoint || splitUrl(req.url || "/").path === endpoint;
+function mountPrefix(req) {
+  if (!req.originalUrl) return "";
+  const full = splitUrl(req.originalUrl).path, rel = splitUrl(req.url || "/").path;
+  return rel !== "/" && full !== rel && full.endsWith(rel) ? full.slice(0, full.length - rel.length) : "";
+}
+function onUnixListener(socket) {
+  const srv = socket?.server;
+  if (!srv) return false;
+  try {
+    if (typeof srv.address?.() === "string") return true;
+  } catch {
+  }
+  return typeof srv._pipeName === "string";
+}
 var cookieValue = (cookie, name2) => {
   const src = "; " + cookie;
   const i = src.indexOf("; " + name2 + "=");
@@ -141,6 +203,27 @@ function keepSessionCookie(res, cookie) {
   };
   res.setHeader("set-cookie", cookie);
 }
+var NO_STORE_HEADERS = ["cache-control", "cdn-cache-control", "surrogate-control", "cloudflare-cdn-cache-control", "vercel-cdn-cache-control", "netlify-cdn-cache-control"];
+function signal(res) {
+  const set = res.setHeader, writeHead = res.writeHead;
+  const isNoStore = (n) => typeof n === "string" && NO_STORE_HEADERS.includes(n.toLowerCase());
+  const strip = (h) => {
+    if (Array.isArray(h)) {
+      if (h.length && Array.isArray(h[0])) return h.filter((p) => !isNoStore(p[0]));
+      const out = [];
+      for (let i = 0; i < h.length; i += 2) if (!isNoStore(h[i])) out.push(h[i], h[i + 1]);
+      return out;
+    }
+    if (h && typeof h === "object") return Object.fromEntries(Object.entries(h).filter(([k]) => !isNoStore(k)));
+    return h;
+  };
+  res.writeHead = function(status, ...rest) {
+    if (!this.headersSent) for (const h of NO_STORE_HEADERS) set.call(this, h, "no-store");
+    return writeHead.call(this, status, ...rest.map(strip));
+  };
+  res.setHeader("x-camada-challenge", "1");
+  for (const h of NO_STORE_HEADERS) res.setHeader(h, "no-store");
+}
 var Camada = class {
   env;
   snap = null;
@@ -150,16 +233,25 @@ var Camada = class {
   fpPath;
   challengeOn;
   challengePath;
+  challengePathSet;
+  // configured explicitly: used as given, never prefixed
+  scriptPathSet;
   kit = null;
   envSource;
+  tlsxHeader;
+  waitUntil;
   constructor(opts = {}) {
     this.envSource = opts.env ?? process.env;
     this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.waitUntil = opts.waitUntil;
     this.scriptPath = opts.scriptPath ?? SCRIPT_PATH;
     this.fpPath = opts.fpPath ?? FP_PATH;
     this.challengeOn = opts.challenge !== false && this.envSource.CAMADA_CHALLENGE !== "0";
     this.challengePath = opts.challengePath ?? CHALLENGE_PATH;
+    this.challengePathSet = opts.challengePath != null;
+    this.scriptPathSet = opts.scriptPath != null;
     this.env = resolveEnv(this.envSource);
+    this.tlsxHeader = parseTlsxHeader(opts.tlsxHeader) ?? this.env?.tlsxHeader ?? null;
     if (!this.env) return;
     if (this.envSource.CAMADA_DISABLED === "1") return;
     this.snap = new import_core3.SnapshotClient({
@@ -182,9 +274,61 @@ var Camada = class {
   trustedProxy() {
     return this.env?.trustedProxy ?? this.snap?.config?.trusted_proxy ?? null;
   }
+  /** The client IP per the trusted-proxy config (team contract C6 v3). No socket at all, or a
+   *  unix-socket listener (nginx/Passenger in front, where Node never has a peer): core's no-peer
+   *  X-Forwarded-For walk, which trusts the local proxy. A TCP socket with no readable peer (the
+   *  client reset the connection before camada ran, e.g. behind an async middleware) is
+   *  unidentifiable: the walk would believe whatever the client wrote. So: null, the stance every
+   *  ip-bound feature already takes (no ip rules, no challenge). */
+  clientIp(req) {
+    const peer = req.socket?.remoteAddress;
+    if (!peer && req.socket && !onUnixListener(req.socket)) return null;
+    return (0, import_core3.resolveClientIp)(peer ?? null, req.headers["x-forwarded-for"], this.trustedProxy());
+  }
+  /** The TLS fingerprint Cloudflare (a Transform Rule) put in the opt-in header, or null. Trusted only
+   *  in `cidrs` mode and only when the socket peer itself is a NON-loopback address core's cidrs walk
+   *  trusts, i.e. Cloudflare connects to the app directly. A loopback peer (a local reverse proxy or
+   *  cloudflared) is never trusted and X-Forwarded-For is never consulted, so the header is not read
+   *  and tlsx conditions fail open. Trust is core's isTrustedPeer, the same first-hop test the cidrs
+   *  walk uses. No readable peer (unix listener included) -> null, since core's no-peer walk would
+   *  trust everyone. */
+  tlsxOf(req) {
+    const header = this.tlsxHeader;
+    if (!header) return null;
+    const v = headerReader(req)(header);
+    if (v == null || v.length > 128 || !TLSX_RE.test(v)) return null;
+    const cfg = this.trustedProxy();
+    const peer = req.socket?.remoteAddress;
+    if (cfg?.mode !== "cidrs" || !peer) return null;
+    if (isLoopbackPeer(peer)) return null;
+    return (0, import_core3.isTrustedPeer)(peer, cfg) ? v : null;
+  }
+  /** Where the challenge form posts: under the mount prefix, so it reaches camada, unless the
+   *  path was configured explicitly. */
+  challengeAction(req) {
+    return this.challengePathSet ? this.challengePath : (req.camadaPrefix ?? mountPrefix(req)) + this.challengePath;
+  }
   beaconEnabled() {
     return this.snap?.config?.beacon !== false;
   }
+  /** Queues a row. With CAMADA_SERVERLESS=1 it also starts the POST now: the platform freezes the
+   *  process once the response is out, so the 15 s interval would never run. Never throws. */
+  enqueue(row, req) {
+    const q = this.queue;
+    q.push(row);
+    if (!this.env?.serverless) return;
+    if (req?.camadaOpen) return;
+    this.flushFor(req);
+  }
+  /** Serverless: start the POST now and hand it to waitUntil. Never throws. */
+  flushFor(req) {
+    const q = this.queue;
+    (0, import_core3.guarded)(() => {
+      const tracks = req?.camadaTracks ?? [];
+      const p = Promise.allSettled(tracks).then(() => q.flush()).then(() => q.size > 0 ? q.flush() : void 0);
+      this.waitUntil?.(p);
+    }, void 0);
+  }
   /** True when camada fully handled the request. Synchronous; never throws. */
   handle(req, res) {
     return (0, import_core3.guarded)(() => this.handleInner(req, res), false);
@@ -192,15 +336,13 @@ var Camada = class {
   handleInner(req, res) {
     if (this.disabled || !this.snap || !this.queue || !this.env) return false;
     const t0 = Date.now();
-    this.snap.ensureFresh();
-    const rawUrl = req.url || "/";
-    const qi = rawUrl.indexOf("?");
-    const path = qi === -1 ? rawUrl : rawUrl.slice(0, qi);
-    const query = qi === -1 ? "" : rawUrl.slice(qi);
-    const ip = (0, import_core3.resolveClientIp)(req.socket?.remoteAddress, req.headers["x-forwarded-for"], this.trustedProxy());
-    const v = this.snap.verdict({ ip, path, ua: req.headers["user-agent"], header: headerReader(req) });
+    this.snap.ensureFresh(this.env.serverless ? this.waitUntil : void 0);
+    const { path, query } = pathAndQuery(req);
+    const ip = this.clientIp(req);
+    req.camadaPrefix = mountPrefix(req);
+    const v = this.snap.verdict({ ip, path, ua: req.headers["user-agent"], header: headerReader(req), tlsx: this.tlsxOf(req) });
     if (v.block) {
-      const headers = { "x-block-reason": v.reason ?? "", "x-block-version": v.version ?? "", "content-type": "text/plain" };
+      const headers = { "x-block-reason": v.reason ?? "", "x-block-version": v.version ?? "", "content-type": "text/plain", "cache-control": "no-store" };
       if (v.rule) headers["x-block-rule"] = v.rule;
       res.writeHead(403, headers);
       res.end("Forbidden");
@@ -208,73 +350,122 @@ var Camada = class {
       ev.st = 403;
       ev.blk = v.reason;
       if (v.rule) ev.rl = v.rule;
-      this.queue.push(ev);
+      this.enqueue(ev);
       return true;
     }
     if (this.challengeOn && this.kit && ip) {
-      if (req.method === "POST" && path === this.challengePath) {
+      if (req.method === "POST" && atEndpoint(req, path, this.challengePath)) {
         this.verifyChallenge(req, res, ip);
         return true;
       }
       if (v.challenge && !this.challengePassed(req, ip)) {
-        this.serveChallengeInner(req, res, ip, path + query);
-        return true;
+        if (isPage(req)) {
+          this.serveChallengeInner(req, res, ip, path + query);
+          return true;
+        }
+        req.camadaSignalled = true;
       }
     }
     if (this.beaconEnabled()) {
-      if (req.method === "GET" && path === this.scriptPath) {
+      if (req.method === "GET" && atEndpoint(req, path, this.scriptPath)) {
         res.writeHead(200, { "content-type": "application/javascript", "cache-control": "public, max-age=3600" });
         res.end(import_iife_string.default);
         return true;
       }
-      if (req.method === "POST" && path === this.fpPath) {
+      if (req.method === "POST" && atEndpoint(req, path, this.fpPath)) {
         this.relayBeacon(req, res, ip);
         return true;
       }
     }
+    const { rid, sid, ns: newSession } = this.begin(req, res, ip, t0, v.warn ? v.rule : void 0);
+    if (req.camadaSignalled) signal(res);
+    const cfg = this.snap.config;
+    const excluded = (cfg?.exclude || []).some((x) => path.startsWith(x));
+    if (req.camadaSignalled || !excluded && Math.random() < (cfg?.sample ?? 1)) {
+      this.hookCapture(req, res, path, query, ip, { rid, sid, newSession, t0 });
+    }
+    return false;
+  }
+  /** Mints the request's rid and session (setting the cookie on a first visit), records them on
+   *  `req.camada` and sets `x-rid`. handle() and serveChallenge() (when handle() did not run) share it. */
+  begin(req, res, ip, t0, wrn) {
     const rid = (0, import_node_crypto2.randomUUID)();
     let sid = cookieValue(req.headers.cookie || "", SESSION_COOKIE);
-    const newSession = !sid;
+    const ns = !sid;
     if (!sid) {
       sid = (0, import_node_crypto2.randomUUID)();
       const https = req.socket.encrypted || req.headers["x-forwarded-proto"] === "https";
       keepSessionCookie(res, `${SESSION_COOKIE}=${sid}; Path=/; Max-Age=2592000; HttpOnly; SameSite=Lax${https ? "; Secure" : ""}`);
     }
-    req.camada = { rid, ip, sid };
     res.setHeader("x-rid", rid);
-    const cfg = this.snap.config;
-    const excluded = (cfg?.exclude || []).some((x) => path.startsWith(x));
-    if (!excluded && Math.random() < (cfg?.sample ?? 1)) {
-      let shipped = false;
-      const ship = () => (0, import_core3.guarded)(() => {
-        if (shipped || req.camadaChallenged) return;
-        shipped = true;
-        const ev = this.buildEvent(req, path, query, ip, { rid, sid, newSession });
-        ev.ts = t0;
-        ev.st = res.statusCode;
-        ev.dur = Date.now() - t0;
-        if (req.route?.path) ev.rt = String(req.route.path);
-        if (v.warn && v.rule) ev.wrn = v.rule;
-        this.queue.push(ev);
-      }, void 0);
-      res.once("finish", ship);
-      res.once("close", ship);
-    }
-    return false;
+    return req.camada = { rid, ip, sid, ns, t0, wrn };
+  }
+  /** Installs the response-finish hook that ships the request's normal capture event. */
+  hookCapture(req, res, path, query, ip, o) {
+    let shipped = false;
+    req.camadaOpen = true;
+    const ship = () => (0, import_core3.guarded)(() => {
+      req.camadaOpen = false;
+      if (shipped) return;
+      shipped = true;
+      if (req.camadaChallenged) {
+        if (this.env?.serverless) this.flushFor(req);
+        return;
+      }
+      const ev = this.buildEvent(req, path, query, ip, o);
+      ev.ts = o.t0;
+      ev.st = res.statusCode;
+      ev.dur = Date.now() - o.t0;
+      if (req.route?.path) ev.rt = String(req.route.path);
+      if (req.camada?.wrn) ev.wrn = req.camada.wrn;
+      if (req.camadaSignalled) ev.chs = 1;
+      this.enqueue(ev, req);
+    }, void 0);
+    res.once("finish", ship);
+    res.once("close", ship);
   }
   buildEvent(req, path, query, ip, o) {
     const raw = req.rawHeaders || [];
     const headers = [];
     for (let i = 0; i + 1 < raw.length; i += 2) headers.push([raw[i], raw[i + 1]]);
-    return (0, import_core3.buildWireEvent)(
+    const ev = (0, import_core3.buildWireEvent)(
       { method: req.method || "GET", host: req.headers.host || "", path, query, headers, ip, httpVersion: req.httpVersion },
       { tap: import_core3.TAP_NODE, rid: o.rid, sid: o.sid, newSession: o.newSession }
     );
+    const tlsx = this.tlsxOf(req);
+    if (tlsx) ev.tlsx = tlsx;
+    return ev;
   }
   /** Reads the beacon POST (≤32 KB), answers 204 immediately, and queues the beacon as a `sig: 1`
    *  row with the trusted-proxy-resolved client IP: it rides the next event batch, so the analyst
-   *  sees one request per flush instead of one per page view. Junk bodies are dropped, never shipped. */
+   *  sees one request per flush instead of one per page view. Junk bodies are dropped, never shipped.
+   *  A body parser mounted before camada (express.json(), always on Nest) has already drained the
+   *  stream: its `req.body` is used instead, and the request is answered either way. */
   relayBeacon(req, res, ip) {
+    const accept = (parsed) => {
+      res.writeHead(204, { "cache-control": "no-store" });
+      res.end();
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || Buffer.isBuffer(parsed)) return;
+      const row = { ...parsed, sig: 1, ip, tap: import_core3.TAP_NODE, rts: Date.now() };
+      for (const k of import_core3.REQUEST_ROW_KEYS) delete row[k];
+      this.enqueue(row);
+    };
+    const fromText = (text) => {
+      try {
+        return JSON.parse(text);
+      } catch {
+        return null;
+      }
+    };
+    if (req.readableEnded) {
+      const b = parsedBody(req);
+      if ((typeof b === "string" ? b : b ? JSON.stringify(b) : "").length > FP_MAX) {
+        res.writeHead(413).end();
+        return;
+      }
+      accept(typeof b === "string" ? fromText(b) : b);
+      return;
+    }
     const chunks = [];
     let size = 0, dead = false;
     req.on("data", (c) => {
@@ -289,16 +480,7 @@ var Camada = class {
     });
     req.on("end", () => (0, import_core3.guarded)(() => {
       if (dead) return;
-      res.writeHead(204, { "cache-control": "no-store" });
-      res.end();
-      let parsed;
-      try {
-        parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
-      } catch {
-        return;
-      }
-      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return;
-      this.queue.push({ ...parsed, sig: 1, ip, tap: import_core3.TAP_NODE });
+      accept(fromText(Buffer.concat(chunks).toString("utf8")));
     }, void 0));
     req.on("error", () => {
       try {
@@ -310,15 +492,11 @@ var Camada = class {
   challengePassed(req, ip) {
     return !!this.kit?.tokenValid(ip, Date.now(), cookieValue(req.headers.cookie || "", import_core3.CHALLENGE_COOKIE));
   }
-  /** 403 + the proof-of-work page (HTML navigations) or 403 JSON (everything else), plus the
+  /** 403 + the proof-of-work page (HTML navigations only), plus the
    *  `blk: "challenge"` event — a served challenge is reported like a block (contract §D2). */
   serveChallengeInner(req, res, ip, target) {
     const to = (0, import_core3.safeReturnTo)(target);
-    if ((0, import_core3.wantsHtml)(req.headers.accept ?? null, req.headers["sec-fetch-dest"] ?? null)) {
-      writeChallengePage(res, (0, import_core3.challengePage)({ nonce: this.kit.nonce(ip, Date.now()), action: this.challengePath, to }));
-    } else {
-      writeChallengeJson(res);
-    }
+    writeChallengePage(res, { nonce: this.kit.nonce(ip, Date.now()), action: this.challengeAction(req), to });
     (0, import_core3.guarded)(() => {
       const qi = target.indexOf("?");
       const ev = this.buildEvent(
@@ -330,7 +508,7 @@ var Camada = class {
       );
       ev.st = 403;
       ev.blk = "challenge";
-      this.queue.push(ev);
+      this.enqueue(ev);
     }, void 0);
   }
   /** The request's existing session, so challenge rows join the session that produced them. */
@@ -340,12 +518,11 @@ var Camada = class {
   /** POST from the challenge page: validate the nonce and the proof of work, set `_cch`, 302
    *  back to the (sanitised, same-site) original URL, and ship `{ st: 200, ch: 1 }`. */
   verifyChallenge(req, res, ip) {
-    readBody(req, (body) => (0, import_core3.guarded)(() => {
-      const form = (0, import_core3.parseFormBody)(body);
+    readForm(req, (form) => (0, import_core3.guarded)(() => {
       const to = (0, import_core3.safeReturnTo)(form.to);
       const now = Date.now();
       if (!this.kit.verify(ip, now, form.nonce, form.solution)) {
-        writeChallengePage(res, (0, import_core3.challengePage)({ nonce: this.kit.nonce(ip, now), action: this.challengePath, to }));
+        writeChallengePage(res, { nonce: this.kit.nonce(ip, now), action: this.challengeAction(req), to });
         return;
       }
       res.writeHead(302, {
@@ -354,10 +531,10 @@ var Camada = class {
         "cache-control": "no-store"
       });
       res.end();
-      const ev = this.buildEvent(req, this.challengePath, "", ip, { rid: (0, import_node_crypto2.randomUUID)(), sid: this.sessionOf(req), newSession: false });
+      const ev = this.buildEvent(req, this.challengeAction(req), "", ip, { rid: (0, import_node_crypto2.randomUUID)(), sid: this.sessionOf(req), newSession: false });
       ev.st = 200;
       ev.ch = 1;
-      this.queue.push(ev);
+      this.enqueue(ev);
     }, void 0));
   }
   /**
@@ -389,28 +566,38 @@ var Camada = class {
   }
   shipUpgrade(req, t0) {
     if (this.disabled || !this.queue) return;
-    const rawUrl = req.url || "/";
-    const qi = rawUrl.indexOf("?");
-    const path = qi === -1 ? rawUrl : rawUrl.slice(0, qi);
+    const { path, query } = pathAndQuery(req);
     const cfg = this.snap?.config;
     if ((cfg?.exclude || []).some((x) => path.startsWith(x)) || Math.random() >= (cfg?.sample ?? 1)) return;
-    const ip = (0, import_core3.resolveClientIp)(req.socket?.remoteAddress, req.headers["x-forwarded-for"], this.trustedProxy());
-    const ev = this.buildEvent(req, path, qi === -1 ? "" : rawUrl.slice(qi), ip, { rid: (0, import_node_crypto2.randomUUID)(), sid: this.sessionOf(req), newSession: false });
+    const ip = this.clientIp(req);
+    const ev = this.buildEvent(req, path, query, ip, { rid: (0, import_node_crypto2.randomUUID)(), sid: this.sessionOf(req), newSession: false });
     ev.ts = t0;
     ev.st = 101;
     ev.dur = Date.now() - t0;
-    this.queue.push(ev);
+    this.enqueue(ev);
   }
   /** Serve the challenge for this request on demand — for a route the app wants to gate itself
    *  (the example's /challenge-me). Returns false when the client already holds a valid `_cch`,
-   *  so the caller renders its own page. */
+   *  so the caller renders its own page. A non-HTML request is never challenged: it gets the
+   *  `x-camada-challenge: 1` header and a `chs: 1` event, and false, so the app answers. */
   serveChallenge(req, res) {
     return (0, import_core3.guarded)(() => {
       if (this.disabled || !this.kit || !this.queue) return false;
-      const ip = (0, import_core3.resolveClientIp)(req.socket?.remoteAddress, req.headers["x-forwarded-for"], this.trustedProxy());
+      const ip = this.clientIp(req);
       if (!ip || this.challengePassed(req, ip)) return false;
-      req.camadaChallenged = true;
-      this.serveChallengeInner(req, res, ip, req.url || "/");
+      const r = req;
+      const { path, query } = pathAndQuery(r);
+      if (!isPage(r)) {
+        if (!r.camadaSignalled) signal(res);
+        r.camadaSignalled = true;
+        if (r.camadaOpen === void 0) {
+          const c = r.camada ?? this.begin(r, res, ip, Date.now());
+          this.hookCapture(r, res, path, query, ip, { rid: c.rid, sid: c.sid, newSession: c.ns, t0: c.t0 });
+        }
+        return false;
+      }
+      r.camadaChallenged = true;
+      this.serveChallengeInner(req, res, ip, path + query);
       return true;
     }, false);
   }
@@ -418,7 +605,9 @@ var Camada = class {
   scriptTag(req) {
     if (this.disabled || !this.beaconEnabled()) return "";
     const rid = req.camada?.rid;
-    return `<script src="${this.scriptPath}${rid ? `?r=${rid}` : ""}" async></script>`;
+    const r = req;
+    const src = this.scriptPathSet ? this.scriptPath : (r.camadaPrefix ?? mountPrefix(r)) + this.scriptPath;
+    return `<script src="${src}${rid ? `?r=${rid}` : ""}" async></script>`;
   }
   /** App-context outcome events (login failed, signup, …). The identifier is HMAC-hashed
    *  in-process; the raw value never reaches the queue. */
@@ -426,10 +615,12 @@ var Camada = class {
     (0, import_core3.guarded)(() => {
       if (this.disabled || !this.queue || !this.env) return;
       const ctx = req.camada;
-      void (async () => {
+      const r = req;
+      const row = (async () => {
         const uid = data?.user ? await (0, import_core3.hashUserId)(data.user, this.env.ingestToken, (globalThis.crypto ?? import_node_crypto2.webcrypto).subtle) : null;
-        this.queue.push({ tap: import_core3.TAP_NODE, et: event, uid, rid: ctx?.rid ?? null, sid: ctx?.sid ?? null, ip: ctx?.ip ?? null, ts: Date.now() });
+        this.enqueue({ tap: import_core3.TAP_NODE, et: event, uid, rid: ctx?.rid ?? null, sid: ctx?.sid ?? null, ip: ctx?.ip ?? null, ts: Date.now() }, r);
       })().catch(import_core3.logRateLimited);
+      if (r.camadaOpen) (r.camadaTracks ??= []).push(row);
     }, void 0);
   }
   /** Express/Connect middleware (also what NestJS on the default platform consumes). */
@@ -438,9 +629,11 @@ var Camada = class {
       if (!this.handle(req, res)) next();
     };
   }
+  /** Stops polling and the event queue. The promise settles once rows still queued behind a drain
+   *  in flight or a 429 hold are sent (or counted dropped); it never rejects. */
   stop() {
     this.snap?.stop();
-    this.queue?.stop();
+    return this.queue?.stop() ?? Promise.resolve();
   }
 };
 function createCamada(opts = {}) {