@pithy-sh/audit 0.5.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.
Files changed (183) hide show
  1. package/README.md +93 -0
  2. package/dist/accessHistory.d.ts +315 -0
  3. package/dist/accessHistory.d.ts.map +1 -0
  4. package/dist/accessHistory.js +299 -0
  5. package/dist/actions.d.ts +15 -1
  6. package/dist/actions.d.ts.map +1 -1
  7. package/dist/actions.js +16 -2
  8. package/dist/capability.d.ts +14 -0
  9. package/dist/capability.d.ts.map +1 -1
  10. package/dist/capability.js +124 -12
  11. package/dist/chain/append.d.ts +43 -0
  12. package/dist/chain/append.d.ts.map +1 -0
  13. package/dist/chain/append.js +110 -0
  14. package/dist/chain/checkpoint.d.ts +70 -0
  15. package/dist/chain/checkpoint.d.ts.map +1 -0
  16. package/dist/chain/checkpoint.js +133 -0
  17. package/dist/chain/lockCheck.d.ts +15 -0
  18. package/dist/chain/lockCheck.d.ts.map +1 -0
  19. package/dist/chain/lockCheck.js +75 -0
  20. package/dist/chain/prune.d.ts +84 -0
  21. package/dist/chain/prune.d.ts.map +1 -0
  22. package/dist/chain/prune.js +231 -0
  23. package/dist/chain/rows.d.ts +74 -0
  24. package/dist/chain/rows.d.ts.map +1 -0
  25. package/dist/chain/rows.js +133 -0
  26. package/dist/chain/tombstone.d.ts +21 -0
  27. package/dist/chain/tombstone.d.ts.map +1 -0
  28. package/dist/chain/tombstone.js +98 -0
  29. package/dist/chain/verify.d.ts +63 -0
  30. package/dist/chain/verify.d.ts.map +1 -0
  31. package/dist/chain/verify.js +220 -0
  32. package/dist/citations.d.ts +17 -0
  33. package/dist/citations.d.ts.map +1 -0
  34. package/dist/citations.js +48 -0
  35. package/dist/cli/emitFromCLI.d.ts +5 -0
  36. package/dist/cli/emitFromCLI.d.ts.map +1 -1
  37. package/dist/cli/emitFromCLI.js +5 -0
  38. package/dist/data/auditEvent.d.ts +4 -0
  39. package/dist/data/auditEvent.d.ts.map +1 -1
  40. package/dist/data/auditEvent.js +7 -3
  41. package/dist/data/sinkState.d.ts +23 -0
  42. package/dist/data/sinkState.d.ts.map +1 -0
  43. package/dist/data/sinkState.js +25 -0
  44. package/dist/data/tables.d.ts +14 -1
  45. package/dist/data/tables.d.ts.map +1 -1
  46. package/dist/data/tables.js +5 -1
  47. package/dist/http/guards.d.ts +39 -6
  48. package/dist/http/guards.d.ts.map +1 -1
  49. package/dist/http/guards.js +101 -17
  50. package/dist/http/responses.d.ts +503 -0
  51. package/dist/http/responses.d.ts.map +1 -1
  52. package/dist/http/responses.js +157 -5
  53. package/dist/http/routes.d.ts +25 -3
  54. package/dist/http/routes.d.ts.map +1 -1
  55. package/dist/http/routes.js +321 -15
  56. package/dist/http/schemas.d.ts +67 -0
  57. package/dist/http/schemas.d.ts.map +1 -1
  58. package/dist/http/schemas.js +88 -4
  59. package/dist/http/views.d.ts +25 -1
  60. package/dist/http/views.d.ts.map +1 -1
  61. package/dist/http/views.js +107 -2
  62. package/dist/migrations/0003_call_index.d.ts +21 -0
  63. package/dist/migrations/0003_call_index.d.ts.map +1 -0
  64. package/dist/migrations/0003_call_index.js +33 -0
  65. package/dist/migrations/0004_request_index.d.ts +16 -0
  66. package/dist/migrations/0004_request_index.d.ts.map +1 -0
  67. package/dist/migrations/0004_request_index.js +24 -0
  68. package/dist/migrations/0005_chain.d.ts +24 -0
  69. package/dist/migrations/0005_chain.d.ts.map +1 -0
  70. package/dist/migrations/0005_chain.js +43 -0
  71. package/dist/migrations/0006_sinks.d.ts +11 -0
  72. package/dist/migrations/0006_sinks.d.ts.map +1 -0
  73. package/dist/migrations/0006_sinks.js +20 -0
  74. package/dist/provision/resolveAuditConfig.d.ts +31 -0
  75. package/dist/provision/resolveAuditConfig.d.ts.map +1 -0
  76. package/dist/provision/resolveAuditConfig.js +43 -0
  77. package/dist/purge/contribution.d.ts +21 -0
  78. package/dist/purge/contribution.d.ts.map +1 -0
  79. package/dist/purge/contribution.js +41 -0
  80. package/dist/reach.d.ts +250 -0
  81. package/dist/reach.d.ts.map +1 -0
  82. package/dist/reach.js +244 -0
  83. package/dist/recorder.d.ts +11 -0
  84. package/dist/recorder.d.ts.map +1 -1
  85. package/dist/recorder.js +23 -5
  86. package/dist/routePattern.d.ts +60 -0
  87. package/dist/routePattern.d.ts.map +1 -0
  88. package/dist/routePattern.js +130 -0
  89. package/dist/seeds/example.d.ts.map +1 -1
  90. package/dist/seeds/example.js +23 -6
  91. package/dist/ship/consumer.d.ts +45 -0
  92. package/dist/ship/consumer.d.ts.map +1 -0
  93. package/dist/ship/consumer.js +141 -0
  94. package/dist/ship/event.d.ts +59 -0
  95. package/dist/ship/event.d.ts.map +1 -0
  96. package/dist/ship/event.js +77 -0
  97. package/dist/ship/health.d.ts +33 -0
  98. package/dist/ship/health.d.ts.map +1 -0
  99. package/dist/ship/health.js +80 -0
  100. package/dist/ship/profiles.d.ts +34 -0
  101. package/dist/ship/profiles.d.ts.map +1 -0
  102. package/dist/ship/profiles.js +62 -0
  103. package/dist/ship/queue.d.ts +57 -0
  104. package/dist/ship/queue.d.ts.map +1 -0
  105. package/dist/ship/queue.js +70 -0
  106. package/dist/ship/secrets.d.ts +7 -0
  107. package/dist/ship/secrets.d.ts.map +1 -0
  108. package/dist/ship/secrets.js +40 -0
  109. package/dist/ship/shipper.d.ts +15 -0
  110. package/dist/ship/shipper.d.ts.map +1 -0
  111. package/dist/ship/shipper.js +27 -0
  112. package/dist/ship/sinks.d.ts +54 -0
  113. package/dist/ship/sinks.d.ts.map +1 -0
  114. package/dist/ship/sinks.js +45 -0
  115. package/dist/ship/state.d.ts +27 -0
  116. package/dist/ship/state.d.ts.map +1 -0
  117. package/dist/ship/state.js +29 -0
  118. package/dist/usage.d.ts +159 -0
  119. package/dist/usage.d.ts.map +1 -0
  120. package/dist/usage.js +87 -0
  121. package/dist/version.generated.d.ts +1 -1
  122. package/dist/version.generated.js +1 -1
  123. package/dist/workflows/prune.d.ts +73 -0
  124. package/dist/workflows/prune.d.ts.map +1 -0
  125. package/dist/workflows/prune.js +128 -0
  126. package/dist/workflows/retryPolicy.d.ts +10 -0
  127. package/dist/workflows/retryPolicy.d.ts.map +1 -0
  128. package/dist/workflows/retryPolicy.js +14 -0
  129. package/dist/workflows/specs.d.ts +70 -0
  130. package/dist/workflows/specs.d.ts.map +1 -0
  131. package/dist/workflows/specs.js +70 -0
  132. package/dist/workflows/worker.d.ts +32 -0
  133. package/dist/workflows/worker.d.ts.map +1 -0
  134. package/dist/workflows/worker.js +41 -0
  135. package/package.json +5 -2
  136. package/pithy.manifest.json +36 -4
  137. package/src/accessHistory.ts +360 -0
  138. package/src/actions.ts +15 -1
  139. package/src/capability.ts +154 -12
  140. package/src/chain/append.ts +161 -0
  141. package/src/chain/checkpoint.ts +172 -0
  142. package/src/chain/lockCheck.ts +72 -0
  143. package/src/chain/prune.ts +340 -0
  144. package/src/chain/rows.ts +211 -0
  145. package/src/chain/tombstone.ts +104 -0
  146. package/src/chain/verify.ts +366 -0
  147. package/src/citations.ts +62 -0
  148. package/src/cli/emitFromCLI.ts +5 -0
  149. package/src/cloudflare-test.d.ts +1 -0
  150. package/src/data/auditEvent.ts +31 -1
  151. package/src/data/sinkState.ts +41 -0
  152. package/src/data/tables.ts +7 -1
  153. package/src/http/guards.ts +90 -6
  154. package/src/http/responses.ts +318 -3
  155. package/src/http/routes.ts +379 -7
  156. package/src/http/schemas.ts +158 -2
  157. package/src/http/views.ts +123 -1
  158. package/src/migrations/0003_call_index.ts +35 -0
  159. package/src/migrations/0004_request_index.ts +26 -0
  160. package/src/migrations/0005_chain.ts +56 -0
  161. package/src/migrations/0006_sinks.ts +28 -0
  162. package/src/provision/resolveAuditConfig.ts +60 -0
  163. package/src/purge/contribution.ts +39 -0
  164. package/src/reach.ts +454 -0
  165. package/src/recorder.ts +64 -42
  166. package/src/routePattern.ts +141 -0
  167. package/src/seeds/example.ts +13 -0
  168. package/src/ship/consumer.ts +169 -0
  169. package/src/ship/event.ts +86 -0
  170. package/src/ship/health.ts +92 -0
  171. package/src/ship/profiles.ts +99 -0
  172. package/src/ship/queue.ts +108 -0
  173. package/src/ship/secrets.ts +42 -0
  174. package/src/ship/shipper.ts +32 -0
  175. package/src/ship/sinks.ts +82 -0
  176. package/src/ship/state.ts +61 -0
  177. package/src/usage.ts +176 -0
  178. package/src/version.generated.ts +1 -1
  179. package/src/workflows/prune.ts +196 -0
  180. package/src/workflows/retryPolicy.ts +14 -0
  181. package/src/workflows/specs.ts +92 -0
  182. package/src/workflows/worker.ts +65 -0
  183. package/src/workflows/wrangler.jsonc +40 -0
package/src/reach.ts ADDED
@@ -0,0 +1,454 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+
4
+ import { ControlPlaneAuditActions } from "@pithy-sh/core/src/controlPlane/audit/actions";
5
+ import { SQLiteBoolean, SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
6
+ import { sql } from "kysely";
7
+ import { z } from "zod";
8
+ import type { AuditDatabase } from "./data/tables";
9
+ import { ReachPattern, routeParams, routeSubject } from "./routePattern";
10
+
11
+ /**
12
+ * What one control-plane credential reached — `#828`.
13
+ *
14
+ * "This key leaked. What did it touch?" Every admitted call writes `controlplane/call_allowed` against the connection
15
+ * as `resourceId`, with the scope, the key, the method and the path as called in `metadata`. The listing carries no
16
+ * metadata, so answering from it means one forensic read per event, behind the scope that also discloses the client
17
+ * IP. This reads the same rows in SQL and returns one row per tenant, action, method, route and outcome.
18
+ *
19
+ * **A refusal is the handler's, paired with the gate's row.** The gate's own refusal (`auditDenial`) is of a call that
20
+ * never verified, so it names no connection and no actor and is no credential's reach. What a verified credential was
21
+ * refused is a handler's refusal past the gate (`auditHandlerDenial`): a `controlplane/call_denied` row against the
22
+ * connection, written in the same request as the gate's `call_allowed` for the same call. The two are one call, and
23
+ * it was refused, so the `call_allowed` row of a request that also holds a refusal for the same actor, method and path
24
+ * is dropped, and the refusal reads its scope and key from that row when its own names none — as rows written before
25
+ * the guard recorded them do not. `scope` is the scope the credential carried, never `required`, which on a handler's
26
+ * refusal is the gate's requirement the call met; what it lacked is only in the log. A call with no request id, as off
27
+ * Cloudflare, cannot be paired: its refusal stands on the scope and key its own row names, and its gate row stays an
28
+ * admitted call.
29
+ *
30
+ * **Grouped by the declared route, expandable to the subjects.** The path is recorded as called, so
31
+ * `/admin/users/u_8f2` names a user. Each call is matched back to the admin route the manifest declares
32
+ * (`routePattern.ts`), most specific first; a path no route matches is its own row, marked unmatched.
33
+ * {@link controlPlaneReachSubjects} expands one route into the paths it was called with and the subject ids they
34
+ * name — the *whose data* list a breach scope is drawn from. The subject is the route's last id parameter
35
+ * ({@link routeSubject}), so a ledger read by user and currency names the user, and a group's subject count is of
36
+ * distinct subjects, not distinct paths.
37
+ *
38
+ * **The tenant is the handler's, joined by request id.** The gate writes its row before the handler runs, so before
39
+ * any tenant is resolved, and that row's own `tenant` is null. The handler's events in the same request carry it, and
40
+ * share the call's `requestId` (`cf-ray`) and `actorId`. So a call reached every tenant its handler recorded, and a
41
+ * call whose handler recorded none — or that carries no request id, as off Cloudflare — reached no named tenant. Only
42
+ * `control-plane` events by the same actor count, so a stray event sharing a request id cannot attribute a call.
43
+ *
44
+ * **One statement, never a page walk.** The calls are found through `pithyAuditEventsCallIdx` and the handler events
45
+ * through `pithyAuditEventsRequestIdx`. The routes go in as one JSON parameter, so a manifest of any size is one bound
46
+ * value rather than four per route against D1's limit. The statement groups by called path, and the Worker folds the
47
+ * paths of each group, because a subject is read from a path by splitting it on `/`, which SQLite cannot do without a
48
+ * recursive CTE per row.
49
+ *
50
+ * **Nothing personal leaves this function.** It reads the scope, the key id, the method and the path out of
51
+ * `metadata`, and no other key, and never the IP or the user-agent. Of the handler's events it reads the tenant.
52
+ */
53
+
54
+ /** What to read: one connection over an inclusive window, optionally one key and one route. */
55
+ export interface ControlPlaneReachFilter {
56
+ /** The connection whose calls are read — the rows' `resourceId`. */
57
+ connectionId: string;
58
+ /** Inclusive lower bound on `occurredAt`. */
59
+ since: Date;
60
+ /** Inclusive upper bound on `occurredAt`. */
61
+ until: Date;
62
+ /** Narrow to the calls one registered key signed — `metadata.keyId`. */
63
+ keyId?: string;
64
+ /** Narrow to one route — a declared pattern, or the called path of an unmatched row. */
65
+ route?: string;
66
+ }
67
+
68
+ /** The two actions that record a verified call: the gate's admission and a handler's refusal past it. */
69
+ const CALL_ACTIONS = [ControlPlaneAuditActions.callAllowed, ControlPlaneAuditActions.callDenied];
70
+
71
+ /** The resource type every attributed call row carries. */
72
+ const CONNECTION_RESOURCE = "controlplane_connection";
73
+
74
+ /** The routes, as the statement's one JSON parameter. */
75
+ const ReachPatterns = sqliteJson(z.array(ReachPattern).describe("Every declared admin route, ranked."));
76
+
77
+ /** The columns every grouping carries, in the order the answer is sorted by. */
78
+ const GROUP = ["tenant", "route", "action", "method", "matched", "outcome", "scope"] as const;
79
+
80
+ /** The order the statement sorts in: the group, with the path after the route. */
81
+ const ORDER = [...GROUP.slice(0, 2), "path" as const, ...GROUP.slice(2)];
82
+
83
+ /**
84
+ * The statement, as one Kysely query — exported so a test can read its query plan.
85
+ *
86
+ * 1. **`routes`** — the declared routes, unpacked from the one JSON parameter.
87
+ * 2. **`rows`** — the connection's call rows in the window, with the scope, key, method and path lifted out of
88
+ * `metadata`. A row with no path is no call to a route and is dropped.
89
+ * 3. **`calls`** — one row per call: a refusal takes its scope and key from the gate's row in the same request when its
90
+ * own names none, and that gate row is dropped, since the call it admitted was refused. The key filter applies here,
91
+ * after the refusal has its key.
92
+ * 4. **`matches`** — each call against every route of its method, by glob and slash count, ranked so the most specific
93
+ * match is `pick = 1`.
94
+ * 5. **`tenants`** — the distinct tenants each call's handler recorded, by request id and actor, from `control-plane`
95
+ * events only.
96
+ * 6. **`reached`** — each call once per tenant it reached, with its route, or its own path when unmatched.
97
+ * 7. **The group** — counts and instants per tenant, route, action, method, outcome and path.
98
+ */
99
+ export function controlPlaneReachStatement(
100
+ db: AuditDatabase,
101
+ filter: ControlPlaneReachFilter,
102
+ patterns: readonly ReachPattern[],
103
+ ) {
104
+ const allowed = ControlPlaneAuditActions.callAllowed;
105
+ const denied = ControlPlaneAuditActions.callDenied;
106
+ const encoded = ReachPatterns.encode([...patterns]);
107
+ const field = (name: string) => sql`json_extract(${sql.ref("value")}, ${`$.${name}`})`;
108
+
109
+ let reached = db
110
+ .with("routes", (q) =>
111
+ q
112
+ .selectFrom(sql`json_each(${encoded})`.as("each"))
113
+ .select([
114
+ sql<string>`${field("method")}`.as("method"),
115
+ sql<string>`${field("pattern")}`.as("pattern"),
116
+ sql<string>`${field("glob")}`.as("glob"),
117
+ sql<number | null>`${field("slashes")}`.as("slashes"),
118
+ sql<number>`${field("params")}`.as("params"),
119
+ sql<number>`${field("rank")}`.as("rank"),
120
+ ]),
121
+ )
122
+ .with("rows", (q) =>
123
+ q
124
+ .selectFrom("pithyAuditEvents")
125
+ .select((eb) => [
126
+ "id",
127
+ "action",
128
+ "outcome",
129
+ "occurredAt",
130
+ "requestId",
131
+ "actorId",
132
+ "tenant",
133
+ sql<string | null>`json_extract(${eb.ref("metadata")}, '$.scope')`.as("scope"),
134
+ sql<string | null>`json_extract(${eb.ref("metadata")}, '$.keyId')`.as("keyId"),
135
+ sql<string>`json_extract(${eb.ref("metadata")}, '$.method')`.as("method"),
136
+ sql<string>`json_extract(${eb.ref("metadata")}, '$.path')`.as("path"),
137
+ ])
138
+ // In `pithyAuditEventsCallIdx`'s column order: the actions, the connection, then the window.
139
+ .where("action", "in", CALL_ACTIONS)
140
+ .where("resourceId", "=", filter.connectionId)
141
+ .where("occurredAt", ">=", SQLiteDate.encode(filter.since))
142
+ .where("occurredAt", "<=", SQLiteDate.encode(filter.until))
143
+ .where("resourceType", "=", CONNECTION_RESOURCE)
144
+ .where(sql`json_extract(${sql.ref("metadata")}, '$.path')`, "is not", null),
145
+ )
146
+ .with("calls", (q) => {
147
+ const keyId = sql<string | null>`coalesce(${sql.ref("call.keyId")}, ${sql.ref("gate.keyId")})`;
148
+ let calls = q
149
+ .selectFrom("rows as call")
150
+ // A refusal's own gate row: the same request, actor, method and path. A null request id pairs with nothing.
151
+ .leftJoin("rows as gate", (join) =>
152
+ join
153
+ .on("call.action", "=", denied)
154
+ .on("gate.action", "=", allowed)
155
+ .onRef("gate.requestId", "=", "call.requestId")
156
+ .onRef("gate.actorId", "=", "call.actorId")
157
+ .onRef("gate.method", "=", "call.method")
158
+ .onRef("gate.path", "=", "call.path"),
159
+ )
160
+ .where((eb) =>
161
+ eb.or([
162
+ eb("call.action", "=", denied),
163
+ eb.not(
164
+ eb.exists(
165
+ eb
166
+ .selectFrom("rows as refusal")
167
+ .select(sql<number>`1`.as("one"))
168
+ .where("refusal.action", "=", denied)
169
+ .whereRef("refusal.requestId", "=", "call.requestId")
170
+ .whereRef("refusal.actorId", "=", "call.actorId")
171
+ .whereRef("refusal.method", "=", "call.method")
172
+ .whereRef("refusal.path", "=", "call.path"),
173
+ ),
174
+ ),
175
+ ]),
176
+ )
177
+ .select([
178
+ "call.id as id",
179
+ "call.action as action",
180
+ "call.outcome as outcome",
181
+ "call.occurredAt as occurredAt",
182
+ "call.requestId as requestId",
183
+ "call.actorId as actorId",
184
+ "call.tenant as tenant",
185
+ sql<string | null>`coalesce(${sql.ref("call.scope")}, ${sql.ref("gate.scope")})`.as("scope"),
186
+ "call.method as method",
187
+ "call.path as path",
188
+ ]);
189
+ if (filter.keyId !== undefined) calls = calls.where(keyId, "=", filter.keyId);
190
+ return calls;
191
+ })
192
+ .with("matches", (q) =>
193
+ q
194
+ .selectFrom("calls")
195
+ .innerJoin("routes", (join) =>
196
+ join
197
+ .onRef("routes.method", "=", "calls.method")
198
+ .on(sql<boolean>`${sql.ref("calls.path")} glob ${sql.ref("routes.glob")}`)
199
+ .on((eb) =>
200
+ eb.or([
201
+ eb("routes.slashes", "is", null),
202
+ eb(
203
+ "routes.slashes",
204
+ "=",
205
+ sql<number>`length(${sql.ref("calls.path")}) - length(replace(${sql.ref("calls.path")}, '/', ''))`,
206
+ ),
207
+ ]),
208
+ ),
209
+ )
210
+ .select([
211
+ "calls.id as callId",
212
+ "routes.pattern as pattern",
213
+ "routes.params as params",
214
+ sql<number>`row_number() over (partition by ${sql.ref("calls.id")} order by ${sql.ref("routes.rank")})`.as(
215
+ "pick",
216
+ ),
217
+ ]),
218
+ )
219
+ .with("tenants", (q) =>
220
+ q
221
+ .selectFrom("calls")
222
+ .innerJoin("pithyAuditEvents as handled", (join) =>
223
+ join
224
+ .onRef("handled.requestId", "=", "calls.requestId")
225
+ .onRef("handled.actorId", "=", "calls.actorId")
226
+ .onRef("handled.id", "!=", "calls.id")
227
+ .on("handled.actorType", "=", "control-plane")
228
+ .on("handled.tenant", "is not", null),
229
+ )
230
+ .select(["calls.id as callId", "handled.tenant as tenant"])
231
+ .distinct(),
232
+ )
233
+ .with("reached", (q) =>
234
+ q
235
+ .selectFrom("calls")
236
+ .leftJoin("matches", (join) => join.onRef("matches.callId", "=", "calls.id").on("matches.pick", "=", 1))
237
+ .leftJoin("tenants", "tenants.callId", "calls.id")
238
+ .select([
239
+ sql<string | null>`coalesce(${sql.ref("tenants.tenant")}, ${sql.ref("calls.tenant")})`.as("tenant"),
240
+ sql<string>`coalesce(${sql.ref("matches.pattern")}, ${sql.ref("calls.path")})`.as("route"),
241
+ sql<number>`${sql.ref("matches.pattern")} is not null`.as("matched"),
242
+ sql<number>`coalesce(${sql.ref("matches.params")}, 0)`.as("params"),
243
+ "calls.action as action",
244
+ "calls.method as method",
245
+ "calls.outcome as outcome",
246
+ "calls.scope as scope",
247
+ "calls.path as path",
248
+ "calls.occurredAt as occurredAt",
249
+ ]),
250
+ )
251
+ .selectFrom("reached")
252
+ .select((eb) => [
253
+ ...GROUP,
254
+ "path",
255
+ sql<number>`count(*)`.as("count"),
256
+ sql<number>`max(${eb.ref("params")})`.as("params"),
257
+ eb.fn.min("occurredAt").as("firstAt"),
258
+ eb.fn.max("occurredAt").as("lastAt"),
259
+ ]);
260
+
261
+ if (filter.route !== undefined) reached = reached.where("route", "=", filter.route);
262
+ let ordered = reached.groupBy([...GROUP, "path"]);
263
+ for (const column of ORDER) ordered = ordered.orderBy(column);
264
+ return ordered;
265
+ }
266
+
267
+ /** One grouped row as the statement returns it, decoded. Internal: the two readers below project it. */
268
+ const ReachStatementRow = z
269
+ .object({
270
+ tenant: z.string().nullable().describe("The tenant the calls reached, or null when their handler named none."),
271
+ route: z.string().describe("The declared route, or the called path when no route matched."),
272
+ action: z.string().describe("`controlplane/call_allowed` or `controlplane/call_denied`."),
273
+ method: z.string().describe("The HTTP method called."),
274
+ matched: SQLiteBoolean.describe("Whether a declared route matched the called path."),
275
+ outcome: z.string().describe("The calls' outcome — `success` or `denied`."),
276
+ scope: z.string().nullable().describe("The scope the calls' credential carried, refused or not."),
277
+ path: z.string().describe("The path the group was called with."),
278
+ count: z.number().int().describe("How many calls the group holds."),
279
+ params: z.number().int().describe("How many parameters the matched route declares; 0 when unmatched."),
280
+ firstAt: SQLiteDate.describe("The earliest call in the group."),
281
+ lastAt: SQLiteDate.describe("The latest call in the group."),
282
+ })
283
+ .describe("One grouped row of the reach statement.");
284
+ type ReachStatementRow = z.output<typeof ReachStatementRow>;
285
+
286
+ /**
287
+ * One tenant, action, method, route and outcome a credential reached.
288
+ *
289
+ * Internal: the wire shape is `ControlPlaneReachView` in `http/responses.ts`, and `http/views.ts` projects this into it.
290
+ */
291
+ export const ControlPlaneReachRow = z
292
+ .object({
293
+ tenant: z
294
+ .string()
295
+ .nullable()
296
+ .describe("The tenant the calls reached, as their handler recorded it. Null when the handler named none."),
297
+ action: z
298
+ .string()
299
+ .describe("`controlplane/call_allowed` for admitted calls, `controlplane/call_denied` for refusals."),
300
+ method: z.string().describe("The HTTP method called."),
301
+ route: z
302
+ .string()
303
+ .describe("The declared route pattern the calls matched, or the path as called when no declared route matched."),
304
+ matched: z.boolean().describe("Whether `route` is a declared pattern. False marks an unmatched path's own row."),
305
+ outcome: z.string().describe("The calls' outcome: `success` or `denied`."),
306
+ scope: z
307
+ .string()
308
+ .nullable()
309
+ .describe(
310
+ "The scope the calls' credential carried. On a refusal it is the scope the refused credential held, not one it lacked, which the trail does not record.",
311
+ ),
312
+ count: z.number().int().describe("How many calls."),
313
+ subjects: z
314
+ .number()
315
+ .int()
316
+ .nullable()
317
+ .describe(
318
+ "How many distinct subjects the calls touched — distinct values of the route's subject parameter and the parameters before it, 0 for a route with none, null for an unmatched path, which names no subject it can count.",
319
+ ),
320
+ firstAt: z.date().describe("When the first call landed."),
321
+ lastAt: z.date().describe("When the last call landed."),
322
+ })
323
+ .describe("One tenant, action, method, route and outcome one control-plane credential reached, with its counts.");
324
+ export type ControlPlaneReachRow = z.output<typeof ControlPlaneReachRow>;
325
+
326
+ /** One subject a route reached, from the paths it was called with. Internal, like {@link ControlPlaneReachRow}. */
327
+ export const ControlPlaneReachSubjectRow = ControlPlaneReachRow.omit({ subjects: true })
328
+ .extend({
329
+ path: z.string().describe("The path as called."),
330
+ subjectId: z
331
+ .string()
332
+ .nullable()
333
+ .describe(
334
+ "The value of the route's last id parameter (`id`, or a name ending in `Id`), or of its last parameter when none names an id — whose data the call acted on. Null when the route declares none.",
335
+ ),
336
+ params: z.record(z.string(), z.string()).describe("Every parameter the route declares, with its value in `path`."),
337
+ })
338
+ .describe("One path a route was called with, and the subject ids it names.");
339
+ export type ControlPlaneReachSubjectRow = z.output<typeof ControlPlaneReachSubjectRow>;
340
+
341
+ /** What one path's subject is counted as: its {@link routeSubject} key, or the path itself when that names none. */
342
+ function subjectKey(row: ReachStatementRow): string {
343
+ return routeSubject(row.route, row.path).key ?? row.path;
344
+ }
345
+
346
+ /** One group of the aggregate, folded from its per-path rows. */
347
+ interface Folded {
348
+ row: ReachStatementRow;
349
+ count: number;
350
+ subjects: Set<string>;
351
+ first: Date;
352
+ last: Date;
353
+ }
354
+
355
+ /**
356
+ * Fold the per-path rows into one reach row per group. Every group is the union of its paths' rows, so the counts sum,
357
+ * the instants are the extremes, and the subjects are the distinct subject keys among its paths: a route with
358
+ * parameters counts them, a route with none counts 0, and an unmatched path names no subject it can count.
359
+ */
360
+ function fold(rows: readonly ReachStatementRow[]): ControlPlaneReachRow[] {
361
+ const folded = new Map<string, Folded>();
362
+ for (const row of rows) {
363
+ const key = JSON.stringify(GROUP.map((column) => row[column]));
364
+ const group = folded.get(key);
365
+ if (!group) {
366
+ folded.set(key, {
367
+ row,
368
+ count: row.count,
369
+ subjects: new Set([subjectKey(row)]),
370
+ first: row.firstAt,
371
+ last: row.lastAt,
372
+ });
373
+ continue;
374
+ }
375
+ group.count += row.count;
376
+ group.subjects.add(subjectKey(row));
377
+ if (row.firstAt < group.first) group.first = row.firstAt;
378
+ if (row.lastAt > group.last) group.last = row.lastAt;
379
+ }
380
+ return [...folded.values()]
381
+ .map(({ row, count, subjects, first, last }) => ({
382
+ tenant: row.tenant,
383
+ action: row.action,
384
+ method: row.method,
385
+ route: row.route,
386
+ matched: row.matched,
387
+ outcome: row.outcome,
388
+ scope: row.scope,
389
+ count,
390
+ subjects: !row.matched ? null : row.params > 0 ? subjects.size : 0,
391
+ firstAt: first,
392
+ lastAt: last,
393
+ }))
394
+ .sort(byGroup);
395
+ }
396
+
397
+ /** Read the statement's rows, decoded. */
398
+ async function grouped(
399
+ db: AuditDatabase,
400
+ filter: ControlPlaneReachFilter,
401
+ patterns: readonly ReachPattern[],
402
+ ): Promise<ReachStatementRow[]> {
403
+ const rows = await controlPlaneReachStatement(db, filter, patterns).execute();
404
+ return rows.map((row) => ReachStatementRow.parse(row));
405
+ }
406
+
407
+ /** Everything one connection's calls reached over a window, one row per tenant, action, method, route and outcome. */
408
+ export async function controlPlaneReach(
409
+ db: AuditDatabase,
410
+ filter: ControlPlaneReachFilter,
411
+ patterns: readonly ReachPattern[],
412
+ ): Promise<ControlPlaneReachRow[]> {
413
+ return fold(await grouped(db, filter, patterns));
414
+ }
415
+
416
+ /** One route's subjects, and that route's reach rows beside them — from the one statement's per-path rows. */
417
+ export async function controlPlaneReachSubjects(
418
+ db: AuditDatabase,
419
+ filter: ControlPlaneReachFilter & { route: string },
420
+ patterns: readonly ReachPattern[],
421
+ ): Promise<{ reach: ControlPlaneReachRow[]; subjects: ControlPlaneReachSubjectRow[] }> {
422
+ const rows = await grouped(db, filter, patterns);
423
+ const subjects = rows.map((row) => {
424
+ const params = row.matched ? routeParams(row.route, row.path) : {};
425
+ return {
426
+ tenant: row.tenant,
427
+ action: row.action,
428
+ method: row.method,
429
+ route: row.route,
430
+ matched: row.matched,
431
+ path: row.path,
432
+ outcome: row.outcome,
433
+ scope: row.scope,
434
+ subjectId: row.matched ? routeSubject(row.route, row.path).subjectId : null,
435
+ params,
436
+ count: row.count,
437
+ firstAt: row.firstAt,
438
+ lastAt: row.lastAt,
439
+ } satisfies ControlPlaneReachSubjectRow;
440
+ });
441
+ return { reach: fold(rows), subjects };
442
+ }
443
+
444
+ /** The aggregate's order, as SQLite sorts it: null first, then by code unit. */
445
+ function byGroup(a: ControlPlaneReachRow, b: ControlPlaneReachRow): number {
446
+ for (const column of GROUP) {
447
+ const [x, y] = [a[column], b[column]];
448
+ if (x === y) continue;
449
+ if (x === null) return -1;
450
+ if (y === null) return 1;
451
+ return x < y ? -1 : 1;
452
+ }
453
+ return 0;
454
+ }
package/src/recorder.ts CHANGED
@@ -7,8 +7,9 @@ import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
7
7
  import { type D1RetryOptions, withD1Retry } from "@pithy-sh/core/src/data/withD1Retry";
8
8
  import { messageOf, PithyError } from "@pithy-sh/core/src/error/pithyError";
9
9
  import { z } from "zod";
10
+ import { appendChained, isUnmigratedChain } from "./chain/append";
10
11
  import { AuditMetadataColumn } from "./data/auditEvent";
11
- import type { AuditDatabase } from "./data/tables";
12
+ import type { AuditDatabase, AuditEventInsert } from "./data/tables";
12
13
  import { AuditInvalidEventError, AuditWriteFailedError } from "./error/errors";
13
14
 
14
15
  /**
@@ -81,6 +82,14 @@ export interface AuditRecorderOptions {
81
82
  onError?: (error: PithyError) => void;
82
83
  /** Retry tuning for the insert. Defaults to retrying `timeout` and `database-busy`. */
83
84
  retry?: D1RetryOptions;
85
+ /**
86
+ * Hand a recorded event to its sinks (#824) — called once the row is written, with its id and action, and
87
+ * nothing else. It never fails the write: whatever it throws goes to {@link onShipError} and the event stands.
88
+ * Omitted when no sink is declared.
89
+ */
90
+ ship?: (event: { eventId: string; action: string }) => Promise<void>;
91
+ /** Called with whatever {@link ship} threw. The event is already written; only its shipment was lost. */
92
+ onShipError?: (error: unknown) => void;
84
93
  }
85
94
 
86
95
  /** Map any caught failure to its namespaced audit `PithyError`. A bad event is `invalid_event`; anything else is `write_failed`. */
@@ -104,52 +113,65 @@ export async function recordAuditEvent(
104
113
  ): Promise<void> {
105
114
  const onError = options?.onError ?? (() => {});
106
115
  const origin = options?.origin ?? NO_ORIGIN;
116
+ // Generated once, before the retry wrapper, so every retry of this one record reuses it. A
117
+ // post-commit transport failure then retries onto the unique eventId index — a UNIQUE violation
118
+ // the guard reads as "already landed", not a duplicate row. It is also what a sink de-duplicates on.
119
+ const eventId = crypto.randomUUID();
120
+ let action: string;
107
121
  try {
108
122
  const event = AuditEvent.parse(input);
123
+ action = event.action;
109
124
  const occurredAt = event.occurredAt ?? new Date();
110
- // Generated once, before the retry wrapper, so every retry of this one record reuses it. A
111
- // post-commit transport failure then retries onto the unique eventId index — a UNIQUE violation
112
- // the guard reads as "already landed", not a duplicate row.
113
- const eventId = crypto.randomUUID();
114
- await withD1Retry(
115
- () =>
116
- db
117
- .insertInto("pithyAuditEvents")
118
- .values({
119
- eventId,
120
- occurredAt: SQLiteDate.encode(occurredAt),
121
- action: event.action,
122
- outcome: event.outcome,
123
- severity: event.severity,
124
- actorType: event.actorType,
125
- actorId: event.actorId ?? null,
126
- // Named only when the event carries one (#721). A Worker deployed ahead of
127
- // `audit_0002_actor_kind` then keeps recording every row it recorded before; only a call
128
- // through a connection with a kind depends on the column being there.
129
- ...(event.actorKind == null ? {} : { actorKind: event.actorKind }),
130
- sessionId: event.sessionId ?? null,
131
- resourceType: event.resourceType ?? null,
132
- resourceId: event.resourceId ?? null,
133
- ip: event.ip ?? null,
134
- userAgent: event.userAgent ?? null,
135
- requestId: event.requestId ?? null,
136
- metadata: event.metadata == null ? null : AuditMetadataColumn.encode(event.metadata),
137
- // From `event`, and it is the only dimension column that is. The recorder cannot forge this
138
- // one and cannot default it: `origin` is read from the Worker's own vars, and no var knows
139
- // which customer an action was taken for. So it is exactly as trustworthy as the emit site,
140
- // and omitted it is null — "not tenant-scoped" — rather than a guess.
141
- tenant: event.tenant ?? null,
142
- // Last, and from `options` rather than `event` — the event cannot reach these columns.
143
- project: origin.project,
144
- environment: origin.environment,
145
- worker: origin.worker,
146
- version: origin.version,
147
- })
148
- .execute(),
149
- options?.retry,
150
- );
125
+ const record: AuditEventInsert = {
126
+ eventId,
127
+ occurredAt: SQLiteDate.encode(occurredAt),
128
+ action: event.action,
129
+ outcome: event.outcome,
130
+ severity: event.severity,
131
+ actorType: event.actorType,
132
+ actorId: event.actorId ?? null,
133
+ // Named only when the event carries one (#721). A Worker deployed ahead of
134
+ // `audit_0002_actor_kind` then keeps recording every row it recorded before; only a call
135
+ // through a connection with a kind depends on the column being there.
136
+ ...(event.actorKind == null ? {} : { actorKind: event.actorKind }),
137
+ sessionId: event.sessionId ?? null,
138
+ resourceType: event.resourceType ?? null,
139
+ resourceId: event.resourceId ?? null,
140
+ ip: event.ip ?? null,
141
+ userAgent: event.userAgent ?? null,
142
+ requestId: event.requestId ?? null,
143
+ metadata: event.metadata == null ? null : AuditMetadataColumn.encode(event.metadata),
144
+ // From `event`, and it is the only dimension column that is. The recorder cannot forge this
145
+ // one and cannot default it: `origin` is read from the Worker's own vars, and no var knows
146
+ // which customer an action was taken for. So it is exactly as trustworthy as the emit site,
147
+ // and omitted it is null — "not tenant-scoped" — rather than a guess.
148
+ tenant: event.tenant ?? null,
149
+ // Last, and from `options` rather than `event` — the event cannot reach these columns.
150
+ project: origin.project,
151
+ environment: origin.environment,
152
+ worker: origin.worker,
153
+ version: origin.version,
154
+ };
155
+ try {
156
+ await appendChained(db, record, options?.retry ? { retry: options.retry } : {});
157
+ } catch (error) {
158
+ // A database not yet migrated to the chain still records, unchained, as every row before the chain did —
159
+ // the same tolerance the recorder keeps for `actorKind` ahead of its migration. `pithy migrate` closes it.
160
+ if (!isUnmigratedChain(error)) throw error;
161
+ await withD1Retry(() => db.insertInto("pithyAuditEvents").values(record).execute(), options?.retry);
162
+ }
151
163
  } catch (error) {
152
164
  onError(toAuditError(error));
165
+ return;
166
+ }
167
+ // After the write, and outside it: an event that could not be enqueued is still in the trail, and the write it
168
+ // follows has already answered. Only a written event is shipped, so a sink never holds one the trail does not.
169
+ if (options?.ship) {
170
+ try {
171
+ await options.ship({ eventId, action });
172
+ } catch (error) {
173
+ options.onShipError?.(error);
174
+ }
153
175
  }
154
176
  }
155
177