@camada/node 0.3.1 → 0.4.0

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
@@ -72,7 +89,7 @@ carries one of four actions:
 |---|---|---|
 | `skip` | passes the request | nothing |
 | `block` | `403` before your app | `blk: "rule"`, `rl: "<rule id>"` |
-| `challenge` | serves the proof-of-work page (`challenge: false` opts out) | `blk: "challenge"` |
+| `challenge` | serves the proof-of-work page to page loads (`challenge: false` opts out). A non-HTML request (fetch/XHR/API) is not challenged: it reaches your app with `x-camada-challenge: 1` on the response | page: `blk: "challenge"`; non-HTML: its normal event plus `chs: 1` (never sampled out or excluded) |
 | `warn` | passes the request and marks it for the analyst | `wrn: "<rule id>"` |
 
 A skip rule also carries a *record matches* flag, which only the analyst reads: a recorded skip
@@ -123,6 +140,40 @@ fire on your app's own truth instead of path heuristics:
 | `payment_failed` / `payment_succeeded` | a payment authorisation settled |
 | `coupon_failed` | a promo/voucher code was rejected |
 
+## TLS fingerprint behind Cloudflare
+
+Node has no TLS handshake to read, but Cloudflare does. Set `CAMADA_TLSX_HEADER=x-camada-tlsx`
+(or `createCamada({ tlsxHeader: 'x-camada-tlsx' })`) and add a Transform Rule that sets it:
+*Rules > Transform Rules > Modify Request Header*, "Set dynamic", header `x-camada-tlsx`, value
+`cf.tls_client_extensions_sha1`, on every request. The rule is required and must **set**
+(overwrite) the header: without it a client-sent `x-camada-tlsx` passes through Cloudflare
+untouched. The value feeds the same matcher as `@camada/hono`'s `request.cf.tlsClientExtensionsSha1`:
+the snapshot's `tls` entries block with `x-block-reason: tls`, and `tlsx is` / `is_in` rule
+conditions apply.
+
+This needs Cloudflare to connect to the app directly. The header is believed only in `cidrs` mode,
+when the socket peer is a non-loopback address inside Cloudflare's ranges, because anyone else can
+write it:
+
+```
+CAMADA_TRUSTED_PROXY=cidrs:173.245.48.0/20,103.21.244.0/22,…   # Cloudflare's published ranges
+CAMADA_TLSX_HEADER=x-camada-tlsx
+```
+
+Every range in `CAMADA_TRUSTED_PROXY=cidrs:…` is trusted to write the header, the same trust it gets
+for `X-Forwarded-For`, so list only Cloudflare's ranges there. A non-Cloudflare proxy range (a docker
+bridge, an internal load balancer) would let anyone who reaches that proxy set the fingerprint.
+
+Behind a local reverse proxy (nginx or Caddy on loopback) or a cloudflared tunnel the peer is
+loopback, so the header is not read and `tlsx` conditions fail open; `X-Forwarded-For` is never
+consulted. The same holds in `none`, `hops` or `vercel` mode, from any other peer, with no readable
+peer (unix listeners included), or with a malformed value (over 128 characters, outside
+`[A-Za-z0-9+/=_-]`, or a repeated header). The Transform Rule must overwrite the header on every
+request: on a request it skips, a client-sent value passes through. The same trusted value is sent
+to camada as `tlsx` on request events (pass, block, challenge and upgrade rows); node never adds it
+to `track()` rows or the beacon relay, and a value that failed the checks above is never sent. The
+analyst uses it to group traffic by TLS fingerprint and to recommend or block rare fingerprints.
+
 ## WebSockets
 
 Node hands an upgrade request (a WebSocket handshake) to the server's `'upgrade'` listeners,
@@ -145,10 +196,25 @@ 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).
+  country 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). TLS-fingerprint conditions
+  match only with the opt-in `CAMADA_TLSX_HEADER` (see "TLS fingerprint behind Cloudflare");
+  without it they fail open too.
+- `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-DuHQ4sLn.d.cts}

@@ -9,6 +9,7 @@ interface ResolvedEnv {
     snapshotUrl: string;
     serverless: boolean;
     trustedProxy: TrustedProxyConfig | null;
+    tlsxHeader: string | null;
 }
 /** Returns null (SDK stays disabled, one log line) rather than throwing on bad config. */
 declare function resolveEnv(env?: Record<string, string | undefined>): ResolvedEnv | null;
@@ -20,8 +21,12 @@ interface CamadaOptions {
     scriptPath?: string;
     fpPath?: string;
     challenge?: boolean;
+    tlsxHeader?: string;
     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,22 +37,56 @@ 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 tlsxHeader;
+    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;
+    /** 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. */
+    private tlsxOf;
+    /** 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;
+    /** 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. */
+    private begin;
+    /** Installs the response-finish hook that ships the request's normal capture event. */
+    private hookCapture;
     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
+    /** 403 + the proof-of-work page (HTML navigations only), plus the
      *  `blk: "challenge"` event — a served challenge is reported like a block (contract §D2). */
     private serveChallengeInner;
     /** The request's existing session, so challenge rows join the session that produced them. */
@@ -68,7 +107,8 @@ declare class Camada {
     private shipUpgrade;
     /** 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: IncomingMessage, res: ServerResponse): boolean;
     /** For HTML templates: the first-party beacon tag with the request's rid. */
     scriptTag(req: IncomingMessage): string;
@@ -79,7 +119,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-DuHQ4sLn.d.ts}

@@ -9,6 +9,7 @@ interface ResolvedEnv {
     snapshotUrl: string;
     serverless: boolean;
     trustedProxy: TrustedProxyConfig | null;
+    tlsxHeader: string | null;
 }
 /** Returns null (SDK stays disabled, one log line) rather than throwing on bad config. */
 declare function resolveEnv(env?: Record<string, string | undefined>): ResolvedEnv | null;
@@ -20,8 +21,12 @@ interface CamadaOptions {
     scriptPath?: string;
     fpPath?: string;
     challenge?: boolean;
+    tlsxHeader?: string;
     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,22 +37,56 @@ 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 tlsxHeader;
+    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;
+    /** 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. */
+    private tlsxOf;
+    /** 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;
+    /** 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. */
+    private begin;
+    /** Installs the response-finish hook that ships the request's normal capture event. */
+    private hookCapture;
     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
+    /** 403 + the proof-of-work page (HTML navigations only), plus the
      *  `blk: "challenge"` event — a served challenge is reported like a block (contract §D2). */
     private serveChallengeInner;
     /** The request's existing session, so challenge rows join the session that produced them. */
@@ -68,7 +107,8 @@ declare class Camada {
     private shipUpgrade;
     /** 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: IncomingMessage, res: ServerResponse): boolean;
     /** For HTML templates: the first-party beacon tag with the request's rid. */
     scriptTag(req: IncomingMessage): string;
@@ -79,7 +119,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;