@pithy-sh/audit 0.3.0 → 0.5.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 (41) hide show
  1. package/dist/capability.d.ts.map +1 -1
  2. package/dist/capability.js +5 -1
  3. package/dist/data/auditEvent.d.ts +7 -2
  4. package/dist/data/auditEvent.d.ts.map +1 -1
  5. package/dist/data/auditEvent.js +2 -0
  6. package/dist/data/tables.d.ts +6 -1
  7. package/dist/data/tables.d.ts.map +1 -1
  8. package/dist/error/errors.d.ts +4 -3
  9. package/dist/error/errors.d.ts.map +1 -1
  10. package/dist/http/responses.d.ts +20 -0
  11. package/dist/http/responses.d.ts.map +1 -1
  12. package/dist/http/responses.js +2 -0
  13. package/dist/http/schemas.d.ts +5 -0
  14. package/dist/http/schemas.d.ts.map +1 -1
  15. package/dist/http/schemas.js +2 -0
  16. package/dist/http/views.d.ts.map +1 -1
  17. package/dist/http/views.js +1 -0
  18. package/dist/migrations/0002_actor_kind.d.ts +19 -0
  19. package/dist/migrations/0002_actor_kind.d.ts.map +1 -0
  20. package/dist/migrations/0002_actor_kind.js +27 -0
  21. package/dist/query.d.ts +3 -0
  22. package/dist/query.d.ts.map +1 -1
  23. package/dist/query.js +1 -0
  24. package/dist/recorder.d.ts.map +1 -1
  25. package/dist/recorder.js +1 -0
  26. package/dist/seeds/example.d.ts.map +1 -1
  27. package/dist/seeds/example.js +6 -0
  28. package/dist/version.generated.d.ts +1 -1
  29. package/dist/version.generated.js +1 -1
  30. package/package.json +3 -3
  31. package/src/capability.ts +6 -2
  32. package/src/data/auditEvent.ts +6 -0
  33. package/src/error/errors.ts +4 -3
  34. package/src/http/responses.ts +7 -0
  35. package/src/http/schemas.ts +4 -0
  36. package/src/http/views.ts +3 -0
  37. package/src/migrations/0002_actor_kind.ts +31 -0
  38. package/src/query.ts +4 -0
  39. package/src/recorder.ts +4 -0
  40. package/src/seeds/example.ts +6 -0
  41. 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":"AAIA,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,CA8DpE;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),
@@ -18,7 +18,7 @@ import { z } from "zod";
18
18
  * on both sides. Exported so the recorder encodes the column through the same codec it is read back
19
19
  * with, rather than hand-rolling `JSON.stringify` (CLAUDE.md §Data layer).
20
20
  */
21
- export declare const AuditMetadataColumn: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
21
+ export declare const AuditMetadataColumn: import("@pithy-sh/core/src/data/codecs").SqliteJson<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
22
22
  export declare const AuditEventRow: z.ZodObject<{
23
23
  id: z.ZodNumber;
24
24
  eventId: z.ZodString;
@@ -42,13 +42,18 @@ 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>;
48
53
  ip: z.ZodNullable<z.ZodString>;
49
54
  userAgent: z.ZodNullable<z.ZodString>;
50
55
  requestId: z.ZodNullable<z.ZodString>;
51
- metadata: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
56
+ metadata: z.ZodNullable<import("@pithy-sh/core/src/data/codecs").SqliteJson<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
52
57
  project: z.ZodNullable<z.ZodString>;
53
58
  environment: z.ZodNullable<z.ZodString>;
54
59
  worker: 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,6FAA4B,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,13 +32,18 @@ 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>;
38
43
  ip: import("zod").ZodNullable<import("zod").ZodString>;
39
44
  userAgent: import("zod").ZodNullable<import("zod").ZodString>;
40
45
  requestId: import("zod").ZodNullable<import("zod").ZodString>;
41
- metadata: import("zod").ZodNullable<import("zod").ZodCodec<import("zod").ZodUnion<readonly [import("zod").ZodString, import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>]>, import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>>;
46
+ metadata: import("zod").ZodNullable<import("@pithy-sh/core/src/data/codecs").SqliteJson<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>>;
42
47
  project: import("zod").ZodNullable<import("zod").ZodString>;
43
48
  environment: import("zod").ZodNullable<import("zod").ZodString>;
44
49
  worker: 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"}
@@ -2,6 +2,7 @@
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
3
  import { PithyError } from "@pithy-sh/core/src/error/pithyError";
4
4
  import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
5
+ import type { UnmarkedString } from "@pithy-sh/core/src/privacy/types";
5
6
  /**
6
7
  * Audit recorder throw sugar. The `audit/*` codes live in core's closed `KitErrorPayload` union
7
8
  * (CLAUDE.md §Errors: capabilities add their codes to the one union); these subclasses are the
@@ -16,11 +17,11 @@ import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
16
17
  /** Variable parts each subclass accepts; `code`/`status` are fixed by the subclass. */
17
18
  interface AuditErrorArgs {
18
19
  /** Override the public, safe-to-expose message. */
19
- message?: string;
20
+ message?: UnmarkedString;
20
21
  /** A remediation hint (CLI action line). */
21
- action?: string;
22
+ action?: UnmarkedString;
22
23
  /** Internal context for logs + audit. Never serialized to clients. */
23
- detail?: string;
24
+ detail?: UnmarkedString;
24
25
  /**
25
26
  * Values a translating client interpolates into its own wording for this code. Client-facing, so —
26
27
  * unlike `action` and `detail` — these cross the boundary with `message`.
@@ -1 +1 @@
1
- {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/error/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAErE;;;;;;;;;;GAUG;AAEH,uFAAuF;AACvF,UAAU,cAAc;IACtB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,wGAAwG;AACxG,qBAAa,sBAAuB,SAAQ,UAAU;IACpD,YAAY,IAAI,GAAE,cAAmB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYnE;CACF;AAED,8FAA8F;AAC9F,qBAAa,qBAAsB,SAAQ,UAAU;IACnD,YAAY,IAAI,GAAE,cAAmB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYnE;CACF"}
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/error/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAEvE;;;;;;;;;;GAUG;AAEH,uFAAuF;AACvF,UAAU,cAAc;IACtB,mDAAmD;IACnD,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,sEAAsE;IACtE,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,wGAAwG;AACxG,qBAAa,sBAAuB,SAAQ,UAAU;IACpD,YAAY,IAAI,GAAE,cAAmB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYnE;CACF;AAED,8FAA8F;AAC9F,qBAAa,qBAAsB,SAAQ,UAAU;IACnD,YAAY,IAAI,GAAE,cAAmB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYnE;CACF"}
@@ -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."),
@@ -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.3.0";
6
+ export declare const PACKAGE_VERSION = "0.5.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.3.0";
7
+ const PACKAGE_VERSION = "0.5.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.3.0",
3
+ "version": "0.5.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,7 +38,7 @@
38
38
  "@hono/zod-validator": "^0.9.0"
39
39
  },
40
40
  "peerDependencies": {
41
- "@pithy-sh/core": "^0.10.0",
41
+ "@pithy-sh/core": "^0.12.0",
42
42
  "hono": "^4.13.2",
43
43
  "kysely": "^0.29.0",
44
44
  "zod": "^4.4.0"
package/src/capability.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
3
 
4
+ import type { AuditEventInput } from "@pithy-sh/core/src/audit/auditEvent";
4
5
  import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
5
6
  import { workerIdentity } from "@pithy-sh/core/src/worker/identity";
6
7
  import { z } from "zod";
@@ -9,6 +10,7 @@ import { auditTables } from "./data/tables";
9
10
  import { auditAdminRoutes } from "./http/guards";
10
11
  import { registerAuditRoutes } from "./http/routes";
11
12
  import { audit_0001_init } from "./migrations/0001_init";
13
+ import { audit_0002_actor_kind } from "./migrations/0002_actor_kind";
12
14
  import { recordAuditEvent } from "./recorder";
13
15
  import { auditExampleSeed } from "./seeds/example";
14
16
  import { PACKAGE_NAME, PACKAGE_VERSION } from "./version.generated";
@@ -87,7 +89,7 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
87
89
  binding: resolved.database,
88
90
  tables: auditTables,
89
91
  migrationOrder: AUDIT_MIGRATION_ORDER,
90
- migrations: { "0001_init": audit_0001_init },
92
+ migrations: { "0001_init": audit_0001_init, "0002_actor_kind": audit_0002_actor_kind },
91
93
  },
92
94
  },
93
95
  seeds: [auditExampleSeed],
@@ -114,7 +116,9 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
114
116
  // capability object is built before any request exists, and `env` is only reachable from a
115
117
  // context. `workerIdentity` never throws and returns nulls for whatever is unstamped, so a
116
118
  // Worker predating these vars still records its events — just without an origin.
117
- c.set("emit", (event) =>
119
+ // The parameter is annotated: `AuditEmit` is generic over `metadata` so a call site carrying a
120
+ // privacy-marked value fails to compile (#132), and the recorder is the one place every event lands.
121
+ c.set("emit", (event: AuditEventInput) =>
118
122
  recordAuditEvent(
119
123
  (c.var.db as Record<typeof AUDIT_DATABASE_NAME, AuditDatabase>)[AUDIT_DATABASE_NAME],
120
124
  event,
@@ -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()
@@ -3,6 +3,7 @@
3
3
 
4
4
  import { PithyError } from "@pithy-sh/core/src/error/pithyError";
5
5
  import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
6
+ import type { UnmarkedString } from "@pithy-sh/core/src/privacy/types";
6
7
 
7
8
  /**
8
9
  * Audit recorder throw sugar. The `audit/*` codes live in core's closed `KitErrorPayload` union
@@ -19,11 +20,11 @@ import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
19
20
  /** Variable parts each subclass accepts; `code`/`status` are fixed by the subclass. */
20
21
  interface AuditErrorArgs {
21
22
  /** Override the public, safe-to-expose message. */
22
- message?: string;
23
+ message?: UnmarkedString;
23
24
  /** A remediation hint (CLI action line). */
24
- action?: string;
25
+ action?: UnmarkedString;
25
26
  /** Internal context for logs + audit. Never serialized to clients. */
26
- detail?: string;
27
+ detail?: UnmarkedString;
27
28
  /**
28
29
  * Values a translating client interpolates into its own wording for this code. Client-facing, so —
29
30
  * unlike `action` and `detail` — these cross the boundary with `message`.
@@ -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."),
@@ -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.3.0";
16
+ export const PACKAGE_VERSION = "0.5.0";