@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,110 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { AuditWriteFailedError } from "../error/errors.js";
4
+ import { chainFieldsOf, readChainHead, whereChain } from "./rows.js";
5
+ import { chainHash, newChainSalt } from "@pithy-sh/core/src/audit/chain";
6
+ import { withD1Retry } from "@pithy-sh/core/src/data/withD1Retry";
7
+ //#region src/chain/append.ts
8
+ /**
9
+ * How long one append keeps contending for its chain's next position before it gives up, in ms. Every lost race
10
+ * means another event landed, so a burst of appends to one tenant all land, one position at a time: the bound is on
11
+ * time, not on how many appends overtake this one, so no burst size drops an event. It exists only to end a request
12
+ * that a chain somebody is writing wrong would hold forever.
13
+ */
14
+ const CHAIN_APPEND_DEADLINE_MS = 3e4;
15
+ /**
16
+ * How many lost races in a row may find the head where it was. A race is lost because an event took the position,
17
+ * so the head moves; one that does not move is a chain this append cannot join, and retrying it is spinning.
18
+ */
19
+ const CHAIN_APPEND_STALLS = 3;
20
+ /** The longest one back-off after a lost race waits, in ms. Each wait is a random fraction of a growing ceiling. */
21
+ const BACKOFF_CEILING_MS = 50;
22
+ /** Wait a random time under a ceiling that doubles with each lost race, so contenders stop retrying in lockstep. */
23
+ async function backOff(lost, ceilingMs) {
24
+ const ceiling = Math.min(ceilingMs, 2 ** Math.min(lost, 10));
25
+ if (ceiling <= 0) return;
26
+ await new Promise((resolve) => setTimeout(resolve, Math.random() * ceiling));
27
+ }
28
+ /**
29
+ * **Append one event to its tenant's chain, without forking it (#822).**
30
+ *
31
+ * Read the head, compute this event's link and hash, then insert in **one statement that refuses when the head has
32
+ * moved**: `INSERT … SELECT … WHERE NOT EXISTS (an event at or past this position in this chain)`. D1 runs one
33
+ * statement at a time, so the check and the write cannot be split by another append. A loser inserts nothing,
34
+ * backs off a random moment, re-reads the head and tries again, so two concurrent appends never share a position
35
+ * and never name the same predecessor, and a burst of them all lands. The partial unique indexes from
36
+ * `audit_0005_chain` sit under it as a backstop.
37
+ *
38
+ * `withD1Retry` still rides out a transient fault on the insert. A retry after a write that landed inserts nothing
39
+ * here rather than tripping the unique index, so it is told apart from a lost race by asking whether the event's
40
+ * own id is already in the table.
41
+ */
42
+ async function appendChained(db, record, options = {}) {
43
+ const tenant = record.tenant ?? null;
44
+ const deadline = Date.now() + (options.deadlineMs ?? 3e4);
45
+ const ceilingMs = options.backoffCeilingMs ?? BACKOFF_CEILING_MS;
46
+ const salt = newChainSalt();
47
+ const fields = await chainFieldsOf({
48
+ eventId: record.eventId,
49
+ occurredAt: record.occurredAt,
50
+ action: record.action,
51
+ outcome: record.outcome,
52
+ severity: record.severity ?? "info",
53
+ actorType: record.actorType,
54
+ actorId: record.actorId ?? null,
55
+ actorKind: record.actorKind ?? null,
56
+ sessionId: record.sessionId ?? null,
57
+ resourceType: record.resourceType ?? null,
58
+ resourceId: record.resourceId ?? null,
59
+ requestId: record.requestId ?? null,
60
+ tenant,
61
+ project: record.project ?? null,
62
+ environment: record.environment ?? null,
63
+ worker: record.worker ?? null,
64
+ version: record.version ?? null,
65
+ ip: record.ip ?? null,
66
+ userAgent: record.userAgent ?? null,
67
+ metadata: record.metadata ?? null,
68
+ chainSalt: salt
69
+ }, salt);
70
+ let lost = 0;
71
+ let stalls = 0;
72
+ let lastSeq = null;
73
+ for (;;) {
74
+ const head = await readChainHead(db, tenant);
75
+ const seq = (head?.seq ?? 0) + 1;
76
+ if (lastSeq !== null) {
77
+ stalls = seq > lastSeq ? 0 : stalls + 1;
78
+ if (stalls >= 3) throw new AuditWriteFailedError({ detail: `The ${chainName(tenant)} chain refused position ${seq} 3 times without moving.` });
79
+ }
80
+ lastSeq = seq;
81
+ const prev = head?.hash ?? null;
82
+ const hash = await chainHash({
83
+ seq,
84
+ prev
85
+ }, fields);
86
+ const row = {
87
+ ...record,
88
+ tenant,
89
+ chainSeq: seq,
90
+ chainPrev: prev,
91
+ chainHash: hash,
92
+ chainSalt: salt
93
+ };
94
+ const columns = Object.keys(row);
95
+ const result = await withD1Retry(() => db.insertInto("pithyAuditEvents").columns(columns).expression(db.selectNoFrom((eb) => columns.map((column) => eb.val(row[column]).as(column))).where(({ not, exists, selectFrom }) => not(exists(whereChain(selectFrom("pithyAuditEvents").select("id").where("chainSeq", ">=", seq), tenant))))).executeTakeFirst(), options.retry);
96
+ if (Number(result?.numInsertedOrUpdatedRows ?? 0n) > 0) return;
97
+ if (await db.selectFrom("pithyAuditEvents").select("id").where("eventId", "=", record.eventId).executeTakeFirst()) return;
98
+ if (Date.now() >= deadline) throw new AuditWriteFailedError({ detail: `The ${chainName(tenant)} chain moved under one append for ${options.deadlineMs ?? 3e4}ms.` });
99
+ await backOff(++lost, ceilingMs);
100
+ }
101
+ }
102
+ function chainName(tenant) {
103
+ return tenant === null ? "untenanted" : `"${tenant}"`;
104
+ }
105
+ /** Whether a failed write failed because the database has not taken `audit_0005_chain` yet. */
106
+ function isUnmigratedChain(error) {
107
+ return error instanceof Error && /(no column named|no such column:) chain_(seq|prev|hash|salt)/.test(error.message);
108
+ }
109
+ //#endregion
110
+ export { CHAIN_APPEND_DEADLINE_MS, CHAIN_APPEND_STALLS, appendChained, isUnmigratedChain };
@@ -0,0 +1,70 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import type { R2Bucket } from "@cloudflare/workers-types";
4
+ import { AuditCheckpoint } from "@pithy-sh/core/src/audit/chain";
5
+ import type { AuditDatabase } from "../data/tables";
6
+ /**
7
+ * **Checkpoints: each chain's length and head, written outside the database (#822).**
8
+ *
9
+ * A chain alone proves no row was changed *unless the whole chain was recomputed* — and anybody with write access to
10
+ * the D1 can recompute it. So on a schedule each tenant's head and count go to the checkpoint bucket, one object per
11
+ * checkpoint, never overwritten: the key carries the count, and the write is conditional on the key being new. A
12
+ * rewritten chain then disagrees with a checkpoint it cannot reach, and a truncated one ends before a checkpoint
13
+ * says it did.
14
+ *
15
+ * **Object lock is what makes the bucket evidence.** Without it whoever can write the bucket can rewrite the
16
+ * checkpoints too. The lock is a bucket rule (`AUDIT_CHECKPOINT_LOCK_PREFIX`, indefinite retention) set on the
17
+ * account, and `pithy doctor` says whether it is in force — the Worker cannot see it through its binding.
18
+ */
19
+ /** The binding the checkpoint bucket is bound as, in the app Worker and in the checkpoint host. */
20
+ export declare const AUDIT_CHECKPOINT_BINDING = "AUDIT_CHECKPOINTS";
21
+ /** Every checkpoint object lives under this prefix, and the lock rule names it. */
22
+ export declare const AUDIT_CHECKPOINT_LOCK_PREFIX = "checkpoints/";
23
+ /** The key prefix of one chain's checkpoints. A tenant id is encoded, so no id can reach another's prefix. */
24
+ export declare function checkpointPrefix(tenant: string | null): string;
25
+ /** The key of one checkpoint: its chain's prefix and its count. */
26
+ export declare function checkpointKey(tenant: string | null, count: number): string;
27
+ /** What one checkpoint run did. */
28
+ export interface CheckpointRun {
29
+ /** Chains whose head was new, and so got a checkpoint. */
30
+ written: number;
31
+ /** Chains whose head was already checkpointed. */
32
+ unchanged: number;
33
+ }
34
+ /**
35
+ * Write a checkpoint for every chain whose head moved since its last one. Idempotent: a head already checkpointed
36
+ * is a key that exists, and the conditional write refuses to replace it.
37
+ */
38
+ export declare function writeCheckpoints(db: AuditDatabase, bucket: R2Bucket, now: Date): Promise<CheckpointRun>;
39
+ /** Which of a chain's checkpoints a read wants: those within a range of positions, and the latest overall. */
40
+ export interface CheckpointRange {
41
+ /** The first position the read covers. */
42
+ fromCount: number;
43
+ /** The last position the read covers, or omitted for the chain's head. */
44
+ throughCount?: number;
45
+ }
46
+ /** The checkpoint keys one chain held when it was listed: a snapshot, read before the chain it is held against. */
47
+ export interface CheckpointListing {
48
+ /** The chain the keys are under. */
49
+ tenant: string | null;
50
+ /** Each checkpoint's key and the count it names. */
51
+ entries: {
52
+ key: string;
53
+ count: number;
54
+ }[];
55
+ }
56
+ /**
57
+ * List one chain's checkpoint keys. A verify or an export lists them **before** it reads the chain's head or rows, so
58
+ * a checkpoint written while the read runs counts at most the head the read then sees. Listed after, it could count
59
+ * an event the read never reached, and an intact chain would read as truncated.
60
+ */
61
+ export declare function listCheckpoints(bucket: R2Bucket, tenant: string | null): Promise<CheckpointListing>;
62
+ /**
63
+ * Every checkpoint of one chain whose count falls in the range, and the latest one whatever its count — the one a
64
+ * truncated tail is caught against. An object that does not parse, or whose body names another chain or count than
65
+ * its key, is skipped: a checkpoint is trusted for what it says only where it says it.
66
+ *
67
+ * Pass a `listing` taken before the chain was read; without one the keys are listed now.
68
+ */
69
+ export declare function readCheckpoints(bucket: R2Bucket, tenant: string | null, range: CheckpointRange, listing?: CheckpointListing): Promise<AuditCheckpoint[]>;
70
+ //# sourceMappingURL=checkpoint.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../src/chain/checkpoint.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAA2B,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAC1F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD;;;;;;;;;;;;GAYG;AAEH,mGAAmG;AACnG,eAAO,MAAM,wBAAwB,sBAAsB,CAAC;AAE5D,mFAAmF;AACnF,eAAO,MAAM,4BAA4B,iBAAiB,CAAC;AAK3D,8GAA8G;AAC9G,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAI9D;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1E;AAQD,mCAAmC;AACnC,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,CAiC7G;AAED,8GAA8G;AAC9G,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,mHAAmH;AACnH,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,oDAAoD;IACpD,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAazG;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,QAAQ,EAChB,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,KAAK,EAAE,eAAe,EACtB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,eAAe,EAAE,CAAC,CA2B5B"}
@@ -0,0 +1,133 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { readChainLink } from "./rows.js";
4
+ import { AUDIT_CHECKPOINT_FORMAT, AuditCheckpoint } from "@pithy-sh/core/src/audit/chain";
5
+ //#region src/chain/checkpoint.ts
6
+ /**
7
+ * **Checkpoints: each chain's length and head, written outside the database (#822).**
8
+ *
9
+ * A chain alone proves no row was changed *unless the whole chain was recomputed* — and anybody with write access to
10
+ * the D1 can recompute it. So on a schedule each tenant's head and count go to the checkpoint bucket, one object per
11
+ * checkpoint, never overwritten: the key carries the count, and the write is conditional on the key being new. A
12
+ * rewritten chain then disagrees with a checkpoint it cannot reach, and a truncated one ends before a checkpoint
13
+ * says it did.
14
+ *
15
+ * **Object lock is what makes the bucket evidence.** Without it whoever can write the bucket can rewrite the
16
+ * checkpoints too. The lock is a bucket rule (`AUDIT_CHECKPOINT_LOCK_PREFIX`, indefinite retention) set on the
17
+ * account, and `pithy doctor` says whether it is in force — the Worker cannot see it through its binding.
18
+ */
19
+ /** The binding the checkpoint bucket is bound as, in the app Worker and in the checkpoint host. */
20
+ const AUDIT_CHECKPOINT_BINDING = "AUDIT_CHECKPOINTS";
21
+ /** Every checkpoint object lives under this prefix, and the lock rule names it. */
22
+ const AUDIT_CHECKPOINT_LOCK_PREFIX = "checkpoints/";
23
+ /** The zero-padded width of a count in a key, so keys list in count order. */
24
+ const COUNT_WIDTH = 15;
25
+ /** The key prefix of one chain's checkpoints. A tenant id is encoded, so no id can reach another's prefix. */
26
+ function checkpointPrefix(tenant) {
27
+ return tenant === null ? `${AUDIT_CHECKPOINT_LOCK_PREFIX}untenanted/` : `${AUDIT_CHECKPOINT_LOCK_PREFIX}tenant/${encodeURIComponent(tenant)}/`;
28
+ }
29
+ /** The key of one checkpoint: its chain's prefix and its count. */
30
+ function checkpointKey(tenant, count) {
31
+ return `${checkpointPrefix(tenant)}${String(count).padStart(COUNT_WIDTH, "0")}.json`;
32
+ }
33
+ /** The count a key names, or null when the key is not a checkpoint's. */
34
+ function countOf(key, prefix) {
35
+ const match = /^(\d+)\.json$/.exec(key.slice(prefix.length));
36
+ return match ? Number(match[1]) : null;
37
+ }
38
+ /**
39
+ * Write a checkpoint for every chain whose head moved since its last one. Idempotent: a head already checkpointed
40
+ * is a key that exists, and the conditional write refuses to replace it.
41
+ */
42
+ async function writeCheckpoints(db, bucket, now) {
43
+ const heads = await db.selectFrom("pithyAuditEvents").select(["tenant", (eb) => eb.fn.max("chainSeq").as("count")]).where("chainSeq", "is not", null).groupBy("tenant").execute();
44
+ const run = {
45
+ written: 0,
46
+ unchanged: 0
47
+ };
48
+ for (const { tenant, count } of heads) {
49
+ if (typeof count !== "number") continue;
50
+ const link = await readChainLink(db, tenant, count);
51
+ if (!link) continue;
52
+ const key = checkpointKey(tenant, link.seq);
53
+ if (await bucket.head(key)) {
54
+ run.unchanged++;
55
+ continue;
56
+ }
57
+ const checkpoint = {
58
+ format: AUDIT_CHECKPOINT_FORMAT,
59
+ tenant,
60
+ count: link.seq,
61
+ head: link.hash,
62
+ takenAt: now.toISOString()
63
+ };
64
+ if (await bucket.put(key, JSON.stringify(AuditCheckpoint.parse(checkpoint)), {
65
+ onlyIf: { etagDoesNotMatch: "*" },
66
+ httpMetadata: { contentType: "application/json" }
67
+ })) run.written++;
68
+ else run.unchanged++;
69
+ }
70
+ return run;
71
+ }
72
+ /**
73
+ * List one chain's checkpoint keys. A verify or an export lists them **before** it reads the chain's head or rows, so
74
+ * a checkpoint written while the read runs counts at most the head the read then sees. Listed after, it could count
75
+ * an event the read never reached, and an intact chain would read as truncated.
76
+ */
77
+ async function listCheckpoints(bucket, tenant) {
78
+ const prefix = checkpointPrefix(tenant);
79
+ const entries = [];
80
+ let cursor;
81
+ do {
82
+ const page = await bucket.list({
83
+ prefix,
84
+ ...cursor ? { cursor } : {}
85
+ });
86
+ for (const object of page.objects) {
87
+ const count = countOf(object.key, prefix);
88
+ if (count !== null) entries.push({
89
+ key: object.key,
90
+ count
91
+ });
92
+ }
93
+ cursor = page.truncated ? page.cursor : void 0;
94
+ } while (cursor);
95
+ return {
96
+ tenant,
97
+ entries
98
+ };
99
+ }
100
+ /**
101
+ * Every checkpoint of one chain whose count falls in the range, and the latest one whatever its count — the one a
102
+ * truncated tail is caught against. An object that does not parse, or whose body names another chain or count than
103
+ * its key, is skipped: a checkpoint is trusted for what it says only where it says it.
104
+ *
105
+ * Pass a `listing` taken before the chain was read; without one the keys are listed now.
106
+ */
107
+ async function readCheckpoints(bucket, tenant, range, listing) {
108
+ const { entries } = listing && listing.tenant === tenant ? listing : await listCheckpoints(bucket, tenant);
109
+ const wanted = [];
110
+ let latest = null;
111
+ for (const entry of entries) {
112
+ if (!latest || entry.count > latest.count) latest = entry;
113
+ if (entry.count >= range.fromCount && (range.throughCount === void 0 || entry.count <= range.throughCount)) wanted.push(entry);
114
+ }
115
+ if (latest && !wanted.some((entry) => entry.key === latest?.key)) wanted.push(latest);
116
+ const checkpoints = [];
117
+ for (const { key, count } of wanted.sort((a, b) => a.count - b.count)) {
118
+ const object = await bucket.get(key);
119
+ if (!object) continue;
120
+ let body;
121
+ try {
122
+ body = JSON.parse(await object.text());
123
+ } catch {
124
+ continue;
125
+ }
126
+ const parsed = AuditCheckpoint.safeParse(body);
127
+ if (!parsed.success || parsed.data.tenant !== tenant || parsed.data.count !== count) continue;
128
+ checkpoints.push(parsed.data);
129
+ }
130
+ return checkpoints;
131
+ }
132
+ //#endregion
133
+ export { AUDIT_CHECKPOINT_BINDING, AUDIT_CHECKPOINT_LOCK_PREFIX, checkpointKey, checkpointPrefix, listCheckpoints, readCheckpoints, writeCheckpoints };
@@ -0,0 +1,15 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { type CapabilitySettings } from "@pithy-sh/core/src/capability/settings";
4
+ /**
5
+ * **`pithy doctor`'s line on the checkpoint bucket's object lock (#822).**
6
+ *
7
+ * A checkpoint is evidence only while nothing can replace it. The Worker cannot tell through its binding whether
8
+ * the bucket is locked, so doctor asks the account, per deployed environment: a bucket with no indefinite lock over
9
+ * the checkpoints is a finding, and so is a bucket that does not exist yet — the chain then has nothing outside the
10
+ * database to be held to. A bucket that is locked says nothing, which is doctor's way of saying it is in force.
11
+ *
12
+ * `dev` is never asked: a developer's checkpoints are a local Miniflare bucket, and no lock means anything there.
13
+ */
14
+ export declare function checkpointLockCheck(): CapabilitySettings;
15
+ //# sourceMappingURL=lockCheck.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"lockCheck.d.ts","sourceRoot":"","sources":["../../src/chain/lockCheck.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,kBAAkB,EAIxB,MAAM,wCAAwC,CAAC;AAOhD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,kBAAkB,CA8CxD"}
@@ -0,0 +1,75 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { AUDIT_CHECKPOINT_BINDING, AUDIT_CHECKPOINT_LOCK_PREFIX } from "./checkpoint.js";
4
+ import { auditCheckpointBucketName } from "../provision/resolveAuditConfig.js";
5
+ import { InternalError } from "@pithy-sh/core/src/error/pithyError";
6
+ import { SettingsAccountIncomplete } from "@pithy-sh/core/src/capability/settings";
7
+ import { remedy } from "@pithy-sh/core/src/cli/command";
8
+ import { LOCAL_ENVIRONMENT } from "@pithy-sh/core/src/naming/environment";
9
+ //#region src/chain/lockCheck.ts
10
+ /**
11
+ * **`pithy doctor`'s line on the checkpoint bucket's object lock (#822).**
12
+ *
13
+ * A checkpoint is evidence only while nothing can replace it. The Worker cannot tell through its binding whether
14
+ * the bucket is locked, so doctor asks the account, per deployed environment: a bucket with no indefinite lock over
15
+ * the checkpoints is a finding, and so is a bucket that does not exist yet — the chain then has nothing outside the
16
+ * database to be held to. A bucket that is locked says nothing, which is doctor's way of saying it is in force.
17
+ *
18
+ * `dev` is never asked: a developer's checkpoints are a local Miniflare bucket, and no lock means anything there.
19
+ */
20
+ function checkpointLockCheck() {
21
+ return {
22
+ local: () => [],
23
+ async account(context) {
24
+ const findings = [];
25
+ const unanswered = [];
26
+ for (const { name: environment } of context.environments) {
27
+ if (environment === LOCAL_ENVIRONMENT) continue;
28
+ const bucket = auditCheckpointBucketName(context.project, environment);
29
+ try {
30
+ const ask = context.account.r2BucketLock;
31
+ if (!ask) throw new InternalError({
32
+ message: "This doctor cannot ask whether a bucket is locked.",
33
+ detail: "SettingsAccountReader.r2BucketLock is absent."
34
+ });
35
+ const state = await ask.call(context.account, {
36
+ bucket,
37
+ prefix: AUDIT_CHECKPOINT_LOCK_PREFIX
38
+ });
39
+ if (state === "locked") continue;
40
+ if (state === "missing") {
41
+ const provision = remedy("provision", { flags: {
42
+ "--env": environment,
43
+ "--yes": true
44
+ } });
45
+ findings.push({
46
+ setting: `${AUDIT_CHECKPOINT_BINDING} bucket`,
47
+ environment,
48
+ problem: `The checkpoint bucket ${bucket} does not exist, so the audit chain is held to nothing outside the database.`,
49
+ action: provision.say((command) => `Run ${command} to create it, then lock it.`),
50
+ ...provision.fix === void 0 ? {} : { fix: String(provision.fix) }
51
+ });
52
+ continue;
53
+ }
54
+ const lock = remedy("audit lock", { flags: { "--env": environment } });
55
+ findings.push({
56
+ setting: `${AUDIT_CHECKPOINT_BINDING} object lock`,
57
+ environment,
58
+ problem: `Object lock is not in force on ${bucket}. Whoever can write the bucket can rewrite the checkpoints the audit chain is verified against.`,
59
+ action: lock.say((command) => `Run ${command} to lock the checkpoints indefinitely.`),
60
+ ...lock.fix === void 0 ? {} : { fix: String(lock.fix) }
61
+ });
62
+ } catch (cause) {
63
+ unanswered.push({
64
+ environment,
65
+ cause
66
+ });
67
+ }
68
+ }
69
+ if (unanswered.length > 0) throw new SettingsAccountIncomplete(findings, unanswered);
70
+ return findings;
71
+ }
72
+ };
73
+ }
74
+ //#endregion
75
+ export { checkpointLockCheck };
@@ -0,0 +1,84 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import type { R2Bucket } from "@cloudflare/workers-types";
4
+ import { type EffectiveRetention } from "@pithy-sh/core/src/retention/policy";
5
+ import type { AuditDatabase } from "../data/tables";
6
+ import { type ChainRow } from "./rows";
7
+ /**
8
+ * **The retention prune: audit events past their window, removed without breaking the chain.**
9
+ *
10
+ * The Worker's `retention.audit` block says how long each action is kept. An event past its window is removed, and
11
+ * because every chained event names the one before it, a removed run leaves a tombstone in the checkpoint bucket
12
+ * first: the run's positions, the link before it, and the hashes at either end. A verify bridges the gap with it and
13
+ * reads the chain as whole. Without a checkpoint bucket nothing chained is pruned, since nothing could vouch for the
14
+ * gap.
15
+ *
16
+ * - **Runs, not single events.** Windows differ by action, so an event kept longer can sit between two that have
17
+ * passed theirs. Each maximal run of consecutive positions past their windows is pruned on its own, and the event
18
+ * kept between two runs stays where it is.
19
+ * - **A run is verified before it goes.** Its links, its hashes and the link before it are checked as a verify would,
20
+ * and a run that does not verify is left in place and counted as refused: the prune never removes the evidence of a
21
+ * break. A run whose positions hold any row it did not read, a second row at one position among them, is refused
22
+ * too, and the delete names the ids of the rows it verified, never a range of positions.
23
+ * - **The head is never pruned.** The next append links to it, so the last event of every chain stays.
24
+ * - **Rows from before the chain** carry no link, and are removed on their own window with nothing to tombstone.
25
+ * - **A page reads only rows past their own windows.** An event kept longer than the shortest window, a floored
26
+ * control-plane call under a short default, is never read, so however many of them sit at the front of a chain a
27
+ * page still reaches the events behind them.
28
+ */
29
+ /** How many rows one prune step reads. */
30
+ export declare const AUDIT_PRUNE_PAGE = 500;
31
+ /** The shortest window any action can have under this policy, in days, or null when nothing is ever pruned. */
32
+ export declare function shortestWindowDays(retention: EffectiveRetention): number | null;
33
+ /** Whether an event with this action, occurring at `occurredAt` ms, is past its window at `now`. */
34
+ export declare function pastWindow(retention: EffectiveRetention, action: string, occurredAt: number, now: Date): boolean;
35
+ /** The actions that share one window, and the instant, in stored ms, before which an event with any of them is past it. */
36
+ export interface ExpiryCutoff {
37
+ readonly before: number;
38
+ readonly actions: readonly string[];
39
+ }
40
+ /** The actions grouped by the instant each is past its window at `now`. An action kept forever is in no group. */
41
+ export declare function expiryCutoffs(retention: EffectiveRetention, actions: readonly string[], now: Date): ExpiryCutoff[];
42
+ /** Every maximal run of consecutive positions among `rows` that are all past their windows. */
43
+ export declare function expiredRuns(rows: readonly ChainRow[], retention: EffectiveRetention, now: Date): ChainRow[][];
44
+ /** What one page of one chain's prune did. */
45
+ export interface ChainPrunePage {
46
+ /** How many events were removed. */
47
+ pruned: number;
48
+ /** How many runs were past their windows and left in place, because they did not verify. */
49
+ refused: number;
50
+ /** The position the next page resumes after, or null when this page reached the end of what is pruneable. */
51
+ next: number | null;
52
+ }
53
+ /**
54
+ * Prune one page of one chain: read up to `limit` chained rows after `afterSeq` that are old enough for the shortest
55
+ * window, and remove every run among them that is past its windows and verifies, tombstone first.
56
+ */
57
+ export declare function pruneChainPage(db: AuditDatabase, bucket: R2Bucket, options: {
58
+ tenant: string | null;
59
+ retention: EffectiveRetention;
60
+ now: Date;
61
+ afterSeq: number;
62
+ limit: number;
63
+ }): Promise<ChainPrunePage>;
64
+ /** The chains the trail holds: each tenant with a chained event, and null for the untenanted chain. */
65
+ export declare function chainTenants(db: AuditDatabase): Promise<(string | null)[]>;
66
+ /** What one page of the unchained prune did. */
67
+ export interface UnchainedPrunePage {
68
+ /** How many rows were removed. */
69
+ deleted: number;
70
+ /** The row id the next page resumes after, or null at the end. */
71
+ next: number | null;
72
+ }
73
+ /**
74
+ * Prune one page of the rows that carry no chain — written before it began, or by an older recorder since. Each is
75
+ * removed on its own window, unless a hold stands on its tenant's trail, and nothing is tombstoned: no chain names it.
76
+ */
77
+ export declare function pruneUnchainedPage(db: AuditDatabase, options: {
78
+ retention: EffectiveRetention;
79
+ now: Date;
80
+ afterId: number;
81
+ limit: number;
82
+ held: (tenant: string | null) => Promise<boolean>;
83
+ }): Promise<UnchainedPrunePage>;
84
+ //# sourceMappingURL=prune.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"prune.d.ts","sourceRoot":"","sources":["../../src/chain/prune.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAQ1D,OAAO,EAAmB,KAAK,kBAAkB,EAAc,MAAM,qCAAqC,CAAC;AAE3G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAAE,KAAK,QAAQ,EAA2E,MAAM,QAAQ,CAAC;AAGhH;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,0CAA0C;AAC1C,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,+GAA+G;AAC/G,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI,CAM/E;AAED,oGAAoG;AACpG,wBAAgB,UAAU,CAAC,SAAS,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAGhH;AAED,2HAA2H;AAC3H,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,kHAAkH;AAClH,wBAAgB,aAAa,CAAC,SAAS,EAAE,kBAAkB,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,IAAI,GAAG,YAAY,EAAE,CAWlH;AAgBD,+FAA+F;AAC/F,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,GAAG,EAAE,IAAI,GAAG,QAAQ,EAAE,EAAE,CAe7G;AAED,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,OAAO,EAAE,MAAM,CAAC;IAChB,6GAA6G;IAC7G,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AA8CD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,aAAa,EACjB,MAAM,EAAE,QAAQ,EAChB,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC5G,OAAO,CAAC,cAAc,CAAC,CA4FzB;AAED,uGAAuG;AACvG,wBAAsB,YAAY,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAQhF;AAED,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,aAAa,EACjB,OAAO,EAAE;IACP,SAAS,EAAE,kBAAkB,CAAC;IAC9B,GAAG,EAAE,IAAI,CAAC;IACV,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACnD,GACA,OAAO,CAAC,kBAAkB,CAAC,CAwC7B"}