@pithy-sh/audit 0.6.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (183) hide show
  1. package/README.md +93 -0
  2. package/dist/accessHistory.d.ts +315 -0
  3. package/dist/accessHistory.d.ts.map +1 -0
  4. package/dist/accessHistory.js +299 -0
  5. package/dist/actions.d.ts +15 -1
  6. package/dist/actions.d.ts.map +1 -1
  7. package/dist/actions.js +16 -2
  8. package/dist/capability.d.ts +14 -0
  9. package/dist/capability.d.ts.map +1 -1
  10. package/dist/capability.js +106 -12
  11. package/dist/chain/append.d.ts +43 -0
  12. package/dist/chain/append.d.ts.map +1 -0
  13. package/dist/chain/append.js +110 -0
  14. package/dist/chain/checkpoint.d.ts +70 -0
  15. package/dist/chain/checkpoint.d.ts.map +1 -0
  16. package/dist/chain/checkpoint.js +133 -0
  17. package/dist/chain/lockCheck.d.ts +15 -0
  18. package/dist/chain/lockCheck.d.ts.map +1 -0
  19. package/dist/chain/lockCheck.js +75 -0
  20. package/dist/chain/prune.d.ts +84 -0
  21. package/dist/chain/prune.d.ts.map +1 -0
  22. package/dist/chain/prune.js +231 -0
  23. package/dist/chain/rows.d.ts +74 -0
  24. package/dist/chain/rows.d.ts.map +1 -0
  25. package/dist/chain/rows.js +133 -0
  26. package/dist/chain/tombstone.d.ts +21 -0
  27. package/dist/chain/tombstone.d.ts.map +1 -0
  28. package/dist/chain/tombstone.js +98 -0
  29. package/dist/chain/verify.d.ts +63 -0
  30. package/dist/chain/verify.d.ts.map +1 -0
  31. package/dist/chain/verify.js +220 -0
  32. package/dist/citations.d.ts +17 -0
  33. package/dist/citations.d.ts.map +1 -0
  34. package/dist/citations.js +48 -0
  35. package/dist/cli/emitFromCLI.d.ts +5 -0
  36. package/dist/cli/emitFromCLI.d.ts.map +1 -1
  37. package/dist/cli/emitFromCLI.js +5 -0
  38. package/dist/data/auditEvent.d.ts +4 -0
  39. package/dist/data/auditEvent.d.ts.map +1 -1
  40. package/dist/data/auditEvent.js +7 -3
  41. package/dist/data/sinkState.d.ts +23 -0
  42. package/dist/data/sinkState.d.ts.map +1 -0
  43. package/dist/data/sinkState.js +25 -0
  44. package/dist/data/tables.d.ts +14 -1
  45. package/dist/data/tables.d.ts.map +1 -1
  46. package/dist/data/tables.js +5 -1
  47. package/dist/http/guards.d.ts +39 -6
  48. package/dist/http/guards.d.ts.map +1 -1
  49. package/dist/http/guards.js +101 -17
  50. package/dist/http/responses.d.ts +503 -0
  51. package/dist/http/responses.d.ts.map +1 -1
  52. package/dist/http/responses.js +157 -5
  53. package/dist/http/routes.d.ts +25 -3
  54. package/dist/http/routes.d.ts.map +1 -1
  55. package/dist/http/routes.js +321 -15
  56. package/dist/http/schemas.d.ts +67 -0
  57. package/dist/http/schemas.d.ts.map +1 -1
  58. package/dist/http/schemas.js +88 -4
  59. package/dist/http/views.d.ts +25 -1
  60. package/dist/http/views.d.ts.map +1 -1
  61. package/dist/http/views.js +107 -2
  62. package/dist/migrations/0003_call_index.d.ts +21 -0
  63. package/dist/migrations/0003_call_index.d.ts.map +1 -0
  64. package/dist/migrations/0003_call_index.js +33 -0
  65. package/dist/migrations/0004_request_index.d.ts +16 -0
  66. package/dist/migrations/0004_request_index.d.ts.map +1 -0
  67. package/dist/migrations/0004_request_index.js +24 -0
  68. package/dist/migrations/0005_chain.d.ts +24 -0
  69. package/dist/migrations/0005_chain.d.ts.map +1 -0
  70. package/dist/migrations/0005_chain.js +43 -0
  71. package/dist/migrations/0006_sinks.d.ts +11 -0
  72. package/dist/migrations/0006_sinks.d.ts.map +1 -0
  73. package/dist/migrations/0006_sinks.js +20 -0
  74. package/dist/provision/resolveAuditConfig.d.ts +31 -0
  75. package/dist/provision/resolveAuditConfig.d.ts.map +1 -0
  76. package/dist/provision/resolveAuditConfig.js +43 -0
  77. package/dist/purge/contribution.d.ts +21 -0
  78. package/dist/purge/contribution.d.ts.map +1 -0
  79. package/dist/purge/contribution.js +41 -0
  80. package/dist/reach.d.ts +250 -0
  81. package/dist/reach.d.ts.map +1 -0
  82. package/dist/reach.js +244 -0
  83. package/dist/recorder.d.ts +11 -0
  84. package/dist/recorder.d.ts.map +1 -1
  85. package/dist/recorder.js +23 -5
  86. package/dist/routePattern.d.ts +60 -0
  87. package/dist/routePattern.d.ts.map +1 -0
  88. package/dist/routePattern.js +130 -0
  89. package/dist/seeds/example.d.ts.map +1 -1
  90. package/dist/seeds/example.js +23 -6
  91. package/dist/ship/consumer.d.ts +45 -0
  92. package/dist/ship/consumer.d.ts.map +1 -0
  93. package/dist/ship/consumer.js +141 -0
  94. package/dist/ship/event.d.ts +59 -0
  95. package/dist/ship/event.d.ts.map +1 -0
  96. package/dist/ship/event.js +77 -0
  97. package/dist/ship/health.d.ts +33 -0
  98. package/dist/ship/health.d.ts.map +1 -0
  99. package/dist/ship/health.js +80 -0
  100. package/dist/ship/profiles.d.ts +34 -0
  101. package/dist/ship/profiles.d.ts.map +1 -0
  102. package/dist/ship/profiles.js +62 -0
  103. package/dist/ship/queue.d.ts +57 -0
  104. package/dist/ship/queue.d.ts.map +1 -0
  105. package/dist/ship/queue.js +70 -0
  106. package/dist/ship/secrets.d.ts +7 -0
  107. package/dist/ship/secrets.d.ts.map +1 -0
  108. package/dist/ship/secrets.js +40 -0
  109. package/dist/ship/shipper.d.ts +15 -0
  110. package/dist/ship/shipper.d.ts.map +1 -0
  111. package/dist/ship/shipper.js +27 -0
  112. package/dist/ship/sinks.d.ts +54 -0
  113. package/dist/ship/sinks.d.ts.map +1 -0
  114. package/dist/ship/sinks.js +45 -0
  115. package/dist/ship/state.d.ts +27 -0
  116. package/dist/ship/state.d.ts.map +1 -0
  117. package/dist/ship/state.js +29 -0
  118. package/dist/usage.d.ts +159 -0
  119. package/dist/usage.d.ts.map +1 -0
  120. package/dist/usage.js +87 -0
  121. package/dist/version.generated.d.ts +1 -1
  122. package/dist/version.generated.js +1 -1
  123. package/dist/workflows/prune.d.ts +73 -0
  124. package/dist/workflows/prune.d.ts.map +1 -0
  125. package/dist/workflows/prune.js +128 -0
  126. package/dist/workflows/retryPolicy.d.ts +10 -0
  127. package/dist/workflows/retryPolicy.d.ts.map +1 -0
  128. package/dist/workflows/retryPolicy.js +14 -0
  129. package/dist/workflows/specs.d.ts +70 -0
  130. package/dist/workflows/specs.d.ts.map +1 -0
  131. package/dist/workflows/specs.js +70 -0
  132. package/dist/workflows/worker.d.ts +32 -0
  133. package/dist/workflows/worker.d.ts.map +1 -0
  134. package/dist/workflows/worker.js +41 -0
  135. package/package.json +5 -2
  136. package/pithy.manifest.json +36 -4
  137. package/src/accessHistory.ts +360 -0
  138. package/src/actions.ts +15 -1
  139. package/src/capability.ts +134 -12
  140. package/src/chain/append.ts +161 -0
  141. package/src/chain/checkpoint.ts +172 -0
  142. package/src/chain/lockCheck.ts +72 -0
  143. package/src/chain/prune.ts +340 -0
  144. package/src/chain/rows.ts +211 -0
  145. package/src/chain/tombstone.ts +104 -0
  146. package/src/chain/verify.ts +366 -0
  147. package/src/citations.ts +62 -0
  148. package/src/cli/emitFromCLI.ts +5 -0
  149. package/src/cloudflare-test.d.ts +1 -0
  150. package/src/data/auditEvent.ts +31 -1
  151. package/src/data/sinkState.ts +41 -0
  152. package/src/data/tables.ts +7 -1
  153. package/src/http/guards.ts +90 -6
  154. package/src/http/responses.ts +318 -3
  155. package/src/http/routes.ts +379 -7
  156. package/src/http/schemas.ts +158 -2
  157. package/src/http/views.ts +123 -1
  158. package/src/migrations/0003_call_index.ts +35 -0
  159. package/src/migrations/0004_request_index.ts +26 -0
  160. package/src/migrations/0005_chain.ts +56 -0
  161. package/src/migrations/0006_sinks.ts +28 -0
  162. package/src/provision/resolveAuditConfig.ts +60 -0
  163. package/src/purge/contribution.ts +39 -0
  164. package/src/reach.ts +454 -0
  165. package/src/recorder.ts +64 -42
  166. package/src/routePattern.ts +141 -0
  167. package/src/seeds/example.ts +13 -0
  168. package/src/ship/consumer.ts +169 -0
  169. package/src/ship/event.ts +86 -0
  170. package/src/ship/health.ts +92 -0
  171. package/src/ship/profiles.ts +99 -0
  172. package/src/ship/queue.ts +108 -0
  173. package/src/ship/secrets.ts +42 -0
  174. package/src/ship/shipper.ts +32 -0
  175. package/src/ship/sinks.ts +82 -0
  176. package/src/ship/state.ts +61 -0
  177. package/src/usage.ts +176 -0
  178. package/src/version.generated.ts +1 -1
  179. package/src/workflows/prune.ts +196 -0
  180. package/src/workflows/retryPolicy.ts +14 -0
  181. package/src/workflows/specs.ts +92 -0
  182. package/src/workflows/worker.ts +65 -0
  183. package/src/workflows/wrangler.jsonc +40 -0
@@ -1,7 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
3
 
4
- import type { AdminRoute } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
4
+ import type { AdminRouteDeclaration } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
5
5
  import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
6
6
 
7
7
  /**
@@ -33,10 +33,33 @@ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/sc
33
33
  * `metadata` bag — which routinely holds the email address, the resource name, or the reason a
34
34
  * capability recorded alongside its event. Bulk-harvesting those over a whole trail is a privacy
35
35
  * incident, and requiring a second scope is what makes it a decision the adopter makes rather than
36
- * one a listing credential comes with. Since the two are separate routes, a credential holding only
37
- * the detail scope cannot enumerate the trail to find ids to read, and a credential holding only the
38
- * list scope cannot resolve one. `scopeCovers` matches exactly — no prefix, no wildcard — so holding
39
- * one confers nothing about the other.
36
+ * one a listing credential comes with. Since the listing and detail routes are separate, a credential holding
37
+ * only the detail scope cannot enumerate the trail to find ids to read, and a credential holding only the list scope
38
+ * cannot resolve one. `scopeCovers` matches exactly — no prefix, no wildcard — so holding one confers nothing about
39
+ * the other.
40
+ *
41
+ * **Usage rides the listing scope.** `GET {base}/control-plane/usage` counts one connection's calls by scope
42
+ * and key. Its answer is the scope, the key id, and the method and path of the last allowed call — the management
43
+ * client's own footprint, which the listing already discloses in shape through `action`, `actorId` and `resourceId`
44
+ * — and never an IP, a user-agent, or any other metadata key. So it needs no detail scope, and an access review does
45
+ * not have to hold the most dangerous grant audit defines to ask which grants are used.
46
+ *
47
+ * **The access history rides the listing scope.** `GET {base}/control-plane/access-history` answers every
48
+ * membership, connection and key change in a window with its before and after — roles, scopes, the connection's
49
+ * kind, purpose and principal, a key id. It lifts those named metadata keys and no other, and never an IP or a
50
+ * user-agent, so replaying who could reach the data does not need the grant that discloses where everyone was.
51
+ *
52
+ * **Reach rides the listing scope.** `GET {base}/control-plane/reach` answers what one credential touched:
53
+ * per tenant, route and outcome, counts and two instants, and on request one route's called paths and the subject
54
+ * ids they name. Those ids are segments of paths the credential itself sent, naming the subjects the listing
55
+ * 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
56
+ * path. So a breach review does not need the detail scope to draw a breach scope.
57
+ *
58
+ * **The chain has a scope of its own.** `GET {base}/control-plane/verify` walks one tenant's chain, and
59
+ * `GET {base}/control-plane/export` takes it out in canonical form with its checkpoints. An export is the trail in
60
+ * bulk, meant to leave the building, so neither read rides the listing scope: both need `audit:events:export`. The
61
+ * export carries IP, user-agent and metadata values only when the connection also holds the detail scope, and their
62
+ * salted hashes otherwise, which verify and disclose nothing.
40
63
  *
41
64
  * The names are constants rather than config: a configurable scope name is a way to misconfigure a
42
65
  * default-denied gate into a differently-named one, and they are the join key with what
@@ -55,6 +78,17 @@ export const AUDIT_TRAIL_READ_SCOPE: ControlPlaneScope = "audit:events:read";
55
78
  */
56
79
  export const AUDIT_EVENT_DETAIL_READ_SCOPE: ControlPlaneScope = "audit:events:read_detail";
57
80
 
81
+ /**
82
+ * Verify and export the hash chain: walk one tenant's chain against its checkpoints, and take it out in
83
+ * canonical form for an auditor to check offline.
84
+ *
85
+ * Its own scope, because an export is the trail in bulk — every event of a tenant, in a form meant to leave the
86
+ * building. The IP, user-agent and metadata ride along only when the connection also holds
87
+ * {@link AUDIT_EVENT_DETAIL_READ_SCOPE}; without it the export carries their salted hashes, which verify and
88
+ * disclose nothing.
89
+ */
90
+ export const AUDIT_CHAIN_EXPORT_SCOPE: ControlPlaneScope = "audit:events:export";
91
+
58
92
  /**
59
93
  * Every control-plane scope audit defines — what `pithy dashboard connect` offers for this capability,
60
94
  * and the list a manifest or a doc quotes rather than re-typing.
@@ -62,6 +96,7 @@ export const AUDIT_EVENT_DETAIL_READ_SCOPE: ControlPlaneScope = "audit:events:re
62
96
  export const AUDIT_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[] = [
63
97
  AUDIT_TRAIL_READ_SCOPE,
64
98
  AUDIT_EVENT_DETAIL_READ_SCOPE,
99
+ AUDIT_CHAIN_EXPORT_SCOPE,
65
100
  ];
66
101
 
67
102
  /**
@@ -75,19 +110,68 @@ export const AUDIT_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[] = [
75
110
  * The summaries say what the operation is *for*. A client renders these beside a pane somebody is
76
111
  * about to open over other people's activity.
77
112
  */
78
- export function auditAdminRoutes(basePath: string): AdminRoute[] {
113
+ export function auditAdminRoutes(basePath: string): AdminRouteDeclaration[] {
79
114
  return [
80
115
  {
81
116
  method: "GET",
117
+ operation: "events.list",
82
118
  path: `${basePath}/events`,
83
119
  scope: AUDIT_TRAIL_READ_SCOPE,
120
+ kind: "reads",
84
121
  summary:
85
122
  "Page the trail, newest first, filtered by actor, action, resource, outcome, severity, origin, and time.",
86
123
  },
87
124
  {
88
125
  method: "GET",
126
+ operation: "access_history.read",
127
+ path: `${basePath}/control-plane/access-history`,
128
+ scope: AUDIT_TRAIL_READ_SCOPE,
129
+ kind: "reads",
130
+ summary:
131
+ "Replay who could do what: every membership, connection and key change in a window, oldest first, with its before and after. No event is read in full.",
132
+ },
133
+ {
134
+ method: "GET",
135
+ operation: "reach.read",
136
+ path: `${basePath}/control-plane/reach`,
137
+ scope: AUDIT_TRAIL_READ_SCOPE,
138
+ kind: "reads",
139
+ summary:
140
+ "Read what one control-plane credential reached, by tenant, route and outcome, and expand a route into the subjects it touched.",
141
+ },
142
+ {
143
+ method: "GET",
144
+ operation: "usage.read",
145
+ path: `${basePath}/control-plane/usage`,
146
+ scope: AUDIT_TRAIL_READ_SCOPE,
147
+ kind: "reads",
148
+ summary:
149
+ "Count which scopes one control-plane connection exercised and was refused, by key, over a window. Counts only — no event is read in full.",
150
+ },
151
+ {
152
+ method: "GET",
153
+ operation: "chain.verify",
154
+ path: `${basePath}/control-plane/verify`,
155
+ scope: AUDIT_CHAIN_EXPORT_SCOPE,
156
+ kind: "reads",
157
+ summary:
158
+ "Walk one tenant's hash chain against its checkpoints, and say whether it is whole or where it first breaks.",
159
+ },
160
+ {
161
+ method: "GET",
162
+ operation: "chain.export",
163
+ path: `${basePath}/control-plane/export`,
164
+ scope: AUDIT_CHAIN_EXPORT_SCOPE,
165
+ kind: "reads",
166
+ summary:
167
+ "Export one tenant's hash chain in canonical form with its checkpoints, to verify offline. Personal values only with the detail scope.",
168
+ },
169
+ {
170
+ method: "GET",
171
+ operation: "events.read",
89
172
  path: `${basePath}/events/:eventId`,
90
173
  scope: AUDIT_EVENT_DETAIL_READ_SCOPE,
174
+ kind: "reads",
91
175
  summary: "Read one event in full, including the client IP, user-agent, and capability metadata.",
92
176
  },
93
177
  ];
@@ -2,6 +2,7 @@
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
3
 
4
4
  import { AuditActorType, AuditMetadata, AuditOutcome, AuditSeverity } from "@pithy-sh/core/src/audit/auditEvent";
5
+ import { AuditChainExport, ChainBreak, ChainLink } from "@pithy-sh/core/src/audit/chain";
5
6
  import { ControlPlaneActorKind } from "@pithy-sh/core/src/controlPlane/data/connection";
6
7
  import { z } from "zod";
7
8
 
@@ -25,7 +26,7 @@ import { z } from "zod";
25
26
  * **A field added here later is `.optional()`, not merely `.nullable()`.** This module is read across a
26
27
  * version boundary — a management client validates a response with this schema against a customer's
27
28
  * Worker at whatever kit version it is on — so an additive required key fails `safeParse` for everyone
28
- * below that release and takes the whole pane with it (#450). Absent then means *this Worker cannot
29
+ * below that release and takes the whole pane with it. Absent then means *this Worker cannot
29
30
  * say*, which is a different fact from `null`.
30
31
  */
31
32
 
@@ -50,11 +51,10 @@ export const AuditEventView = z
50
51
  severity: AuditSeverity.describe("How serious it is, orthogonal to the outcome."),
51
52
  actorType: AuditActorType.describe("The kind of principal that acted."),
52
53
  actorId: z.string().nullable().describe("The acting principal's stable id, or null."),
53
- // Added (#721), so `.optional()` too: a client reading an older Worker receives no such field.
54
54
  actorKind: ControlPlaneActorKind.nullable()
55
55
  .optional()
56
56
  .describe(
57
- "For a `control-plane` actor, which kind of management client acted — `agent`, `dashboard` or `script` — or null. Absent from a Worker older than the field.",
57
+ "Which kind of client acted — `agent`, `dashboard` or `script` — or null. A `control-plane` actor's connection kind, or `agent` on a `user` row an MCP client wrote. Absent from a Worker older than the field.",
58
58
  ),
59
59
  sessionId: z.string().nullable().describe("The session the action belongs to — a row id, never a token — or null."),
60
60
  resourceType: z.string().nullable().describe("The kind of thing acted on, or null."),
@@ -68,6 +68,14 @@ export const AuditEventView = z
68
68
  .string()
69
69
  .nullable()
70
70
  .describe("The tenant the action was taken for, or null when it was not tenant-scoped."),
71
+ chainSeq: z
72
+ .number()
73
+ .int()
74
+ .nullable()
75
+ .optional()
76
+ .describe(
77
+ "The event's position in its tenant's hash chain, or null when it was written before the chain began and is marked so. Absent from a Worker older than the chain.",
78
+ ),
71
79
  })
72
80
  .describe("One audit event as the listing shows it. No client IP, no user-agent, no metadata bag.");
73
81
  export type AuditEventView = z.output<typeof AuditEventView>;
@@ -106,3 +114,310 @@ export const AuditEventResponse = z
106
114
  .object({ event: AuditEventDetailView.describe("The event, with the fields the detail scope gates.") })
107
115
  .describe("One audit event in full.");
108
116
  export type AuditEventResponse = z.output<typeof AuditEventResponse>;
117
+
118
+ /**
119
+ * Whether a change's event carried its before and after.
120
+ *
121
+ * `not_recorded` is an event written before its emitter recorded the detail — a role change from before
122
+ * `previousRole`, an update that moved no scope from before every update carried the grant. Its unknown values are
123
+ * null, and this says they are unknown rather than none: the reader is told, never handed a guess.
124
+ */
125
+ const ChangeDetail = z
126
+ .enum(["recorded", "not_recorded"])
127
+ .describe(
128
+ "Whether the event recorded this change's before and after. `not_recorded` means a null before or after is unknown, not none: the event predates the emitter recording it.",
129
+ );
130
+
131
+ /** What every access change carries: when, who, and from which code. */
132
+ const AccessChangeBase = z.object({
133
+ eventId: z.string().describe("The event the change was read from — the listing's `eventId`."),
134
+ occurredAt: z.iso.datetime().describe("When it changed, ISO-8601."),
135
+ action: z.string().describe("The `domain/reason` code it was recorded under."),
136
+ actorType: AuditActorType.describe("The kind of principal that made the change."),
137
+ actorId: z.string().nullable().describe("The principal that made the change, or null."),
138
+ actorKind: ControlPlaneActorKind.nullable().describe(
139
+ "Which kind of client made the change — a `control-plane` actor's connection kind, or `agent` for a user's MCP client — or null.",
140
+ ),
141
+ detail: ChangeDetail,
142
+ });
143
+
144
+ /** A membership joined, changed role, or ended. */
145
+ export const MemberAccessChange = AccessChangeBase.extend({
146
+ subject: z.literal("member").describe("A membership changed."),
147
+ organizationId: z.string().nullable().describe("The organization the membership is in."),
148
+ membershipId: z.string().nullable().describe("The membership that changed."),
149
+ userId: z.string().nullable().describe("Whose membership it is, or null when the event did not say."),
150
+ roleBefore: z
151
+ .string()
152
+ .nullable()
153
+ .describe("The role it held before. Null for a join, or when `detail` is `not_recorded`."),
154
+ roleAfter: z
155
+ .string()
156
+ .nullable()
157
+ .describe("The role it holds after. Null for a leave or a removal, or when `detail` is `not_recorded`."),
158
+ }).describe("A membership joined, changed role, or ended.");
159
+ export type MemberAccessChange = z.output<typeof MemberAccessChange>;
160
+
161
+ /** A control-plane connection was registered, updated, or removed. */
162
+ export const ConnectionAccessChange = AccessChangeBase.extend({
163
+ subject: z.literal("connection").describe("A control-plane connection changed."),
164
+ connectionId: z.string().nullable().describe("The connection that changed."),
165
+ connectionKind: ControlPlaneActorKind.nullable().describe(
166
+ "What kind of client the connection is for, or null when it was not recorded.",
167
+ ),
168
+ purpose: z.string().nullable().describe("What the connection is for, in its registrant's words, or null."),
169
+ principal: z
170
+ .string()
171
+ .nullable()
172
+ .describe("Who sanctioned the connection — the registering session's email address — or null."),
173
+ scopesBefore: z
174
+ .array(z.string().describe("A granted scope."))
175
+ .nullable()
176
+ .describe("The scopes it held before. Null for a registration, or when `detail` is `not_recorded`."),
177
+ scopesAfter: z
178
+ .array(z.string().describe("A granted scope."))
179
+ .nullable()
180
+ .describe("The scopes it holds after. Null for a removal, or when `detail` is `not_recorded`."),
181
+ replacedConnectionId: z
182
+ .string()
183
+ .nullable()
184
+ .describe(
185
+ "For a registration that started over, the connection it replaced: that connection's grant ended here. Null otherwise. A start-over recorded by a current CLI also has the old connection's own removal, just before.",
186
+ ),
187
+ }).describe("A control-plane connection was registered, updated, or removed.");
188
+ export type ConnectionAccessChange = z.output<typeof ConnectionAccessChange>;
189
+
190
+ /** A key on a connection was registered, expired, or revoked. */
191
+ export const KeyAccessChange = AccessChangeBase.extend({
192
+ subject: z.literal("key").describe("A key on a control-plane connection changed."),
193
+ connectionId: z.string().nullable().describe("The connection the key belongs to."),
194
+ keyId: z.string().nullable().describe("The key's id. Never key material."),
195
+ change: z
196
+ .enum(["registered", "expired", "revoked"])
197
+ .describe("What happened to it: registered, expired at the end of a rotation, or revoked."),
198
+ }).describe("A key on a control-plane connection was registered, expired, or revoked.");
199
+ export type KeyAccessChange = z.output<typeof KeyAccessChange>;
200
+
201
+ /** One access change, discriminated on what changed. */
202
+ export const AccessChangeView = z
203
+ .discriminatedUnion("subject", [MemberAccessChange, ConnectionAccessChange, KeyAccessChange])
204
+ .describe("One change to who can reach this environment's data, with its before and after.");
205
+ export type AccessChangeView = z.output<typeof AccessChangeView>;
206
+
207
+ /** `GET {base}/control-plane/access-history`. */
208
+ export const AccessHistoryResponse = z
209
+ .object({
210
+ since: z.iso.datetime().describe("The window's inclusive start, ISO-8601."),
211
+ until: z.iso.datetime().describe("The window's inclusive end, ISO-8601 — now, when the query named none."),
212
+ changes: z.array(AccessChangeView).describe("The page, oldest first."),
213
+ nextCursor: NextCursor,
214
+ })
215
+ .describe("Every membership, connection and key change in a window, oldest first, with its before and after.");
216
+ export type AccessHistoryResponse = z.output<typeof AccessHistoryResponse>;
217
+
218
+ /**
219
+ * One tenant, action, method, route and outcome a control-plane credential reached.
220
+ *
221
+ * Counts, two instants, and the route. No IP, no user-agent, no metadata key beyond what the route and scope already
222
+ * say: this is the credential's own footprint, which is why it sits behind the listing scope.
223
+ */
224
+ export const ControlPlaneReachView = z
225
+ .object({
226
+ tenant: z
227
+ .string()
228
+ .nullable()
229
+ .describe(
230
+ "The tenant the calls reached, as the handler behind them recorded it in the same request. Null when the handler named none.",
231
+ ),
232
+ action: z
233
+ .string()
234
+ .describe("`controlplane/call_allowed` for admitted calls, `controlplane/call_denied` for refusals."),
235
+ method: z.string().describe("The HTTP method called."),
236
+ route: z
237
+ .string()
238
+ .describe("The declared admin route the calls matched, or the path as called when no declared route matched."),
239
+ matched: z
240
+ .boolean()
241
+ .describe("Whether `route` is a declared pattern. False marks an unmatched path, which is its own row."),
242
+ outcome: z
243
+ .string()
244
+ .describe(
245
+ "The calls' outcome: `success`, or `denied` for a call a handler refused past the gate, which is counted once, as denied.",
246
+ ),
247
+ scope: z
248
+ .string()
249
+ .nullable()
250
+ .describe(
251
+ "The scope the calls' credential carried. On a refusal it is the scope the refused credential held, not one it lacked, which the trail does not record.",
252
+ ),
253
+ count: z.number().int().describe("How many calls."),
254
+ subjects: z
255
+ .number()
256
+ .int()
257
+ .nullable()
258
+ .describe(
259
+ "How many distinct subjects the calls touched: distinct values of the route's subject parameter and the parameters before it, so one user read in two currencies is one subject. 0 for a route with no parameters, null for an unmatched path.",
260
+ ),
261
+ firstAt: z.iso.datetime().describe("When the first call landed, ISO-8601."),
262
+ lastAt: z.iso.datetime().describe("When the last call landed, ISO-8601."),
263
+ })
264
+ .describe("One tenant, action, method, route and outcome one control-plane credential reached in a window.");
265
+ export type ControlPlaneReachView = z.output<typeof ControlPlaneReachView>;
266
+
267
+ /** One path a route was called with, and the subject ids it names. */
268
+ export const ControlPlaneReachSubjectView = z
269
+ .object({
270
+ tenant: z.string().nullable().describe("The tenant the calls reached, or null when their handler named none."),
271
+ action: z.string().describe("`controlplane/call_allowed` or `controlplane/call_denied`."),
272
+ method: z.string().describe("The HTTP method called."),
273
+ route: z.string().describe("The route expanded, as asked for."),
274
+ matched: z.boolean().describe("Whether the route is a declared pattern."),
275
+ path: z.string().describe("The path as called."),
276
+ outcome: z.string().describe("The calls' outcome: `success` or `denied`."),
277
+ scope: z
278
+ .string()
279
+ .nullable()
280
+ .describe("The scope the calls' credential carried, refused or not. Never the scope a refusal lacked."),
281
+ subjectId: z
282
+ .string()
283
+ .nullable()
284
+ .describe(
285
+ "Whose data the call acted on: the value of the route's last id parameter (`id`, or a name ending in `Id`), or of its last parameter when none names an id. On `/accounts/:userId/:currency/transactions` it is the user, not the currency. `params` has the rest. Null when the route declares none.",
286
+ ),
287
+ params: z
288
+ .record(z.string(), z.string())
289
+ .describe("Every parameter the route declares, with the value it took in `path`, decoded."),
290
+ count: z.number().int().describe("How many calls to this path."),
291
+ firstAt: z.iso.datetime().describe("When the first call to this path landed, ISO-8601."),
292
+ lastAt: z.iso.datetime().describe("When the last call to this path landed, ISO-8601."),
293
+ })
294
+ .describe("One path a route was called with by one control-plane credential, and the subject ids it names.");
295
+ export type ControlPlaneReachSubjectView = z.output<typeof ControlPlaneReachSubjectView>;
296
+
297
+ /** `GET {base}/control-plane/reach`. */
298
+ export const ControlPlaneReachResponse = z
299
+ .object({
300
+ connectionId: z.string().describe("The connection read, as asked for."),
301
+ keyId: z.string().nullable().describe("The key the read was narrowed to, or null for every key."),
302
+ since: z.iso.datetime().describe("The window's inclusive start, ISO-8601."),
303
+ until: z.iso.datetime().describe("The window's inclusive end, ISO-8601 — now, when the query named none."),
304
+ reach: z
305
+ .array(ControlPlaneReachView)
306
+ .describe("One row per tenant, route, action, method and outcome reached, ordered in that order."),
307
+ subjects: z
308
+ .array(ControlPlaneReachSubjectView)
309
+ .optional()
310
+ .describe(
311
+ "The route's subjects, one row per tenant and path called. Present only when the query asked with `subjects=true`.",
312
+ ),
313
+ })
314
+ .describe("Everything one control-plane credential reached over a window, by tenant, route and outcome.");
315
+ export type ControlPlaneReachResponse = z.output<typeof ControlPlaneReachResponse>;
316
+
317
+ /**
318
+ * One `(scope, keyId)` a control-plane connection exercised.
319
+ *
320
+ * Counts, two instants, and the method and path of the last allowed call. No IP, no user-agent, no other metadata key:
321
+ * this is the management client's own footprint, which is why it sits behind the listing scope.
322
+ */
323
+ export const ControlPlaneUsageView = z
324
+ .object({
325
+ scope: z
326
+ .string()
327
+ .describe(
328
+ "The scope exercised — what an allowed call's token carried, or what a refused call required. A scope never exercised has no row.",
329
+ ),
330
+ keyId: z.string().nullable().describe("The registered key that signed the calls, or null when none was recorded."),
331
+ allowed: z.number().int().describe("How many calls under this scope and key were admitted in the window."),
332
+ denied: z
333
+ .number()
334
+ .int()
335
+ .describe(
336
+ "How many verified calls naming this scope were refused in the window. An under-grant shows here, beside an over-grant's zero. A refusal that failed verification proves no connection and is not counted.",
337
+ ),
338
+ lastAllowedAt: z.iso
339
+ .datetime()
340
+ .nullable()
341
+ .describe("When the last admitted call landed, ISO-8601, or null when none was admitted."),
342
+ lastAllowedMethod: z.string().nullable().describe("The HTTP method of the last admitted call, or null."),
343
+ lastAllowedPath: z.string().nullable().describe("The path of the last admitted call, or null."),
344
+ lastDeniedAt: z.iso
345
+ .datetime()
346
+ .nullable()
347
+ .describe("When the last refusal landed, ISO-8601, or null when none was refused."),
348
+ })
349
+ .describe("One scope and key a control-plane connection exercised in a window.");
350
+ export type ControlPlaneUsageView = z.output<typeof ControlPlaneUsageView>;
351
+
352
+ /** `GET {base}/control-plane/usage`. */
353
+ export const ControlPlaneUsageResponse = z
354
+ .object({
355
+ connectionId: z.string().describe("The connection counted, as asked for."),
356
+ since: z.iso.datetime().describe("The window's inclusive start, ISO-8601."),
357
+ until: z.iso.datetime().describe("The window's inclusive end, ISO-8601 — now, when the query named none."),
358
+ usage: z.array(ControlPlaneUsageView).describe("One row per scope and key exercised, ordered by scope then key."),
359
+ oldestEventAt: z.iso
360
+ .datetime()
361
+ .nullable()
362
+ .describe(
363
+ "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.",
364
+ ),
365
+ })
366
+ .describe("Which scopes one control-plane connection exercised and was refused, by key, over a window.");
367
+ export type ControlPlaneUsageResponse = z.output<typeof ControlPlaneUsageResponse>;
368
+
369
+ /** `GET {base}/control-plane/verify`. */
370
+ export const ChainVerifyResponse = z
371
+ .object({
372
+ tenant: z.string().nullable().describe("The tenant whose chain was walked, or null for the untenanted chain."),
373
+ since: z.iso
374
+ .datetime()
375
+ .nullable()
376
+ .describe("The window's inclusive start as asked, or null for the chain's start."),
377
+ until: z.iso.datetime().nullable().describe("The window's inclusive end as asked, or null for the chain's head."),
378
+ intact: z.boolean().describe("Whether the range is whole: every link, every hash, every checkpoint covering it."),
379
+ checked: z
380
+ .number()
381
+ .int()
382
+ .nonnegative()
383
+ .describe("How many chained events were checked before the first break, or all of them."),
384
+ checkpoints: z.number().int().nonnegative().describe("How many checkpoints the walk was held to."),
385
+ pruned: z
386
+ .number()
387
+ .int()
388
+ .nonnegative()
389
+ .optional()
390
+ .describe(
391
+ "How many events the walk crossed as pruned by the retention policy, each run bridged by the tombstone written before it was deleted. Absent from a Worker that cannot prune.",
392
+ ),
393
+ checkpointStore: z
394
+ .enum(["bound", "absent"])
395
+ .describe(
396
+ "`absent` when this Worker binds no checkpoint bucket, so the walk checked links alone: a chain rewritten end to end would read as intact.",
397
+ ),
398
+ beforeChain: z
399
+ .number()
400
+ .int()
401
+ .nonnegative()
402
+ .describe("How many of the tenant's events in the window were written before the chain, and so are not in it."),
403
+ outsideChain: z
404
+ .number()
405
+ .int()
406
+ .nonnegative()
407
+ .describe(
408
+ "How many rows in the window carry no chain though written after it began — an older recorder's during an upgrade or a rollback. Not in the chain, and not a break: `intact` is about the chain itself.",
409
+ ),
410
+ break: ChainBreak.nullable().describe("The first break — its event, its position and why — or null."),
411
+ head: ChainLink.nullable().describe("The last position the walk reached intact, or null when it reached none."),
412
+ })
413
+ .describe("Whether one tenant's audit chain is whole over a window, or where it first breaks.");
414
+ export type ChainVerifyResponse = z.output<typeof ChainVerifyResponse>;
415
+
416
+ /**
417
+ * `GET {base}/control-plane/export`. Core's export document, which `pithy audit verify` reads offline —
418
+ * one schema, so what the Worker writes and what the verifier accepts cannot drift.
419
+ */
420
+ export const ChainExportResponse = AuditChainExport.describe(
421
+ "One page of one tenant's audit chain: canonical events, their hashes, the link before them and the checkpoints covering them.",
422
+ );
423
+ export type ChainExportResponse = z.output<typeof ChainExportResponse>;