@uptimizr/collector-server 1.1.1 → 2.0.0

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"}

package/dist/audit.js

@@ -0,0 +1,96 @@
+import { serializeAuditParams } from "@uptimizr/db";
+import { isDashboardRequest } from "./auth.js";
+/**
+ * Agent audit log plumbing (#309, ADR 0051 §7).
+ *
+ * Every authenticated request made with a key that is not the dashboard's own
+ * session is recorded: which key, which endpoint, the (bounded, redacted)
+ * parameters, the row count, the duration and the status.
+ *
+ * Two invariants hold everywhere in here:
+ *
+ * - **It never blocks the response.** The row is written from an `onResponse`
+ *   hook, after the reply has been flushed.
+ * - **It never fails a request.** Every store call is fire-and-forget with its
+ *   rejection swallowed into a log line; an unavailable audit table degrades
+ *   the log, not the API.
+ */
+/** How often the retention sweep runs. Daily is plenty for a 30-day window. */
+const PRUNE_INTERVAL_MS = 6 * 60 * 60 * 1000;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * 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 function registerAuditHooks(app, store, config) {
+    app.addHook("preSerialization", async (request, _reply, payload) => {
+        if (Array.isArray(payload))
+            request.auditRowCount = payload.length;
+        return payload;
+    });
+    app.addHook("onResponse", async (request, reply) => {
+        const resolved = request.resolvedKey;
+        if (!resolved)
+            return;
+        if (!config.auditDashboardRequests && isDashboardRequest(request))
+            return;
+        // `reply.elapsedTime` is the ms between the request arriving and the
+        // response being sent — exactly the duration the audit log wants.
+        const durationMs = Math.round(reply.elapsedTime);
+        try {
+            void store
+                .recordAudit({
+                projectId: resolved.projectId,
+                keyId: resolved.keyId,
+                surface: "http",
+                // The route pattern (`/api/v1/sessions/:id/events`), not the raw URL:
+                // it groups cleanly and cannot carry a querystring credential.
+                toolOrPath: request.routeOptions.url ?? new URL(request.url, "http://x").pathname,
+                params: serializeAuditParams(request.query),
+                rowCount: request.auditRowCount,
+                durationMs,
+                status: reply.statusCode,
+            })
+                .catch((err) => {
+                request.log.warn({ err }, "failed to write agent audit row");
+            });
+        }
+        catch (err) {
+            // A synchronous throw from the store (or a store that does not implement
+            // the audit surface at all) must never surface on the request path.
+            request.log.warn({ err }, "failed to write agent audit row");
+        }
+    });
+}
+/**
+ * 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 function startAuditRetention(app, store, config) {
+    if (config.auditRetentionDays <= 0)
+        return () => { };
+    const sweep = () => {
+        const cutoff = Date.now() - config.auditRetentionDays * MS_PER_DAY;
+        try {
+            void store.pruneAudit(cutoff).catch((err) => {
+                app.log.warn({ err }, "agent audit retention sweep failed");
+            });
+        }
+        catch (err) {
+            app.log.warn({ err }, "agent audit retention sweep failed");
+        }
+    };
+    sweep();
+    const timer = setInterval(sweep, PRUNE_INTERVAL_MS);
+    timer.unref?.();
+    return () => clearInterval(timer);
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

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

package/dist/auth.d.ts

@@ -0,0 +1,64 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import type { ApiKeyCapability, ResolvedApiKey } from "@uptimizr/db";
+import type { CollectorStore } from "./store.js";
+/**
+ * Request-boundary authentication and capability checks for the collector
+ * (#309, ADR 0051 §7).
+ *
+ * A key resolves to a **capability set**, not a single capability, so the same
+ * plumbing serves reads (`query`), raw per-session access (`query:raw`, which
+ * additionally requires `ENABLE_RAW_SESSION_RETENTION` — ADR 0003) and the
+ * metadata write path (`annotate`, whose endpoints arrive with #310).
+ *
+ * Resolution happens once per request, in an `onRequest` hook, so that:
+ *
+ * 1. the rate limiter can key on the API key id and honour the key's own
+ *    per-key budget before any handler runs, and
+ * 2. handlers and the audit hook read the already-resolved key instead of
+ *    hitting the metadata store again.
+ */
+declare module "fastify" {
+    interface FastifyRequest {
+        /**
+         * What this request's `x-api-key` resolved to, or `null` when
+         * unauthenticated. This is the key's **record** — project, key id,
+         * capabilities, rate limit — and deliberately never the key itself, which
+         * is read from the header and discarded.
+         */
+        resolvedKey: ResolvedApiKey | null;
+        /** Rows in the response body, when it serialized to an array (audit log). */
+        auditRowCount: number | null;
+    }
+}
+/** Header a first-party UI sets to identify itself (see `isDashboardRequest`). */
+export declare const CLIENT_HEADER = "x-uptimizr-client";
+/**
+ * Whether this request is "the dashboard's own session" — the requests the
+ * audit log deliberately skips so an agent's activity is not buried under a
+ * dashboard's panel refreshes.
+ *
+ * It is identified by the `x-uptimizr-client: dashboard` header that
+ * `@uptimizr/react`'s `CollectorApi` sets by default; the in-browser assistant
+ * and any other agent client send a different value (or none) and are audited.
+ *
+ * This is a **volume filter, not a security boundary**: anyone holding the key
+ * could send the header, and anyone holding the key can already do everything
+ * the key allows. Set `AUDIT_DASHBOARD_REQUESTS=1` to record every
+ * authenticated request without exception.
+ */
+export declare function isDashboardRequest(request: FastifyRequest): boolean;
+/**
+ * Resolve the request's `x-api-key` into {@link FastifyRequest.resolvedKey}.
+ * Never replies and never throws: an absent, unknown or revoked key simply
+ * leaves `resolvedKey` null, and the helpers below turn that into a 401.
+ */
+export declare function attachApiKey(request: FastifyRequest, store: CollectorStore): Promise<void>;
+/**
+ * Require an authenticated key holding `capability`. Sends a 401 (no/invalid
+ * key) or 403 (key lacks the capability) and returns `null` on refusal.
+ *
+ * Reads are always scoped to the authenticated project — a client-supplied
+ * project id is never trusted.
+ */
+export declare function requireCapability(request: FastifyRequest, reply: FastifyReply, store: CollectorStore, capability: ApiKeyCapability): Promise<ResolvedApiKey | null>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB;;;;;WAKG;QACH,WAAW,EAAE,cAAc,GAAG,IAAI,CAAC;QACnC,6EAA6E;QAC7E,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;KAC9B;CACF;AAED,kFAAkF;AAClF,eAAO,MAAM,aAAa,sBAAsB,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAEnE;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAQhG;AAUD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,cAAc,EACrB,UAAU,EAAE,gBAAgB,GAC3B,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAmBhC"}