@pithy-sh/audit 0.8.0 → 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.
@@ -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
@@ -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
@@ -138,7 +138,7 @@ function auditAdminRoutes(basePath) {
138
138
  path: `${basePath}/control-plane/usage`,
139
139
  scope: AUDIT_TRAIL_READ_SCOPE,
140
140
  kind: "reads",
141
- 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."
142
142
  },
143
143
  {
144
144
  method: "GET",
@@ -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>;
@@ -1 +1 @@
1
- {"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/http/responses.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/http/responses.ts"],"names":[],"mappings":"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"}
@@ -205,6 +205,26 @@ const ControlPlaneUsageResponse = z.object({
205
205
  usage: z.array(ControlPlaneUsageView).describe("One row per scope and key exercised, ordered by scope then key."),
206
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.")
207
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`.");
208
228
  /** `GET {base}/control-plane/verify`. */
209
229
  const ChainVerifyResponse = z.object({
210
230
  tenant: z.string().nullable().describe("The tenant whose chain was walked, or null for the untenanted chain."),
@@ -241,4 +261,4 @@ const AuditSinkView = z.object({
241
261
  /** `GET {base}/control-plane/sinks`. */
242
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.");
243
263
  //#endregion
244
- export { AccessChangeView, AccessHistoryResponse, AuditEventDetailView, AuditEventResponse, AuditEventView, AuditEventsResponse, AuditSinkView, AuditSinksResponse, 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 };
@@ -17,7 +17,7 @@ import type { AuditSinks } from "../ship/sinks";
17
17
  * (control-plane: audit:events:read) query: AccessHistoryQuery
18
18
  * GET /audit/control-plane/reach → what one credential reached, by tenant, route and outcome
19
19
  * (control-plane: audit:events:read) query: ControlPlaneReachQuery
20
- * 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
21
21
  * (control-plane: audit:events:read) query: ControlPlaneUsageQuery
22
22
  * GET /audit/control-plane/verify → whether one tenant's hash chain is whole, or where it breaks
23
23
  * (control-plane: audit:events:export) query: ChainVerifyQuery
@@ -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;AAIpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAiChD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,CAmblG"}
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"}
@@ -9,9 +9,9 @@ import { reachPatterns } from "../routePattern.js";
9
9
  import { controlPlaneReach, controlPlaneReachSubjects } from "../reach.js";
10
10
  import { readSinkStates } from "../ship/state.js";
11
11
  import { controlPlaneUsage } from "../usage.js";
12
- import { AccessHistoryResponse, AuditEventResponse, AuditEventsResponse, AuditSinksResponse, ChainExportResponse, ChainVerifyResponse, ControlPlaneReachResponse, ControlPlaneUsageResponse } from "./responses.js";
12
+ import { AccessHistoryResponse, AuditEventResponse, AuditEventsResponse, AuditSinksResponse, ChainExportResponse, ChainVerifyResponse, ControlPlaneReachResponse, ControlPlaneUsageReadResponse } from "./responses.js";
13
13
  import { AccessHistoryQuery, AuditEventIdParam, ChainExportQuery, ChainVerifyQuery, ControlPlaneReachQuery, ControlPlaneUsageQuery, ListAuditEventsQuery } from "./schemas.js";
14
- import { accessChangeView, auditEventDetailView, auditEventView, auditSinkViews, controlPlaneReachSubjectView, controlPlaneReachView, controlPlaneUsageView } from "./views.js";
14
+ import { accessChangeView, auditEventDetailView, auditEventView, auditSinkViews, controlPlaneConnectionUsageViews, controlPlaneReachSubjectView, controlPlaneReachView, controlPlaneUsageView } from "./views.js";
15
15
  import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
16
16
  import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
17
17
  import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
@@ -293,15 +293,16 @@ function registerAuditRoutes(options) {
293
293
  });
294
294
  /**
295
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. Behind the listing scope, not the detail one: the
297
- * answer is the scope, the key, and the last allowed call's method and path, and never an IP, a user-agent or any
298
- * other metadata key.
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.
299
300
  */
300
301
  app.get(`${base}/control-plane/usage`, describeRoute({
301
- 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.",
302
303
  verification: "control-plane",
303
304
  scopes: [AUDIT_TRAIL_READ_SCOPE],
304
- responses: { 200: ControlPlaneUsageResponse }
305
+ responses: { 200: ControlPlaneUsageReadResponse }
305
306
  }), requireControlPlane(AUDIT_TRAIL_READ_SCOPE), validate("query", ControlPlaneUsageQuery), async (c) => {
306
307
  const operator = caller(c);
307
308
  const query = c.req.valid("query");
@@ -309,32 +310,41 @@ function registerAuditRoutes(options) {
309
310
  since: query.since,
310
311
  until: query.until ?? /* @__PURE__ */ new Date()
311
312
  };
313
+ const named = query.connectionId;
312
314
  const result = await controlPlaneUsage(database(c), {
313
- connectionId: query.connectionId,
315
+ ...named !== void 0 ? { connectionId: named } : {},
314
316
  ...window
315
317
  });
318
+ const connections = named === void 0 ? controlPlaneConnectionUsageViews(result.usage) : void 0;
316
319
  await c.var.emit({
317
320
  action: AuditTrailActions.usageRead,
318
321
  outcome: "success",
319
322
  actorType: "control-plane",
320
323
  actorId: operator.subject,
321
324
  resourceType: "controlplane_connection",
322
- resourceId: query.connectionId,
325
+ ...named !== void 0 ? { resourceId: named } : {},
323
326
  requestId: c.req.header("cf-ray"),
324
327
  ip: c.req.header("cf-connecting-ip"),
325
328
  userAgent: c.req.header("user-agent"),
326
329
  metadata: {
327
330
  connectionId: operator.connectionId,
328
331
  query: {
329
- connectionId: query.connectionId,
332
+ connectionId: named ?? null,
330
333
  since: window.since.toISOString(),
331
334
  until: window.until.toISOString()
332
335
  },
336
+ ...connections !== void 0 ? { connections: connections.map((entry) => entry.connectionId) } : {},
333
337
  returned: result.usage.length
334
338
  }
335
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);
336
346
  return c.json({
337
- connectionId: query.connectionId,
347
+ connectionId: named,
338
348
  since: window.since.toISOString(),
339
349
  until: window.until.toISOString(),
340
350
  usage: result.usage.map(controlPlaneUsageView),
@@ -448,8 +458,8 @@ function registerAuditRoutes(options) {
448
458
  });
449
459
  /**
450
460
  * CONTROL-PLANE READ. Every declared sink beside its own delivery row: one primary-key lookup per sink, bounded
451
- * by the config. Not audited, unlike the trail's reads: it reads delivery state, never the trail, and a pane
452
- * polling it would otherwise append to the trail, and ship to every sink, on each poll.
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.
453
463
  */
454
464
  app.get(`${base}/control-plane/sinks`, describeRoute({
455
465
  summary: "List every sink the trail ships to, each with its backlog, last delivery and dead letters.",
@@ -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"}
@@ -54,7 +54,8 @@ const ListAuditEventsQuery = z.object({
54
54
  actorType: AuditActorType.optional().describe("Filter to one kind of principal. `control-plane` is the one that separates a management client's own actions from the adopter's users'."),
55
55
  actorId: FilterValue.optional().describe("Filter to one principal — a user id, a service name, a token subject."),
56
56
  actorKind: ControlPlaneActorKind.optional().describe("Filter to one kind of client: `agent`, `dashboard` or `script`. `agent` finds a management agent's rows and every row a user's MCP client wrote, on both paths."),
57
- action: AuditAction.max(MAX_FILTER_LENGTH).optional().describe("Filter to one exact `domain/reason` action code. Exact, never a prefix — the taxonomy is federated."),
57
+ action: AuditAction.max(MAX_FILTER_LENGTH).optional().describe("Filter to one exact `domain/reason` action code. Exact; `actionPrefix` is the domain-wide filter."),
58
+ actionPrefix: z.string().regex(/^[a-z][a-z0-9]*\/?$/, "An action prefix is one domain, lowercase, with or without its trailing `/` (e.g. `auth` or `auth/`).").max(MAX_FILTER_LENGTH).transform((value) => value.replace(/\/$/, "")).optional().describe("Filter to every action under one domain — `auth` or `auth/` matches `auth/login` and `auth/logout`, never `authority/granted`. The domain is the only prefix: a reason is never matched by its start."),
58
59
  outcome: AuditOutcome.optional().describe("Filter to one outcome. `denied` is the one worth watching: a run of denials is what a credential being probed looks like."),
59
60
  severity: AuditSeverity.optional().describe("Filter to one severity."),
60
61
  resourceType: FilterValue.optional().describe("Filter to the kind of thing acted on (`user`, `secret`)."),
@@ -112,19 +113,20 @@ const ControlPlaneReachQuery = z.object({
112
113
  /**
113
114
  * The usage query: whose calls to count, and over what window.
114
115
  *
115
- * `connectionId` and `since` are required, so a missing one is a 400 before any query runs — an unbounded window over
116
- * every connection is not a question this route answers. `until` defaults to now in the handler, which is the one
117
- * value a schema cannot compute for a request. A window that ends before it starts is refused rather than answered
118
- * with nothing, because nothing would read as an idle connection.
116
+ * `since` is required, so a missing one is a 400 before any query runs — an unbounded window is not a question this
117
+ * route answers. `connectionId` is optional: named, the route counts that connection's calls; left out, it counts every
118
+ * connection's, which is the over-grant question across a Worker in one read. `until` defaults to now in the
119
+ * handler, which is the one value a schema cannot compute for a request. A window that ends before it starts is
120
+ * refused rather than answered with nothing, because nothing would read as an idle connection.
119
121
  */
120
122
  const ControlPlaneUsageQuery = z.object({
121
- connectionId: FilterValue.describe("The control-plane connection whose calls to count — the `resourceId` its call rows carry. Required."),
123
+ connectionId: FilterValue.optional().describe("The control-plane connection whose calls to count — the `resourceId` its call rows carry. Omit it to count every connection's."),
122
124
  since: TimeBound.describe("Inclusive lower bound on when a call landed, ISO-8601. Required."),
123
125
  until: TimeBound.optional().describe("Inclusive upper bound on when a call landed, ISO-8601. Defaults to now.")
124
126
  }).refine((query) => query.until === void 0 || query.until.getTime() >= query.since.getTime(), {
125
127
  message: "`until` must not be before `since`.",
126
128
  path: ["until"]
127
- }).describe("The control-plane usage query: one connection, over a window.");
129
+ }).describe("The control-plane usage query: one connection or every connection, over a window.");
128
130
  /**
129
131
  * The tenant whose chain to read. **Required**, because there is no "every chain": a chain is one tenant's.
130
132
  * Send it empty (`?tenant=`) for the untenanted chain — the same encoding the listing's filter uses.
@@ -6,7 +6,7 @@ import type { AuditSinkStateRow } from "../data/sinkState";
6
6
  import type { ControlPlaneReachRow, ControlPlaneReachSubjectRow } from "../reach";
7
7
  import type { AuditSinks } from "../ship/sinks";
8
8
  import type { ControlPlaneUsageRow } from "../usage";
9
- import type { AccessChangeView, AuditEventDetailView, AuditEventView, AuditSinkView, ControlPlaneReachSubjectView, ControlPlaneReachView, ControlPlaneUsageView } from "./responses";
9
+ import type { AccessChangeView, AuditEventDetailView, AuditEventView, AuditSinkView, ControlPlaneConnectionUsageView, ControlPlaneReachSubjectView, ControlPlaneReachView, ControlPlaneUsageView } from "./responses";
10
10
  /**
11
11
  * What a management client is shown of an audit event — decided here, once, rather than by whichever
12
12
  * columns a query happened to select.
@@ -78,6 +78,11 @@ export declare function controlPlaneReachSubjectView(row: ControlPlaneReachSubje
78
78
  * the scope, the key, and the last allowed call's method and path out of `metadata`, so there is nothing here to drop.
79
79
  */
80
80
  export declare function controlPlaneUsageView(row: ControlPlaneUsageRow): ControlPlaneUsageView;
81
+ /**
82
+ * Fold every connection's usage rows into one entry per connection, in the order the aggregate returned them —
83
+ * by connection, then scope, then key — so each connection's rows keep the order a named read gives them.
84
+ */
85
+ export declare function controlPlaneConnectionUsageViews(rows: readonly ControlPlaneUsageRow[]): ControlPlaneConnectionUsageView[];
81
86
  /**
82
87
  * Project the declared sinks, in declaration order, each beside its own state row. A sink with no row has never been
83
88
  * attempted and answers null times, zero counts and `idle`; a row whose sink is no longer declared is not answered.
@@ -1 +1 @@
1
- {"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../../src/http/views.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAElF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,aAAa,EACb,4BAA4B,EAC5B,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,cAAc,CA6BjE;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,GAAG,oBAAoB,CAE7E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CA2CxE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,oBAAoB,GAAG,qBAAqB,CActF;AAED,6GAA6G;AAC7G,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,2BAA2B,GAAG,4BAA4B,CAgB3G;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,oBAAoB,GAAG,qBAAqB,CAWtF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,iBAAiB,EAAE,GAAG,aAAa,EAAE,CAuBvG"}
1
+ {"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../../src/http/views.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAElF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,aAAa,EACb,+BAA+B,EAC/B,4BAA4B,EAC5B,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,cAAc,CA6BjE;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,GAAG,oBAAoB,CAE7E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CA2CxE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,oBAAoB,GAAG,qBAAqB,CActF;AAED,6GAA6G;AAC7G,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,2BAA2B,GAAG,4BAA4B,CAgB3G;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,oBAAoB,GAAG,qBAAqB,CAWtF;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,SAAS,oBAAoB,EAAE,GACpC,+BAA+B,EAAE,CAQnC;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,iBAAiB,EAAE,GAAG,aAAa,EAAE,CAuBvG"}
@@ -185,6 +185,22 @@ function controlPlaneUsageView(row) {
185
185
  };
186
186
  }
187
187
  /**
188
+ * Fold every connection's usage rows into one entry per connection, in the order the aggregate returned them —
189
+ * by connection, then scope, then key — so each connection's rows keep the order a named read gives them.
190
+ */
191
+ function controlPlaneConnectionUsageViews(rows) {
192
+ const byConnection = /* @__PURE__ */ new Map();
193
+ for (const row of rows) {
194
+ const usage = byConnection.get(row.connectionId) ?? [];
195
+ usage.push(controlPlaneUsageView(row));
196
+ byConnection.set(row.connectionId, usage);
197
+ }
198
+ return [...byConnection].map(([connectionId, usage]) => ({
199
+ connectionId,
200
+ usage
201
+ }));
202
+ }
203
+ /**
188
204
  * Project the declared sinks, in declaration order, each beside its own state row. A sink with no row has never been
189
205
  * attempted and answers null times, zero counts and `idle`; a row whose sink is no longer declared is not answered.
190
206
  *
@@ -216,4 +232,4 @@ function auditSinkViews(sinks, states) {
216
232
  });
217
233
  }
218
234
  //#endregion
219
- export { accessChangeView, auditEventDetailView, auditEventView, auditSinkViews, controlPlaneReachSubjectView, controlPlaneReachView, controlPlaneUsageView };
235
+ export { accessChangeView, auditEventDetailView, auditEventView, auditSinkViews, controlPlaneConnectionUsageViews, controlPlaneReachSubjectView, controlPlaneReachView, controlPlaneUsageView };
package/dist/query.d.ts CHANGED
@@ -26,6 +26,8 @@ export interface AuditQuery {
26
26
  actorKind?: ControlPlaneActorKind;
27
27
  /** Match an exact `domain/reason` action code. */
28
28
  action?: string;
29
+ /** Match every action under one domain — `auth` matches `auth/login`, never `authority/granted`. */
30
+ actionPrefix?: string;
29
31
  /** Match the outcome (`success` | `failure` | `denied`). */
30
32
  outcome?: AuditOutcome;
31
33
  /** Match the severity (`info` | `warning` | `critical`). */
@@ -1 +1 @@
1
- {"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACvG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iDAAiD,CAAC;AAG7F,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,6CAA6C;IAC7C,EAAE,CAAC,EAAE,IAAI,CAAC;IACV;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,mEAAmE;IACnE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAyDD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,aAAa,EAAE,MAAM,GAAE,UAAe,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAK3G;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,EAAE,EAAE,aAAa,EAAE,MAAM,GAAE,UAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAuBzG;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAGtG"}
1
+ {"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACvG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iDAAiD,CAAC;AAG7F,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oGAAoG;IACpG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,6CAA6C;IAC7C,EAAE,CAAC,EAAE,IAAI,CAAC;IACV;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,mEAAmE;IACnE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AA8DD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,aAAa,EAAE,MAAM,GAAE,UAAe,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAK3G;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,EAAE,EAAE,aAAa,EAAE,MAAM,GAAE,UAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAuBzG;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAGtG"}
package/dist/query.js CHANGED
@@ -18,6 +18,7 @@ function auditEventQuery(db, filter) {
18
18
  if (filter.actorId !== void 0) query = query.where("actorId", "=", filter.actorId);
19
19
  if (filter.actorKind !== void 0) query = query.where("actorKind", "=", filter.actorKind);
20
20
  if (filter.action !== void 0) query = query.where("action", "=", filter.action);
21
+ if (filter.actionPrefix !== void 0) query = query.where("action", ">=", `${filter.actionPrefix}/`).where("action", "<", `${filter.actionPrefix}0`);
21
22
  if (filter.outcome !== void 0) query = query.where("outcome", "=", filter.outcome);
22
23
  if (filter.severity !== void 0) query = query.where("severity", "=", filter.severity);
23
24
  if (filter.resourceType !== void 0) query = query.where("resourceType", "=", filter.resourceType);
package/dist/usage.d.ts CHANGED
@@ -3,25 +3,31 @@
3
3
  import { z } from "zod";
4
4
  import type { AuditDatabase } from "./data/tables";
5
5
  /**
6
- * Which scopes a control-plane connection exercised, and which it was refused — `#812`.
6
+ * Which scopes a control-plane connection exercised, and which it was refused — `#812` — for one connection or every
7
+ * connection at once.
7
8
  *
8
9
  * Every admitted call writes `controlplane/call_allowed`, and every verified call refused a scope writes
9
10
  * `controlplane/call_denied`, both against the connection as `resourceId` and both naming the scope and key in
10
11
  * `metadata`. Answering "granted twelve, used three" from the listing would take one forensic read per event, behind
11
12
  * the scope that also discloses the client IP; this reads the same rows in SQL and returns counts.
12
13
  *
14
+ * **One connection, or every one.** Over-grant — scopes a credential holds and never used — is a question over every
15
+ * connection on the Worker, so leaving the connection out counts them all in the same statement, grouped by connection
16
+ * first. A connection that made no call in the window has no row: the caller joins against the connection listing.
17
+ *
13
18
  * **One statement for the aggregate, never a page walk.** A dashboard connection makes thousands of calls a day, and a
14
19
  * handler that paged them to count would be the largest read on the surface. The `GROUP BY` runs in D1, over rows
15
- * `pithyAuditEventsCallIdx` (`audit_0003_call_index`) finds by action, connection and time.
20
+ * `pithyAuditEventsCallIdx` (`audit_0003_call_index`) finds by action, connection and time — or, across every
21
+ * connection, rows `pithyAuditEventsOccurredAtIdx` finds by the window.
16
22
  *
17
23
  * **Nothing personal leaves this function.** It reads the scope, the key id, and the method and path of the last
18
24
  * allowed call out of `metadata`, and no other key, and never the IP or the user-agent. Those four are the management
19
25
  * client's own footprint.
20
26
  */
21
- /** What to count: one connection, over an inclusive window. */
27
+ /** What to count: one connection, or every connection, over an inclusive window. */
22
28
  export interface ControlPlaneUsageFilter {
23
- /** The connection whose calls are counted — the rows' `resourceId`. */
24
- connectionId: string;
29
+ /** The connection whose calls are counted — the rows' `resourceId`. Absent, every connection's calls are. */
30
+ connectionId?: string;
25
31
  /** Inclusive lower bound on `occurredAt`. */
26
32
  since: Date;
27
33
  /** Inclusive upper bound on `occurredAt`. */
@@ -33,6 +39,7 @@ export interface ControlPlaneUsageFilter {
33
39
  * Internal: the wire shape is `ControlPlaneUsageView` in `http/responses.ts`, and `http/views.ts` projects this into it.
34
40
  */
35
41
  export declare const ControlPlaneUsageRow: z.ZodObject<{
42
+ connectionId: z.ZodString;
36
43
  scope: z.ZodString;
37
44
  keyId: z.ZodNullable<z.ZodString>;
38
45
  allowed: z.ZodNumber;
@@ -45,7 +52,7 @@ export declare const ControlPlaneUsageRow: z.ZodObject<{
45
52
  export type ControlPlaneUsageRow = z.output<typeof ControlPlaneUsageRow>;
46
53
  /** What {@link controlPlaneUsage} answers. */
47
54
  export interface ControlPlaneUsage {
48
- /** One row per `(scope, keyId)` exercised, ordered by scope then key. */
55
+ /** One row per `(connectionId, scope, keyId)` exercised, ordered by connection, then scope, then key. */
49
56
  usage: ControlPlaneUsageRow[];
50
57
  /** The oldest event the trail holds, or null on an empty trail. */
51
58
  oldestEventAt: Date | null;
@@ -55,13 +62,19 @@ export interface ControlPlaneUsage {
55
62
  *
56
63
  * Three steps, in one statement:
57
64
  *
58
- * 1. **`calls`** — the connection's call rows in the window, with the scope, key, method and path lifted out of
59
- * `metadata`. The scope is read from where each writer puts it: an allowed row carries the token's `scope`; a gate
65
+ * 1. **`calls`** — the connection's call rows in the window, or every connection's when none is named, with the
66
+ * connection beside the scope, key, method and path lifted out of `metadata`. The scope is read from where each writer puts it: an allowed row carries the token's `scope`; a gate
60
67
  * refusal names the scope it required as `required`, and a handler's refusal as `scope`, so a denied row reads
61
68
  * `required` first. A row with no scope at all is nobody's usage and is dropped.
62
- * 2. **`ranked`** — each row's recency within its `(scope, keyId, action)`, newest first, `id` breaking a tie. Rank 1
63
- * of the allowed rows is the last allowed call, whose method and path the answer carries.
64
- * 3. **The group** — counts and last instants per `(scope, keyId)`.
69
+ * 2. **`ranked`** — each row's recency within its `(connectionId, scope, keyId, action)`, newest first, `id`
70
+ * breaking a tie. Rank 1 of the allowed rows is the last allowed call, whose method and path the answer carries.
71
+ * 3. **The group** — counts and last instants per `(connectionId, scope, keyId)`.
72
+ *
73
+ * Named, it seeks `pithyAuditEventsCallIdx`: each action, then the connection, then the window as a range. Unnamed,
74
+ * nothing narrows it but the actions and the window, and the window is what is small: an access review reads days of
75
+ * a trail that keeps months. So the planner reads `pithyAuditEventsOccurredAtIdx` over the window and checks the
76
+ * action on each row it finds, and the cost follows the window rather than everything retention holds. A row with no
77
+ * connection — an unverified refusal — is nobody's usage in either.
65
78
  */
66
79
  export declare function controlPlaneUsageStatement(db: AuditDatabase, filter: ControlPlaneUsageFilter): import("kysely").SelectQueryBuilder<import("@pithy-sh/core/src/data/db").DatabaseSchema<{
67
80
  pithyAuditEvents: z.ZodObject<{
@@ -119,6 +132,7 @@ export declare function controlPlaneUsageStatement(db: AuditDatabase, filter: Co
119
132
  }> & {
120
133
  calls: {
121
134
  action: string;
135
+ connectionId: string | null;
122
136
  id: number;
123
137
  keyId: string | null;
124
138
  method: string | null;
@@ -129,6 +143,7 @@ export declare function controlPlaneUsageStatement(db: AuditDatabase, filter: Co
129
143
  } & {
130
144
  ranked: {
131
145
  action: string;
146
+ connectionId: string | null;
132
147
  id: number;
133
148
  keyId: string | null;
134
149
  method: string | null;
@@ -139,6 +154,7 @@ export declare function controlPlaneUsageStatement(db: AuditDatabase, filter: Co
139
154
  };
140
155
  }, "ranked", {
141
156
  allowed: number;
157
+ connectionId: string | null;
142
158
  denied: number;
143
159
  keyId: string | null;
144
160
  lastAllowedAt: number | null;
@@ -148,7 +164,8 @@ export declare function controlPlaneUsageStatement(db: AuditDatabase, filter: Co
148
164
  scope: string | null;
149
165
  }>;
150
166
  /**
151
- * Count one connection's calls by scope and key, over an inclusive window.
167
+ * Count one connection's calls by scope and key, or every connection's by connection, scope and key, over an
168
+ * inclusive window.
152
169
  *
153
170
  * `oldestEventAt` is the oldest event the trail holds at all, for any connection or none. Retention prunes the trail
154
171
  * by time, never per connection, so this is how far back any connection's answer can reach: a window starting before
@@ -1 +1 @@
1
- {"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;;;;;;;;;;;;;;GAeG;AAEH,+DAA+D;AAC/D,MAAM,WAAW,uBAAuB;IACtC,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,KAAK,EAAE,IAAI,CAAC;IACZ,6CAA6C;IAC7C,KAAK,EAAE,IAAI,CAAC;CACb;AAQD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;iBAkBkE,CAAC;AACpG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AASzE,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,mEAAmE;IACnE,aAAa,EAAE,IAAI,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwD5F;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,aAAa,EACjB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,iBAAiB,CAAC,CAU5B"}
1
+ {"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,oFAAoF;AACpF,MAAM,WAAW,uBAAuB;IACtC,6GAA6G;IAC7G,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,KAAK,EAAE,IAAI,CAAC;IACZ,6CAA6C;IAC7C,KAAK,EAAE,IAAI,CAAC;CACb;AAQD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;iBAmBkE,CAAC;AACpG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AASzE,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,yGAAyG;IACzG,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,mEAAmE;IACnE,aAAa,EAAE,IAAI,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+D5F;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,aAAa,EACjB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,iBAAiB,CAAC,CAU5B"}
package/dist/usage.js CHANGED
@@ -15,6 +15,7 @@ const CONNECTION_RESOURCE = "controlplane_connection";
15
15
  * Internal: the wire shape is `ControlPlaneUsageView` in `http/responses.ts`, and `http/views.ts` projects this into it.
16
16
  */
17
17
  const ControlPlaneUsageRow = z.object({
18
+ connectionId: z.string().describe("The connection that made the calls — the rows' `resourceId`."),
18
19
  scope: z.string().describe("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."),
19
20
  keyId: z.string().nullable().describe("The registered key that signed the calls. Null for a row that recorded none."),
20
21
  allowed: z.number().int().describe("How many `controlplane/call_allowed` events in the window."),
@@ -31,13 +32,19 @@ const OldestEvent = z.object({ oldest: SQLiteDate.nullable().describe("The small
31
32
  *
32
33
  * Three steps, in one statement:
33
34
  *
34
- * 1. **`calls`** — the connection's call rows in the window, with the scope, key, method and path lifted out of
35
- * `metadata`. The scope is read from where each writer puts it: an allowed row carries the token's `scope`; a gate
35
+ * 1. **`calls`** — the connection's call rows in the window, or every connection's when none is named, with the
36
+ * connection beside the scope, key, method and path lifted out of `metadata`. The scope is read from where each writer puts it: an allowed row carries the token's `scope`; a gate
36
37
  * refusal names the scope it required as `required`, and a handler's refusal as `scope`, so a denied row reads
37
38
  * `required` first. A row with no scope at all is nobody's usage and is dropped.
38
- * 2. **`ranked`** — each row's recency within its `(scope, keyId, action)`, newest first, `id` breaking a tie. Rank 1
39
- * of the allowed rows is the last allowed call, whose method and path the answer carries.
40
- * 3. **The group** — counts and last instants per `(scope, keyId)`.
39
+ * 2. **`ranked`** — each row's recency within its `(connectionId, scope, keyId, action)`, newest first, `id`
40
+ * breaking a tie. Rank 1 of the allowed rows is the last allowed call, whose method and path the answer carries.
41
+ * 3. **The group** — counts and last instants per `(connectionId, scope, keyId)`.
42
+ *
43
+ * Named, it seeks `pithyAuditEventsCallIdx`: each action, then the connection, then the window as a range. Unnamed,
44
+ * nothing narrows it but the actions and the window, and the window is what is small: an access review reads days of
45
+ * a trail that keeps months. So the planner reads `pithyAuditEventsOccurredAtIdx` over the window and checks the
46
+ * action on each row it finds, and the cost follows the window rather than everything retention holds. A row with no
47
+ * connection — an unverified refusal — is nobody's usage in either.
41
48
  */
42
49
  function controlPlaneUsageStatement(db, filter) {
43
50
  const allowed = ControlPlaneAuditActions.callAllowed;
@@ -46,15 +53,17 @@ function controlPlaneUsageStatement(db, filter) {
46
53
  "id",
47
54
  "action",
48
55
  "occurredAt",
56
+ eb.ref("resourceId").as("connectionId"),
49
57
  sql`case when ${eb.ref("action")} = ${denied}
50
58
  then coalesce(json_extract(${eb.ref("metadata")}, '$.required'), json_extract(${eb.ref("metadata")}, '$.scope'))
51
59
  else json_extract(${eb.ref("metadata")}, '$.scope') end`.as("scope"),
52
60
  sql`json_extract(${eb.ref("metadata")}, '$.keyId')`.as("keyId"),
53
61
  sql`json_extract(${eb.ref("metadata")}, '$.method')`.as("method"),
54
62
  sql`json_extract(${eb.ref("metadata")}, '$.path')`.as("path")
55
- ]).where("action", "in", CALL_ACTIONS).where("resourceId", "=", filter.connectionId).where("occurredAt", ">=", SQLiteDate.encode(filter.since)).where("occurredAt", "<=", SQLiteDate.encode(filter.until)).where("resourceType", "=", CONNECTION_RESOURCE)).with("ranked", (q) => q.selectFrom("calls").selectAll().select(sql`row_number() over (
56
- partition by ${sql.ref("scope")}, ${sql.ref("keyId")}, ${sql.ref("action")}
63
+ ]).where("action", "in", CALL_ACTIONS).where((eb) => filter.connectionId === void 0 ? eb("resourceId", "is not", null) : eb("resourceId", "=", filter.connectionId)).where("occurredAt", ">=", SQLiteDate.encode(filter.since)).where("occurredAt", "<=", SQLiteDate.encode(filter.until)).where("resourceType", "=", CONNECTION_RESOURCE)).with("ranked", (q) => q.selectFrom("calls").selectAll().select(sql`row_number() over (
64
+ partition by ${sql.ref("connectionId")}, ${sql.ref("scope")}, ${sql.ref("keyId")}, ${sql.ref("action")}
57
65
  order by ${sql.ref("occurredAt")} desc, ${sql.ref("id")} desc)`.as("recency")).where("scope", "is not", null)).selectFrom("ranked").select((eb) => [
66
+ "connectionId",
58
67
  "scope",
59
68
  "keyId",
60
69
  sql`sum(case when ${eb.ref("action")} = ${allowed} then 1 else 0 end)`.as("allowed"),
@@ -65,10 +74,15 @@ function controlPlaneUsageStatement(db, filter) {
65
74
  sql`max(case when ${eb.ref("action")} = ${allowed} and ${eb.ref("recency")} = 1
66
75
  then ${eb.ref("path")} end)`.as("lastAllowedPath"),
67
76
  sql`max(case when ${eb.ref("action")} = ${denied} then ${eb.ref("occurredAt")} end)`.as("lastDeniedAt")
68
- ]).groupBy(["scope", "keyId"]).orderBy("scope").orderBy("keyId");
77
+ ]).groupBy([
78
+ "connectionId",
79
+ "scope",
80
+ "keyId"
81
+ ]).orderBy("connectionId").orderBy("scope").orderBy("keyId");
69
82
  }
70
83
  /**
71
- * Count one connection's calls by scope and key, over an inclusive window.
84
+ * Count one connection's calls by scope and key, or every connection's by connection, scope and key, over an
85
+ * inclusive window.
72
86
  *
73
87
  * `oldestEventAt` is the oldest event the trail holds at all, for any connection or none. Retention prunes the trail
74
88
  * by time, never per connection, so this is how far back any connection's answer can reach: a window starting before
@@ -3,5 +3,5 @@
3
3
  /** This package's npm name — the join key against a release feed. */
4
4
  export declare const PACKAGE_NAME = "@pithy-sh/audit";
5
5
  /** This package's version, stamped from its own package.json at generation time. */
6
- export declare const PACKAGE_VERSION = "0.8.0";
6
+ export declare const PACKAGE_VERSION = "0.9.0";
7
7
  //# sourceMappingURL=version.generated.d.ts.map
@@ -4,6 +4,6 @@
4
4
  /** This package's npm name — the join key against a release feed. */
5
5
  const PACKAGE_NAME = "@pithy-sh/audit";
6
6
  /** This package's version, stamped from its own package.json at generation time. */
7
- const PACKAGE_VERSION = "0.8.0";
7
+ const PACKAGE_VERSION = "0.9.0";
8
8
  //#endregion
9
9
  export { PACKAGE_NAME, PACKAGE_VERSION };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pithy-sh/audit",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
4
4
  "license": "FSL-1.1-MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -38,8 +38,8 @@
38
38
  "@hono/zod-validator": "^0.9.0"
39
39
  },
40
40
  "peerDependencies": {
41
- "@pithy-sh/core": "^0.16.0",
42
- "@pithy-sh/secrets": "^0.6.4",
41
+ "@pithy-sh/core": "^0.17.0",
42
+ "@pithy-sh/secrets": "^0.6.5",
43
43
  "hono": "^4.13.2",
44
44
  "kysely": "^0.29.0",
45
45
  "zod": "^4.4.0"
@@ -39,9 +39,9 @@ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/sc
39
39
  * the other.
40
40
  *
41
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
42
+ * and key, or every connection's. Its answer is the connection, the scope, the key id, and the method and path of the
43
+ * last allowed call — the management client's own footprint, which the listing already discloses in shape through
44
+ * `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
45
45
  * not have to hold the most dangerous grant audit defines to ask which grants are used.
46
46
  *
47
47
  * **The access history rides the listing scope.** `GET {base}/control-plane/access-history` answers every
@@ -150,7 +150,7 @@ export function auditAdminRoutes(basePath: string): AdminRouteDeclaration[] {
150
150
  scope: AUDIT_TRAIL_READ_SCOPE,
151
151
  kind: "reads",
152
152
  summary:
153
- "Count which scopes one control-plane connection exercised and was refused, by key, over a window. Counts only — no event is read in full.",
153
+ "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.",
154
154
  },
155
155
  {
156
156
  method: "GET",
@@ -368,6 +368,51 @@ export const ControlPlaneUsageResponse = z
368
368
  .describe("Which scopes one control-plane connection exercised and was refused, by key, over a window.");
369
369
  export type ControlPlaneUsageResponse = z.output<typeof ControlPlaneUsageResponse>;
370
370
 
371
+ /** One connection's scopes and keys, in the every-connection usage answer. */
372
+ export const ControlPlaneConnectionUsageView = z
373
+ .object({
374
+ connectionId: z.string().describe("The connection that made the calls."),
375
+ usage: z
376
+ .array(ControlPlaneUsageView)
377
+ .describe("One row per scope and key this connection exercised, ordered by scope then key. Never empty."),
378
+ })
379
+ .describe("One control-plane connection's usage, by scope and key.");
380
+ export type ControlPlaneConnectionUsageView = z.output<typeof ControlPlaneConnectionUsageView>;
381
+
382
+ /**
383
+ * `GET {base}/control-plane/usage` with no `connectionId`: every connection that called in the window.
384
+ *
385
+ * A shape of its own, beside {@link ControlPlaneUsageResponse}, so the answer to a named connection is unchanged and
386
+ * a client that names one parses what it always did. Told apart by its keys: `connections` here, `connectionId` and
387
+ * `usage` there.
388
+ */
389
+ export const ControlPlaneUsageAllResponse = z
390
+ .object({
391
+ since: z.iso.datetime().describe("The window's inclusive start, ISO-8601."),
392
+ until: z.iso.datetime().describe("The window's inclusive end, ISO-8601 — now, when the query named none."),
393
+ connections: z
394
+ .array(ControlPlaneConnectionUsageView)
395
+ .describe(
396
+ "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.",
397
+ ),
398
+ oldestEventAt: z.iso
399
+ .datetime()
400
+ .nullable()
401
+ .describe(
402
+ "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.",
403
+ ),
404
+ })
405
+ .describe("Which scopes every control-plane connection exercised and was refused, by key, over a window.");
406
+ export type ControlPlaneUsageAllResponse = z.output<typeof ControlPlaneUsageAllResponse>;
407
+
408
+ /** What the usage route answers: one connection's usage when the query names one, every connection's when not. */
409
+ export const ControlPlaneUsageReadResponse = z
410
+ .union([ControlPlaneUsageResponse, ControlPlaneUsageAllResponse])
411
+ .describe(
412
+ "One connection's usage when `connectionId` is named, as `ControlPlaneUsageResponse`; every connection's when it is not, as `ControlPlaneUsageAllResponse`.",
413
+ );
414
+ export type ControlPlaneUsageReadResponse = z.output<typeof ControlPlaneUsageReadResponse>;
415
+
371
416
  /** `GET {base}/control-plane/verify`. */
372
417
  export const ChainVerifyResponse = z
373
418
  .object({
@@ -31,7 +31,9 @@ import {
31
31
  ChainExportResponse,
32
32
  ChainVerifyResponse,
33
33
  ControlPlaneReachResponse,
34
- ControlPlaneUsageResponse,
34
+ type ControlPlaneUsageAllResponse,
35
+ ControlPlaneUsageReadResponse,
36
+ type ControlPlaneUsageResponse,
35
37
  } from "./responses";
36
38
  import {
37
39
  AccessHistoryQuery,
@@ -47,6 +49,7 @@ import {
47
49
  auditEventDetailView,
48
50
  auditEventView,
49
51
  auditSinkViews,
52
+ controlPlaneConnectionUsageViews,
50
53
  controlPlaneReachSubjectView,
51
54
  controlPlaneReachView,
52
55
  controlPlaneUsageView,
@@ -61,7 +64,7 @@ import {
61
64
  * (control-plane: audit:events:read) query: AccessHistoryQuery
62
65
  * GET /audit/control-plane/reach → what one credential reached, by tenant, route and outcome
63
66
  * (control-plane: audit:events:read) query: ControlPlaneReachQuery
64
- * GET /audit/control-plane/usage → one connection's calls, counted by scope and key
67
+ * GET /audit/control-plane/usage → one connection's calls, or every connection's, counted by scope and key
65
68
  * (control-plane: audit:events:read) query: ControlPlaneUsageQuery
66
69
  * GET /audit/control-plane/verify → whether one tenant's hash chain is whole, or where it breaks
67
70
  * (control-plane: audit:events:export) query: ChainVerifyQuery
@@ -412,17 +415,19 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
412
415
 
413
416
  /**
414
417
  * CONTROL-PLANE READ. Which scopes one connection exercised and was refused, by key, over a window —
415
- * counted in one SQL statement, never by paging events here. Behind the listing scope, not the detail one: the
416
- * answer is the scope, the key, and the last allowed call's method and path, and never an IP, a user-agent or any
417
- * other metadata key.
418
+ * counted in one SQL statement, never by paging events here. With no `connectionId`, every connection that called
419
+ * in the window, each with its own scopes and keys, from the same one statement. Behind the listing
420
+ * scope, not the detail one: the answer is the connection, the scope, the key, and the last allowed call's method
421
+ * and path, and never an IP, a user-agent or any other metadata key.
418
422
  */
419
423
  app.get(
420
424
  `${base}/control-plane/usage`,
421
425
  describeRoute({
422
- summary: "Count which scopes one control-plane connection exercised and was refused, by key, over a window.",
426
+ summary:
427
+ "Count which scopes one control-plane connection, or every one, exercised and was refused, by key, over a window.",
423
428
  verification: "control-plane",
424
429
  scopes: [AUDIT_TRAIL_READ_SCOPE],
425
- responses: { 200: ControlPlaneUsageResponse },
430
+ responses: { 200: ControlPlaneUsageReadResponse },
426
431
  }),
427
432
  requireControlPlane(AUDIT_TRAIL_READ_SCOPE),
428
433
  validate("query", ControlPlaneUsageQuery),
@@ -430,32 +435,51 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
430
435
  const operator = caller(c);
431
436
  const query = c.req.valid("query");
432
437
  const window = { since: query.since, until: query.until ?? new Date() };
433
- const result = await controlPlaneUsage(database(c), { connectionId: query.connectionId, ...window });
434
- // Audited like the listing, and against the connection whose usage was read: "who reviewed this
435
- // connection's grants" is a question the trail should answer about that connection.
438
+ const named = query.connectionId;
439
+ const result = await controlPlaneUsage(database(c), {
440
+ ...(named !== undefined ? { connectionId: named } : {}),
441
+ ...window,
442
+ });
443
+ const connections = named === undefined ? controlPlaneConnectionUsageViews(result.usage) : undefined;
444
+ // Audited like the listing, once. Named, against the connection whose usage was read: "who reviewed this
445
+ // connection's grants" is a question the trail should answer about that connection. Unnamed, against no
446
+ // one connection: `query.connectionId` is null, which is "every connection", and `connections` names each
447
+ // one the answer covered, so the same question still finds this read from any of them.
436
448
  await c.var.emit({
437
449
  action: AuditTrailActions.usageRead,
438
450
  outcome: "success",
439
451
  actorType: "control-plane",
440
452
  actorId: operator.subject,
441
453
  resourceType: "controlplane_connection",
442
- resourceId: query.connectionId,
454
+ ...(named !== undefined ? { resourceId: named } : {}),
443
455
  requestId: c.req.header("cf-ray"),
444
456
  ip: c.req.header("cf-connecting-ip"),
445
457
  userAgent: c.req.header("user-agent"),
446
458
  metadata: {
447
459
  connectionId: operator.connectionId,
448
460
  query: {
449
- connectionId: query.connectionId,
461
+ connectionId: named ?? null,
450
462
  since: window.since.toISOString(),
451
463
  until: window.until.toISOString(),
452
464
  },
465
+ ...(connections !== undefined ? { connections: connections.map((entry) => entry.connectionId) } : {}),
453
466
  returned: result.usage.length,
454
467
  },
455
468
  });
469
+ if (named === undefined) {
470
+ return c.json(
471
+ {
472
+ since: window.since.toISOString(),
473
+ until: window.until.toISOString(),
474
+ connections: connections ?? [],
475
+ oldestEventAt: result.oldestEventAt?.toISOString() ?? null,
476
+ } satisfies ControlPlaneUsageAllResponse,
477
+ 200,
478
+ );
479
+ }
456
480
  return c.json(
457
481
  {
458
- connectionId: query.connectionId,
482
+ connectionId: named,
459
483
  since: window.since.toISOString(),
460
484
  until: window.until.toISOString(),
461
485
  usage: result.usage.map(controlPlaneUsageView),
@@ -599,8 +623,8 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
599
623
 
600
624
  /**
601
625
  * CONTROL-PLANE READ. Every declared sink beside its own delivery row: one primary-key lookup per sink, bounded
602
- * by the config. Not audited, unlike the trail's reads: it reads delivery state, never the trail, and a pane
603
- * polling it would otherwise append to the trail, and ship to every sink, on each poll.
626
+ * by the config. Records no audit action of its own, unlike the trail's reads: it reads delivery state, never
627
+ * the trail, so the gate's `controlplane/call_allowed` row is its only record.
604
628
  */
605
629
  app.get(
606
630
  `${base}/control-plane/sinks`,
@@ -81,7 +81,19 @@ export const ListAuditEventsQuery = z
81
81
  ),
82
82
  action: AuditAction.max(MAX_FILTER_LENGTH)
83
83
  .optional()
84
- .describe("Filter to one exact `domain/reason` action code. Exact, never a prefix — the taxonomy is federated."),
84
+ .describe("Filter to one exact `domain/reason` action code. Exact; `actionPrefix` is the domain-wide filter."),
85
+ actionPrefix: z
86
+ .string()
87
+ .regex(
88
+ /^[a-z][a-z0-9]*\/?$/,
89
+ "An action prefix is one domain, lowercase, with or without its trailing `/` (e.g. `auth` or `auth/`).",
90
+ )
91
+ .max(MAX_FILTER_LENGTH)
92
+ .transform((value) => value.replace(/\/$/, ""))
93
+ .optional()
94
+ .describe(
95
+ "Filter to every action under one domain — `auth` or `auth/` matches `auth/login` and `auth/logout`, never `authority/granted`. The domain is the only prefix: a reason is never matched by its start.",
96
+ ),
85
97
  outcome: AuditOutcome.optional().describe(
86
98
  "Filter to one outcome. `denied` is the one worth watching: a run of denials is what a credential being probed looks like.",
87
99
  ),
@@ -191,15 +203,16 @@ export type ControlPlaneReachQuery = z.infer<typeof ControlPlaneReachQuery>;
191
203
  /**
192
204
  * The usage query: whose calls to count, and over what window.
193
205
  *
194
- * `connectionId` and `since` are required, so a missing one is a 400 before any query runs — an unbounded window over
195
- * every connection is not a question this route answers. `until` defaults to now in the handler, which is the one
196
- * value a schema cannot compute for a request. A window that ends before it starts is refused rather than answered
197
- * with nothing, because nothing would read as an idle connection.
206
+ * `since` is required, so a missing one is a 400 before any query runs — an unbounded window is not a question this
207
+ * route answers. `connectionId` is optional: named, the route counts that connection's calls; left out, it counts every
208
+ * connection's, which is the over-grant question across a Worker in one read. `until` defaults to now in the
209
+ * handler, which is the one value a schema cannot compute for a request. A window that ends before it starts is
210
+ * refused rather than answered with nothing, because nothing would read as an idle connection.
198
211
  */
199
212
  export const ControlPlaneUsageQuery = z
200
213
  .object({
201
- connectionId: FilterValue.describe(
202
- "The control-plane connection whose calls to count — the `resourceId` its call rows carry. Required.",
214
+ connectionId: FilterValue.optional().describe(
215
+ "The control-plane connection whose calls to count — the `resourceId` its call rows carry. Omit it to count every connection's.",
203
216
  ),
204
217
  since: TimeBound.describe("Inclusive lower bound on when a call landed, ISO-8601. Required."),
205
218
  until: TimeBound.optional().describe("Inclusive upper bound on when a call landed, ISO-8601. Defaults to now."),
@@ -208,7 +221,7 @@ export const ControlPlaneUsageQuery = z
208
221
  message: "`until` must not be before `since`.",
209
222
  path: ["until"],
210
223
  })
211
- .describe("The control-plane usage query: one connection, over a window.");
224
+ .describe("The control-plane usage query: one connection or every connection, over a window.");
212
225
  export type ControlPlaneUsageQuery = z.infer<typeof ControlPlaneUsageQuery>;
213
226
 
214
227
  /**
package/src/http/views.ts CHANGED
@@ -14,6 +14,7 @@ import type {
14
14
  AuditEventDetailView,
15
15
  AuditEventView,
16
16
  AuditSinkView,
17
+ ControlPlaneConnectionUsageView,
17
18
  ControlPlaneReachSubjectView,
18
19
  ControlPlaneReachView,
19
20
  ControlPlaneUsageView,
@@ -212,6 +213,22 @@ export function controlPlaneUsageView(row: ControlPlaneUsageRow): ControlPlaneUs
212
213
  };
213
214
  }
214
215
 
216
+ /**
217
+ * Fold every connection's usage rows into one entry per connection, in the order the aggregate returned them —
218
+ * by connection, then scope, then key — so each connection's rows keep the order a named read gives them.
219
+ */
220
+ export function controlPlaneConnectionUsageViews(
221
+ rows: readonly ControlPlaneUsageRow[],
222
+ ): ControlPlaneConnectionUsageView[] {
223
+ const byConnection = new Map<string, ControlPlaneUsageView[]>();
224
+ for (const row of rows) {
225
+ const usage = byConnection.get(row.connectionId) ?? [];
226
+ usage.push(controlPlaneUsageView(row));
227
+ byConnection.set(row.connectionId, usage);
228
+ }
229
+ return [...byConnection].map(([connectionId, usage]) => ({ connectionId, usage }));
230
+ }
231
+
215
232
  /**
216
233
  * Project the declared sinks, in declaration order, each beside its own state row. A sink with no row has never been
217
234
  * attempted and answers null times, zero counts and `idle`; a row whose sink is no longer declared is not answered.
package/src/query.ts CHANGED
@@ -30,6 +30,8 @@ export interface AuditQuery {
30
30
  actorKind?: ControlPlaneActorKind;
31
31
  /** Match an exact `domain/reason` action code. */
32
32
  action?: string;
33
+ /** Match every action under one domain — `auth` matches `auth/login`, never `authority/granted`. */
34
+ actionPrefix?: string;
33
35
  /** Match the outcome (`success` | `failure` | `denied`). */
34
36
  outcome?: AuditOutcome;
35
37
  /** Match the severity (`info` | `warning` | `critical`). */
@@ -100,6 +102,11 @@ function auditEventQuery(db: AuditDatabase, filter: AuditQuery) {
100
102
  if (filter.actorId !== undefined) query = query.where("actorId", "=", filter.actorId);
101
103
  if (filter.actorKind !== undefined) query = query.where("actorKind", "=", filter.actorKind);
102
104
  if (filter.action !== undefined) query = query.where("action", "=", filter.action);
105
+ // A range rather than `LIKE`, so `pithyAuditEventsActionIdx` serves it: every `domain/…` code sorts at or after
106
+ // `domain/` and before `domain0`, because `0` is the character after `/`.
107
+ if (filter.actionPrefix !== undefined) {
108
+ query = query.where("action", ">=", `${filter.actionPrefix}/`).where("action", "<", `${filter.actionPrefix}0`);
109
+ }
103
110
  if (filter.outcome !== undefined) query = query.where("outcome", "=", filter.outcome);
104
111
  if (filter.severity !== undefined) query = query.where("severity", "=", filter.severity);
105
112
  if (filter.resourceType !== undefined) query = query.where("resourceType", "=", filter.resourceType);
package/src/usage.ts CHANGED
@@ -8,26 +8,32 @@ import { z } from "zod";
8
8
  import type { AuditDatabase } from "./data/tables";
9
9
 
10
10
  /**
11
- * Which scopes a control-plane connection exercised, and which it was refused — `#812`.
11
+ * Which scopes a control-plane connection exercised, and which it was refused — `#812` — for one connection or every
12
+ * connection at once.
12
13
  *
13
14
  * Every admitted call writes `controlplane/call_allowed`, and every verified call refused a scope writes
14
15
  * `controlplane/call_denied`, both against the connection as `resourceId` and both naming the scope and key in
15
16
  * `metadata`. Answering "granted twelve, used three" from the listing would take one forensic read per event, behind
16
17
  * the scope that also discloses the client IP; this reads the same rows in SQL and returns counts.
17
18
  *
19
+ * **One connection, or every one.** Over-grant — scopes a credential holds and never used — is a question over every
20
+ * connection on the Worker, so leaving the connection out counts them all in the same statement, grouped by connection
21
+ * first. A connection that made no call in the window has no row: the caller joins against the connection listing.
22
+ *
18
23
  * **One statement for the aggregate, never a page walk.** A dashboard connection makes thousands of calls a day, and a
19
24
  * 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.
25
+ * `pithyAuditEventsCallIdx` (`audit_0003_call_index`) finds by action, connection and time — or, across every
26
+ * connection, rows `pithyAuditEventsOccurredAtIdx` finds by the window.
21
27
  *
22
28
  * **Nothing personal leaves this function.** It reads the scope, the key id, and the method and path of the last
23
29
  * allowed call out of `metadata`, and no other key, and never the IP or the user-agent. Those four are the management
24
30
  * client's own footprint.
25
31
  */
26
32
 
27
- /** What to count: one connection, over an inclusive window. */
33
+ /** What to count: one connection, or every connection, over an inclusive window. */
28
34
  export interface ControlPlaneUsageFilter {
29
- /** The connection whose calls are counted — the rows' `resourceId`. */
30
- connectionId: string;
35
+ /** The connection whose calls are counted — the rows' `resourceId`. Absent, every connection's calls are. */
36
+ connectionId?: string;
31
37
  /** Inclusive lower bound on `occurredAt`. */
32
38
  since: Date;
33
39
  /** Inclusive upper bound on `occurredAt`. */
@@ -47,6 +53,7 @@ const CONNECTION_RESOURCE = "controlplane_connection";
47
53
  */
48
54
  export const ControlPlaneUsageRow = z
49
55
  .object({
56
+ connectionId: z.string().describe("The connection that made the calls — the rows' `resourceId`."),
50
57
  scope: z
51
58
  .string()
52
59
  .describe(
@@ -75,7 +82,7 @@ const OldestEvent = z
75
82
 
76
83
  /** What {@link controlPlaneUsage} answers. */
77
84
  export interface ControlPlaneUsage {
78
- /** One row per `(scope, keyId)` exercised, ordered by scope then key. */
85
+ /** One row per `(connectionId, scope, keyId)` exercised, ordered by connection, then scope, then key. */
79
86
  usage: ControlPlaneUsageRow[];
80
87
  /** The oldest event the trail holds, or null on an empty trail. */
81
88
  oldestEventAt: Date | null;
@@ -86,13 +93,19 @@ export interface ControlPlaneUsage {
86
93
  *
87
94
  * Three steps, in one statement:
88
95
  *
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
96
+ * 1. **`calls`** — the connection's call rows in the window, or every connection's when none is named, with the
97
+ * connection beside the scope, key, method and path lifted out of `metadata`. The scope is read from where each writer puts it: an allowed row carries the token's `scope`; a gate
91
98
  * refusal names the scope it required as `required`, and a handler's refusal as `scope`, so a denied row reads
92
99
  * `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)`.
100
+ * 2. **`ranked`** — each row's recency within its `(connectionId, scope, keyId, action)`, newest first, `id`
101
+ * breaking a tie. Rank 1 of the allowed rows is the last allowed call, whose method and path the answer carries.
102
+ * 3. **The group** — counts and last instants per `(connectionId, scope, keyId)`.
103
+ *
104
+ * Named, it seeks `pithyAuditEventsCallIdx`: each action, then the connection, then the window as a range. Unnamed,
105
+ * nothing narrows it but the actions and the window, and the window is what is small: an access review reads days of
106
+ * a trail that keeps months. So the planner reads `pithyAuditEventsOccurredAtIdx` over the window and checks the
107
+ * action on each row it finds, and the cost follows the window rather than everything retention holds. A row with no
108
+ * connection — an unverified refusal — is nobody's usage in either.
96
109
  */
97
110
  export function controlPlaneUsageStatement(db: AuditDatabase, filter: ControlPlaneUsageFilter) {
98
111
  const allowed = ControlPlaneAuditActions.callAllowed;
@@ -105,6 +118,7 @@ export function controlPlaneUsageStatement(db: AuditDatabase, filter: ControlPla
105
118
  "id",
106
119
  "action",
107
120
  "occurredAt",
121
+ eb.ref("resourceId").as("connectionId"),
108
122
  sql<string | null>`case when ${eb.ref("action")} = ${denied}
109
123
  then coalesce(json_extract(${eb.ref("metadata")}, '$.required'), json_extract(${eb.ref("metadata")}, '$.scope'))
110
124
  else json_extract(${eb.ref("metadata")}, '$.scope') end`.as("scope"),
@@ -112,9 +126,13 @@ export function controlPlaneUsageStatement(db: AuditDatabase, filter: ControlPla
112
126
  sql<string | null>`json_extract(${eb.ref("metadata")}, '$.method')`.as("method"),
113
127
  sql<string | null>`json_extract(${eb.ref("metadata")}, '$.path')`.as("path"),
114
128
  ])
115
- // In `pithyAuditEventsCallIdx`'s column order: the actions, the connection, then the window.
129
+ // In `pithyAuditEventsCallIdx`'s column order, for the named read: the actions, the connection, the window.
116
130
  .where("action", "in", CALL_ACTIONS)
117
- .where("resourceId", "=", filter.connectionId)
131
+ .where((eb) =>
132
+ filter.connectionId === undefined
133
+ ? eb("resourceId", "is not", null)
134
+ : eb("resourceId", "=", filter.connectionId),
135
+ )
118
136
  .where("occurredAt", ">=", SQLiteDate.encode(filter.since))
119
137
  .where("occurredAt", "<=", SQLiteDate.encode(filter.until))
120
138
  .where("resourceType", "=", CONNECTION_RESOURCE),
@@ -125,13 +143,14 @@ export function controlPlaneUsageStatement(db: AuditDatabase, filter: ControlPla
125
143
  .selectAll()
126
144
  .select(
127
145
  sql<number>`row_number() over (
128
- partition by ${sql.ref("scope")}, ${sql.ref("keyId")}, ${sql.ref("action")}
146
+ partition by ${sql.ref("connectionId")}, ${sql.ref("scope")}, ${sql.ref("keyId")}, ${sql.ref("action")}
129
147
  order by ${sql.ref("occurredAt")} desc, ${sql.ref("id")} desc)`.as("recency"),
130
148
  )
131
149
  .where("scope", "is not", null),
132
150
  )
133
151
  .selectFrom("ranked")
134
152
  .select((eb) => [
153
+ "connectionId",
135
154
  "scope",
136
155
  "keyId",
137
156
  sql<number>`sum(case when ${eb.ref("action")} = ${allowed} then 1 else 0 end)`.as("allowed"),
@@ -147,13 +166,15 @@ export function controlPlaneUsageStatement(db: AuditDatabase, filter: ControlPla
147
166
  "lastDeniedAt",
148
167
  ),
149
168
  ])
150
- .groupBy(["scope", "keyId"])
169
+ .groupBy(["connectionId", "scope", "keyId"])
170
+ .orderBy("connectionId")
151
171
  .orderBy("scope")
152
172
  .orderBy("keyId");
153
173
  }
154
174
 
155
175
  /**
156
- * Count one connection's calls by scope and key, over an inclusive window.
176
+ * Count one connection's calls by scope and key, or every connection's by connection, scope and key, over an
177
+ * inclusive window.
157
178
  *
158
179
  * `oldestEventAt` is the oldest event the trail holds at all, for any connection or none. Retention prunes the trail
159
180
  * by time, never per connection, so this is how far back any connection's answer can reach: a window starting before
@@ -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.8.0";
16
+ export const PACKAGE_VERSION = "0.9.0";