@pithy-sh/audit 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +93 -0
- package/dist/accessHistory.d.ts +315 -0
- package/dist/accessHistory.d.ts.map +1 -0
- package/dist/accessHistory.js +299 -0
- package/dist/actions.d.ts +15 -1
- package/dist/actions.d.ts.map +1 -1
- package/dist/actions.js +16 -2
- package/dist/capability.d.ts +14 -0
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +106 -12
- package/dist/chain/append.d.ts +43 -0
- package/dist/chain/append.d.ts.map +1 -0
- package/dist/chain/append.js +110 -0
- package/dist/chain/checkpoint.d.ts +70 -0
- package/dist/chain/checkpoint.d.ts.map +1 -0
- package/dist/chain/checkpoint.js +133 -0
- package/dist/chain/lockCheck.d.ts +15 -0
- package/dist/chain/lockCheck.d.ts.map +1 -0
- package/dist/chain/lockCheck.js +75 -0
- package/dist/chain/prune.d.ts +84 -0
- package/dist/chain/prune.d.ts.map +1 -0
- package/dist/chain/prune.js +231 -0
- package/dist/chain/rows.d.ts +74 -0
- package/dist/chain/rows.d.ts.map +1 -0
- package/dist/chain/rows.js +133 -0
- package/dist/chain/tombstone.d.ts +21 -0
- package/dist/chain/tombstone.d.ts.map +1 -0
- package/dist/chain/tombstone.js +98 -0
- package/dist/chain/verify.d.ts +63 -0
- package/dist/chain/verify.d.ts.map +1 -0
- package/dist/chain/verify.js +220 -0
- package/dist/citations.d.ts +17 -0
- package/dist/citations.d.ts.map +1 -0
- package/dist/citations.js +48 -0
- package/dist/cli/emitFromCLI.d.ts +5 -0
- package/dist/cli/emitFromCLI.d.ts.map +1 -1
- package/dist/cli/emitFromCLI.js +5 -0
- package/dist/data/auditEvent.d.ts +4 -0
- package/dist/data/auditEvent.d.ts.map +1 -1
- package/dist/data/auditEvent.js +7 -3
- package/dist/data/sinkState.d.ts +23 -0
- package/dist/data/sinkState.d.ts.map +1 -0
- package/dist/data/sinkState.js +25 -0
- package/dist/data/tables.d.ts +14 -1
- package/dist/data/tables.d.ts.map +1 -1
- package/dist/data/tables.js +5 -1
- package/dist/http/guards.d.ts +39 -6
- package/dist/http/guards.d.ts.map +1 -1
- package/dist/http/guards.js +101 -17
- package/dist/http/responses.d.ts +503 -0
- package/dist/http/responses.d.ts.map +1 -1
- package/dist/http/responses.js +157 -5
- package/dist/http/routes.d.ts +25 -3
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +321 -15
- package/dist/http/schemas.d.ts +67 -0
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +88 -4
- package/dist/http/views.d.ts +25 -1
- package/dist/http/views.d.ts.map +1 -1
- package/dist/http/views.js +107 -2
- package/dist/migrations/0003_call_index.d.ts +21 -0
- package/dist/migrations/0003_call_index.d.ts.map +1 -0
- package/dist/migrations/0003_call_index.js +33 -0
- package/dist/migrations/0004_request_index.d.ts +16 -0
- package/dist/migrations/0004_request_index.d.ts.map +1 -0
- package/dist/migrations/0004_request_index.js +24 -0
- package/dist/migrations/0005_chain.d.ts +24 -0
- package/dist/migrations/0005_chain.d.ts.map +1 -0
- package/dist/migrations/0005_chain.js +43 -0
- package/dist/migrations/0006_sinks.d.ts +11 -0
- package/dist/migrations/0006_sinks.d.ts.map +1 -0
- package/dist/migrations/0006_sinks.js +20 -0
- package/dist/provision/resolveAuditConfig.d.ts +31 -0
- package/dist/provision/resolveAuditConfig.d.ts.map +1 -0
- package/dist/provision/resolveAuditConfig.js +43 -0
- package/dist/purge/contribution.d.ts +21 -0
- package/dist/purge/contribution.d.ts.map +1 -0
- package/dist/purge/contribution.js +41 -0
- package/dist/reach.d.ts +250 -0
- package/dist/reach.d.ts.map +1 -0
- package/dist/reach.js +244 -0
- package/dist/recorder.d.ts +11 -0
- package/dist/recorder.d.ts.map +1 -1
- package/dist/recorder.js +23 -5
- package/dist/routePattern.d.ts +60 -0
- package/dist/routePattern.d.ts.map +1 -0
- package/dist/routePattern.js +130 -0
- package/dist/seeds/example.d.ts.map +1 -1
- package/dist/seeds/example.js +23 -6
- package/dist/ship/consumer.d.ts +45 -0
- package/dist/ship/consumer.d.ts.map +1 -0
- package/dist/ship/consumer.js +141 -0
- package/dist/ship/event.d.ts +59 -0
- package/dist/ship/event.d.ts.map +1 -0
- package/dist/ship/event.js +77 -0
- package/dist/ship/health.d.ts +33 -0
- package/dist/ship/health.d.ts.map +1 -0
- package/dist/ship/health.js +80 -0
- package/dist/ship/profiles.d.ts +34 -0
- package/dist/ship/profiles.d.ts.map +1 -0
- package/dist/ship/profiles.js +62 -0
- package/dist/ship/queue.d.ts +57 -0
- package/dist/ship/queue.d.ts.map +1 -0
- package/dist/ship/queue.js +70 -0
- package/dist/ship/secrets.d.ts +7 -0
- package/dist/ship/secrets.d.ts.map +1 -0
- package/dist/ship/secrets.js +40 -0
- package/dist/ship/shipper.d.ts +15 -0
- package/dist/ship/shipper.d.ts.map +1 -0
- package/dist/ship/shipper.js +27 -0
- package/dist/ship/sinks.d.ts +54 -0
- package/dist/ship/sinks.d.ts.map +1 -0
- package/dist/ship/sinks.js +45 -0
- package/dist/ship/state.d.ts +27 -0
- package/dist/ship/state.d.ts.map +1 -0
- package/dist/ship/state.js +29 -0
- package/dist/usage.d.ts +159 -0
- package/dist/usage.d.ts.map +1 -0
- package/dist/usage.js +87 -0
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/dist/workflows/prune.d.ts +73 -0
- package/dist/workflows/prune.d.ts.map +1 -0
- package/dist/workflows/prune.js +128 -0
- package/dist/workflows/retryPolicy.d.ts +10 -0
- package/dist/workflows/retryPolicy.d.ts.map +1 -0
- package/dist/workflows/retryPolicy.js +14 -0
- package/dist/workflows/specs.d.ts +70 -0
- package/dist/workflows/specs.d.ts.map +1 -0
- package/dist/workflows/specs.js +70 -0
- package/dist/workflows/worker.d.ts +32 -0
- package/dist/workflows/worker.d.ts.map +1 -0
- package/dist/workflows/worker.js +41 -0
- package/package.json +5 -2
- package/pithy.manifest.json +36 -4
- package/src/accessHistory.ts +360 -0
- package/src/actions.ts +15 -1
- package/src/capability.ts +134 -12
- package/src/chain/append.ts +161 -0
- package/src/chain/checkpoint.ts +172 -0
- package/src/chain/lockCheck.ts +72 -0
- package/src/chain/prune.ts +340 -0
- package/src/chain/rows.ts +211 -0
- package/src/chain/tombstone.ts +104 -0
- package/src/chain/verify.ts +366 -0
- package/src/citations.ts +62 -0
- package/src/cli/emitFromCLI.ts +5 -0
- package/src/cloudflare-test.d.ts +1 -0
- package/src/data/auditEvent.ts +31 -1
- package/src/data/sinkState.ts +41 -0
- package/src/data/tables.ts +7 -1
- package/src/http/guards.ts +90 -6
- package/src/http/responses.ts +318 -3
- package/src/http/routes.ts +379 -7
- package/src/http/schemas.ts +158 -2
- package/src/http/views.ts +123 -1
- package/src/migrations/0003_call_index.ts +35 -0
- package/src/migrations/0004_request_index.ts +26 -0
- package/src/migrations/0005_chain.ts +56 -0
- package/src/migrations/0006_sinks.ts +28 -0
- package/src/provision/resolveAuditConfig.ts +60 -0
- package/src/purge/contribution.ts +39 -0
- package/src/reach.ts +454 -0
- package/src/recorder.ts +64 -42
- package/src/routePattern.ts +141 -0
- package/src/seeds/example.ts +13 -0
- package/src/ship/consumer.ts +169 -0
- package/src/ship/event.ts +86 -0
- package/src/ship/health.ts +92 -0
- package/src/ship/profiles.ts +99 -0
- package/src/ship/queue.ts +108 -0
- package/src/ship/secrets.ts +42 -0
- package/src/ship/shipper.ts +32 -0
- package/src/ship/sinks.ts +82 -0
- package/src/ship/state.ts +61 -0
- package/src/usage.ts +176 -0
- package/src/version.generated.ts +1 -1
- package/src/workflows/prune.ts +196 -0
- package/src/workflows/retryPolicy.ts +14 -0
- package/src/workflows/specs.ts +92 -0
- package/src/workflows/worker.ts +65 -0
- package/src/workflows/wrangler.jsonc +40 -0
|
@@ -0,0 +1,366 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
|
|
4
|
+
import type { R2Bucket } from "@cloudflare/workers-types";
|
|
5
|
+
import {
|
|
6
|
+
AUDIT_CHAIN_FORMAT,
|
|
7
|
+
AUDIT_EXPORT_FORMAT,
|
|
8
|
+
type AuditChainExport,
|
|
9
|
+
type AuditCheckpoint,
|
|
10
|
+
type AuditTombstone,
|
|
11
|
+
type ChainBreak,
|
|
12
|
+
type ChainLink,
|
|
13
|
+
chainVerifier,
|
|
14
|
+
} from "@pithy-sh/core/src/audit/chain";
|
|
15
|
+
import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
|
|
16
|
+
import type { AuditDatabase } from "../data/tables";
|
|
17
|
+
import { listCheckpoints, readCheckpoints } from "./checkpoint";
|
|
18
|
+
import { chainedEventOf, readChainHead, readChainLink, readChainRows, whereChain } from "./rows";
|
|
19
|
+
import { readTombstones, tombstoneEndingAt } from "./tombstone";
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* **The verify and export reads over one tenant's chain (#822).**
|
|
23
|
+
*
|
|
24
|
+
* A range is asked for in time and walked in chain order. `since` resolves to the first position whose event
|
|
25
|
+
* occurred at or after it, `until` to the last at or before it, and everything between is walked — including an
|
|
26
|
+
* event whose `occurredAt` an emitter set outside the window, because a chain is contiguous in position and a
|
|
27
|
+
* walk that skipped one would report the gap as a break.
|
|
28
|
+
*/
|
|
29
|
+
|
|
30
|
+
/** How many rows one read of the walk takes. */
|
|
31
|
+
const WALK_PAGE = 500;
|
|
32
|
+
|
|
33
|
+
/** One tenant's chain over a window of time. */
|
|
34
|
+
export interface ChainRangeQuery {
|
|
35
|
+
/** The tenant whose chain is read, or null for the untenanted chain. */
|
|
36
|
+
tenant: string | null;
|
|
37
|
+
/** The window's inclusive start, or omitted for the chain's start. */
|
|
38
|
+
since?: Date;
|
|
39
|
+
/** The window's inclusive end, or omitted for the chain's head. */
|
|
40
|
+
until?: Date;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** A window resolved to positions. */
|
|
44
|
+
interface ResolvedRange {
|
|
45
|
+
/** The first position in the window. */
|
|
46
|
+
fromSeq: number;
|
|
47
|
+
/** The last position in the window. Below `fromSeq` when the window holds no chained event. */
|
|
48
|
+
throughSeq: number;
|
|
49
|
+
/** Whether the window runs to the head, so a checkpoint past its end is a truncation. */
|
|
50
|
+
toHead: boolean;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
async function resolveRange(db: AuditDatabase, query: ChainRangeQuery): Promise<ResolvedRange> {
|
|
54
|
+
const head = await readChainHead(db, query.tenant);
|
|
55
|
+
let fromSeq = 1;
|
|
56
|
+
if (query.since) {
|
|
57
|
+
const first = await whereChain(
|
|
58
|
+
db
|
|
59
|
+
.selectFrom("pithyAuditEvents")
|
|
60
|
+
.select((eb) => eb.fn.min("chainSeq").as("seq"))
|
|
61
|
+
.where("chainSeq", "is not", null)
|
|
62
|
+
.where("occurredAt", ">=", SQLiteDate.encode(query.since)),
|
|
63
|
+
query.tenant,
|
|
64
|
+
).executeTakeFirst();
|
|
65
|
+
fromSeq = typeof first?.seq === "number" ? first.seq : (head?.seq ?? 0) + 1;
|
|
66
|
+
}
|
|
67
|
+
let throughSeq = head?.seq ?? 0;
|
|
68
|
+
if (query.until) {
|
|
69
|
+
const last = await whereChain(
|
|
70
|
+
db
|
|
71
|
+
.selectFrom("pithyAuditEvents")
|
|
72
|
+
.select((eb) => eb.fn.max("chainSeq").as("seq"))
|
|
73
|
+
.where("chainSeq", "is not", null)
|
|
74
|
+
.where("occurredAt", "<=", SQLiteDate.encode(query.until)),
|
|
75
|
+
query.tenant,
|
|
76
|
+
).executeTakeFirst();
|
|
77
|
+
throughSeq = typeof last?.seq === "number" ? last.seq : 0;
|
|
78
|
+
}
|
|
79
|
+
return { fromSeq, throughSeq, toHead: query.until === undefined };
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** The id of the chain's first row, or null when the tenant has no chained event yet. */
|
|
83
|
+
async function chainStartId(db: AuditDatabase, tenant: string | null): Promise<number | null> {
|
|
84
|
+
const start = await whereChain(
|
|
85
|
+
db
|
|
86
|
+
.selectFrom("pithyAuditEvents")
|
|
87
|
+
.select((eb) => eb.fn.min("id").as("id"))
|
|
88
|
+
.where("chainSeq", "is not", null),
|
|
89
|
+
tenant,
|
|
90
|
+
).executeTakeFirst();
|
|
91
|
+
return typeof start?.id === "number" ? start.id : null;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** The id of the first row holding a position, or null when none does. */
|
|
95
|
+
async function idAt(db: AuditDatabase, tenant: string | null, seq: number): Promise<number | null> {
|
|
96
|
+
const row = await whereChain(
|
|
97
|
+
db
|
|
98
|
+
.selectFrom("pithyAuditEvents")
|
|
99
|
+
.select((eb) => eb.fn.min("id").as("id"))
|
|
100
|
+
.where("chainSeq", "=", seq),
|
|
101
|
+
tenant,
|
|
102
|
+
).executeTakeFirst();
|
|
103
|
+
return typeof row?.id === "number" ? row.id : null;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** How many of the tenant's events in the window were written before the chain began. */
|
|
107
|
+
async function countBeforeChain(db: AuditDatabase, query: ChainRangeQuery, startId: number | null): Promise<number> {
|
|
108
|
+
let builder = whereChain(
|
|
109
|
+
db
|
|
110
|
+
.selectFrom("pithyAuditEvents")
|
|
111
|
+
.select((eb) => eb.fn.countAll<number>().as("n"))
|
|
112
|
+
.where("chainSeq", "is", null),
|
|
113
|
+
query.tenant,
|
|
114
|
+
);
|
|
115
|
+
if (startId !== null) builder = builder.where("id", "<", startId);
|
|
116
|
+
if (query.since) builder = builder.where("occurredAt", ">=", SQLiteDate.encode(query.since));
|
|
117
|
+
if (query.until) builder = builder.where("occurredAt", "<=", SQLiteDate.encode(query.until));
|
|
118
|
+
return Number((await builder.executeTakeFirst())?.n ?? 0);
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* How many rows carrying no chain were written after the chain began, among the range's positions. A recorder from
|
|
123
|
+
* before the chain writes them — a Worker not yet redeployed, an isolate still serving the old version while a new
|
|
124
|
+
* one rolls out, a rollback, an older CLI emitting into the same database — and Cloudflare deploys no two of those
|
|
125
|
+
* together, so such a row is no evidence of tampering and no break. It carries no evidence of anything: counted here,
|
|
126
|
+
* and marked `chainSeq: null` in the listing, so an auditor sees it. An insert dressed as a chained row is the walk's.
|
|
127
|
+
*
|
|
128
|
+
* A row sits at one past the last chained event recorded before it, so the range's rows lie between the row at the
|
|
129
|
+
* position before `fromSeq` and the row at `throughSeq`, by id — or past it, for a range that runs to the head.
|
|
130
|
+
*/
|
|
131
|
+
async function countOutsideChain(
|
|
132
|
+
db: AuditDatabase,
|
|
133
|
+
tenant: string | null,
|
|
134
|
+
range: ResolvedRange,
|
|
135
|
+
startId: number | null,
|
|
136
|
+
): Promise<number> {
|
|
137
|
+
if (startId === null) return 0;
|
|
138
|
+
if (!range.toHead && range.throughSeq < range.fromSeq) return 0;
|
|
139
|
+
const lowerId = (await idAt(db, tenant, Math.max(range.fromSeq - 1, 1))) ?? startId;
|
|
140
|
+
let builder = whereChain(
|
|
141
|
+
db
|
|
142
|
+
.selectFrom("pithyAuditEvents")
|
|
143
|
+
.select((eb) => eb.fn.countAll<number>().as("n"))
|
|
144
|
+
.where("chainSeq", "is", null)
|
|
145
|
+
.where("id", ">", lowerId),
|
|
146
|
+
tenant,
|
|
147
|
+
);
|
|
148
|
+
if (!range.toHead) {
|
|
149
|
+
const upperId = await idAt(db, tenant, range.throughSeq);
|
|
150
|
+
if (upperId !== null) builder = builder.where("id", "<", upperId);
|
|
151
|
+
}
|
|
152
|
+
return Number((await builder.executeTakeFirst())?.n ?? 0);
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** What the verify read found. */
|
|
156
|
+
export interface ChainRangeVerification {
|
|
157
|
+
/** Whether the range is whole. */
|
|
158
|
+
intact: boolean;
|
|
159
|
+
/** How many chained events were checked before the first break, or all of them. */
|
|
160
|
+
checked: number;
|
|
161
|
+
/** How many checkpoints the walk was held to. */
|
|
162
|
+
checkpoints: number;
|
|
163
|
+
/** How many of the tenant's events in the window were written before the chain, and so are not in it. */
|
|
164
|
+
beforeChain: number;
|
|
165
|
+
/** How many rows in the range carry no chain though written after it began: an older recorder's, not a break. */
|
|
166
|
+
outsideChain: number;
|
|
167
|
+
/** How many events the walk crossed as pruned, each run bridged by its tombstone. */
|
|
168
|
+
pruned: number;
|
|
169
|
+
/** The first break, or null. */
|
|
170
|
+
break: ChainBreak | null;
|
|
171
|
+
/** The last position the walk reached intact, or null when it reached none. */
|
|
172
|
+
head: ChainLink | null;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* The link before position `seq`: the stored event there, or, where the retention prune removed it, the last hash its
|
|
177
|
+
* tombstone recorded. Null when neither holds it.
|
|
178
|
+
*/
|
|
179
|
+
async function linkBefore(
|
|
180
|
+
db: AuditDatabase,
|
|
181
|
+
tenant: string | null,
|
|
182
|
+
seq: number,
|
|
183
|
+
tombstones: readonly AuditTombstone[],
|
|
184
|
+
): Promise<ChainLink | null> {
|
|
185
|
+
const stored = await readChainLink(db, tenant, seq);
|
|
186
|
+
if (stored) return stored;
|
|
187
|
+
const run = tombstoneEndingAt(tombstones, seq);
|
|
188
|
+
return run ? { seq: run.throughSeq, hash: run.last } : null;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* Walk a range: every link, every hash, and the checkpoints covering it. `pageSize` is how many rows one read
|
|
193
|
+
* takes, and is a test's to set, so a page boundary can be put where a test needs it.
|
|
194
|
+
*/
|
|
195
|
+
export async function verifyChainRange(
|
|
196
|
+
db: AuditDatabase,
|
|
197
|
+
bucket: R2Bucket | null,
|
|
198
|
+
query: ChainRangeQuery,
|
|
199
|
+
options: { pageSize?: number } = {},
|
|
200
|
+
): Promise<ChainRangeVerification> {
|
|
201
|
+
const first = await walkRange(db, bucket, query, options);
|
|
202
|
+
// A prune that ran during the walk wrote its tombstone after the listing and deleted rows the walk then missed. A
|
|
203
|
+
// second walk lists the tombstone; a gap that is still a gap is one.
|
|
204
|
+
if (bucket && first.break?.reason === "missing") return walkRange(db, bucket, query, options);
|
|
205
|
+
return first;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
async function walkRange(
|
|
209
|
+
db: AuditDatabase,
|
|
210
|
+
bucket: R2Bucket | null,
|
|
211
|
+
query: ChainRangeQuery,
|
|
212
|
+
options: { pageSize?: number },
|
|
213
|
+
): Promise<ChainRangeVerification> {
|
|
214
|
+
const pageSize = options.pageSize ?? WALK_PAGE;
|
|
215
|
+
// Checkpoints first: one written after the head is read would count past it, and read as a truncation.
|
|
216
|
+
const listing = bucket ? await listCheckpoints(bucket, query.tenant) : null;
|
|
217
|
+
const tombstones = bucket ? await readTombstones(bucket, query.tenant) : [];
|
|
218
|
+
const range = await resolveRange(db, query);
|
|
219
|
+
const startId = await chainStartId(db, query.tenant);
|
|
220
|
+
const beforeChain = await countBeforeChain(db, query, startId);
|
|
221
|
+
const outsideChain = await countOutsideChain(db, query.tenant, range, startId);
|
|
222
|
+
const prior = range.fromSeq > 1 ? await linkBefore(db, query.tenant, range.fromSeq - 1, tombstones) : null;
|
|
223
|
+
const checkpoints =
|
|
224
|
+
bucket && listing
|
|
225
|
+
? await readCheckpoints(
|
|
226
|
+
bucket,
|
|
227
|
+
query.tenant,
|
|
228
|
+
{ fromCount: range.fromSeq, ...(range.toHead ? {} : { throughCount: range.throughSeq }) },
|
|
229
|
+
listing,
|
|
230
|
+
)
|
|
231
|
+
: [];
|
|
232
|
+
const result = (found: ChainBreak | null, checked: number, head: ChainLink | null, held: number, pruned = 0) => ({
|
|
233
|
+
intact: found === null,
|
|
234
|
+
checked,
|
|
235
|
+
checkpoints: held,
|
|
236
|
+
pruned,
|
|
237
|
+
beforeChain,
|
|
238
|
+
outsideChain,
|
|
239
|
+
break: found,
|
|
240
|
+
head,
|
|
241
|
+
});
|
|
242
|
+
if (range.fromSeq > 1 && !prior) {
|
|
243
|
+
return result(
|
|
244
|
+
{
|
|
245
|
+
eventId: null,
|
|
246
|
+
position: range.fromSeq - 1,
|
|
247
|
+
reason: "missing",
|
|
248
|
+
detail: `The event at position ${range.fromSeq - 1}, before the range, is missing.`,
|
|
249
|
+
},
|
|
250
|
+
0,
|
|
251
|
+
null,
|
|
252
|
+
0,
|
|
253
|
+
);
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
const verifier = chainVerifier({ tenant: query.tenant, prior, checkpoints, tombstones });
|
|
257
|
+
let found: ChainBreak | null = null;
|
|
258
|
+
// Resumed by position and id together, so a second row at the position a page ended on is the next page's first.
|
|
259
|
+
let after: { seq: number; id?: number } = { seq: range.fromSeq - 1 };
|
|
260
|
+
walk: while (range.throughSeq >= range.fromSeq) {
|
|
261
|
+
const rows = await readChainRows(db, {
|
|
262
|
+
tenant: query.tenant,
|
|
263
|
+
afterSeq: after.seq,
|
|
264
|
+
...(after.id !== undefined ? { afterId: after.id } : {}),
|
|
265
|
+
limit: pageSize,
|
|
266
|
+
throughSeq: range.throughSeq,
|
|
267
|
+
});
|
|
268
|
+
for (const row of rows) {
|
|
269
|
+
found = await verifier.push(await chainedEventOf(row, { detail: false }));
|
|
270
|
+
if (found) break walk;
|
|
271
|
+
}
|
|
272
|
+
const last = rows.at(-1);
|
|
273
|
+
if (rows.length < pageSize || !last) break;
|
|
274
|
+
after = { seq: last.chainSeq ?? range.throughSeq, id: last.id };
|
|
275
|
+
}
|
|
276
|
+
found ??= verifier.finish(range.toHead);
|
|
277
|
+
return result(found, verifier.checked, verifier.head, verifier.checkpoints, verifier.pruned);
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
/** One page of an export. */
|
|
281
|
+
export interface ChainExportOptions {
|
|
282
|
+
/** Whether the personal values and their salt travel with the commitments. */
|
|
283
|
+
detail: boolean;
|
|
284
|
+
/** Where the previous page ended — its last position and row id — from its `nextCursor`. */
|
|
285
|
+
cursor?: string;
|
|
286
|
+
/** How many events one page carries. */
|
|
287
|
+
limit: number;
|
|
288
|
+
/** When the export is taken. */
|
|
289
|
+
now: Date;
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
/**
|
|
293
|
+
* One page of a range as an export document: its events in canonical form with their hashes, the link before
|
|
294
|
+
* the page, and the checkpoints covering it. Each page verifies on its own from its `prior`, so an auditor can
|
|
295
|
+
* check a page without the ones before it.
|
|
296
|
+
*/
|
|
297
|
+
export async function exportChainRange(
|
|
298
|
+
db: AuditDatabase,
|
|
299
|
+
bucket: R2Bucket | null,
|
|
300
|
+
query: ChainRangeQuery,
|
|
301
|
+
options: ChainExportOptions,
|
|
302
|
+
): Promise<AuditChainExport> {
|
|
303
|
+
// Checkpoints first, as in the verify: one written after the rows are read would count past the last of them.
|
|
304
|
+
const listing = bucket ? await listCheckpoints(bucket, query.tenant) : null;
|
|
305
|
+
const tombstones = bucket ? await readTombstones(bucket, query.tenant) : [];
|
|
306
|
+
const range = await resolveRange(db, query);
|
|
307
|
+
const startId = await chainStartId(db, query.tenant);
|
|
308
|
+
const resumed = parseExportCursor(options.cursor);
|
|
309
|
+
const after: { seq: number; id?: number } =
|
|
310
|
+
resumed && resumed.seq >= range.fromSeq - 1 ? resumed : { seq: range.fromSeq - 1 };
|
|
311
|
+
const afterSeq = after.seq;
|
|
312
|
+
// One row past the page says whether there is a next one, without a count.
|
|
313
|
+
const read =
|
|
314
|
+
range.throughSeq >= range.fromSeq
|
|
315
|
+
? await readChainRows(db, {
|
|
316
|
+
tenant: query.tenant,
|
|
317
|
+
afterSeq,
|
|
318
|
+
...(after.id !== undefined ? { afterId: after.id } : {}),
|
|
319
|
+
limit: options.limit + 1,
|
|
320
|
+
throughSeq: range.throughSeq,
|
|
321
|
+
})
|
|
322
|
+
: [];
|
|
323
|
+
const more = read.length > options.limit;
|
|
324
|
+
const rows = read.slice(0, options.limit);
|
|
325
|
+
const events = await Promise.all(rows.map((row) => chainedEventOf(row, { detail: options.detail })));
|
|
326
|
+
const lastSeq = events.at(-1)?.seq ?? afterSeq;
|
|
327
|
+
const lastRow = rows.at(-1);
|
|
328
|
+
const prior = afterSeq > 0 ? await linkBefore(db, query.tenant, afterSeq, tombstones) : null;
|
|
329
|
+
const complete = range.toHead && !more;
|
|
330
|
+
const checkpoints: AuditCheckpoint[] =
|
|
331
|
+
bucket && listing
|
|
332
|
+
? await readCheckpoints(bucket, query.tenant, { fromCount: afterSeq + 1, throughCount: lastSeq }, listing)
|
|
333
|
+
: [];
|
|
334
|
+
return {
|
|
335
|
+
format: AUDIT_EXPORT_FORMAT,
|
|
336
|
+
chain: AUDIT_CHAIN_FORMAT,
|
|
337
|
+
tenant: query.tenant,
|
|
338
|
+
since: query.since?.toISOString() ?? null,
|
|
339
|
+
until: query.until?.toISOString() ?? null,
|
|
340
|
+
exportedAt: options.now.toISOString(),
|
|
341
|
+
detail: options.detail,
|
|
342
|
+
prior,
|
|
343
|
+
events,
|
|
344
|
+
// The latest checkpoint rides along with every page, and only the last page of a range that runs to the head
|
|
345
|
+
// may be held to it: a checkpoint past an earlier page's end is the next page's, not a truncation.
|
|
346
|
+
checkpoints,
|
|
347
|
+
// Every pruned run, so each page bridges a gap it meets, on its own as it verifies from its own prior.
|
|
348
|
+
...(tombstones.length > 0 ? { tombstones } : {}),
|
|
349
|
+
complete,
|
|
350
|
+
beforeChain: await countBeforeChain(db, query, startId),
|
|
351
|
+
outsideChain: await countOutsideChain(db, query.tenant, range, startId),
|
|
352
|
+
nextCursor: more && lastRow ? exportCursor(lastSeq, lastRow.id) : null,
|
|
353
|
+
};
|
|
354
|
+
}
|
|
355
|
+
|
|
356
|
+
/** An export page's `nextCursor`: the last row's position and id, so the next page resumes after that one row. */
|
|
357
|
+
function exportCursor(seq: number, id: number): string {
|
|
358
|
+
return `${seq}:${id}`;
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
/** A `nextCursor` read back, or null when it is not one — a malformed cursor is a first page. */
|
|
362
|
+
export function parseExportCursor(cursor: string | undefined): { seq: number; id: number } | null {
|
|
363
|
+
const match = cursor === undefined ? null : /^(\d{1,15}):(\d{1,15})$/.exec(cursor);
|
|
364
|
+
if (!match) return null;
|
|
365
|
+
return { seq: Number(match[1]), id: Number(match[2]) };
|
|
366
|
+
}
|
package/src/citations.ts
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
|
|
4
|
+
import type { D1Database } from "@cloudflare/workers-types";
|
|
5
|
+
import type { AuditCitation, AuditCitationReader } from "@pithy-sh/core/src/audit/citations";
|
|
6
|
+
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
7
|
+
import { AuditEventRow } from "./data/auditEvent";
|
|
8
|
+
import { type AuditDatabase, auditDatabase } from "./data/tables";
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* **Citing the trail (#823)** — the reader core's `composedAuditCitations` finds, so the control plane's erasure
|
|
12
|
+
* attestation can point at the events a purge wrote by id and chain position, and import nothing from here.
|
|
13
|
+
*
|
|
14
|
+
* It hands back where an event is, never what it holds: no IP, no user-agent, and of the metadata only a `step`
|
|
15
|
+
* name, which is how a purge step's event says which step it records. A row written before the chain began has no
|
|
16
|
+
* position, and says so with `null` rather than a guess.
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
/** The reader over one audit database. */
|
|
20
|
+
export function auditCitationReader(db: AuditDatabase): AuditCitationReader {
|
|
21
|
+
return async (query) => {
|
|
22
|
+
if (query.resourceIds.length === 0 || query.actions.length === 0) return [];
|
|
23
|
+
const rows = await db
|
|
24
|
+
.selectFrom("pithyAuditEvents")
|
|
25
|
+
.selectAll()
|
|
26
|
+
.where("resourceType", "=", query.resourceType)
|
|
27
|
+
.where("resourceId", "in", [...query.resourceIds])
|
|
28
|
+
.where("action", "in", [...query.actions])
|
|
29
|
+
.orderBy("occurredAt", "asc")
|
|
30
|
+
.orderBy("id", "asc")
|
|
31
|
+
.execute();
|
|
32
|
+
return rows.map((raw): AuditCitation => {
|
|
33
|
+
const row = AuditEventRow.parse(raw);
|
|
34
|
+
const step = row.metadata?.step;
|
|
35
|
+
return {
|
|
36
|
+
eventId: row.eventId,
|
|
37
|
+
action: row.action,
|
|
38
|
+
resourceId: row.resourceId ?? "",
|
|
39
|
+
occurredAt: row.occurredAt,
|
|
40
|
+
tenant: row.tenant ?? null,
|
|
41
|
+
seq: row.chainSeq ?? null,
|
|
42
|
+
hash: row.chainHash ?? null,
|
|
43
|
+
step: typeof step === "string" ? step : null,
|
|
44
|
+
};
|
|
45
|
+
});
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** The reader over the binding the config names, built per call from the env, like the Workflow recorder. */
|
|
50
|
+
export function auditCitationsFor(database: string): (env: Record<string, unknown>) => AuditCitationReader {
|
|
51
|
+
return (env) => {
|
|
52
|
+
const binding = env[database];
|
|
53
|
+
if (typeof binding !== "object" || binding === null) {
|
|
54
|
+
throw new InternalError({
|
|
55
|
+
message: "The audit database is not bound.",
|
|
56
|
+
action: `Bind the ${database} D1 database to this Worker.`,
|
|
57
|
+
detail: `the audit citation reader found no ${database} binding on the env`,
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
return auditCitationReader(auditDatabase(binding as D1Database));
|
|
61
|
+
};
|
|
62
|
+
}
|
package/src/cli/emitFromCLI.ts
CHANGED
|
@@ -36,6 +36,11 @@ export type CliAuditEvent = Omit<AuditEventInput, "actorType" | "actorId"> & {
|
|
|
36
36
|
*
|
|
37
37
|
* Like the in-Worker recorder, this is **non-fatal**: a write failure is logged, never thrown, so an
|
|
38
38
|
* audit write never breaks the command it records.
|
|
39
|
+
*
|
|
40
|
+
* **It is never shipped (#824).** The event takes its position in the tenant's chain like any other, and nothing
|
|
41
|
+
* enqueues it: the CLI binds no queue, and pushing over the Queues REST API would need a credential and a queue
|
|
42
|
+
* name per environment that a command recording one event should not resolve. So a sink sees a `seq` skip at
|
|
43
|
+
* every CLI action, and the audit README says so, and says how a receiver reconciles one against an export.
|
|
39
44
|
*/
|
|
40
45
|
export async function emitFromCLI(
|
|
41
46
|
d1: D1Database,
|
package/src/cloudflare-test.d.ts
CHANGED
package/src/data/auditEvent.ts
CHANGED
|
@@ -64,7 +64,7 @@ export const AuditEventRow = z
|
|
|
64
64
|
actorKind: ControlPlaneActorKind.nullable()
|
|
65
65
|
.default(null)
|
|
66
66
|
.describe(
|
|
67
|
-
"
|
|
67
|
+
"What kind of client acted: `agent`, `dashboard` or `script`. For a `control-plane` actor, the connection it called through; for a `user` actor, `agent` when an MCP client acted as them. Null for every other row, for a connection registered before the kind was recorded, and on rows written before this column existed (`audit_0002_actor_kind`).",
|
|
68
68
|
),
|
|
69
69
|
sessionId: z
|
|
70
70
|
.string()
|
|
@@ -117,6 +117,36 @@ export const AuditEventRow = z
|
|
|
117
117
|
.describe(
|
|
118
118
|
"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.",
|
|
119
119
|
),
|
|
120
|
+
// The hash chain (`audit_0005_chain`). All four null on a row written before the chain, which is its mark.
|
|
121
|
+
chainSeq: z
|
|
122
|
+
.number()
|
|
123
|
+
.int()
|
|
124
|
+
.nullable()
|
|
125
|
+
.default(null)
|
|
126
|
+
.describe(
|
|
127
|
+
"The event's 1-based position in its tenant's chain — one chain per tenant, and one for the events with no tenant. Null on a row written before the chain began, which is what marks it as before the chain; such a row is never back-filled.",
|
|
128
|
+
),
|
|
129
|
+
chainPrev: z
|
|
130
|
+
.string()
|
|
131
|
+
.nullable()
|
|
132
|
+
.default(null)
|
|
133
|
+
.describe(
|
|
134
|
+
"The hash of the event before it in its chain, null for the first event and for a row before the chain.",
|
|
135
|
+
),
|
|
136
|
+
chainHash: z
|
|
137
|
+
.string()
|
|
138
|
+
.nullable()
|
|
139
|
+
.default(null)
|
|
140
|
+
.describe(
|
|
141
|
+
"This event's SHA-256 over its canonical serialization (`@pithy-sh/core/src/audit/chain`), which covers its link and every column, with the IP, user-agent and metadata committed by salted hash. Null on a row before the chain.",
|
|
142
|
+
),
|
|
143
|
+
chainSalt: z
|
|
144
|
+
.string()
|
|
145
|
+
.nullable()
|
|
146
|
+
.default(null)
|
|
147
|
+
.describe(
|
|
148
|
+
"The per-event salt the IP, user-agent and metadata are committed under. Travels only with those values, so a commitment in an export without them cannot be reversed by guessing. Null on a row before the chain.",
|
|
149
|
+
),
|
|
120
150
|
})
|
|
121
151
|
.describe("One audit event in `pithy_audit_events` — the durable, queryable record of a security-relevant action.");
|
|
122
152
|
export type AuditEventRow = z.output<typeof AuditEventRow>;
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
|
|
4
|
+
import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
|
|
5
|
+
import { z } from "zod";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* The `pithy_audit_sinks` table (#824) — one row per declared sink, written by the shipping consumer and read by
|
|
9
|
+
* the manifest's health keys. It holds what the queue cannot be asked: when the sink last took a delivery, when it
|
|
10
|
+
* last refused one, how many events are waiting on a retry, and how many were given up on.
|
|
11
|
+
*
|
|
12
|
+
* A row per **sink**, keyed by the name it is declared under, so a health read is a primary-key lookup per declared
|
|
13
|
+
* sink — bounded by the config, never by the trail. A sink renamed or removed leaves its row behind, read by
|
|
14
|
+
* nothing, and a sink declared again under the same name picks its counts back up.
|
|
15
|
+
*
|
|
16
|
+
* It records delivery, never the trail: no event, no value, no response body from the receiver.
|
|
17
|
+
*/
|
|
18
|
+
export const AuditSinkStateRow = z
|
|
19
|
+
.object({
|
|
20
|
+
sink: z.string().describe("The sink's name, as `audit({ sinks })` declares it. Primary key."),
|
|
21
|
+
lastDeliveredAt: SQLiteDate.nullable().describe(
|
|
22
|
+
"When the sink last accepted a delivery. Ms-epoch in SQLite, a `Date` in app code; null until the first.",
|
|
23
|
+
),
|
|
24
|
+
lastFailedAt: SQLiteDate.nullable().describe(
|
|
25
|
+
"When the sink last refused a delivery or could not be reached; null until the first failure.",
|
|
26
|
+
),
|
|
27
|
+
retrying: z
|
|
28
|
+
.number()
|
|
29
|
+
.int()
|
|
30
|
+
.min(0)
|
|
31
|
+
.describe("How many events are waiting on a retry to this sink: its backlog of failed deliveries."),
|
|
32
|
+
deadLettered: z
|
|
33
|
+
.number()
|
|
34
|
+
.int()
|
|
35
|
+
.min(0)
|
|
36
|
+
.describe(
|
|
37
|
+
"How many events exhausted their retries and went to the dead-letter queue, since the sink was first declared.",
|
|
38
|
+
),
|
|
39
|
+
})
|
|
40
|
+
.describe("One sink's delivery state: its last delivery, its last failure, its backlog, and what it gave up on.");
|
|
41
|
+
export type AuditSinkStateRow = z.output<typeof AuditSinkStateRow>;
|
package/src/data/tables.ts
CHANGED
|
@@ -3,8 +3,9 @@
|
|
|
3
3
|
|
|
4
4
|
import type { D1Database } from "@cloudflare/workers-types";
|
|
5
5
|
import { createDatabase, type DatabaseSchema } from "@pithy-sh/core/src/data/db";
|
|
6
|
-
import type { Kysely } from "kysely";
|
|
6
|
+
import type { Insertable, Kysely } from "kysely";
|
|
7
7
|
import { AuditEventRow } from "./auditEvent";
|
|
8
|
+
import { AuditSinkStateRow } from "./sinkState";
|
|
8
9
|
|
|
9
10
|
/**
|
|
10
11
|
* The audit capability's table map: camelCase keys (CamelCasePlugin emits the snake_case
|
|
@@ -13,12 +14,17 @@ import { AuditEventRow } from "./auditEvent";
|
|
|
13
14
|
*/
|
|
14
15
|
export const auditTables = {
|
|
15
16
|
pithyAuditEvents: AuditEventRow,
|
|
17
|
+
// Shipping's delivery state, one row per declared sink (#824).
|
|
18
|
+
pithyAuditSinks: AuditSinkStateRow,
|
|
16
19
|
};
|
|
17
20
|
export type AuditTables = typeof auditTables;
|
|
18
21
|
|
|
19
22
|
/** The typed Kysely view over the audit table — what the recorder and query helper run against. */
|
|
20
23
|
export type AuditDatabase = Kysely<DatabaseSchema<AuditTables>>;
|
|
21
24
|
|
|
25
|
+
/** One row as the recorder inserts it — the `z.input` side, every column it may name. */
|
|
26
|
+
export type AuditEventInsert = Insertable<DatabaseSchema<AuditTables>["pithyAuditEvents"]>;
|
|
27
|
+
|
|
22
28
|
/** Build the audit Kysely over a D1 binding (or a REST `D1Database` from `@pithy-sh/cloudflare`). */
|
|
23
29
|
export function auditDatabase(d1: D1Database): AuditDatabase {
|
|
24
30
|
return createDatabase(d1, auditTables);
|