Audit reference

Config

KeyDefault
databaseDBThe D1 binding the table and its migrations target
basePath/auditWhere 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

ColumnNullable
idAutoincrement surrogate. Internal, never exposed
eventIdA UUID minted before the insert — the idempotency key
occurredAtMs-epoch in SQLite, a Date in app code. Indexed
actiondomain/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

ScopeGrants
audit:events:readThe 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_detailOne event in full. With audit:events:export, the personal values in an export too
audit:events:exportThe 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/eventsKeyset paged, newest first. Returns nextCursor
GET /audit/events/:eventId
GET /audit/control-plane/access-historyEvery 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/reachWhat 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/usageOne 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/sinksEvery 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/verifyWhether 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/exportOne 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.

KeyKind
auditShipBacklogcountEvents waiting on a retry, across every sink. Nominal at 0
auditShipDeadLetteredcountEvents whose retries ran out and went to the dead-letter queue, across every sink. Nominal at 0
auditShipDeliverystatedelivering, 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_readThe filter, and how much came back
audit/event_readWhich event was asked for
audit/access_history_readThe window, whether it resumed from a cursor, and how much came back
audit/reach_readThe connection read, the window, the key and route it was narrowed to, whether it expanded the subjects, and how much came back
audit/usage_readThe 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_verifiedThe 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_exportedThe 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_eventThe event did not validate
audit/write_failedThe 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.

License

ESC