@pithy-sh/audit 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (183) hide show
  1. package/README.md +93 -0
  2. package/dist/accessHistory.d.ts +315 -0
  3. package/dist/accessHistory.d.ts.map +1 -0
  4. package/dist/accessHistory.js +299 -0
  5. package/dist/actions.d.ts +15 -1
  6. package/dist/actions.d.ts.map +1 -1
  7. package/dist/actions.js +16 -2
  8. package/dist/capability.d.ts +14 -0
  9. package/dist/capability.d.ts.map +1 -1
  10. package/dist/capability.js +124 -12
  11. package/dist/chain/append.d.ts +43 -0
  12. package/dist/chain/append.d.ts.map +1 -0
  13. package/dist/chain/append.js +110 -0
  14. package/dist/chain/checkpoint.d.ts +70 -0
  15. package/dist/chain/checkpoint.d.ts.map +1 -0
  16. package/dist/chain/checkpoint.js +133 -0
  17. package/dist/chain/lockCheck.d.ts +15 -0
  18. package/dist/chain/lockCheck.d.ts.map +1 -0
  19. package/dist/chain/lockCheck.js +75 -0
  20. package/dist/chain/prune.d.ts +84 -0
  21. package/dist/chain/prune.d.ts.map +1 -0
  22. package/dist/chain/prune.js +231 -0
  23. package/dist/chain/rows.d.ts +74 -0
  24. package/dist/chain/rows.d.ts.map +1 -0
  25. package/dist/chain/rows.js +133 -0
  26. package/dist/chain/tombstone.d.ts +21 -0
  27. package/dist/chain/tombstone.d.ts.map +1 -0
  28. package/dist/chain/tombstone.js +98 -0
  29. package/dist/chain/verify.d.ts +63 -0
  30. package/dist/chain/verify.d.ts.map +1 -0
  31. package/dist/chain/verify.js +220 -0
  32. package/dist/citations.d.ts +17 -0
  33. package/dist/citations.d.ts.map +1 -0
  34. package/dist/citations.js +48 -0
  35. package/dist/cli/emitFromCLI.d.ts +5 -0
  36. package/dist/cli/emitFromCLI.d.ts.map +1 -1
  37. package/dist/cli/emitFromCLI.js +5 -0
  38. package/dist/data/auditEvent.d.ts +4 -0
  39. package/dist/data/auditEvent.d.ts.map +1 -1
  40. package/dist/data/auditEvent.js +7 -3
  41. package/dist/data/sinkState.d.ts +23 -0
  42. package/dist/data/sinkState.d.ts.map +1 -0
  43. package/dist/data/sinkState.js +25 -0
  44. package/dist/data/tables.d.ts +14 -1
  45. package/dist/data/tables.d.ts.map +1 -1
  46. package/dist/data/tables.js +5 -1
  47. package/dist/http/guards.d.ts +39 -6
  48. package/dist/http/guards.d.ts.map +1 -1
  49. package/dist/http/guards.js +101 -17
  50. package/dist/http/responses.d.ts +503 -0
  51. package/dist/http/responses.d.ts.map +1 -1
  52. package/dist/http/responses.js +157 -5
  53. package/dist/http/routes.d.ts +25 -3
  54. package/dist/http/routes.d.ts.map +1 -1
  55. package/dist/http/routes.js +321 -15
  56. package/dist/http/schemas.d.ts +67 -0
  57. package/dist/http/schemas.d.ts.map +1 -1
  58. package/dist/http/schemas.js +88 -4
  59. package/dist/http/views.d.ts +25 -1
  60. package/dist/http/views.d.ts.map +1 -1
  61. package/dist/http/views.js +107 -2
  62. package/dist/migrations/0003_call_index.d.ts +21 -0
  63. package/dist/migrations/0003_call_index.d.ts.map +1 -0
  64. package/dist/migrations/0003_call_index.js +33 -0
  65. package/dist/migrations/0004_request_index.d.ts +16 -0
  66. package/dist/migrations/0004_request_index.d.ts.map +1 -0
  67. package/dist/migrations/0004_request_index.js +24 -0
  68. package/dist/migrations/0005_chain.d.ts +24 -0
  69. package/dist/migrations/0005_chain.d.ts.map +1 -0
  70. package/dist/migrations/0005_chain.js +43 -0
  71. package/dist/migrations/0006_sinks.d.ts +11 -0
  72. package/dist/migrations/0006_sinks.d.ts.map +1 -0
  73. package/dist/migrations/0006_sinks.js +20 -0
  74. package/dist/provision/resolveAuditConfig.d.ts +31 -0
  75. package/dist/provision/resolveAuditConfig.d.ts.map +1 -0
  76. package/dist/provision/resolveAuditConfig.js +43 -0
  77. package/dist/purge/contribution.d.ts +21 -0
  78. package/dist/purge/contribution.d.ts.map +1 -0
  79. package/dist/purge/contribution.js +41 -0
  80. package/dist/reach.d.ts +250 -0
  81. package/dist/reach.d.ts.map +1 -0
  82. package/dist/reach.js +244 -0
  83. package/dist/recorder.d.ts +11 -0
  84. package/dist/recorder.d.ts.map +1 -1
  85. package/dist/recorder.js +23 -5
  86. package/dist/routePattern.d.ts +60 -0
  87. package/dist/routePattern.d.ts.map +1 -0
  88. package/dist/routePattern.js +130 -0
  89. package/dist/seeds/example.d.ts.map +1 -1
  90. package/dist/seeds/example.js +23 -6
  91. package/dist/ship/consumer.d.ts +45 -0
  92. package/dist/ship/consumer.d.ts.map +1 -0
  93. package/dist/ship/consumer.js +141 -0
  94. package/dist/ship/event.d.ts +59 -0
  95. package/dist/ship/event.d.ts.map +1 -0
  96. package/dist/ship/event.js +77 -0
  97. package/dist/ship/health.d.ts +33 -0
  98. package/dist/ship/health.d.ts.map +1 -0
  99. package/dist/ship/health.js +80 -0
  100. package/dist/ship/profiles.d.ts +34 -0
  101. package/dist/ship/profiles.d.ts.map +1 -0
  102. package/dist/ship/profiles.js +62 -0
  103. package/dist/ship/queue.d.ts +57 -0
  104. package/dist/ship/queue.d.ts.map +1 -0
  105. package/dist/ship/queue.js +70 -0
  106. package/dist/ship/secrets.d.ts +7 -0
  107. package/dist/ship/secrets.d.ts.map +1 -0
  108. package/dist/ship/secrets.js +40 -0
  109. package/dist/ship/shipper.d.ts +15 -0
  110. package/dist/ship/shipper.d.ts.map +1 -0
  111. package/dist/ship/shipper.js +27 -0
  112. package/dist/ship/sinks.d.ts +54 -0
  113. package/dist/ship/sinks.d.ts.map +1 -0
  114. package/dist/ship/sinks.js +45 -0
  115. package/dist/ship/state.d.ts +27 -0
  116. package/dist/ship/state.d.ts.map +1 -0
  117. package/dist/ship/state.js +29 -0
  118. package/dist/usage.d.ts +159 -0
  119. package/dist/usage.d.ts.map +1 -0
  120. package/dist/usage.js +87 -0
  121. package/dist/version.generated.d.ts +1 -1
  122. package/dist/version.generated.js +1 -1
  123. package/dist/workflows/prune.d.ts +73 -0
  124. package/dist/workflows/prune.d.ts.map +1 -0
  125. package/dist/workflows/prune.js +128 -0
  126. package/dist/workflows/retryPolicy.d.ts +10 -0
  127. package/dist/workflows/retryPolicy.d.ts.map +1 -0
  128. package/dist/workflows/retryPolicy.js +14 -0
  129. package/dist/workflows/specs.d.ts +70 -0
  130. package/dist/workflows/specs.d.ts.map +1 -0
  131. package/dist/workflows/specs.js +70 -0
  132. package/dist/workflows/worker.d.ts +32 -0
  133. package/dist/workflows/worker.d.ts.map +1 -0
  134. package/dist/workflows/worker.js +41 -0
  135. package/package.json +5 -2
  136. package/pithy.manifest.json +36 -4
  137. package/src/accessHistory.ts +360 -0
  138. package/src/actions.ts +15 -1
  139. package/src/capability.ts +154 -12
  140. package/src/chain/append.ts +161 -0
  141. package/src/chain/checkpoint.ts +172 -0
  142. package/src/chain/lockCheck.ts +72 -0
  143. package/src/chain/prune.ts +340 -0
  144. package/src/chain/rows.ts +211 -0
  145. package/src/chain/tombstone.ts +104 -0
  146. package/src/chain/verify.ts +366 -0
  147. package/src/citations.ts +62 -0
  148. package/src/cli/emitFromCLI.ts +5 -0
  149. package/src/cloudflare-test.d.ts +1 -0
  150. package/src/data/auditEvent.ts +31 -1
  151. package/src/data/sinkState.ts +41 -0
  152. package/src/data/tables.ts +7 -1
  153. package/src/http/guards.ts +90 -6
  154. package/src/http/responses.ts +318 -3
  155. package/src/http/routes.ts +379 -7
  156. package/src/http/schemas.ts +158 -2
  157. package/src/http/views.ts +123 -1
  158. package/src/migrations/0003_call_index.ts +35 -0
  159. package/src/migrations/0004_request_index.ts +26 -0
  160. package/src/migrations/0005_chain.ts +56 -0
  161. package/src/migrations/0006_sinks.ts +28 -0
  162. package/src/provision/resolveAuditConfig.ts +60 -0
  163. package/src/purge/contribution.ts +39 -0
  164. package/src/reach.ts +454 -0
  165. package/src/recorder.ts +64 -42
  166. package/src/routePattern.ts +141 -0
  167. package/src/seeds/example.ts +13 -0
  168. package/src/ship/consumer.ts +169 -0
  169. package/src/ship/event.ts +86 -0
  170. package/src/ship/health.ts +92 -0
  171. package/src/ship/profiles.ts +99 -0
  172. package/src/ship/queue.ts +108 -0
  173. package/src/ship/secrets.ts +42 -0
  174. package/src/ship/shipper.ts +32 -0
  175. package/src/ship/sinks.ts +82 -0
  176. package/src/ship/state.ts +61 -0
  177. package/src/usage.ts +176 -0
  178. package/src/version.generated.ts +1 -1
  179. package/src/workflows/prune.ts +196 -0
  180. package/src/workflows/retryPolicy.ts +14 -0
  181. package/src/workflows/specs.ts +92 -0
  182. package/src/workflows/worker.ts +65 -0
  183. package/src/workflows/wrangler.jsonc +40 -0
@@ -0,0 +1,33 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
4
+ import { type CapabilityHealth } from "@pithy-sh/core/src/controlPlane/discovery/health";
5
+ import type { Context } from "hono";
6
+ import type { AuditSinkStateRow } from "../data/sinkState";
7
+ import type { AuditDatabase } from "../data/tables";
8
+ import type { AuditSinks } from "./sinks";
9
+ /**
10
+ * **Shipping's health, on audit's manifest entry (#824)** — whether the trail is reaching its sinks.
11
+ *
12
+ * Three keys, all behind `audit:events:read`, the scope the listing already requires: a backlog, a dead-letter
13
+ * count, and a state. Each is read off `pithy_audit_sinks` by primary key, one row per declared sink, so the bound
14
+ * is the config's sink count and never the trail's size. Declared only when a sink is: a Worker that ships nothing
15
+ * has nothing to report and reports nothing.
16
+ */
17
+ /** Events waiting on a retry, across every sink. */
18
+ export declare const AUDIT_SHIP_BACKLOG = "auditShipBacklog";
19
+ /** Events given up on, across every sink: their last retry failed and they went to the dead-letter queue. */
20
+ export declare const AUDIT_SHIP_DEAD_LETTERED = "auditShipDeadLettered";
21
+ /** How delivery stands, across every sink. */
22
+ export declare const AUDIT_SHIP_DELIVERY = "auditShipDelivery";
23
+ /**
24
+ * The values {@link AUDIT_SHIP_DELIVERY} takes. `failing` when any sink's last attempt failed; `delivering` when
25
+ * every sink that has been attempted last took a delivery; `idle` when no sink has been attempted yet.
26
+ */
27
+ export declare const SHIP_DELIVERY_STATES: readonly ["delivering", "failing", "idle"];
28
+ export type ShipDeliveryState = (typeof SHIP_DELIVERY_STATES)[number];
29
+ /** How delivery stands, from the declared sinks' rows. */
30
+ export declare function shipDelivery(states: readonly AuditSinkStateRow[]): ShipDeliveryState;
31
+ /** Declare shipping's health keys over the declared sinks. */
32
+ export declare function shipHealth(sinks: AuditSinks, database: (c: Context<PithyHonoEnv>) => AuditDatabase): CapabilityHealth;
33
+ //# sourceMappingURL=health.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/ship/health.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAC7E,OAAO,EAAE,KAAK,gBAAgB,EAA0B,MAAM,kDAAkD,CAAC;AACjH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAG1C;;;;;;;GAOG;AAEH,oDAAoD;AACpD,eAAO,MAAM,kBAAkB,qBAAqB,CAAC;AAErD,6GAA6G;AAC7G,eAAO,MAAM,wBAAwB,0BAA0B,CAAC;AAEhE,8CAA8C;AAC9C,eAAO,MAAM,mBAAmB,sBAAsB,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,YAAI,YAAY,EAAE,SAAS,EAAE,MAAM,CAAU,CAAC;AAC/E,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,GAAG,iBAAiB,CAQpF;AAED,8DAA8D;AAC9D,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,aAAa,GAAG,gBAAgB,CA0CrH"}
@@ -0,0 +1,80 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { AUDIT_TRAIL_READ_SCOPE } from "../http/guards.js";
4
+ import { readSinkStates } from "./state.js";
5
+ import { defineCapabilityHealth } from "@pithy-sh/core/src/controlPlane/discovery/health";
6
+ //#region src/ship/health.ts
7
+ /**
8
+ * **Shipping's health, on audit's manifest entry (#824)** — whether the trail is reaching its sinks.
9
+ *
10
+ * Three keys, all behind `audit:events:read`, the scope the listing already requires: a backlog, a dead-letter
11
+ * count, and a state. Each is read off `pithy_audit_sinks` by primary key, one row per declared sink, so the bound
12
+ * is the config's sink count and never the trail's size. Declared only when a sink is: a Worker that ships nothing
13
+ * has nothing to report and reports nothing.
14
+ */
15
+ /** Events waiting on a retry, across every sink. */
16
+ const AUDIT_SHIP_BACKLOG = "auditShipBacklog";
17
+ /** Events given up on, across every sink: their last retry failed and they went to the dead-letter queue. */
18
+ const AUDIT_SHIP_DEAD_LETTERED = "auditShipDeadLettered";
19
+ /** How delivery stands, across every sink. */
20
+ const AUDIT_SHIP_DELIVERY = "auditShipDelivery";
21
+ /**
22
+ * The values {@link AUDIT_SHIP_DELIVERY} takes. `failing` when any sink's last attempt failed; `delivering` when
23
+ * every sink that has been attempted last took a delivery; `idle` when no sink has been attempted yet.
24
+ */
25
+ const SHIP_DELIVERY_STATES = [
26
+ "delivering",
27
+ "failing",
28
+ "idle"
29
+ ];
30
+ /** How delivery stands, from the declared sinks' rows. */
31
+ function shipDelivery(states) {
32
+ const attempted = states.filter((state) => state.lastDeliveredAt !== null || state.lastFailedAt !== null);
33
+ if (attempted.length === 0) return "idle";
34
+ return attempted.some((state) => state.lastFailedAt !== null && (state.lastDeliveredAt === null || state.lastFailedAt > state.lastDeliveredAt)) ? "failing" : "delivering";
35
+ }
36
+ /** Declare shipping's health keys over the declared sinks. */
37
+ function shipHealth(sinks, database) {
38
+ const names = Object.keys(sinks);
39
+ return defineCapabilityHealth({
40
+ keys: [
41
+ {
42
+ key: AUDIT_SHIP_BACKLOG,
43
+ kind: "count",
44
+ states: null,
45
+ scope: AUDIT_TRAIL_READ_SCOPE,
46
+ cost: "indexed",
47
+ nominal: { atMost: 0 },
48
+ summary: "Audit events waiting on a retry to a sink that refused or could not be reached."
49
+ },
50
+ {
51
+ key: AUDIT_SHIP_DEAD_LETTERED,
52
+ kind: "count",
53
+ states: null,
54
+ scope: AUDIT_TRAIL_READ_SCOPE,
55
+ cost: "indexed",
56
+ nominal: { atMost: 0 },
57
+ summary: "Audit events a sink never took: their retries ran out and they went to the dead-letter queue."
58
+ },
59
+ {
60
+ key: AUDIT_SHIP_DELIVERY,
61
+ kind: "state",
62
+ states: [...SHIP_DELIVERY_STATES],
63
+ scope: AUDIT_TRAIL_READ_SCOPE,
64
+ cost: "indexed",
65
+ nominal: ["delivering", "idle"],
66
+ summary: "Whether every sink took its last delivery, any sink is failing, or nothing has been shipped yet."
67
+ }
68
+ ],
69
+ read: async (c) => {
70
+ const states = await readSinkStates(database(c), names);
71
+ return {
72
+ [AUDIT_SHIP_BACKLOG]: states.reduce((sum, state) => sum + state.retrying, 0),
73
+ [AUDIT_SHIP_DEAD_LETTERED]: states.reduce((sum, state) => sum + state.deadLettered, 0),
74
+ [AUDIT_SHIP_DELIVERY]: shipDelivery(states)
75
+ };
76
+ }
77
+ });
78
+ }
79
+ //#endregion
80
+ export { AUDIT_SHIP_BACKLOG, AUDIT_SHIP_DEAD_LETTERED, AUDIT_SHIP_DELIVERY, SHIP_DELIVERY_STATES, shipDelivery, shipHealth };
@@ -0,0 +1,34 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import type { ShippedAuditEvent } from "./event";
4
+ import type { AuditSink } from "./sinks";
5
+ /**
6
+ * **One delivery, in the receiver's own documented format (#824).**
7
+ *
8
+ * - **`splunk-hec`** — Splunk's HTTP Event Collector: one JSON object per event, concatenated, with
9
+ * `Authorization: Splunk <token>`. Each carries `time` in epoch seconds, `source` and `sourcetype`, and the event
10
+ * under `event`. https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector
11
+ * - **`datadog-logs`** — the Datadog Logs intake (`/api/v2/logs`): a JSON array, with `DD-API-KEY: <key>`. Each log
12
+ * carries `ddsource`, `service`, `ddtags`, a one-line `message`, and the event under `audit`.
13
+ * https://docs.datadoghq.com/api/latest/logs/#send-logs
14
+ * - **`webhook`** — a JSON document `{ format, events }` with `Authorization: Bearer <token>`, for Elastic, Sumo Logic,
15
+ * or anything else that takes HTTPS. `format` is `pithy-audit-ship/1`.
16
+ *
17
+ * Every profile carries the whole shipped event, so the chain hash and the event id reach every receiver.
18
+ */
19
+ /** What one delivery sends: where, and the request. */
20
+ export interface SinkDelivery {
21
+ url: string;
22
+ init: {
23
+ method: "POST";
24
+ headers: Record<string, string>;
25
+ body: string;
26
+ };
27
+ }
28
+ /** Splunk's `source`, Datadog's `ddsource`: what the events are, at a glance, in the receiver's own search. */
29
+ export declare const SHIP_SOURCE = "pithy";
30
+ /** Splunk's `sourcetype` for the trail. */
31
+ export declare const SPLUNK_SOURCETYPE = "pithy:audit";
32
+ /** The request that delivers these events to this sink. */
33
+ export declare function sinkDelivery(sink: Pick<AuditSink, "profile" | "url">, token: string, events: readonly ShippedAuditEvent[]): SinkDelivery;
34
+ //# sourceMappingURL=profiles.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/ship/profiles.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD,OAAO,KAAK,EAAE,SAAS,EAAoB,MAAM,SAAS,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AAEH,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACzE;AAED,+GAA+G;AAC/G,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC,2CAA2C;AAC3C,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAoD/C,2DAA2D;AAC3D,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,GAAG,KAAK,CAAC,EACxC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,SAAS,iBAAiB,EAAE,GACnC,YAAY,CASd"}
@@ -0,0 +1,62 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { AUDIT_SHIP_FORMAT } from "./event.js";
4
+ //#region src/ship/profiles.ts
5
+ /** Splunk's `source`, Datadog's `ddsource`: what the events are, at a glance, in the receiver's own search. */
6
+ const SHIP_SOURCE = "pithy";
7
+ /** Splunk's `sourcetype` for the trail. */
8
+ const SPLUNK_SOURCETYPE = "pithy:audit";
9
+ /** A Datadog tag value: its own allowed characters, lowercased. */
10
+ function tag(value) {
11
+ return value.toLowerCase().replace(/[^a-z0-9_./:-]/g, "_");
12
+ }
13
+ function body(profile, events) {
14
+ switch (profile) {
15
+ case "splunk-hec": return events.map((event) => JSON.stringify({
16
+ time: event.occurredAt / 1e3,
17
+ source: SHIP_SOURCE,
18
+ sourcetype: SPLUNK_SOURCETYPE,
19
+ ...event.worker === null ? {} : { host: event.worker },
20
+ event
21
+ })).join("\n");
22
+ case "datadog-logs": return JSON.stringify(events.map((event) => ({
23
+ ddsource: SHIP_SOURCE,
24
+ service: event.project ?? "pithy",
25
+ ...event.worker === null ? {} : { hostname: event.worker },
26
+ ddtags: [
27
+ ...event.environment === null ? [] : [`env:${tag(event.environment)}`],
28
+ `action:${tag(event.action)}`,
29
+ `outcome:${tag(event.outcome)}`
30
+ ].join(","),
31
+ message: `${event.action} ${event.outcome}`,
32
+ audit: event
33
+ })));
34
+ case "webhook": return JSON.stringify({
35
+ format: AUDIT_SHIP_FORMAT,
36
+ events
37
+ });
38
+ }
39
+ }
40
+ function authorization(profile, token) {
41
+ switch (profile) {
42
+ case "splunk-hec": return { authorization: `Splunk ${token}` };
43
+ case "datadog-logs": return { "dd-api-key": token };
44
+ case "webhook": return { authorization: `Bearer ${token}` };
45
+ }
46
+ }
47
+ /** The request that delivers these events to this sink. */
48
+ function sinkDelivery(sink, token, events) {
49
+ return {
50
+ url: sink.url,
51
+ init: {
52
+ method: "POST",
53
+ headers: {
54
+ "content-type": "application/json",
55
+ ...authorization(sink.profile, token)
56
+ },
57
+ body: body(sink.profile, events)
58
+ }
59
+ };
60
+ }
61
+ //#endregion
62
+ export { SHIP_SOURCE, SPLUNK_SOURCETYPE, sinkDelivery };
@@ -0,0 +1,57 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import type { BindingSpecInput } from "@pithy-sh/core/src/capability/bindings";
4
+ import { z } from "zod";
5
+ import { type AuditSinks } from "./sinks";
6
+ /**
7
+ * **The shipping queue: what goes on it, and what the Worker binds for it (#824).**
8
+ *
9
+ * One message per event per sink that takes it. A message names the sink and the event and nothing else: the
10
+ * consumer reads the row back at delivery, so no IP, user-agent or metadata value ever sits in a queue, and a sink
11
+ * that fails retries on its own without redelivering to the sinks that took the event.
12
+ *
13
+ * Two queues, both declared only when a sink is: `AUDIT_SHIP`, which the Worker produces to and consumes, and
14
+ * `AUDIT_SHIP_DLQ`, where a message goes once its retries are spent. Cloudflare Queues needs the Workers Paid plan,
15
+ * so a project that ships nothing binds neither.
16
+ */
17
+ /** As much of a queue producer binding as shipping uses: one batched send. */
18
+ export interface ShipQueue {
19
+ sendBatch(messages: Iterable<{
20
+ body: unknown;
21
+ }>): Promise<unknown>;
22
+ }
23
+ /** The capability name every message body carries, so the Worker's one `queue` export routes it here. */
24
+ export declare const AUDIT_QUEUE_CAPABILITY = "audit";
25
+ /** The queue every shipment goes through. */
26
+ export declare const AUDIT_SHIP_BINDING = "AUDIT_SHIP";
27
+ /** Where a shipment goes once its retries are spent. */
28
+ export declare const AUDIT_SHIP_DLQ_BINDING = "AUDIT_SHIP_DLQ";
29
+ /**
30
+ * How many times a failed shipment is retried before it is dead-lettered. With {@link retryDelaySeconds} that is
31
+ * about five hours of a sink being unreachable before an event is given up on.
32
+ */
33
+ export declare const AUDIT_SHIP_MAX_RETRIES = 10;
34
+ /** The most shipments one invocation takes. Each sink's share of a batch is one request to it. */
35
+ export declare const AUDIT_SHIP_MAX_BATCH = 50;
36
+ /** How long the retry after this attempt waits: doubling from 30 seconds, never past an hour. */
37
+ export declare function retryDelaySeconds(attempts: number): number;
38
+ /** Whether this was a message's last delivery: the one whose failure dead-letters it. */
39
+ export declare function isFinalAttempt(attempts: number, maxRetries?: number): boolean;
40
+ /** One shipment: one event, to one sink. */
41
+ export declare const ShipMessage: z.ZodObject<{
42
+ capability: z.ZodLiteral<"audit">;
43
+ sink: z.ZodString;
44
+ eventId: z.ZodString;
45
+ }, z.core.$strip>;
46
+ export type ShipMessage = z.infer<typeof ShipMessage>;
47
+ /** The queue bindings shipping needs: none without a sink, the queue and its dead-letter queue with one. */
48
+ export declare function shipBindings(sinks: AuditSinks): BindingSpecInput[];
49
+ /**
50
+ * Put one event on the queue for every sink that takes it. Throws only what the queue throws; the recorder catches
51
+ * it, because a failed enqueue never fails the write it follows.
52
+ */
53
+ export declare function enqueueShipments(queue: ShipQueue, sinks: AuditSinks, event: {
54
+ eventId: string;
55
+ action: string;
56
+ }): Promise<number>;
57
+ //# sourceMappingURL=queue.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/ship/queue.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AAE/E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,UAAU,EAAY,MAAM,SAAS,CAAC;AAEpD;;;;;;;;;;GAUG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpE;AAED,yGAAyG;AACzG,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAE9C,6CAA6C;AAC7C,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAE/C,wDAAwD;AACxD,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,kGAAkG;AAClG,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAQvC,iGAAiG;AACjG,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,yFAAyF;AACzF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,GAAE,MAA+B,GAAG,OAAO,CAErG;AAED,4CAA4C;AAC5C,eAAO,MAAM,WAAW;;;;iBAMkE,CAAC;AAC3F,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,4GAA4G;AAC5G,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,gBAAgB,EAAE,CAiBlE;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzC,OAAO,CAAC,MAAM,CAAC,CASjB"}
@@ -0,0 +1,70 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { sinksFor } from "./sinks.js";
4
+ import { z } from "zod";
5
+ import { queueBody } from "@pithy-sh/core/src/queue/consumer";
6
+ //#region src/ship/queue.ts
7
+ /** The capability name every message body carries, so the Worker's one `queue` export routes it here. */
8
+ const AUDIT_QUEUE_CAPABILITY = "audit";
9
+ /** The queue every shipment goes through. */
10
+ const AUDIT_SHIP_BINDING = "AUDIT_SHIP";
11
+ /** Where a shipment goes once its retries are spent. */
12
+ const AUDIT_SHIP_DLQ_BINDING = "AUDIT_SHIP_DLQ";
13
+ /**
14
+ * How many times a failed shipment is retried before it is dead-lettered. With {@link retryDelaySeconds} that is
15
+ * about five hours of a sink being unreachable before an event is given up on.
16
+ */
17
+ const AUDIT_SHIP_MAX_RETRIES = 10;
18
+ /** The most shipments one invocation takes. Each sink's share of a batch is one request to it. */
19
+ const AUDIT_SHIP_MAX_BATCH = 50;
20
+ /** The first retry's delay, in seconds. Each one after doubles it. */
21
+ const FIRST_RETRY_SECONDS = 30;
22
+ /** The longest one retry waits, in seconds. */
23
+ const LONGEST_RETRY_SECONDS = 3600;
24
+ /** How long the retry after this attempt waits: doubling from 30 seconds, never past an hour. */
25
+ function retryDelaySeconds(attempts) {
26
+ const exponent = Math.max(0, Math.min(attempts - 1, 20));
27
+ return Math.min(FIRST_RETRY_SECONDS * 2 ** exponent, LONGEST_RETRY_SECONDS);
28
+ }
29
+ /** Whether this was a message's last delivery: the one whose failure dead-letters it. */
30
+ function isFinalAttempt(attempts, maxRetries = 10) {
31
+ return attempts > maxRetries;
32
+ }
33
+ /** One shipment: one event, to one sink. */
34
+ const ShipMessage = z.object({
35
+ capability: z.literal(AUDIT_QUEUE_CAPABILITY).describe("The capability the message belongs to."),
36
+ sink: z.string().min(1).describe("The sink the event is shipped to, by its declared name."),
37
+ eventId: z.string().min(1).describe("The event's stable public id — the row the consumer reads back.")
38
+ }).describe("One audit event, to one sink. Names only; the row is read back at delivery.");
39
+ /** The queue bindings shipping needs: none without a sink, the queue and its dead-letter queue with one. */
40
+ function shipBindings(sinks) {
41
+ if (Object.keys(sinks).length === 0) return [];
42
+ return [{
43
+ type: "queue",
44
+ name: AUDIT_SHIP_BINDING,
45
+ consumer: {
46
+ deadLetter: AUDIT_SHIP_DLQ_BINDING,
47
+ maxRetries: 10,
48
+ maxBatchSize: 50
49
+ }
50
+ }, {
51
+ type: "queue",
52
+ name: AUDIT_SHIP_DLQ_BINDING,
53
+ optional: true
54
+ }];
55
+ }
56
+ /**
57
+ * Put one event on the queue for every sink that takes it. Throws only what the queue throws; the recorder catches
58
+ * it, because a failed enqueue never fails the write it follows.
59
+ */
60
+ async function enqueueShipments(queue, sinks, event) {
61
+ const targets = sinksFor(sinks, event.action);
62
+ if (targets.length === 0) return 0;
63
+ await queue.sendBatch(targets.map((sink) => ({ body: queueBody(AUDIT_QUEUE_CAPABILITY, {
64
+ sink,
65
+ eventId: event.eventId
66
+ }) })));
67
+ return targets.length;
68
+ }
69
+ //#endregion
70
+ export { AUDIT_QUEUE_CAPABILITY, AUDIT_SHIP_BINDING, AUDIT_SHIP_DLQ_BINDING, AUDIT_SHIP_MAX_BATCH, AUDIT_SHIP_MAX_RETRIES, ShipMessage, enqueueShipments, isFinalAttempt, retryDelaySeconds, shipBindings };
@@ -0,0 +1,7 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { type SecretRegistry } from "@pithy-sh/secrets/src/registry";
4
+ import type { AuditSinks } from "./sinks";
5
+ /** The registry slice for every sink's token. Empty when no sink is declared. */
6
+ export declare function sinkSecretsRegistry(sinks: AuditSinks): SecretRegistry;
7
+ //# sourceMappingURL=secrets.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../src/ship/secrets.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAkB1C,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,CAkBrE"}
@@ -0,0 +1,40 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { defineSecretRegistry } from "@pithy-sh/secrets/src/registry";
4
+ //#region src/ship/secrets.ts
5
+ /**
6
+ * **Each sink's token, declared where every secret is (#824).**
7
+ *
8
+ * A sink names the `@pithy-sh/secrets` name its token lives under, and this declares it: a per-environment `d1`
9
+ * secret, `text`, obtained from the receiver's own console and replaced there by hand. Declared on audit's
10
+ * `secretRegistry`, so `pithy secrets create` knows the name, `pithy doctor` can say whether it is set, and the
11
+ * consumer reads it through the one `secretsStore` reader like every other secret. Two sinks may share one token by
12
+ * naming the same secret; it is declared once.
13
+ *
14
+ * Nothing here is a Cloudflare API token, so nothing joins the application's runtime token.
15
+ */
16
+ /** Where an operator is told to look for the token, whichever receiver issues it. */
17
+ const SINK_TOKEN_DOCUMENTATION = "https://github.com/pithy-sh/pithy/blob/main/packages/audit/README.md#shipping-the-trail";
18
+ /** The registry slice for every sink's token. Empty when no sink is declared. */
19
+ function sinkSecretsRegistry(sinks) {
20
+ const names = [...new Set(Object.values(sinks).map((sink) => sink.secret))];
21
+ return defineSecretRegistry(Object.fromEntries(names.map((name) => [name, {
22
+ backend: "d1",
23
+ scope: "environment",
24
+ rotatable: false,
25
+ valueType: "text",
26
+ origin: {
27
+ kind: "obtained",
28
+ issuer: "other",
29
+ documentation: SINK_TOKEN_DOCUMENTATION
30
+ },
31
+ rotation: {
32
+ kind: "manual",
33
+ issuer: "other",
34
+ documentation: SINK_TOKEN_DOCUMENTATION
35
+ },
36
+ notes: "An audit sink's token: the Splunk HEC token, the Datadog API key, or the webhook's bearer token."
37
+ }])));
38
+ }
39
+ //#endregion
40
+ export { sinkSecretsRegistry };
@@ -0,0 +1,15 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import type { AuditSinks } from "./sinks";
4
+ /**
5
+ * The recorder's `ship` hook over one env's queue binding (#824), or nothing when no sink is declared.
6
+ *
7
+ * The binding is read when an event is shipped, not when the hook is built: a Worker deployed before `pithy upgrade`
8
+ * wrote the binding still records every event, and the shipment that could not be enqueued is said, never thrown
9
+ * into the write.
10
+ */
11
+ export declare function shipperFor(env: Record<string, unknown> | undefined, sinks: AuditSinks): ((event: {
12
+ eventId: string;
13
+ action: string;
14
+ }) => Promise<void>) | undefined;
15
+ //# sourceMappingURL=shipper.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"shipper.d.ts","sourceRoot":"","sources":["../../src/ship/shipper.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACxC,KAAK,EAAE,UAAU,GAChB,CAAC,CAAC,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAa7E"}
@@ -0,0 +1,27 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { AUDIT_SHIP_BINDING, enqueueShipments } from "./queue.js";
4
+ import { InternalError } from "@pithy-sh/core/src/error/pithyError";
5
+ import { pithyCommand } from "@pithy-sh/core/src/cli/command";
6
+ //#region src/ship/shipper.ts
7
+ /**
8
+ * The recorder's `ship` hook over one env's queue binding (#824), or nothing when no sink is declared.
9
+ *
10
+ * The binding is read when an event is shipped, not when the hook is built: a Worker deployed before `pithy upgrade`
11
+ * wrote the binding still records every event, and the shipment that could not be enqueued is said, never thrown
12
+ * into the write.
13
+ */
14
+ function shipperFor(env, sinks) {
15
+ if (Object.keys(sinks).length === 0) return void 0;
16
+ return async (event) => {
17
+ const queue = env?.[AUDIT_SHIP_BINDING];
18
+ if (typeof queue?.sendBatch !== "function") throw new InternalError({
19
+ message: "Audit sinks are declared and this Worker binds no shipping queue.",
20
+ action: `Run ${pithyCommand("upgrade")} to write the ${AUDIT_SHIP_BINDING} queue binding, then ${pithyCommand("provision")}.`,
21
+ detail: `no ${AUDIT_SHIP_BINDING} binding on env; event ${event.eventId} was recorded and not shipped`
22
+ });
23
+ await enqueueShipments(queue, sinks, event);
24
+ };
25
+ }
26
+ //#endregion
27
+ export { shipperFor };
@@ -0,0 +1,54 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { z } from "zod";
4
+ /**
5
+ * **Where the trail is shipped: sinks, declared in `pithy.config.ts` (#824).**
6
+ *
7
+ * A sink is reviewed and deployed like code. No control-plane route adds, changes or removes one, so no management
8
+ * credential can point the trail somewhere new — the same reason audit has no route that writes. Each sink names its
9
+ * profile, its URL, the `@pithy-sh/secrets` name its token is read through, and optionally which actions it takes
10
+ * and whether it ships personal values.
11
+ *
12
+ * Strict objects, so a misspelled key (`detial: true`) is refused at config load rather than read as the default
13
+ * it was trying to change. A profile nobody wrote a format for, a URL that is not HTTPS, and a sink with no secret
14
+ * name are refused the same way, before the Worker serves anything.
15
+ */
16
+ /** The formats a sink speaks. One per receiver's own documented ingestion API, and a generic one for the rest. */
17
+ export declare const AuditSinkProfile: z.ZodEnum<{
18
+ "datadog-logs": "datadog-logs";
19
+ "splunk-hec": "splunk-hec";
20
+ webhook: "webhook";
21
+ }>;
22
+ export type AuditSinkProfile = z.infer<typeof AuditSinkProfile>;
23
+ /** A sink's name: the key it is declared under, reported by `pithy doctor` and on the manifest's health. */
24
+ export declare const AUDIT_SINK_NAME: RegExp;
25
+ export declare const AuditSink: z.ZodObject<{
26
+ profile: z.ZodEnum<{
27
+ "datadog-logs": "datadog-logs";
28
+ "splunk-hec": "splunk-hec";
29
+ webhook: "webhook";
30
+ }>;
31
+ url: z.ZodURL;
32
+ secret: z.ZodString;
33
+ actions: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
34
+ detail: z.ZodDefault<z.ZodBoolean>;
35
+ }, z.core.$strict>;
36
+ export type AuditSink = z.output<typeof AuditSink>;
37
+ export type AuditSinkInput = z.input<typeof AuditSink>;
38
+ export declare const AuditSinks: z.ZodRecord<z.ZodString, z.ZodObject<{
39
+ profile: z.ZodEnum<{
40
+ "datadog-logs": "datadog-logs";
41
+ "splunk-hec": "splunk-hec";
42
+ webhook: "webhook";
43
+ }>;
44
+ url: z.ZodURL;
45
+ secret: z.ZodString;
46
+ actions: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
47
+ detail: z.ZodDefault<z.ZodBoolean>;
48
+ }, z.core.$strict>>;
49
+ export type AuditSinks = z.output<typeof AuditSinks>;
50
+ /** Whether a sink takes an event with this action — every action when it names no prefixes. */
51
+ export declare function sinkTakes(sink: Pick<AuditSink, "actions">, action: string): boolean;
52
+ /** The sinks, by name, that take an event with this action, in declaration order. */
53
+ export declare function sinksFor(sinks: AuditSinks, action: string): string[];
54
+ //# sourceMappingURL=sinks.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sinks.d.ts","sourceRoot":"","sources":["../../src/ship/sinks.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;GAWG;AAEH,kHAAkH;AAClH,eAAO,MAAM,gBAAgB;;;;EAI1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,4GAA4G;AAC5G,eAAO,MAAM,eAAe,QAAsB,CAAC;AAKnD,eAAO,MAAM,SAAS;;;;;;;;;;kBA6BwD,CAAC;AAC/E,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AACnD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAEvD,eAAO,MAAM,UAAU;;;;;;;;;;mBAK2E,CAAC;AACnG,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAErD,+FAA+F;AAC/F,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnF;AAED,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAEpE"}
@@ -0,0 +1,45 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { z } from "zod";
4
+ //#region src/ship/sinks.ts
5
+ /**
6
+ * **Where the trail is shipped: sinks, declared in `pithy.config.ts` (#824).**
7
+ *
8
+ * A sink is reviewed and deployed like code. No control-plane route adds, changes or removes one, so no management
9
+ * credential can point the trail somewhere new — the same reason audit has no route that writes. Each sink names its
10
+ * profile, its URL, the `@pithy-sh/secrets` name its token is read through, and optionally which actions it takes
11
+ * and whether it ships personal values.
12
+ *
13
+ * Strict objects, so a misspelled key (`detial: true`) is refused at config load rather than read as the default
14
+ * it was trying to change. A profile nobody wrote a format for, a URL that is not HTTPS, and a sink with no secret
15
+ * name are refused the same way, before the Worker serves anything.
16
+ */
17
+ /** The formats a sink speaks. One per receiver's own documented ingestion API, and a generic one for the rest. */
18
+ const AuditSinkProfile = z.enum([
19
+ "splunk-hec",
20
+ "datadog-logs",
21
+ "webhook"
22
+ ]).describe("How events are delivered: `splunk-hec` to a Splunk HTTP Event Collector, `datadog-logs` to the Datadog Logs intake, or `webhook` as a JSON document to any HTTPS endpoint — Elastic, Sumo Logic, or your own.");
23
+ /** A sink's name: the key it is declared under, reported by `pithy doctor` and on the manifest's health. */
24
+ const AUDIT_SINK_NAME = /^[a-z][a-z0-9-]*$/;
25
+ const AuditSink = z.strictObject({
26
+ profile: AuditSinkProfile,
27
+ url: z.url({
28
+ protocol: /^https$/,
29
+ hostname: z.regexes.domain
30
+ }).describe("The HTTPS endpoint events are posted to — the collector's full URL, path included, e.g. `https://splunk.example.com:8088/services/collector/event`."),
31
+ secret: z.string().regex(/^[a-z][a-z0-9-]*$/, "A secret name is kebab-case: lowercase letters, digits and hyphens.").describe("The `@pithy-sh/secrets` name the sink's token is stored under — the HEC token, the Datadog API key, or the webhook's bearer token. Set it with `pithy secrets create <name> --env <env>`."),
32
+ actions: z.array(z.string().min(1).describe("An action prefix, e.g. `auth/` or `controlplane/connection`.")).min(1).readonly().optional().describe("Ship only events whose action starts with one of these prefixes. Absent ships every event the trail records."),
33
+ detail: z.boolean().default(false).describe("Ship each event's IP, user-agent and metadata values. Off by default: the sink receives their salted hashes instead, which verify against the chain and disclose nothing.")
34
+ }).describe("One destination the audit trail is shipped to as it is written.");
35
+ const AuditSinks = z.record(z.string().regex(AUDIT_SINK_NAME, "A sink name is kebab-case: lowercase letters, digits and hyphens."), AuditSink).describe("The sinks the trail is shipped to, by name. Empty ships nothing and binds no queue.");
36
+ /** Whether a sink takes an event with this action — every action when it names no prefixes. */
37
+ function sinkTakes(sink, action) {
38
+ return sink.actions === void 0 || sink.actions.some((prefix) => action.startsWith(prefix));
39
+ }
40
+ /** The sinks, by name, that take an event with this action, in declaration order. */
41
+ function sinksFor(sinks, action) {
42
+ return Object.entries(sinks).flatMap(([name, sink]) => sinkTakes(sink, action) ? [name] : []);
43
+ }
44
+ //#endregion
45
+ export { AUDIT_SINK_NAME, AuditSink, AuditSinkProfile, AuditSinks, sinkTakes, sinksFor };
@@ -0,0 +1,27 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { AuditSinkStateRow } from "../data/sinkState";
4
+ import type { AuditDatabase } from "../data/tables";
5
+ /**
6
+ * **Each sink's delivery state, kept by the consumer and read by the health keys (#824).**
7
+ *
8
+ * `retrying` is the backlog the queue cannot be asked for: an event joins it the first time a delivery to the sink
9
+ * fails, and leaves it when a retry lands or when its last retry fails and it is dead-lettered. Counts move by
10
+ * upsert, one statement per sink per batch, and never below zero.
11
+ */
12
+ /** What one batch did to one sink. */
13
+ export interface SinkOutcome {
14
+ /** The batch landed, or it did not. */
15
+ delivered: boolean;
16
+ /** When. */
17
+ at: Date;
18
+ /** The change to the backlog: events newly waiting on a retry, less those that stopped waiting. */
19
+ retryingDelta: number;
20
+ /** Events given up on: their last retry failed, and they went to the dead-letter queue. */
21
+ deadLettered: number;
22
+ }
23
+ /** Record one batch's outcome for one sink. */
24
+ export declare function recordSinkOutcome(db: AuditDatabase, sink: string, outcome: SinkOutcome): Promise<void>;
25
+ /** The declared sinks' rows, decoded. A sink with no row yet has done nothing and is absent. */
26
+ export declare function readSinkStates(db: AuditDatabase, sinks: readonly string[]): Promise<AuditSinkStateRow[]>;
27
+ //# sourceMappingURL=state.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/ship/state.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;;GAMG;AAEH,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY;IACZ,EAAE,EAAE,IAAI,CAAC;IACT,mGAAmG;IACnG,aAAa,EAAE,MAAM,CAAC;IACtB,2FAA2F;IAC3F,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,+CAA+C;AAC/C,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB5G;AAED,gGAAgG;AAChG,wBAAsB,cAAc,CAAC,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAQ9G"}
@@ -0,0 +1,29 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { AuditSinkStateRow } from "../data/sinkState.js";
4
+ import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
5
+ import { sql } from "kysely";
6
+ //#region src/ship/state.ts
7
+ /** Record one batch's outcome for one sink. */
8
+ async function recordSinkOutcome(db, sink, outcome) {
9
+ const at = SQLiteDate.encode(outcome.at);
10
+ const delta = outcome.retryingDelta;
11
+ await db.insertInto("pithyAuditSinks").values({
12
+ sink,
13
+ lastDeliveredAt: outcome.delivered ? at : null,
14
+ lastFailedAt: outcome.delivered ? null : at,
15
+ retrying: Math.max(delta, 0),
16
+ deadLettered: outcome.deadLettered
17
+ }).onConflict((conflict) => conflict.column("sink").doUpdateSet({
18
+ ...outcome.delivered ? { lastDeliveredAt: at } : { lastFailedAt: at },
19
+ retrying: sql`max(${sql.ref("retrying")} + ${delta}, 0)`,
20
+ deadLettered: sql`${sql.ref("deadLettered")} + ${outcome.deadLettered}`
21
+ })).execute();
22
+ }
23
+ /** The declared sinks' rows, decoded. A sink with no row yet has done nothing and is absent. */
24
+ async function readSinkStates(db, sinks) {
25
+ if (sinks.length === 0) return [];
26
+ return (await db.selectFrom("pithyAuditSinks").selectAll().where("sink", "in", [...sinks]).execute()).map((row) => AuditSinkStateRow.parse(row));
27
+ }
28
+ //#endregion
29
+ export { readSinkStates, recordSinkOutcome };