@uptimizr/collector-server 1.1.1 → 2.0.1

package/AGENTS.md

@@ -0,0 +1,193 @@
+# AGENTS.md — @uptimizr/collector-server
+
+> Packaged agent guide. For the human reference see [README.md](./README.md); for design
+> rationale see the project ADRs at https://github.com/RaananW/Uptimizr/tree/main/docs/adr.
+
+## What this package is
+
+The public-facing **ingestion + query API** (Fastify) for the OSS data collector, plus the
+`uptimizr` CLI that self-hosts it. All client input is untrusted and validated against
+`@uptimizr/schema` at the boundary. Route handlers stay thin; storage lives behind a swappable
+`CollectorStore` (ADR 0005).
+
+It is the **single gateway** to the data: the dashboard, `@uptimizr/mcp`, the in-browser assistant
+and your own agents all read through this HTTP API, never the database.
+
+## Run it
+
+```bash
+# 1. One-time setup: generate a visitor-hash secret, create + migrate the store,
+#    mint a first project + API key, write a local .env.
+npx -p @uptimizr/collector-server uptimizr init "My Project"
+
+# 2. Start the ingestion + query API (reads the generated .env; 0.0.0.0:4318).
+npx -p @uptimizr/collector-server uptimizr serve
+```
+
+`init` prints a **`projectId`** (public — give it to your client SDK along with this server's URL)
+and a one-time **API key** (secret — `x-api-key` for the query routes).
+
+### CLI (ADR 0029)
+
+| Command                        | What it does                                                         |
+| ------------------------------ | -------------------------------------------------------------------- |
+| `uptimizr init [name]`         | Secret + store + migrations + first project/key + `.env`.            |
+| `uptimizr serve`               | Run the ingestion + query API. The default when no command is given. |
+| `uptimizr new-project <name>`  | Mint an additional project + API key.                                |
+| `uptimizr new-key <projectId>` | Mint an additional key on an existing project (see the flags below). |
+| `uptimizr migrate`             | Apply store migrations.                                              |
+| `uptimizr regions set <scene>` | Replace a scene's named regions from `--file <regions.json>`.        |
+| `uptimizr regions get <scene>` | Print a scene's named regions as JSON.                               |
+| `uptimizr help`                | Usage.                                                               |
+
+`new-key` flags: `--capabilities <list>` (comma-separated; default `query`), `--label <name>`,
+and the paired `--rate-limit-max <n>` / `--rate-limit-window-ms <ms>`:
+
+```bash
+uptimizr new-key <projectId> --capabilities query,annotate \
+  --label "weekly-report-agent" --rate-limit-max 120 --rate-limit-window-ms 60000
+```
+
+`regions` commands take `--project <projectId>` (or `UPTIMIZR_PROJECT_ID`). They talk to the store
+**directly**, so they need no API key — an operator command, unlike the HTTP equivalent.
+
+**Every command targets the store selected by `COLLECTOR_STORE`**, read through the same
+connection variables `serve` uses — so export the store + its settings before `init` and the
+project you mint is the one the running collector resolves.
+
+Installed as a dependency, the package exposes the `uptimizr` CLI plus the legacy
+`uptimizr-collector` bin (equivalent to `uptimizr serve`).
+
+## API keys and capabilities (ADR 0051 §7)
+
+A key carries a **set of capabilities**, not a single role. Keys default to `query`.
+
+| Capability  | Unlocks                                                                                                   |
+| ----------- | --------------------------------------------------------------------------------------------------------- |
+| `query`     | The aggregate analytics API, the scene registry, the live token exchange, and `GET /api/v1/audit`.        |
+| `query:raw` | Raw per-session streams: `GET /api/v1/sessions/:id/events` and `GET /api/v1/live/sessions/:id`.           |
+| `annotate`  | The project **metadata** write path (annotations, glossary, saved analyses, panel specs). Never events.   |
+| `ingest`    | Reserved for server-side write paths. Public ingestion is keyless, so issued keys are normally read keys. |
+
+The raw endpoints are gated **twice**: the collector must run with `ENABLE_RAW_SESSION_RETENTION`
+**and** the key must hold `query:raw` — otherwise `403`. Retention alone is not enough.
+
+`--rate-limit-max` / `--rate-limit-window-ms` give a key its own request budget, bucketed on the
+**key id** rather than the client IP; keys without one fall back to `COLLECTOR_RATE_LIMIT_*`.
+Ingestion keeps its separate `COLLECTOR_INGEST_RATE_LIMIT_*` budget.
+
+## Endpoints an agent should know
+
+- **`GET /api/v1/openapi.json`** — **unauthenticated** OpenAPI 3.1 for the whole read API,
+  generated from the `@uptimizr/metrics` registry (ADR 0051) and this server's route table. One
+  path per endpoint, the real validating schema per parameter, a response schema per metric, and
+  the semantics OpenAPI cannot express as `x-uptimizr-*` extensions (result `grain`, per-column
+  `units`, `caveats`, `interpretation`, source capture channels, row `limits`). **Start here**
+  rather than guessing routes; generate a typed client with
+  `npx openapi-typescript <collector>/api/v1/openapi.json -o collector.d.ts`.
+- **`GET /api/v1/whoami`** — the calling key's `projectId`, `keyId`, `capabilities`, `label` and
+  effective `rateLimit` (plus `rateLimitSource`: `"key"` or `"default"`). It reports the key's
+  **id**, never the key. Call it first and register only the tools your capabilities permit,
+  instead of probing for `403`s.
+- **`GET /api/v1/audit`** (`since` / `until` / `limit`, any `query` key) — the agent audit log.
+- `POST /api/v1/collect` — batched ingestion. **Keyless by design** (it runs in untrusted
+  browsers, where a key is not a secret); protected by schema validation, payload bounds and rate
+  limits instead. The server sets the cookieless `visitorId = hash(ip + ua + dailySalt)`; the raw
+  IP is never stored (ADR 0003).
+- The read API: sessions, heatmaps (`pointer`, `camera`, `position`, `world`, `gaze`, `mesh-uv`,
+  `click-rays`, `flow`, `perf`, `errors`), mesh/interaction insights, performance and diagnostics,
+  scene/path/funnel analytics, scene representations and regions, and the live SSE endpoints.
+- `GET /health` — liveness probe, unauthenticated.
+
+### Result envelopes: `format=full | table | summary` (ADR 0051 §2)
+
+Every aggregate endpoint accepts `format`. It **filters nothing** — it picks the result envelope:
+
+- `full` (default) — the bare rows, unchanged. What the dashboard uses.
+- `table` — adds a `meta` envelope: metric, range, applied filters, sample size, row count,
+  `truncated`, limits.
+- `summary` — a bounded digest: ranked top rows, a first/last/min/max/trend series, or merged
+  spatial clusters, with shares, the metric's caveats and a templated `reading` sentence, capped at
+  the registry's `maxSummaryRows`. **This is what makes a 500-bin heatmap affordable for an LLM** —
+  prefer it over `full` when feeding a model.
+
+### Filters
+
+Common query params: `since`, `until` (epoch ms), `bins`, `limit`, `scene`, `session`,
+`cameraMode`, `source`, and spatial `cellSize` / **`region`** where supported. `region=<id>` drills
+a spatial query into one named place from the scene registry — declare regions with
+`uptimizr regions set`, `PUT /api/v1/scenes/:sceneId/regions` (an `annotate` key), or
+`registerRegions` in `@uptimizr/sdk-core`.
+
+### Live endpoints
+
+`POST /api/v1/live/token` exchanges a query key for a short-lived SSE token; the key's capability
+set is carried **inside the signed token**, so `GET /api/v1/live/sessions/:id` can enforce
+`query:raw` even though `EventSource` cannot send headers. `GET /api/v1/live/presence` and
+`/live/stream` use the same `?token=...`.
+
+## Storage (`COLLECTOR_STORE`)
+
+| Value                  | Store                                                                                                                                                                                                                 |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `duckdb` **(default)** | Single-file OSS store: events **and** metadata in one file at `DUCKDB_PATH` (default `./data/uptimizr.duckdb`). No external service. **Single-writer** — one collector process per file; back up by copying the file. |
+| `memory`               | Dependency-free in-memory store for local dev / E2E only (`COLLECTOR_MEMORY_PROJECT_ID` / `COLLECTOR_MEMORY_API_KEY`).                                                                                                |
+| `postgres`             | `@uptimizr/db-postgres` — `POSTGRES_URL` / `DATABASE_URL`, `POSTGRES_SCHEMA`, `POSTGRES_POOL_MAX`. Multi-writer.                                                                                                      |
+| `mssql`                | `@uptimizr/db-mssql` — `MSSQL_URL` (or `MSSQL_SERVER` / `MSSQL_PORT` / `MSSQL_DATABASE` / `MSSQL_USER` / `MSSQL_PASSWORD`). SQL Server 2022+ / Azure SQL. Multi-writer.                                               |
+| `clickhouse`           | `@uptimizr/db-clickhouse` — `CLICKHOUSE_URL` / `CLICKHOUSE_DATABASE` / `CLICKHOUSE_USER` / `CLICKHOUSE_PASSWORD`. Concurrent writers, high-volume ingestion.                                                          |
+
+All four return **identical analytics** (the cross-engine parity suite). Aggregations are computed
+at **query time** in v1 — no materialized views.
+
+## Other configuration
+
+- Server / browser access: `COLLECTOR_HOST` (`0.0.0.0`), `COLLECTOR_PORT` (`4318`),
+  `COLLECTOR_CORS_ORIGINS`, `COLLECTOR_TRUST_PROXY`, `COLLECTOR_BODY_LIMIT`.
+- Privacy / replay / live: **`VISITOR_HASH_SECRET` (required — the server fails fast without it)**,
+  `ENABLE_RAW_SESSION_RETENTION`, `LIVE_TOKEN_SECRET`, `LIVE_TOKEN_TTL_MS`, `LIVE_WINDOW_MS`,
+  `LIVE_MAX_CONNECTIONS`, `LIVE_PRESENCE_INTERVAL_MS`.
+- Rate limits: `COLLECTOR_RATE_LIMIT_MAX`, `COLLECTOR_RATE_LIMIT_WINDOW_MS`,
+  `COLLECTOR_INGEST_RATE_LIMIT_MAX`, `COLLECTOR_INGEST_RATE_LIMIT_WINDOW_MS`.
+- Agent audit: **`AUDIT_RETENTION_DAYS`** (default `30`; `0` = keep forever),
+  `AUDIT_DASHBOARD_REQUESTS` (default off — requests carrying `x-uptimizr-client: dashboard` are
+  skipped as a volume filter, **not** a security boundary).
+- All-in-one dashboard: `COLLECTOR_DASHBOARD_DIR` (point it at a static dashboard export and one
+  process serves ingestion, queries and the UI), `COLLECTOR_CSP` (`strict` or `off`).
+
+## Rules for agents
+
+- **Validate at the boundary.** Every request body and querystring is parsed against
+  `@uptimizr/schema` / the metric registry. Never trust client input, never skip validation.
+- **Keep handlers thin** (ADR 0005). Aggregation logic belongs in `@uptimizr/db`; the semantics of
+  a metric belong in `@uptimizr/metrics`. A new read endpoint is a **registry entry**, not a
+  hand-written route — `registryRoutes.test.ts` asserts the endpoint exists and that its
+  querystring keys equal the metric's `filters`, and `queryResponseSchemas.test.ts` asserts every
+  endpoint's rows parse against the metric's `row` schema on a seeded store, an empty one, and the
+  in-memory store.
+- **Never weaken the raw-data gate.** `ENABLE_RAW_SESSION_RETENTION` **and** `query:raw`, both,
+  for `/sessions/:id/events` and `/live/sessions/:id` (ADR 0003).
+- **Never log secrets or raw IPs.** The audit log's subject is the key **id**; `params` drops
+  credential-shaped fields and is capped at 512 bytes. Audit writes happen after the response is
+  flushed, so they can never block or fail a request. Refusals are recorded too.
+- **Ingestion stays keyless.** Do not "fix" it by requiring a key — a key shipped to an untrusted
+  browser is not a secret. Harden with validation, payload bounds, rate limits and CORS instead.
+- Events live once in `@uptimizr/schema`. Do not redefine an event shape here.
+- Aggregations are query-time in v1; do not add materialized views without an ADR.
+
+## Develop
+
+```bash
+pnpm --filter @uptimizr/collector-server dev    # tsx watch
+pnpm --filter @uptimizr/collector-server test   # vitest (app.inject() + a fake store)
+pnpm --filter @uptimizr/collector-server build
+```
+
+Tests run against a fake `CollectorStore` with `app.inject()` — no live database required.
+
+## More
+
+- Package reference: [README.md](./README.md)
+- HTTP API reference:
+  https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md#4-http-api
+- Query API guide: https://uptimizr.com/docs/api/query/
+- Deploy guide: https://uptimizr.com/docs/deploy/collector/

package/README.md

@@ -25,7 +25,10 @@ npx -p @uptimizr/collector-server uptimizr serve
 and this server's URL (the **`endpoint`**) to your client SDK (e.g.
 `@uptimizr/babylon`); use the **API key** (`x-api-key`) for the query routes /
 dashboard. Mint more projects later with
-`npx -p @uptimizr/collector-server uptimizr new-project "<name>"`.
+`npx -p @uptimizr/collector-server uptimizr new-project "<name>"`, or add a key
+to an existing project with
+`npx -p @uptimizr/collector-server uptimizr new-key <projectId> [--capabilities …] [--label …]`
+— see [API keys and capabilities](#api-keys-and-capabilities).
 
 `init`, `new-project` and `migrate` target the store selected by
 `COLLECTOR_STORE`, read through the same connection variables `serve` uses — so
@@ -41,6 +44,34 @@ npx -p @uptimizr/collector-server uptimizr init "My Project"   # schema + first
 npx -p @uptimizr/collector-server uptimizr serve
 ```
 
+### Naming places in a scene: `uptimizr regions`
+
+A scene can carry **regions** — named, labelled world-space boxes ("the
+entrance", "the checkout counter") that give spatial results a vocabulary and let
+any spatial query be drilled into a place with `?region=<id>`. Declare them from
+a JSON file straight against the store, without a running collector:
+
+```bash
+cat > regions.json <<'JSON'
+[
+  { "id": "entrance", "label": "Entrance", "bounds": [-5, 0, -5, 5, 3, 0] },
+  { "id": "counter", "label": "Checkout counter", "bounds": [-1, 0, 1, 1, 2, 3] }
+]
+JSON
+
+npx -p @uptimizr/collector-server uptimizr regions set lobby --file regions.json --project "$PROJECT_ID"
+npx -p @uptimizr/collector-server uptimizr regions get lobby --project "$PROJECT_ID"
+```
+
+The file is either a bare array or the `{ "regions": [...] }` envelope the HTTP
+endpoint takes, so one file works with both. `--project` may be replaced by
+`UPTIMIZR_PROJECT_ID`. The write **replaces** the scene's whole set, so leaving a
+region out removes it and `[]` clears them. The CLI talks to the store directly,
+so it needs no API key. Over HTTP the same thing is
+`PUT /api/v1/scenes/:sceneId/regions` (see the integration guide), which takes
+an `annotate`-capable key, and from a client build `registerRegions` in
+`@uptimizr/sdk-core`.
+
 ### All-in-one: serve the dashboard too
 
 The collector can also serve a pre-built static dashboard from its own origin, so
@@ -92,6 +123,18 @@ file; back up by copying the file).
 
 ## Endpoints
 
+### Self-description
+
+- `GET /api/v1/openapi.json` — an **OpenAPI 3.1** document for the whole read API,
+  generated from the semantic metric registry (ADR 0051) and this server's own
+  route table: one path per endpoint, every parameter carrying the schema that
+  actually validates it, and a response schema per metric. The semantics OpenAPI
+  cannot express ride along as `x-uptimizr-*` extensions — the result `grain`,
+  per-column `units`, `caveats`, `interpretation`, the capture channels that feed
+  the metric, and its row `limits`. **Unauthenticated**: it is documentation and
+  contains no project data. Generate a typed client with
+  `npx openapi-typescript <collector>/api/v1/openapi.json -o collector.d.ts`.
+
 ### Ingestion
 
 - `POST /api/v1/collect` — accepts a batched `collectRequest`. Validates → rejects
@@ -127,20 +170,38 @@ the project the API key resolves to.
   `/xr/sources`, `/xr/abandonment`, `/xr/locomotion`.
 - Scene representations: `PUT /api/v1/scenes/:sceneId/representation`,
   `GET /api/v1/scenes/:sceneId/representation`.
-- `GET /api/v1/sessions/:id/events` — ordered replay timeline, **gated by**
-  `ENABLE_RAW_SESSION_RETENTION` (returns `403` when disabled); supports buffered
-  JSON or NDJSON streaming (`Accept: application/x-ndjson` / `?format=ndjson`).
+- `GET /api/v1/sessions/:id/events` — ordered replay timeline. Raw per-session
+  data, so it is **gated twice**: `ENABLE_RAW_SESSION_RETENTION` must be on
+  **and** the key must hold `query:raw` (`403` otherwise). Supports buffered JSON
+  or NDJSON streaming (`Accept: application/x-ndjson` / `?format=ndjson`).
+- Key identity + audit: `GET /api/v1/whoami` (the calling key's project, key id,
+  capabilities, label and effective rate limit) and `GET /api/v1/audit`
+  (`since`/`until`/`limit`) — see
+  [API keys and capabilities](#api-keys-and-capabilities).
 
 Live endpoints:
 
-- `POST /api/v1/live/token` — exchange a query API key for a short-lived live token.
+- `POST /api/v1/live/token` — exchange a query API key for a short-lived live
+  token. The key's capability set is carried inside the signed token, so the
+  per-session follow can enforce `query:raw` without a header `EventSource`
+  cannot send.
 - `GET /api/v1/live/presence`, `/live/stream`, `/live/sessions/:id` — SSE streams
-  authenticated with `?token=...`; per-session live follow is also gated by raw
-  retention.
+  authenticated with `?token=...`; the per-session follow is gated by raw
+  retention **and** `query:raw`, exactly like the replay timeline.
 
 Common query params include `since`, `until` (epoch ms), `bins`, `limit`, `scene`,
 `session`, `cameraMode`, `source`, and spatial `cellSize` / `region` where supported.
 
+Every aggregate endpoint also accepts `format=full | table | summary` (ADR 0051 §2).
+It filters nothing — it picks the result envelope. `full` is the default and returns
+the bare rows unchanged (what the dashboard uses); `table` adds a `meta` envelope
+(metric, range, applied filters, sample size, row count, `truncated`, limits); and
+`summary` returns a bounded digest — ranked top rows, a first/last/min/max/trend
+series, or merged spatial clusters, with shares, the metric's caveats and a
+templated `reading` sentence — capped at the registry's `maxSummaryRows`, which is
+what makes a 500-bin heatmap affordable for an LLM. See
+[Result formats](https://uptimizr.com/docs/api/query/#result-formats).
+
 - `GET /health` — liveness probe.
 
 ## Security
@@ -158,6 +219,46 @@ if `VISITOR_HASH_SECRET` is missing.
 | `POST /api/v1/live/token`                 | `x-api-key`        | Exchanges a project query key for a short-lived SSE token.                                                                                              |
 | Live SSE routes (`/api/v1/live/*` `GET`s) | `?token=...`       | Browser `EventSource` cannot attach custom headers, so live streams use short-lived bearer tokens.                                                      |
 | `GET /health`                             | None               | Liveness probe.                                                                                                                                         |
+| `GET /api/v1/openapi.json`                | None               | API documentation, not data — a client needs it before it has a key. Rate-limited like every other route.                                               |
+
+### API keys and capabilities
+
+A key carries a **set of capabilities** (ADR 0051 §7), not a single role:
+
+| Capability  | Grants                                                                                                    |
+| ----------- | --------------------------------------------------------------------------------------------------------- |
+| `query`     | The aggregate analytics API, the scene registry, the live token exchange and `GET /api/v1/audit`.         |
+| `query:raw` | Raw per-session streams: `GET /api/v1/sessions/:id/events` and `GET /api/v1/live/sessions/:id`.           |
+| `annotate`  | The project **metadata** write path (annotations, glossary, saved analyses, panel specs). Never events.   |
+| `ingest`    | Reserved for server-side write paths. Public ingestion is keyless, so issued keys are normally read keys. |
+
+Keys default to `query`, including those from `uptimizr init` / `uptimizr new-project`:
+
+```bash
+uptimizr new-key <projectId> --capabilities query,annotate \
+  --label "weekly-report-agent" --rate-limit-max 120 --rate-limit-window-ms 60000
+```
+
+> **Breaking change.** `query:raw` is new, and the raw per-session endpoints now require **both**
+> `ENABLE_RAW_SESSION_RETENTION` **and** `query:raw` — previously retention alone was enough for
+> any `query` key. Existing keys keep working for every aggregate endpoint; a key that drives
+> session replay or live-follow must be re-minted with `--capabilities query,query:raw`.
+
+`--rate-limit-max` / `--rate-limit-window-ms` give a key its own request budget, bucketed on the
+key id rather than the client IP; keys without one fall back to `COLLECTOR_RATE_LIMIT_*`.
+Ingestion keeps its separate `COLLECTOR_INGEST_RATE_LIMIT_*` budget.
+
+### Agent audit log
+
+Every authenticated request made with a key that is not the dashboard's own session is recorded
+(`keyId`, `surface`, route pattern, bounded+redacted `params`, `rowCount`, `durationMs`,
+`status`), readable at `GET /api/v1/audit` with any `query` key. Refusals are recorded too. A key
+never appears in a row — the subject is the key's **id** — and `params` drops credential-shaped
+fields and is capped at 512 bytes. Writes happen after the response is flushed, so the audit log
+can never block or fail a request. "The dashboard's own session" is a request carrying
+`x-uptimizr-client: dashboard` (a volume filter, not a security boundary — set
+`AUDIT_DASHBOARD_REQUESTS=1` to record everything). Rows expire after `AUDIT_RETENTION_DAYS`
+(default `30`; `0` keeps them forever).
 
 ### Threat model for keyless ingestion
 
@@ -188,7 +289,10 @@ Environment-driven (see [`.env.example`](../../../.env.example)):
   `ENABLE_RAW_SESSION_RETENTION`, `LIVE_TOKEN_SECRET`, `LIVE_TOKEN_TTL_MS`,
   `LIVE_WINDOW_MS`, `LIVE_MAX_CONNECTIONS`, `LIVE_PRESENCE_INTERVAL_MS`.
 - Rate limits: `COLLECTOR_RATE_LIMIT_MAX`, `COLLECTOR_RATE_LIMIT_WINDOW_MS`,
-  `COLLECTOR_INGEST_RATE_LIMIT_MAX`, `COLLECTOR_INGEST_RATE_LIMIT_WINDOW_MS`.
+  `COLLECTOR_INGEST_RATE_LIMIT_MAX`, `COLLECTOR_INGEST_RATE_LIMIT_WINDOW_MS`
+  (a key's own budget overrides the first pair).
+- Agent audit: `AUDIT_RETENTION_DAYS` (default `30`, `0` = keep forever),
+  `AUDIT_DASHBOARD_REQUESTS` (default off).
 - All-in-one dashboard: `COLLECTOR_DASHBOARD_DIR` (optional; see
   [above](#all-in-one-serve-the-dashboard-too)), `COLLECTOR_CSP` (`strict` or `off`).
 

package/dist/__tests__/support/registryRequests.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared fixtures for the suites that sweep **every** registry endpoint
+ * (`queryResponseSchemas.test.ts`, `resultFormat.test.ts`).
+ *
+ * Both need the same three things: a collector config, a scene proxy so the
+ * `scene_representation` resource has something to return, and the rule for
+ * turning a registry `endpoint.path` into a request URL. Keeping them here means
+ * a new endpoint that needs a required parameter is taught about once.
+ *
+ * Not a test file — the filename has no `.test.` segment, so Vitest does not
+ * collect it.
+ */
+import type { MetricDefinition } from "@uptimizr/metrics";
+import type { CollectorConfig } from "../../config.js";
+/** A collector config with every gate open and every secret a test secret. */
+export declare const TEST_CONFIG: CollectorConfig;
+/** Fixture scene proxy, so the `scene_representation` resource has a hit. */
+export declare const TEST_PROXY: {
+    version: 1;
+    sceneId: string;
+    kind: "aabb";
+    bounds: [number, number, number, number, number, number];
+    upAxis: "y";
+    unitScale: number;
+    meshes: {
+        name: string;
+        aabb: [number, number, number, number, number, number];
+    }[];
+    meshCount: number;
+    contentHash: string;
+    capturedAt: number;
+};
+/** Path params every registry endpoint that declares one can be satisfied with. */
+export declare const PATH_PARAM_VALUES: Readonly<Record<string, string>>;
+/**
+ * Query parameters an endpoint needs beyond the shared range. Only the genuinely
+ * required ones: `mesh` for the per-mesh UV heatmap and `steps` for the funnel.
+ */
+export declare const REQUIRED_QUERY: Readonly<Record<string, Record<string, string>>>;
+/** The two resource reads, which legitimately 404 when nothing is registered. */
+export declare const RESOURCE_METRICS: ReadonlySet<string>;
+/**
+ * Fill a registry path's `:params` and append the query string for a request.
+ * `extra` adds (or overrides) query parameters — `format`, for instance.
+ */
+export declare function requestUrl(metric: MetricDefinition, extra?: Readonly<Record<string, string>>): string;
+//# sourceMappingURL=registryRequests.d.ts.map

package/dist/__tests__/support/registryRequests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registryRequests.d.ts","sourceRoot":"","sources":["../../../src/__tests__/support/registryRequests.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,8EAA8E;AAC9E,eAAO,MAAM,WAAW,EAAE,eAqBzB,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,UAAU;;;;YAIW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;;;;;cAM5C,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;;;;;CAMrF,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAI9D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAK3E,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAG/C,CAAC;AAEH;;;GAGG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,gBAAgB,EACxB,KAAK,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,GAC3C,MAAM,CAYR"}

package/dist/__tests__/support/registryRequests.js

@@ -0,0 +1,93 @@
+/**
+ * Shared fixtures for the suites that sweep **every** registry endpoint
+ * (`queryResponseSchemas.test.ts`, `resultFormat.test.ts`).
+ *
+ * Both need the same three things: a collector config, a scene proxy so the
+ * `scene_representation` resource has something to return, and the rule for
+ * turning a registry `endpoint.path` into a request URL. Keeping them here means
+ * a new endpoint that needs a required parameter is taught about once.
+ *
+ * Not a test file — the filename has no `.test.` segment, so Vitest does not
+ * collect it.
+ */
+import { PARITY_RANGE } from "@uptimizr/db";
+/** A collector config with every gate open and every secret a test secret. */
+export const TEST_CONFIG = {
+    host: "127.0.0.1",
+    port: 0,
+    corsOrigins: [],
+    visitorHashSecret: "test-secret",
+    enableRawSessionRetention: false,
+    liveWindowMs: 30_000,
+    liveTokenSecret: "test-live-secret",
+    liveTokenSecretIsDedicated: true,
+    liveTokenTtlMs: 900_000,
+    liveMaxConnections: 200,
+    livePresenceIntervalMs: 2_000,
+    rateLimitMax: 1000,
+    rateLimitWindowMs: 60_000,
+    ingestRateLimitMax: 1000,
+    ingestRateLimitWindowMs: 60_000,
+    trustProxy: false,
+    bodyLimit: 1_048_576,
+    cspMode: "strict",
+    auditRetentionDays: 30,
+    auditDashboardRequests: false,
+};
+/** Fixture scene proxy, so the `scene_representation` resource has a hit. */
+export const TEST_PROXY = {
+    version: 1,
+    sceneId: "lobby",
+    kind: "aabb",
+    bounds: [-2, 0, -2, 2, 3, 2],
+    upAxis: "y",
+    unitScale: 1,
+    meshes: [
+        {
+            name: "floor",
+            aabb: [-2, 0, -2, 2, 0.1, 2],
+        },
+    ],
+    meshCount: 1,
+    contentHash: "abc123",
+    capturedAt: 1_750_000_000_000,
+};
+/** Path params every registry endpoint that declares one can be satisfied with. */
+export const PATH_PARAM_VALUES = {
+    ":sessionId": "s1",
+    ":id": "s1",
+    ":sceneId": "lobby",
+};
+/**
+ * Query parameters an endpoint needs beyond the shared range. Only the genuinely
+ * required ones: `mesh` for the per-mesh UV heatmap and `steps` for the funnel.
+ */
+export const REQUIRED_QUERY = {
+    "/api/v1/heatmaps/mesh-uv": { mesh: "box" },
+    "/api/v1/funnel": {
+        steps: JSON.stringify([{ type: "session_start" }, { type: "pointer_click" }]),
+    },
+};
+/** The two resource reads, which legitimately 404 when nothing is registered. */
+export const RESOURCE_METRICS = new Set([
+    "session_meta",
+    "scene_representation",
+]);
+/**
+ * Fill a registry path's `:params` and append the query string for a request.
+ * `extra` adds (or overrides) query parameters — `format`, for instance.
+ */
+export function requestUrl(metric, extra = {}) {
+    let path = metric.endpoint.path;
+    for (const [token, value] of Object.entries(PATH_PARAM_VALUES)) {
+        path = path.replace(token, value);
+    }
+    const params = new URLSearchParams({
+        since: String(PARITY_RANGE.since),
+        until: String(PARITY_RANGE.until),
+        ...(REQUIRED_QUERY[metric.endpoint.path] ?? {}),
+        ...extra,
+    });
+    return `${path}?${params.toString()}`;
+}
+//# sourceMappingURL=registryRequests.js.map

package/dist/__tests__/support/registryRequests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registryRequests.js","sourceRoot":"","sources":["../../../src/__tests__/support/registryRequests.ts"],"names":[],"mappings":"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"}

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAIA,OAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AAMxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAM3D,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,EAAE,eAAe,CAAC;IACxB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA0BD;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CAuE3E"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAIA,OAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AAMxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAS3D,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,EAAE,eAAe,CAAC;IACxB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA0BD;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CAuG3E"}

package/dist/app.js

@@ -1,13 +1,16 @@
 import cors from "@fastify/cors";
 import helmet from "@fastify/helmet";
-import rateLimit from "@fastify/rate-limit";
+import rateLimit, { normalizeIP } from "@fastify/rate-limit";
 import fastifyStatic from "@fastify/static";
 import Fastify, {} from "fastify";
 import { serializerCompiler, validatorCompiler, } from "fastify-type-provider-zod";
 import { createLiveBus } from "./liveBus.js";
+import { attachApiKey } from "./auth.js";
+import { registerAuditHooks, startAuditRetention } from "./audit.js";
 import { buildDashboardCsp } from "./csp.js";
 import { collectRoutes } from "./routes/collect.js";
 import { liveRoutes } from "./routes/live.js";
+import { collectRouteSchemas, metaRoutes } from "./routes/meta.js";
 import { queryRoutes } from "./routes/query.js";
 /**
  * Strip the live-SSE `?token=` from a logged URL. The token is a short-lived
@@ -74,14 +77,42 @@ export async function buildApp(deps) {
         // satisfies the preflight that sendBeacon forces.
         credentials: true,
     });
+    // Resolve `x-api-key` once, before the rate limiter runs, so (a) a key with
+    // its own budget is throttled per key rather than per client IP and (b) the
+    // handlers and the audit hook reuse one metadata lookup per request (#309).
+    // Instance-level `onRequest` hooks run before the route-level hook the
+    // rate-limit plugin installs, so registration order here is load-bearing.
+    app.decorateRequest("resolvedKey", null);
+    app.decorateRequest("auditRowCount", null);
+    app.addHook("onRequest", async (request) => {
+        await attachApiKey(request, store);
+    });
     await app.register(rateLimit, {
-        max: config.rateLimitMax,
-        timeWindow: config.rateLimitWindowMs,
+        // A key carrying its own `rate_limit_max` / `rate_limit_window_ms` is
+        // bucketed on the key id with those values; everything else (including
+        // keyless ingest) keeps the global per-client-IP budget.
+        max: (request) => request.resolvedKey?.rateLimit?.max ?? config.rateLimitMax,
+        timeWindow: (request) => request.resolvedKey?.rateLimit?.windowMs ?? config.rateLimitWindowMs,
+        // `normalizeIP` is exactly what the plugin's own default key generator uses,
+        // so requests without a per-key budget keep their existing IPv6-aware bucket.
+        keyGenerator: (request) => request.resolvedKey?.rateLimit ? `key:${request.resolvedKey.keyId}` : normalizeIP(request.ip),
     });
+    // Audit every authenticated, non-dashboard request (ADR 0051 §7). Registered
+    // after the rate limiter so a throttled request is still recorded.
+    registerAuditHooks(app, store, config);
+    const stopAuditRetention = startAuditRetention(app, store, config);
+    app.addHook("onClose", async () => stopAuditRetention());
+    // Record every route's Zod schemas as they are registered, so the generated
+    // OpenAPI document describes each parameter with the *same* schema that
+    // validates the request (ADR 0051 §1). The hook must be installed before the
+    // route plugins below; the array it fills is complete once `app.ready()` has
+    // resolved, which is always before `metaRoutes` serves its first request.
+    const routeSchemas = collectRouteSchemas(app);
     app.get("/health", async () => ({ status: "ok" }));
     await app.register(collectRoutes, { store, config, liveBus });
     await app.register(liveRoutes, { store, config, liveBus });
     await app.register(queryRoutes, { store, config });
+    await app.register(metaRoutes, { routeSchemas });
     // All-in-one: serve a pre-built static dashboard from `dashboardDir`. The API
     // routes above (`/health`, `/api/v1/*`) are matched first; everything else
     // falls through to the static files. Unmatched GET navigations (the SPA deep

package/dist/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/audit.d.ts

@@ -0,0 +1,22 @@
+import type { FastifyInstance } from "fastify";
+import type { CollectorConfig } from "./config.js";
+import type { CollectorStore } from "./store.js";
+/**
+ * Register the audit hooks on `app`:
+ *
+ * - `preSerialization` captures the row count when a handler returned an array
+ *   (streamed/hijacked responses simply have none);
+ * - `onResponse` writes the row for authenticated, non-dashboard requests.
+ */
+export declare function registerAuditHooks(app: FastifyInstance, store: CollectorStore, config: CollectorConfig): void;
+/**
+ * Start the retention sweep: delete audit rows older than
+ * `config.auditRetentionDays` now, then every {@link PRUNE_INTERVAL_MS}. The
+ * delete is idempotent, so a restart loop or several collector instances
+ * sharing one database cost nothing. Returns a stop function; the timer is
+ * `unref`'d so it never keeps the process alive.
+ *
+ * `auditRetentionDays === 0` disables the sweep (keep rows indefinitely).
+ */
+export declare function startAuditRetention(app: FastifyInstance, store: CollectorStore, config: CollectorConfig): () => void;
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAwBjD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,eAAe,EACpB,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,eAAe,GACtB,IAAI,CAoCN;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,eAAe,EACpB,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,eAAe,GACtB,MAAM,IAAI,CAkBZ"}