@pithy-sh/audit 0.6.0 → 0.7.1
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/dist/usage.d.ts
ADDED
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
import type { AuditDatabase } from "./data/tables";
|
|
5
|
+
/**
|
|
6
|
+
* Which scopes a control-plane connection exercised, and which it was refused — `#812`.
|
|
7
|
+
*
|
|
8
|
+
* Every admitted call writes `controlplane/call_allowed`, and every verified call refused a scope writes
|
|
9
|
+
* `controlplane/call_denied`, both against the connection as `resourceId` and both naming the scope and key in
|
|
10
|
+
* `metadata`. Answering "granted twelve, used three" from the listing would take one forensic read per event, behind
|
|
11
|
+
* the scope that also discloses the client IP; this reads the same rows in SQL and returns counts.
|
|
12
|
+
*
|
|
13
|
+
* **One statement for the aggregate, never a page walk.** A dashboard connection makes thousands of calls a day, and a
|
|
14
|
+
* handler that paged them to count would be the largest read on the surface. The `GROUP BY` runs in D1, over rows
|
|
15
|
+
* `pithyAuditEventsCallIdx` (`audit_0003_call_index`) finds by action, connection and time.
|
|
16
|
+
*
|
|
17
|
+
* **Nothing personal leaves this function.** It reads the scope, the key id, and the method and path of the last
|
|
18
|
+
* allowed call out of `metadata`, and no other key, and never the IP or the user-agent. Those four are the management
|
|
19
|
+
* client's own footprint.
|
|
20
|
+
*/
|
|
21
|
+
/** What to count: one connection, over an inclusive window. */
|
|
22
|
+
export interface ControlPlaneUsageFilter {
|
|
23
|
+
/** The connection whose calls are counted — the rows' `resourceId`. */
|
|
24
|
+
connectionId: string;
|
|
25
|
+
/** Inclusive lower bound on `occurredAt`. */
|
|
26
|
+
since: Date;
|
|
27
|
+
/** Inclusive upper bound on `occurredAt`. */
|
|
28
|
+
until: Date;
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* One `(scope, keyId)` a connection exercised, decoded from the aggregate's row.
|
|
32
|
+
*
|
|
33
|
+
* Internal: the wire shape is `ControlPlaneUsageView` in `http/responses.ts`, and `http/views.ts` projects this into it.
|
|
34
|
+
*/
|
|
35
|
+
export declare const ControlPlaneUsageRow: z.ZodObject<{
|
|
36
|
+
scope: z.ZodString;
|
|
37
|
+
keyId: z.ZodNullable<z.ZodString>;
|
|
38
|
+
allowed: z.ZodNumber;
|
|
39
|
+
denied: z.ZodNumber;
|
|
40
|
+
lastAllowedAt: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>;
|
|
41
|
+
lastAllowedMethod: z.ZodNullable<z.ZodString>;
|
|
42
|
+
lastAllowedPath: z.ZodNullable<z.ZodString>;
|
|
43
|
+
lastDeniedAt: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>;
|
|
44
|
+
}, z.core.$strip>;
|
|
45
|
+
export type ControlPlaneUsageRow = z.output<typeof ControlPlaneUsageRow>;
|
|
46
|
+
/** What {@link controlPlaneUsage} answers. */
|
|
47
|
+
export interface ControlPlaneUsage {
|
|
48
|
+
/** One row per `(scope, keyId)` exercised, ordered by scope then key. */
|
|
49
|
+
usage: ControlPlaneUsageRow[];
|
|
50
|
+
/** The oldest event the trail holds, or null on an empty trail. */
|
|
51
|
+
oldestEventAt: Date | null;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* The aggregate, as one Kysely statement — exported so a test can read its query plan.
|
|
55
|
+
*
|
|
56
|
+
* Three steps, in one statement:
|
|
57
|
+
*
|
|
58
|
+
* 1. **`calls`** — the connection's call rows in the window, with the scope, key, method and path lifted out of
|
|
59
|
+
* `metadata`. The scope is read from where each writer puts it: an allowed row carries the token's `scope`; a gate
|
|
60
|
+
* refusal names the scope it required as `required`, and a handler's refusal as `scope`, so a denied row reads
|
|
61
|
+
* `required` first. A row with no scope at all is nobody's usage and is dropped.
|
|
62
|
+
* 2. **`ranked`** — each row's recency within its `(scope, keyId, action)`, newest first, `id` breaking a tie. Rank 1
|
|
63
|
+
* of the allowed rows is the last allowed call, whose method and path the answer carries.
|
|
64
|
+
* 3. **The group** — counts and last instants per `(scope, keyId)`.
|
|
65
|
+
*/
|
|
66
|
+
export declare function controlPlaneUsageStatement(db: AuditDatabase, filter: ControlPlaneUsageFilter): import("kysely").SelectQueryBuilder<import("@pithy-sh/core/src/data/db").DatabaseSchema<{
|
|
67
|
+
pithyAuditEvents: z.ZodObject<{
|
|
68
|
+
id: z.ZodNumber;
|
|
69
|
+
eventId: z.ZodString;
|
|
70
|
+
occurredAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
|
|
71
|
+
action: z.ZodString;
|
|
72
|
+
outcome: z.ZodEnum<{
|
|
73
|
+
denied: "denied";
|
|
74
|
+
failure: "failure";
|
|
75
|
+
success: "success";
|
|
76
|
+
}>;
|
|
77
|
+
severity: z.ZodEnum<{
|
|
78
|
+
critical: "critical";
|
|
79
|
+
info: "info";
|
|
80
|
+
warning: "warning";
|
|
81
|
+
}>;
|
|
82
|
+
actorType: z.ZodEnum<{
|
|
83
|
+
anonymous: "anonymous";
|
|
84
|
+
"control-plane": "control-plane";
|
|
85
|
+
service: "service";
|
|
86
|
+
system: "system";
|
|
87
|
+
user: "user";
|
|
88
|
+
}>;
|
|
89
|
+
actorId: z.ZodNullable<z.ZodString>;
|
|
90
|
+
actorKind: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
|
|
91
|
+
agent: "agent";
|
|
92
|
+
dashboard: "dashboard";
|
|
93
|
+
script: "script";
|
|
94
|
+
}>>>;
|
|
95
|
+
sessionId: z.ZodNullable<z.ZodString>;
|
|
96
|
+
resourceType: z.ZodNullable<z.ZodString>;
|
|
97
|
+
resourceId: z.ZodNullable<z.ZodString>;
|
|
98
|
+
ip: z.ZodNullable<z.ZodString>;
|
|
99
|
+
userAgent: z.ZodNullable<z.ZodString>;
|
|
100
|
+
requestId: z.ZodNullable<z.ZodString>;
|
|
101
|
+
metadata: z.ZodNullable<import("@pithy-sh/core/src/data/codecs").SqliteJson<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
|
|
102
|
+
project: z.ZodNullable<z.ZodString>;
|
|
103
|
+
environment: z.ZodNullable<z.ZodString>;
|
|
104
|
+
worker: z.ZodNullable<z.ZodString>;
|
|
105
|
+
version: z.ZodNullable<z.ZodString>;
|
|
106
|
+
tenant: z.ZodNullable<z.ZodString>;
|
|
107
|
+
chainSeq: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
|
|
108
|
+
chainPrev: z.ZodDefault<z.ZodNullable<z.ZodString>>;
|
|
109
|
+
chainHash: z.ZodDefault<z.ZodNullable<z.ZodString>>;
|
|
110
|
+
chainSalt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
|
|
111
|
+
}, z.core.$strip>;
|
|
112
|
+
pithyAuditSinks: z.ZodObject<{
|
|
113
|
+
sink: z.ZodString;
|
|
114
|
+
lastDeliveredAt: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>;
|
|
115
|
+
lastFailedAt: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>;
|
|
116
|
+
retrying: z.ZodNumber;
|
|
117
|
+
deadLettered: z.ZodNumber;
|
|
118
|
+
}, z.core.$strip>;
|
|
119
|
+
}> & {
|
|
120
|
+
calls: {
|
|
121
|
+
action: string;
|
|
122
|
+
id: number;
|
|
123
|
+
keyId: string | null;
|
|
124
|
+
method: string | null;
|
|
125
|
+
occurredAt: string | number | Date;
|
|
126
|
+
path: string | null;
|
|
127
|
+
scope: string | null;
|
|
128
|
+
};
|
|
129
|
+
} & {
|
|
130
|
+
ranked: {
|
|
131
|
+
action: string;
|
|
132
|
+
id: number;
|
|
133
|
+
keyId: string | null;
|
|
134
|
+
method: string | null;
|
|
135
|
+
occurredAt: string | number | Date;
|
|
136
|
+
path: string | null;
|
|
137
|
+
recency: number;
|
|
138
|
+
scope: string | null;
|
|
139
|
+
};
|
|
140
|
+
}, "ranked", {
|
|
141
|
+
allowed: number;
|
|
142
|
+
denied: number;
|
|
143
|
+
keyId: string | null;
|
|
144
|
+
lastAllowedAt: number | null;
|
|
145
|
+
lastAllowedMethod: string | null;
|
|
146
|
+
lastAllowedPath: string | null;
|
|
147
|
+
lastDeniedAt: number | null;
|
|
148
|
+
scope: string | null;
|
|
149
|
+
}>;
|
|
150
|
+
/**
|
|
151
|
+
* Count one connection's calls by scope and key, over an inclusive window.
|
|
152
|
+
*
|
|
153
|
+
* `oldestEventAt` is the oldest event the trail holds at all, for any connection or none. Retention prunes the trail
|
|
154
|
+
* by time, never per connection, so this is how far back any connection's answer can reach: a window starting before
|
|
155
|
+
* it was not fully covered, and a client can say so rather than read a short count as a quiet connection. Read through
|
|
156
|
+
* `pithyAuditEventsOccurredAtIdx`, so it costs one index probe however large the trail is.
|
|
157
|
+
*/
|
|
158
|
+
export declare function controlPlaneUsage(db: AuditDatabase, filter: ControlPlaneUsageFilter): Promise<ControlPlaneUsage>;
|
|
159
|
+
//# sourceMappingURL=usage.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;;;;;;;;;;;;;;GAeG;AAEH,+DAA+D;AAC/D,MAAM,WAAW,uBAAuB;IACtC,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,KAAK,EAAE,IAAI,CAAC;IACZ,6CAA6C;IAC7C,KAAK,EAAE,IAAI,CAAC;CACb;AAQD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;iBAkBkE,CAAC;AACpG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AASzE,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,mEAAmE;IACnE,aAAa,EAAE,IAAI,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwD5F;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,aAAa,EACjB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,iBAAiB,CAAC,CAU5B"}
|
package/dist/usage.js
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
import { ControlPlaneAuditActions } from "@pithy-sh/core/src/controlPlane/audit/actions";
|
|
4
|
+
import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
|
|
5
|
+
import { sql } from "kysely";
|
|
6
|
+
import { z } from "zod";
|
|
7
|
+
//#region src/usage.ts
|
|
8
|
+
/** The two actions that record a call the gate decided. */
|
|
9
|
+
const CALL_ACTIONS = [ControlPlaneAuditActions.callAllowed, ControlPlaneAuditActions.callDenied];
|
|
10
|
+
/** The resource type every attributed call row carries. */
|
|
11
|
+
const CONNECTION_RESOURCE = "controlplane_connection";
|
|
12
|
+
/**
|
|
13
|
+
* One `(scope, keyId)` a connection exercised, decoded from the aggregate's row.
|
|
14
|
+
*
|
|
15
|
+
* Internal: the wire shape is `ControlPlaneUsageView` in `http/responses.ts`, and `http/views.ts` projects this into it.
|
|
16
|
+
*/
|
|
17
|
+
const ControlPlaneUsageRow = z.object({
|
|
18
|
+
scope: z.string().describe("The scope exercised: what an allowed call's token carried, or what a refused call required — `metadata.required` from the gate, `metadata.scope` from a handler."),
|
|
19
|
+
keyId: z.string().nullable().describe("The registered key that signed the calls. Null for a row that recorded none."),
|
|
20
|
+
allowed: z.number().int().describe("How many `controlplane/call_allowed` events in the window."),
|
|
21
|
+
denied: z.number().int().describe("How many `controlplane/call_denied` events in the window."),
|
|
22
|
+
lastAllowedAt: SQLiteDate.nullable().describe("When the last allowed call landed. Null when none was allowed."),
|
|
23
|
+
lastAllowedMethod: z.string().nullable().describe("The HTTP method of the last allowed call, or null."),
|
|
24
|
+
lastAllowedPath: z.string().nullable().describe("The path of the last allowed call, or null."),
|
|
25
|
+
lastDeniedAt: SQLiteDate.nullable().describe("When the last refusal landed. Null when none was refused.")
|
|
26
|
+
}).describe("One scope and key a control-plane connection exercised in a window, with its counts.");
|
|
27
|
+
/** The oldest event the trail holds, decoded. */
|
|
28
|
+
const OldestEvent = z.object({ oldest: SQLiteDate.nullable().describe("The smallest `occurredAt` in the trail, or null when it is empty.") }).describe("How far back the trail reaches.");
|
|
29
|
+
/**
|
|
30
|
+
* The aggregate, as one Kysely statement — exported so a test can read its query plan.
|
|
31
|
+
*
|
|
32
|
+
* Three steps, in one statement:
|
|
33
|
+
*
|
|
34
|
+
* 1. **`calls`** — the connection's call rows in the window, with the scope, key, method and path lifted out of
|
|
35
|
+
* `metadata`. The scope is read from where each writer puts it: an allowed row carries the token's `scope`; a gate
|
|
36
|
+
* refusal names the scope it required as `required`, and a handler's refusal as `scope`, so a denied row reads
|
|
37
|
+
* `required` first. A row with no scope at all is nobody's usage and is dropped.
|
|
38
|
+
* 2. **`ranked`** — each row's recency within its `(scope, keyId, action)`, newest first, `id` breaking a tie. Rank 1
|
|
39
|
+
* of the allowed rows is the last allowed call, whose method and path the answer carries.
|
|
40
|
+
* 3. **The group** — counts and last instants per `(scope, keyId)`.
|
|
41
|
+
*/
|
|
42
|
+
function controlPlaneUsageStatement(db, filter) {
|
|
43
|
+
const allowed = ControlPlaneAuditActions.callAllowed;
|
|
44
|
+
const denied = ControlPlaneAuditActions.callDenied;
|
|
45
|
+
return db.with("calls", (q) => q.selectFrom("pithyAuditEvents").select((eb) => [
|
|
46
|
+
"id",
|
|
47
|
+
"action",
|
|
48
|
+
"occurredAt",
|
|
49
|
+
sql`case when ${eb.ref("action")} = ${denied}
|
|
50
|
+
then coalesce(json_extract(${eb.ref("metadata")}, '$.required'), json_extract(${eb.ref("metadata")}, '$.scope'))
|
|
51
|
+
else json_extract(${eb.ref("metadata")}, '$.scope') end`.as("scope"),
|
|
52
|
+
sql`json_extract(${eb.ref("metadata")}, '$.keyId')`.as("keyId"),
|
|
53
|
+
sql`json_extract(${eb.ref("metadata")}, '$.method')`.as("method"),
|
|
54
|
+
sql`json_extract(${eb.ref("metadata")}, '$.path')`.as("path")
|
|
55
|
+
]).where("action", "in", CALL_ACTIONS).where("resourceId", "=", filter.connectionId).where("occurredAt", ">=", SQLiteDate.encode(filter.since)).where("occurredAt", "<=", SQLiteDate.encode(filter.until)).where("resourceType", "=", CONNECTION_RESOURCE)).with("ranked", (q) => q.selectFrom("calls").selectAll().select(sql`row_number() over (
|
|
56
|
+
partition by ${sql.ref("scope")}, ${sql.ref("keyId")}, ${sql.ref("action")}
|
|
57
|
+
order by ${sql.ref("occurredAt")} desc, ${sql.ref("id")} desc)`.as("recency")).where("scope", "is not", null)).selectFrom("ranked").select((eb) => [
|
|
58
|
+
"scope",
|
|
59
|
+
"keyId",
|
|
60
|
+
sql`sum(case when ${eb.ref("action")} = ${allowed} then 1 else 0 end)`.as("allowed"),
|
|
61
|
+
sql`sum(case when ${eb.ref("action")} = ${denied} then 1 else 0 end)`.as("denied"),
|
|
62
|
+
sql`max(case when ${eb.ref("action")} = ${allowed} then ${eb.ref("occurredAt")} end)`.as("lastAllowedAt"),
|
|
63
|
+
sql`max(case when ${eb.ref("action")} = ${allowed} and ${eb.ref("recency")} = 1
|
|
64
|
+
then ${eb.ref("method")} end)`.as("lastAllowedMethod"),
|
|
65
|
+
sql`max(case when ${eb.ref("action")} = ${allowed} and ${eb.ref("recency")} = 1
|
|
66
|
+
then ${eb.ref("path")} end)`.as("lastAllowedPath"),
|
|
67
|
+
sql`max(case when ${eb.ref("action")} = ${denied} then ${eb.ref("occurredAt")} end)`.as("lastDeniedAt")
|
|
68
|
+
]).groupBy(["scope", "keyId"]).orderBy("scope").orderBy("keyId");
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Count one connection's calls by scope and key, over an inclusive window.
|
|
72
|
+
*
|
|
73
|
+
* `oldestEventAt` is the oldest event the trail holds at all, for any connection or none. Retention prunes the trail
|
|
74
|
+
* by time, never per connection, so this is how far back any connection's answer can reach: a window starting before
|
|
75
|
+
* it was not fully covered, and a client can say so rather than read a short count as a quiet connection. Read through
|
|
76
|
+
* `pithyAuditEventsOccurredAtIdx`, so it costs one index probe however large the trail is.
|
|
77
|
+
*/
|
|
78
|
+
async function controlPlaneUsage(db, filter) {
|
|
79
|
+
const rows = await controlPlaneUsageStatement(db, filter).execute();
|
|
80
|
+
const oldest = await db.selectFrom("pithyAuditEvents").select((eb) => eb.fn.min("occurredAt").as("oldest")).executeTakeFirst();
|
|
81
|
+
return {
|
|
82
|
+
usage: rows.map((row) => ControlPlaneUsageRow.parse(row)),
|
|
83
|
+
oldestEventAt: OldestEvent.parse({ oldest: oldest?.oldest ?? null }).oldest
|
|
84
|
+
};
|
|
85
|
+
}
|
|
86
|
+
//#endregion
|
|
87
|
+
export { ControlPlaneUsageRow, controlPlaneUsage, controlPlaneUsageStatement };
|
|
@@ -3,5 +3,5 @@
|
|
|
3
3
|
/** This package's npm name — the join key against a release feed. */
|
|
4
4
|
export declare const PACKAGE_NAME = "@pithy-sh/audit";
|
|
5
5
|
/** This package's version, stamped from its own package.json at generation time. */
|
|
6
|
-
export declare const PACKAGE_VERSION = "0.
|
|
6
|
+
export declare const PACKAGE_VERSION = "0.7.1";
|
|
7
7
|
//# sourceMappingURL=version.generated.d.ts.map
|
|
@@ -4,6 +4,6 @@
|
|
|
4
4
|
/** This package's npm name — the join key against a release feed. */
|
|
5
5
|
const PACKAGE_NAME = "@pithy-sh/audit";
|
|
6
6
|
/** This package's version, stamped from its own package.json at generation time. */
|
|
7
|
-
const PACKAGE_VERSION = "0.
|
|
7
|
+
const PACKAGE_VERSION = "0.7.1";
|
|
8
8
|
//#endregion
|
|
9
9
|
export { PACKAGE_NAME, PACKAGE_VERSION };
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
import { type EffectiveRetention } from "@pithy-sh/core/src/retention/policy";
|
|
4
|
+
import { type TerminalErrorConstructor, type WorkflowStepLike } from "@pithy-sh/core/src/workflow/faults";
|
|
5
|
+
import { type ChainPrunePage, type UnchainedPrunePage } from "../chain/prune";
|
|
6
|
+
import { AuditPruneParams } from "./specs";
|
|
7
|
+
/**
|
|
8
|
+
* **The retention prune's Workflow body**, run by a class the adopter's own Worker exports beside the
|
|
9
|
+
* `createEntrypoint` it already exports, because the prune reads the `retention` block that Worker resolved:
|
|
10
|
+
*
|
|
11
|
+
* // apps/api/src/index.ts
|
|
12
|
+
* import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
|
|
13
|
+
* import { NonRetryableError } from "cloudflare:workflows";
|
|
14
|
+
* import { runAuditPrune } from "@pithy-sh/audit/src/workflows/prune";
|
|
15
|
+
*
|
|
16
|
+
* export class AuditPruneWorkflow extends WorkflowEntrypoint<Record<string, unknown>> {
|
|
17
|
+
* override run(event: WorkflowEvent<unknown>, step: WorkflowStep) {
|
|
18
|
+
* return runAuditPrune(this.env, event, step, NonRetryableError);
|
|
19
|
+
* }
|
|
20
|
+
* }
|
|
21
|
+
*
|
|
22
|
+
* plus a `workflows` entry binding `AUDIT_PRUNE` to it and the daily cron.
|
|
23
|
+
*
|
|
24
|
+
* **A legal hold on a tenant's trail stops it.** Before every page of a chain the pass asks whether a hold stands on
|
|
25
|
+
* that tenant's trail, each ask its own step, so a hold placed while a pass runs stops it at its next page. The
|
|
26
|
+
* chain is left whole until the hold is released, and the next pass after that prunes it.
|
|
27
|
+
*/
|
|
28
|
+
/** What one pass reads and removes through. */
|
|
29
|
+
export interface AuditPruneRun {
|
|
30
|
+
/** Whether the policy prunes anything at all. Asked inside a step, so a replay serves the answer it got. */
|
|
31
|
+
prunes(): Promise<boolean>;
|
|
32
|
+
/** Whether a checkpoint bucket is bound. Without one nothing chained is pruned: no tombstone could be written. */
|
|
33
|
+
readonly checkpointed: boolean;
|
|
34
|
+
/** Every chain the trail holds. */
|
|
35
|
+
tenants(): Promise<(string | null)[]>;
|
|
36
|
+
/** Whether a legal hold stands on a tenant's trail. Throws when it cannot say. */
|
|
37
|
+
held(tenant: string | null): Promise<boolean>;
|
|
38
|
+
/** Prune one page of one chain. */
|
|
39
|
+
chainPage(tenant: string | null, afterSeq: number): Promise<ChainPrunePage>;
|
|
40
|
+
/** Prune one page of the rows that carry no chain. */
|
|
41
|
+
unchainedPage(afterId: number): Promise<UnchainedPrunePage>;
|
|
42
|
+
}
|
|
43
|
+
/** What one pass did. */
|
|
44
|
+
export interface AuditPruneOutcome {
|
|
45
|
+
/** How many chained events were removed, each run behind a tombstone. */
|
|
46
|
+
pruned: number;
|
|
47
|
+
/** How many runs were past their windows and left in place, because they did not verify. */
|
|
48
|
+
refused: number;
|
|
49
|
+
/** How many rows that carry no chain were removed. */
|
|
50
|
+
unchained: number;
|
|
51
|
+
/** How many chains a legal hold kept whole. */
|
|
52
|
+
held: number;
|
|
53
|
+
}
|
|
54
|
+
/** How many pages of one chain a pass takes, unless the trigger says otherwise. */
|
|
55
|
+
export declare const AUDIT_PRUNE_DEFAULT_PAGES = 20;
|
|
56
|
+
/**
|
|
57
|
+
* One pass: every chain, a page per step, each page behind its own hold check; then the unchained rows. A pass that
|
|
58
|
+
* dies part-way resumes after the step it finished, and a page repeated deletes nothing twice, because what it
|
|
59
|
+
* removed is gone and its tombstone is found rather than written again.
|
|
60
|
+
*/
|
|
61
|
+
export declare function pruneAuditTrail(run: AuditPruneRun, step: WorkflowStepLike, terminalError: TerminalErrorConstructor, params?: AuditPruneParams): Promise<AuditPruneOutcome>;
|
|
62
|
+
/** The pass over one env: its audit database, its checkpoint bucket, its holds, and the policy resolved at assembly. */
|
|
63
|
+
export declare function auditPruneRun(env: Record<string, unknown>, database: string, policy: () => EffectiveRetention | null, now?: () => Date): AuditPruneRun;
|
|
64
|
+
/** What a Workflow event hands a body. */
|
|
65
|
+
interface PruneEvent {
|
|
66
|
+
readonly payload?: unknown;
|
|
67
|
+
readonly workflowName?: string;
|
|
68
|
+
readonly instanceId?: string;
|
|
69
|
+
}
|
|
70
|
+
/** The prune pass, over this Worker's composition and the `retention` block it resolved. */
|
|
71
|
+
export declare function runAuditPrune(env: Record<string, unknown>, event: PruneEvent, step: WorkflowStepLike, terminalError: TerminalErrorConstructor): Promise<AuditPruneOutcome>;
|
|
72
|
+
export {};
|
|
73
|
+
//# sourceMappingURL=prune.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"prune.d.ts","sourceRoot":"","sources":["../../src/workflows/prune.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,KAAK,kBAAkB,EAAe,MAAM,qCAAqC,CAAC;AAC3F,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,EACtB,MAAM,oCAAoC,CAAC;AAG5C,OAAO,EAEL,KAAK,cAAc,EAInB,KAAK,kBAAkB,EACxB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,4GAA4G;IAC5G,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B,kHAAkH;IAClH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,mCAAmC;IACnC,OAAO,IAAI,OAAO,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;IACtC,kFAAkF;IAClF,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,mCAAmC;IACnC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5E,sDAAsD;IACtD,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC7D;AAED,yBAAyB;AACzB,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,mFAAmF;AACnF,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,gBAAgB,EACtB,aAAa,EAAE,wBAAwB,EACvC,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CAgC5B;AAED,wHAAwH;AACxH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,kBAAkB,GAAG,IAAI,EACvC,GAAG,GAAE,MAAM,IAAuB,GACjC,aAAa,CAiCf;AAED,0CAA0C;AAC1C,UAAU,UAAU;IAClB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,4FAA4F;AAC5F,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,gBAAgB,EACtB,aAAa,EAAE,wBAAwB,GACtC,OAAO,CAAC,iBAAiB,CAAC,CAe5B"}
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
import { AUDIT_CHECKPOINT_BINDING } from "../chain/checkpoint.js";
|
|
4
|
+
import { AuditPruneParams } from "./specs.js";
|
|
5
|
+
import { auditDatabase } from "../data/tables.js";
|
|
6
|
+
import { isAuditCapability } from "../capability.js";
|
|
7
|
+
import { chainTenants, pruneChainPage, pruneUnchainedPage } from "../chain/prune.js";
|
|
8
|
+
import { auditWorkflowRetry } from "./retryPolicy.js";
|
|
9
|
+
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
10
|
+
import { bindWorkflowContext, createWorkerLogger } from "@pithy-sh/core/src/logger/worker";
|
|
11
|
+
import { prunesAudit } from "@pithy-sh/core/src/retention/policy";
|
|
12
|
+
import { composedCapability } from "@pithy-sh/core/src/capability/composition";
|
|
13
|
+
import { composedRetention } from "@pithy-sh/core/src/retention/composed";
|
|
14
|
+
import { legalHolds } from "@pithy-sh/core/src/retention/holds";
|
|
15
|
+
import { classifiedSteps } from "@pithy-sh/core/src/workflow/faults";
|
|
16
|
+
//#region src/workflows/prune.ts
|
|
17
|
+
/** How many pages of one chain a pass takes, unless the trigger says otherwise. */
|
|
18
|
+
const AUDIT_PRUNE_DEFAULT_PAGES = 20;
|
|
19
|
+
/**
|
|
20
|
+
* One pass: every chain, a page per step, each page behind its own hold check; then the unchained rows. A pass that
|
|
21
|
+
* dies part-way resumes after the step it finished, and a page repeated deletes nothing twice, because what it
|
|
22
|
+
* removed is gone and its tombstone is found rather than written again.
|
|
23
|
+
*/
|
|
24
|
+
async function pruneAuditTrail(run, step, terminalError, params = {}) {
|
|
25
|
+
const outcome = {
|
|
26
|
+
pruned: 0,
|
|
27
|
+
refused: 0,
|
|
28
|
+
unchained: 0,
|
|
29
|
+
held: 0
|
|
30
|
+
};
|
|
31
|
+
const own = classifiedSteps(step, auditWorkflowRetry, terminalError);
|
|
32
|
+
if (!await own.do("policy", () => run.prunes())) return outcome;
|
|
33
|
+
const pages = params.pages ?? 20;
|
|
34
|
+
if (run.checkpointed) {
|
|
35
|
+
const tenants = await own.do("tenants", () => run.tenants());
|
|
36
|
+
for (const [index, tenant] of tenants.entries()) {
|
|
37
|
+
let afterSeq = 0;
|
|
38
|
+
for (let page = 1; page <= pages; page++) {
|
|
39
|
+
if (await own.do(`hold ${index + 1} ${page}`, () => run.held(tenant))) {
|
|
40
|
+
outcome.held++;
|
|
41
|
+
break;
|
|
42
|
+
}
|
|
43
|
+
const done = await own.do(`chain ${index + 1} ${page}`, () => run.chainPage(tenant, afterSeq));
|
|
44
|
+
outcome.pruned += done.pruned;
|
|
45
|
+
outcome.refused += done.refused;
|
|
46
|
+
if (done.next === null) break;
|
|
47
|
+
afterSeq = done.next;
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
let afterId = 0;
|
|
52
|
+
for (let page = 1; page <= pages; page++) {
|
|
53
|
+
const done = await own.do(`unchained ${page}`, () => run.unchainedPage(afterId));
|
|
54
|
+
outcome.unchained += done.deleted;
|
|
55
|
+
if (done.next === null) break;
|
|
56
|
+
afterId = done.next;
|
|
57
|
+
}
|
|
58
|
+
return outcome;
|
|
59
|
+
}
|
|
60
|
+
/** The pass over one env: its audit database, its checkpoint bucket, its holds, and the policy resolved at assembly. */
|
|
61
|
+
function auditPruneRun(env, database, policy, now = () => /* @__PURE__ */ new Date()) {
|
|
62
|
+
const binding = env[database];
|
|
63
|
+
if (typeof binding !== "object" || binding === null) throw new InternalError({
|
|
64
|
+
message: "The audit database is not bound, so the prune could not run.",
|
|
65
|
+
action: `Bind the ${database} D1 database to the Worker that runs the audit prune.`,
|
|
66
|
+
detail: `the audit prune found no ${database} binding on the env`
|
|
67
|
+
});
|
|
68
|
+
const db = auditDatabase(binding);
|
|
69
|
+
const found = env[AUDIT_CHECKPOINT_BINDING];
|
|
70
|
+
const bucket = typeof found === "object" && found !== null ? found : null;
|
|
71
|
+
const holds = legalHolds(env);
|
|
72
|
+
const held = (tenant) => holds.held("audit", tenant);
|
|
73
|
+
return {
|
|
74
|
+
prunes: async () => {
|
|
75
|
+
const retention = policy();
|
|
76
|
+
return retention !== null && prunesAudit(retention);
|
|
77
|
+
},
|
|
78
|
+
checkpointed: bucket !== null,
|
|
79
|
+
tenants: () => chainTenants(db),
|
|
80
|
+
held,
|
|
81
|
+
chainPage: (tenant, afterSeq) => {
|
|
82
|
+
const retention = policy();
|
|
83
|
+
if (!bucket || !retention) return Promise.resolve({
|
|
84
|
+
pruned: 0,
|
|
85
|
+
refused: 0,
|
|
86
|
+
next: null
|
|
87
|
+
});
|
|
88
|
+
return pruneChainPage(db, bucket, {
|
|
89
|
+
tenant,
|
|
90
|
+
retention,
|
|
91
|
+
now: now(),
|
|
92
|
+
afterSeq,
|
|
93
|
+
limit: 500
|
|
94
|
+
});
|
|
95
|
+
},
|
|
96
|
+
unchainedPage: (afterId) => {
|
|
97
|
+
const retention = policy();
|
|
98
|
+
if (!retention) return Promise.resolve({
|
|
99
|
+
deleted: 0,
|
|
100
|
+
next: null
|
|
101
|
+
});
|
|
102
|
+
return pruneUnchainedPage(db, {
|
|
103
|
+
retention,
|
|
104
|
+
now: now(),
|
|
105
|
+
afterId,
|
|
106
|
+
limit: 500,
|
|
107
|
+
held
|
|
108
|
+
});
|
|
109
|
+
}
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
/** The prune pass, over this Worker's composition and the `retention` block it resolved. */
|
|
113
|
+
async function runAuditPrune(env, event, step, terminalError) {
|
|
114
|
+
const params = AuditPruneParams.parse(event.payload ?? {});
|
|
115
|
+
const audit = composedCapability("audit", isAuditCapability);
|
|
116
|
+
const log = bindWorkflowContext(createWorkerLogger({ name: "audit" }), {
|
|
117
|
+
workflow: event.workflowName ?? "audit:prune",
|
|
118
|
+
instance: event.instanceId ?? "unknown",
|
|
119
|
+
env: typeof env.ENVIRONMENT === "string" ? env.ENVIRONMENT : "unknown"
|
|
120
|
+
});
|
|
121
|
+
const run = auditPruneRun(env, audit.auditDatabase, composedRetention);
|
|
122
|
+
if (!run.checkpointed) log.warn("audit prune leaves the chains whole", { reason: `no ${AUDIT_CHECKPOINT_BINDING} binding` });
|
|
123
|
+
const outcome = await pruneAuditTrail(run, step, terminalError, params);
|
|
124
|
+
log.info("audit prune finished", { ...outcome });
|
|
125
|
+
return outcome;
|
|
126
|
+
}
|
|
127
|
+
//#endregion
|
|
128
|
+
export { AUDIT_PRUNE_DEFAULT_PAGES, auditPruneRun, pruneAuditTrail, runAuditPrune };
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
import type { WorkflowRetryPolicy } from "@pithy-sh/core/src/workflow/faults";
|
|
4
|
+
/**
|
|
5
|
+
* The checkpoint's retry policy: **no audit code is retried.** Core already re-drives a transient D1 fault, and an
|
|
6
|
+
* R2 write that failed is re-attempted by the next hour's run, which checkpoints the head as it then stands. A run
|
|
7
|
+
* that fails costs one hour of checkpoint coverage, never a checkpoint, because nothing is ever overwritten.
|
|
8
|
+
*/
|
|
9
|
+
export declare const auditWorkflowRetry: WorkflowRetryPolicy;
|
|
10
|
+
//# sourceMappingURL=retryPolicy.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"retryPolicy.d.ts","sourceRoot":"","sources":["../../src/workflows/retryPolicy.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,mBAGhC,CAAC"}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
//#region src/workflows/retryPolicy.ts
|
|
4
|
+
/**
|
|
5
|
+
* The checkpoint's retry policy: **no audit code is retried.** Core already re-drives a transient D1 fault, and an
|
|
6
|
+
* R2 write that failed is re-attempted by the next hour's run, which checkpoints the head as it then stands. A run
|
|
7
|
+
* that fails costs one hour of checkpoint coverage, never a checkpoint, because nothing is ever overwritten.
|
|
8
|
+
*/
|
|
9
|
+
const auditWorkflowRetry = {
|
|
10
|
+
capability: "audit",
|
|
11
|
+
retryable: {}
|
|
12
|
+
};
|
|
13
|
+
//#endregion
|
|
14
|
+
export { auditWorkflowRetry };
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
import type { WorkflowRegistry } from "@pithy-sh/core/src/workflow/spec";
|
|
4
|
+
import { z } from "zod";
|
|
5
|
+
/**
|
|
6
|
+
* The one durable job audit owns: the checkpoint (#822).
|
|
7
|
+
*
|
|
8
|
+
* Declared once, here. `capability.ts` derives its Workflow binding from this map, the host resolver derives the
|
|
9
|
+
* checkpoint host's `workflows` array and its cron from it, and a caller triggers it by the `audit/checkpoint` key.
|
|
10
|
+
*
|
|
11
|
+
* `optional: true` because the Workflow lives in the prebuilt checkpoint host, which exists only once the project
|
|
12
|
+
* deploys it. Until then an app composing audit records every event and verifies every link; only the checkpoints
|
|
13
|
+
* are missing, and the verify read says so.
|
|
14
|
+
*/
|
|
15
|
+
/** The capability name — the first segment of the dispatch key and of every deployed resource name. */
|
|
16
|
+
export declare const AUDIT_CAPABILITY = "audit";
|
|
17
|
+
/** The checkpoint's parameters: none. A cron passes none, and every run checkpoints every chain whose head moved. */
|
|
18
|
+
export declare const AuditCheckpointParams: z.ZodObject<{}, z.core.$strip>;
|
|
19
|
+
export type AuditCheckpointParams = z.infer<typeof AuditCheckpointParams>;
|
|
20
|
+
/**
|
|
21
|
+
* Audit's durable jobs, keyed by job name.
|
|
22
|
+
*
|
|
23
|
+
* **Hourly, on the hour's 20th minute.** The checkpoint bounds how much of a chain's tail can be rewritten unseen:
|
|
24
|
+
* everything after the last checkpoint is held only by its own links. An hour is that window. A run writes one
|
|
25
|
+
* small object per chain whose head moved and nothing for one that did not, so a quiet hour costs a listing. Offset
|
|
26
|
+
* from the other kit hosts' hourly work at `:15`.
|
|
27
|
+
*/
|
|
28
|
+
export declare const auditWorkflows: {
|
|
29
|
+
readonly checkpoint: {
|
|
30
|
+
readonly binding: "AUDIT_CHECKPOINT";
|
|
31
|
+
readonly className: "AuditCheckpointWorkflow";
|
|
32
|
+
readonly params: z.ZodObject<{}, z.core.$strip>;
|
|
33
|
+
readonly schedule: "20 * * * *";
|
|
34
|
+
readonly optional: true;
|
|
35
|
+
};
|
|
36
|
+
};
|
|
37
|
+
/** The binding the retention prune runs on, in the adopter's own Worker. */
|
|
38
|
+
export declare const AUDIT_PRUNE_BINDING = "AUDIT_PRUNE";
|
|
39
|
+
/** The prune's parameters. Every field optional, because a cron passes none. */
|
|
40
|
+
export declare const AuditPruneParams: z.ZodObject<{
|
|
41
|
+
pages: z.ZodOptional<z.ZodNumber>;
|
|
42
|
+
}, z.core.$strip>;
|
|
43
|
+
export type AuditPruneParams = z.infer<typeof AuditPruneParams>;
|
|
44
|
+
/**
|
|
45
|
+
* The job audit runs in the adopter's own Worker: the retention prune. Not in the checkpoint host, because the prune
|
|
46
|
+
* reads the Worker's `retention` block, which exists only where `createEntrypoint` resolved it. No `className`: the
|
|
47
|
+
* class is the adopter's, five lines calling `runAuditPrune` in `./prune.ts`.
|
|
48
|
+
*
|
|
49
|
+
* **Daily, at 02:00 UTC**, the trigger auth's and organization's purge passes share, so a Worker composing all three
|
|
50
|
+
* spends one cron. Windows are counted in days, so a daily pass prunes nothing later than an hourly one would.
|
|
51
|
+
*
|
|
52
|
+
* `optional: true`, so a Worker composing audit boots before the adopter has bound it. Until then nothing is pruned
|
|
53
|
+
* and the trail is kept, which is what a Worker with no `retention` block does anyway.
|
|
54
|
+
*/
|
|
55
|
+
export declare const auditAppWorkflows: {
|
|
56
|
+
readonly prune: {
|
|
57
|
+
readonly binding: "AUDIT_PRUNE";
|
|
58
|
+
readonly params: z.ZodObject<{
|
|
59
|
+
pages: z.ZodOptional<z.ZodNumber>;
|
|
60
|
+
}, z.core.$strip>;
|
|
61
|
+
readonly schedule: "0 2 * * *";
|
|
62
|
+
readonly optional: true;
|
|
63
|
+
};
|
|
64
|
+
};
|
|
65
|
+
/**
|
|
66
|
+
* The checkpoint host's jobs as a dispatch registry, keyed `audit/<job>`, with core's key format. The prune is not
|
|
67
|
+
* in it: the host resolver derives the host's Workflows from this registry, and the prune is hosted elsewhere.
|
|
68
|
+
*/
|
|
69
|
+
export declare const auditWorkflowRegistry: WorkflowRegistry;
|
|
70
|
+
//# sourceMappingURL=specs.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"specs.d.ts","sourceRoot":"","sources":["../../src/workflows/specs.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAmB,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;GASG;AAEH,uGAAuG;AACvG,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC,qHAAqH;AACrH,eAAO,MAAM,qBAAqB,gCAEkF,CAAC;AACrH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;iBAEvB,OAAO,EAAE,kBAAkB;iBAC3B,SAAS,EAAE,yBAAyB;iBACpC,MAAM;iBACN,QAAQ,EAAE,YAAY;iBACtB,QAAQ;;CAEwB,CAAC;AAErC,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AAEjD,gFAAgF;AAChF,eAAO,MAAM,gBAAgB;;iBAUoD,CAAC;AAClF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB;;iBAE1B,OAAO;iBACP,MAAM;;;iBACN,QAAQ,EAAE,WAAW;iBACrB,QAAQ;;CAEwB,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,gBAKnC,CAAC"}
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
import { workflowKey } from "@pithy-sh/core/src/workflow/naming";
|
|
5
|
+
//#region src/workflows/specs.ts
|
|
6
|
+
/**
|
|
7
|
+
* The one durable job audit owns: the checkpoint (#822).
|
|
8
|
+
*
|
|
9
|
+
* Declared once, here. `capability.ts` derives its Workflow binding from this map, the host resolver derives the
|
|
10
|
+
* checkpoint host's `workflows` array and its cron from it, and a caller triggers it by the `audit/checkpoint` key.
|
|
11
|
+
*
|
|
12
|
+
* `optional: true` because the Workflow lives in the prebuilt checkpoint host, which exists only once the project
|
|
13
|
+
* deploys it. Until then an app composing audit records every event and verifies every link; only the checkpoints
|
|
14
|
+
* are missing, and the verify read says so.
|
|
15
|
+
*/
|
|
16
|
+
/** The capability name — the first segment of the dispatch key and of every deployed resource name. */
|
|
17
|
+
const AUDIT_CAPABILITY = "audit";
|
|
18
|
+
/** The checkpoint's parameters: none. A cron passes none, and every run checkpoints every chain whose head moved. */
|
|
19
|
+
const AuditCheckpointParams = z.object({}).describe("One checkpoint run. No parameters: a cron passes none, and a run covers every chain whose head moved.");
|
|
20
|
+
/**
|
|
21
|
+
* Audit's durable jobs, keyed by job name.
|
|
22
|
+
*
|
|
23
|
+
* **Hourly, on the hour's 20th minute.** The checkpoint bounds how much of a chain's tail can be rewritten unseen:
|
|
24
|
+
* everything after the last checkpoint is held only by its own links. An hour is that window. A run writes one
|
|
25
|
+
* small object per chain whose head moved and nothing for one that did not, so a quiet hour costs a listing. Offset
|
|
26
|
+
* from the other kit hosts' hourly work at `:15`.
|
|
27
|
+
*/
|
|
28
|
+
const auditWorkflows = { checkpoint: {
|
|
29
|
+
binding: "AUDIT_CHECKPOINT",
|
|
30
|
+
className: "AuditCheckpointWorkflow",
|
|
31
|
+
params: AuditCheckpointParams,
|
|
32
|
+
schedule: "20 * * * *",
|
|
33
|
+
optional: true
|
|
34
|
+
} };
|
|
35
|
+
/** The binding the retention prune runs on, in the adopter's own Worker. */
|
|
36
|
+
const AUDIT_PRUNE_BINDING = "AUDIT_PRUNE";
|
|
37
|
+
/** The prune's parameters. Every field optional, because a cron passes none. */
|
|
38
|
+
const AuditPruneParams = z.object({ pages: z.number().int().min(1).max(100).optional().describe("How many pages of 500 rows one chain is pruned in this pass, at most. Defaults to 20.") }).describe("One retention prune pass over every chain. A cron passes no field.");
|
|
39
|
+
/**
|
|
40
|
+
* The job audit runs in the adopter's own Worker: the retention prune. Not in the checkpoint host, because the prune
|
|
41
|
+
* reads the Worker's `retention` block, which exists only where `createEntrypoint` resolved it. No `className`: the
|
|
42
|
+
* class is the adopter's, five lines calling `runAuditPrune` in `./prune.ts`.
|
|
43
|
+
*
|
|
44
|
+
* **Daily, at 02:00 UTC**, the trigger auth's and organization's purge passes share, so a Worker composing all three
|
|
45
|
+
* spends one cron. Windows are counted in days, so a daily pass prunes nothing later than an hourly one would.
|
|
46
|
+
*
|
|
47
|
+
* `optional: true`, so a Worker composing audit boots before the adopter has bound it. Until then nothing is pruned
|
|
48
|
+
* and the trail is kept, which is what a Worker with no `retention` block does anyway.
|
|
49
|
+
*/
|
|
50
|
+
const auditAppWorkflows = { prune: {
|
|
51
|
+
binding: AUDIT_PRUNE_BINDING,
|
|
52
|
+
params: AuditPruneParams,
|
|
53
|
+
schedule: "0 2 * * *",
|
|
54
|
+
optional: true
|
|
55
|
+
} };
|
|
56
|
+
/**
|
|
57
|
+
* The checkpoint host's jobs as a dispatch registry, keyed `audit/<job>`, with core's key format. The prune is not
|
|
58
|
+
* in it: the host resolver derives the host's Workflows from this registry, and the prune is hosted elsewhere.
|
|
59
|
+
*/
|
|
60
|
+
const auditWorkflowRegistry = Object.fromEntries(Object.entries(auditWorkflows).map(([job, spec]) => {
|
|
61
|
+
const key = workflowKey(AUDIT_CAPABILITY, job);
|
|
62
|
+
return [key, {
|
|
63
|
+
key,
|
|
64
|
+
capability: AUDIT_CAPABILITY,
|
|
65
|
+
job,
|
|
66
|
+
spec
|
|
67
|
+
}];
|
|
68
|
+
}));
|
|
69
|
+
//#endregion
|
|
70
|
+
export { AUDIT_CAPABILITY, AUDIT_PRUNE_BINDING, AuditCheckpointParams, AuditPruneParams, auditAppWorkflows, auditWorkflowRegistry, auditWorkflows };
|