@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
package/src/capability.ts
CHANGED
|
@@ -1,21 +1,41 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
3
|
|
|
4
|
-
import type { D1Database } from "@cloudflare/workers-types";
|
|
4
|
+
import type { D1Database, R2Bucket } from "@cloudflare/workers-types";
|
|
5
5
|
import type { AuditEventInput } from "@pithy-sh/core/src/audit/auditEvent";
|
|
6
6
|
import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
|
|
7
|
+
import type { AdminRoute } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
|
|
8
|
+
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
7
9
|
import { createWorkerLogger } from "@pithy-sh/core/src/logger/worker";
|
|
8
10
|
import { workerIdentity } from "@pithy-sh/core/src/worker/identity";
|
|
11
|
+
import { workflowBindings } from "@pithy-sh/core/src/workflow/bindings";
|
|
12
|
+
import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
|
|
13
|
+
import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
|
|
9
14
|
import { z } from "zod";
|
|
15
|
+
import { AUDIT_CHECKPOINT_BINDING } from "./chain/checkpoint";
|
|
16
|
+
import { checkpointLockCheck } from "./chain/lockCheck";
|
|
17
|
+
import { auditCitationsFor } from "./citations";
|
|
10
18
|
import type { AuditDatabase } from "./data/tables";
|
|
11
19
|
import { auditDatabase, auditTables } from "./data/tables";
|
|
12
20
|
import { auditAdminRoutes } from "./http/guards";
|
|
13
21
|
import { registerAuditRoutes } from "./http/routes";
|
|
14
22
|
import { audit_0001_init } from "./migrations/0001_init";
|
|
15
23
|
import { audit_0002_actor_kind } from "./migrations/0002_actor_kind";
|
|
24
|
+
import { audit_0003_call_index } from "./migrations/0003_call_index";
|
|
25
|
+
import { audit_0004_request_index } from "./migrations/0004_request_index";
|
|
26
|
+
import { audit_0005_chain } from "./migrations/0005_chain";
|
|
27
|
+
import { audit_0006_sinks } from "./migrations/0006_sinks";
|
|
28
|
+
import { auditUserPurge } from "./purge/contribution";
|
|
16
29
|
import { recordAuditEvent } from "./recorder";
|
|
17
30
|
import { auditExampleSeed } from "./seeds/example";
|
|
31
|
+
import { auditShipConsumer } from "./ship/consumer";
|
|
32
|
+
import { shipHealth } from "./ship/health";
|
|
33
|
+
import { shipBindings } from "./ship/queue";
|
|
34
|
+
import { sinkSecretsRegistry } from "./ship/secrets";
|
|
35
|
+
import { shipperFor } from "./ship/shipper";
|
|
36
|
+
import { AuditSinks } from "./ship/sinks";
|
|
18
37
|
import { PACKAGE_NAME, PACKAGE_VERSION } from "./version.generated";
|
|
38
|
+
import { auditAppWorkflows, auditWorkflows } from "./workflows/specs";
|
|
19
39
|
|
|
20
40
|
/**
|
|
21
41
|
* Sort order of the audit migration within the audit database, relative to other capabilities
|
|
@@ -57,6 +77,9 @@ export const AuditConfig = z
|
|
|
57
77
|
.describe(
|
|
58
78
|
"Where the control-plane routes that read the trail mount. Reads only — the trail is append-only and this surface never writes.",
|
|
59
79
|
),
|
|
80
|
+
sinks: AuditSinks.default({}).describe(
|
|
81
|
+
"Where the trail is shipped as it is written — Splunk HEC, Datadog Logs, or any HTTPS endpoint — by name. Declared here and nowhere else: no control-plane route adds, changes or removes one. Empty ships nothing and binds no queue.",
|
|
82
|
+
),
|
|
60
83
|
})
|
|
61
84
|
.describe("Configuration for the audit capability.");
|
|
62
85
|
export type AuditConfig = z.output<typeof AuditConfig>;
|
|
@@ -66,6 +89,8 @@ export type AuditConfigInput = z.input<typeof AuditConfig>;
|
|
|
66
89
|
export interface AuditCapability extends Capability {
|
|
67
90
|
/** The D1 binding the audit table lives in (the resolved `database` config). */
|
|
68
91
|
auditDatabase: string;
|
|
92
|
+
/** The sinks the trail ships to (#824), as declared — what `pithy doctor` lists. */
|
|
93
|
+
auditSinks: AuditSinks;
|
|
69
94
|
}
|
|
70
95
|
|
|
71
96
|
/**
|
|
@@ -76,6 +101,15 @@ export interface AuditCapability extends Capability {
|
|
|
76
101
|
*/
|
|
77
102
|
export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
78
103
|
const resolved = AuditConfig.parse(config);
|
|
104
|
+
const sinks = resolved.sinks;
|
|
105
|
+
const ships = Object.keys(sinks).length > 0;
|
|
106
|
+
// The tokens each sink reads, declared on audit's own slice (#824); empty, and not declared, when nothing ships.
|
|
107
|
+
const sinkSecrets = sinkSecretsRegistry(sinks);
|
|
108
|
+
const databaseOf = (c: { var: { db: unknown } }) =>
|
|
109
|
+
(c.var.db as Record<typeof AUDIT_DATABASE_NAME, AuditDatabase>)[AUDIT_DATABASE_NAME];
|
|
110
|
+
// Every composed capability's admin routes, read at `compose`. Until then — a router mounted outside a backend —
|
|
111
|
+
// audit's own, so a reach read still groups its own routes rather than calling every path unmatched.
|
|
112
|
+
let adminRoutes: readonly AdminRoute[] = auditAdminRoutes(resolved.basePath);
|
|
79
113
|
const capability = defineCapability({
|
|
80
114
|
name: "audit",
|
|
81
115
|
// The package this capability ships in and the version it ships at, both stamped by
|
|
@@ -85,16 +119,73 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
85
119
|
version: PACKAGE_VERSION,
|
|
86
120
|
package: PACKAGE_NAME,
|
|
87
121
|
config: AuditConfig,
|
|
88
|
-
requiredBindings: [
|
|
122
|
+
requiredBindings: [
|
|
123
|
+
{ type: "d1", name: resolved.database },
|
|
124
|
+
// The checkpoint bucket (#822): each tenant chain's head and count, written on a schedule by the checkpoint
|
|
125
|
+
// host and read back by the verify and export routes. Optional, so a Worker not yet provisioned still records
|
|
126
|
+
// every event and still verifies links — it says so, as `checkpointStore: "absent"`.
|
|
127
|
+
{ type: "r2", name: AUDIT_CHECKPOINT_BINDING, optional: true },
|
|
128
|
+
// The checkpoint Workflow's binding, derived from the spec rather than written again. Optional: it exists only
|
|
129
|
+
// once the checkpoint host is deployed, and nothing in the app dispatches it — the host's cron does.
|
|
130
|
+
...workflowBindings(auditWorkflows),
|
|
131
|
+
// The retention prune's binding: optional, and bound by the adopter to the class their own Worker exports.
|
|
132
|
+
...workflowBindings(auditAppWorkflows),
|
|
133
|
+
// The shipping queue and its dead-letter queue (#824), only when a sink is declared: Cloudflare Queues needs
|
|
134
|
+
// the Workers Paid plan, so a project that ships nothing binds neither. Required when declared — a sink that
|
|
135
|
+
// could never be enqueued to is a config that does not do what it says.
|
|
136
|
+
...shipBindings(sinks),
|
|
137
|
+
],
|
|
138
|
+
// A sink's token is read through `@pithy-sh/secrets`, so a Worker that ships needs it composed (#824).
|
|
139
|
+
...(ships
|
|
140
|
+
? {
|
|
141
|
+
dependsOn: ["secrets"],
|
|
142
|
+
secretRegistry: sinkSecrets,
|
|
143
|
+
// Backlog, dead-lettered and delivery state on audit's manifest entry, behind the listing's own scope.
|
|
144
|
+
health: shipHealth(sinks, databaseOf),
|
|
145
|
+
// The consumer of `AUDIT_SHIP`: one request per sink per batch, retried with back-off, dead-lettered.
|
|
146
|
+
queue: auditShipConsumer({
|
|
147
|
+
sinks,
|
|
148
|
+
database: (env) => {
|
|
149
|
+
const binding = env[resolved.database];
|
|
150
|
+
if (typeof binding !== "object" || binding === null) {
|
|
151
|
+
throw new InternalError({
|
|
152
|
+
message: "Audit shipping cannot read the trail.",
|
|
153
|
+
action: `Bind the ${resolved.database} D1 database to this Worker.`,
|
|
154
|
+
detail: `no ${resolved.database} binding on the queue invocation's env`,
|
|
155
|
+
});
|
|
156
|
+
}
|
|
157
|
+
return auditDatabase(binding as D1Database);
|
|
158
|
+
},
|
|
159
|
+
token: async (env, secret) =>
|
|
160
|
+
(await sharedSecretsStore(env as unknown as SecretsStoreEnv, sinkSecrets)).get(secret) as string,
|
|
161
|
+
log: createWorkerLogger({ name: "audit" }),
|
|
162
|
+
}),
|
|
163
|
+
}
|
|
164
|
+
: {}),
|
|
165
|
+
// The checkpoint job (#822), hosted by the prebuilt audit worker and fired hourly from its cron.
|
|
166
|
+
// And the retention prune, hosted by the adopter's own Worker and fired daily from its cron.
|
|
167
|
+
workflows: { ...auditWorkflows, ...auditAppWorkflows },
|
|
168
|
+
// `pithy doctor` says whether object lock is in force on each deployed environment's checkpoint bucket (#822).
|
|
169
|
+
settings: checkpointLockCheck(),
|
|
89
170
|
databases: {
|
|
90
171
|
[AUDIT_DATABASE_NAME]: {
|
|
91
172
|
binding: resolved.database,
|
|
92
173
|
tables: auditTables,
|
|
93
174
|
migrationOrder: AUDIT_MIGRATION_ORDER,
|
|
94
|
-
migrations: {
|
|
175
|
+
migrations: {
|
|
176
|
+
"0001_init": audit_0001_init,
|
|
177
|
+
"0002_actor_kind": audit_0002_actor_kind,
|
|
178
|
+
"0003_call_index": audit_0003_call_index,
|
|
179
|
+
"0004_request_index": audit_0004_request_index,
|
|
180
|
+
"0005_chain": audit_0005_chain,
|
|
181
|
+
"0006_sinks": audit_0006_sinks,
|
|
182
|
+
},
|
|
95
183
|
},
|
|
96
184
|
},
|
|
97
185
|
seeds: [auditExampleSeed],
|
|
186
|
+
// Every event where a person is the actor is kept through their purge, as the record of who acted, and exported
|
|
187
|
+
// on an access request with the basis that keeps it (#814).
|
|
188
|
+
purge: [auditUserPurge(resolved.database)],
|
|
98
189
|
// The same recorder for code with no request — a Workflow step, which has `env` and nothing else (#622).
|
|
99
190
|
// Built over the binding this config names, stamped with the env's own origin, and non-fatal on the same
|
|
100
191
|
// terms as the middleware's: a missing binding or a failed insert drops the event and logs it, and the
|
|
@@ -107,20 +198,36 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
107
198
|
log.error("audit event dropped", { reason: `no ${resolved.database} binding`, action: event.action });
|
|
108
199
|
return;
|
|
109
200
|
}
|
|
201
|
+
const ship = shipperFor(env, sinks);
|
|
110
202
|
await recordAuditEvent(auditDatabase(binding as D1Database), event, {
|
|
111
203
|
origin: workerIdentity(env),
|
|
112
204
|
onError: (error) => log.error("audit event dropped", { error }),
|
|
205
|
+
...(ship ? { ship, onShipError: (error) => log.error("audit shipment not enqueued", { error }) } : {}),
|
|
113
206
|
});
|
|
114
207
|
};
|
|
115
208
|
},
|
|
209
|
+
// Where a resource's events sit in their chains, for the control plane's erasure attestation (#823). Found by
|
|
210
|
+
// core's `composedAuditCitations`, so the attestation imports nothing from here.
|
|
211
|
+
auditCitations: auditCitationsFor(resolved.database),
|
|
116
212
|
// Built from the resolved `basePath`, never the default: an adopter who mounts this at `/trail`
|
|
117
213
|
// gets a manifest naming their paths, where a client assuming the default would 404.
|
|
118
214
|
adminRoutes: auditAdminRoutes(resolved.basePath),
|
|
215
|
+
// The manifest's routes, gathered once at startup: a credential's reach groups the paths it called by the routes
|
|
216
|
+
// this Worker declares (#828), and only `compose` sees every capability.
|
|
217
|
+
compose: ({ capabilities }) => {
|
|
218
|
+
adminRoutes = capabilities.flatMap((capability) => capability.adminRoutes ?? []);
|
|
219
|
+
},
|
|
119
220
|
// The registry key is this package's own detail, so the routes are handed a resolver rather than
|
|
120
221
|
// being made to know it — the same reason the middleware below resolves lazily.
|
|
121
222
|
routes: registerAuditRoutes({
|
|
122
223
|
basePath: resolved.basePath,
|
|
123
224
|
database: (c) => (c.var.db as Record<typeof AUDIT_DATABASE_NAME, AuditDatabase>)[AUDIT_DATABASE_NAME],
|
|
225
|
+
adminRoutes: () => adminRoutes,
|
|
226
|
+
// Read off the env per request: a binding exists only on a request, and an unprovisioned Worker has none.
|
|
227
|
+
checkpoints: (c) => {
|
|
228
|
+
const bucket = (c.env as Record<string, unknown> | undefined)?.[AUDIT_CHECKPOINT_BINDING];
|
|
229
|
+
return typeof bucket === "object" && bucket !== null ? (bucket as R2Bucket) : null;
|
|
230
|
+
},
|
|
124
231
|
}),
|
|
125
232
|
// Replace the no-op `emit` seam with a recorder over this request's audit database. The database
|
|
126
233
|
// is resolved lazily inside the closure — only when a route actually emits — so a request that
|
|
@@ -138,22 +245,37 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
138
245
|
// Worker predating these vars still records its events — just without an origin.
|
|
139
246
|
// The parameter is annotated: `AuditEmit` is generic over `metadata` so a call site carrying a
|
|
140
247
|
// privacy-marked value fails to compile (#132), and the recorder is the one place every event lands.
|
|
248
|
+
const ship = shipperFor(c.env as Record<string, unknown> | undefined, sinks);
|
|
249
|
+
const onShipError = (error: unknown) =>
|
|
250
|
+
c.var.log.child("audit").error("audit shipment not enqueued", { error });
|
|
141
251
|
c.set("emit", (event: AuditEventInput) =>
|
|
142
|
-
recordAuditEvent(
|
|
143
|
-
(c.
|
|
144
|
-
event,
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
252
|
+
recordAuditEvent(databaseOf(c), event, {
|
|
253
|
+
origin: workerIdentity(c.env),
|
|
254
|
+
onError: (error) => c.var.log.child("audit").error("audit event dropped", { error }),
|
|
255
|
+
// Enqueued after the response where the runtime allows it (#824), so shipping never holds the
|
|
256
|
+
// request it records; awaited only where there is no execution context to hand it to.
|
|
257
|
+
...(ship
|
|
258
|
+
? {
|
|
259
|
+
ship: (shipment: { eventId: string; action: string }) => {
|
|
260
|
+
const sent = ship(shipment);
|
|
261
|
+
try {
|
|
262
|
+
c.executionCtx.waitUntil(sent.catch(onShipError));
|
|
263
|
+
return Promise.resolve();
|
|
264
|
+
} catch {
|
|
265
|
+
return sent;
|
|
266
|
+
}
|
|
267
|
+
},
|
|
268
|
+
onShipError,
|
|
269
|
+
}
|
|
270
|
+
: {}),
|
|
271
|
+
}),
|
|
150
272
|
);
|
|
151
273
|
await next();
|
|
152
274
|
});
|
|
153
275
|
},
|
|
154
276
|
],
|
|
155
277
|
});
|
|
156
|
-
return Object.assign(capability, { auditDatabase: resolved.database });
|
|
278
|
+
return Object.assign(capability, { auditDatabase: resolved.database, auditSinks: sinks });
|
|
157
279
|
}
|
|
158
280
|
|
|
159
281
|
/** Whether a capability is the audit capability — carries its resolved binding. */
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
|
|
4
|
+
import { chainHash, newChainSalt } from "@pithy-sh/core/src/audit/chain";
|
|
5
|
+
import { type D1RetryOptions, withD1Retry } from "@pithy-sh/core/src/data/withD1Retry";
|
|
6
|
+
import type { AuditDatabase, AuditEventInsert } from "../data/tables";
|
|
7
|
+
import { AuditWriteFailedError } from "../error/errors";
|
|
8
|
+
import { chainFieldsOf, readChainHead, whereChain } from "./rows";
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* How long one append keeps contending for its chain's next position before it gives up, in ms. Every lost race
|
|
12
|
+
* means another event landed, so a burst of appends to one tenant all land, one position at a time: the bound is on
|
|
13
|
+
* time, not on how many appends overtake this one, so no burst size drops an event. It exists only to end a request
|
|
14
|
+
* that a chain somebody is writing wrong would hold forever.
|
|
15
|
+
*/
|
|
16
|
+
export const CHAIN_APPEND_DEADLINE_MS = 30_000;
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* How many lost races in a row may find the head where it was. A race is lost because an event took the position,
|
|
20
|
+
* so the head moves; one that does not move is a chain this append cannot join, and retrying it is spinning.
|
|
21
|
+
*/
|
|
22
|
+
export const CHAIN_APPEND_STALLS = 3;
|
|
23
|
+
|
|
24
|
+
/** The longest one back-off after a lost race waits, in ms. Each wait is a random fraction of a growing ceiling. */
|
|
25
|
+
const BACKOFF_CEILING_MS = 50;
|
|
26
|
+
|
|
27
|
+
/** How one append contends for its chain. Every field has a default; tests narrow them. */
|
|
28
|
+
export interface ChainAppendOptions {
|
|
29
|
+
/** How a transient D1 fault on the insert is retried. */
|
|
30
|
+
retry?: D1RetryOptions;
|
|
31
|
+
/** How long the append keeps contending, in ms. Defaults to {@link CHAIN_APPEND_DEADLINE_MS}. */
|
|
32
|
+
deadlineMs?: number;
|
|
33
|
+
/** The longest back-off between attempts, in ms. Defaults to 50; 0 retries at once. */
|
|
34
|
+
backoffCeilingMs?: number;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Wait a random time under a ceiling that doubles with each lost race, so contenders stop retrying in lockstep. */
|
|
38
|
+
async function backOff(lost: number, ceilingMs: number): Promise<void> {
|
|
39
|
+
const ceiling = Math.min(ceilingMs, 2 ** Math.min(lost, 10));
|
|
40
|
+
if (ceiling <= 0) return;
|
|
41
|
+
await new Promise((resolve) => setTimeout(resolve, Math.random() * ceiling));
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* **Append one event to its tenant's chain, without forking it (#822).**
|
|
46
|
+
*
|
|
47
|
+
* Read the head, compute this event's link and hash, then insert in **one statement that refuses when the head has
|
|
48
|
+
* moved**: `INSERT … SELECT … WHERE NOT EXISTS (an event at or past this position in this chain)`. D1 runs one
|
|
49
|
+
* statement at a time, so the check and the write cannot be split by another append. A loser inserts nothing,
|
|
50
|
+
* backs off a random moment, re-reads the head and tries again, so two concurrent appends never share a position
|
|
51
|
+
* and never name the same predecessor, and a burst of them all lands. The partial unique indexes from
|
|
52
|
+
* `audit_0005_chain` sit under it as a backstop.
|
|
53
|
+
*
|
|
54
|
+
* `withD1Retry` still rides out a transient fault on the insert. A retry after a write that landed inserts nothing
|
|
55
|
+
* here rather than tripping the unique index, so it is told apart from a lost race by asking whether the event's
|
|
56
|
+
* own id is already in the table.
|
|
57
|
+
*/
|
|
58
|
+
export async function appendChained(
|
|
59
|
+
db: AuditDatabase,
|
|
60
|
+
record: AuditEventInsert,
|
|
61
|
+
options: ChainAppendOptions = {},
|
|
62
|
+
): Promise<void> {
|
|
63
|
+
const tenant = record.tenant ?? null;
|
|
64
|
+
const deadline = Date.now() + (options.deadlineMs ?? CHAIN_APPEND_DEADLINE_MS);
|
|
65
|
+
const ceilingMs = options.backoffCeilingMs ?? BACKOFF_CEILING_MS;
|
|
66
|
+
// The salt and the commitments do not depend on the position, so a lost race recomputes only the link.
|
|
67
|
+
const salt = newChainSalt();
|
|
68
|
+
const fields = await chainFieldsOf(
|
|
69
|
+
{
|
|
70
|
+
eventId: record.eventId,
|
|
71
|
+
occurredAt: record.occurredAt as number,
|
|
72
|
+
action: record.action,
|
|
73
|
+
outcome: record.outcome,
|
|
74
|
+
severity: record.severity ?? "info",
|
|
75
|
+
actorType: record.actorType,
|
|
76
|
+
actorId: record.actorId ?? null,
|
|
77
|
+
actorKind: record.actorKind ?? null,
|
|
78
|
+
sessionId: record.sessionId ?? null,
|
|
79
|
+
resourceType: record.resourceType ?? null,
|
|
80
|
+
resourceId: record.resourceId ?? null,
|
|
81
|
+
requestId: record.requestId ?? null,
|
|
82
|
+
tenant,
|
|
83
|
+
project: record.project ?? null,
|
|
84
|
+
environment: record.environment ?? null,
|
|
85
|
+
worker: record.worker ?? null,
|
|
86
|
+
version: record.version ?? null,
|
|
87
|
+
ip: record.ip ?? null,
|
|
88
|
+
userAgent: record.userAgent ?? null,
|
|
89
|
+
metadata: (record.metadata as string | null | undefined) ?? null,
|
|
90
|
+
chainSalt: salt,
|
|
91
|
+
},
|
|
92
|
+
salt,
|
|
93
|
+
);
|
|
94
|
+
let lost = 0;
|
|
95
|
+
let stalls = 0;
|
|
96
|
+
let lastSeq: number | null = null;
|
|
97
|
+
for (;;) {
|
|
98
|
+
const head = await readChainHead(db, tenant);
|
|
99
|
+
const seq = (head?.seq ?? 0) + 1;
|
|
100
|
+
if (lastSeq !== null) {
|
|
101
|
+
stalls = seq > lastSeq ? 0 : stalls + 1;
|
|
102
|
+
if (stalls >= CHAIN_APPEND_STALLS) {
|
|
103
|
+
throw new AuditWriteFailedError({
|
|
104
|
+
detail: `The ${chainName(tenant)} chain refused position ${seq} ${CHAIN_APPEND_STALLS} times without moving.`,
|
|
105
|
+
});
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
lastSeq = seq;
|
|
109
|
+
const prev = head?.hash ?? null;
|
|
110
|
+
const hash = await chainHash({ seq, prev }, fields);
|
|
111
|
+
const row = {
|
|
112
|
+
...record,
|
|
113
|
+
tenant,
|
|
114
|
+
chainSeq: seq,
|
|
115
|
+
chainPrev: prev,
|
|
116
|
+
chainHash: hash,
|
|
117
|
+
chainSalt: salt,
|
|
118
|
+
};
|
|
119
|
+
const columns = Object.keys(row) as (keyof typeof row)[];
|
|
120
|
+
const result = await withD1Retry(
|
|
121
|
+
() =>
|
|
122
|
+
db
|
|
123
|
+
.insertInto("pithyAuditEvents")
|
|
124
|
+
.columns(columns)
|
|
125
|
+
.expression(
|
|
126
|
+
db
|
|
127
|
+
.selectNoFrom((eb) => columns.map((column) => eb.val(row[column]).as(column)))
|
|
128
|
+
.where(({ not, exists, selectFrom }) =>
|
|
129
|
+
not(
|
|
130
|
+
exists(whereChain(selectFrom("pithyAuditEvents").select("id").where("chainSeq", ">=", seq), tenant)),
|
|
131
|
+
),
|
|
132
|
+
),
|
|
133
|
+
)
|
|
134
|
+
.executeTakeFirst(),
|
|
135
|
+
options.retry,
|
|
136
|
+
);
|
|
137
|
+
if (Number(result?.numInsertedOrUpdatedRows ?? 0n) > 0) return;
|
|
138
|
+
// Nothing inserted: either a retry found this event already landed, or another append took the position.
|
|
139
|
+
const landed = await db
|
|
140
|
+
.selectFrom("pithyAuditEvents")
|
|
141
|
+
.select("id")
|
|
142
|
+
.where("eventId", "=", record.eventId)
|
|
143
|
+
.executeTakeFirst();
|
|
144
|
+
if (landed) return;
|
|
145
|
+
if (Date.now() >= deadline) {
|
|
146
|
+
throw new AuditWriteFailedError({
|
|
147
|
+
detail: `The ${chainName(tenant)} chain moved under one append for ${options.deadlineMs ?? CHAIN_APPEND_DEADLINE_MS}ms.`,
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
await backOff(++lost, ceilingMs);
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
function chainName(tenant: string | null): string {
|
|
155
|
+
return tenant === null ? "untenanted" : `"${tenant}"`;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/** Whether a failed write failed because the database has not taken `audit_0005_chain` yet. */
|
|
159
|
+
export function isUnmigratedChain(error: unknown): boolean {
|
|
160
|
+
return error instanceof Error && /(no column named|no such column:) chain_(seq|prev|hash|salt)/.test(error.message);
|
|
161
|
+
}
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
|
|
4
|
+
import type { R2Bucket } from "@cloudflare/workers-types";
|
|
5
|
+
import { AUDIT_CHECKPOINT_FORMAT, AuditCheckpoint } from "@pithy-sh/core/src/audit/chain";
|
|
6
|
+
import type { AuditDatabase } from "../data/tables";
|
|
7
|
+
import { readChainLink } from "./rows";
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* **Checkpoints: each chain's length and head, written outside the database (#822).**
|
|
11
|
+
*
|
|
12
|
+
* A chain alone proves no row was changed *unless the whole chain was recomputed* — and anybody with write access to
|
|
13
|
+
* the D1 can recompute it. So on a schedule each tenant's head and count go to the checkpoint bucket, one object per
|
|
14
|
+
* checkpoint, never overwritten: the key carries the count, and the write is conditional on the key being new. A
|
|
15
|
+
* rewritten chain then disagrees with a checkpoint it cannot reach, and a truncated one ends before a checkpoint
|
|
16
|
+
* says it did.
|
|
17
|
+
*
|
|
18
|
+
* **Object lock is what makes the bucket evidence.** Without it whoever can write the bucket can rewrite the
|
|
19
|
+
* checkpoints too. The lock is a bucket rule (`AUDIT_CHECKPOINT_LOCK_PREFIX`, indefinite retention) set on the
|
|
20
|
+
* account, and `pithy doctor` says whether it is in force — the Worker cannot see it through its binding.
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
/** The binding the checkpoint bucket is bound as, in the app Worker and in the checkpoint host. */
|
|
24
|
+
export const AUDIT_CHECKPOINT_BINDING = "AUDIT_CHECKPOINTS";
|
|
25
|
+
|
|
26
|
+
/** Every checkpoint object lives under this prefix, and the lock rule names it. */
|
|
27
|
+
export const AUDIT_CHECKPOINT_LOCK_PREFIX = "checkpoints/";
|
|
28
|
+
|
|
29
|
+
/** The zero-padded width of a count in a key, so keys list in count order. */
|
|
30
|
+
const COUNT_WIDTH = 15;
|
|
31
|
+
|
|
32
|
+
/** The key prefix of one chain's checkpoints. A tenant id is encoded, so no id can reach another's prefix. */
|
|
33
|
+
export function checkpointPrefix(tenant: string | null): string {
|
|
34
|
+
return tenant === null
|
|
35
|
+
? `${AUDIT_CHECKPOINT_LOCK_PREFIX}untenanted/`
|
|
36
|
+
: `${AUDIT_CHECKPOINT_LOCK_PREFIX}tenant/${encodeURIComponent(tenant)}/`;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** The key of one checkpoint: its chain's prefix and its count. */
|
|
40
|
+
export function checkpointKey(tenant: string | null, count: number): string {
|
|
41
|
+
return `${checkpointPrefix(tenant)}${String(count).padStart(COUNT_WIDTH, "0")}.json`;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** The count a key names, or null when the key is not a checkpoint's. */
|
|
45
|
+
function countOf(key: string, prefix: string): number | null {
|
|
46
|
+
const match = /^(\d+)\.json$/.exec(key.slice(prefix.length));
|
|
47
|
+
return match ? Number(match[1]) : null;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** What one checkpoint run did. */
|
|
51
|
+
export interface CheckpointRun {
|
|
52
|
+
/** Chains whose head was new, and so got a checkpoint. */
|
|
53
|
+
written: number;
|
|
54
|
+
/** Chains whose head was already checkpointed. */
|
|
55
|
+
unchanged: number;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Write a checkpoint for every chain whose head moved since its last one. Idempotent: a head already checkpointed
|
|
60
|
+
* is a key that exists, and the conditional write refuses to replace it.
|
|
61
|
+
*/
|
|
62
|
+
export async function writeCheckpoints(db: AuditDatabase, bucket: R2Bucket, now: Date): Promise<CheckpointRun> {
|
|
63
|
+
const heads = await db
|
|
64
|
+
.selectFrom("pithyAuditEvents")
|
|
65
|
+
.select(["tenant", (eb) => eb.fn.max("chainSeq").as("count")])
|
|
66
|
+
.where("chainSeq", "is not", null)
|
|
67
|
+
.groupBy("tenant")
|
|
68
|
+
.execute();
|
|
69
|
+
const run: CheckpointRun = { written: 0, unchanged: 0 };
|
|
70
|
+
for (const { tenant, count } of heads) {
|
|
71
|
+
if (typeof count !== "number") continue;
|
|
72
|
+
const link = await readChainLink(db, tenant, count);
|
|
73
|
+
if (!link) continue;
|
|
74
|
+
const key = checkpointKey(tenant, link.seq);
|
|
75
|
+
if (await bucket.head(key)) {
|
|
76
|
+
run.unchanged++;
|
|
77
|
+
continue;
|
|
78
|
+
}
|
|
79
|
+
const checkpoint: AuditCheckpoint = {
|
|
80
|
+
format: AUDIT_CHECKPOINT_FORMAT,
|
|
81
|
+
tenant,
|
|
82
|
+
count: link.seq,
|
|
83
|
+
head: link.hash,
|
|
84
|
+
takenAt: now.toISOString(),
|
|
85
|
+
};
|
|
86
|
+
// `etagDoesNotMatch: "*"` is "only if no object has this key": a run racing another never replaces one.
|
|
87
|
+
const put = await bucket.put(key, JSON.stringify(AuditCheckpoint.parse(checkpoint)), {
|
|
88
|
+
onlyIf: { etagDoesNotMatch: "*" },
|
|
89
|
+
httpMetadata: { contentType: "application/json" },
|
|
90
|
+
});
|
|
91
|
+
if (put) run.written++;
|
|
92
|
+
else run.unchanged++;
|
|
93
|
+
}
|
|
94
|
+
return run;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/** Which of a chain's checkpoints a read wants: those within a range of positions, and the latest overall. */
|
|
98
|
+
export interface CheckpointRange {
|
|
99
|
+
/** The first position the read covers. */
|
|
100
|
+
fromCount: number;
|
|
101
|
+
/** The last position the read covers, or omitted for the chain's head. */
|
|
102
|
+
throughCount?: number;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/** The checkpoint keys one chain held when it was listed: a snapshot, read before the chain it is held against. */
|
|
106
|
+
export interface CheckpointListing {
|
|
107
|
+
/** The chain the keys are under. */
|
|
108
|
+
tenant: string | null;
|
|
109
|
+
/** Each checkpoint's key and the count it names. */
|
|
110
|
+
entries: { key: string; count: number }[];
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* List one chain's checkpoint keys. A verify or an export lists them **before** it reads the chain's head or rows, so
|
|
115
|
+
* a checkpoint written while the read runs counts at most the head the read then sees. Listed after, it could count
|
|
116
|
+
* an event the read never reached, and an intact chain would read as truncated.
|
|
117
|
+
*/
|
|
118
|
+
export async function listCheckpoints(bucket: R2Bucket, tenant: string | null): Promise<CheckpointListing> {
|
|
119
|
+
const prefix = checkpointPrefix(tenant);
|
|
120
|
+
const entries: { key: string; count: number }[] = [];
|
|
121
|
+
let cursor: string | undefined;
|
|
122
|
+
do {
|
|
123
|
+
const page = await bucket.list({ prefix, ...(cursor ? { cursor } : {}) });
|
|
124
|
+
for (const object of page.objects) {
|
|
125
|
+
const count = countOf(object.key, prefix);
|
|
126
|
+
if (count !== null) entries.push({ key: object.key, count });
|
|
127
|
+
}
|
|
128
|
+
cursor = page.truncated ? page.cursor : undefined;
|
|
129
|
+
} while (cursor);
|
|
130
|
+
return { tenant, entries };
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Every checkpoint of one chain whose count falls in the range, and the latest one whatever its count — the one a
|
|
135
|
+
* truncated tail is caught against. An object that does not parse, or whose body names another chain or count than
|
|
136
|
+
* its key, is skipped: a checkpoint is trusted for what it says only where it says it.
|
|
137
|
+
*
|
|
138
|
+
* Pass a `listing` taken before the chain was read; without one the keys are listed now.
|
|
139
|
+
*/
|
|
140
|
+
export async function readCheckpoints(
|
|
141
|
+
bucket: R2Bucket,
|
|
142
|
+
tenant: string | null,
|
|
143
|
+
range: CheckpointRange,
|
|
144
|
+
listing?: CheckpointListing,
|
|
145
|
+
): Promise<AuditCheckpoint[]> {
|
|
146
|
+
const { entries } = listing && listing.tenant === tenant ? listing : await listCheckpoints(bucket, tenant);
|
|
147
|
+
const wanted: { key: string; count: number }[] = [];
|
|
148
|
+
let latest: { key: string; count: number } | null = null;
|
|
149
|
+
for (const entry of entries) {
|
|
150
|
+
if (!latest || entry.count > latest.count) latest = entry;
|
|
151
|
+
if (entry.count >= range.fromCount && (range.throughCount === undefined || entry.count <= range.throughCount)) {
|
|
152
|
+
wanted.push(entry);
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
if (latest && !wanted.some((entry) => entry.key === latest?.key)) wanted.push(latest);
|
|
156
|
+
|
|
157
|
+
const checkpoints: AuditCheckpoint[] = [];
|
|
158
|
+
for (const { key, count } of wanted.sort((a, b) => a.count - b.count)) {
|
|
159
|
+
const object = await bucket.get(key);
|
|
160
|
+
if (!object) continue;
|
|
161
|
+
let body: unknown;
|
|
162
|
+
try {
|
|
163
|
+
body = JSON.parse(await object.text());
|
|
164
|
+
} catch {
|
|
165
|
+
continue;
|
|
166
|
+
}
|
|
167
|
+
const parsed = AuditCheckpoint.safeParse(body);
|
|
168
|
+
if (!parsed.success || parsed.data.tenant !== tenant || parsed.data.count !== count) continue;
|
|
169
|
+
checkpoints.push(parsed.data);
|
|
170
|
+
}
|
|
171
|
+
return checkpoints;
|
|
172
|
+
}
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
|
|
4
|
+
import {
|
|
5
|
+
type CapabilitySettings,
|
|
6
|
+
SettingsAccountIncomplete,
|
|
7
|
+
type SettingsFinding,
|
|
8
|
+
type UnansweredEnvironment,
|
|
9
|
+
} from "@pithy-sh/core/src/capability/settings";
|
|
10
|
+
import { remedy } from "@pithy-sh/core/src/cli/command";
|
|
11
|
+
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
12
|
+
import { LOCAL_ENVIRONMENT } from "@pithy-sh/core/src/naming/environment";
|
|
13
|
+
import { auditCheckpointBucketName } from "../provision/resolveAuditConfig";
|
|
14
|
+
import { AUDIT_CHECKPOINT_BINDING, AUDIT_CHECKPOINT_LOCK_PREFIX } from "./checkpoint";
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* **`pithy doctor`'s line on the checkpoint bucket's object lock (#822).**
|
|
18
|
+
*
|
|
19
|
+
* A checkpoint is evidence only while nothing can replace it. The Worker cannot tell through its binding whether
|
|
20
|
+
* the bucket is locked, so doctor asks the account, per deployed environment: a bucket with no indefinite lock over
|
|
21
|
+
* the checkpoints is a finding, and so is a bucket that does not exist yet — the chain then has nothing outside the
|
|
22
|
+
* database to be held to. A bucket that is locked says nothing, which is doctor's way of saying it is in force.
|
|
23
|
+
*
|
|
24
|
+
* `dev` is never asked: a developer's checkpoints are a local Miniflare bucket, and no lock means anything there.
|
|
25
|
+
*/
|
|
26
|
+
export function checkpointLockCheck(): CapabilitySettings {
|
|
27
|
+
return {
|
|
28
|
+
local: () => [],
|
|
29
|
+
async account(context) {
|
|
30
|
+
const findings: SettingsFinding[] = [];
|
|
31
|
+
const unanswered: UnansweredEnvironment[] = [];
|
|
32
|
+
for (const { name: environment } of context.environments) {
|
|
33
|
+
if (environment === LOCAL_ENVIRONMENT) continue;
|
|
34
|
+
const bucket = auditCheckpointBucketName(context.project, environment);
|
|
35
|
+
try {
|
|
36
|
+
const ask = context.account.r2BucketLock;
|
|
37
|
+
if (!ask) {
|
|
38
|
+
throw new InternalError({
|
|
39
|
+
message: "This doctor cannot ask whether a bucket is locked.",
|
|
40
|
+
detail: "SettingsAccountReader.r2BucketLock is absent.",
|
|
41
|
+
});
|
|
42
|
+
}
|
|
43
|
+
const state = await ask.call(context.account, { bucket, prefix: AUDIT_CHECKPOINT_LOCK_PREFIX });
|
|
44
|
+
if (state === "locked") continue;
|
|
45
|
+
if (state === "missing") {
|
|
46
|
+
const provision = remedy("provision", { flags: { "--env": environment, "--yes": true } });
|
|
47
|
+
findings.push({
|
|
48
|
+
setting: `${AUDIT_CHECKPOINT_BINDING} bucket`,
|
|
49
|
+
environment,
|
|
50
|
+
problem: `The checkpoint bucket ${bucket} does not exist, so the audit chain is held to nothing outside the database.`,
|
|
51
|
+
action: provision.say((command) => `Run ${command} to create it, then lock it.`),
|
|
52
|
+
...(provision.fix === undefined ? {} : { fix: String(provision.fix) }),
|
|
53
|
+
});
|
|
54
|
+
continue;
|
|
55
|
+
}
|
|
56
|
+
const lock = remedy("audit lock", { flags: { "--env": environment } });
|
|
57
|
+
findings.push({
|
|
58
|
+
setting: `${AUDIT_CHECKPOINT_BINDING} object lock`,
|
|
59
|
+
environment,
|
|
60
|
+
problem: `Object lock is not in force on ${bucket}. Whoever can write the bucket can rewrite the checkpoints the audit chain is verified against.`,
|
|
61
|
+
action: lock.say((command) => `Run ${command} to lock the checkpoints indefinitely.`),
|
|
62
|
+
...(lock.fix === undefined ? {} : { fix: String(lock.fix) }),
|
|
63
|
+
});
|
|
64
|
+
} catch (cause) {
|
|
65
|
+
unanswered.push({ environment, cause });
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
if (unanswered.length > 0) throw new SettingsAccountIncomplete(findings, unanswered);
|
|
69
|
+
return findings;
|
|
70
|
+
},
|
|
71
|
+
};
|
|
72
|
+
}
|