@pithy-sh/audit 0.7.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/README.md +1 -1
  2. package/dist/capability.d.ts +1 -1
  3. package/dist/capability.d.ts.map +1 -1
  4. package/dist/capability.js +4 -3
  5. package/dist/http/guards.d.ts +7 -3
  6. package/dist/http/guards.d.ts.map +1 -1
  7. package/dist/http/guards.js +16 -4
  8. package/dist/http/responses.d.ts +122 -0
  9. package/dist/http/responses.d.ts.map +1 -1
  10. package/dist/http/responses.js +38 -1
  11. package/dist/http/routes.d.ts +8 -3
  12. package/dist/http/routes.d.ts.map +1 -1
  13. package/dist/http/routes.js +48 -16
  14. package/dist/http/schemas.d.ts +7 -5
  15. package/dist/http/schemas.d.ts.map +1 -1
  16. package/dist/http/schemas.js +9 -7
  17. package/dist/http/views.d.ts +20 -5
  18. package/dist/http/views.d.ts.map +1 -1
  19. package/dist/http/views.js +53 -5
  20. package/dist/query.d.ts +2 -0
  21. package/dist/query.d.ts.map +1 -1
  22. package/dist/query.js +1 -0
  23. package/dist/ship/consumer.js +1 -1
  24. package/dist/ship/delivery.d.ts +13 -0
  25. package/dist/ship/delivery.d.ts.map +1 -0
  26. package/dist/ship/delivery.js +21 -0
  27. package/dist/ship/health.d.ts +2 -11
  28. package/dist/ship/health.d.ts.map +1 -1
  29. package/dist/ship/health.js +4 -18
  30. package/dist/usage.d.ts +29 -12
  31. package/dist/usage.d.ts.map +1 -1
  32. package/dist/usage.js +23 -9
  33. package/dist/version.generated.d.ts +1 -1
  34. package/dist/version.generated.js +1 -1
  35. package/package.json +3 -3
  36. package/src/capability.ts +19 -20
  37. package/src/http/guards.ts +17 -4
  38. package/src/http/responses.ts +109 -0
  39. package/src/http/routes.ts +74 -20
  40. package/src/http/schemas.ts +21 -8
  41. package/src/http/views.ts +58 -5
  42. package/src/query.ts +7 -0
  43. package/src/ship/delivery.ts +23 -0
  44. package/src/ship/health.ts +3 -21
  45. package/src/usage.ts +37 -16
  46. package/src/version.generated.ts +1 -1
package/src/http/views.ts CHANGED
@@ -4,12 +4,17 @@
4
4
  import { InternalError } from "@pithy-sh/core/src/error/pithyError";
5
5
  import type { AccessHistoryRow } from "../accessHistory";
6
6
  import type { AuditEventRow } from "../data/auditEvent";
7
+ import type { AuditSinkStateRow } from "../data/sinkState";
7
8
  import type { ControlPlaneReachRow, ControlPlaneReachSubjectRow } from "../reach";
9
+ import { shipDelivery } from "../ship/delivery";
10
+ import type { AuditSinks } from "../ship/sinks";
8
11
  import type { ControlPlaneUsageRow } from "../usage";
9
12
  import type {
10
13
  AccessChangeView,
11
14
  AuditEventDetailView,
12
15
  AuditEventView,
16
+ AuditSinkView,
17
+ ControlPlaneConnectionUsageView,
13
18
  ControlPlaneReachSubjectView,
14
19
  ControlPlaneReachView,
15
20
  ControlPlaneUsageView,
@@ -89,7 +94,7 @@ export function auditEventView(row: AuditEventRow): AuditEventView {
89
94
  // not personal data — and a client that can filter by tenant but cannot see which tenant a row
90
95
  // carries has to take the filter on trust, which is how a row ends up drawn under the wrong heading.
91
96
  tenant: row.tenant,
92
- // Its position in its tenant's chain, or null: written before the chain began (#822). The mark, on the listing.
97
+ // Its position in its tenant's chain, or null: written before the chain began. The mark, on the listing.
93
98
  chainSeq: row.chainSeq,
94
99
  };
95
100
  }
@@ -100,7 +105,7 @@ export function auditEventDetailView(row: AuditEventRow): AuditEventDetailView {
100
105
  }
101
106
 
102
107
  /**
103
- * Project one access change (#831) into the wire union, by what changed.
108
+ * Project one access change into the wire union, by what changed.
104
109
  *
105
110
  * The statement already read nothing but the named metadata keys, so this drops nothing personal; what it does is
106
111
  * keep each subject's fields to that subject, so a member change never carries a null `scopesBefore` a client could
@@ -152,7 +157,7 @@ export function accessChangeView(row: AccessHistoryRow): AccessChangeView {
152
157
  }
153
158
 
154
159
  /**
155
- * Project one reach row (#828). Field for field, with the instants as ISO-8601: the statement already read nothing
160
+ * Project one reach row. Field for field, with the instants as ISO-8601: the statement already read nothing
156
161
  * but the scope, the key, the method and the path out of `metadata`, and the tenant out of the handler's events, so
157
162
  * there is nothing here to drop.
158
163
  */
@@ -172,7 +177,7 @@ export function controlPlaneReachView(row: ControlPlaneReachRow): ControlPlaneRe
172
177
  };
173
178
  }
174
179
 
175
- /** Project one subject row (#828), field for field, the same way — never a spread a new field would ride out on. */
180
+ /** Project one subject row, field for field, the same way — never a spread a new field would ride out on. */
176
181
  export function controlPlaneReachSubjectView(row: ControlPlaneReachSubjectRow): ControlPlaneReachSubjectView {
177
182
  return {
178
183
  tenant: row.tenant,
@@ -192,7 +197,7 @@ export function controlPlaneReachSubjectView(row: ControlPlaneReachSubjectRow):
192
197
  }
193
198
 
194
199
  /**
195
- * Project one usage row (#812). Field for field, with the instants as ISO-8601: the aggregate already read nothing but
200
+ * Project one usage row. Field for field, with the instants as ISO-8601: the aggregate already read nothing but
196
201
  * the scope, the key, and the last allowed call's method and path out of `metadata`, so there is nothing here to drop.
197
202
  */
198
203
  export function controlPlaneUsageView(row: ControlPlaneUsageRow): ControlPlaneUsageView {
@@ -207,3 +212,51 @@ export function controlPlaneUsageView(row: ControlPlaneUsageRow): ControlPlaneUs
207
212
  lastDeniedAt: row.lastDeniedAt?.toISOString() ?? null,
208
213
  };
209
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
+
232
+ /**
233
+ * Project the declared sinks, in declaration order, each beside its own state row. A sink with no row has never been
234
+ * attempted and answers null times, zero counts and `idle`; a row whose sink is no longer declared is not answered.
235
+ *
236
+ * Named fields, never a spread of the config: a sink's URL path and query may carry a key, and its secret name says
237
+ * where its token lives, so neither leaves. The host is the URL's host and port, as `pithy doctor` prints it.
238
+ */
239
+ export function auditSinkViews(sinks: AuditSinks, states: readonly AuditSinkStateRow[]): AuditSinkView[] {
240
+ const byName = new Map(states.map((state) => [state.sink, state]));
241
+ return Object.entries(sinks).map(([name, sink]) => {
242
+ const state = byName.get(name) ?? {
243
+ sink: name,
244
+ lastDeliveredAt: null,
245
+ lastFailedAt: null,
246
+ retrying: 0,
247
+ deadLettered: 0,
248
+ };
249
+ return {
250
+ name,
251
+ profile: sink.profile,
252
+ host: new URL(sink.url).host,
253
+ detail: sink.detail,
254
+ actions: sink.actions === undefined ? null : [...sink.actions],
255
+ lastDeliveredAt: state.lastDeliveredAt?.toISOString() ?? null,
256
+ lastFailedAt: state.lastFailedAt?.toISOString() ?? null,
257
+ retrying: state.retrying,
258
+ deadLettered: state.deadLettered,
259
+ delivery: shipDelivery([state]),
260
+ };
261
+ });
262
+ }
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);
@@ -0,0 +1,23 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+
4
+ import type { AuditSinkStateRow } from "../data/sinkState";
5
+
6
+ /**
7
+ * The values a delivery state takes: per sink on the sinks read, and across every sink on the manifest's
8
+ * `auditShipDelivery`. `failing` when any sink's last attempt failed; `delivering` when every sink that has been
9
+ * attempted last took a delivery; `idle` when no sink has been attempted yet.
10
+ */
11
+ export const SHIP_DELIVERY_STATES = ["delivering", "failing", "idle"] as const;
12
+ export type ShipDeliveryState = (typeof SHIP_DELIVERY_STATES)[number];
13
+
14
+ /** How delivery stands, from the given sinks' rows: one sink's for its own state, every declared sink's for the total. */
15
+ export function shipDelivery(states: readonly AuditSinkStateRow[]): ShipDeliveryState {
16
+ const attempted = states.filter((state) => state.lastDeliveredAt !== null || state.lastFailedAt !== null);
17
+ if (attempted.length === 0) return "idle";
18
+ const failing = attempted.some(
19
+ (state) =>
20
+ state.lastFailedAt !== null && (state.lastDeliveredAt === null || state.lastFailedAt > state.lastDeliveredAt),
21
+ );
22
+ return failing ? "failing" : "delivering";
23
+ }
@@ -4,14 +4,14 @@
4
4
  import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
5
5
  import { type CapabilityHealth, defineCapabilityHealth } from "@pithy-sh/core/src/controlPlane/discovery/health";
6
6
  import type { Context } from "hono";
7
- import type { AuditSinkStateRow } from "../data/sinkState";
8
7
  import type { AuditDatabase } from "../data/tables";
9
8
  import { AUDIT_TRAIL_READ_SCOPE } from "../http/guards";
9
+ import { SHIP_DELIVERY_STATES, shipDelivery } from "./delivery";
10
10
  import type { AuditSinks } from "./sinks";
11
11
  import { readSinkStates } from "./state";
12
12
 
13
13
  /**
14
- * **Shipping's health, on audit's manifest entry (#824)** — whether the trail is reaching its sinks.
14
+ * **Shipping's health, on audit's manifest entry** — whether the trail is reaching its sinks.
15
15
  *
16
16
  * Three keys, all behind `audit:events:read`, the scope the listing already requires: a backlog, a dead-letter
17
17
  * count, and a state. Each is read off `pithy_audit_sinks` by primary key, one row per declared sink, so the bound
@@ -25,27 +25,9 @@ export const AUDIT_SHIP_BACKLOG = "auditShipBacklog";
25
25
  /** Events given up on, across every sink: their last retry failed and they went to the dead-letter queue. */
26
26
  export const AUDIT_SHIP_DEAD_LETTERED = "auditShipDeadLettered";
27
27
 
28
- /** How delivery stands, across every sink. */
28
+ /** How delivery stands, across every sink: {@link shipDelivery} over every declared sink's row. */
29
29
  export const AUDIT_SHIP_DELIVERY = "auditShipDelivery";
30
30
 
31
- /**
32
- * The values {@link AUDIT_SHIP_DELIVERY} takes. `failing` when any sink's last attempt failed; `delivering` when
33
- * every sink that has been attempted last took a delivery; `idle` when no sink has been attempted yet.
34
- */
35
- export const SHIP_DELIVERY_STATES = ["delivering", "failing", "idle"] as const;
36
- export type ShipDeliveryState = (typeof SHIP_DELIVERY_STATES)[number];
37
-
38
- /** How delivery stands, from the declared sinks' rows. */
39
- export function shipDelivery(states: readonly AuditSinkStateRow[]): ShipDeliveryState {
40
- const attempted = states.filter((state) => state.lastDeliveredAt !== null || state.lastFailedAt !== null);
41
- if (attempted.length === 0) return "idle";
42
- const failing = attempted.some(
43
- (state) =>
44
- state.lastFailedAt !== null && (state.lastDeliveredAt === null || state.lastFailedAt > state.lastDeliveredAt),
45
- );
46
- return failing ? "failing" : "delivering";
47
- }
48
-
49
31
  /** Declare shipping's health keys over the declared sinks. */
50
32
  export function shipHealth(sinks: AuditSinks, database: (c: Context<PithyHonoEnv>) => AuditDatabase): CapabilityHealth {
51
33
  const names = Object.keys(sinks);
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.7.1";
16
+ export const PACKAGE_VERSION = "0.9.0";