@pithy-sh/audit 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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
package/src/http/views.ts CHANGED
@@ -1,8 +1,19 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
3
 
4
+ import { InternalError } from "@pithy-sh/core/src/error/pithyError";
5
+ import type { AccessHistoryRow } from "../accessHistory";
4
6
  import type { AuditEventRow } from "../data/auditEvent";
5
- import type { AuditEventDetailView, AuditEventView } from "./responses";
7
+ import type { ControlPlaneReachRow, ControlPlaneReachSubjectRow } from "../reach";
8
+ import type { ControlPlaneUsageRow } from "../usage";
9
+ import type {
10
+ AccessChangeView,
11
+ AuditEventDetailView,
12
+ AuditEventView,
13
+ ControlPlaneReachSubjectView,
14
+ ControlPlaneReachView,
15
+ ControlPlaneUsageView,
16
+ } from "./responses";
6
17
 
7
18
  /**
8
19
  * What a management client is shown of an audit event — decided here, once, rather than by whichever
@@ -78,6 +89,8 @@ export function auditEventView(row: AuditEventRow): AuditEventView {
78
89
  // not personal data — and a client that can filter by tenant but cannot see which tenant a row
79
90
  // carries has to take the filter on trust, which is how a row ends up drawn under the wrong heading.
80
91
  tenant: row.tenant,
92
+ // Its position in its tenant's chain, or null: written before the chain began (#822). The mark, on the listing.
93
+ chainSeq: row.chainSeq,
81
94
  };
82
95
  }
83
96
 
@@ -85,3 +98,112 @@ export function auditEventView(row: AuditEventRow): AuditEventView {
85
98
  export function auditEventDetailView(row: AuditEventRow): AuditEventDetailView {
86
99
  return { ...auditEventView(row), ip: row.ip, userAgent: row.userAgent, metadata: row.metadata };
87
100
  }
101
+
102
+ /**
103
+ * Project one access change (#831) into the wire union, by what changed.
104
+ *
105
+ * The statement already read nothing but the named metadata keys, so this drops nothing personal; what it does is
106
+ * keep each subject's fields to that subject, so a member change never carries a null `scopesBefore` a client could
107
+ * read as a connection that held nothing.
108
+ */
109
+ export function accessChangeView(row: AccessHistoryRow): AccessChangeView {
110
+ const base = {
111
+ eventId: row.eventId,
112
+ occurredAt: row.occurredAt.toISOString(),
113
+ action: row.action,
114
+ actorType: row.actorType,
115
+ actorId: row.actorId,
116
+ actorKind: row.actorKind,
117
+ detail: row.recorded ? ("recorded" as const) : ("not_recorded" as const),
118
+ };
119
+ if (row.subject === "member") {
120
+ return {
121
+ ...base,
122
+ subject: "member",
123
+ organizationId: row.organizationId,
124
+ membershipId: row.membershipId,
125
+ userId: row.userId,
126
+ roleBefore: row.roleBefore,
127
+ roleAfter: row.roleAfter,
128
+ };
129
+ }
130
+ if (row.subject === "connection") {
131
+ return {
132
+ ...base,
133
+ subject: "connection",
134
+ connectionId: row.connectionId,
135
+ connectionKind: row.connectionKind,
136
+ purpose: row.purpose,
137
+ principal: row.principal,
138
+ scopesBefore: row.scopesBefore,
139
+ scopesAfter: row.scopesAfter,
140
+ replacedConnectionId: row.replacedConnectionId,
141
+ };
142
+ }
143
+ if (row.keyChange === null) {
144
+ // The statement answers a change for every key subject, so this is a programming-error guard rather than a
145
+ // runtime path. Guessing one would put a registration in the history that may have been a revocation.
146
+ throw new InternalError({
147
+ message: "Audit could not read a key change.",
148
+ detail: `access-history row for event ${row.eventId} is a key change with no change recorded`,
149
+ });
150
+ }
151
+ return { ...base, subject: "key", connectionId: row.connectionId, keyId: row.keyId, change: row.keyChange };
152
+ }
153
+
154
+ /**
155
+ * Project one reach row (#828). Field for field, with the instants as ISO-8601: the statement already read nothing
156
+ * but the scope, the key, the method and the path out of `metadata`, and the tenant out of the handler's events, so
157
+ * there is nothing here to drop.
158
+ */
159
+ export function controlPlaneReachView(row: ControlPlaneReachRow): ControlPlaneReachView {
160
+ return {
161
+ tenant: row.tenant,
162
+ action: row.action,
163
+ method: row.method,
164
+ route: row.route,
165
+ matched: row.matched,
166
+ outcome: row.outcome,
167
+ scope: row.scope,
168
+ count: row.count,
169
+ subjects: row.subjects,
170
+ firstAt: row.firstAt.toISOString(),
171
+ lastAt: row.lastAt.toISOString(),
172
+ };
173
+ }
174
+
175
+ /** Project one subject row (#828), field for field, the same way — never a spread a new field would ride out on. */
176
+ export function controlPlaneReachSubjectView(row: ControlPlaneReachSubjectRow): ControlPlaneReachSubjectView {
177
+ return {
178
+ tenant: row.tenant,
179
+ action: row.action,
180
+ method: row.method,
181
+ route: row.route,
182
+ matched: row.matched,
183
+ path: row.path,
184
+ outcome: row.outcome,
185
+ scope: row.scope,
186
+ subjectId: row.subjectId,
187
+ params: { ...row.params },
188
+ count: row.count,
189
+ firstAt: row.firstAt.toISOString(),
190
+ lastAt: row.lastAt.toISOString(),
191
+ };
192
+ }
193
+
194
+ /**
195
+ * Project one usage row (#812). Field for field, with the instants as ISO-8601: the aggregate already read nothing but
196
+ * the scope, the key, and the last allowed call's method and path out of `metadata`, so there is nothing here to drop.
197
+ */
198
+ export function controlPlaneUsageView(row: ControlPlaneUsageRow): ControlPlaneUsageView {
199
+ return {
200
+ scope: row.scope,
201
+ keyId: row.keyId,
202
+ allowed: row.allowed,
203
+ denied: row.denied,
204
+ lastAllowedAt: row.lastAllowedAt?.toISOString() ?? null,
205
+ lastAllowedMethod: row.lastAllowedMethod,
206
+ lastAllowedPath: row.lastAllowedPath,
207
+ lastDeniedAt: row.lastDeniedAt?.toISOString() ?? null,
208
+ };
209
+ }
@@ -0,0 +1,35 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+
4
+ import type { Kysely } from "kysely";
5
+ import type { Migration } from "kysely/migration";
6
+
7
+ /**
8
+ * One connection's calls over a window — `#812`.
9
+ *
10
+ * `GET {audit}/control-plane/usage` reads the `controlplane/call_allowed` and `controlplane/call_denied` rows of one
11
+ * connection between two instants, and groups them by scope and key. None of 0001's indexes serves that:
12
+ * `pithyAuditEventsResourceIdx` finds the connection's rows but not by action or time, and `pithyAuditEventsActionIdx`
13
+ * finds every call of every connection. On the table a dashboard connection appends thousands of rows to a day, the
14
+ * difference is a range read against a scan.
15
+ *
16
+ * **In this column order, and it is the query's.** `action` first, because the read names two actions with `IN` and
17
+ * SQLite walks one range per value. `resourceId` second, an equality inside each. `occurredAt` last, so the window
18
+ * is a bounded range rather than a filter over every row the connection ever wrote. `resourceType` is left out: a
19
+ * connection id is a UUID, so `resourceId` is already selective, and the type is checked against the row it finds.
20
+ *
21
+ * **Appended, never folded into `0001`.** The audit capability has shipped, so its table is history.
22
+ */
23
+ export const audit_0003_call_index: Migration = {
24
+ up: async (db: Kysely<unknown>): Promise<void> => {
25
+ await db.schema
26
+ .createIndex("pithyAuditEventsCallIdx")
27
+ .on("pithyAuditEvents")
28
+ .columns(["action", "resourceId", "occurredAt"])
29
+ .execute();
30
+ },
31
+
32
+ down: async (db: Kysely<unknown>): Promise<void> => {
33
+ await db.schema.dropIndex("pithyAuditEventsCallIdx").execute();
34
+ },
35
+ };
@@ -0,0 +1,26 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+
4
+ import type { Kysely } from "kysely";
5
+ import type { Migration } from "kysely/migration";
6
+
7
+ /**
8
+ * The events one request wrote — `#828`.
9
+ *
10
+ * `GET {audit}/control-plane/reach` answers whose data a credential reached, and the gate's own
11
+ * `controlplane/call_allowed` row cannot say: it is written before the handler runs, so before any tenant is
12
+ * resolved. The handler's events carry the tenant, and the request id (`cf-ray`) is what ties them to the call. The
13
+ * reach statement finds them by it, once per call in the window, so without this index every call is a scan of the
14
+ * trail.
15
+ *
16
+ * **Appended, never folded into `0001`.** The audit capability has shipped, so its table is history.
17
+ */
18
+ export const audit_0004_request_index: Migration = {
19
+ up: async (db: Kysely<unknown>): Promise<void> => {
20
+ await db.schema.createIndex("pithyAuditEventsRequestIdx").on("pithyAuditEvents").column("requestId").execute();
21
+ },
22
+
23
+ down: async (db: Kysely<unknown>): Promise<void> => {
24
+ await db.schema.dropIndex("pithyAuditEventsRequestIdx").execute();
25
+ },
26
+ };
@@ -0,0 +1,56 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+
4
+ import { type Kysely, sql } from "kysely";
5
+ import type { Migration } from "kysely/migration";
6
+
7
+ /**
8
+ * The hash chain — `#822`.
9
+ *
10
+ * Four columns, every one nullable and none back-filled. `chainSeq` is an event's 1-based position in its tenant's
11
+ * chain, `chainPrev` the hash of the event before it, `chainHash` its own hash over the canonical serialization
12
+ * (`@pithy-sh/core/src/audit/chain`), and `chainSalt` the per-event salt its IP, user-agent and metadata are
13
+ * committed under.
14
+ *
15
+ * **A row written before this migration keeps all four null, and that is its mark: before the chain.** Asserting a
16
+ * chain over rows nobody checked when they were written would be a claim, not evidence, so nothing here computes
17
+ * one.
18
+ *
19
+ * **Two partial unique indexes, one per kind of chain.** The tenant column is nullable and SQLite treats nulls as
20
+ * distinct in a unique index, so one index on `(tenant, chainSeq)` would let the untenanted chain hold two events
21
+ * at one position. Splitting by `tenant is null` closes that, and gives the verify walk an index in chain order for
22
+ * either kind. The recorder's append is already one compare-and-set statement; these are the backstop under it.
23
+ *
24
+ * **Appended, never folded into `0001`.** The audit capability has shipped, so its table is history.
25
+ */
26
+ export const audit_0005_chain: Migration = {
27
+ up: async (db: Kysely<unknown>): Promise<void> => {
28
+ await db.schema.alterTable("pithyAuditEvents").addColumn("chainSeq", "integer").execute();
29
+ await db.schema.alterTable("pithyAuditEvents").addColumn("chainPrev", "text").execute();
30
+ await db.schema.alterTable("pithyAuditEvents").addColumn("chainHash", "text").execute();
31
+ await db.schema.alterTable("pithyAuditEvents").addColumn("chainSalt", "text").execute();
32
+ await db.schema
33
+ .createIndex("pithyAuditEventsTenantChainIdx")
34
+ .on("pithyAuditEvents")
35
+ .columns(["tenant", "chainSeq"])
36
+ .unique()
37
+ .where(sql.ref("tenant"), "is not", null)
38
+ .execute();
39
+ await db.schema
40
+ .createIndex("pithyAuditEventsUntenantedChainIdx")
41
+ .on("pithyAuditEvents")
42
+ .column("chainSeq")
43
+ .unique()
44
+ .where(sql.ref("tenant"), "is", null)
45
+ .execute();
46
+ },
47
+
48
+ down: async (db: Kysely<unknown>): Promise<void> => {
49
+ await db.schema.dropIndex("pithyAuditEventsUntenantedChainIdx").execute();
50
+ await db.schema.dropIndex("pithyAuditEventsTenantChainIdx").execute();
51
+ await db.schema.alterTable("pithyAuditEvents").dropColumn("chainSalt").execute();
52
+ await db.schema.alterTable("pithyAuditEvents").dropColumn("chainHash").execute();
53
+ await db.schema.alterTable("pithyAuditEvents").dropColumn("chainPrev").execute();
54
+ await db.schema.alterTable("pithyAuditEvents").dropColumn("chainSeq").execute();
55
+ },
56
+ };
@@ -0,0 +1,28 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+
4
+ import { type Kysely, sql } from "kysely";
5
+ import type { Migration } from "kysely/migration";
6
+
7
+ /**
8
+ * Shipping's delivery state — `#824`.
9
+ *
10
+ * One table, `pithy_audit_sinks`, one row per declared sink: what the manifest's health keys report. Nothing in it
11
+ * is the trail, and nothing in the trail changes. **Appended, never folded into `0001`**: audit has shipped.
12
+ */
13
+ export const audit_0006_sinks: Migration = {
14
+ up: async (db: Kysely<unknown>): Promise<void> => {
15
+ await db.schema
16
+ .createTable("pithyAuditSinks")
17
+ .addColumn("sink", "text", (col) => col.primaryKey())
18
+ .addColumn("lastDeliveredAt", "integer")
19
+ .addColumn("lastFailedAt", "integer")
20
+ .addColumn("retrying", "integer", (col) => col.notNull().defaultTo(sql`0`))
21
+ .addColumn("deadLettered", "integer", (col) => col.notNull().defaultTo(sql`0`))
22
+ .execute();
23
+ },
24
+
25
+ down: async (db: Kysely<unknown>): Promise<void> => {
26
+ await db.schema.dropTable("pithyAuditSinks").execute();
27
+ },
28
+ };
@@ -0,0 +1,60 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+
4
+ import type { FeatureIdentity } from "@pithy-sh/core/src/naming/feature";
5
+ import { environmentScope } from "@pithy-sh/core/src/naming/provisionScope";
6
+ import { hostWorkflowsFor, resolveWorkflowHost, type WorkflowHostTemplate } from "@pithy-sh/core/src/workflow/host";
7
+ import { AUDIT_CHECKPOINT_BINDING } from "../chain/checkpoint";
8
+ import { AUDIT_CAPABILITY, auditWorkflowRegistry } from "../workflows/specs";
9
+
10
+ /**
11
+ * Resolve the checkpoint host's committed `wrangler.jsonc` template into one environment's standalone config
12
+ * (#822). Thin over core's {@link resolveWorkflowHost}: this file owns only which database the host reads, which
13
+ * bucket it writes, and the Workflow names derived from audit's own specs.
14
+ */
15
+
16
+ /**
17
+ * The checkpoint bucket's name in a declared environment — **the name `pithy provision` gives the
18
+ * `AUDIT_CHECKPOINTS` binding**, read through the very function it composes it with, so the host and the app
19
+ * Worker cannot bind two different buckets.
20
+ */
21
+ export function auditCheckpointBucketName(project: string, env: string): string {
22
+ return environmentScope(project, env).resource(AUDIT_CHECKPOINT_BINDING, "r2", {});
23
+ }
24
+
25
+ /** The resolved resource ids and names for one environment's checkpoint host. */
26
+ export interface AuditConfigParams {
27
+ /** The project name, from `requireProjectName` and never guessed. */
28
+ project: string;
29
+ /** The target environment. */
30
+ env: string;
31
+ /** The feature this host serves, when it serves one (#643). */
32
+ feature?: FeatureIdentity;
33
+ /** The audit database's id — the D1 behind the binding `audit({ database })` names. */
34
+ auditDatabaseId: string;
35
+ /** The checkpoint bucket's name. */
36
+ bucketName: string;
37
+ }
38
+
39
+ /** Fill the template for one environment. */
40
+ export function resolveAuditConfig(template: WorkflowHostTemplate, params: AuditConfigParams): WorkflowHostTemplate {
41
+ const { project, env, feature } = params;
42
+ const derived = hostWorkflowsFor(auditWorkflowRegistry, {
43
+ project,
44
+ capability: AUDIT_CAPABILITY,
45
+ env,
46
+ ...(feature ? { feature } : {}),
47
+ });
48
+ const resolved = resolveWorkflowHost(template, {
49
+ project,
50
+ capability: AUDIT_CAPABILITY,
51
+ env,
52
+ ...(feature ? { feature } : {}),
53
+ // The host always reads it as `DB`; which database that is follows the adopter's `audit({ database })`.
54
+ databaseIds: { DB: params.auditDatabaseId },
55
+ r2BucketNames: { [AUDIT_CHECKPOINT_BINDING]: params.bucketName },
56
+ workflows: derived.workflows,
57
+ });
58
+ resolved.triggers = derived.crons.length > 0 ? { crons: derived.crons } : undefined;
59
+ return resolved;
60
+ }
@@ -0,0 +1,39 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+
4
+ import { personRowsExport } from "@pithy-sh/core/src/capability/personRows";
5
+ import type { RetainingPurgeContribution } from "@pithy-sh/core/src/capability/purge";
6
+ import { AuditEventRow } from "../data/auditEvent";
7
+
8
+ /**
9
+ * What a person's purge means for `@pithy-sh/audit` (#814): **nothing is erased, and the export says so and why.**
10
+ *
11
+ * The audit trail is the record of who acted — who signed in, who changed a role, who deleted an organization — and
12
+ * it is what a security review or a dispute is read against. A trail that forgot an actor on request would answer
13
+ * neither, so this contribution **retains**: the purge records the step as retained with the basis below and erases
14
+ * no event, and the export answers for every event where the person is the actor.
15
+ *
16
+ * Events are written through `emit`, whose metadata is held to `Loggable` — no token, no secret reaches a row — so
17
+ * the export carries each event whole.
18
+ */
19
+
20
+ /** The one sentence the purge records with this step. */
21
+ export const AUDIT_PURGE_SUMMARY = "Keeps every audit event where the user is the actor.";
22
+
23
+ /** Why, in the sentence the person is told. */
24
+ export const AUDIT_RETENTION_BASIS =
25
+ "Kept as the record of who did what, which a security review or a dispute is read against.";
26
+
27
+ /** The user contribution `audit()` declares, over the D1 binding its config names. */
28
+ export function auditUserPurge(database = "DB"): RetainingPurgeContribution {
29
+ return {
30
+ subject: "user",
31
+ summary: AUDIT_PURGE_SUMMARY,
32
+ retain: { basis: AUDIT_RETENTION_BASIS },
33
+ export: personRowsExport({
34
+ capability: "audit",
35
+ database,
36
+ tables: [{ table: "pithyAuditEvents", schema: AuditEventRow, columns: ["actorId"], as: "events", orderBy: "id" }],
37
+ }),
38
+ };
39
+ }