@pithy-sh/audit 0.1.0

package/src/data/auditEvent.ts

@@ -0,0 +1,116 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+import {
+  AuditAction,
+  AuditActorType,
+  AuditMetadata,
+  AuditOutcome,
+  AuditSeverity,
+} from "@pithy-sh/core/src/audit/auditEvent";
+import { SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+
+/**
+ * The `pithy_audit_events` table — one row per recorded security-relevant action. One Zod object is
+ * the whole table definition: `z.output` is the app shape (a `Date` for `occurredAt`, a decoded
+ * object for `metadata`), `z.input` is the SQLite row shape (ms-epoch numbers, JSON strings), and
+ * every JS↔SQLite conversion goes through a codec. The taxonomy enums and the `action` validator are
+ * core's (`@pithy-sh/core/src/audit/auditEvent`) — the seam every emitter writes to; this table is
+ * how `@pithy-sh/audit` persists it.
+ *
+ * The `pithy_audit_` prefix (CamelCasePlugin snake-cases `pithyAuditEvents` → `pithy_audit_events`)
+ * keeps the table from clashing with an adopter's own (principle 1). `id` is an autoincrement
+ * surrogate giving natural event ordering; it is internal and never exposed over HTTP.
+ */
+/**
+ * The `metadata` column codec — the JSON ↔ object conversion, Zod-validated against {@link AuditMetadata}
+ * on both sides. Exported so the recorder encodes the column through the same codec it is read back
+ * with, rather than hand-rolling `JSON.stringify` (CLAUDE.md §Data layer).
+ */
+export const AuditMetadataColumn = sqliteJson(AuditMetadata);
+
+export const AuditEventRow = z
+  .object({
+    id: z
+      .number()
+      .int()
+      .describe(
+        "Autoincrement surrogate primary key. Monotonic, so it gives natural event ordering; internal, never exposed.",
+      ),
+    eventId: z
+      .string()
+      .describe(
+        "Client-generated unique idempotency key (a UUID), set by the recorder before the insert and held stable across `withD1Retry` attempts. The unique index turns a retry after a post-commit transport hiccup into a no-op (the guard fires) instead of a duplicate row.",
+      ),
+    occurredAt: SQLiteDate.describe(
+      "When the action occurred. Ms-epoch in SQLite, a `Date` in app code; indexed for time-range queries.",
+    ),
+    action: AuditAction.describe(
+      "What happened, as a namespaced `domain/reason` action code; indexed for per-action queries.",
+    ),
+    outcome: AuditOutcome.describe("Whether the action succeeded, failed, or was denied."),
+    severity: AuditSeverity.describe(
+      "How serious the event is, orthogonal to outcome; drives dashboard filtering and alerting.",
+    ),
+    actorType: AuditActorType.describe("The kind of principal that acted."),
+    actorId: z
+      .string()
+      .nullable()
+      .describe(
+        "The acting principal's stable id (user id, service/token name); null for `system`/`anonymous`. Indexed.",
+      ),
+    sessionId: z
+      .string()
+      .nullable()
+      .describe("The session this action belongs to, tying a chain of actions together; null when none."),
+    resourceType: z
+      .string()
+      .nullable()
+      .describe("The type of resource the action targeted (e.g. `user`, `secret`); null when not resource-scoped."),
+    resourceId: z
+      .string()
+      .nullable()
+      .describe("The id of the resource the action targeted; null when not resource-scoped."),
+    ip: z.string().nullable().describe("The client IP the request came from, for correlation; null when unknown."),
+    userAgent: z.string().nullable().describe("The client user-agent string, for correlation; null when unknown."),
+    requestId: z
+      .string()
+      .nullable()
+      .describe("The request correlation id, tying this event to one request/trace; null when unknown."),
+    metadata: AuditMetadataColumn.nullable().describe(
+      "Capability-specific structured detail as a JSON column, Zod-validated on write and read; null when there is none.",
+    ),
+    project: z
+      .string()
+      .nullable()
+      .describe(
+        "The project this event was recorded in, stamped by the recorder from the Worker's `PROJECT` var — never by the emitter, so it cannot be forged or omitted. Null on rows written before this column existed, and on a Worker carrying no `PROJECT` var.",
+      ),
+    environment: z
+      .string()
+      .nullable()
+      .describe(
+        "The environment the recording Worker serves (`dev` | `staging` | `prod`), stamped by the recorder from the `ENVIRONMENT` var. Null on rows written before this column existed. Recorded on the row rather than inferred from the database, because an exported or aggregated trail no longer knows which database it came from.",
+      ),
+    worker: z
+      .string()
+      .nullable()
+      .describe(
+        "The `apps/<name>` directory name of the Worker that recorded the event, stamped from the `WORKER` var; null for a CLI-originated action, which came from no Worker. Two Workers in one project share a database when they declare the same binding, so this is the only column that separates their events.",
+      ),
+    version: z
+      .string()
+      .nullable()
+      .describe(
+        'The Cloudflare version id of the build that recorded the event, stamped by the recorder from the `CF_VERSION_METADATA` binding. Null for a CLI-originated action, for a Worker that does not declare the binding, and on rows written before this column existed. It is what turns "this was revoked" into "this was revoked, by this subject, against this exact build".',
+      ),
+    tenant: z
+      .string()
+      .nullable()
+      .describe(
+        "Whose action it was — the id of the tenant it was taken *for*, indexed with `occurredAt` for the (tenant, time) read this column exists to serve. **Supplied by the emitter, not stamped by the recorder** — the opposite of the four columns above it, and deliberately: `project`, `environment` and `worker` are properties of the writer, constant across every row a multi-tenant Worker writes, and no Worker var can know which customer an action belonged to. So this one is exactly as trustworthy as the call site that sets it, and it cannot be defaulted or verified here. Null means *not tenant-scoped* — a single-tenant app, a CLI-originated action, a fleet-wide operator action — and on rows written before this column existed. Never derived from a membership table afterwards: the tenant of an action is a fact at the time of the action, membership is a fact now.",
+      ),
+  })
+  .describe("One audit event in `pithy_audit_events` — the durable, queryable record of a security-relevant action.");
+export type AuditEventRow = z.output<typeof AuditEventRow>;

package/src/data/tables.ts

@@ -0,0 +1,25 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { createDatabase, type DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import type { Kysely } from "kysely";
+import { AuditEventRow } from "./auditEvent";
+
+/**
+ * The audit capability's table map: camelCase keys (CamelCasePlugin emits the snake_case
+ * `pithy_audit_` SQL). One source of truth, shared by the capability wiring (`capability.ts`), the
+ * recorder, and the query helper so all three type against the same schema.
+ */
+export const auditTables = {
+  pithyAuditEvents: AuditEventRow,
+};
+export type AuditTables = typeof auditTables;
+
+/** The typed Kysely view over the audit table — what the recorder and query helper run against. */
+export type AuditDatabase = Kysely<DatabaseSchema<AuditTables>>;
+
+/** Build the audit Kysely over a D1 binding (or a REST `D1Database` from `@pithy-sh/cloudflare`). */
+export function auditDatabase(d1: D1Database): AuditDatabase {
+  return createDatabase(d1, auditTables);
+}

package/src/error/errors.ts

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+
+/**
+ * Audit recorder throw sugar. The `audit/*` codes live in core's closed `KitErrorPayload` union
+ * (CLAUDE.md §Errors: capabilities add their codes to the one union); these subclasses are the
+ * package-local vehicles that set one of those members — the same pattern as core's `NotFoundError`
+ * and `@pithy-sh/cloudflare`'s error classes. Runtime code here builds one of these, never a plain
+ * `new Error`.
+ *
+ * Both are recorded **non-fatally**: the recorder constructs one to represent a failure it logs, but
+ * never throws it into the audited action. `detail` carries throw-site context for logs; it is never
+ * serialized to a client (the HTTP codec strips it).
+ */
+
+/** Variable parts each subclass accepts; `code`/`status` are fixed by the subclass. */
+interface AuditErrorArgs {
+  /** Override the public, safe-to-expose message. */
+  message?: string;
+  /** A remediation hint (CLI action line). */
+  action?: string;
+  /** Internal context for logs + audit. Never serialized to clients. */
+  detail?: string;
+  /**
+   * Values a translating client interpolates into its own wording for this code. Client-facing, so —
+   * unlike `action` and `detail` — these cross the boundary with `message`.
+   */
+  params?: MessageParams;
+}
+
+/** An audit event failed validation against the `AuditEvent` schema (bad action, outcome, or actor). */
+export class AuditInvalidEventError extends PithyError {
+  constructor(args: AuditErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "audit/invalid_event",
+        status: 400,
+        message: args.message ?? "An audit event failed validation.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** Persisting an audit event to D1 failed after retries. Logged, never thrown to a client. */
+export class AuditWriteFailedError extends PithyError {
+  constructor(args: AuditErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "audit/write_failed",
+        status: 500,
+        message: args.message ?? "Failed to persist an audit event.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}

package/src/http/guards.ts

@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+import type { AdminRoute } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
+import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
+
+/**
+ * Audit's control-plane scopes, and the admin surface a manifest advertises.
+ *
+ * **Every route here is `control-plane`, every route here is a read, and there are no others.** The
+ * trail has no end-user surface — a user does not read the record of themselves being audited — so
+ * there is nothing for `requireAuth()` to gate, and putting it on these routes would deny every
+ * legitimate management call permanently: the seam deliberately leaves `c.var.auth` null for a
+ * control-plane caller, and no credential could ever satisfy it. The gate is imported from core
+ * rather than copied, because core is a hard dependency of every capability, so importing it cannot
+ * leave a deployment without one; with the seam uncomposed `requireControlPlane` raises
+ * `controlplane/not_connected` rather than passing.
+ *
+ * **Nothing here writes.** The trail is append-only by construction and stays that way: there is no
+ * delete route, no edit route, and no retention control on this surface. A management credential that
+ * could erase an audit row is a management credential that can erase the evidence of its own use.
+ *
+ * ## Two read scopes, because two reads disclose different things
+ *
+ * The tempting shape is one `audit:read`. It is wrong on the merits for the same reason a single
+ * `payments:admin` flag was: it makes the safe operation and the dangerous one the same grant.
+ *
+ * A **page of the trail** answers who did what, when, and whether it worked. That is the "recent
+ * activity" pane, it is what an operator looks at all day, and its projection carries no network
+ * identifier and no capability payload.
+ *
+ * **One event in full** additionally carries the client IP, the user-agent, and the capability's own
+ * `metadata` bag — which routinely holds the email address, the resource name, or the reason a
+ * capability recorded alongside its event. Bulk-harvesting those over a whole trail is a privacy
+ * incident, and requiring a second scope is what makes it a decision the adopter makes rather than
+ * one a listing credential comes with. Since the two are separate routes, a credential holding only
+ * the detail scope cannot enumerate the trail to find ids to read, and a credential holding only the
+ * list scope cannot resolve one. `scopeCovers` matches exactly — no prefix, no wildcard — so holding
+ * one confers nothing about the other.
+ *
+ * The names are constants rather than config: a configurable scope name is a way to misconfigure a
+ * default-denied gate into a differently-named one, and they are the join key with what
+ * `pithy dashboard connect` offers an adopter to grant.
+ */
+
+/**
+ * Page the trail: who acted, what they did, when, against what, and whether it was allowed. The
+ * everyday read, and deliberately the one that carries no IP address and no capability metadata.
+ */
+export const AUDIT_TRAIL_READ_SCOPE: ControlPlaneScope = "audit:events:read";
+
+/**
+ * Read one event in full — the client IP, the user-agent, and the capability's `metadata` bag with it.
+ * The forensic read, and the more dangerous of the two: this is where the trail's personal data is.
+ */
+export const AUDIT_EVENT_DETAIL_READ_SCOPE: ControlPlaneScope = "audit:events:read_detail";
+
+/**
+ * Every control-plane scope audit defines — what `pithy dashboard connect` offers for this capability,
+ * and the list a manifest or a doc quotes rather than re-typing.
+ */
+export const AUDIT_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[] = [
+  AUDIT_TRAIL_READ_SCOPE,
+  AUDIT_EVENT_DETAIL_READ_SCOPE,
+];
+
+/**
+ * Audit's management surface, as `GET /control-plane/manifest` reports it.
+ *
+ * Declared beside the scopes so the scope a route demands and the scope a manifest advertises are the
+ * same constant, read from one place. `basePath` is a parameter and never a default: an adopter who
+ * mounted audit at `/trail` must get a manifest naming `/trail/events`, or a client composing its
+ * calls from the manifest would 404 against exactly the adopters who customized anything.
+ *
+ * The summaries say what the operation is *for*. A client renders these beside a pane somebody is
+ * about to open over other people's activity.
+ */
+export function auditAdminRoutes(basePath: string): AdminRoute[] {
+  return [
+    {
+      method: "GET",
+      path: `${basePath}/events`,
+      scope: AUDIT_TRAIL_READ_SCOPE,
+      summary:
+        "Page the trail, newest first, filtered by actor, action, resource, outcome, severity, origin, and time.",
+    },
+    {
+      method: "GET",
+      path: `${basePath}/events/:eventId`,
+      scope: AUDIT_EVENT_DETAIL_READ_SCOPE,
+      summary: "Read one event in full, including the client IP, user-agent, and capability metadata.",
+    },
+  ];
+}

package/src/http/responses.ts

@@ -0,0 +1,101 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+import { AuditActorType, AuditMetadata, AuditOutcome, AuditSeverity } from "@pithy-sh/core/src/audit/auditEvent";
+import { z } from "zod";
+
+/**
+ * What the audit routes return, as Zod objects a management client can validate against.
+ *
+ * `schemas.ts` bounds what a caller may send; this file states what it gets back. Both halves of the
+ * contract are runtime values for the same reason: a client reading a customer's Worker is crossing a
+ * trust boundary in *both* directions, and a TypeScript interface is erased before it can help — it
+ * cannot check a response, so every client that had only an interface hand-wrote a mirror of it, and
+ * the mirror drifted the first time a field landed here.
+ *
+ * **No codecs, and no transform anywhere in this file.** These schemas describe JSON on the wire, so
+ * parsing one must hand back exactly what went in — that is what lets `responses.test.ts` compare the
+ * parsed value with the projection's output and fail on a field either side forgot. A `SQLiteDate`
+ * here would decode an ISO string into a `Date` and quietly make that comparison meaningless.
+ *
+ * The projections that fill these live in `views.ts`, which documents *why* each field is in one view
+ * and not the other. This file is the shape; that file is the argument.
+ *
+ * **A field added here later is `.optional()`, not merely `.nullable()`.** This module is read across a
+ * version boundary — a management client validates a response with this schema against a customer's
+ * Worker at whatever kit version it is on — so an additive required key fails `safeParse` for everyone
+ * below that release and takes the whole pane with it (#450). Absent then means *this Worker cannot
+ * say*, which is a different fact from `null`.
+ */
+
+/** Where a page resumes, or the end of the list. */
+const NextCursor = z
+  .string()
+  .nullable()
+  .describe("Where the next page resumes. Null at the end of the list. Opaque — pass it back verbatim.");
+
+/**
+ * One event as the listing shows it — everything but the network identifiers and the metadata bag.
+ *
+ * The type is derived from this object rather than declared beside it, so a field cannot exist in one
+ * and not the other.
+ */
+export const AuditEventView = z
+  .object({
+    eventId: z.string().describe("The event's stable public id (the recorder's UUID)."),
+    occurredAt: z.iso.datetime().describe("When it happened, ISO-8601."),
+    action: z.string().describe("The `domain/reason` action code."),
+    outcome: AuditOutcome.describe("Whether it succeeded, failed, or was denied."),
+    severity: AuditSeverity.describe("How serious it is, orthogonal to the outcome."),
+    actorType: AuditActorType.describe("The kind of principal that acted."),
+    actorId: z.string().nullable().describe("The acting principal's stable id, or null."),
+    sessionId: z.string().nullable().describe("The session the action belongs to — a row id, never a token — or null."),
+    resourceType: z.string().nullable().describe("The kind of thing acted on, or null."),
+    resourceId: z.string().nullable().describe("The thing acted on, or null."),
+    requestId: z.string().nullable().describe("The request correlation id, or null."),
+    project: z.string().nullable().describe("The project the recorder stamped, or null when it recorded none."),
+    environment: z.string().nullable().describe("The environment the recording Worker served, or null."),
+    worker: z.string().nullable().describe("The `apps/<name>` Worker that recorded it, or null for a CLI action."),
+    version: z.string().nullable().describe("The Cloudflare build id that recorded it, or null."),
+    tenant: z
+      .string()
+      .nullable()
+      .describe("The tenant the action was taken for, or null when it was not tenant-scoped."),
+  })
+  .describe("One audit event as the listing shows it. No client IP, no user-agent, no metadata bag.");
+export type AuditEventView = z.output<typeof AuditEventView>;
+
+/**
+ * One event in full — the listing view plus the three fields the detail scope exists to separate.
+ *
+ * Re-described after `.extend()`: extending builds a new schema, and a description does not follow it.
+ */
+export const AuditEventDetailView = AuditEventView.extend({
+  ip: z
+    .string()
+    .nullable()
+    .describe("The client IP the request came from, or null. Personal data; behind its own scope."),
+  userAgent: z
+    .string()
+    .nullable()
+    .describe("The client user-agent, or null. A device fingerprint; behind its own scope."),
+  metadata: AuditMetadata.nullable().describe(
+    "The capability's own structured detail, or null. Arbitrary payload; behind its own scope.",
+  ),
+}).describe("One audit event in full — the listing view plus the client IP, user-agent, and metadata bag.");
+export type AuditEventDetailView = z.output<typeof AuditEventDetailView>;
+
+/** `GET {base}/events`. */
+export const AuditEventsResponse = z
+  .object({
+    events: z.array(AuditEventView).describe("The page, newest first."),
+    nextCursor: NextCursor,
+  })
+  .describe("A filtered, resumable page of the audit trail.");
+export type AuditEventsResponse = z.output<typeof AuditEventsResponse>;
+
+/** `GET {base}/events/:eventId`. */
+export const AuditEventResponse = z
+  .object({ event: AuditEventDetailView.describe("The event, with the fields the detail scope gates.") })
+  .describe("One audit event in full.");
+export type AuditEventResponse = z.output<typeof AuditEventResponse>;

package/src/http/routes.ts

@@ -0,0 +1,206 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+import { zValidator } from "@hono/zod-validator";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import type { ControlPlaneContext } from "@pithy-sh/core/src/controlPlane/context";
+import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
+import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
+import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import { validationHook } from "@pithy-sh/core/src/http/validation";
+import type { VerificationStrategy } from "@pithy-sh/core/src/http/verification";
+import type { Context, Hono } from "hono";
+import { AuditTrailActions } from "../actions";
+import type { AuditDatabase } from "../data/tables";
+import { pageAuditEvents, readAuditEvent } from "../query";
+import { AUDIT_EVENT_DETAIL_READ_SCOPE, AUDIT_TRAIL_READ_SCOPE } from "./guards";
+import type { AuditEventResponse, AuditEventsResponse } from "./responses";
+import { AuditEventIdParam, ListAuditEventsQuery } from "./schemas";
+import { auditEventDetailView, auditEventView } from "./views";
+
+/**
+ * The audit routes, their verification strategies, and what each accepts:
+ *
+ *   GET /audit/events           → a page of the trail   (control-plane: audit:events:read)        query: ListAuditEventsQuery
+ *   GET /audit/events/:eventId  → one event in full     (control-plane: audit:events:read_detail) param: AuditEventIdParam
+ *
+ * **Both are reads, and there is nothing else.** The trail is append-only: no route here deletes,
+ * edits, or prunes, because a management credential that could erase an audit row could erase the
+ * evidence of its own use. Retention is a lifecycle concern for a Workflow, not a button on a
+ * dashboard.
+ *
+ * **Neither has an end-user surface.** A user does not call the record of themselves being audited,
+ * so `requireAuth()` appears nowhere in this file — and must not: the seam leaves `c.var.auth` null
+ * for a control-plane caller by design, so an auth gate would deny every legitimate management call
+ * permanently, with no credential able to fix it.
+ *
+ * **Validators sit after the gate on both lines.** A validator ahead of it turns a 403 into a 400 and
+ * tells an unverified caller which requests were well-formed — here that is a live oracle for which
+ * projects, Workers, and action codes this deployment records.
+ */
+
+/**
+ * What every route this capability mounts declares: its path, its strategy, and the scope it checks.
+ *
+ * Exported so a test asserts against the declaration rather than against a middleware count. Counting
+ * `app.routes` entries proves that *something* runs before the handler — a bare `zValidator` satisfies
+ * it — and cannot prove *what*. This is a declaration, so it can drift from the router;
+ * `routeContract.test.ts` checks it against Hono in both directions, so a route added without an entry
+ * and an entry naming no route both fail.
+ */
+export interface AuditRouteDeclaration {
+  readonly method: "GET";
+  /** The path relative to the configured `basePath`, e.g. `/events`. */
+  readonly path: string;
+  readonly strategy: VerificationStrategy;
+  /** The control-plane scope this route checks. */
+  readonly scope: ControlPlaneScope;
+}
+
+/** Every route, and how it is gated. */
+export const AUDIT_ROUTES: readonly AuditRouteDeclaration[] = [
+  { method: "GET", path: "/events", strategy: "control-plane", scope: AUDIT_TRAIL_READ_SCOPE },
+  { method: "GET", path: "/events/:eventId", strategy: "control-plane", scope: AUDIT_EVENT_DETAIL_READ_SCOPE },
+];
+
+/** How the audit sub-router is built. */
+export interface AuditRoutesOptions {
+  /**
+   * The path the routes mount under — **required, with no fallback here**. The default lives in
+   * `AuditConfig`, and the capability passes its resolved value to both this and `auditAdminRoutes`,
+   * so the mounted path and the advertised path are one value read twice rather than two defaults
+   * that can drift apart.
+   */
+  basePath: string;
+  /** The audit database for this request — resolved by the capability, which owns the registry key. */
+  database: (c: Context<PithyHonoEnv>) => AuditDatabase;
+}
+
+/**
+ * The verified management client behind a control-plane call.
+ *
+ * `requireControlPlane()` has run on every route in this file, so `c.var.controlPlane` is populated by
+ * the time a handler reads it. The throw is a programming-error guard, not a runtime path: reaching it
+ * would mean a route was mounted without its gate, which is the one mistake this file is arranged to
+ * make impossible.
+ */
+function caller(c: Context<PithyHonoEnv>): ControlPlaneContext {
+  const context = c.var.controlPlane;
+  if (!context) {
+    throw new InternalError({
+      message: "Audit could not identify the management caller.",
+      detail: "requireControlPlane() must run before an audit handler reads the caller.",
+    });
+  }
+  return context;
+}
+
+/**
+ * The filter, as the audit trail should record that it was asked.
+ *
+ * Built here rather than inline in the `metadata:` literal for two reasons. It keeps dates as ISO
+ * strings — a `Date` would round-trip out of the JSON column as a string anyway, so writing one is a
+ * silent type change. And `metadata` may not carry top-level keys that name a column (`project`,
+ * `environment`, `worker`, `tenant`); nesting the filter under one key keeps the record of *what was
+ * asked for* distinct from the record of *where the reading happened* and *whose events these were*,
+ * which is what those columns mean. A `tenant` here is a filter the caller typed, not the tenant this
+ * read belonged to — collapsing the two would make the trail lie about its own reads.
+ */
+function askedFor(query: ListAuditEventsQuery): Record<string, unknown> {
+  const { from, to, cursor, ...rest } = query;
+  return {
+    ...rest,
+    ...(from ? { from: from.toISOString() } : {}),
+    ...(to ? { to: to.toISOString() } : {}),
+    // The cursor's value is noise in a trail; whether the caller was paging is not.
+    resumed: cursor !== undefined,
+  };
+}
+
+/** Register the audit sub-router. Returned as the capability's `routes` hook. */
+export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<PithyHonoEnv>) => void {
+  const base = options.basePath;
+  const database = options.database;
+
+  return (app) => {
+    /**
+     * CONTROL-PLANE READ. A filtered, resumable page of the trail — keyset, never offset, because the
+     * table is appended to while it is being read and an offset page silently skips records.
+     */
+    app.get(
+      `${base}/events`,
+      requireControlPlane(AUDIT_TRAIL_READ_SCOPE),
+      zValidator("query", ListAuditEventsQuery, validationHook),
+      async (c) => {
+        const operator = caller(c);
+        const query = c.req.valid("query");
+        const page = await pageAuditEvents(database(c), query);
+        // Audited *after* the read, so `returned` is the truth rather than an intention, and audited at
+        // all because reading the record of everyone else's actions is itself one. Core's guard already
+        // recorded that the call was allowed; what it cannot know is what was asked for and how much
+        // came back, which is the difference between "an operator opened the pane" and "something
+        // paged the entire trail".
+        await c.var.emit({
+          action: AuditTrailActions.trailRead,
+          outcome: "success",
+          actorType: "control-plane",
+          actorId: operator.subject,
+          resourceType: "audit_trail",
+          requestId: c.req.header("cf-ray"),
+          ip: c.req.header("cf-connecting-ip"),
+          userAgent: c.req.header("user-agent"),
+          metadata: {
+            connectionId: operator.connectionId,
+            query: askedFor(query),
+            returned: page.events.length,
+            more: page.nextCursor !== null,
+          },
+        });
+        // `satisfies`, not `.parse()`. The check belongs at compile time: parsing every response would
+        // spend a validation pass on data this Worker just built from its own rows, and it would turn a
+        // shape mistake into a 500 in production rather than a red build.
+        return c.json(
+          { events: page.events.map(auditEventView), nextCursor: page.nextCursor } satisfies AuditEventsResponse,
+          200,
+        );
+      },
+    );
+
+    /**
+     * CONTROL-PLANE READ, the forensic one. Returns the client IP, the user-agent, and the capability's
+     * metadata bag, which is why it sits behind its own scope rather than the listing's.
+     */
+    app.get(
+      `${base}/events/:eventId`,
+      requireControlPlane(AUDIT_EVENT_DETAIL_READ_SCOPE),
+      zValidator("param", AuditEventIdParam, validationHook),
+      async (c) => {
+        const operator = caller(c);
+        const { eventId } = c.req.valid("param");
+        const row = await readAuditEvent(database(c), eventId);
+        // Recorded whether or not the event existed, and with the same `resourceId` either way. A read
+        // that found nothing is still somebody asking after a specific event, and a miss that went
+        // unrecorded would make probing for ids the one action on this surface that leaves no trace.
+        await c.var.emit({
+          action: AuditTrailActions.eventRead,
+          outcome: row ? "success" : "failure",
+          actorType: "control-plane",
+          actorId: operator.subject,
+          resourceType: "audit_event",
+          resourceId: eventId,
+          requestId: c.req.header("cf-ray"),
+          ip: c.req.header("cf-connecting-ip"),
+          userAgent: c.req.header("user-agent"),
+          metadata: { connectionId: operator.connectionId, found: row !== null },
+        });
+        if (!row) {
+          throw new NotFoundError({
+            message: "No audit event with that id.",
+            action: "Check the eventId against a page from GET /events.",
+          });
+        }
+        return c.json({ event: auditEventDetailView(row) } satisfies AuditEventResponse, 200);
+      },
+    );
+  };
+}