@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.
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 +106 -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 +134 -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
@@ -0,0 +1,43 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { AUDIT_CHECKPOINT_BINDING } from "../chain/checkpoint.js";
4
+ import { AUDIT_CAPABILITY, auditWorkflowRegistry } from "../workflows/specs.js";
5
+ import { environmentScope } from "@pithy-sh/core/src/naming/provisionScope";
6
+ import { hostWorkflowsFor, resolveWorkflowHost } from "@pithy-sh/core/src/workflow/host";
7
+ //#region src/provision/resolveAuditConfig.ts
8
+ /**
9
+ * Resolve the checkpoint host's committed `wrangler.jsonc` template into one environment's standalone config
10
+ * (#822). Thin over core's {@link resolveWorkflowHost}: this file owns only which database the host reads, which
11
+ * bucket it writes, and the Workflow names derived from audit's own specs.
12
+ */
13
+ /**
14
+ * The checkpoint bucket's name in a declared environment — **the name `pithy provision` gives the
15
+ * `AUDIT_CHECKPOINTS` binding**, read through the very function it composes it with, so the host and the app
16
+ * Worker cannot bind two different buckets.
17
+ */
18
+ function auditCheckpointBucketName(project, env) {
19
+ return environmentScope(project, env).resource(AUDIT_CHECKPOINT_BINDING, "r2", {});
20
+ }
21
+ /** Fill the template for one environment. */
22
+ function resolveAuditConfig(template, params) {
23
+ const { project, env, feature } = params;
24
+ const derived = hostWorkflowsFor(auditWorkflowRegistry, {
25
+ project,
26
+ capability: AUDIT_CAPABILITY,
27
+ env,
28
+ ...feature ? { feature } : {}
29
+ });
30
+ const resolved = resolveWorkflowHost(template, {
31
+ project,
32
+ capability: AUDIT_CAPABILITY,
33
+ env,
34
+ ...feature ? { feature } : {},
35
+ databaseIds: { DB: params.auditDatabaseId },
36
+ r2BucketNames: { [AUDIT_CHECKPOINT_BINDING]: params.bucketName },
37
+ workflows: derived.workflows
38
+ });
39
+ resolved.triggers = derived.crons.length > 0 ? { crons: derived.crons } : void 0;
40
+ return resolved;
41
+ }
42
+ //#endregion
43
+ export { auditCheckpointBucketName, resolveAuditConfig };
@@ -0,0 +1,21 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import type { RetainingPurgeContribution } from "@pithy-sh/core/src/capability/purge";
4
+ /**
5
+ * What a person's purge means for `@pithy-sh/audit` (#814): **nothing is erased, and the export says so and why.**
6
+ *
7
+ * The audit trail is the record of who acted — who signed in, who changed a role, who deleted an organization — and
8
+ * it is what a security review or a dispute is read against. A trail that forgot an actor on request would answer
9
+ * neither, so this contribution **retains**: the purge records the step as retained with the basis below and erases
10
+ * no event, and the export answers for every event where the person is the actor.
11
+ *
12
+ * Events are written through `emit`, whose metadata is held to `Loggable` — no token, no secret reaches a row — so
13
+ * the export carries each event whole.
14
+ */
15
+ /** The one sentence the purge records with this step. */
16
+ export declare const AUDIT_PURGE_SUMMARY = "Keeps every audit event where the user is the actor.";
17
+ /** Why, in the sentence the person is told. */
18
+ export declare const AUDIT_RETENTION_BASIS = "Kept as the record of who did what, which a security review or a dispute is read against.";
19
+ /** The user contribution `audit()` declares, over the D1 binding its config names. */
20
+ export declare function auditUserPurge(database?: string): RetainingPurgeContribution;
21
+ //# sourceMappingURL=contribution.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"contribution.d.ts","sourceRoot":"","sources":["../../src/purge/contribution.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AAGtF;;;;;;;;;;GAUG;AAEH,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,yDAAyD,CAAC;AAE1F,+CAA+C;AAC/C,eAAO,MAAM,qBAAqB,8FAC2D,CAAC;AAE9F,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,QAAQ,SAAO,GAAG,0BAA0B,CAW1E"}
@@ -0,0 +1,41 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { AuditEventRow } from "../data/auditEvent.js";
4
+ import { personRowsExport } from "@pithy-sh/core/src/capability/personRows";
5
+ //#region src/purge/contribution.ts
6
+ /**
7
+ * What a person's purge means for `@pithy-sh/audit` (#814): **nothing is erased, and the export says so and why.**
8
+ *
9
+ * The audit trail is the record of who acted — who signed in, who changed a role, who deleted an organization — and
10
+ * it is what a security review or a dispute is read against. A trail that forgot an actor on request would answer
11
+ * neither, so this contribution **retains**: the purge records the step as retained with the basis below and erases
12
+ * no event, and the export answers for every event where the person is the actor.
13
+ *
14
+ * Events are written through `emit`, whose metadata is held to `Loggable` — no token, no secret reaches a row — so
15
+ * the export carries each event whole.
16
+ */
17
+ /** The one sentence the purge records with this step. */
18
+ const AUDIT_PURGE_SUMMARY = "Keeps every audit event where the user is the actor.";
19
+ /** Why, in the sentence the person is told. */
20
+ const AUDIT_RETENTION_BASIS = "Kept as the record of who did what, which a security review or a dispute is read against.";
21
+ /** The user contribution `audit()` declares, over the D1 binding its config names. */
22
+ function auditUserPurge(database = "DB") {
23
+ return {
24
+ subject: "user",
25
+ summary: AUDIT_PURGE_SUMMARY,
26
+ retain: { basis: AUDIT_RETENTION_BASIS },
27
+ export: personRowsExport({
28
+ capability: "audit",
29
+ database,
30
+ tables: [{
31
+ table: "pithyAuditEvents",
32
+ schema: AuditEventRow,
33
+ columns: ["actorId"],
34
+ as: "events",
35
+ orderBy: "id"
36
+ }]
37
+ })
38
+ };
39
+ }
40
+ //#endregion
41
+ export { AUDIT_PURGE_SUMMARY, AUDIT_RETENTION_BASIS, auditUserPurge };
@@ -0,0 +1,250 @@
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
+ import { ReachPattern } from "./routePattern";
6
+ /**
7
+ * What one control-plane credential reached — `#828`.
8
+ *
9
+ * "This key leaked. What did it touch?" Every admitted call writes `controlplane/call_allowed` against the connection
10
+ * as `resourceId`, with the scope, the key, the method and the path as called in `metadata`. The listing carries no
11
+ * metadata, so answering from it means one forensic read per event, behind the scope that also discloses the client
12
+ * IP. This reads the same rows in SQL and returns one row per tenant, action, method, route and outcome.
13
+ *
14
+ * **A refusal is the handler's, paired with the gate's row.** The gate's own refusal (`auditDenial`) is of a call that
15
+ * never verified, so it names no connection and no actor and is no credential's reach. What a verified credential was
16
+ * refused is a handler's refusal past the gate (`auditHandlerDenial`): a `controlplane/call_denied` row against the
17
+ * connection, written in the same request as the gate's `call_allowed` for the same call. The two are one call, and
18
+ * it was refused, so the `call_allowed` row of a request that also holds a refusal for the same actor, method and path
19
+ * is dropped, and the refusal reads its scope and key from that row when its own names none — as rows written before
20
+ * the guard recorded them do not. `scope` is the scope the credential carried, never `required`, which on a handler's
21
+ * 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
22
+ * Cloudflare, cannot be paired: its refusal stands on the scope and key its own row names, and its gate row stays an
23
+ * admitted call.
24
+ *
25
+ * **Grouped by the declared route, expandable to the subjects.** The path is recorded as called, so
26
+ * `/admin/users/u_8f2` names a user. Each call is matched back to the admin route the manifest declares
27
+ * (`routePattern.ts`), most specific first; a path no route matches is its own row, marked unmatched.
28
+ * {@link controlPlaneReachSubjects} expands one route into the paths it was called with and the subject ids they
29
+ * name — the *whose data* list a breach scope is drawn from. The subject is the route's last id parameter
30
+ * ({@link routeSubject}), so a ledger read by user and currency names the user, and a group's subject count is of
31
+ * distinct subjects, not distinct paths.
32
+ *
33
+ * **The tenant is the handler's, joined by request id.** The gate writes its row before the handler runs, so before
34
+ * any tenant is resolved, and that row's own `tenant` is null. The handler's events in the same request carry it, and
35
+ * share the call's `requestId` (`cf-ray`) and `actorId`. So a call reached every tenant its handler recorded, and a
36
+ * call whose handler recorded none — or that carries no request id, as off Cloudflare — reached no named tenant. Only
37
+ * `control-plane` events by the same actor count, so a stray event sharing a request id cannot attribute a call.
38
+ *
39
+ * **One statement, never a page walk.** The calls are found through `pithyAuditEventsCallIdx` and the handler events
40
+ * through `pithyAuditEventsRequestIdx`. The routes go in as one JSON parameter, so a manifest of any size is one bound
41
+ * value rather than four per route against D1's limit. The statement groups by called path, and the Worker folds the
42
+ * paths of each group, because a subject is read from a path by splitting it on `/`, which SQLite cannot do without a
43
+ * recursive CTE per row.
44
+ *
45
+ * **Nothing personal leaves this function.** It reads the scope, the key id, the method and the path out of
46
+ * `metadata`, and no other key, and never the IP or the user-agent. Of the handler's events it reads the tenant.
47
+ */
48
+ /** What to read: one connection over an inclusive window, optionally one key and one route. */
49
+ export interface ControlPlaneReachFilter {
50
+ /** The connection whose calls are read — the rows' `resourceId`. */
51
+ connectionId: string;
52
+ /** Inclusive lower bound on `occurredAt`. */
53
+ since: Date;
54
+ /** Inclusive upper bound on `occurredAt`. */
55
+ until: Date;
56
+ /** Narrow to the calls one registered key signed — `metadata.keyId`. */
57
+ keyId?: string;
58
+ /** Narrow to one route — a declared pattern, or the called path of an unmatched row. */
59
+ route?: string;
60
+ }
61
+ /**
62
+ * The statement, as one Kysely query — exported so a test can read its query plan.
63
+ *
64
+ * 1. **`routes`** — the declared routes, unpacked from the one JSON parameter.
65
+ * 2. **`rows`** — the connection's call rows in the window, with the scope, key, method and path lifted out of
66
+ * `metadata`. A row with no path is no call to a route and is dropped.
67
+ * 3. **`calls`** — one row per call: a refusal takes its scope and key from the gate's row in the same request when its
68
+ * own names none, and that gate row is dropped, since the call it admitted was refused. The key filter applies here,
69
+ * after the refusal has its key.
70
+ * 4. **`matches`** — each call against every route of its method, by glob and slash count, ranked so the most specific
71
+ * match is `pick = 1`.
72
+ * 5. **`tenants`** — the distinct tenants each call's handler recorded, by request id and actor, from `control-plane`
73
+ * events only.
74
+ * 6. **`reached`** — each call once per tenant it reached, with its route, or its own path when unmatched.
75
+ * 7. **The group** — counts and instants per tenant, route, action, method, outcome and path.
76
+ */
77
+ export declare function controlPlaneReachStatement(db: AuditDatabase, filter: ControlPlaneReachFilter, patterns: readonly ReachPattern[]): import("kysely").SelectQueryBuilder<import("@pithy-sh/core/src/data/db").DatabaseSchema<{
78
+ pithyAuditEvents: z.ZodObject<{
79
+ id: z.ZodNumber;
80
+ eventId: z.ZodString;
81
+ occurredAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
82
+ action: z.ZodString;
83
+ outcome: z.ZodEnum<{
84
+ denied: "denied";
85
+ failure: "failure";
86
+ success: "success";
87
+ }>;
88
+ severity: z.ZodEnum<{
89
+ critical: "critical";
90
+ info: "info";
91
+ warning: "warning";
92
+ }>;
93
+ actorType: z.ZodEnum<{
94
+ anonymous: "anonymous";
95
+ "control-plane": "control-plane";
96
+ service: "service";
97
+ system: "system";
98
+ user: "user";
99
+ }>;
100
+ actorId: z.ZodNullable<z.ZodString>;
101
+ actorKind: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
102
+ agent: "agent";
103
+ dashboard: "dashboard";
104
+ script: "script";
105
+ }>>>;
106
+ sessionId: z.ZodNullable<z.ZodString>;
107
+ resourceType: z.ZodNullable<z.ZodString>;
108
+ resourceId: z.ZodNullable<z.ZodString>;
109
+ ip: z.ZodNullable<z.ZodString>;
110
+ userAgent: z.ZodNullable<z.ZodString>;
111
+ requestId: z.ZodNullable<z.ZodString>;
112
+ metadata: z.ZodNullable<import("@pithy-sh/core/src/data/codecs").SqliteJson<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
113
+ project: z.ZodNullable<z.ZodString>;
114
+ environment: z.ZodNullable<z.ZodString>;
115
+ worker: z.ZodNullable<z.ZodString>;
116
+ version: z.ZodNullable<z.ZodString>;
117
+ tenant: z.ZodNullable<z.ZodString>;
118
+ chainSeq: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
119
+ chainPrev: z.ZodDefault<z.ZodNullable<z.ZodString>>;
120
+ chainHash: z.ZodDefault<z.ZodNullable<z.ZodString>>;
121
+ chainSalt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
122
+ }, z.core.$strip>;
123
+ pithyAuditSinks: z.ZodObject<{
124
+ sink: z.ZodString;
125
+ lastDeliveredAt: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>;
126
+ lastFailedAt: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>;
127
+ retrying: z.ZodNumber;
128
+ deadLettered: z.ZodNumber;
129
+ }, z.core.$strip>;
130
+ }> & {
131
+ routes: {
132
+ glob: string;
133
+ method: string;
134
+ params: number;
135
+ pattern: string;
136
+ rank: number;
137
+ slashes: number | null;
138
+ };
139
+ } & {
140
+ rows: {
141
+ action: string;
142
+ actorId: string | null;
143
+ id: number;
144
+ keyId: string | null;
145
+ method: string;
146
+ occurredAt: string | number | Date;
147
+ outcome: "denied" | "failure" | "success";
148
+ path: string;
149
+ requestId: string | null;
150
+ scope: string | null;
151
+ tenant: string | null;
152
+ };
153
+ } & {
154
+ calls: {
155
+ action: string;
156
+ actorId: string | null;
157
+ id: number;
158
+ method: string;
159
+ occurredAt: string | number | Date;
160
+ outcome: "denied" | "failure" | "success";
161
+ path: string;
162
+ requestId: string | null;
163
+ scope: string | null;
164
+ tenant: string | null;
165
+ };
166
+ } & {
167
+ matches: {
168
+ callId: number;
169
+ params: number;
170
+ pattern: string;
171
+ pick: number;
172
+ };
173
+ } & {
174
+ tenants: {
175
+ callId: number;
176
+ tenant: string | null;
177
+ };
178
+ } & {
179
+ reached: {
180
+ action: string;
181
+ matched: number;
182
+ method: string;
183
+ occurredAt: string | number | Date;
184
+ outcome: "denied" | "failure" | "success";
185
+ params: number;
186
+ path: string;
187
+ route: string;
188
+ scope: string | null;
189
+ tenant: string | null;
190
+ };
191
+ }, "reached", {
192
+ action: string;
193
+ count: number;
194
+ firstAt: string | number | Date;
195
+ lastAt: string | number | Date;
196
+ matched: number;
197
+ method: string;
198
+ outcome: "denied" | "failure" | "success";
199
+ params: number;
200
+ path: string;
201
+ route: string;
202
+ scope: string | null;
203
+ tenant: string | null;
204
+ }>;
205
+ /**
206
+ * One tenant, action, method, route and outcome a credential reached.
207
+ *
208
+ * Internal: the wire shape is `ControlPlaneReachView` in `http/responses.ts`, and `http/views.ts` projects this into it.
209
+ */
210
+ export declare const ControlPlaneReachRow: z.ZodObject<{
211
+ tenant: z.ZodNullable<z.ZodString>;
212
+ action: z.ZodString;
213
+ method: z.ZodString;
214
+ route: z.ZodString;
215
+ matched: z.ZodBoolean;
216
+ outcome: z.ZodString;
217
+ scope: z.ZodNullable<z.ZodString>;
218
+ count: z.ZodNumber;
219
+ subjects: z.ZodNullable<z.ZodNumber>;
220
+ firstAt: z.ZodDate;
221
+ lastAt: z.ZodDate;
222
+ }, z.core.$strip>;
223
+ export type ControlPlaneReachRow = z.output<typeof ControlPlaneReachRow>;
224
+ /** One subject a route reached, from the paths it was called with. Internal, like {@link ControlPlaneReachRow}. */
225
+ export declare const ControlPlaneReachSubjectRow: z.ZodObject<{
226
+ tenant: z.ZodNullable<z.ZodString>;
227
+ action: z.ZodString;
228
+ method: z.ZodString;
229
+ route: z.ZodString;
230
+ matched: z.ZodBoolean;
231
+ outcome: z.ZodString;
232
+ scope: z.ZodNullable<z.ZodString>;
233
+ count: z.ZodNumber;
234
+ firstAt: z.ZodDate;
235
+ lastAt: z.ZodDate;
236
+ path: z.ZodString;
237
+ subjectId: z.ZodNullable<z.ZodString>;
238
+ params: z.ZodRecord<z.ZodString, z.ZodString>;
239
+ }, z.core.$strip>;
240
+ export type ControlPlaneReachSubjectRow = z.output<typeof ControlPlaneReachSubjectRow>;
241
+ /** Everything one connection's calls reached over a window, one row per tenant, action, method, route and outcome. */
242
+ export declare function controlPlaneReach(db: AuditDatabase, filter: ControlPlaneReachFilter, patterns: readonly ReachPattern[]): Promise<ControlPlaneReachRow[]>;
243
+ /** One route's subjects, and that route's reach rows beside them — from the one statement's per-path rows. */
244
+ export declare function controlPlaneReachSubjects(db: AuditDatabase, filter: ControlPlaneReachFilter & {
245
+ route: string;
246
+ }, patterns: readonly ReachPattern[]): Promise<{
247
+ reach: ControlPlaneReachRow[];
248
+ subjects: ControlPlaneReachSubjectRow[];
249
+ }>;
250
+ //# sourceMappingURL=reach.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"reach.d.ts","sourceRoot":"","sources":["../src/reach.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,YAAY,EAA6B,MAAM,gBAAgB,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,+FAA+F;AAC/F,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,KAAK,EAAE,IAAI,CAAC;IACZ,6CAA6C;IAC7C,KAAK,EAAE,IAAI,CAAC;IACZ,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,aAAa,EACjB,MAAM,EAAE,uBAAuB,EAC/B,QAAQ,EAAE,SAAS,YAAY,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmKlC;AAqBD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;iBAgCkF,CAAC;AACpH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAEzE,mHAAmH;AACnH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;iBAWsC,CAAC;AAC/E,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAoEvF,sHAAsH;AACtH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,aAAa,EACjB,MAAM,EAAE,uBAAuB,EAC/B,QAAQ,EAAE,SAAS,YAAY,EAAE,GAChC,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAEjC;AAED,8GAA8G;AAC9G,wBAAsB,yBAAyB,CAC7C,EAAE,EAAE,aAAa,EACjB,MAAM,EAAE,uBAAuB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EACnD,QAAQ,EAAE,SAAS,YAAY,EAAE,GAChC,OAAO,CAAC;IAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAAC,QAAQ,EAAE,2BAA2B,EAAE,CAAA;CAAE,CAAC,CAqBrF"}
package/dist/reach.js ADDED
@@ -0,0 +1,244 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { ReachPattern, routeParams, routeSubject } from "./routePattern.js";
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
+ //#region src/reach.ts
9
+ /** The two actions that record a verified call: the gate's admission and a handler's refusal past it. */
10
+ const CALL_ACTIONS = [ControlPlaneAuditActions.callAllowed, ControlPlaneAuditActions.callDenied];
11
+ /** The resource type every attributed call row carries. */
12
+ const CONNECTION_RESOURCE = "controlplane_connection";
13
+ /** The routes, as the statement's one JSON parameter. */
14
+ const ReachPatterns = sqliteJson(z.array(ReachPattern).describe("Every declared admin route, ranked."));
15
+ /** The columns every grouping carries, in the order the answer is sorted by. */
16
+ const GROUP = [
17
+ "tenant",
18
+ "route",
19
+ "action",
20
+ "method",
21
+ "matched",
22
+ "outcome",
23
+ "scope"
24
+ ];
25
+ /** The order the statement sorts in: the group, with the path after the route. */
26
+ const ORDER = [
27
+ ...GROUP.slice(0, 2),
28
+ "path",
29
+ ...GROUP.slice(2)
30
+ ];
31
+ /**
32
+ * The statement, as one Kysely query — exported so a test can read its query plan.
33
+ *
34
+ * 1. **`routes`** — the declared routes, unpacked from the one JSON parameter.
35
+ * 2. **`rows`** — the connection's call rows in the window, with the scope, key, method and path lifted out of
36
+ * `metadata`. A row with no path is no call to a route and is dropped.
37
+ * 3. **`calls`** — one row per call: a refusal takes its scope and key from the gate's row in the same request when its
38
+ * own names none, and that gate row is dropped, since the call it admitted was refused. The key filter applies here,
39
+ * after the refusal has its key.
40
+ * 4. **`matches`** — each call against every route of its method, by glob and slash count, ranked so the most specific
41
+ * match is `pick = 1`.
42
+ * 5. **`tenants`** — the distinct tenants each call's handler recorded, by request id and actor, from `control-plane`
43
+ * events only.
44
+ * 6. **`reached`** — each call once per tenant it reached, with its route, or its own path when unmatched.
45
+ * 7. **The group** — counts and instants per tenant, route, action, method, outcome and path.
46
+ */
47
+ function controlPlaneReachStatement(db, filter, patterns) {
48
+ const allowed = ControlPlaneAuditActions.callAllowed;
49
+ const denied = ControlPlaneAuditActions.callDenied;
50
+ const encoded = ReachPatterns.encode([...patterns]);
51
+ const field = (name) => sql`json_extract(${sql.ref("value")}, ${`$.${name}`})`;
52
+ let reached = db.with("routes", (q) => q.selectFrom(sql`json_each(${encoded})`.as("each")).select([
53
+ sql`${field("method")}`.as("method"),
54
+ sql`${field("pattern")}`.as("pattern"),
55
+ sql`${field("glob")}`.as("glob"),
56
+ sql`${field("slashes")}`.as("slashes"),
57
+ sql`${field("params")}`.as("params"),
58
+ sql`${field("rank")}`.as("rank")
59
+ ])).with("rows", (q) => q.selectFrom("pithyAuditEvents").select((eb) => [
60
+ "id",
61
+ "action",
62
+ "outcome",
63
+ "occurredAt",
64
+ "requestId",
65
+ "actorId",
66
+ "tenant",
67
+ sql`json_extract(${eb.ref("metadata")}, '$.scope')`.as("scope"),
68
+ sql`json_extract(${eb.ref("metadata")}, '$.keyId')`.as("keyId"),
69
+ sql`json_extract(${eb.ref("metadata")}, '$.method')`.as("method"),
70
+ sql`json_extract(${eb.ref("metadata")}, '$.path')`.as("path")
71
+ ]).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).where(sql`json_extract(${sql.ref("metadata")}, '$.path')`, "is not", null)).with("calls", (q) => {
72
+ const keyId = sql`coalesce(${sql.ref("call.keyId")}, ${sql.ref("gate.keyId")})`;
73
+ let calls = q.selectFrom("rows as call").leftJoin("rows as gate", (join) => join.on("call.action", "=", denied).on("gate.action", "=", allowed).onRef("gate.requestId", "=", "call.requestId").onRef("gate.actorId", "=", "call.actorId").onRef("gate.method", "=", "call.method").onRef("gate.path", "=", "call.path")).where((eb) => eb.or([eb("call.action", "=", denied), eb.not(eb.exists(eb.selectFrom("rows as refusal").select(sql`1`.as("one")).where("refusal.action", "=", denied).whereRef("refusal.requestId", "=", "call.requestId").whereRef("refusal.actorId", "=", "call.actorId").whereRef("refusal.method", "=", "call.method").whereRef("refusal.path", "=", "call.path")))])).select([
74
+ "call.id as id",
75
+ "call.action as action",
76
+ "call.outcome as outcome",
77
+ "call.occurredAt as occurredAt",
78
+ "call.requestId as requestId",
79
+ "call.actorId as actorId",
80
+ "call.tenant as tenant",
81
+ sql`coalesce(${sql.ref("call.scope")}, ${sql.ref("gate.scope")})`.as("scope"),
82
+ "call.method as method",
83
+ "call.path as path"
84
+ ]);
85
+ if (filter.keyId !== void 0) calls = calls.where(keyId, "=", filter.keyId);
86
+ return calls;
87
+ }).with("matches", (q) => q.selectFrom("calls").innerJoin("routes", (join) => join.onRef("routes.method", "=", "calls.method").on(sql`${sql.ref("calls.path")} glob ${sql.ref("routes.glob")}`).on((eb) => eb.or([eb("routes.slashes", "is", null), eb("routes.slashes", "=", sql`length(${sql.ref("calls.path")}) - length(replace(${sql.ref("calls.path")}, '/', ''))`)]))).select([
88
+ "calls.id as callId",
89
+ "routes.pattern as pattern",
90
+ "routes.params as params",
91
+ sql`row_number() over (partition by ${sql.ref("calls.id")} order by ${sql.ref("routes.rank")})`.as("pick")
92
+ ])).with("tenants", (q) => q.selectFrom("calls").innerJoin("pithyAuditEvents as handled", (join) => join.onRef("handled.requestId", "=", "calls.requestId").onRef("handled.actorId", "=", "calls.actorId").onRef("handled.id", "!=", "calls.id").on("handled.actorType", "=", "control-plane").on("handled.tenant", "is not", null)).select(["calls.id as callId", "handled.tenant as tenant"]).distinct()).with("reached", (q) => q.selectFrom("calls").leftJoin("matches", (join) => join.onRef("matches.callId", "=", "calls.id").on("matches.pick", "=", 1)).leftJoin("tenants", "tenants.callId", "calls.id").select([
93
+ sql`coalesce(${sql.ref("tenants.tenant")}, ${sql.ref("calls.tenant")})`.as("tenant"),
94
+ sql`coalesce(${sql.ref("matches.pattern")}, ${sql.ref("calls.path")})`.as("route"),
95
+ sql`${sql.ref("matches.pattern")} is not null`.as("matched"),
96
+ sql`coalesce(${sql.ref("matches.params")}, 0)`.as("params"),
97
+ "calls.action as action",
98
+ "calls.method as method",
99
+ "calls.outcome as outcome",
100
+ "calls.scope as scope",
101
+ "calls.path as path",
102
+ "calls.occurredAt as occurredAt"
103
+ ])).selectFrom("reached").select((eb) => [
104
+ ...GROUP,
105
+ "path",
106
+ sql`count(*)`.as("count"),
107
+ sql`max(${eb.ref("params")})`.as("params"),
108
+ eb.fn.min("occurredAt").as("firstAt"),
109
+ eb.fn.max("occurredAt").as("lastAt")
110
+ ]);
111
+ if (filter.route !== void 0) reached = reached.where("route", "=", filter.route);
112
+ let ordered = reached.groupBy([...GROUP, "path"]);
113
+ for (const column of ORDER) ordered = ordered.orderBy(column);
114
+ return ordered;
115
+ }
116
+ /** One grouped row as the statement returns it, decoded. Internal: the two readers below project it. */
117
+ const ReachStatementRow = z.object({
118
+ tenant: z.string().nullable().describe("The tenant the calls reached, or null when their handler named none."),
119
+ route: z.string().describe("The declared route, or the called path when no route matched."),
120
+ action: z.string().describe("`controlplane/call_allowed` or `controlplane/call_denied`."),
121
+ method: z.string().describe("The HTTP method called."),
122
+ matched: SQLiteBoolean.describe("Whether a declared route matched the called path."),
123
+ outcome: z.string().describe("The calls' outcome — `success` or `denied`."),
124
+ scope: z.string().nullable().describe("The scope the calls' credential carried, refused or not."),
125
+ path: z.string().describe("The path the group was called with."),
126
+ count: z.number().int().describe("How many calls the group holds."),
127
+ params: z.number().int().describe("How many parameters the matched route declares; 0 when unmatched."),
128
+ firstAt: SQLiteDate.describe("The earliest call in the group."),
129
+ lastAt: SQLiteDate.describe("The latest call in the group.")
130
+ }).describe("One grouped row of the reach statement.");
131
+ /**
132
+ * One tenant, action, method, route and outcome a credential reached.
133
+ *
134
+ * Internal: the wire shape is `ControlPlaneReachView` in `http/responses.ts`, and `http/views.ts` projects this into it.
135
+ */
136
+ const ControlPlaneReachRow = z.object({
137
+ tenant: z.string().nullable().describe("The tenant the calls reached, as their handler recorded it. Null when the handler named none."),
138
+ action: z.string().describe("`controlplane/call_allowed` for admitted calls, `controlplane/call_denied` for refusals."),
139
+ method: z.string().describe("The HTTP method called."),
140
+ route: z.string().describe("The declared route pattern the calls matched, or the path as called when no declared route matched."),
141
+ matched: z.boolean().describe("Whether `route` is a declared pattern. False marks an unmatched path's own row."),
142
+ outcome: z.string().describe("The calls' outcome: `success` or `denied`."),
143
+ scope: z.string().nullable().describe("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."),
144
+ count: z.number().int().describe("How many calls."),
145
+ subjects: z.number().int().nullable().describe("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."),
146
+ firstAt: z.date().describe("When the first call landed."),
147
+ lastAt: z.date().describe("When the last call landed.")
148
+ }).describe("One tenant, action, method, route and outcome one control-plane credential reached, with its counts.");
149
+ /** One subject a route reached, from the paths it was called with. Internal, like {@link ControlPlaneReachRow}. */
150
+ const ControlPlaneReachSubjectRow = ControlPlaneReachRow.omit({ subjects: true }).extend({
151
+ path: z.string().describe("The path as called."),
152
+ subjectId: z.string().nullable().describe("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."),
153
+ params: z.record(z.string(), z.string()).describe("Every parameter the route declares, with its value in `path`.")
154
+ }).describe("One path a route was called with, and the subject ids it names.");
155
+ /** What one path's subject is counted as: its {@link routeSubject} key, or the path itself when that names none. */
156
+ function subjectKey(row) {
157
+ return routeSubject(row.route, row.path).key ?? row.path;
158
+ }
159
+ /**
160
+ * Fold the per-path rows into one reach row per group. Every group is the union of its paths' rows, so the counts sum,
161
+ * the instants are the extremes, and the subjects are the distinct subject keys among its paths: a route with
162
+ * parameters counts them, a route with none counts 0, and an unmatched path names no subject it can count.
163
+ */
164
+ function fold(rows) {
165
+ const folded = /* @__PURE__ */ new Map();
166
+ for (const row of rows) {
167
+ const key = JSON.stringify(GROUP.map((column) => row[column]));
168
+ const group = folded.get(key);
169
+ if (!group) {
170
+ folded.set(key, {
171
+ row,
172
+ count: row.count,
173
+ subjects: /* @__PURE__ */ new Set([subjectKey(row)]),
174
+ first: row.firstAt,
175
+ last: row.lastAt
176
+ });
177
+ continue;
178
+ }
179
+ group.count += row.count;
180
+ group.subjects.add(subjectKey(row));
181
+ if (row.firstAt < group.first) group.first = row.firstAt;
182
+ if (row.lastAt > group.last) group.last = row.lastAt;
183
+ }
184
+ return [...folded.values()].map(({ row, count, subjects, first, last }) => ({
185
+ tenant: row.tenant,
186
+ action: row.action,
187
+ method: row.method,
188
+ route: row.route,
189
+ matched: row.matched,
190
+ outcome: row.outcome,
191
+ scope: row.scope,
192
+ count,
193
+ subjects: !row.matched ? null : row.params > 0 ? subjects.size : 0,
194
+ firstAt: first,
195
+ lastAt: last
196
+ })).sort(byGroup);
197
+ }
198
+ /** Read the statement's rows, decoded. */
199
+ async function grouped(db, filter, patterns) {
200
+ return (await controlPlaneReachStatement(db, filter, patterns).execute()).map((row) => ReachStatementRow.parse(row));
201
+ }
202
+ /** Everything one connection's calls reached over a window, one row per tenant, action, method, route and outcome. */
203
+ async function controlPlaneReach(db, filter, patterns) {
204
+ return fold(await grouped(db, filter, patterns));
205
+ }
206
+ /** One route's subjects, and that route's reach rows beside them — from the one statement's per-path rows. */
207
+ async function controlPlaneReachSubjects(db, filter, patterns) {
208
+ const rows = await grouped(db, filter, patterns);
209
+ const subjects = rows.map((row) => {
210
+ const params = row.matched ? routeParams(row.route, row.path) : {};
211
+ return {
212
+ tenant: row.tenant,
213
+ action: row.action,
214
+ method: row.method,
215
+ route: row.route,
216
+ matched: row.matched,
217
+ path: row.path,
218
+ outcome: row.outcome,
219
+ scope: row.scope,
220
+ subjectId: row.matched ? routeSubject(row.route, row.path).subjectId : null,
221
+ params,
222
+ count: row.count,
223
+ firstAt: row.firstAt,
224
+ lastAt: row.lastAt
225
+ };
226
+ });
227
+ return {
228
+ reach: fold(rows),
229
+ subjects
230
+ };
231
+ }
232
+ /** The aggregate's order, as SQLite sorts it: null first, then by code unit. */
233
+ function byGroup(a, b) {
234
+ for (const column of GROUP) {
235
+ const [x, y] = [a[column], b[column]];
236
+ if (x === y) continue;
237
+ if (x === null) return -1;
238
+ if (y === null) return 1;
239
+ return x < y ? -1 : 1;
240
+ }
241
+ return 0;
242
+ }
243
+ //#endregion
244
+ export { ControlPlaneReachRow, ControlPlaneReachSubjectRow, controlPlaneReach, controlPlaneReachStatement, controlPlaneReachSubjects };
@@ -70,6 +70,17 @@ export interface AuditRecorderOptions {
70
70
  onError?: (error: PithyError) => void;
71
71
  /** Retry tuning for the insert. Defaults to retrying `timeout` and `database-busy`. */
72
72
  retry?: D1RetryOptions;
73
+ /**
74
+ * Hand a recorded event to its sinks (#824) — called once the row is written, with its id and action, and
75
+ * nothing else. It never fails the write: whatever it throws goes to {@link onShipError} and the event stands.
76
+ * Omitted when no sink is declared.
77
+ */
78
+ ship?: (event: {
79
+ eventId: string;
80
+ action: string;
81
+ }) => Promise<void>;
82
+ /** Called with whatever {@link ship} threw. The event is already written; only its shipment was lost. */
83
+ onShipError?: (error: unknown) => void;
73
84
  }
74
85
  /**
75
86
  * Record one audit event. Validates the event against the core {@link AuditEvent} seam, stamps
@@ -1 +1 @@
1
- {"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,qCAAqC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAEnE,OAAO,EAAE,KAAK,cAAc,EAAe,MAAM,qCAAqC,CAAC;AACvF,OAAO,EAAa,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAG5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,WAAW;IAC1B,8FAA8F;IAC9F,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,2EAA2E;IAC3E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kFAAkF;IAClF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAKD,mHAAmH;AACnH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,uFAAuF;IACvF,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAWD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE,eAAe,EACtB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAkDf;AAED,iHAAiH;AACjH,wBAAgB,eAAe,CAAC,EAAE,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAE5F"}
1
+ {"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,qCAAqC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAEnE,OAAO,EAAE,KAAK,cAAc,EAAe,MAAM,qCAAqC,CAAC;AACvF,OAAO,EAAa,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAI5E,OAAO,KAAK,EAAE,aAAa,EAAoB,MAAM,eAAe,CAAC;AAGrE;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,WAAW;IAC1B,8FAA8F;IAC9F,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,2EAA2E;IAC3E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kFAAkF;IAClF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAKD,mHAAmH;AACnH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,uFAAuF;IACvF,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,yGAAyG;IACzG,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACxC;AAWD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE,eAAe,EACtB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,IAAI,CAAC,CA+Df;AAED,iHAAiH;AACjH,wBAAgB,eAAe,CAAC,EAAE,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAE5F"}