@pithy-sh/audit 0.2.7 → 0.4.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/dist/capability.d.ts.map +1 -1
  2. package/dist/capability.js +5 -1
  3. package/dist/cli/resolveActor.d.ts +12 -2
  4. package/dist/cli/resolveActor.d.ts.map +1 -1
  5. package/dist/cli/resolveActor.js +14 -3
  6. package/dist/data/auditEvent.d.ts +5 -0
  7. package/dist/data/auditEvent.d.ts.map +1 -1
  8. package/dist/data/auditEvent.js +2 -0
  9. package/dist/data/tables.d.ts +5 -0
  10. package/dist/data/tables.d.ts.map +1 -1
  11. package/dist/http/responses.d.ts +20 -0
  12. package/dist/http/responses.d.ts.map +1 -1
  13. package/dist/http/responses.js +2 -0
  14. package/dist/http/routes.d.ts +1 -1
  15. package/dist/http/routes.d.ts.map +1 -1
  16. package/dist/http/routes.js +15 -4
  17. package/dist/http/schemas.d.ts +5 -0
  18. package/dist/http/schemas.d.ts.map +1 -1
  19. package/dist/http/schemas.js +2 -0
  20. package/dist/http/views.d.ts.map +1 -1
  21. package/dist/http/views.js +1 -0
  22. package/dist/migrations/0002_actor_kind.d.ts +19 -0
  23. package/dist/migrations/0002_actor_kind.d.ts.map +1 -0
  24. package/dist/migrations/0002_actor_kind.js +27 -0
  25. package/dist/query.d.ts +3 -0
  26. package/dist/query.d.ts.map +1 -1
  27. package/dist/query.js +1 -0
  28. package/dist/recorder.d.ts.map +1 -1
  29. package/dist/recorder.js +1 -0
  30. package/dist/seeds/example.d.ts.map +1 -1
  31. package/dist/seeds/example.js +6 -0
  32. package/dist/version.generated.d.ts +1 -1
  33. package/dist/version.generated.js +1 -1
  34. package/package.json +5 -5
  35. package/src/capability.ts +2 -1
  36. package/src/cli/resolveActor.ts +32 -3
  37. package/src/data/auditEvent.ts +6 -0
  38. package/src/http/responses.ts +7 -0
  39. package/src/http/routes.ts +18 -6
  40. package/src/http/schemas.ts +4 -0
  41. package/src/http/views.ts +3 -0
  42. package/src/migrations/0002_actor_kind.ts +31 -0
  43. package/src/query.ts +4 -0
  44. package/src/recorder.ts +4 -0
  45. package/src/seeds/example.ts +6 -0
  46. package/src/version.generated.ts +1 -1
@@ -1 +1 @@
1
- {"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,0CAA0C,CAAC;AAE7F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAWzC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW;;;iBAc8B,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AACvD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,MAAM,GAAE,gBAAqB,GAAG,eAAe,CA4DpE;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,eAAe,CAEvF"}
1
+ {"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,0CAA0C,CAAC;AAE7F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAWzC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW;;;iBAc8B,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AACvD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,MAAM,GAAE,gBAAqB,GAAG,eAAe,CA4DpE;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,eAAe,CAEvF"}
@@ -4,6 +4,7 @@ import { auditTables } from "./data/tables.js";
4
4
  import { auditAdminRoutes } from "./http/guards.js";
5
5
  import { registerAuditRoutes } from "./http/routes.js";
6
6
  import { audit_0001_init } from "./migrations/0001_init.js";
7
+ import { audit_0002_actor_kind } from "./migrations/0002_actor_kind.js";
7
8
  import { recordAuditEvent } from "./recorder.js";
8
9
  import { auditExampleSeed } from "./seeds/example.js";
9
10
  import { PACKAGE_NAME, PACKAGE_VERSION } from "./version.generated.js";
@@ -61,7 +62,10 @@ function audit(config = {}) {
61
62
  binding: resolved.database,
62
63
  tables: auditTables,
63
64
  migrationOrder: 250,
64
- migrations: { "0001_init": audit_0001_init }
65
+ migrations: {
66
+ "0001_init": audit_0001_init,
67
+ "0002_actor_kind": audit_0002_actor_kind
68
+ }
65
69
  } },
66
70
  seeds: [auditExampleSeed],
67
71
  adminRoutes: auditAdminRoutes(resolved.basePath),
@@ -36,6 +36,16 @@ export interface CfActorSource {
36
36
  /** Account-scoped reads, for a `cfat_*` token. */
37
37
  accountTokens: CfAccountTokenActorSource;
38
38
  }
39
+ /**
40
+ * What the caller knows about the credential that the token's spelling cannot say.
41
+ *
42
+ * `kind: "session"` is a signed-in Cloudflare session (#759): an OAuth access token, opaque, carrying
43
+ * neither `cfut_` nor `cfat_`. The caller resolved the credential and knows; inferring it from the
44
+ * spelling would make a prefix change at Cloudflare a silent change of actor.
45
+ */
46
+ export interface ResolveActorOptions {
47
+ kind?: "session";
48
+ }
39
49
  /** A resolved CLI actor: who to attribute a control-plane audit event to, plus correlation metadata. */
40
50
  export interface ResolvedActor {
41
51
  /** The kind of principal. */
@@ -66,11 +76,11 @@ export interface ResolvedActor {
66
76
  * Resolution failure — a bad token, a network error, an unrecognized prefix — is **never fatal**: it
67
77
  * returns a `system` actor with a `metadata` note, so the event is still written, just unattributed.
68
78
  */
69
- export declare function resolveActor(apiToken: string, source: CfActorSource): Promise<ResolvedActor>;
79
+ export declare function resolveActor(apiToken: string, source: CfActorSource, options?: ResolveActorOptions): Promise<ResolvedActor>;
70
80
  /**
71
81
  * A resolver that runs {@link resolveActor} **once** and caches the result for the lifetime of a CLI
72
82
  * command — actor identity is resolved at session start, not per event. Memoizes the in-flight
73
83
  * promise so concurrent emits share the single resolution.
74
84
  */
75
- export declare function createCachedActorResolver(apiToken: string, source: CfActorSource): () => Promise<ResolvedActor>;
85
+ export declare function createCachedActorResolver(apiToken: string, source: CfActorSource, options?: ResolveActorOptions): () => Promise<ResolvedActor>;
76
86
  //# sourceMappingURL=resolveActor.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"resolveActor.d.ts","sourceRoot":"","sources":["../../src/cli/resolveActor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAGzF,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,OAAO,IAAI,OAAO,CAAC;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,8GAA8G;AAC9G,MAAM,WAAW,yBAAyB;IACxC,oHAAoH;IACpH,WAAW,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,4GAA4G;IAC5G,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACvD;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,IAAI,EAAE,iBAAiB,CAAC;IACxB,kDAAkD;IAClD,aAAa,EAAE,yBAAyB,CAAC;CAC1C;AAED,wGAAwG;AACxG,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,SAAS,EAAE,cAAc,CAAC;IAC1B,gFAAgF;IAChF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iFAAiF;IACjF,QAAQ,EAAE,aAAa,CAAC;CACzB;AAOD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAsClG;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,CAM/G"}
1
+ {"version":3,"file":"resolveActor.d.ts","sourceRoot":"","sources":["../../src/cli/resolveActor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAGzF,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,OAAO,IAAI,OAAO,CAAC;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,8GAA8G;AAC9G,MAAM,WAAW,yBAAyB;IACxC,oHAAoH;IACpH,WAAW,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,4GAA4G;IAC5G,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACvD;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,IAAI,EAAE,iBAAiB,CAAC;IACxB,kDAAkD;IAClD,aAAa,EAAE,yBAAyB,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED,wGAAwG;AACxG,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,SAAS,EAAE,cAAc,CAAC;IAC1B,gFAAgF;IAChF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iFAAiF;IACjF,QAAQ,EAAE,aAAa,CAAC;CACzB;AAOD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,aAAa,CAAC,CAgDxB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,mBAAwB,GAChC,MAAM,OAAO,CAAC,aAAa,CAAC,CAM9B"}
@@ -34,8 +34,19 @@ function systemActor(note) {
34
34
  * Resolution failure — a bad token, a network error, an unrecognized prefix — is **never fatal**: it
35
35
  * returns a `system` actor with a `metadata` note, so the event is still written, just unattributed.
36
36
  */
37
- async function resolveActor(apiToken, source) {
37
+ async function resolveActor(apiToken, source, options = {}) {
38
38
  try {
39
+ if (options.kind === "session") {
40
+ const user = await source.user.getUser();
41
+ return {
42
+ actorType: "user",
43
+ actorId: user.email ?? user.id ?? null,
44
+ metadata: {
45
+ cfTokenType: "session",
46
+ cfUserId: user.id ?? null
47
+ }
48
+ };
49
+ }
39
50
  if (apiToken.startsWith("cfut_")) {
40
51
  const user = await source.user.getUser();
41
52
  return {
@@ -74,10 +85,10 @@ async function resolveActor(apiToken, source) {
74
85
  * command — actor identity is resolved at session start, not per event. Memoizes the in-flight
75
86
  * promise so concurrent emits share the single resolution.
76
87
  */
77
- function createCachedActorResolver(apiToken, source) {
88
+ function createCachedActorResolver(apiToken, source, options = {}) {
78
89
  let cached;
79
90
  return () => {
80
- cached ??= resolveActor(apiToken, source);
91
+ cached ??= resolveActor(apiToken, source, options);
81
92
  return cached;
82
93
  };
83
94
  }
@@ -42,6 +42,11 @@ export declare const AuditEventRow: z.ZodObject<{
42
42
  user: "user";
43
43
  }>;
44
44
  actorId: z.ZodNullable<z.ZodString>;
45
+ actorKind: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
46
+ agent: "agent";
47
+ dashboard: "dashboard";
48
+ script: "script";
49
+ }>>>;
45
50
  sessionId: z.ZodNullable<z.ZodString>;
46
51
  resourceType: z.ZodNullable<z.ZodString>;
47
52
  resourceId: z.ZodNullable<z.ZodString>;
@@ -1 +1 @@
1
- {"version":3,"file":"auditEvent.d.ts","sourceRoot":"","sources":["../../src/data/auditEvent.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;GAWG;AACH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,gIAA4B,CAAC;AAE7D,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkF2F,CAAC;AACtH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC"}
1
+ {"version":3,"file":"auditEvent.d.ts","sourceRoot":"","sources":["../../src/data/auditEvent.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;GAWG;AACH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,gIAA4B,CAAC;AAE7D,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuF2F,CAAC;AACtH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC"}
@@ -2,6 +2,7 @@
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
3
  import { AuditAction, AuditActorType, AuditMetadata, AuditOutcome, AuditSeverity } from "@pithy-sh/core/src/audit/auditEvent";
4
4
  import { z } from "zod";
5
+ import { ControlPlaneActorKind } from "@pithy-sh/core/src/controlPlane/data/connection";
5
6
  import { SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
6
7
  //#region src/data/auditEvent.ts
7
8
  /**
@@ -31,6 +32,7 @@ const AuditEventRow = z.object({
31
32
  severity: AuditSeverity.describe("How serious the event is, orthogonal to outcome; drives dashboard filtering and alerting."),
32
33
  actorType: AuditActorType.describe("The kind of principal that acted."),
33
34
  actorId: z.string().nullable().describe("The acting principal's stable id (user id, service/token name); null for `system`/`anonymous`. Indexed."),
35
+ actorKind: ControlPlaneActorKind.nullable().default(null).describe("For a `control-plane` actor, what kind of management client acted: `agent`, `dashboard` or `script`, from the connection it called through (#721). Null for every other actor, for a connection registered before the kind was recorded, and on rows written before this column existed (`audit_0002_actor_kind`)."),
34
36
  sessionId: z.string().nullable().describe("The session this action belongs to, tying a chain of actions together; null when none."),
35
37
  resourceType: z.string().nullable().describe("The type of resource the action targeted (e.g. `user`, `secret`); null when not resource-scoped."),
36
38
  resourceId: z.string().nullable().describe("The id of the resource the action targeted; null when not resource-scoped."),
@@ -32,6 +32,11 @@ export declare const auditTables: {
32
32
  user: "user";
33
33
  }>;
34
34
  actorId: import("zod").ZodNullable<import("zod").ZodString>;
35
+ actorKind: import("zod").ZodDefault<import("zod").ZodNullable<import("zod").ZodEnum<{
36
+ agent: "agent";
37
+ dashboard: "dashboard";
38
+ script: "script";
39
+ }>>>;
35
40
  sessionId: import("zod").ZodNullable<import("zod").ZodString>;
36
41
  resourceType: import("zod").ZodNullable<import("zod").ZodString>;
37
42
  resourceId: import("zod").ZodNullable<import("zod").ZodString>;
@@ -1 +1 @@
1
- {"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../src/data/tables.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGrC;;;;GAIG;AACH,eAAO,MAAM,WAAW;IACtB,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CACjB,CAAC;AACF,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC;AAE7C,mGAAmG;AACnG,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC;AAEhE,qGAAqG;AACrG,wBAAgB,aAAa,CAAC,EAAE,EAAE,UAAU,GAAG,aAAa,CAE3D"}
1
+ {"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../src/data/tables.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGrC;;;;GAIG;AACH,eAAO,MAAM,WAAW;IACtB,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CACjB,CAAC;AACF,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC;AAE7C,mGAAmG;AACnG,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC;AAEhE,qGAAqG;AACrG,wBAAgB,aAAa,CAAC,EAAE,EAAE,UAAU,GAAG,aAAa,CAE3D"}
@@ -29,6 +29,11 @@ export declare const AuditEventView: z.ZodObject<{
29
29
  user: "user";
30
30
  }>;
31
31
  actorId: z.ZodNullable<z.ZodString>;
32
+ actorKind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
33
+ agent: "agent";
34
+ dashboard: "dashboard";
35
+ script: "script";
36
+ }>>>;
32
37
  sessionId: z.ZodNullable<z.ZodString>;
33
38
  resourceType: z.ZodNullable<z.ZodString>;
34
39
  resourceId: z.ZodNullable<z.ZodString>;
@@ -67,6 +72,11 @@ export declare const AuditEventDetailView: z.ZodObject<{
67
72
  user: "user";
68
73
  }>;
69
74
  actorId: z.ZodNullable<z.ZodString>;
75
+ actorKind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
76
+ agent: "agent";
77
+ dashboard: "dashboard";
78
+ script: "script";
79
+ }>>>;
70
80
  sessionId: z.ZodNullable<z.ZodString>;
71
81
  resourceType: z.ZodNullable<z.ZodString>;
72
82
  resourceId: z.ZodNullable<z.ZodString>;
@@ -105,6 +115,11 @@ export declare const AuditEventsResponse: z.ZodObject<{
105
115
  user: "user";
106
116
  }>;
107
117
  actorId: z.ZodNullable<z.ZodString>;
118
+ actorKind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
119
+ agent: "agent";
120
+ dashboard: "dashboard";
121
+ script: "script";
122
+ }>>>;
108
123
  sessionId: z.ZodNullable<z.ZodString>;
109
124
  resourceType: z.ZodNullable<z.ZodString>;
110
125
  resourceId: z.ZodNullable<z.ZodString>;
@@ -142,6 +157,11 @@ export declare const AuditEventResponse: z.ZodObject<{
142
157
  user: "user";
143
158
  }>;
144
159
  actorId: z.ZodNullable<z.ZodString>;
160
+ actorKind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
161
+ agent: "agent";
162
+ dashboard: "dashboard";
163
+ script: "script";
164
+ }>>>;
145
165
  sessionId: z.ZodNullable<z.ZodString>;
146
166
  resourceType: z.ZodNullable<z.ZodString>;
147
167
  resourceId: z.ZodNullable<z.ZodString>;
@@ -1 +1 @@
1
- {"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/http/responses.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgCxB;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsB0E,CAAC;AACtG,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAY0E,CAAC;AAC5G,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAEzE,2BAA2B;AAC3B,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAK6B,CAAC;AAC9D,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,oCAAoC;AACpC,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAEQ,CAAC;AACxC,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC"}
1
+ {"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/http/responses.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgCxB;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4B0E,CAAC;AACtG,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAY0E,CAAC;AAC5G,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAEzE,2BAA2B;AAC3B,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAK6B,CAAC;AAC9D,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,oCAAoC;AACpC,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAEQ,CAAC;AACxC,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC"}
@@ -2,6 +2,7 @@
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
3
  import { AuditActorType, AuditMetadata, AuditOutcome, AuditSeverity } from "@pithy-sh/core/src/audit/auditEvent";
4
4
  import { z } from "zod";
5
+ import { ControlPlaneActorKind } from "@pithy-sh/core/src/controlPlane/data/connection";
5
6
  //#region src/http/responses.ts
6
7
  /**
7
8
  * What the audit routes return, as Zod objects a management client can validate against.
@@ -42,6 +43,7 @@ const AuditEventView = z.object({
42
43
  severity: AuditSeverity.describe("How serious it is, orthogonal to the outcome."),
43
44
  actorType: AuditActorType.describe("The kind of principal that acted."),
44
45
  actorId: z.string().nullable().describe("The acting principal's stable id, or null."),
46
+ actorKind: ControlPlaneActorKind.nullable().optional().describe("For a `control-plane` actor, which kind of management client acted — `agent`, `dashboard` or `script` — or null. Absent from a Worker older than the field."),
45
47
  sessionId: z.string().nullable().describe("The session the action belongs to — a row id, never a token — or null."),
46
48
  resourceType: z.string().nullable().describe("The kind of thing acted on, or null."),
47
49
  resourceId: z.string().nullable().describe("The thing acted on, or null."),
@@ -29,7 +29,7 @@ import type { AuditDatabase } from "../data/tables";
29
29
  * What every route this capability mounts declares: its path, its strategy, and the scope it checks.
30
30
  *
31
31
  * Exported so a test asserts against the declaration rather than against a middleware count. Counting
32
- * `app.routes` entries proves that *something* runs before the handler — a bare `zValidator` satisfies
32
+ * `app.routes` entries proves that *something* runs before the handler — a bare `validate` satisfies
33
33
  * it — and cannot prove *what*. This is a declaration, so it can drift from the router;
34
34
  * `routeContract.test.ts` checks it against Hono in both directions, so a route added without an entry
35
35
  * and an entry naming no route both fail.
@@ -1 +1 @@
1
- {"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAG7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAGrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAOpD;;;;;;;;;;;;;;;;;;;GAmBG;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,EAGxD,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;CACvD;AA2CD,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,kBAAkB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAqFlG"}
1
+ {"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAG7E,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;AAE1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAOpD;;;;;;;;;;;;;;;;;;;GAmBG;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,EAGxD,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;CACvD;AA2CD,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,kBAAkB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAiGlG"}
@@ -3,12 +3,13 @@
3
3
  import { AuditTrailActions } from "../actions.js";
4
4
  import { AUDIT_EVENT_DETAIL_READ_SCOPE, AUDIT_TRAIL_READ_SCOPE } from "./guards.js";
5
5
  import { pageAuditEvents, readAuditEvent } from "../query.js";
6
+ import { AuditEventResponse, AuditEventsResponse } from "./responses.js";
6
7
  import { AuditEventIdParam, ListAuditEventsQuery } from "./schemas.js";
7
8
  import { auditEventDetailView, auditEventView } from "./views.js";
8
9
  import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
9
- import { zValidator } from "@hono/zod-validator";
10
10
  import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
11
- import { validationHook } from "@pithy-sh/core/src/http/validation";
11
+ import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
12
+ import { validate } from "@pithy-sh/core/src/http/validation";
12
13
  //#region src/http/routes.ts
13
14
  /** Every route, and how it is gated. */
14
15
  const AUDIT_ROUTES = [{
@@ -67,7 +68,12 @@ function registerAuditRoutes(options) {
67
68
  * CONTROL-PLANE READ. A filtered, resumable page of the trail — keyset, never offset, because the
68
69
  * table is appended to while it is being read and an offset page silently skips records.
69
70
  */
70
- app.get(`${base}/events`, requireControlPlane(AUDIT_TRAIL_READ_SCOPE), zValidator("query", ListAuditEventsQuery, validationHook), async (c) => {
71
+ app.get(`${base}/events`, describeRoute({
72
+ summary: "Page through the audit trail, newest first.",
73
+ verification: "control-plane",
74
+ scopes: [AUDIT_TRAIL_READ_SCOPE],
75
+ responses: { 200: AuditEventsResponse }
76
+ }), requireControlPlane(AUDIT_TRAIL_READ_SCOPE), validate("query", ListAuditEventsQuery), async (c) => {
71
77
  const operator = caller(c);
72
78
  const query = c.req.valid("query");
73
79
  const page = await pageAuditEvents(database(c), query);
@@ -96,7 +102,12 @@ function registerAuditRoutes(options) {
96
102
  * CONTROL-PLANE READ, the forensic one. Returns the client IP, the user-agent, and the capability's
97
103
  * metadata bag, which is why it sits behind its own scope rather than the listing's.
98
104
  */
99
- app.get(`${base}/events/:eventId`, requireControlPlane(AUDIT_EVENT_DETAIL_READ_SCOPE), zValidator("param", AuditEventIdParam, validationHook), async (c) => {
105
+ app.get(`${base}/events/:eventId`, describeRoute({
106
+ summary: "Read one audit event in full, with its IP, user-agent and metadata.",
107
+ verification: "control-plane",
108
+ scopes: [AUDIT_EVENT_DETAIL_READ_SCOPE],
109
+ responses: { 200: AuditEventResponse }
110
+ }), requireControlPlane(AUDIT_EVENT_DETAIL_READ_SCOPE), validate("param", AuditEventIdParam), async (c) => {
100
111
  const operator = caller(c);
101
112
  const { eventId } = c.req.valid("param");
102
113
  const row = await readAuditEvent(database(c), eventId);
@@ -21,6 +21,11 @@ export declare const ListAuditEventsQuery: z.ZodObject<{
21
21
  user: "user";
22
22
  }>>;
23
23
  actorId: z.ZodOptional<z.ZodString>;
24
+ actorKind: z.ZodOptional<z.ZodEnum<{
25
+ agent: "agent";
26
+ dashboard: "dashboard";
27
+ script: "script";
28
+ }>>;
24
29
  action: z.ZodOptional<z.ZodString>;
25
30
  outcome: z.ZodOptional<z.ZodEnum<{
26
31
  denied: "denied";
@@ -1 +1 @@
1
- {"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"AAKA,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsCiE,CAAC;AACnG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyCiE,CAAC;AACnG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}
@@ -2,6 +2,7 @@
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
3
  import { AuditAction, AuditActorType, AuditOutcome, AuditSeverity } from "@pithy-sh/core/src/audit/auditEvent";
4
4
  import { z } from "zod";
5
+ import { ControlPlaneActorKind } from "@pithy-sh/core/src/controlPlane/data/connection";
5
6
  import { MAX_PAGE_SIZE } from "@pithy-sh/core/src/data/cursor";
6
7
  //#region src/http/schemas.ts
7
8
  /**
@@ -52,6 +53,7 @@ const AuditEventIdParam = z.object({ eventId: z.string().uuid().describe("The ev
52
53
  const ListAuditEventsQuery = z.object({
53
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'."),
54
55
  actorId: FilterValue.optional().describe("Filter to one principal — a user id, a service name, a token subject."),
56
+ actorKind: ControlPlaneActorKind.optional().describe("Filter to one kind of management client: `agent`, `dashboard` or `script`. What `actorType=control-plane` cannot say on its own."),
55
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."),
56
58
  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."),
57
59
  severity: AuditSeverity.optional().describe("Filter to one severity."),
@@ -1 +1 @@
1
- {"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../../src/http/views.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,cAAc,CAwBjE;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,GAAG,oBAAoB,CAE7E"}
1
+ {"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../../src/http/views.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,cAAc,CA2BjE;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,GAAG,oBAAoB,CAE7E"}
@@ -57,6 +57,7 @@ function auditEventView(row) {
57
57
  severity: row.severity,
58
58
  actorType: row.actorType,
59
59
  actorId: row.actorId,
60
+ actorKind: row.actorKind,
60
61
  sessionId: row.sessionId,
61
62
  resourceType: row.resourceType,
62
63
  resourceId: row.resourceId,
@@ -0,0 +1,19 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ import type { Migration } from "kysely/migration";
4
+ /**
5
+ * What kind of management client acted — `#721`.
6
+ *
7
+ * `actorType: "control-plane"` names an agent, the dashboard and a script identically, and those are the
8
+ * questions asked after an incident. The kind is recorded on the connection when it is registered and
9
+ * stamped onto every control-plane row by `requireControlPlane`; this is the column it lands in.
10
+ *
11
+ * **Appended, never folded into `0001`.** The audit capability has shipped, so its table is history.
12
+ *
13
+ * **Nullable, with no default and no backfill.** Every row before this one, and every row whose actor is
14
+ * not a management client, has no kind — and a row recorded under a connection registered before kinds
15
+ * were recorded has none either. Null says exactly that. No index: the trail is read by time and actor
16
+ * first, and a kind narrows a page that `actorType` has already narrowed.
17
+ */
18
+ export declare const audit_0002_actor_kind: Migration;
19
+ //# sourceMappingURL=0002_actor_kind.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"0002_actor_kind.d.ts","sourceRoot":"","sources":["../../src/migrations/0002_actor_kind.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAUnC,CAAC"}
@@ -0,0 +1,27 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+ //#region src/migrations/0002_actor_kind.ts
4
+ /**
5
+ * What kind of management client acted — `#721`.
6
+ *
7
+ * `actorType: "control-plane"` names an agent, the dashboard and a script identically, and those are the
8
+ * questions asked after an incident. The kind is recorded on the connection when it is registered and
9
+ * stamped onto every control-plane row by `requireControlPlane`; this is the column it lands in.
10
+ *
11
+ * **Appended, never folded into `0001`.** The audit capability has shipped, so its table is history.
12
+ *
13
+ * **Nullable, with no default and no backfill.** Every row before this one, and every row whose actor is
14
+ * not a management client, has no kind — and a row recorded under a connection registered before kinds
15
+ * were recorded has none either. Null says exactly that. No index: the trail is read by time and actor
16
+ * first, and a kind narrows a page that `actorType` has already narrowed.
17
+ */
18
+ const audit_0002_actor_kind = {
19
+ up: async (db) => {
20
+ await db.schema.alterTable("pithyAuditEvents").addColumn("actorKind", "text").execute();
21
+ },
22
+ down: async (db) => {
23
+ await db.schema.alterTable("pithyAuditEvents").dropColumn("actorKind").execute();
24
+ }
25
+ };
26
+ //#endregion
27
+ export { audit_0002_actor_kind };
package/dist/query.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
3
  import type { AuditActorType, AuditOutcome, AuditSeverity } from "@pithy-sh/core/src/audit/auditEvent";
4
+ import type { ControlPlaneActorKind } from "@pithy-sh/core/src/controlPlane/data/connection";
4
5
  import { AuditEventRow } from "./data/auditEvent";
5
6
  import type { AuditDatabase } from "./data/tables";
6
7
  /**
@@ -21,6 +22,8 @@ export interface AuditQuery {
21
22
  actorType?: AuditActorType;
22
23
  /** Match the acting principal's id. */
23
24
  actorId?: string;
25
+ /** Match the kind of management client that acted (`agent` | `dashboard` | `script`). */
26
+ actorKind?: ControlPlaneActorKind;
24
27
  /** Match an exact `domain/reason` action code. */
25
28
  action?: string;
26
29
  /** Match the outcome (`success` | `failure` | `denied`). */
@@ -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;AAGvG,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,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;AAwDD;;;;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,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"}
package/dist/query.js CHANGED
@@ -16,6 +16,7 @@ function auditEventQuery(db, filter) {
16
16
  let query = db.selectFrom("pithyAuditEvents").selectAll();
17
17
  if (filter.actorType !== void 0) query = query.where("actorType", "=", filter.actorType);
18
18
  if (filter.actorId !== void 0) query = query.where("actorId", "=", filter.actorId);
19
+ if (filter.actorKind !== void 0) query = query.where("actorKind", "=", filter.actorKind);
19
20
  if (filter.action !== void 0) query = query.where("action", "=", filter.action);
20
21
  if (filter.outcome !== void 0) query = query.where("outcome", "=", filter.outcome);
21
22
  if (filter.severity !== void 0) query = query.where("severity", "=", filter.severity);
@@ -1 +1 @@
1
- {"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,qCAAqC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAEnE,OAAO,EAAE,KAAK,cAAc,EAAe,MAAM,qCAAqC,CAAC;AACvF,OAAO,EAAa,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAG5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,WAAW;IAC1B,8FAA8F;IAC9F,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,2EAA2E;IAC3E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kFAAkF;IAClF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAKD,mHAAmH;AACnH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,uFAAuF;IACvF,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAWD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE,eAAe,EACtB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,IAAI,CAAC,CA8Cf;AAED,iHAAiH;AACjH,wBAAgB,eAAe,CAAC,EAAE,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAE5F"}
1
+ {"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,qCAAqC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAEnE,OAAO,EAAE,KAAK,cAAc,EAAe,MAAM,qCAAqC,CAAC;AACvF,OAAO,EAAa,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAG5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,WAAW;IAC1B,8FAA8F;IAC9F,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,2EAA2E;IAC3E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kFAAkF;IAClF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAKD,mHAAmH;AACnH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,uFAAuF;IACvF,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAWD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE,eAAe,EACtB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAkDf;AAED,iHAAiH;AACjH,wBAAgB,eAAe,CAAC,EAAE,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAE5F"}
package/dist/recorder.js CHANGED
@@ -41,6 +41,7 @@ async function recordAuditEvent(db, input, options) {
41
41
  severity: event.severity,
42
42
  actorType: event.actorType,
43
43
  actorId: event.actorId ?? null,
44
+ ...event.actorKind == null ? {} : { actorKind: event.actorKind },
44
45
  sessionId: event.sessionId ?? null,
45
46
  resourceType: event.resourceType ?? null,
46
47
  resourceId: event.resourceId ?? null,
@@ -1 +1 @@
1
- {"version":3,"file":"example.d.ts","sourceRoot":"","sources":["../../src/seeds/example.ts"],"names":[],"mappings":"AAIA,OAAO,EAA2B,KAAK,OAAO,EAAE,MAAM,8BAA8B,CAAC;AA0CrF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAiI7B,CAAC"}
1
+ {"version":3,"file":"example.d.ts","sourceRoot":"","sources":["../../src/seeds/example.ts"],"names":[],"mappings":"AAIA,OAAO,EAA2B,KAAK,OAAO,EAAE,MAAM,8BAA8B,CAAC;AA0CrF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAuI7B,CAAC"}
@@ -72,6 +72,7 @@ const auditExampleSeed = defineSeed({
72
72
  severity: "info",
73
73
  actorType: "user",
74
74
  actorId: EXAMPLE_ADA.id,
75
+ actorKind: null,
75
76
  sessionId: "example-session-ada",
76
77
  resourceType: null,
77
78
  resourceId: null,
@@ -91,6 +92,7 @@ const auditExampleSeed = defineSeed({
91
92
  severity: "warning",
92
93
  actorType: "user",
93
94
  actorId: EXAMPLE_GRACE.id,
95
+ actorKind: null,
94
96
  sessionId: null,
95
97
  resourceType: null,
96
98
  resourceId: null,
@@ -110,6 +112,7 @@ const auditExampleSeed = defineSeed({
110
112
  severity: "info",
111
113
  actorType: "system",
112
114
  actorId: null,
115
+ actorKind: null,
113
116
  sessionId: null,
114
117
  resourceType: "user",
115
118
  resourceId: EXAMPLE_ALAN.id,
@@ -132,6 +135,7 @@ const auditExampleSeed = defineSeed({
132
135
  severity: "warning",
133
136
  actorType: "user",
134
137
  actorId: EXAMPLE_ADA.id,
138
+ actorKind: null,
135
139
  sessionId: "example-session-ada",
136
140
  resourceType: "config",
137
141
  resourceId: "billing",
@@ -155,6 +159,7 @@ const auditExampleSeed = defineSeed({
155
159
  severity: "critical",
156
160
  actorType: "user",
157
161
  actorId: EXAMPLE_GRACE.id,
162
+ actorKind: null,
158
163
  sessionId: null,
159
164
  resourceType: "session",
160
165
  resourceId: "example-family-grace",
@@ -177,6 +182,7 @@ const auditExampleSeed = defineSeed({
177
182
  severity: "info",
178
183
  actorType: "user",
179
184
  actorId: EXAMPLE_ALAN.id,
185
+ actorKind: null,
180
186
  sessionId: "example-session-alan",
181
187
  resourceType: "ledger",
182
188
  resourceId: "coins",
@@ -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.2.7";
6
+ export declare const PACKAGE_VERSION = "0.4.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.2.7";
7
+ const PACKAGE_VERSION = "0.4.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.2.7",
3
+ "version": "0.4.0",
4
4
  "license": "FSL-1.1-MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -26,7 +26,7 @@
26
26
  },
27
27
  "scripts": {
28
28
  "build": "tsdown && tsc -p tsconfig.build.json && bun ../../tooling/build/src/stampDeclarations.ts",
29
- "typecheck": "tsc -p tsconfig.json",
29
+ "typecheck": "bun check -p tsconfig.json",
30
30
  "test": "vitest run",
31
31
  "test:node": "vitest run --project=node",
32
32
  "test:workers": "vitest run --project=workers",
@@ -38,13 +38,13 @@
38
38
  "@hono/zod-validator": "^0.9.0"
39
39
  },
40
40
  "peerDependencies": {
41
- "@pithy-sh/core": "^0.9.0",
41
+ "@pithy-sh/core": "^0.11.0",
42
42
  "hono": "^4.13.2",
43
43
  "kysely": "^0.29.0",
44
44
  "zod": "^4.4.0"
45
45
  },
46
46
  "devDependencies": {
47
- "@cloudflare/vitest-plugin": "^1.0.0",
47
+ "@cloudflare/vitest-plugin": "^1.4.2",
48
48
  "@pithy-sh/core": "workspace:*",
49
49
  "@pithy-sh/tsconfig": "workspace:*",
50
50
  "@types/node": "^22.15.0",
@@ -55,7 +55,7 @@
55
55
  "tsdown": "^0.23.0",
56
56
  "typescript": "^7.0.2",
57
57
  "vitest": "^4.1.0",
58
- "wrangler": "^4.115.0",
58
+ "wrangler": "^4.151.0",
59
59
  "zod": "^4.4.0"
60
60
  }
61
61
  }
package/src/capability.ts CHANGED
@@ -9,6 +9,7 @@ import { auditTables } from "./data/tables";
9
9
  import { auditAdminRoutes } from "./http/guards";
10
10
  import { registerAuditRoutes } from "./http/routes";
11
11
  import { audit_0001_init } from "./migrations/0001_init";
12
+ import { audit_0002_actor_kind } from "./migrations/0002_actor_kind";
12
13
  import { recordAuditEvent } from "./recorder";
13
14
  import { auditExampleSeed } from "./seeds/example";
14
15
  import { PACKAGE_NAME, PACKAGE_VERSION } from "./version.generated";
@@ -87,7 +88,7 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
87
88
  binding: resolved.database,
88
89
  tables: auditTables,
89
90
  migrationOrder: AUDIT_MIGRATION_ORDER,
90
- migrations: { "0001_init": audit_0001_init },
91
+ migrations: { "0001_init": audit_0001_init, "0002_actor_kind": audit_0002_actor_kind },
91
92
  },
92
93
  },
93
94
  seeds: [auditExampleSeed],
@@ -36,6 +36,17 @@ export interface CfActorSource {
36
36
  accountTokens: CfAccountTokenActorSource;
37
37
  }
38
38
 
39
+ /**
40
+ * What the caller knows about the credential that the token's spelling cannot say.
41
+ *
42
+ * `kind: "session"` is a signed-in Cloudflare session (#759): an OAuth access token, opaque, carrying
43
+ * neither `cfut_` nor `cfat_`. The caller resolved the credential and knows; inferring it from the
44
+ * spelling would make a prefix change at Cloudflare a silent change of actor.
45
+ */
46
+ export interface ResolveActorOptions {
47
+ kind?: "session";
48
+ }
49
+
39
50
  /** A resolved CLI actor: who to attribute a control-plane audit event to, plus correlation metadata. */
40
51
  export interface ResolvedActor {
41
52
  /** The kind of principal. */
@@ -72,8 +83,22 @@ function systemActor(note: string): ResolvedActor {
72
83
  * Resolution failure — a bad token, a network error, an unrecognized prefix — is **never fatal**: it
73
84
  * returns a `system` actor with a `metadata` note, so the event is still written, just unattributed.
74
85
  */
75
- export async function resolveActor(apiToken: string, source: CfActorSource): Promise<ResolvedActor> {
86
+ export async function resolveActor(
87
+ apiToken: string,
88
+ source: CfActorSource,
89
+ options: ResolveActorOptions = {},
90
+ ): Promise<ResolvedActor> {
76
91
  try {
92
+ // A signed-in session names the person through `GET /user`, which `user-details.read` grants (#759).
93
+ // Its access token carries neither prefix, so the caller — which resolved the credential — says so.
94
+ if (options.kind === "session") {
95
+ const user = await source.user.getUser();
96
+ return {
97
+ actorType: "user",
98
+ actorId: user.email ?? user.id ?? null,
99
+ metadata: { cfTokenType: "session", cfUserId: user.id ?? null },
100
+ };
101
+ }
77
102
  if (apiToken.startsWith("cfut_")) {
78
103
  const user = await source.user.getUser();
79
104
  return {
@@ -117,10 +142,14 @@ export async function resolveActor(apiToken: string, source: CfActorSource): Pro
117
142
  * command — actor identity is resolved at session start, not per event. Memoizes the in-flight
118
143
  * promise so concurrent emits share the single resolution.
119
144
  */
120
- export function createCachedActorResolver(apiToken: string, source: CfActorSource): () => Promise<ResolvedActor> {
145
+ export function createCachedActorResolver(
146
+ apiToken: string,
147
+ source: CfActorSource,
148
+ options: ResolveActorOptions = {},
149
+ ): () => Promise<ResolvedActor> {
121
150
  let cached: Promise<ResolvedActor> | undefined;
122
151
  return () => {
123
- cached ??= resolveActor(apiToken, source);
152
+ cached ??= resolveActor(apiToken, source, options);
124
153
  return cached;
125
154
  };
126
155
  }
@@ -8,6 +8,7 @@ import {
8
8
  AuditOutcome,
9
9
  AuditSeverity,
10
10
  } from "@pithy-sh/core/src/audit/auditEvent";
11
+ import { ControlPlaneActorKind } from "@pithy-sh/core/src/controlPlane/data/connection";
11
12
  import { SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
12
13
  import { z } from "zod";
13
14
 
@@ -60,6 +61,11 @@ export const AuditEventRow = z
60
61
  .describe(
61
62
  "The acting principal's stable id (user id, service/token name); null for `system`/`anonymous`. Indexed.",
62
63
  ),
64
+ actorKind: ControlPlaneActorKind.nullable()
65
+ .default(null)
66
+ .describe(
67
+ "For a `control-plane` actor, what kind of management client acted: `agent`, `dashboard` or `script`, from the connection it called through (#721). Null for every other actor, for a connection registered before the kind was recorded, and on rows written before this column existed (`audit_0002_actor_kind`).",
68
+ ),
63
69
  sessionId: z
64
70
  .string()
65
71
  .nullable()
@@ -2,6 +2,7 @@
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
3
 
4
4
  import { AuditActorType, AuditMetadata, AuditOutcome, AuditSeverity } from "@pithy-sh/core/src/audit/auditEvent";
5
+ import { ControlPlaneActorKind } from "@pithy-sh/core/src/controlPlane/data/connection";
5
6
  import { z } from "zod";
6
7
 
7
8
  /**
@@ -49,6 +50,12 @@ export const AuditEventView = z
49
50
  severity: AuditSeverity.describe("How serious it is, orthogonal to the outcome."),
50
51
  actorType: AuditActorType.describe("The kind of principal that acted."),
51
52
  actorId: z.string().nullable().describe("The acting principal's stable id, or null."),
53
+ // Added (#721), so `.optional()` too: a client reading an older Worker receives no such field.
54
+ actorKind: ControlPlaneActorKind.nullable()
55
+ .optional()
56
+ .describe(
57
+ "For a `control-plane` actor, which kind of management client acted — `agent`, `dashboard` or `script` — or null. Absent from a Worker older than the field.",
58
+ ),
52
59
  sessionId: z.string().nullable().describe("The session the action belongs to — a row id, never a token — or null."),
53
60
  resourceType: z.string().nullable().describe("The kind of thing acted on, or null."),
54
61
  resourceId: z.string().nullable().describe("The thing acted on, or null."),
@@ -1,20 +1,20 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
3
 
4
- import { zValidator } from "@hono/zod-validator";
5
4
  import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
6
5
  import type { ControlPlaneContext } from "@pithy-sh/core/src/controlPlane/context";
7
6
  import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
8
7
  import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
9
8
  import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
10
- import { validationHook } from "@pithy-sh/core/src/http/validation";
9
+ import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
10
+ import { validate } from "@pithy-sh/core/src/http/validation";
11
11
  import type { VerificationStrategy } from "@pithy-sh/core/src/http/verification";
12
12
  import type { Context, Hono } from "hono";
13
13
  import { AuditTrailActions } from "../actions";
14
14
  import type { AuditDatabase } from "../data/tables";
15
15
  import { pageAuditEvents, readAuditEvent } from "../query";
16
16
  import { AUDIT_EVENT_DETAIL_READ_SCOPE, AUDIT_TRAIL_READ_SCOPE } from "./guards";
17
- import type { AuditEventResponse, AuditEventsResponse } from "./responses";
17
+ import { AuditEventResponse, AuditEventsResponse } from "./responses";
18
18
  import { AuditEventIdParam, ListAuditEventsQuery } from "./schemas";
19
19
  import { auditEventDetailView, auditEventView } from "./views";
20
20
 
@@ -43,7 +43,7 @@ import { auditEventDetailView, auditEventView } from "./views";
43
43
  * What every route this capability mounts declares: its path, its strategy, and the scope it checks.
44
44
  *
45
45
  * Exported so a test asserts against the declaration rather than against a middleware count. Counting
46
- * `app.routes` entries proves that *something* runs before the handler — a bare `zValidator` satisfies
46
+ * `app.routes` entries proves that *something* runs before the handler — a bare `validate` satisfies
47
47
  * it — and cannot prove *what*. This is a declaration, so it can drift from the router;
48
48
  * `routeContract.test.ts` checks it against Hono in both directions, so a route added without an entry
49
49
  * and an entry naming no route both fail.
@@ -129,8 +129,14 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
129
129
  */
130
130
  app.get(
131
131
  `${base}/events`,
132
+ describeRoute({
133
+ summary: "Page through the audit trail, newest first.",
134
+ verification: "control-plane",
135
+ scopes: [AUDIT_TRAIL_READ_SCOPE],
136
+ responses: { 200: AuditEventsResponse },
137
+ }),
132
138
  requireControlPlane(AUDIT_TRAIL_READ_SCOPE),
133
- zValidator("query", ListAuditEventsQuery, validationHook),
139
+ validate("query", ListAuditEventsQuery),
134
140
  async (c) => {
135
141
  const operator = caller(c);
136
142
  const query = c.req.valid("query");
@@ -172,8 +178,14 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
172
178
  */
173
179
  app.get(
174
180
  `${base}/events/:eventId`,
181
+ describeRoute({
182
+ summary: "Read one audit event in full, with its IP, user-agent and metadata.",
183
+ verification: "control-plane",
184
+ scopes: [AUDIT_EVENT_DETAIL_READ_SCOPE],
185
+ responses: { 200: AuditEventResponse },
186
+ }),
175
187
  requireControlPlane(AUDIT_EVENT_DETAIL_READ_SCOPE),
176
- zValidator("param", AuditEventIdParam, validationHook),
188
+ validate("param", AuditEventIdParam),
177
189
  async (c) => {
178
190
  const operator = caller(c);
179
191
  const { eventId } = c.req.valid("param");
@@ -2,6 +2,7 @@
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
3
 
4
4
  import { AuditAction, AuditActorType, AuditOutcome, AuditSeverity } from "@pithy-sh/core/src/audit/auditEvent";
5
+ import { ControlPlaneActorKind } from "@pithy-sh/core/src/controlPlane/data/connection";
5
6
  import { MAX_PAGE_SIZE } from "@pithy-sh/core/src/data/cursor";
6
7
  import { z } from "zod";
7
8
 
@@ -75,6 +76,9 @@ export const ListAuditEventsQuery = z
75
76
  "Filter to one kind of principal. `control-plane` is the one that separates a management client's own actions from the adopter's users'.",
76
77
  ),
77
78
  actorId: FilterValue.optional().describe("Filter to one principal — a user id, a service name, a token subject."),
79
+ actorKind: ControlPlaneActorKind.optional().describe(
80
+ "Filter to one kind of management client: `agent`, `dashboard` or `script`. What `actorType=control-plane` cannot say on its own.",
81
+ ),
78
82
  action: AuditAction.max(MAX_FILTER_LENGTH)
79
83
  .optional()
80
84
  .describe("Filter to one exact `domain/reason` action code. Exact, never a prefix — the taxonomy is federated."),
package/src/http/views.ts CHANGED
@@ -61,6 +61,9 @@ export function auditEventView(row: AuditEventRow): AuditEventView {
61
61
  severity: row.severity,
62
62
  actorType: row.actorType,
63
63
  actorId: row.actorId,
64
+ // In the listing: it is what tells an agent's action from the dashboard's, which is the first thing
65
+ // a reader after an incident filters on, and it is no more personal than `actorType` beside it.
66
+ actorKind: row.actorKind,
64
67
  sessionId: row.sessionId,
65
68
  resourceType: row.resourceType,
66
69
  resourceId: row.resourceId,
@@ -0,0 +1,31 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: FSL-1.1-MIT
3
+
4
+ import type { Kysely } from "kysely";
5
+ import type { Migration } from "kysely/migration";
6
+
7
+ /**
8
+ * What kind of management client acted — `#721`.
9
+ *
10
+ * `actorType: "control-plane"` names an agent, the dashboard and a script identically, and those are the
11
+ * questions asked after an incident. The kind is recorded on the connection when it is registered and
12
+ * stamped onto every control-plane row by `requireControlPlane`; this is the column it lands in.
13
+ *
14
+ * **Appended, never folded into `0001`.** The audit capability has shipped, so its table is history.
15
+ *
16
+ * **Nullable, with no default and no backfill.** Every row before this one, and every row whose actor is
17
+ * not a management client, has no kind — and a row recorded under a connection registered before kinds
18
+ * were recorded has none either. Null says exactly that. No index: the trail is read by time and actor
19
+ * first, and a kind narrows a page that `actorType` has already narrowed.
20
+ */
21
+ export const audit_0002_actor_kind: Migration = {
22
+ up: async (db: Kysely<unknown>): Promise<void> => {
23
+ await db.schema.alterTable("pithyAuditEvents").addColumn("actorKind", "text").execute();
24
+ },
25
+
26
+ down: async (db: Kysely<unknown>): Promise<void> => {
27
+ // In place, as `controlplane_0002` drops its column: D1's engine supports it, and a rebuild would
28
+ // rewrite every row of the largest table in the project to remove one nothing else reads.
29
+ await db.schema.alterTable("pithyAuditEvents").dropColumn("actorKind").execute();
30
+ },
31
+ };
package/src/query.ts CHANGED
@@ -2,6 +2,7 @@
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
3
 
4
4
  import type { AuditActorType, AuditOutcome, AuditSeverity } from "@pithy-sh/core/src/audit/auditEvent";
5
+ import type { ControlPlaneActorKind } from "@pithy-sh/core/src/controlPlane/data/connection";
5
6
  import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
6
7
  import { decodeCursor, type PageCursor, pageLimit, toPage } from "@pithy-sh/core/src/data/cursor";
7
8
  import { AuditEventRow } from "./data/auditEvent";
@@ -25,6 +26,8 @@ export interface AuditQuery {
25
26
  actorType?: AuditActorType;
26
27
  /** Match the acting principal's id. */
27
28
  actorId?: string;
29
+ /** Match the kind of management client that acted (`agent` | `dashboard` | `script`). */
30
+ actorKind?: ControlPlaneActorKind;
28
31
  /** Match an exact `domain/reason` action code. */
29
32
  action?: string;
30
33
  /** Match the outcome (`success` | `failure` | `denied`). */
@@ -95,6 +98,7 @@ function auditEventQuery(db: AuditDatabase, filter: AuditQuery) {
95
98
 
96
99
  if (filter.actorType !== undefined) query = query.where("actorType", "=", filter.actorType);
97
100
  if (filter.actorId !== undefined) query = query.where("actorId", "=", filter.actorId);
101
+ if (filter.actorKind !== undefined) query = query.where("actorKind", "=", filter.actorKind);
98
102
  if (filter.action !== undefined) query = query.where("action", "=", filter.action);
99
103
  if (filter.outcome !== undefined) query = query.where("outcome", "=", filter.outcome);
100
104
  if (filter.severity !== undefined) query = query.where("severity", "=", filter.severity);
package/src/recorder.ts CHANGED
@@ -123,6 +123,10 @@ export async function recordAuditEvent(
123
123
  severity: event.severity,
124
124
  actorType: event.actorType,
125
125
  actorId: event.actorId ?? null,
126
+ // Named only when the event carries one (#721). A Worker deployed ahead of
127
+ // `audit_0002_actor_kind` then keeps recording every row it recorded before; only a call
128
+ // through a connection with a kind depends on the column being there.
129
+ ...(event.actorKind == null ? {} : { actorKind: event.actorKind }),
126
130
  sessionId: event.sessionId ?? null,
127
131
  resourceType: event.resourceType ?? null,
128
132
  resourceId: event.resourceId ?? null,
@@ -73,6 +73,7 @@ export const auditExampleSeed: SeedSet = defineSeed({
73
73
  severity: "info",
74
74
  actorType: "user",
75
75
  actorId: EXAMPLE_ADA.id,
76
+ actorKind: null,
76
77
  sessionId: "example-session-ada",
77
78
  resourceType: null,
78
79
  resourceId: null,
@@ -92,6 +93,7 @@ export const auditExampleSeed: SeedSet = defineSeed({
92
93
  severity: "warning",
93
94
  actorType: "user",
94
95
  actorId: EXAMPLE_GRACE.id,
96
+ actorKind: null,
95
97
  sessionId: null,
96
98
  resourceType: null,
97
99
  resourceId: null,
@@ -111,6 +113,7 @@ export const auditExampleSeed: SeedSet = defineSeed({
111
113
  severity: "info",
112
114
  actorType: "system",
113
115
  actorId: null,
116
+ actorKind: null,
114
117
  sessionId: null,
115
118
  // The two halves of a payments subject, spelled in the two columns the trail already had:
116
119
  // `resourceType` is the kind (`user` or `organization` — `PaymentsSubjectType`) and `resourceId`
@@ -134,6 +137,7 @@ export const auditExampleSeed: SeedSet = defineSeed({
134
137
  severity: "warning",
135
138
  actorType: "user",
136
139
  actorId: EXAMPLE_ADA.id,
140
+ actorKind: null,
137
141
  sessionId: "example-session-ada",
138
142
  resourceType: "config",
139
143
  resourceId: "billing",
@@ -154,6 +158,7 @@ export const auditExampleSeed: SeedSet = defineSeed({
154
158
  severity: "critical",
155
159
  actorType: "user",
156
160
  actorId: EXAMPLE_GRACE.id,
161
+ actorKind: null,
157
162
  sessionId: null,
158
163
  resourceType: "session",
159
164
  resourceId: "example-family-grace",
@@ -173,6 +178,7 @@ export const auditExampleSeed: SeedSet = defineSeed({
173
178
  severity: "info",
174
179
  actorType: "user",
175
180
  actorId: EXAMPLE_ALAN.id,
181
+ actorKind: null,
176
182
  sessionId: "example-session-alan",
177
183
  resourceType: "ledger",
178
184
  resourceId: "coins",
@@ -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.2.7";
16
+ export const PACKAGE_VERSION = "0.4.0";