Config
| Key | Default | |
|---|---|---|
database | DB | The D1 binding the table and its migrations target |
basePath | /audit | Where the control-plane read routes mount |
sinks | {} | The sinks the trail ships to, by kebab-case name. Each takes profile (splunk-hec, datadog-logs or webhook), an HTTPS url, the secret name its token is read through, an optional actions prefix list, and detail, false by default. Strict: an unknown profile or key, a URL that is not HTTPS, or a missing secret name is refused at config load |
Three optional bindings beside it. AUDIT_CHECKPOINTS is the R2 bucket the chain’s checkpoints are written to and read back from, <project>-<env>-audit-checkpoints, which pithy provision creates. AUDIT_CHECKPOINT is the checkpoint Workflow, hosted by the prebuilt audit host Worker and fired hourly by its cron. AUDIT_PRUNE is the retention prune, a Workflow class your own Worker exports from @pithy-sh/audit/src/workflows/prune and binds beside the daily 0 2 * * * cron; unbound, nothing is pruned. Without the bucket every event is still recorded and chained, a verify says checkpointStore: "absent", and nothing chained is pruned. Tamper evidence has what the first two are for, and Retention the third.
Two more only when a sink is declared. AUDIT_SHIP is the queue each event is enqueued on once per sink that takes it, consumed by the app Worker’s own queue handler, with max_retries 10, max_batch_size 50 and AUDIT_SHIP_DLQ as its dead-letter queue. Both are <project>-<env>-<binding>, created by pithy provision. A Worker that declares a sink also depends on secrets. Shipping the trail has what each one is for.
The shape below is the event model as columns. What each field means, and which of them the emitter cannot set, is on that page.
The row
| Column | Nullable | |
|---|---|---|
id | Autoincrement surrogate. Internal, never exposed | |
eventId | A UUID minted before the insert — the idempotency key | |
occurredAt | Ms-epoch in SQLite, a Date in app code. Indexed | |
action | domain/reason. Indexed | |
outcome | ||
severity | ||
actorType | ||
actorId | ✓ | Indexed |
actorKind | ✓ | Which kind of client acted. For a control-plane actor, stamped from the connection; for a user actor, agent on an MCP tool call. Added by audit_0002_actor_kind |
sessionId | ✓ | |
resourceType, resourceId | ✓ | |
ip, userAgent | ✓ | Correlation |
requestId | ✓ | Correlation. Indexed by audit_0004_request_index |
metadata | ✓ | A JSON object, validated both ways |
project, environment, worker | ✓ | Stamped by the recorder |
version | ✓ | |
tenant | ✓ | Supplied by the emitter |
chainSeq | ✓ | The event’s 1-based position in its tenant’s hash chain. Null on a row written before the chain, which is its mark. Added by audit_0005_chain, and the one chain column the listing returns |
chainPrev, chainHash | ✓ | The hash of the event before it, and its own over the canonical serialization. Stamped by the recorder |
chainSalt | ✓ | The per-event salt the IP, user-agent and metadata are committed under. Stamped by the recorder |
Two indexes serve a credential’s reach. audit_0003_call_index indexes action, resourceId and occurredAt together, so one connection’s calls in a window are a range read — the one a connection’s usage counts over too. audit_0004_request_index indexes requestId, so each call finds its handler’s events in the same request. Two more hold the chain. audit_0005_chain adds a unique index on tenant and chainSeq, and one on chainSeq alone for the events with no tenant, so no chain holds two events at one position and the verify walk reads either kind in chain order.
Shipping keeps its state beside the trail. audit_0006_sinks creates pithy_audit_sinks, one row per declared sink keyed by its name: lastDeliveredAt, lastFailedAt, retrying and deadLettered. Nothing in it is the trail, and nothing in the trail changes.
Enums
Outcome — success · failure · denied
Severity — info · warning · critical. Defaults to info.
Actor type — user · service · system · anonymous · control-plane
Actor kind — agent · dashboard · script. On a control-plane row, null where the connection recorded none; on a user row, agent for an MCP tool call and null otherwise
Scopes
| Scope | Grants |
|---|---|
audit:events:read | The listing, the access history, a credential’s reach, a connection’s usage, and each sink’s delivery state. No ip, no userAgent, no metadata beyond the named keys the access history, the reach and the usage read |
audit:events:read_detail | One event in full. With audit:events:export, the personal values in an export too |
audit:events:export | The chain’s verify and its export. Values only beside the detail scope; their commitments otherwise |
Matched exactly. Holding one implies neither of the others.
Routes
GET /audit/events | Keyset paged, newest first. Returns nextCursor |
GET /audit/events/:eventId | |
GET /audit/control-plane/access-history | Every membership, connection and key change in a since–until window, with its before and after. Keyset paged, oldest first. Returns nextCursor |
GET /audit/control-plane/reach | What one connection’s calls reached in a since–until window, by tenant, route, action, method and outcome. route with subjects=true adds that route’s subjects. One answer, not paged |
GET /audit/control-plane/usage | One connection’s calls in a since–until window, counted by scope and key, admitted and refused, with oldestEventAt beside the rows. With no connectionId, every connection that called in the window, each with its own rows, as connections. One answer, not paged |
GET /audit/control-plane/sinks | Every declared sink in declaration order: its name, profile, host, detail flag and actions filter, and its lastDeliveredAt, lastFailedAt, retrying, deadLettered and delivery state. Never a token, a secret name, a URL path or query. One answer, not paged |
GET /audit/control-plane/verify | Whether one tenant’s chain is whole over a since–until window, against its checkpoints, or its first break. tenant required, empty for the untenanted chain. One answer, not paged |
GET /audit/control-plane/export | One tenant’s chain in canonical form, with the link before the page and the checkpoints covering it. Paged by cursor, 500 events by default and 1000 at most. Returns nextCursor |
All eight are reads. There is no ninth route. Querying the trail covers the scopes, the keyset pages, the filter, the access history, a credential’s reach and a connection’s usage, tamper evidence the verify and the export, and shipping the trail the sinks; the shape these eight share with every other route in the kit is on HTTP routes.
Health keys
Declared on audit’s manifest entry only when a sink is, all behind audit:events:read, each read by primary key from pithy_audit_sinks.
| Key | Kind | |
|---|---|---|
auditShipBacklog | count | Events waiting on a retry, across every sink. Nominal at 0 |
auditShipDeadLettered | count | Events whose retries ran out and went to the dead-letter queue, across every sink. Nominal at 0 |
auditShipDelivery | state | delivering, failing or idle. Nominal at delivering and idle |
GET /audit/control-plane/sinks answers the same per sink, behind the same scope: each sink’s retrying and deadLettered are what the first two keys sum, and its delivery is the third over that sink’s row alone.
Actions this capability emits about itself
| Action | |
|---|---|
audit/trail_read | The filter, and how much came back |
audit/event_read | Which event was asked for |
audit/access_history_read | The window, whether it resumed from a cursor, and how much came back |
audit/reach_read | The connection read, the window, the key and route it was narrowed to, whether it expanded the subjects, and how much came back |
audit/usage_read | The connection read, the window, and how many rows came back. A read that named no connection records connectionId: null and lists in connections every connection the answer covered |
audit/chain_verified | The tenant and window walked, how many events and checkpoints were checked, and the break if there was one. A break is recorded at critical, with outcome failure |
audit/chain_exported | The tenant and window, whether it resumed from a cursor, whether the values went out, and how many events came back |
Recorded including the reads that found nothing. The sinks read records no audit/* action: it reads delivery state, never the trail, and the gate’s controlplane/call_allowed row already records the call.
Error codes
Each is domain/reason, and they read the way every error code in the kit does.
| Code | |
|---|---|
audit/invalid_event | The event did not validate |
audit/write_failed | The insert failed. The audited action still succeeded |
Not implemented
A dedicated database by default. Deferred: the trail defaults to the shared app database, and pointing it at its own binding is yours to do. A signature over an export is not built either: an export is verified against its chain and its checkpoints, and nothing in it is signed.