@camada/node 0.3.0 → 0.3.2

package/README.md

@@ -23,8 +23,16 @@ CAMADA_INGEST_URL=http://localhost:8787        # dev only; defaults to productio
 **Express / Connect**
 ```js
 import camada from '@camada/node';
-app.use(camada.express());
+app.use(camada.express());   // before express.json() / urlencoded() and before helmet
 ```
+Mount camada first. It still works behind body parsers (it uses the `req.body` they leave for
+its challenge and beacon POSTs) and behind helmet (the challenge page replaces any inherited
+`Content-Security-Policy` with its own), but first is cheapest: a blocked request never pays for
+parsing. Under a prefix (`app.use('/api', camada.express())`) rules and events see the full path
+(`/api/…`), and camada's own endpoints answer under the prefix (`/api/_cam/b.js`, `/api/_cam/fp`,
+`/api/__camada/challenge`). The beacon tag (`scriptTag()`) and the challenge form point under the
+prefix too, unless you set `scriptPath` or `challengePath` yourself: an explicit path is used
+exactly as given. The beacon posts next to its script, so `fpPath` can stay as it is.
 
 **Fastify**
 ```js
@@ -37,12 +45,18 @@ await app.register(camadaFastify);
 import { CamadaModule } from '@camada/node/nest';
 @Module({ imports: [CamadaModule.forRoot()] })   // Nest ≤10: CamadaModule.forRoot({ routes: '*' })
 ```
+Nest registers its body parsers before module middleware; camada reads what they parsed, so the
+default `bodyParser: true` is fine. Tested on Nest 11. Nest 10 (`routes: '*'`) is checked through
+the Express 4 wildcard mount it registers, not against Nest 10 itself.
 
 **Koa**
 ```js
 import { camadaKoa } from '@camada/node/koa';
-app.use(camadaKoa());
+app.use(camadaKoa());   // before @koa/bodyparser
 ```
+Register it first. Behind `@koa/bodyparser` or `koa-bodyparser` it reads the form and beacon from
+`ctx.request.body`. Under `koa-mount` it works like an Express prefix mount: rules and events see the
+full path, and its own endpoints answer under the prefix.
 
 ## What it does per request
 
@@ -50,6 +64,9 @@ app.use(camadaKoa());
    poll and event batch carries `x-camada-sdk: @camada/node/<version>`.
 2. Resolves the client IP per your tenant's trusted-proxy config — raw `X-Forwarded-For` is
    never trusted without it (`CAMADA_TRUSTED_PROXY=hops:1|cidrs:…|vercel` overrides locally).
+   On a unix-socket listener (nginx or Passenger in front) Node has no peer address, so the walk
+   runs without one and trusts the local proxy that owns the socket. A TCP request whose peer is
+   already gone (the client reset the connection) gets no IP: no ip rules, no challenge.
 3. Runs your ordered custom rules (see below), then the allow, block and challenge lists.
    Blocked → `403` with `x-block-reason` before your app; the event still ships, with
    `st: 403` and `blk: <reason>` (ip4|ip6|path|rule) so the analyst counts SDK blocks apart
@@ -145,10 +162,23 @@ handshake your library then rejects still ships `st: 101`.
 
 - `CAMADA_DISABLED=1` — kill switch, checked per request.
 - `CAMADA_SERVERLESS=1` — lazy snapshot refresh (no interval timer); cold invocations fail
-  open and catch up asynchronously.
+  open and catch up asynchronously. Each request's event (and every `track()` row) is POSTed as
+  the response finishes instead of waiting for the 15 s batch timer, which a frozen function
+  never runs. Pass the platform's `waitUntil` so the invocation stays alive for that POST:
+  ```js
+  import { waitUntil } from '@vercel/functions';
+  const camada = createCamada({ waitUntil });   // also holds the lazy snapshot refresh open
+  ```
+  Where the platform has no `waitUntil`, the POST starts before the response completes but can
+  still be frozen mid-flight; use a fetch adapter (`@camada/hono`, `@camada/next`) there.
+- The challenge page sends its own `Content-Security-Policy` allowing only its inline script and
+  style by `sha256` hash, and drops any `Content-Security-Policy(-Report-Only)` set before it.
 - Enforcement scope at this position: IP, path, user-agent and request-header conditions. ASN,
   country and TLS-fingerprint conditions can't be evaluated in-app and fail open (a rule that
   needs one never matches here; run `@camada/hono` on Cloudflare Workers for those).
+- `await camada.stop()` in your own graceful shutdown stops polling and the event queue. It
+  returns a promise that settles once queued rows (a drain in flight, or rows held by an ingest
+  429) are sent, or counted as dropped if the send fails; it never rejects.
 - Memory: ~5 MB per loaded snapshot.
 
 ## Develop

package/dist/{camada-Dh_9D6Sx.d.cts → camada-CFmJTruP.d.cts}

@@ -22,6 +22,9 @@ interface CamadaOptions {
     challenge?: boolean;
     challengePath?: string;
     snapshotVersion?: SnapshotVersion;
+    /** With CAMADA_SERVERLESS=1: handed every per-request event flush and snapshot refresh, so the
+     *  platform keeps the invocation alive until they finish (e.g. `waitUntil` from `@vercel/functions`). */
+    waitUntil?: (p: Promise<unknown>) => void;
 }
 declare class Camada {
     readonly env: ResolvedEnv | null;
@@ -32,19 +35,39 @@ declare class Camada {
     private readonly fpPath;
     private readonly challengeOn;
     private readonly challengePath;
+    private readonly challengePathSet;
+    private readonly scriptPathSet;
     private readonly kit;
     private readonly envSource;
+    private readonly waitUntil?;
     constructor(opts?: CamadaOptions);
     get disabled(): boolean;
     private trustedProxy;
+    /** 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). */
+    private clientIp;
+    /** Where the challenge form posts: under the mount prefix, so it reaches camada, unless the
+     *  path was configured explicitly. */
+    private challengeAction;
     private beaconEnabled;
+    /** 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. */
+    private enqueue;
+    /** Serverless: start the POST now and hand it to waitUntil. Never throws. */
+    private flushFor;
     /** True when camada fully handled the request. Synchronous; never throws. */
     handle(req: IncomingMessage, res: ServerResponse): boolean;
     private handleInner;
     private buildEvent;
     /** 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. */
     private relayBeacon;
     private challengePassed;
     /** 403 + the proof-of-work page (HTML navigations) or 403 JSON (everything else), plus the
@@ -79,7 +102,9 @@ declare class Camada {
     }): void;
     /** Express/Connect middleware (also what NestJS on the default platform consumes). */
     express(): (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
-    stop(): void;
+    /** 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(): Promise<void>;
 }
 declare function createCamada(opts?: CamadaOptions): Camada;
 

package/dist/{camada-Dh_9D6Sx.d.ts → camada-CFmJTruP.d.ts}

@@ -22,6 +22,9 @@ interface CamadaOptions {
     challenge?: boolean;
     challengePath?: string;
     snapshotVersion?: SnapshotVersion;
+    /** With CAMADA_SERVERLESS=1: handed every per-request event flush and snapshot refresh, so the
+     *  platform keeps the invocation alive until they finish (e.g. `waitUntil` from `@vercel/functions`). */
+    waitUntil?: (p: Promise<unknown>) => void;
 }
 declare class Camada {
     readonly env: ResolvedEnv | null;
@@ -32,19 +35,39 @@ declare class Camada {
     private readonly fpPath;
     private readonly challengeOn;
     private readonly challengePath;
+    private readonly challengePathSet;
+    private readonly scriptPathSet;
     private readonly kit;
     private readonly envSource;
+    private readonly waitUntil?;
     constructor(opts?: CamadaOptions);
     get disabled(): boolean;
     private trustedProxy;
+    /** 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). */
+    private clientIp;
+    /** Where the challenge form posts: under the mount prefix, so it reaches camada, unless the
+     *  path was configured explicitly. */
+    private challengeAction;
     private beaconEnabled;
+    /** 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. */
+    private enqueue;
+    /** Serverless: start the POST now and hand it to waitUntil. Never throws. */
+    private flushFor;
     /** True when camada fully handled the request. Synchronous; never throws. */
     handle(req: IncomingMessage, res: ServerResponse): boolean;
     private handleInner;
     private buildEvent;
     /** 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. */
     private relayBeacon;
     private challengePassed;
     /** 403 + the proof-of-work page (HTML navigations) or 403 JSON (everything else), plus the
@@ -79,7 +102,9 @@ declare class Camada {
     }): void;
     /** Express/Connect middleware (also what NestJS on the default platform consumes). */
     express(): (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
-    stop(): void;
+    /** 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(): Promise<void>;
 }
 declare function createCamada(opts?: CamadaOptions): Camada;
 

package/dist/{chunk-CR3UHMBJ.js → chunk-V3UWO5OT.js}

@@ -19,11 +19,9 @@ import {
   hashUserId,
   guarded,
   logRateLimited,
-  challengePage,
   challengeCookie,
   safeReturnTo,
   wantsHtml,
-  parseFormBody,
   CHALLENGE_COOKIE,
   TAP_NODE
 } from "@camada/core";
@@ -50,7 +48,7 @@ function resolveEnv(env = process.env) {
 
 // src/challenge.ts
 import { createHash, createHmac } from "crypto";
-import { createChallenge } from "@camada/core";
+import { createChallenge, challengePage, challengePageCsp, parseFormBody } from "@camada/core";
 var CHALLENGE_PATH = "/__camada/challenge";
 var BODY_MAX = 4 * 1024;
 function nodeChallengeKit(secret) {
@@ -76,10 +74,41 @@ function readBody(req, done) {
   req.on("end", () => done(dead ? "" : Buffer.concat(chunks).toString("utf8")));
   req.on("error", () => done(""));
 }
+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(parseFormBody(body)));
+    return;
+  }
+  const b = parsedBody(req);
+  if (typeof b === "string") {
+    done(b.length > BODY_MAX ? {} : 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);
+}
 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);
+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": challengePageCsp(o.bits)
+  });
+  res.end(challengePage(o));
 }
 function writeChallengeJson(res) {
   res.writeHead(403, { "content-type": "application/json", "cache-control": "no-store", "x-camada-challenge": "1" });
@@ -87,7 +116,7 @@ function writeChallengeJson(res) {
 }
 
 // package.json
-var version = "0.3.0";
+var version = "0.3.2";
 var name = "@camada/node";
 
 // src/version.ts
@@ -103,6 +132,28 @@ 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) };
+};
+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 + "=");
@@ -131,15 +182,22 @@ var Camada = class {
   fpPath;
   challengeOn;
   challengePath;
+  challengePathSet;
+  // configured explicitly: used as given, never prefixed
+  scriptPathSet;
   kit = null;
   envSource;
+  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);
     if (!this.env) return;
     if (this.envSource.CAMADA_DISABLED === "1") return;
@@ -163,9 +221,43 @@ 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 resolveClientIp(peer ?? null, req.headers["x-forwarded-for"], this.trustedProxy());
+  }
+  /** 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;
+    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 guarded(() => this.handleInner(req, res), false);
@@ -173,15 +265,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 = resolveClientIp(req.socket?.remoteAddress, req.headers["x-forwarded-for"], this.trustedProxy());
+    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) });
     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");
@@ -189,11 +279,11 @@ 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;
       }
@@ -203,12 +293,12 @@ var Camada = class {
       }
     }
     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(iife);
         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;
       }
@@ -227,16 +317,22 @@ var Camada = class {
     const excluded = (cfg?.exclude || []).some((x) => path.startsWith(x));
     if (!excluded && Math.random() < (cfg?.sample ?? 1)) {
       let shipped = false;
+      req.camadaOpen = true;
       const ship = () => guarded(() => {
-        if (shipped || req.camadaChallenged) return;
+        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, { 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);
+        this.enqueue(ev, req);
       }, void 0);
       res.once("finish", ship);
       res.once("close", ship);
@@ -254,8 +350,32 @@ var Camada = class {
   }
   /** 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;
+      this.enqueue({ ...parsed, sig: 1, ip, tap: TAP_NODE });
+    };
+    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) => {
@@ -270,16 +390,7 @@ var Camada = class {
     });
     req.on("end", () => 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: TAP_NODE });
+      accept(fromText(Buffer.concat(chunks).toString("utf8")));
     }, void 0));
     req.on("error", () => {
       try {
@@ -296,7 +407,7 @@ var Camada = class {
   serveChallengeInner(req, res, ip, target) {
     const to = safeReturnTo(target);
     if (wantsHtml(req.headers.accept ?? null, req.headers["sec-fetch-dest"] ?? null)) {
-      writeChallengePage(res, challengePage({ nonce: this.kit.nonce(ip, Date.now()), action: this.challengePath, to }));
+      writeChallengePage(res, { nonce: this.kit.nonce(ip, Date.now()), action: this.challengeAction(req), to });
     } else {
       writeChallengeJson(res);
     }
@@ -311,7 +422,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. */
@@ -321,12 +432,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) => guarded(() => {
-      const form = parseFormBody(body);
+    readForm(req, (form) => guarded(() => {
       const to = safeReturnTo(form.to);
       const now = Date.now();
       if (!this.kit.verify(ip, now, form.nonce, form.solution)) {
-        writeChallengePage(res, 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, {
@@ -335,10 +445,10 @@ var Camada = class {
         "cache-control": "no-store"
       });
       res.end();
-      const ev = this.buildEvent(req, this.challengePath, "", ip, { rid: randomUUID(), sid: this.sessionOf(req), newSession: false });
+      const ev = this.buildEvent(req, this.challengeAction(req), "", ip, { rid: randomUUID(), sid: this.sessionOf(req), newSession: false });
       ev.st = 200;
       ev.ch = 1;
-      this.queue.push(ev);
+      this.enqueue(ev);
     }, void 0));
   }
   /**
@@ -370,17 +480,15 @@ 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 = resolveClientIp(req.socket?.remoteAddress, req.headers["x-forwarded-for"], this.trustedProxy());
-    const ev = this.buildEvent(req, path, qi === -1 ? "" : rawUrl.slice(qi), ip, { rid: randomUUID(), sid: this.sessionOf(req), newSession: false });
+    const ip = this.clientIp(req);
+    const ev = this.buildEvent(req, path, query, ip, { rid: 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`,
@@ -388,10 +496,11 @@ var Camada = class {
   serveChallenge(req, res) {
     return guarded(() => {
       if (this.disabled || !this.kit || !this.queue) return false;
-      const ip = 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 { path, query } = pathAndQuery(req);
+      this.serveChallengeInner(req, res, ip, path + query);
       return true;
     }, false);
   }
@@ -399,7 +508,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. */
@@ -407,10 +518,12 @@ var Camada = class {
     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 hashUserId(data.user, this.env.ingestToken, (globalThis.crypto ?? webcrypto).subtle) : null;
-        this.queue.push({ tap: TAP_NODE, et: event, uid, rid: ctx?.rid ?? null, sid: ctx?.sid ?? null, ip: ctx?.ip ?? null, ts: Date.now() });
+        this.enqueue({ tap: TAP_NODE, et: event, uid, rid: ctx?.rid ?? null, sid: ctx?.sid ?? null, ip: ctx?.ip ?? null, ts: Date.now() }, r);
       })().catch(logRateLimited);
+      if (r.camadaOpen) (r.camadaTracks ??= []).push(row);
     }, void 0);
   }
   /** Express/Connect middleware (also what NestJS on the default platform consumes). */
@@ -419,9 +532,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 = {}) {
@@ -462,4 +577,4 @@ export {
   configure,
   index_default
 };
-//# sourceMappingURL=chunk-CR3UHMBJ.js.map
+//# sourceMappingURL=chunk-V3UWO5OT.js.map