@pithy-sh/audit 0.7.1 → 0.9.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 (46) hide show
  1. package/README.md +1 -1
  2. package/dist/capability.d.ts +1 -1
  3. package/dist/capability.d.ts.map +1 -1
  4. package/dist/capability.js +4 -3
  5. package/dist/http/guards.d.ts +7 -3
  6. package/dist/http/guards.d.ts.map +1 -1
  7. package/dist/http/guards.js +16 -4
  8. package/dist/http/responses.d.ts +122 -0
  9. package/dist/http/responses.d.ts.map +1 -1
  10. package/dist/http/responses.js +38 -1
  11. package/dist/http/routes.d.ts +8 -3
  12. package/dist/http/routes.d.ts.map +1 -1
  13. package/dist/http/routes.js +48 -16
  14. package/dist/http/schemas.d.ts +7 -5
  15. package/dist/http/schemas.d.ts.map +1 -1
  16. package/dist/http/schemas.js +9 -7
  17. package/dist/http/views.d.ts +20 -5
  18. package/dist/http/views.d.ts.map +1 -1
  19. package/dist/http/views.js +53 -5
  20. package/dist/query.d.ts +2 -0
  21. package/dist/query.d.ts.map +1 -1
  22. package/dist/query.js +1 -0
  23. package/dist/ship/consumer.js +1 -1
  24. package/dist/ship/delivery.d.ts +13 -0
  25. package/dist/ship/delivery.d.ts.map +1 -0
  26. package/dist/ship/delivery.js +21 -0
  27. package/dist/ship/health.d.ts +2 -11
  28. package/dist/ship/health.d.ts.map +1 -1
  29. package/dist/ship/health.js +4 -18
  30. package/dist/usage.d.ts +29 -12
  31. package/dist/usage.d.ts.map +1 -1
  32. package/dist/usage.js +23 -9
  33. package/dist/version.generated.d.ts +1 -1
  34. package/dist/version.generated.js +1 -1
  35. package/package.json +3 -3
  36. package/src/capability.ts +19 -20
  37. package/src/http/guards.ts +17 -4
  38. package/src/http/responses.ts +109 -0
  39. package/src/http/routes.ts +74 -20
  40. package/src/http/schemas.ts +21 -8
  41. package/src/http/views.ts +58 -5
  42. package/src/query.ts +7 -0
  43. package/src/ship/delivery.ts +23 -0
  44. package/src/ship/health.ts +3 -21
  45. package/src/usage.ts +37 -16
  46. package/src/version.generated.ts +1 -1
package/README.md CHANGED
@@ -82,7 +82,7 @@ Set the token with `pithy secrets create splunk-hec-token --env prod`, then run
82
82
 
83
83
  **Declared, not toggled.** A sink is reviewed and deployed like code. No control-plane route adds, changes or removes one, so no management credential can point the trail somewhere new.
84
84
 
85
- **Delivered at least once, and never in the way.** Each event a Worker writes goes on the `AUDIT_SHIP` queue once per sink that takes it, naming the event and the sink and nothing else; the Worker's own consumer reads the row back and posts each sink's share of a batch in one request. Enqueueing happens after the write and never fails it. A redirect is never followed, so the token and the batch go only to the URL you declared; a sink answering 3xx counts as a refusal. A sink that refuses or cannot be reached retries after 30 seconds, doubling to an hour, and fails alone: the other sinks still deliver. After ten retries a message goes to `AUDIT_SHIP_DLQ` and waits there for a person. Audit's manifest entry reports `auditShipBacklog`, `auditShipDeadLettered` and `auditShipDelivery` (`delivering`, `failing`, `idle`), behind `audit:events:read`, and `pithy doctor` lists every sink and whether each environment holds its token.
85
+ **Delivered at least once, and never in the way.** Each event a Worker writes goes on the `AUDIT_SHIP` queue once per sink that takes it, naming the event and the sink and nothing else; the Worker's own consumer reads the row back and posts each sink's share of a batch in one request. Enqueueing happens after the write and never fails it. A redirect is never followed, so the token and the batch go only to the URL you declared; a sink answering 3xx counts as a refusal. A sink that refuses or cannot be reached retries after 30 seconds, doubling to an hour, and fails alone: the other sinks still deliver. After ten retries a message goes to `AUDIT_SHIP_DLQ` and waits there for a person. Audit's manifest entry reports `auditShipBacklog`, `auditShipDeadLettered` and `auditShipDelivery` (`delivering`, `failing`, `idle`), behind `audit:events:read`, each across every sink: the two counts summed, and the state `failing` when any sink is. `GET /audit/control-plane/sinks`, behind the same scope, answers each sink on its own, in declaration order: its name, profile, host, `detail` flag and `actions` filter, its `lastDeliveredAt` and `lastFailedAt`, its `retrying` backlog, its `deadLettered` count and its own `delivery` state. Never its token, its URL path or query, or an event. `pithy doctor` lists every sink and whether each environment holds its token.
86
86
 
87
87
  **Redacted by default.** Without `detail: true`, no IP, user-agent or metadata value leaves the Worker. The sink receives their salted commitments instead — the same ones the chain hashes — which verify and disclose nothing. With `detail: true` the values and their salt travel, so the receiver can check the commitments too.
88
88
 
@@ -41,7 +41,7 @@ export type AuditConfigInput = z.input<typeof AuditConfig>;
41
41
  export interface AuditCapability extends Capability {
42
42
  /** The D1 binding the audit table lives in (the resolved `database` config). */
43
43
  auditDatabase: string;
44
- /** The sinks the trail ships to (#824), as declared — what `pithy doctor` lists. */
44
+ /** The sinks the trail ships to, as declared — what `pithy doctor` lists. */
45
45
  auditSinks: AuditSinks;
46
46
  }
47
47
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,0CAA0C,CAAC;AAQ7F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsBxB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI1C;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAWzC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;iBAiB8B,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AACvD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,UAAU,EAAE,UAAU,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,MAAM,GAAE,gBAAqB,GAAG,eAAe,CAiLpE;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,eAAe,CAEvF"}
1
+ {"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,0CAA0C,CAAC;AAQ7F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsBxB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI1C;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAWzC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;iBAiB8B,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AACvD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,UAAU,EAAE,UAAU,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,MAAM,GAAE,gBAAqB,GAAG,eAAe,CAgLpE;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,eAAe,CAEvF"}
@@ -6,6 +6,7 @@ import { checkpointLockCheck } from "./chain/lockCheck.js";
6
6
  import { auditDatabase, auditTables } from "./data/tables.js";
7
7
  import { auditCitationsFor } from "./citations.js";
8
8
  import { auditAdminRoutes } from "./http/guards.js";
9
+ import { AuditSinks } from "./ship/sinks.js";
9
10
  import { registerAuditRoutes } from "./http/routes.js";
10
11
  import { audit_0001_init } from "./migrations/0001_init.js";
11
12
  import { audit_0002_actor_kind } from "./migrations/0002_actor_kind.js";
@@ -16,7 +17,6 @@ import { audit_0006_sinks } from "./migrations/0006_sinks.js";
16
17
  import { auditUserPurge } from "./purge/contribution.js";
17
18
  import { recordAuditEvent } from "./recorder.js";
18
19
  import { auditExampleSeed } from "./seeds/example.js";
19
- import { AuditSinks } from "./ship/sinks.js";
20
20
  import { shipBindings } from "./ship/queue.js";
21
21
  import { auditShipConsumer } from "./ship/consumer.js";
22
22
  import { shipHealth } from "./ship/health.js";
@@ -42,7 +42,7 @@ const AUDIT_MIGRATION_ORDER = 250;
42
42
  * database (`app`, the `DB` binding) by default — so the audit migration tracks alongside the app's
43
43
  * in one `pithy_migrations` table rather than fighting it on a second provider over the same binding.
44
44
  * The physical binding is config-selectable; this registry key is the coordination point capabilities
45
- * use to share one database (CLAUDE.md §Data layer; isolating audit into its own D1 is a later issue).
45
+ * use to share one database (CLAUDE.md §Data layer).
46
46
  */
47
47
  const AUDIT_DATABASE_NAME = "app";
48
48
  /**
@@ -166,7 +166,8 @@ function audit(config = {}) {
166
166
  checkpoints: (c) => {
167
167
  const bucket = c.env?.[AUDIT_CHECKPOINT_BINDING];
168
168
  return typeof bucket === "object" && bucket !== null ? bucket : null;
169
- }
169
+ },
170
+ sinks
170
171
  }),
171
172
  middleware: [(app) => {
172
173
  app.use("*", async (c, next) => {
@@ -37,9 +37,9 @@ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/sc
37
37
  * the other.
38
38
  *
39
39
  * **Usage rides the listing scope.** `GET {base}/control-plane/usage` counts one connection's calls by scope
40
- * and key. Its answer is the scope, the key id, and the method and path of the last allowed call — the management
41
- * client's own footprint, which the listing already discloses in shape through `action`, `actorId` and `resourceId`
42
- * — and never an IP, a user-agent, or any other metadata key. So it needs no detail scope, and an access review does
40
+ * and key, or every connection's. Its answer is the connection, the scope, the key id, and the method and path of the
41
+ * last allowed call — the management client's own footprint, which the listing already discloses in shape through
42
+ * `action`, `actorId` and `resourceId` — and never an IP, a user-agent, or any other metadata key. So it needs no detail scope, and an access review does
43
43
  * not have to hold the most dangerous grant audit defines to ask which grants are used.
44
44
  *
45
45
  * **The access history rides the listing scope.** `GET {base}/control-plane/access-history` answers every
@@ -53,6 +53,10 @@ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/sc
53
53
  * already names in `resourceId`, and the tenant is what it shows as `tenant`; the answer never carries an IP, a user-agent, or a metadata key beyond the key id, scope, method and
54
54
  * path. So a breach review does not need the detail scope to draw a breach scope.
55
55
  *
56
+ * **The sinks ride the listing scope.** `GET {base}/control-plane/sinks` answers each declared sink's name, profile,
57
+ * host, filter and delivery state — what the manifest's health keys already total behind the same scope. It never
58
+ * carries a token, a secret name, a URL path or query, an event, or anything a receiver answered.
59
+ *
56
60
  * **The chain has a scope of its own.** `GET {base}/control-plane/verify` walks one tenant's chain, and
57
61
  * `GET {base}/control-plane/export` takes it out in canonical form with its checkpoints. An export is the trail in
58
62
  * bulk, meant to leave the building, so neither read rides the listing scope: both need `audit:events:export`. The
@@ -1 +1 @@
1
- {"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/http/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAC;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAAuC,CAAC;AAE7E;;;GAGG;AACH,eAAO,MAAM,6BAA6B,EAAE,iBAA8C,CAAC;AAE3F;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAAyC,CAAC;AAEjF;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,iBAAiB,EAIlE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAiE1E"}
1
+ {"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/http/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAC;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAAuC,CAAC;AAE7E;;;GAGG;AACH,eAAO,MAAM,6BAA6B,EAAE,iBAA8C,CAAC;AAE3F;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAAyC,CAAC;AAEjF;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,iBAAiB,EAIlE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,EAAE,CA0E1E"}
@@ -36,9 +36,9 @@
36
36
  * the other.
37
37
  *
38
38
  * **Usage rides the listing scope.** `GET {base}/control-plane/usage` counts one connection's calls by scope
39
- * and key. Its answer is the scope, the key id, and the method and path of the last allowed call — the management
40
- * client's own footprint, which the listing already discloses in shape through `action`, `actorId` and `resourceId`
41
- * — and never an IP, a user-agent, or any other metadata key. So it needs no detail scope, and an access review does
39
+ * and key, or every connection's. Its answer is the connection, the scope, the key id, and the method and path of the
40
+ * last allowed call — the management client's own footprint, which the listing already discloses in shape through
41
+ * `action`, `actorId` and `resourceId` — and never an IP, a user-agent, or any other metadata key. So it needs no detail scope, and an access review does
42
42
  * not have to hold the most dangerous grant audit defines to ask which grants are used.
43
43
  *
44
44
  * **The access history rides the listing scope.** `GET {base}/control-plane/access-history` answers every
@@ -52,6 +52,10 @@
52
52
  * already names in `resourceId`, and the tenant is what it shows as `tenant`; the answer never carries an IP, a user-agent, or a metadata key beyond the key id, scope, method and
53
53
  * path. So a breach review does not need the detail scope to draw a breach scope.
54
54
  *
55
+ * **The sinks ride the listing scope.** `GET {base}/control-plane/sinks` answers each declared sink's name, profile,
56
+ * host, filter and delivery state — what the manifest's health keys already total behind the same scope. It never
57
+ * carries a token, a secret name, a URL path or query, an event, or anything a receiver answered.
58
+ *
55
59
  * **The chain has a scope of its own.** `GET {base}/control-plane/verify` walks one tenant's chain, and
56
60
  * `GET {base}/control-plane/export` takes it out in canonical form with its checkpoints. An export is the trail in
57
61
  * bulk, meant to leave the building, so neither read rides the listing scope: both need `audit:events:export`. The
@@ -134,7 +138,7 @@ function auditAdminRoutes(basePath) {
134
138
  path: `${basePath}/control-plane/usage`,
135
139
  scope: AUDIT_TRAIL_READ_SCOPE,
136
140
  kind: "reads",
137
- summary: "Count which scopes one control-plane connection exercised and was refused, by key, over a window. Counts only — no event is read in full."
141
+ summary: "Count which scopes one control-plane connection, or every one, exercised and was refused, by key, over a window. Counts only — no event is read in full."
138
142
  },
139
143
  {
140
144
  method: "GET",
@@ -152,6 +156,14 @@ function auditAdminRoutes(basePath) {
152
156
  kind: "reads",
153
157
  summary: "Export one tenant's hash chain in canonical form with its checkpoints, to verify offline. Personal values only with the detail scope."
154
158
  },
159
+ {
160
+ method: "GET",
161
+ operation: "sinks.list",
162
+ path: `${basePath}/control-plane/sinks`,
163
+ scope: AUDIT_TRAIL_READ_SCOPE,
164
+ kind: "reads",
165
+ summary: "List every sink the trail ships to, with its profile, host and filter, and its backlog, last delivery and dead letters. No event is read."
166
+ },
155
167
  {
156
168
  method: "GET",
157
169
  operation: "events.read",
@@ -576,6 +576,82 @@ export declare const ControlPlaneUsageResponse: z.ZodObject<{
576
576
  oldestEventAt: z.ZodNullable<z.ZodISODateTime>;
577
577
  }, z.core.$strip>;
578
578
  export type ControlPlaneUsageResponse = z.output<typeof ControlPlaneUsageResponse>;
579
+ /** One connection's scopes and keys, in the every-connection usage answer. */
580
+ export declare const ControlPlaneConnectionUsageView: z.ZodObject<{
581
+ connectionId: z.ZodString;
582
+ usage: z.ZodArray<z.ZodObject<{
583
+ scope: z.ZodString;
584
+ keyId: z.ZodNullable<z.ZodString>;
585
+ allowed: z.ZodNumber;
586
+ denied: z.ZodNumber;
587
+ lastAllowedAt: z.ZodNullable<z.ZodISODateTime>;
588
+ lastAllowedMethod: z.ZodNullable<z.ZodString>;
589
+ lastAllowedPath: z.ZodNullable<z.ZodString>;
590
+ lastDeniedAt: z.ZodNullable<z.ZodISODateTime>;
591
+ }, z.core.$strip>>;
592
+ }, z.core.$strip>;
593
+ export type ControlPlaneConnectionUsageView = z.output<typeof ControlPlaneConnectionUsageView>;
594
+ /**
595
+ * `GET {base}/control-plane/usage` with no `connectionId`: every connection that called in the window.
596
+ *
597
+ * A shape of its own, beside {@link ControlPlaneUsageResponse}, so the answer to a named connection is unchanged and
598
+ * a client that names one parses what it always did. Told apart by its keys: `connections` here, `connectionId` and
599
+ * `usage` there.
600
+ */
601
+ export declare const ControlPlaneUsageAllResponse: z.ZodObject<{
602
+ since: z.ZodISODateTime;
603
+ until: z.ZodISODateTime;
604
+ connections: z.ZodArray<z.ZodObject<{
605
+ connectionId: z.ZodString;
606
+ usage: z.ZodArray<z.ZodObject<{
607
+ scope: z.ZodString;
608
+ keyId: z.ZodNullable<z.ZodString>;
609
+ allowed: z.ZodNumber;
610
+ denied: z.ZodNumber;
611
+ lastAllowedAt: z.ZodNullable<z.ZodISODateTime>;
612
+ lastAllowedMethod: z.ZodNullable<z.ZodString>;
613
+ lastAllowedPath: z.ZodNullable<z.ZodString>;
614
+ lastDeniedAt: z.ZodNullable<z.ZodISODateTime>;
615
+ }, z.core.$strip>>;
616
+ }, z.core.$strip>>;
617
+ oldestEventAt: z.ZodNullable<z.ZodISODateTime>;
618
+ }, z.core.$strip>;
619
+ export type ControlPlaneUsageAllResponse = z.output<typeof ControlPlaneUsageAllResponse>;
620
+ /** What the usage route answers: one connection's usage when the query names one, every connection's when not. */
621
+ export declare const ControlPlaneUsageReadResponse: z.ZodUnion<readonly [z.ZodObject<{
622
+ connectionId: z.ZodString;
623
+ since: z.ZodISODateTime;
624
+ until: z.ZodISODateTime;
625
+ usage: z.ZodArray<z.ZodObject<{
626
+ scope: z.ZodString;
627
+ keyId: z.ZodNullable<z.ZodString>;
628
+ allowed: z.ZodNumber;
629
+ denied: z.ZodNumber;
630
+ lastAllowedAt: z.ZodNullable<z.ZodISODateTime>;
631
+ lastAllowedMethod: z.ZodNullable<z.ZodString>;
632
+ lastAllowedPath: z.ZodNullable<z.ZodString>;
633
+ lastDeniedAt: z.ZodNullable<z.ZodISODateTime>;
634
+ }, z.core.$strip>>;
635
+ oldestEventAt: z.ZodNullable<z.ZodISODateTime>;
636
+ }, z.core.$strip>, z.ZodObject<{
637
+ since: z.ZodISODateTime;
638
+ until: z.ZodISODateTime;
639
+ connections: z.ZodArray<z.ZodObject<{
640
+ connectionId: z.ZodString;
641
+ usage: z.ZodArray<z.ZodObject<{
642
+ scope: z.ZodString;
643
+ keyId: z.ZodNullable<z.ZodString>;
644
+ allowed: z.ZodNumber;
645
+ denied: z.ZodNumber;
646
+ lastAllowedAt: z.ZodNullable<z.ZodISODateTime>;
647
+ lastAllowedMethod: z.ZodNullable<z.ZodString>;
648
+ lastAllowedPath: z.ZodNullable<z.ZodString>;
649
+ lastDeniedAt: z.ZodNullable<z.ZodISODateTime>;
650
+ }, z.core.$strip>>;
651
+ }, z.core.$strip>>;
652
+ oldestEventAt: z.ZodNullable<z.ZodISODateTime>;
653
+ }, z.core.$strip>]>;
654
+ export type ControlPlaneUsageReadResponse = z.output<typeof ControlPlaneUsageReadResponse>;
579
655
  /** `GET {base}/control-plane/verify`. */
580
656
  export declare const ChainVerifyResponse: z.ZodObject<{
581
657
  tenant: z.ZodNullable<z.ZodString>;
@@ -680,4 +756,50 @@ export declare const ChainExportResponse: z.ZodObject<{
680
756
  nextCursor: z.ZodNullable<z.ZodString>;
681
757
  }, z.core.$strip>;
682
758
  export type ChainExportResponse = z.output<typeof ChainExportResponse>;
759
+ /** One declared sink, as `GET {base}/control-plane/sinks` shows it. Never its URL path, its query or its token. */
760
+ export declare const AuditSinkView: z.ZodObject<{
761
+ name: z.ZodString;
762
+ profile: z.ZodEnum<{
763
+ "datadog-logs": "datadog-logs";
764
+ "splunk-hec": "splunk-hec";
765
+ webhook: "webhook";
766
+ }>;
767
+ host: z.ZodString;
768
+ detail: z.ZodBoolean;
769
+ actions: z.ZodNullable<z.ZodArray<z.ZodString>>;
770
+ lastDeliveredAt: z.ZodNullable<z.ZodISODateTime>;
771
+ lastFailedAt: z.ZodNullable<z.ZodISODateTime>;
772
+ retrying: z.ZodNumber;
773
+ deadLettered: z.ZodNumber;
774
+ delivery: z.ZodEnum<{
775
+ delivering: "delivering";
776
+ failing: "failing";
777
+ idle: "idle";
778
+ }>;
779
+ }, z.core.$strip>;
780
+ export type AuditSinkView = z.output<typeof AuditSinkView>;
781
+ /** `GET {base}/control-plane/sinks`. */
782
+ export declare const AuditSinksResponse: z.ZodObject<{
783
+ sinks: z.ZodArray<z.ZodObject<{
784
+ name: z.ZodString;
785
+ profile: z.ZodEnum<{
786
+ "datadog-logs": "datadog-logs";
787
+ "splunk-hec": "splunk-hec";
788
+ webhook: "webhook";
789
+ }>;
790
+ host: z.ZodString;
791
+ detail: z.ZodBoolean;
792
+ actions: z.ZodNullable<z.ZodArray<z.ZodString>>;
793
+ lastDeliveredAt: z.ZodNullable<z.ZodISODateTime>;
794
+ lastFailedAt: z.ZodNullable<z.ZodISODateTime>;
795
+ retrying: z.ZodNumber;
796
+ deadLettered: z.ZodNumber;
797
+ delivery: z.ZodEnum<{
798
+ delivering: "delivering";
799
+ failing: "failing";
800
+ idle: "idle";
801
+ }>;
802
+ }, z.core.$strip>>;
803
+ }, z.core.$strip>;
804
+ export type AuditSinksResponse = z.output<typeof AuditSinksResponse>;
683
805
  //# sourceMappingURL=responses.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/http/responses.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgCxB;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmC0E,CAAC;AACtG,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAY0E,CAAC;AAC5G,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAEzE,2BAA2B;AAC3B,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAK6B,CAAC;AAC9D,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,oCAAoC;AACpC,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAEQ,CAAC;AACxC,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AA4BrE,mDAAmD;AACnD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAa4B,CAAC;AAC5D,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE,sEAAsE;AACtE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyB2C,CAAC;AAC/E,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE7E,iEAAiE;AACjE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAO2D,CAAC;AACxF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D,wDAAwD;AACxD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8BAEiE,CAAC;AAC/F,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE,iDAAiD;AACjD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAO8E,CAAC;AACjH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;iBAwC4E,CAAC;AAC/G,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE3E,sEAAsE;AACtE,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;iBA0BqE,CAAC;AAC/G,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAEzF,wCAAwC;AACxC,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgBqE,CAAC;AAC5G,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAEnF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;iBA0BgD,CAAC;AACnF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE3E,wCAAwC;AACxC,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;iBAaoE,CAAC;AAC3G,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAEnF,yCAAyC;AACzC,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2CiE,CAAC;AAClG,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAE/B,CAAC;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC"}
1
+ {"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/http/responses.ts"],"names":[],"mappings":"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"}
@@ -1,5 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import { SHIP_DELIVERY_STATES } from "../ship/delivery.js";
4
+ import { AuditSinkProfile } from "../ship/sinks.js";
3
5
  import { AuditActorType, AuditMetadata, AuditOutcome, AuditSeverity } from "@pithy-sh/core/src/audit/auditEvent";
4
6
  import { ControlPlaneActorKind } from "@pithy-sh/core/src/controlPlane/data/connection";
5
7
  import { z } from "zod";
@@ -203,6 +205,26 @@ const ControlPlaneUsageResponse = z.object({
203
205
  usage: z.array(ControlPlaneUsageView).describe("One row per scope and key exercised, ordered by scope then key."),
204
206
  oldestEventAt: z.iso.datetime().nullable().describe("The oldest event the trail holds, for any connection, or null on an empty trail. A window starting before it was not fully covered: retention removed what came before.")
205
207
  }).describe("Which scopes one control-plane connection exercised and was refused, by key, over a window.");
208
+ /** One connection's scopes and keys, in the every-connection usage answer. */
209
+ const ControlPlaneConnectionUsageView = z.object({
210
+ connectionId: z.string().describe("The connection that made the calls."),
211
+ usage: z.array(ControlPlaneUsageView).describe("One row per scope and key this connection exercised, ordered by scope then key. Never empty.")
212
+ }).describe("One control-plane connection's usage, by scope and key.");
213
+ /**
214
+ * `GET {base}/control-plane/usage` with no `connectionId`: every connection that called in the window.
215
+ *
216
+ * A shape of its own, beside {@link ControlPlaneUsageResponse}, so the answer to a named connection is unchanged and
217
+ * a client that names one parses what it always did. Told apart by its keys: `connections` here, `connectionId` and
218
+ * `usage` there.
219
+ */
220
+ const ControlPlaneUsageAllResponse = z.object({
221
+ since: z.iso.datetime().describe("The window's inclusive start, ISO-8601."),
222
+ until: z.iso.datetime().describe("The window's inclusive end, ISO-8601 — now, when the query named none."),
223
+ connections: z.array(ControlPlaneConnectionUsageView).describe("One entry per connection that made a call in the window, ordered by connection id. A connection that made none is absent: join against the connection listing for it."),
224
+ oldestEventAt: z.iso.datetime().nullable().describe("The oldest event the trail holds, for any connection, or null on an empty trail. A window starting before it was not fully covered: retention removed what came before.")
225
+ }).describe("Which scopes every control-plane connection exercised and was refused, by key, over a window.");
226
+ /** What the usage route answers: one connection's usage when the query names one, every connection's when not. */
227
+ const ControlPlaneUsageReadResponse = z.union([ControlPlaneUsageResponse, ControlPlaneUsageAllResponse]).describe("One connection's usage when `connectionId` is named, as `ControlPlaneUsageResponse`; every connection's when it is not, as `ControlPlaneUsageAllResponse`.");
206
228
  /** `GET {base}/control-plane/verify`. */
207
229
  const ChainVerifyResponse = z.object({
208
230
  tenant: z.string().nullable().describe("The tenant whose chain was walked, or null for the untenanted chain."),
@@ -223,5 +245,20 @@ const ChainVerifyResponse = z.object({
223
245
  * one schema, so what the Worker writes and what the verifier accepts cannot drift.
224
246
  */
225
247
  const ChainExportResponse = AuditChainExport.describe("One page of one tenant's audit chain: canonical events, their hashes, the link before them and the checkpoints covering them.");
248
+ /** One declared sink, as `GET {base}/control-plane/sinks` shows it. Never its URL path, its query or its token. */
249
+ const AuditSinkView = z.object({
250
+ name: z.string().describe("The sink's name, as `audit({ sinks })` declares it."),
251
+ profile: AuditSinkProfile.describe("The format the sink is delivered in: `splunk-hec`, `datadog-logs` or `webhook`."),
252
+ host: z.string().describe("The host the sink posts to, with its port when the URL names one. Never the path or query, which may carry a key."),
253
+ detail: z.boolean().describe("Whether the sink receives each event's IP, user-agent and metadata values, rather than their salted hashes."),
254
+ actions: z.array(z.string().describe("An action prefix the sink takes, e.g. `auth/`.")).nullable().describe("The action prefixes the sink takes, or null when it takes every action the trail records."),
255
+ lastDeliveredAt: z.iso.datetime().nullable().describe("When the sink last accepted a delivery, ISO-8601, or null when it never has."),
256
+ lastFailedAt: z.iso.datetime().nullable().describe("When the sink last refused a delivery or could not be reached, ISO-8601, or null when it never has."),
257
+ retrying: z.number().int().nonnegative().describe("How many events are waiting on a retry to this sink: its backlog. The manifest's `auditShipBacklog` is the sum over every sink."),
258
+ deadLettered: z.number().int().nonnegative().describe("How many events this sink never took: their retries ran out and they went to the dead-letter queue. The manifest's `auditShipDeadLettered` is the sum."),
259
+ delivery: z.enum(SHIP_DELIVERY_STATES).describe("How delivery to this sink stands: `failing` when its last attempt failed, `delivering` when it last took one, `idle` when it has never been attempted.")
260
+ }).describe("One sink the trail ships to: where, what it takes, and how delivery to it stands.");
261
+ /** `GET {base}/control-plane/sinks`. */
262
+ const AuditSinksResponse = z.object({ sinks: z.array(AuditSinkView).describe("Every declared sink, in declaration order. Empty when the Worker ships nothing.") }).describe("Every sink the trail ships to, each with its backlog, last delivery and dead letters.");
226
263
  //#endregion
227
- export { AccessChangeView, AccessHistoryResponse, AuditEventDetailView, AuditEventResponse, AuditEventView, AuditEventsResponse, ChainExportResponse, ChainVerifyResponse, ConnectionAccessChange, ControlPlaneReachResponse, ControlPlaneReachSubjectView, ControlPlaneReachView, ControlPlaneUsageResponse, ControlPlaneUsageView, KeyAccessChange, MemberAccessChange };
264
+ export { AccessChangeView, AccessHistoryResponse, AuditEventDetailView, AuditEventResponse, AuditEventView, AuditEventsResponse, AuditSinkView, AuditSinksResponse, ChainExportResponse, ChainVerifyResponse, ConnectionAccessChange, ControlPlaneConnectionUsageView, ControlPlaneReachResponse, ControlPlaneReachSubjectView, ControlPlaneReachView, ControlPlaneUsageAllResponse, ControlPlaneUsageReadResponse, ControlPlaneUsageResponse, ControlPlaneUsageView, KeyAccessChange, MemberAccessChange };
@@ -7,6 +7,7 @@ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/sc
7
7
  import type { VerificationStrategy } from "@pithy-sh/core/src/http/verification";
8
8
  import type { Context, Hono } from "hono";
9
9
  import type { AuditDatabase } from "../data/tables";
10
+ import type { AuditSinks } from "../ship/sinks";
10
11
  /**
11
12
  * The audit routes, their verification strategies, and what each accepts:
12
13
  *
@@ -16,15 +17,17 @@ import type { AuditDatabase } from "../data/tables";
16
17
  * (control-plane: audit:events:read) query: AccessHistoryQuery
17
18
  * GET /audit/control-plane/reach → what one credential reached, by tenant, route and outcome
18
19
  * (control-plane: audit:events:read) query: ControlPlaneReachQuery
19
- * GET /audit/control-plane/usage → one connection's calls, counted by scope and key
20
+ * GET /audit/control-plane/usage → one connection's calls, or every connection's, counted by scope and key
20
21
  * (control-plane: audit:events:read) query: ControlPlaneUsageQuery
21
22
  * GET /audit/control-plane/verify → whether one tenant's hash chain is whole, or where it breaks
22
23
  * (control-plane: audit:events:export) query: ChainVerifyQuery
23
24
  * GET /audit/control-plane/export → one tenant's chain in canonical form, with its checkpoints
24
25
  * (control-plane: audit:events:export) query: ChainExportQuery
26
+ * GET /audit/control-plane/sinks → every declared sink and how delivery to it stands
27
+ * (control-plane: audit:events:read) no input
25
28
  *
26
29
  * **All are reads, and there is nothing else.** The trail is append-only: no route here deletes,
27
- * edits, or prunes, because a management credential that could erase an audit row could erase the
30
+ * edits, or prunes, and no route adds, changes or removes a sink, because a management credential that could erase an audit row could erase the
28
31
  * evidence of its own use. Retention is a lifecycle concern for a Workflow, not a button on a
29
32
  * dashboard.
30
33
  *
@@ -73,10 +76,12 @@ export interface AuditRoutesOptions {
73
76
  */
74
77
  adminRoutes: () => readonly AdminRoute[];
75
78
  /**
76
- * The checkpoint bucket for this request, or null when the Worker binds none (#822). Absent, verify checks links
79
+ * The checkpoint bucket for this request, or null when the Worker binds none. Absent, verify checks links
77
80
  * alone and says so, and an export carries no checkpoints.
78
81
  */
79
82
  checkpoints?: (c: Context<PithyHonoEnv>) => R2Bucket | null;
83
+ /** The sinks the trail ships to, as declared. Absent, the sinks read answers an empty list. */
84
+ sinks?: AuditSinks;
80
85
  }
81
86
  /** Register the audit sub-router. Returned as the capability's `routes` hook. */
82
87
  export declare function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<PithyHonoEnv>) => void;
@@ -1 +1 @@
1
- {"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAE7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sDAAsD,CAAC;AAEvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAIrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAI1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAiCpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IACvB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AAED,wCAAwC;AACxC,eAAO,MAAM,YAAY,EAAE,SAAS,qBAAqB,EAQxD,CAAC;AAEF,yCAAyC;AACzC,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,qGAAqG;IACrG,QAAQ,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,aAAa,CAAC;IACtD;;;OAGG;IACH,WAAW,EAAE,MAAM,SAAS,UAAU,EAAE,CAAC;IACzC;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,QAAQ,GAAG,IAAI,CAAC;CAC7D;AA2CD,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,kBAAkB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CA8ZlG"}
1
+ {"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAE7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sDAAsD,CAAC;AAEvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAIrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAI1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAoChD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IACvB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AAED,wCAAwC;AACxC,eAAO,MAAM,YAAY,EAAE,SAAS,qBAAqB,EASxD,CAAC;AAEF,yCAAyC;AACzC,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,qGAAqG;IACrG,QAAQ,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,aAAa,CAAC;IACtD;;;OAGG;IACH,WAAW,EAAE,MAAM,SAAS,UAAU,EAAE,CAAC;IACzC;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,QAAQ,GAAG,IAAI,CAAC;IAC5D,+FAA+F;IAC/F,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AA2CD,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,kBAAkB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAwclG"}
@@ -7,10 +7,11 @@ import { exportChainRange, verifyChainRange } from "../chain/verify.js";
7
7
  import { pageAuditEvents, readAuditEvent } from "../query.js";
8
8
  import { reachPatterns } from "../routePattern.js";
9
9
  import { controlPlaneReach, controlPlaneReachSubjects } from "../reach.js";
10
+ import { readSinkStates } from "../ship/state.js";
10
11
  import { controlPlaneUsage } from "../usage.js";
11
- import { AccessHistoryResponse, AuditEventResponse, AuditEventsResponse, ChainExportResponse, ChainVerifyResponse, ControlPlaneReachResponse, ControlPlaneUsageResponse } from "./responses.js";
12
+ import { AccessHistoryResponse, AuditEventResponse, AuditEventsResponse, AuditSinksResponse, ChainExportResponse, ChainVerifyResponse, ControlPlaneReachResponse, ControlPlaneUsageReadResponse } from "./responses.js";
12
13
  import { AccessHistoryQuery, AuditEventIdParam, ChainExportQuery, ChainVerifyQuery, ControlPlaneReachQuery, ControlPlaneUsageQuery, ListAuditEventsQuery } from "./schemas.js";
13
- import { accessChangeView, auditEventDetailView, auditEventView, controlPlaneReachSubjectView, controlPlaneReachView, controlPlaneUsageView } from "./views.js";
14
+ import { accessChangeView, auditEventDetailView, auditEventView, auditSinkViews, controlPlaneConnectionUsageViews, controlPlaneReachSubjectView, controlPlaneReachView, controlPlaneUsageView } from "./views.js";
14
15
  import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
15
16
  import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
16
17
  import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
@@ -59,6 +60,12 @@ const AUDIT_ROUTES = [
59
60
  path: "/control-plane/export",
60
61
  strategy: "control-plane",
61
62
  scope: AUDIT_CHAIN_EXPORT_SCOPE
63
+ },
64
+ {
65
+ method: "GET",
66
+ path: "/control-plane/sinks",
67
+ strategy: "control-plane",
68
+ scope: AUDIT_TRAIL_READ_SCOPE
62
69
  }
63
70
  ];
64
71
  /**
@@ -103,6 +110,7 @@ function registerAuditRoutes(options) {
103
110
  const database = options.database;
104
111
  const adminRoutes = options.adminRoutes;
105
112
  const checkpoints = options.checkpoints ?? (() => null);
113
+ const sinks = options.sinks ?? {};
106
114
  return (app) => {
107
115
  /**
108
116
  * CONTROL-PLANE READ. A filtered, resumable page of the trail — keyset, never offset, because the
@@ -173,7 +181,7 @@ function registerAuditRoutes(options) {
173
181
  return c.json({ event: auditEventDetailView(row) }, 200);
174
182
  });
175
183
  /**
176
- * CONTROL-PLANE READ (#831). Who could do what, over time: every membership, connection and key change in a
184
+ * CONTROL-PLANE READ. Who could do what, over time: every membership, connection and key change in a
177
185
  * window, oldest first, with its before and after — one SQL statement per page, never a walk of events here.
178
186
  * Behind the listing scope, not the detail one: it lifts named metadata keys and never an IP or a user-agent.
179
187
  */
@@ -222,7 +230,7 @@ function registerAuditRoutes(options) {
222
230
  }, 200);
223
231
  });
224
232
  /**
225
- * CONTROL-PLANE READ (#828). What one credential reached — by tenant, action, method, route and outcome — over a
233
+ * CONTROL-PLANE READ. What one credential reached — by tenant, action, method, route and outcome — over a
226
234
  * window, in one SQL statement, never by paging events here. `subjects=true` expands one route into the subject
227
235
  * ids its called paths name. Behind the listing scope, not the detail one: the answer is the tenant, the route,
228
236
  * the scope and ids the listing already shows, and never an IP, a user-agent or any other metadata key.
@@ -284,16 +292,17 @@ function registerAuditRoutes(options) {
284
292
  }, 200);
285
293
  });
286
294
  /**
287
- * CONTROL-PLANE READ (#812). Which scopes one connection exercised and was refused, by key, over a window —
288
- * counted in one SQL statement, never by paging events here. Behind the listing scope, not the detail one: the
289
- * answer is the scope, the key, and the last allowed call's method and path, and never an IP, a user-agent or any
290
- * other metadata key.
295
+ * CONTROL-PLANE READ. Which scopes one connection exercised and was refused, by key, over a window —
296
+ * counted in one SQL statement, never by paging events here. With no `connectionId`, every connection that called
297
+ * in the window, each with its own scopes and keys, from the same one statement. Behind the listing
298
+ * scope, not the detail one: the answer is the connection, the scope, the key, and the last allowed call's method
299
+ * and path, and never an IP, a user-agent or any other metadata key.
291
300
  */
292
301
  app.get(`${base}/control-plane/usage`, describeRoute({
293
- summary: "Count which scopes one control-plane connection exercised and was refused, by key, over a window.",
302
+ summary: "Count which scopes one control-plane connection, or every one, exercised and was refused, by key, over a window.",
294
303
  verification: "control-plane",
295
304
  scopes: [AUDIT_TRAIL_READ_SCOPE],
296
- responses: { 200: ControlPlaneUsageResponse }
305
+ responses: { 200: ControlPlaneUsageReadResponse }
297
306
  }), requireControlPlane(AUDIT_TRAIL_READ_SCOPE), validate("query", ControlPlaneUsageQuery), async (c) => {
298
307
  const operator = caller(c);
299
308
  const query = c.req.valid("query");
@@ -301,32 +310,41 @@ function registerAuditRoutes(options) {
301
310
  since: query.since,
302
311
  until: query.until ?? /* @__PURE__ */ new Date()
303
312
  };
313
+ const named = query.connectionId;
304
314
  const result = await controlPlaneUsage(database(c), {
305
- connectionId: query.connectionId,
315
+ ...named !== void 0 ? { connectionId: named } : {},
306
316
  ...window
307
317
  });
318
+ const connections = named === void 0 ? controlPlaneConnectionUsageViews(result.usage) : void 0;
308
319
  await c.var.emit({
309
320
  action: AuditTrailActions.usageRead,
310
321
  outcome: "success",
311
322
  actorType: "control-plane",
312
323
  actorId: operator.subject,
313
324
  resourceType: "controlplane_connection",
314
- resourceId: query.connectionId,
325
+ ...named !== void 0 ? { resourceId: named } : {},
315
326
  requestId: c.req.header("cf-ray"),
316
327
  ip: c.req.header("cf-connecting-ip"),
317
328
  userAgent: c.req.header("user-agent"),
318
329
  metadata: {
319
330
  connectionId: operator.connectionId,
320
331
  query: {
321
- connectionId: query.connectionId,
332
+ connectionId: named ?? null,
322
333
  since: window.since.toISOString(),
323
334
  until: window.until.toISOString()
324
335
  },
336
+ ...connections !== void 0 ? { connections: connections.map((entry) => entry.connectionId) } : {},
325
337
  returned: result.usage.length
326
338
  }
327
339
  });
340
+ if (named === void 0) return c.json({
341
+ since: window.since.toISOString(),
342
+ until: window.until.toISOString(),
343
+ connections: connections ?? [],
344
+ oldestEventAt: result.oldestEventAt?.toISOString() ?? null
345
+ }, 200);
328
346
  return c.json({
329
- connectionId: query.connectionId,
347
+ connectionId: named,
330
348
  since: window.since.toISOString(),
331
349
  until: window.until.toISOString(),
332
350
  usage: result.usage.map(controlPlaneUsageView),
@@ -334,7 +352,7 @@ function registerAuditRoutes(options) {
334
352
  }, 200);
335
353
  });
336
354
  /**
337
- * CONTROL-PLANE READ (#822). Walk one tenant's hash chain over a window — every link, every hash, the
355
+ * CONTROL-PLANE READ. Walk one tenant's hash chain over a window — every link, every hash, the
338
356
  * checkpoints covering it — and answer intact or the first break. Reads only: it proves the trail whole and
339
357
  * changes nothing.
340
358
  */
@@ -391,7 +409,7 @@ function registerAuditRoutes(options) {
391
409
  }, 200);
392
410
  });
393
411
  /**
394
- * CONTROL-PLANE READ (#822). One page of one tenant's chain in canonical form, each event with its hash, the
412
+ * CONTROL-PLANE READ. One page of one tenant's chain in canonical form, each event with its hash, the
395
413
  * link before the page and the checkpoints covering it — what `pithy audit verify` checks offline. The IP,
396
414
  * user-agent and metadata values ride along only when the connection also holds the detail scope.
397
415
  */
@@ -438,6 +456,20 @@ function registerAuditRoutes(options) {
438
456
  });
439
457
  return c.json(page, 200);
440
458
  });
459
+ /**
460
+ * CONTROL-PLANE READ. Every declared sink beside its own delivery row: one primary-key lookup per sink, bounded
461
+ * by the config. Records no audit action of its own, unlike the trail's reads: it reads delivery state, never
462
+ * the trail, so the gate's `controlplane/call_allowed` row is its only record.
463
+ */
464
+ app.get(`${base}/control-plane/sinks`, describeRoute({
465
+ summary: "List every sink the trail ships to, each with its backlog, last delivery and dead letters.",
466
+ verification: "control-plane",
467
+ scopes: [AUDIT_TRAIL_READ_SCOPE],
468
+ responses: { 200: AuditSinksResponse }
469
+ }), requireControlPlane(AUDIT_TRAIL_READ_SCOPE), async (c) => {
470
+ const states = await readSinkStates(database(c), Object.keys(sinks));
471
+ return c.json({ sinks: auditSinkViews(sinks, states) }, 200);
472
+ });
441
473
  };
442
474
  }
443
475
  //#endregion
@@ -27,6 +27,7 @@ export declare const ListAuditEventsQuery: z.ZodObject<{
27
27
  script: "script";
28
28
  }>>;
29
29
  action: z.ZodOptional<z.ZodString>;
30
+ actionPrefix: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
30
31
  outcome: z.ZodOptional<z.ZodEnum<{
31
32
  denied: "denied";
32
33
  failure: "failure";
@@ -87,13 +88,14 @@ export type ControlPlaneReachQuery = z.infer<typeof ControlPlaneReachQuery>;
87
88
  /**
88
89
  * The usage query: whose calls to count, and over what window.
89
90
  *
90
- * `connectionId` and `since` are required, so a missing one is a 400 before any query runs — an unbounded window over
91
- * every connection is not a question this route answers. `until` defaults to now in the handler, which is the one
92
- * value a schema cannot compute for a request. A window that ends before it starts is refused rather than answered
93
- * with nothing, because nothing would read as an idle connection.
91
+ * `since` is required, so a missing one is a 400 before any query runs — an unbounded window is not a question this
92
+ * route answers. `connectionId` is optional: named, the route counts that connection's calls; left out, it counts every
93
+ * connection's, which is the over-grant question across a Worker in one read. `until` defaults to now in the
94
+ * handler, which is the one value a schema cannot compute for a request. A window that ends before it starts is
95
+ * refused rather than answered with nothing, because nothing would read as an idle connection.
94
96
  */
95
97
  export declare const ControlPlaneUsageQuery: z.ZodObject<{
96
- connectionId: z.ZodString;
98
+ connectionId: z.ZodOptional<z.ZodString>;
97
99
  since: z.ZodPipe<z.ZodString, z.ZodTransform<Date, string>>;
98
100
  until: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<Date, string>>>;
99
101
  }, z.core.$strip>;
@@ -1 +1 @@
1
- {"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA+CxB,kCAAkC;AAClC,eAAO,MAAM,iBAAiB;;iBAS+B,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyCiE,CAAC;AACnG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB;;;;;iBAqBiE,CAAC;AACjG,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAKpE;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;iBA4B2E,CAAC;AAC/G,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE5E;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB;;;;iBAYyC,CAAC;AAC7E,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAU5E,iEAAiE;AACjE,eAAO,MAAM,gBAAgB;;;;iBAc4C,CAAC;AAC1E,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,+CAA+C;AAC/C,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC,kFAAkF;AAClF,eAAO,MAAM,gBAAgB;;;;;;iBA0B8D,CAAC;AAC5F,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}
1
+ {"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA+CxB,kCAAkC;AAClC,eAAO,MAAM,iBAAiB;;iBAS+B,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqDiE,CAAC;AACnG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB;;;;;iBAqBiE,CAAC;AACjG,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAKpE;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;iBA4B2E,CAAC;AAC/G,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE5E;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;iBAY6D,CAAC;AACjG,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAU5E,iEAAiE;AACjE,eAAO,MAAM,gBAAgB;;;;iBAc4C,CAAC;AAC1E,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,+CAA+C;AAC/C,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC,kFAAkF;AAClF,eAAO,MAAM,gBAAgB;;;;;;iBA0B8D,CAAC;AAC5F,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}