@camada/node 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 camada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# @camada/node
+
+camada's backend SDK for Node: captures request metadata on response-finish (real status,
+latency, and the true wire header order no proxy position can see), enforces the tenant
+blocklist inline before your app runs, and serves the fingerprint beacon first-party at
+`/_cam/b.js` + `/_cam/fp`. Fails open by design: a camada outage or bug never 5xxes your app.
+
+Not yet on npm — consumed via `file:` dependency from a sibling checkout.
+
+## Quickstart
+
+Env (printed by camada onboarding / `npm run seed` in dev):
+
+```
+CAMADA_KEY=<ingest_token>.<snap_token>
+CAMADA_INGEST_URL=http://localhost:8787        # dev only; defaults to production ingest
+```
+
+**Express / Connect**
+```js
+import camada from '@camada/node';
+app.use(camada.express());
+```
+
+**Fastify**
+```js
+import { camadaFastify } from '@camada/node/fastify';
+await app.register(camadaFastify);
+```
+
+**NestJS** (default Express platform; on the Fastify platform register the fastify plugin instead)
+```ts
+import { CamadaModule } from '@camada/node/nest';
+@Module({ imports: [CamadaModule.forRoot()] })   // Nest ≤10: CamadaModule.forRoot({ routes: '*' })
+```
+
+**Koa**
+```js
+import { camadaKoa } from '@camada/node/koa';
+app.use(camadaKoa());
+```
+
+## What it does per request
+
+1. Refreshes the blocklist snapshot off-path (30 s poll, ETag; cold start fails open). Every
+   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).
+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
+   from your app's own 403s.
+4. Serves `/_cam/b.js` (the beacon, first-party — no third-party domain for ad-blockers or CSP
+   to break) and relays `/_cam/fp` posts to ingest with the resolved client IP.
+5. Otherwise: sets `x-rid` + the `_sfp` session cookie, and on response-finish ships one
+   batched, redacted event (Authorization/Cookie values never leave the process; credential-
+   looking query values are scrubbed; see @camada/core).
+
+## Custom rules
+
+Your Rules page holds one ordered list per project, and this SDK walks it before the allow,
+block and challenge lists. First match wins — the order *is* the precedence — and each rule
+carries one of four actions:
+
+| action | what this SDK does | on the event |
+|---|---|---|
+| `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"` |
+| `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
+is still scored and shows on your dashboard as Allowed, an unrecorded one is dropped before
+scoring. Either way the request passes here, unstamped — the built-in Allow-list is a skip rule
+with recording on.
+
+A rule block also names the row that decided, so the response says which rule to edit:
+
+```
+HTTP/1.1 403 Forbidden
+x-block-reason: rule
+x-block-rule: cr_4f2a9c1b7e03
+```
+
+A rule may also test one request header (`is`, `contains` or `matches`), and the header name is
+matched case-insensitively against what the client actually sent. Headers belong to the request
+plane alone: the analyst never sees them, so it treats a header rule as not matching and only a
+v5 SDK like this one enforces it.
+
+The rules ride the v5 snapshot, which this SDK asks for by default. `snapshotVersion: 4`
+pins the allow/challenge lists without the rules, `3` the block list alone; a project that
+has not published the container you ask for is answered with the next one down, so asking
+for the newest is always safe.
+
+HTML templates add the beacon with the helper (or use `@camada/react`'s `<CamadaBeacon/>`):
+
+```js
+res.send(`<head>${camada.scriptTag(req)}</head>…`);
+```
+
+App-context outcomes (the signals no edge tap can see; identifiers are HMAC-hashed in-process):
+
+```js
+camada.track(req, 'login_failed', { user: email });
+```
+
+The event name is free-form, but the analyst's app-context rules read a fixed vocabulary — use these names
+and the credential-stuffing, password-spray, account-aggregation, signup-velocity, carding and coupon rules
+fire on your app's own truth instead of path heuristics:
+
+| event | when |
+|---|---|
+| `login_failed` / `login_succeeded` | a password (or passwordless) login attempt settled; pass `{ user }` so attempts per account can be counted |
+| `signup` | an account was created |
+| `password_reset` | a reset was requested |
+| `mfa_failed` | a second factor was rejected |
+| `payment_failed` / `payment_succeeded` | a payment authorisation settled |
+| `coupon_failed` | a promo/voucher code was rejected |
+
+## Operational notes
+
+- `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.
+- 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).
+- Memory: ~5 MB per loaded snapshot.
+
+## Develop
+
+```
+npm install && npm run build && npm test && npm run check
+```
+Sibling checkouts of `camada-core` and `camada-browser` must exist (file: deps).

package/dist/camada-Cn5SJVIG.d.cts

@@ -0,0 +1,75 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { TrustedProxyConfig, SnapshotClient, EventQueue, SnapshotVersion } from '@camada/core';
+
+interface ResolvedEnv {
+    ingestToken: string;
+    snapToken: string;
+    secret: string;
+    ingestUrl: string;
+    snapshotUrl: string;
+    serverless: boolean;
+    trustedProxy: TrustedProxyConfig | 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;
+
+interface CamadaOptions {
+    env?: Record<string, string | undefined>;
+    fetchImpl?: typeof fetch;
+    refreshMs?: number;
+    scriptPath?: string;
+    fpPath?: string;
+    challenge?: boolean;
+    challengePath?: string;
+    snapshotVersion?: SnapshotVersion;
+}
+declare class Camada {
+    readonly env: ResolvedEnv | null;
+    readonly snap: SnapshotClient | null;
+    readonly queue: EventQueue | null;
+    private readonly fetchImpl;
+    private readonly scriptPath;
+    private readonly fpPath;
+    private readonly challengeOn;
+    private readonly challengePath;
+    private readonly kit;
+    private readonly envSource;
+    constructor(opts?: CamadaOptions);
+    get disabled(): boolean;
+    private trustedProxy;
+    private beaconEnabled;
+    /** 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. */
+    private relayBeacon;
+    private challengePassed;
+    /** 403 + the proof-of-work page (HTML navigations) or 403 JSON (everything else), 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. */
+    private sessionOf;
+    /** 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 }`. */
+    private verifyChallenge;
+    /** 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. */
+    serveChallenge(req: IncomingMessage, res: ServerResponse): boolean;
+    /** For HTML templates: the first-party beacon tag with the request's rid. */
+    scriptTag(req: IncomingMessage): string;
+    /** App-context outcome events (login failed, signup, …). The identifier is HMAC-hashed
+     *  in-process; the raw value never reaches the queue. */
+    track(req: IncomingMessage, event: string, data?: {
+        user?: string;
+    }): void;
+    /** Express/Connect middleware (also what NestJS on the default platform consumes). */
+    express(): (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
+    stop(): void;
+}
+declare function createCamada(opts?: CamadaOptions): Camada;
+
+export { Camada as C, type ResolvedEnv as R, type CamadaOptions as a, createCamada as c, resolveEnv as r };

package/dist/camada-Cn5SJVIG.d.ts

@@ -0,0 +1,75 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { TrustedProxyConfig, SnapshotClient, EventQueue, SnapshotVersion } from '@camada/core';
+
+interface ResolvedEnv {
+    ingestToken: string;
+    snapToken: string;
+    secret: string;
+    ingestUrl: string;
+    snapshotUrl: string;
+    serverless: boolean;
+    trustedProxy: TrustedProxyConfig | 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;
+
+interface CamadaOptions {
+    env?: Record<string, string | undefined>;
+    fetchImpl?: typeof fetch;
+    refreshMs?: number;
+    scriptPath?: string;
+    fpPath?: string;
+    challenge?: boolean;
+    challengePath?: string;
+    snapshotVersion?: SnapshotVersion;
+}
+declare class Camada {
+    readonly env: ResolvedEnv | null;
+    readonly snap: SnapshotClient | null;
+    readonly queue: EventQueue | null;
+    private readonly fetchImpl;
+    private readonly scriptPath;
+    private readonly fpPath;
+    private readonly challengeOn;
+    private readonly challengePath;
+    private readonly kit;
+    private readonly envSource;
+    constructor(opts?: CamadaOptions);
+    get disabled(): boolean;
+    private trustedProxy;
+    private beaconEnabled;
+    /** 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. */
+    private relayBeacon;
+    private challengePassed;
+    /** 403 + the proof-of-work page (HTML navigations) or 403 JSON (everything else), 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. */
+    private sessionOf;
+    /** 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 }`. */
+    private verifyChallenge;
+    /** 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. */
+    serveChallenge(req: IncomingMessage, res: ServerResponse): boolean;
+    /** For HTML templates: the first-party beacon tag with the request's rid. */
+    scriptTag(req: IncomingMessage): string;
+    /** App-context outcome events (login failed, signup, …). The identifier is HMAC-hashed
+     *  in-process; the raw value never reaches the queue. */
+    track(req: IncomingMessage, event: string, data?: {
+        user?: string;
+    }): void;
+    /** Express/Connect middleware (also what NestJS on the default platform consumes). */
+    express(): (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
+    stop(): void;
+}
+declare function createCamada(opts?: CamadaOptions): Camada;
+
+export { Camada as C, type ResolvedEnv as R, type CamadaOptions as a, createCamada as c, resolveEnv as r };