@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,108 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+
4
+ import type { BindingSpecInput } from "@pithy-sh/core/src/capability/bindings";
5
+ import { queueBody } from "@pithy-sh/core/src/queue/consumer";
6
+ import { z } from "zod";
7
+ import { type AuditSinks, sinksFor } from "./sinks";
8
+
9
+ /**
10
+ * **The shipping queue: what goes on it, and what the Worker binds for it (#824).**
11
+ *
12
+ * One message per event per sink that takes it. A message names the sink and the event and nothing else: the
13
+ * consumer reads the row back at delivery, so no IP, user-agent or metadata value ever sits in a queue, and a sink
14
+ * that fails retries on its own without redelivering to the sinks that took the event.
15
+ *
16
+ * Two queues, both declared only when a sink is: `AUDIT_SHIP`, which the Worker produces to and consumes, and
17
+ * `AUDIT_SHIP_DLQ`, where a message goes once its retries are spent. Cloudflare Queues needs the Workers Paid plan,
18
+ * so a project that ships nothing binds neither.
19
+ */
20
+
21
+ /** As much of a queue producer binding as shipping uses: one batched send. */
22
+ export interface ShipQueue {
23
+ sendBatch(messages: Iterable<{ body: unknown }>): Promise<unknown>;
24
+ }
25
+
26
+ /** The capability name every message body carries, so the Worker's one `queue` export routes it here. */
27
+ export const AUDIT_QUEUE_CAPABILITY = "audit";
28
+
29
+ /** The queue every shipment goes through. */
30
+ export const AUDIT_SHIP_BINDING = "AUDIT_SHIP";
31
+
32
+ /** Where a shipment goes once its retries are spent. */
33
+ export const AUDIT_SHIP_DLQ_BINDING = "AUDIT_SHIP_DLQ";
34
+
35
+ /**
36
+ * How many times a failed shipment is retried before it is dead-lettered. With {@link retryDelaySeconds} that is
37
+ * about five hours of a sink being unreachable before an event is given up on.
38
+ */
39
+ export const AUDIT_SHIP_MAX_RETRIES = 10;
40
+
41
+ /** The most shipments one invocation takes. Each sink's share of a batch is one request to it. */
42
+ export const AUDIT_SHIP_MAX_BATCH = 50;
43
+
44
+ /** The first retry's delay, in seconds. Each one after doubles it. */
45
+ const FIRST_RETRY_SECONDS = 30;
46
+
47
+ /** The longest one retry waits, in seconds. */
48
+ const LONGEST_RETRY_SECONDS = 3600;
49
+
50
+ /** How long the retry after this attempt waits: doubling from 30 seconds, never past an hour. */
51
+ export function retryDelaySeconds(attempts: number): number {
52
+ const exponent = Math.max(0, Math.min(attempts - 1, 20));
53
+ return Math.min(FIRST_RETRY_SECONDS * 2 ** exponent, LONGEST_RETRY_SECONDS);
54
+ }
55
+
56
+ /** Whether this was a message's last delivery: the one whose failure dead-letters it. */
57
+ export function isFinalAttempt(attempts: number, maxRetries: number = AUDIT_SHIP_MAX_RETRIES): boolean {
58
+ return attempts > maxRetries;
59
+ }
60
+
61
+ /** One shipment: one event, to one sink. */
62
+ export const ShipMessage = z
63
+ .object({
64
+ capability: z.literal(AUDIT_QUEUE_CAPABILITY).describe("The capability the message belongs to."),
65
+ sink: z.string().min(1).describe("The sink the event is shipped to, by its declared name."),
66
+ eventId: z.string().min(1).describe("The event's stable public id — the row the consumer reads back."),
67
+ })
68
+ .describe("One audit event, to one sink. Names only; the row is read back at delivery.");
69
+ export type ShipMessage = z.infer<typeof ShipMessage>;
70
+
71
+ /** The queue bindings shipping needs: none without a sink, the queue and its dead-letter queue with one. */
72
+ export function shipBindings(sinks: AuditSinks): BindingSpecInput[] {
73
+ if (Object.keys(sinks).length === 0) return [];
74
+ return [
75
+ {
76
+ type: "queue",
77
+ name: AUDIT_SHIP_BINDING,
78
+ consumer: {
79
+ deadLetter: AUDIT_SHIP_DLQ_BINDING,
80
+ maxRetries: AUDIT_SHIP_MAX_RETRIES,
81
+ maxBatchSize: AUDIT_SHIP_MAX_BATCH,
82
+ },
83
+ },
84
+ // Bound as a producer only so `pithy provision` creates it and `pithy upgrade` writes it; nothing in the kit sends
85
+ // to it or reads it, so a Worker missing it still boots. A message lands there from Cloudflare, once its retries
86
+ // are spent, and waits for a person.
87
+ { type: "queue", name: AUDIT_SHIP_DLQ_BINDING, optional: true },
88
+ ];
89
+ }
90
+
91
+ /**
92
+ * Put one event on the queue for every sink that takes it. Throws only what the queue throws; the recorder catches
93
+ * it, because a failed enqueue never fails the write it follows.
94
+ */
95
+ export async function enqueueShipments(
96
+ queue: ShipQueue,
97
+ sinks: AuditSinks,
98
+ event: { eventId: string; action: string },
99
+ ): Promise<number> {
100
+ const targets = sinksFor(sinks, event.action);
101
+ if (targets.length === 0) return 0;
102
+ await queue.sendBatch(
103
+ targets.map((sink) => ({
104
+ body: queueBody(AUDIT_QUEUE_CAPABILITY, { sink, eventId: event.eventId }) satisfies ShipMessage,
105
+ })),
106
+ );
107
+ return targets.length;
108
+ }
@@ -0,0 +1,42 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+
4
+ import { defineSecretRegistry, type SecretRegistry } from "@pithy-sh/secrets/src/registry";
5
+ import type { AuditSinks } from "./sinks";
6
+
7
+ /**
8
+ * **Each sink's token, declared where every secret is (#824).**
9
+ *
10
+ * A sink names the `@pithy-sh/secrets` name its token lives under, and this declares it: a per-environment `d1`
11
+ * secret, `text`, obtained from the receiver's own console and replaced there by hand. Declared on audit's
12
+ * `secretRegistry`, so `pithy secrets create` knows the name, `pithy doctor` can say whether it is set, and the
13
+ * consumer reads it through the one `secretsStore` reader like every other secret. Two sinks may share one token by
14
+ * naming the same secret; it is declared once.
15
+ *
16
+ * Nothing here is a Cloudflare API token, so nothing joins the application's runtime token.
17
+ */
18
+
19
+ /** Where an operator is told to look for the token, whichever receiver issues it. */
20
+ const SINK_TOKEN_DOCUMENTATION =
21
+ "https://github.com/pithy-sh/pithy/blob/main/packages/audit/README.md#shipping-the-trail";
22
+
23
+ /** The registry slice for every sink's token. Empty when no sink is declared. */
24
+ export function sinkSecretsRegistry(sinks: AuditSinks): SecretRegistry {
25
+ const names = [...new Set(Object.values(sinks).map((sink) => sink.secret))];
26
+ return defineSecretRegistry(
27
+ Object.fromEntries(
28
+ names.map((name) => [
29
+ name,
30
+ {
31
+ backend: "d1",
32
+ scope: "environment",
33
+ rotatable: false,
34
+ valueType: "text",
35
+ origin: { kind: "obtained", issuer: "other", documentation: SINK_TOKEN_DOCUMENTATION },
36
+ rotation: { kind: "manual", issuer: "other", documentation: SINK_TOKEN_DOCUMENTATION },
37
+ notes: "An audit sink's token: the Splunk HEC token, the Datadog API key, or the webhook's bearer token.",
38
+ } as const,
39
+ ]),
40
+ ),
41
+ );
42
+ }
@@ -0,0 +1,32 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+
4
+ import { pithyCommand } from "@pithy-sh/core/src/cli/command";
5
+ import { InternalError } from "@pithy-sh/core/src/error/pithyError";
6
+ import { AUDIT_SHIP_BINDING, enqueueShipments, type ShipQueue } from "./queue";
7
+ import type { AuditSinks } from "./sinks";
8
+
9
+ /**
10
+ * The recorder's `ship` hook over one env's queue binding (#824), or nothing when no sink is declared.
11
+ *
12
+ * The binding is read when an event is shipped, not when the hook is built: a Worker deployed before `pithy upgrade`
13
+ * wrote the binding still records every event, and the shipment that could not be enqueued is said, never thrown
14
+ * into the write.
15
+ */
16
+ export function shipperFor(
17
+ env: Record<string, unknown> | undefined,
18
+ sinks: AuditSinks,
19
+ ): ((event: { eventId: string; action: string }) => Promise<void>) | undefined {
20
+ if (Object.keys(sinks).length === 0) return undefined;
21
+ return async (event) => {
22
+ const queue = env?.[AUDIT_SHIP_BINDING] as ShipQueue | undefined;
23
+ if (typeof queue?.sendBatch !== "function") {
24
+ throw new InternalError({
25
+ message: "Audit sinks are declared and this Worker binds no shipping queue.",
26
+ action: `Run ${pithyCommand("upgrade")} to write the ${AUDIT_SHIP_BINDING} queue binding, then ${pithyCommand("provision")}.`,
27
+ detail: `no ${AUDIT_SHIP_BINDING} binding on env; event ${event.eventId} was recorded and not shipped`,
28
+ });
29
+ }
30
+ await enqueueShipments(queue, sinks, event);
31
+ };
32
+ }
@@ -0,0 +1,82 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+
4
+ import { z } from "zod";
5
+
6
+ /**
7
+ * **Where the trail is shipped: sinks, declared in `pithy.config.ts` (#824).**
8
+ *
9
+ * A sink is reviewed and deployed like code. No control-plane route adds, changes or removes one, so no management
10
+ * credential can point the trail somewhere new — the same reason audit has no route that writes. Each sink names its
11
+ * profile, its URL, the `@pithy-sh/secrets` name its token is read through, and optionally which actions it takes
12
+ * and whether it ships personal values.
13
+ *
14
+ * Strict objects, so a misspelled key (`detial: true`) is refused at config load rather than read as the default
15
+ * it was trying to change. A profile nobody wrote a format for, a URL that is not HTTPS, and a sink with no secret
16
+ * name are refused the same way, before the Worker serves anything.
17
+ */
18
+
19
+ /** The formats a sink speaks. One per receiver's own documented ingestion API, and a generic one for the rest. */
20
+ export const AuditSinkProfile = z
21
+ .enum(["splunk-hec", "datadog-logs", "webhook"])
22
+ .describe(
23
+ "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.",
24
+ );
25
+ export type AuditSinkProfile = z.infer<typeof AuditSinkProfile>;
26
+
27
+ /** A sink's name: the key it is declared under, reported by `pithy doctor` and on the manifest's health. */
28
+ export const AUDIT_SINK_NAME = /^[a-z][a-z0-9-]*$/;
29
+
30
+ /** A secret name, as `@pithy-sh/secrets` stores one: kebab-case, never a keyspace member. */
31
+ const SECRET_NAME = /^[a-z][a-z0-9-]*$/;
32
+
33
+ export const AuditSink = z
34
+ .strictObject({
35
+ profile: AuditSinkProfile,
36
+ url: z
37
+ .url({ protocol: /^https$/, hostname: z.regexes.domain })
38
+ .describe(
39
+ "The HTTPS endpoint events are posted to — the collector's full URL, path included, e.g. `https://splunk.example.com:8088/services/collector/event`.",
40
+ ),
41
+ secret: z
42
+ .string()
43
+ .regex(SECRET_NAME, "A secret name is kebab-case: lowercase letters, digits and hyphens.")
44
+ .describe(
45
+ "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>`.",
46
+ ),
47
+ actions: z
48
+ .array(z.string().min(1).describe("An action prefix, e.g. `auth/` or `controlplane/connection`."))
49
+ .min(1)
50
+ .readonly()
51
+ .optional()
52
+ .describe(
53
+ "Ship only events whose action starts with one of these prefixes. Absent ships every event the trail records.",
54
+ ),
55
+ detail: z
56
+ .boolean()
57
+ .default(false)
58
+ .describe(
59
+ "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.",
60
+ ),
61
+ })
62
+ .describe("One destination the audit trail is shipped to as it is written.");
63
+ export type AuditSink = z.output<typeof AuditSink>;
64
+ export type AuditSinkInput = z.input<typeof AuditSink>;
65
+
66
+ export const AuditSinks = z
67
+ .record(
68
+ z.string().regex(AUDIT_SINK_NAME, "A sink name is kebab-case: lowercase letters, digits and hyphens."),
69
+ AuditSink,
70
+ )
71
+ .describe("The sinks the trail is shipped to, by name. Empty ships nothing and binds no queue.");
72
+ export type AuditSinks = z.output<typeof AuditSinks>;
73
+
74
+ /** Whether a sink takes an event with this action — every action when it names no prefixes. */
75
+ export function sinkTakes(sink: Pick<AuditSink, "actions">, action: string): boolean {
76
+ return sink.actions === undefined || sink.actions.some((prefix) => action.startsWith(prefix));
77
+ }
78
+
79
+ /** The sinks, by name, that take an event with this action, in declaration order. */
80
+ export function sinksFor(sinks: AuditSinks, action: string): string[] {
81
+ return Object.entries(sinks).flatMap(([name, sink]) => (sinkTakes(sink, action) ? [name] : []));
82
+ }
@@ -0,0 +1,61 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+
4
+ import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
5
+ import { sql } from "kysely";
6
+ import { AuditSinkStateRow } from "../data/sinkState";
7
+ import type { AuditDatabase } from "../data/tables";
8
+
9
+ /**
10
+ * **Each sink's delivery state, kept by the consumer and read by the health keys (#824).**
11
+ *
12
+ * `retrying` is the backlog the queue cannot be asked for: an event joins it the first time a delivery to the sink
13
+ * fails, and leaves it when a retry lands or when its last retry fails and it is dead-lettered. Counts move by
14
+ * upsert, one statement per sink per batch, and never below zero.
15
+ */
16
+
17
+ /** What one batch did to one sink. */
18
+ export interface SinkOutcome {
19
+ /** The batch landed, or it did not. */
20
+ delivered: boolean;
21
+ /** When. */
22
+ at: Date;
23
+ /** The change to the backlog: events newly waiting on a retry, less those that stopped waiting. */
24
+ retryingDelta: number;
25
+ /** Events given up on: their last retry failed, and they went to the dead-letter queue. */
26
+ deadLettered: number;
27
+ }
28
+
29
+ /** Record one batch's outcome for one sink. */
30
+ export async function recordSinkOutcome(db: AuditDatabase, sink: string, outcome: SinkOutcome): Promise<void> {
31
+ const at = SQLiteDate.encode(outcome.at) as number;
32
+ const delta = outcome.retryingDelta;
33
+ await db
34
+ .insertInto("pithyAuditSinks")
35
+ .values({
36
+ sink,
37
+ lastDeliveredAt: outcome.delivered ? at : null,
38
+ lastFailedAt: outcome.delivered ? null : at,
39
+ retrying: Math.max(delta, 0),
40
+ deadLettered: outcome.deadLettered,
41
+ })
42
+ .onConflict((conflict) =>
43
+ conflict.column("sink").doUpdateSet({
44
+ ...(outcome.delivered ? { lastDeliveredAt: at } : { lastFailedAt: at }),
45
+ retrying: sql<number>`max(${sql.ref("retrying")} + ${delta}, 0)`,
46
+ deadLettered: sql<number>`${sql.ref("deadLettered")} + ${outcome.deadLettered}`,
47
+ }),
48
+ )
49
+ .execute();
50
+ }
51
+
52
+ /** The declared sinks' rows, decoded. A sink with no row yet has done nothing and is absent. */
53
+ export async function readSinkStates(db: AuditDatabase, sinks: readonly string[]): Promise<AuditSinkStateRow[]> {
54
+ if (sinks.length === 0) return [];
55
+ const rows = await db
56
+ .selectFrom("pithyAuditSinks")
57
+ .selectAll()
58
+ .where("sink", "in", [...sinks])
59
+ .execute();
60
+ return rows.map((row) => AuditSinkStateRow.parse(row));
61
+ }
package/src/usage.ts ADDED
@@ -0,0 +1,176 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+
4
+ import { ControlPlaneAuditActions } from "@pithy-sh/core/src/controlPlane/audit/actions";
5
+ import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
6
+ import { sql } from "kysely";
7
+ import { z } from "zod";
8
+ import type { AuditDatabase } from "./data/tables";
9
+
10
+ /**
11
+ * Which scopes a control-plane connection exercised, and which it was refused — `#812`.
12
+ *
13
+ * Every admitted call writes `controlplane/call_allowed`, and every verified call refused a scope writes
14
+ * `controlplane/call_denied`, both against the connection as `resourceId` and both naming the scope and key in
15
+ * `metadata`. Answering "granted twelve, used three" from the listing would take one forensic read per event, behind
16
+ * the scope that also discloses the client IP; this reads the same rows in SQL and returns counts.
17
+ *
18
+ * **One statement for the aggregate, never a page walk.** A dashboard connection makes thousands of calls a day, and a
19
+ * handler that paged them to count would be the largest read on the surface. The `GROUP BY` runs in D1, over rows
20
+ * `pithyAuditEventsCallIdx` (`audit_0003_call_index`) finds by action, connection and time.
21
+ *
22
+ * **Nothing personal leaves this function.** It reads the scope, the key id, and the method and path of the last
23
+ * allowed call out of `metadata`, and no other key, and never the IP or the user-agent. Those four are the management
24
+ * client's own footprint.
25
+ */
26
+
27
+ /** What to count: one connection, over an inclusive window. */
28
+ export interface ControlPlaneUsageFilter {
29
+ /** The connection whose calls are counted — the rows' `resourceId`. */
30
+ connectionId: string;
31
+ /** Inclusive lower bound on `occurredAt`. */
32
+ since: Date;
33
+ /** Inclusive upper bound on `occurredAt`. */
34
+ until: Date;
35
+ }
36
+
37
+ /** The two actions that record a call the gate decided. */
38
+ const CALL_ACTIONS = [ControlPlaneAuditActions.callAllowed, ControlPlaneAuditActions.callDenied];
39
+
40
+ /** The resource type every attributed call row carries. */
41
+ const CONNECTION_RESOURCE = "controlplane_connection";
42
+
43
+ /**
44
+ * One `(scope, keyId)` a connection exercised, decoded from the aggregate's row.
45
+ *
46
+ * Internal: the wire shape is `ControlPlaneUsageView` in `http/responses.ts`, and `http/views.ts` projects this into it.
47
+ */
48
+ export const ControlPlaneUsageRow = z
49
+ .object({
50
+ scope: z
51
+ .string()
52
+ .describe(
53
+ "The scope exercised: what an allowed call's token carried, or what a refused call required — `metadata.required` from the gate, `metadata.scope` from a handler.",
54
+ ),
55
+ keyId: z
56
+ .string()
57
+ .nullable()
58
+ .describe("The registered key that signed the calls. Null for a row that recorded none."),
59
+ allowed: z.number().int().describe("How many `controlplane/call_allowed` events in the window."),
60
+ denied: z.number().int().describe("How many `controlplane/call_denied` events in the window."),
61
+ lastAllowedAt: SQLiteDate.nullable().describe("When the last allowed call landed. Null when none was allowed."),
62
+ lastAllowedMethod: z.string().nullable().describe("The HTTP method of the last allowed call, or null."),
63
+ lastAllowedPath: z.string().nullable().describe("The path of the last allowed call, or null."),
64
+ lastDeniedAt: SQLiteDate.nullable().describe("When the last refusal landed. Null when none was refused."),
65
+ })
66
+ .describe("One scope and key a control-plane connection exercised in a window, with its counts.");
67
+ export type ControlPlaneUsageRow = z.output<typeof ControlPlaneUsageRow>;
68
+
69
+ /** The oldest event the trail holds, decoded. */
70
+ const OldestEvent = z
71
+ .object({
72
+ oldest: SQLiteDate.nullable().describe("The smallest `occurredAt` in the trail, or null when it is empty."),
73
+ })
74
+ .describe("How far back the trail reaches.");
75
+
76
+ /** What {@link controlPlaneUsage} answers. */
77
+ export interface ControlPlaneUsage {
78
+ /** One row per `(scope, keyId)` exercised, ordered by scope then key. */
79
+ usage: ControlPlaneUsageRow[];
80
+ /** The oldest event the trail holds, or null on an empty trail. */
81
+ oldestEventAt: Date | null;
82
+ }
83
+
84
+ /**
85
+ * The aggregate, as one Kysely statement — exported so a test can read its query plan.
86
+ *
87
+ * Three steps, in one statement:
88
+ *
89
+ * 1. **`calls`** — the connection's call rows in the window, with the scope, key, method and path lifted out of
90
+ * `metadata`. The scope is read from where each writer puts it: an allowed row carries the token's `scope`; a gate
91
+ * refusal names the scope it required as `required`, and a handler's refusal as `scope`, so a denied row reads
92
+ * `required` first. A row with no scope at all is nobody's usage and is dropped.
93
+ * 2. **`ranked`** — each row's recency within its `(scope, keyId, action)`, newest first, `id` breaking a tie. Rank 1
94
+ * of the allowed rows is the last allowed call, whose method and path the answer carries.
95
+ * 3. **The group** — counts and last instants per `(scope, keyId)`.
96
+ */
97
+ export function controlPlaneUsageStatement(db: AuditDatabase, filter: ControlPlaneUsageFilter) {
98
+ const allowed = ControlPlaneAuditActions.callAllowed;
99
+ const denied = ControlPlaneAuditActions.callDenied;
100
+ return db
101
+ .with("calls", (q) =>
102
+ q
103
+ .selectFrom("pithyAuditEvents")
104
+ .select((eb) => [
105
+ "id",
106
+ "action",
107
+ "occurredAt",
108
+ sql<string | null>`case when ${eb.ref("action")} = ${denied}
109
+ then coalesce(json_extract(${eb.ref("metadata")}, '$.required'), json_extract(${eb.ref("metadata")}, '$.scope'))
110
+ else json_extract(${eb.ref("metadata")}, '$.scope') end`.as("scope"),
111
+ sql<string | null>`json_extract(${eb.ref("metadata")}, '$.keyId')`.as("keyId"),
112
+ sql<string | null>`json_extract(${eb.ref("metadata")}, '$.method')`.as("method"),
113
+ sql<string | null>`json_extract(${eb.ref("metadata")}, '$.path')`.as("path"),
114
+ ])
115
+ // In `pithyAuditEventsCallIdx`'s column order: the actions, the connection, then the window.
116
+ .where("action", "in", CALL_ACTIONS)
117
+ .where("resourceId", "=", filter.connectionId)
118
+ .where("occurredAt", ">=", SQLiteDate.encode(filter.since))
119
+ .where("occurredAt", "<=", SQLiteDate.encode(filter.until))
120
+ .where("resourceType", "=", CONNECTION_RESOURCE),
121
+ )
122
+ .with("ranked", (q) =>
123
+ q
124
+ .selectFrom("calls")
125
+ .selectAll()
126
+ .select(
127
+ sql<number>`row_number() over (
128
+ partition by ${sql.ref("scope")}, ${sql.ref("keyId")}, ${sql.ref("action")}
129
+ order by ${sql.ref("occurredAt")} desc, ${sql.ref("id")} desc)`.as("recency"),
130
+ )
131
+ .where("scope", "is not", null),
132
+ )
133
+ .selectFrom("ranked")
134
+ .select((eb) => [
135
+ "scope",
136
+ "keyId",
137
+ sql<number>`sum(case when ${eb.ref("action")} = ${allowed} then 1 else 0 end)`.as("allowed"),
138
+ sql<number>`sum(case when ${eb.ref("action")} = ${denied} then 1 else 0 end)`.as("denied"),
139
+ sql<number | null>`max(case when ${eb.ref("action")} = ${allowed} then ${eb.ref("occurredAt")} end)`.as(
140
+ "lastAllowedAt",
141
+ ),
142
+ sql<string | null>`max(case when ${eb.ref("action")} = ${allowed} and ${eb.ref("recency")} = 1
143
+ then ${eb.ref("method")} end)`.as("lastAllowedMethod"),
144
+ sql<string | null>`max(case when ${eb.ref("action")} = ${allowed} and ${eb.ref("recency")} = 1
145
+ then ${eb.ref("path")} end)`.as("lastAllowedPath"),
146
+ sql<number | null>`max(case when ${eb.ref("action")} = ${denied} then ${eb.ref("occurredAt")} end)`.as(
147
+ "lastDeniedAt",
148
+ ),
149
+ ])
150
+ .groupBy(["scope", "keyId"])
151
+ .orderBy("scope")
152
+ .orderBy("keyId");
153
+ }
154
+
155
+ /**
156
+ * Count one connection's calls by scope and key, over an inclusive window.
157
+ *
158
+ * `oldestEventAt` is the oldest event the trail holds at all, for any connection or none. Retention prunes the trail
159
+ * by time, never per connection, so this is how far back any connection's answer can reach: a window starting before
160
+ * it was not fully covered, and a client can say so rather than read a short count as a quiet connection. Read through
161
+ * `pithyAuditEventsOccurredAtIdx`, so it costs one index probe however large the trail is.
162
+ */
163
+ export async function controlPlaneUsage(
164
+ db: AuditDatabase,
165
+ filter: ControlPlaneUsageFilter,
166
+ ): Promise<ControlPlaneUsage> {
167
+ const rows = await controlPlaneUsageStatement(db, filter).execute();
168
+ const oldest = await db
169
+ .selectFrom("pithyAuditEvents")
170
+ .select((eb) => eb.fn.min("occurredAt").as("oldest"))
171
+ .executeTakeFirst();
172
+ return {
173
+ usage: rows.map((row) => ControlPlaneUsageRow.parse(row)),
174
+ oldestEventAt: OldestEvent.parse({ oldest: oldest?.oldest ?? null }).oldest,
175
+ };
176
+ }
@@ -13,4 +13,4 @@
13
13
  export const PACKAGE_NAME = "@pithy-sh/audit";
14
14
 
15
15
  /** This package's version, stamped from its own package.json at generation time. */
16
- export const PACKAGE_VERSION = "0.5.0";
16
+ export const PACKAGE_VERSION = "0.7.0";