@pithy-sh/audit 0.7.1 → 0.9.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 +1 -1
- package/dist/capability.d.ts +1 -1
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +4 -3
- package/dist/http/guards.d.ts +7 -3
- package/dist/http/guards.d.ts.map +1 -1
- package/dist/http/guards.js +16 -4
- package/dist/http/responses.d.ts +122 -0
- package/dist/http/responses.d.ts.map +1 -1
- package/dist/http/responses.js +38 -1
- package/dist/http/routes.d.ts +8 -3
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +48 -16
- package/dist/http/schemas.d.ts +7 -5
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +9 -7
- package/dist/http/views.d.ts +20 -5
- package/dist/http/views.d.ts.map +1 -1
- package/dist/http/views.js +53 -5
- package/dist/query.d.ts +2 -0
- package/dist/query.d.ts.map +1 -1
- package/dist/query.js +1 -0
- package/dist/ship/consumer.js +1 -1
- package/dist/ship/delivery.d.ts +13 -0
- package/dist/ship/delivery.d.ts.map +1 -0
- package/dist/ship/delivery.js +21 -0
- package/dist/ship/health.d.ts +2 -11
- package/dist/ship/health.d.ts.map +1 -1
- package/dist/ship/health.js +4 -18
- package/dist/usage.d.ts +29 -12
- package/dist/usage.d.ts.map +1 -1
- package/dist/usage.js +23 -9
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/package.json +3 -3
- package/src/capability.ts +19 -20
- package/src/http/guards.ts +17 -4
- package/src/http/responses.ts +109 -0
- package/src/http/routes.ts +74 -20
- package/src/http/schemas.ts +21 -8
- package/src/http/views.ts +58 -5
- package/src/query.ts +7 -0
- package/src/ship/delivery.ts +23 -0
- package/src/ship/health.ts +3 -21
- package/src/usage.ts +37 -16
- package/src/version.generated.ts +1 -1
package/src/capability.ts
CHANGED
|
@@ -49,7 +49,7 @@ export const AUDIT_MIGRATION_ORDER = 250;
|
|
|
49
49
|
* database (`app`, the `DB` binding) by default — so the audit migration tracks alongside the app's
|
|
50
50
|
* in one `pithy_migrations` table rather than fighting it on a second provider over the same binding.
|
|
51
51
|
* The physical binding is config-selectable; this registry key is the coordination point capabilities
|
|
52
|
-
* use to share one database (CLAUDE.md §Data layer
|
|
52
|
+
* use to share one database (CLAUDE.md §Data layer).
|
|
53
53
|
*/
|
|
54
54
|
const AUDIT_DATABASE_NAME = "app" as const;
|
|
55
55
|
|
|
@@ -89,7 +89,7 @@ export type AuditConfigInput = z.input<typeof AuditConfig>;
|
|
|
89
89
|
export interface AuditCapability extends Capability {
|
|
90
90
|
/** The D1 binding the audit table lives in (the resolved `database` config). */
|
|
91
91
|
auditDatabase: string;
|
|
92
|
-
/** The sinks the trail ships to
|
|
92
|
+
/** The sinks the trail ships to, as declared — what `pithy doctor` lists. */
|
|
93
93
|
auditSinks: AuditSinks;
|
|
94
94
|
}
|
|
95
95
|
|
|
@@ -103,7 +103,7 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
103
103
|
const resolved = AuditConfig.parse(config);
|
|
104
104
|
const sinks = resolved.sinks;
|
|
105
105
|
const ships = Object.keys(sinks).length > 0;
|
|
106
|
-
// The tokens each sink reads, declared on audit's own slice
|
|
106
|
+
// The tokens each sink reads, declared on audit's own slice; empty, and not declared, when nothing ships.
|
|
107
107
|
const sinkSecrets = sinkSecretsRegistry(sinks);
|
|
108
108
|
const databaseOf = (c: { var: { db: unknown } }) =>
|
|
109
109
|
(c.var.db as Record<typeof AUDIT_DATABASE_NAME, AuditDatabase>)[AUDIT_DATABASE_NAME];
|
|
@@ -112,16 +112,14 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
112
112
|
let adminRoutes: readonly AdminRoute[] = auditAdminRoutes(resolved.basePath);
|
|
113
113
|
const capability = defineCapability({
|
|
114
114
|
name: "audit",
|
|
115
|
-
//
|
|
116
|
-
//
|
|
117
|
-
// the control-plane manifest, and reported together: a release feed is keyed by package name, so the
|
|
118
|
-
// version alone leaves a client guessing the key (#626).
|
|
115
|
+
// Stamped by `scripts/stampVersions.ts`: a Worker cannot read its own package.json. Reported together, because a
|
|
116
|
+
// release feed is keyed by package name and the version alone leaves a client guessing the key.
|
|
119
117
|
version: PACKAGE_VERSION,
|
|
120
118
|
package: PACKAGE_NAME,
|
|
121
119
|
config: AuditConfig,
|
|
122
120
|
requiredBindings: [
|
|
123
121
|
{ type: "d1", name: resolved.database },
|
|
124
|
-
// The checkpoint bucket
|
|
122
|
+
// The checkpoint bucket: each tenant chain's head and count, written on a schedule by the checkpoint
|
|
125
123
|
// host and read back by the verify and export routes. Optional, so a Worker not yet provisioned still records
|
|
126
124
|
// every event and still verifies links — it says so, as `checkpointStore: "absent"`.
|
|
127
125
|
{ type: "r2", name: AUDIT_CHECKPOINT_BINDING, optional: true },
|
|
@@ -130,12 +128,12 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
130
128
|
...workflowBindings(auditWorkflows),
|
|
131
129
|
// The retention prune's binding: optional, and bound by the adopter to the class their own Worker exports.
|
|
132
130
|
...workflowBindings(auditAppWorkflows),
|
|
133
|
-
// The shipping queue and its dead-letter queue
|
|
131
|
+
// The shipping queue and its dead-letter queue, only when a sink is declared: Cloudflare Queues needs
|
|
134
132
|
// the Workers Paid plan, so a project that ships nothing binds neither. Required when declared — a sink that
|
|
135
133
|
// could never be enqueued to is a config that does not do what it says.
|
|
136
134
|
...shipBindings(sinks),
|
|
137
135
|
],
|
|
138
|
-
// A sink's token is read through `@pithy-sh/secrets`, so a Worker that ships needs it composed
|
|
136
|
+
// A sink's token is read through `@pithy-sh/secrets`, so a Worker that ships needs it composed.
|
|
139
137
|
...(ships
|
|
140
138
|
? {
|
|
141
139
|
dependsOn: ["secrets"],
|
|
@@ -162,10 +160,10 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
162
160
|
}),
|
|
163
161
|
}
|
|
164
162
|
: {}),
|
|
165
|
-
// The checkpoint job
|
|
163
|
+
// The checkpoint job, hosted by the prebuilt audit worker and fired hourly from its cron.
|
|
166
164
|
// And the retention prune, hosted by the adopter's own Worker and fired daily from its cron.
|
|
167
165
|
workflows: { ...auditWorkflows, ...auditAppWorkflows },
|
|
168
|
-
// `pithy doctor` says whether object lock is in force on each deployed environment's checkpoint bucket
|
|
166
|
+
// `pithy doctor` says whether object lock is in force on each deployed environment's checkpoint bucket.
|
|
169
167
|
settings: checkpointLockCheck(),
|
|
170
168
|
databases: {
|
|
171
169
|
[AUDIT_DATABASE_NAME]: {
|
|
@@ -184,9 +182,9 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
184
182
|
},
|
|
185
183
|
seeds: [auditExampleSeed],
|
|
186
184
|
// 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
|
|
185
|
+
// on an access request with the basis that keeps it.
|
|
188
186
|
purge: [auditUserPurge(resolved.database)],
|
|
189
|
-
// The same recorder for code with no request — a Workflow step, which has `env` and nothing else
|
|
187
|
+
// The same recorder for code with no request — a Workflow step, which has `env` and nothing else.
|
|
190
188
|
// Built over the binding this config names, stamped with the env's own origin, and non-fatal on the same
|
|
191
189
|
// terms as the middleware's: a missing binding or a failed insert drops the event and logs it, and the
|
|
192
190
|
// step it records stands. Found by core's `composedAuditEmit`, so the step imports nothing from here.
|
|
@@ -206,14 +204,14 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
206
204
|
});
|
|
207
205
|
};
|
|
208
206
|
},
|
|
209
|
-
// Where a resource's events sit in their chains, for the control plane's erasure attestation
|
|
207
|
+
// Where a resource's events sit in their chains, for the control plane's erasure attestation. Found by
|
|
210
208
|
// core's `composedAuditCitations`, so the attestation imports nothing from here.
|
|
211
209
|
auditCitations: auditCitationsFor(resolved.database),
|
|
212
210
|
// Built from the resolved `basePath`, never the default: an adopter who mounts this at `/trail`
|
|
213
211
|
// gets a manifest naming their paths, where a client assuming the default would 404.
|
|
214
212
|
adminRoutes: auditAdminRoutes(resolved.basePath),
|
|
215
213
|
// The manifest's routes, gathered once at startup: a credential's reach groups the paths it called by the routes
|
|
216
|
-
// this Worker declares
|
|
214
|
+
// this Worker declares, and only `compose` sees every capability.
|
|
217
215
|
compose: ({ capabilities }) => {
|
|
218
216
|
adminRoutes = capabilities.flatMap((capability) => capability.adminRoutes ?? []);
|
|
219
217
|
},
|
|
@@ -228,13 +226,14 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
228
226
|
const bucket = (c.env as Record<string, unknown> | undefined)?.[AUDIT_CHECKPOINT_BINDING];
|
|
229
227
|
return typeof bucket === "object" && bucket !== null ? (bucket as R2Bucket) : null;
|
|
230
228
|
},
|
|
229
|
+
sinks,
|
|
231
230
|
}),
|
|
232
231
|
// Replace the no-op `emit` seam with a recorder over this request's audit database. The database
|
|
233
232
|
// is resolved lazily inside the closure — only when a route actually emits — so a request that
|
|
234
233
|
// never audits never triggers the lazy Kysely build. Runs after createBackend's default-setter
|
|
235
234
|
// (which seeds `db`, `log`, and the no-op `emit`), so `c.var.db` and `c.var.log` are ready by the
|
|
236
|
-
// time emit is called. A non-fatal write failure routes through the logger seam
|
|
237
|
-
//
|
|
235
|
+
// time emit is called. A non-fatal write failure routes through the logger seam as a namespaced
|
|
236
|
+
// `audit/*` record on the `audit` sub-logger.
|
|
238
237
|
middleware: [
|
|
239
238
|
(app) => {
|
|
240
239
|
app.use("*", async (c, next) => {
|
|
@@ -244,7 +243,7 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
244
243
|
// context. `workerIdentity` never throws and returns nulls for whatever is unstamped, so a
|
|
245
244
|
// Worker predating these vars still records its events — just without an origin.
|
|
246
245
|
// The parameter is annotated: `AuditEmit` is generic over `metadata` so a call site carrying a
|
|
247
|
-
// privacy-marked value fails to compile
|
|
246
|
+
// privacy-marked value fails to compile, and the recorder is the one place every event lands.
|
|
248
247
|
const ship = shipperFor(c.env as Record<string, unknown> | undefined, sinks);
|
|
249
248
|
const onShipError = (error: unknown) =>
|
|
250
249
|
c.var.log.child("audit").error("audit shipment not enqueued", { error });
|
|
@@ -252,7 +251,7 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
252
251
|
recordAuditEvent(databaseOf(c), event, {
|
|
253
252
|
origin: workerIdentity(c.env),
|
|
254
253
|
onError: (error) => c.var.log.child("audit").error("audit event dropped", { error }),
|
|
255
|
-
// Enqueued after the response where the runtime allows it
|
|
254
|
+
// Enqueued after the response where the runtime allows it, so shipping never holds the
|
|
256
255
|
// request it records; awaited only where there is no execution context to hand it to.
|
|
257
256
|
...(ship
|
|
258
257
|
? {
|
package/src/http/guards.ts
CHANGED
|
@@ -39,9 +39,9 @@ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/sc
|
|
|
39
39
|
* the other.
|
|
40
40
|
*
|
|
41
41
|
* **Usage rides the listing scope.** `GET {base}/control-plane/usage` counts one connection's calls by scope
|
|
42
|
-
* and key. Its answer is the scope, the key id, and the method and path of the
|
|
43
|
-
* client's own footprint, which the listing already discloses in shape through
|
|
44
|
-
* — and never an IP, a user-agent, or any other metadata key. So it needs no detail scope, and an access review does
|
|
42
|
+
* and key, or every connection's. Its answer is the connection, the scope, the key id, and the method and path of the
|
|
43
|
+
* last allowed call — the management client's own footprint, which the listing already discloses in shape through
|
|
44
|
+
* `action`, `actorId` and `resourceId` — and never an IP, a user-agent, or any other metadata key. So it needs no detail scope, and an access review does
|
|
45
45
|
* not have to hold the most dangerous grant audit defines to ask which grants are used.
|
|
46
46
|
*
|
|
47
47
|
* **The access history rides the listing scope.** `GET {base}/control-plane/access-history` answers every
|
|
@@ -55,6 +55,10 @@ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/sc
|
|
|
55
55
|
* already names in `resourceId`, and the tenant is what it shows as `tenant`; the answer never carries an IP, a user-agent, or a metadata key beyond the key id, scope, method and
|
|
56
56
|
* path. So a breach review does not need the detail scope to draw a breach scope.
|
|
57
57
|
*
|
|
58
|
+
* **The sinks ride the listing scope.** `GET {base}/control-plane/sinks` answers each declared sink's name, profile,
|
|
59
|
+
* host, filter and delivery state — what the manifest's health keys already total behind the same scope. It never
|
|
60
|
+
* carries a token, a secret name, a URL path or query, an event, or anything a receiver answered.
|
|
61
|
+
*
|
|
58
62
|
* **The chain has a scope of its own.** `GET {base}/control-plane/verify` walks one tenant's chain, and
|
|
59
63
|
* `GET {base}/control-plane/export` takes it out in canonical form with its checkpoints. An export is the trail in
|
|
60
64
|
* bulk, meant to leave the building, so neither read rides the listing scope: both need `audit:events:export`. The
|
|
@@ -146,7 +150,7 @@ export function auditAdminRoutes(basePath: string): AdminRouteDeclaration[] {
|
|
|
146
150
|
scope: AUDIT_TRAIL_READ_SCOPE,
|
|
147
151
|
kind: "reads",
|
|
148
152
|
summary:
|
|
149
|
-
"Count which scopes one control-plane connection exercised and was refused, by key, over a window. Counts only — no event is read in full.",
|
|
153
|
+
"Count which scopes one control-plane connection, or every one, exercised and was refused, by key, over a window. Counts only — no event is read in full.",
|
|
150
154
|
},
|
|
151
155
|
{
|
|
152
156
|
method: "GET",
|
|
@@ -166,6 +170,15 @@ export function auditAdminRoutes(basePath: string): AdminRouteDeclaration[] {
|
|
|
166
170
|
summary:
|
|
167
171
|
"Export one tenant's hash chain in canonical form with its checkpoints, to verify offline. Personal values only with the detail scope.",
|
|
168
172
|
},
|
|
173
|
+
{
|
|
174
|
+
method: "GET",
|
|
175
|
+
operation: "sinks.list",
|
|
176
|
+
path: `${basePath}/control-plane/sinks`,
|
|
177
|
+
scope: AUDIT_TRAIL_READ_SCOPE,
|
|
178
|
+
kind: "reads",
|
|
179
|
+
summary:
|
|
180
|
+
"List every sink the trail ships to, with its profile, host and filter, and its backlog, last delivery and dead letters. No event is read.",
|
|
181
|
+
},
|
|
169
182
|
{
|
|
170
183
|
method: "GET",
|
|
171
184
|
operation: "events.read",
|
package/src/http/responses.ts
CHANGED
|
@@ -5,6 +5,8 @@ import { AuditActorType, AuditMetadata, AuditOutcome, AuditSeverity } from "@pit
|
|
|
5
5
|
import { AuditChainExport, ChainBreak, ChainLink } from "@pithy-sh/core/src/audit/chain";
|
|
6
6
|
import { ControlPlaneActorKind } from "@pithy-sh/core/src/controlPlane/data/connection";
|
|
7
7
|
import { z } from "zod";
|
|
8
|
+
import { SHIP_DELIVERY_STATES } from "../ship/delivery";
|
|
9
|
+
import { AuditSinkProfile } from "../ship/sinks";
|
|
8
10
|
|
|
9
11
|
/**
|
|
10
12
|
* What the audit routes return, as Zod objects a management client can validate against.
|
|
@@ -366,6 +368,51 @@ export const ControlPlaneUsageResponse = z
|
|
|
366
368
|
.describe("Which scopes one control-plane connection exercised and was refused, by key, over a window.");
|
|
367
369
|
export type ControlPlaneUsageResponse = z.output<typeof ControlPlaneUsageResponse>;
|
|
368
370
|
|
|
371
|
+
/** One connection's scopes and keys, in the every-connection usage answer. */
|
|
372
|
+
export const ControlPlaneConnectionUsageView = z
|
|
373
|
+
.object({
|
|
374
|
+
connectionId: z.string().describe("The connection that made the calls."),
|
|
375
|
+
usage: z
|
|
376
|
+
.array(ControlPlaneUsageView)
|
|
377
|
+
.describe("One row per scope and key this connection exercised, ordered by scope then key. Never empty."),
|
|
378
|
+
})
|
|
379
|
+
.describe("One control-plane connection's usage, by scope and key.");
|
|
380
|
+
export type ControlPlaneConnectionUsageView = z.output<typeof ControlPlaneConnectionUsageView>;
|
|
381
|
+
|
|
382
|
+
/**
|
|
383
|
+
* `GET {base}/control-plane/usage` with no `connectionId`: every connection that called in the window.
|
|
384
|
+
*
|
|
385
|
+
* A shape of its own, beside {@link ControlPlaneUsageResponse}, so the answer to a named connection is unchanged and
|
|
386
|
+
* a client that names one parses what it always did. Told apart by its keys: `connections` here, `connectionId` and
|
|
387
|
+
* `usage` there.
|
|
388
|
+
*/
|
|
389
|
+
export const ControlPlaneUsageAllResponse = z
|
|
390
|
+
.object({
|
|
391
|
+
since: z.iso.datetime().describe("The window's inclusive start, ISO-8601."),
|
|
392
|
+
until: z.iso.datetime().describe("The window's inclusive end, ISO-8601 — now, when the query named none."),
|
|
393
|
+
connections: z
|
|
394
|
+
.array(ControlPlaneConnectionUsageView)
|
|
395
|
+
.describe(
|
|
396
|
+
"One entry per connection that made a call in the window, ordered by connection id. A connection that made none is absent: join against the connection listing for it.",
|
|
397
|
+
),
|
|
398
|
+
oldestEventAt: z.iso
|
|
399
|
+
.datetime()
|
|
400
|
+
.nullable()
|
|
401
|
+
.describe(
|
|
402
|
+
"The oldest event the trail holds, for any connection, or null on an empty trail. A window starting before it was not fully covered: retention removed what came before.",
|
|
403
|
+
),
|
|
404
|
+
})
|
|
405
|
+
.describe("Which scopes every control-plane connection exercised and was refused, by key, over a window.");
|
|
406
|
+
export type ControlPlaneUsageAllResponse = z.output<typeof ControlPlaneUsageAllResponse>;
|
|
407
|
+
|
|
408
|
+
/** What the usage route answers: one connection's usage when the query names one, every connection's when not. */
|
|
409
|
+
export const ControlPlaneUsageReadResponse = z
|
|
410
|
+
.union([ControlPlaneUsageResponse, ControlPlaneUsageAllResponse])
|
|
411
|
+
.describe(
|
|
412
|
+
"One connection's usage when `connectionId` is named, as `ControlPlaneUsageResponse`; every connection's when it is not, as `ControlPlaneUsageAllResponse`.",
|
|
413
|
+
);
|
|
414
|
+
export type ControlPlaneUsageReadResponse = z.output<typeof ControlPlaneUsageReadResponse>;
|
|
415
|
+
|
|
369
416
|
/** `GET {base}/control-plane/verify`. */
|
|
370
417
|
export const ChainVerifyResponse = z
|
|
371
418
|
.object({
|
|
@@ -421,3 +468,65 @@ export const ChainExportResponse = AuditChainExport.describe(
|
|
|
421
468
|
"One page of one tenant's audit chain: canonical events, their hashes, the link before them and the checkpoints covering them.",
|
|
422
469
|
);
|
|
423
470
|
export type ChainExportResponse = z.output<typeof ChainExportResponse>;
|
|
471
|
+
|
|
472
|
+
/** One declared sink, as `GET {base}/control-plane/sinks` shows it. Never its URL path, its query or its token. */
|
|
473
|
+
export const AuditSinkView = z
|
|
474
|
+
.object({
|
|
475
|
+
name: z.string().describe("The sink's name, as `audit({ sinks })` declares it."),
|
|
476
|
+
profile: AuditSinkProfile.describe(
|
|
477
|
+
"The format the sink is delivered in: `splunk-hec`, `datadog-logs` or `webhook`.",
|
|
478
|
+
),
|
|
479
|
+
host: z
|
|
480
|
+
.string()
|
|
481
|
+
.describe(
|
|
482
|
+
"The host the sink posts to, with its port when the URL names one. Never the path or query, which may carry a key.",
|
|
483
|
+
),
|
|
484
|
+
detail: z
|
|
485
|
+
.boolean()
|
|
486
|
+
.describe(
|
|
487
|
+
"Whether the sink receives each event's IP, user-agent and metadata values, rather than their salted hashes.",
|
|
488
|
+
),
|
|
489
|
+
actions: z
|
|
490
|
+
.array(z.string().describe("An action prefix the sink takes, e.g. `auth/`."))
|
|
491
|
+
.nullable()
|
|
492
|
+
.describe("The action prefixes the sink takes, or null when it takes every action the trail records."),
|
|
493
|
+
lastDeliveredAt: z.iso
|
|
494
|
+
.datetime()
|
|
495
|
+
.nullable()
|
|
496
|
+
.describe("When the sink last accepted a delivery, ISO-8601, or null when it never has."),
|
|
497
|
+
lastFailedAt: z.iso
|
|
498
|
+
.datetime()
|
|
499
|
+
.nullable()
|
|
500
|
+
.describe("When the sink last refused a delivery or could not be reached, ISO-8601, or null when it never has."),
|
|
501
|
+
retrying: z
|
|
502
|
+
.number()
|
|
503
|
+
.int()
|
|
504
|
+
.nonnegative()
|
|
505
|
+
.describe(
|
|
506
|
+
"How many events are waiting on a retry to this sink: its backlog. The manifest's `auditShipBacklog` is the sum over every sink.",
|
|
507
|
+
),
|
|
508
|
+
deadLettered: z
|
|
509
|
+
.number()
|
|
510
|
+
.int()
|
|
511
|
+
.nonnegative()
|
|
512
|
+
.describe(
|
|
513
|
+
"How many events this sink never took: their retries ran out and they went to the dead-letter queue. The manifest's `auditShipDeadLettered` is the sum.",
|
|
514
|
+
),
|
|
515
|
+
delivery: z
|
|
516
|
+
.enum(SHIP_DELIVERY_STATES)
|
|
517
|
+
.describe(
|
|
518
|
+
"How delivery to this sink stands: `failing` when its last attempt failed, `delivering` when it last took one, `idle` when it has never been attempted.",
|
|
519
|
+
),
|
|
520
|
+
})
|
|
521
|
+
.describe("One sink the trail ships to: where, what it takes, and how delivery to it stands.");
|
|
522
|
+
export type AuditSinkView = z.output<typeof AuditSinkView>;
|
|
523
|
+
|
|
524
|
+
/** `GET {base}/control-plane/sinks`. */
|
|
525
|
+
export const AuditSinksResponse = z
|
|
526
|
+
.object({
|
|
527
|
+
sinks: z
|
|
528
|
+
.array(AuditSinkView)
|
|
529
|
+
.describe("Every declared sink, in declaration order. Empty when the Worker ships nothing."),
|
|
530
|
+
})
|
|
531
|
+
.describe("Every sink the trail ships to, each with its backlog, last delivery and dead letters.");
|
|
532
|
+
export type AuditSinksResponse = z.output<typeof AuditSinksResponse>;
|
package/src/http/routes.ts
CHANGED
|
@@ -19,16 +19,21 @@ import type { AuditDatabase } from "../data/tables";
|
|
|
19
19
|
import { pageAuditEvents, readAuditEvent } from "../query";
|
|
20
20
|
import { controlPlaneReach, controlPlaneReachSubjects } from "../reach";
|
|
21
21
|
import { reachPatterns } from "../routePattern";
|
|
22
|
+
import type { AuditSinks } from "../ship/sinks";
|
|
23
|
+
import { readSinkStates } from "../ship/state";
|
|
22
24
|
import { controlPlaneUsage } from "../usage";
|
|
23
25
|
import { AUDIT_CHAIN_EXPORT_SCOPE, AUDIT_EVENT_DETAIL_READ_SCOPE, AUDIT_TRAIL_READ_SCOPE } from "./guards";
|
|
24
26
|
import {
|
|
25
27
|
AccessHistoryResponse,
|
|
26
28
|
AuditEventResponse,
|
|
27
29
|
AuditEventsResponse,
|
|
30
|
+
AuditSinksResponse,
|
|
28
31
|
ChainExportResponse,
|
|
29
32
|
ChainVerifyResponse,
|
|
30
33
|
ControlPlaneReachResponse,
|
|
31
|
-
|
|
34
|
+
type ControlPlaneUsageAllResponse,
|
|
35
|
+
ControlPlaneUsageReadResponse,
|
|
36
|
+
type ControlPlaneUsageResponse,
|
|
32
37
|
} from "./responses";
|
|
33
38
|
import {
|
|
34
39
|
AccessHistoryQuery,
|
|
@@ -43,6 +48,8 @@ import {
|
|
|
43
48
|
accessChangeView,
|
|
44
49
|
auditEventDetailView,
|
|
45
50
|
auditEventView,
|
|
51
|
+
auditSinkViews,
|
|
52
|
+
controlPlaneConnectionUsageViews,
|
|
46
53
|
controlPlaneReachSubjectView,
|
|
47
54
|
controlPlaneReachView,
|
|
48
55
|
controlPlaneUsageView,
|
|
@@ -57,15 +64,17 @@ import {
|
|
|
57
64
|
* (control-plane: audit:events:read) query: AccessHistoryQuery
|
|
58
65
|
* GET /audit/control-plane/reach → what one credential reached, by tenant, route and outcome
|
|
59
66
|
* (control-plane: audit:events:read) query: ControlPlaneReachQuery
|
|
60
|
-
* GET /audit/control-plane/usage → one connection's calls, counted by scope and key
|
|
67
|
+
* GET /audit/control-plane/usage → one connection's calls, or every connection's, counted by scope and key
|
|
61
68
|
* (control-plane: audit:events:read) query: ControlPlaneUsageQuery
|
|
62
69
|
* GET /audit/control-plane/verify → whether one tenant's hash chain is whole, or where it breaks
|
|
63
70
|
* (control-plane: audit:events:export) query: ChainVerifyQuery
|
|
64
71
|
* GET /audit/control-plane/export → one tenant's chain in canonical form, with its checkpoints
|
|
65
72
|
* (control-plane: audit:events:export) query: ChainExportQuery
|
|
73
|
+
* GET /audit/control-plane/sinks → every declared sink and how delivery to it stands
|
|
74
|
+
* (control-plane: audit:events:read) no input
|
|
66
75
|
*
|
|
67
76
|
* **All are reads, and there is nothing else.** The trail is append-only: no route here deletes,
|
|
68
|
-
* edits, or prunes, because a management credential that could erase an audit row could erase the
|
|
77
|
+
* edits, or prunes, and no route adds, changes or removes a sink, because a management credential that could erase an audit row could erase the
|
|
69
78
|
* evidence of its own use. Retention is a lifecycle concern for a Workflow, not a button on a
|
|
70
79
|
* dashboard.
|
|
71
80
|
*
|
|
@@ -106,6 +115,7 @@ export const AUDIT_ROUTES: readonly AuditRouteDeclaration[] = [
|
|
|
106
115
|
{ method: "GET", path: "/control-plane/usage", strategy: "control-plane", scope: AUDIT_TRAIL_READ_SCOPE },
|
|
107
116
|
{ method: "GET", path: "/control-plane/verify", strategy: "control-plane", scope: AUDIT_CHAIN_EXPORT_SCOPE },
|
|
108
117
|
{ method: "GET", path: "/control-plane/export", strategy: "control-plane", scope: AUDIT_CHAIN_EXPORT_SCOPE },
|
|
118
|
+
{ method: "GET", path: "/control-plane/sinks", strategy: "control-plane", scope: AUDIT_TRAIL_READ_SCOPE },
|
|
109
119
|
];
|
|
110
120
|
|
|
111
121
|
/** How the audit sub-router is built. */
|
|
@@ -125,10 +135,12 @@ export interface AuditRoutesOptions {
|
|
|
125
135
|
*/
|
|
126
136
|
adminRoutes: () => readonly AdminRoute[];
|
|
127
137
|
/**
|
|
128
|
-
* The checkpoint bucket for this request, or null when the Worker binds none
|
|
138
|
+
* The checkpoint bucket for this request, or null when the Worker binds none. Absent, verify checks links
|
|
129
139
|
* alone and says so, and an export carries no checkpoints.
|
|
130
140
|
*/
|
|
131
141
|
checkpoints?: (c: Context<PithyHonoEnv>) => R2Bucket | null;
|
|
142
|
+
/** The sinks the trail ships to, as declared. Absent, the sinks read answers an empty list. */
|
|
143
|
+
sinks?: AuditSinks;
|
|
132
144
|
}
|
|
133
145
|
|
|
134
146
|
/**
|
|
@@ -178,6 +190,7 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
178
190
|
const database = options.database;
|
|
179
191
|
const adminRoutes = options.adminRoutes;
|
|
180
192
|
const checkpoints = options.checkpoints ?? (() => null);
|
|
193
|
+
const sinks = options.sinks ?? {};
|
|
181
194
|
|
|
182
195
|
return (app) => {
|
|
183
196
|
/**
|
|
@@ -273,7 +286,7 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
273
286
|
);
|
|
274
287
|
|
|
275
288
|
/**
|
|
276
|
-
* CONTROL-PLANE READ
|
|
289
|
+
* CONTROL-PLANE READ. Who could do what, over time: every membership, connection and key change in a
|
|
277
290
|
* window, oldest first, with its before and after — one SQL statement per page, never a walk of events here.
|
|
278
291
|
* Behind the listing scope, not the detail one: it lifts named metadata keys and never an IP or a user-agent.
|
|
279
292
|
*/
|
|
@@ -328,7 +341,7 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
328
341
|
);
|
|
329
342
|
|
|
330
343
|
/**
|
|
331
|
-
* CONTROL-PLANE READ
|
|
344
|
+
* CONTROL-PLANE READ. What one credential reached — by tenant, action, method, route and outcome — over a
|
|
332
345
|
* window, in one SQL statement, never by paging events here. `subjects=true` expands one route into the subject
|
|
333
346
|
* ids its called paths name. Behind the listing scope, not the detail one: the answer is the tenant, the route,
|
|
334
347
|
* the scope and ids the listing already shows, and never an IP, a user-agent or any other metadata key.
|
|
@@ -401,18 +414,20 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
401
414
|
);
|
|
402
415
|
|
|
403
416
|
/**
|
|
404
|
-
* CONTROL-PLANE READ
|
|
405
|
-
* counted in one SQL statement, never by paging events here.
|
|
406
|
-
*
|
|
407
|
-
*
|
|
417
|
+
* CONTROL-PLANE READ. Which scopes one connection exercised and was refused, by key, over a window —
|
|
418
|
+
* counted in one SQL statement, never by paging events here. With no `connectionId`, every connection that called
|
|
419
|
+
* in the window, each with its own scopes and keys, from the same one statement. Behind the listing
|
|
420
|
+
* scope, not the detail one: the answer is the connection, the scope, the key, and the last allowed call's method
|
|
421
|
+
* and path, and never an IP, a user-agent or any other metadata key.
|
|
408
422
|
*/
|
|
409
423
|
app.get(
|
|
410
424
|
`${base}/control-plane/usage`,
|
|
411
425
|
describeRoute({
|
|
412
|
-
summary:
|
|
426
|
+
summary:
|
|
427
|
+
"Count which scopes one control-plane connection, or every one, exercised and was refused, by key, over a window.",
|
|
413
428
|
verification: "control-plane",
|
|
414
429
|
scopes: [AUDIT_TRAIL_READ_SCOPE],
|
|
415
|
-
responses: { 200:
|
|
430
|
+
responses: { 200: ControlPlaneUsageReadResponse },
|
|
416
431
|
}),
|
|
417
432
|
requireControlPlane(AUDIT_TRAIL_READ_SCOPE),
|
|
418
433
|
validate("query", ControlPlaneUsageQuery),
|
|
@@ -420,32 +435,51 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
420
435
|
const operator = caller(c);
|
|
421
436
|
const query = c.req.valid("query");
|
|
422
437
|
const window = { since: query.since, until: query.until ?? new Date() };
|
|
423
|
-
const
|
|
424
|
-
|
|
425
|
-
|
|
438
|
+
const named = query.connectionId;
|
|
439
|
+
const result = await controlPlaneUsage(database(c), {
|
|
440
|
+
...(named !== undefined ? { connectionId: named } : {}),
|
|
441
|
+
...window,
|
|
442
|
+
});
|
|
443
|
+
const connections = named === undefined ? controlPlaneConnectionUsageViews(result.usage) : undefined;
|
|
444
|
+
// Audited like the listing, once. Named, against the connection whose usage was read: "who reviewed this
|
|
445
|
+
// connection's grants" is a question the trail should answer about that connection. Unnamed, against no
|
|
446
|
+
// one connection: `query.connectionId` is null, which is "every connection", and `connections` names each
|
|
447
|
+
// one the answer covered, so the same question still finds this read from any of them.
|
|
426
448
|
await c.var.emit({
|
|
427
449
|
action: AuditTrailActions.usageRead,
|
|
428
450
|
outcome: "success",
|
|
429
451
|
actorType: "control-plane",
|
|
430
452
|
actorId: operator.subject,
|
|
431
453
|
resourceType: "controlplane_connection",
|
|
432
|
-
resourceId:
|
|
454
|
+
...(named !== undefined ? { resourceId: named } : {}),
|
|
433
455
|
requestId: c.req.header("cf-ray"),
|
|
434
456
|
ip: c.req.header("cf-connecting-ip"),
|
|
435
457
|
userAgent: c.req.header("user-agent"),
|
|
436
458
|
metadata: {
|
|
437
459
|
connectionId: operator.connectionId,
|
|
438
460
|
query: {
|
|
439
|
-
connectionId:
|
|
461
|
+
connectionId: named ?? null,
|
|
440
462
|
since: window.since.toISOString(),
|
|
441
463
|
until: window.until.toISOString(),
|
|
442
464
|
},
|
|
465
|
+
...(connections !== undefined ? { connections: connections.map((entry) => entry.connectionId) } : {}),
|
|
443
466
|
returned: result.usage.length,
|
|
444
467
|
},
|
|
445
468
|
});
|
|
469
|
+
if (named === undefined) {
|
|
470
|
+
return c.json(
|
|
471
|
+
{
|
|
472
|
+
since: window.since.toISOString(),
|
|
473
|
+
until: window.until.toISOString(),
|
|
474
|
+
connections: connections ?? [],
|
|
475
|
+
oldestEventAt: result.oldestEventAt?.toISOString() ?? null,
|
|
476
|
+
} satisfies ControlPlaneUsageAllResponse,
|
|
477
|
+
200,
|
|
478
|
+
);
|
|
479
|
+
}
|
|
446
480
|
return c.json(
|
|
447
481
|
{
|
|
448
|
-
connectionId:
|
|
482
|
+
connectionId: named,
|
|
449
483
|
since: window.since.toISOString(),
|
|
450
484
|
until: window.until.toISOString(),
|
|
451
485
|
usage: result.usage.map(controlPlaneUsageView),
|
|
@@ -457,7 +491,7 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
457
491
|
);
|
|
458
492
|
|
|
459
493
|
/**
|
|
460
|
-
* CONTROL-PLANE READ
|
|
494
|
+
* CONTROL-PLANE READ. Walk one tenant's hash chain over a window — every link, every hash, the
|
|
461
495
|
* checkpoints covering it — and answer intact or the first break. Reads only: it proves the trail whole and
|
|
462
496
|
* changes nothing.
|
|
463
497
|
*/
|
|
@@ -526,7 +560,7 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
526
560
|
);
|
|
527
561
|
|
|
528
562
|
/**
|
|
529
|
-
* CONTROL-PLANE READ
|
|
563
|
+
* CONTROL-PLANE READ. One page of one tenant's chain in canonical form, each event with its hash, the
|
|
530
564
|
* link before the page and the checkpoints covering it — what `pithy audit verify` checks offline. The IP,
|
|
531
565
|
* user-agent and metadata values ride along only when the connection also holds the detail scope.
|
|
532
566
|
*/
|
|
@@ -586,5 +620,25 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
586
620
|
return c.json(page satisfies ChainExportResponse, 200);
|
|
587
621
|
},
|
|
588
622
|
);
|
|
623
|
+
|
|
624
|
+
/**
|
|
625
|
+
* CONTROL-PLANE READ. Every declared sink beside its own delivery row: one primary-key lookup per sink, bounded
|
|
626
|
+
* by the config. Records no audit action of its own, unlike the trail's reads: it reads delivery state, never
|
|
627
|
+
* the trail, so the gate's `controlplane/call_allowed` row is its only record.
|
|
628
|
+
*/
|
|
629
|
+
app.get(
|
|
630
|
+
`${base}/control-plane/sinks`,
|
|
631
|
+
describeRoute({
|
|
632
|
+
summary: "List every sink the trail ships to, each with its backlog, last delivery and dead letters.",
|
|
633
|
+
verification: "control-plane",
|
|
634
|
+
scopes: [AUDIT_TRAIL_READ_SCOPE],
|
|
635
|
+
responses: { 200: AuditSinksResponse },
|
|
636
|
+
}),
|
|
637
|
+
requireControlPlane(AUDIT_TRAIL_READ_SCOPE),
|
|
638
|
+
async (c) => {
|
|
639
|
+
const states = await readSinkStates(database(c), Object.keys(sinks));
|
|
640
|
+
return c.json({ sinks: auditSinkViews(sinks, states) } satisfies AuditSinksResponse, 200);
|
|
641
|
+
},
|
|
642
|
+
);
|
|
589
643
|
};
|
|
590
644
|
}
|
package/src/http/schemas.ts
CHANGED
|
@@ -81,7 +81,19 @@ export const ListAuditEventsQuery = z
|
|
|
81
81
|
),
|
|
82
82
|
action: AuditAction.max(MAX_FILTER_LENGTH)
|
|
83
83
|
.optional()
|
|
84
|
-
.describe("Filter to one exact `domain/reason` action code. Exact
|
|
84
|
+
.describe("Filter to one exact `domain/reason` action code. Exact; `actionPrefix` is the domain-wide filter."),
|
|
85
|
+
actionPrefix: z
|
|
86
|
+
.string()
|
|
87
|
+
.regex(
|
|
88
|
+
/^[a-z][a-z0-9]*\/?$/,
|
|
89
|
+
"An action prefix is one domain, lowercase, with or without its trailing `/` (e.g. `auth` or `auth/`).",
|
|
90
|
+
)
|
|
91
|
+
.max(MAX_FILTER_LENGTH)
|
|
92
|
+
.transform((value) => value.replace(/\/$/, ""))
|
|
93
|
+
.optional()
|
|
94
|
+
.describe(
|
|
95
|
+
"Filter to every action under one domain — `auth` or `auth/` matches `auth/login` and `auth/logout`, never `authority/granted`. The domain is the only prefix: a reason is never matched by its start.",
|
|
96
|
+
),
|
|
85
97
|
outcome: AuditOutcome.optional().describe(
|
|
86
98
|
"Filter to one outcome. `denied` is the one worth watching: a run of denials is what a credential being probed looks like.",
|
|
87
99
|
),
|
|
@@ -191,15 +203,16 @@ export type ControlPlaneReachQuery = z.infer<typeof ControlPlaneReachQuery>;
|
|
|
191
203
|
/**
|
|
192
204
|
* The usage query: whose calls to count, and over what window.
|
|
193
205
|
*
|
|
194
|
-
* `
|
|
195
|
-
*
|
|
196
|
-
*
|
|
197
|
-
*
|
|
206
|
+
* `since` is required, so a missing one is a 400 before any query runs — an unbounded window is not a question this
|
|
207
|
+
* route answers. `connectionId` is optional: named, the route counts that connection's calls; left out, it counts every
|
|
208
|
+
* connection's, which is the over-grant question across a Worker in one read. `until` defaults to now in the
|
|
209
|
+
* handler, which is the one value a schema cannot compute for a request. A window that ends before it starts is
|
|
210
|
+
* refused rather than answered with nothing, because nothing would read as an idle connection.
|
|
198
211
|
*/
|
|
199
212
|
export const ControlPlaneUsageQuery = z
|
|
200
213
|
.object({
|
|
201
|
-
connectionId: FilterValue.describe(
|
|
202
|
-
"The control-plane connection whose calls to count — the `resourceId` its call rows carry.
|
|
214
|
+
connectionId: FilterValue.optional().describe(
|
|
215
|
+
"The control-plane connection whose calls to count — the `resourceId` its call rows carry. Omit it to count every connection's.",
|
|
203
216
|
),
|
|
204
217
|
since: TimeBound.describe("Inclusive lower bound on when a call landed, ISO-8601. Required."),
|
|
205
218
|
until: TimeBound.optional().describe("Inclusive upper bound on when a call landed, ISO-8601. Defaults to now."),
|
|
@@ -208,7 +221,7 @@ export const ControlPlaneUsageQuery = z
|
|
|
208
221
|
message: "`until` must not be before `since`.",
|
|
209
222
|
path: ["until"],
|
|
210
223
|
})
|
|
211
|
-
.describe("The control-plane usage query: one connection, over a window.");
|
|
224
|
+
.describe("The control-plane usage query: one connection or every connection, over a window.");
|
|
212
225
|
export type ControlPlaneUsageQuery = z.infer<typeof ControlPlaneUsageQuery>;
|
|
213
226
|
|
|
214
227
|
/**
|