@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.
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +5 -1
- package/dist/data/auditEvent.d.ts +7 -2
- package/dist/data/auditEvent.d.ts.map +1 -1
- package/dist/data/auditEvent.js +2 -0
- package/dist/data/tables.d.ts +6 -1
- package/dist/data/tables.d.ts.map +1 -1
- package/dist/error/errors.d.ts +4 -3
- package/dist/error/errors.d.ts.map +1 -1
- package/dist/http/responses.d.ts +20 -0
- package/dist/http/responses.d.ts.map +1 -1
- package/dist/http/responses.js +2 -0
- package/dist/http/schemas.d.ts +5 -0
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +2 -0
- package/dist/http/views.d.ts.map +1 -1
- package/dist/http/views.js +1 -0
- package/dist/migrations/0002_actor_kind.d.ts +19 -0
- package/dist/migrations/0002_actor_kind.d.ts.map +1 -0
- package/dist/migrations/0002_actor_kind.js +27 -0
- package/dist/query.d.ts +3 -0
- package/dist/query.d.ts.map +1 -1
- package/dist/query.js +1 -0
- package/dist/recorder.d.ts.map +1 -1
- package/dist/recorder.js +1 -0
- package/dist/seeds/example.d.ts.map +1 -1
- package/dist/seeds/example.js +6 -0
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/package.json +3 -3
- package/src/capability.ts +6 -2
- package/src/data/auditEvent.ts +6 -0
- package/src/error/errors.ts +4 -3
- package/src/http/responses.ts +7 -0
- package/src/http/schemas.ts +4 -0
- package/src/http/views.ts +3 -0
- package/src/migrations/0002_actor_kind.ts +31 -0
- package/src/query.ts +4 -0
- package/src/recorder.ts +4 -0
- package/src/seeds/example.ts +6 -0
- package/src/version.generated.ts +1 -1
package/dist/capability.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"
|
|
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"}
|
package/dist/capability.js
CHANGED
|
@@ -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: {
|
|
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:
|
|
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<
|
|
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":"
|
|
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"}
|
package/dist/data/auditEvent.js
CHANGED
|
@@ -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."),
|
package/dist/data/tables.d.ts
CHANGED
|
@@ -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("
|
|
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
|
|
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"}
|
package/dist/error/errors.d.ts
CHANGED
|
@@ -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?:
|
|
20
|
+
message?: UnmarkedString;
|
|
20
21
|
/** A remediation hint (CLI action line). */
|
|
21
|
-
action?:
|
|
22
|
+
action?: UnmarkedString;
|
|
22
23
|
/** Internal context for logs + audit. Never serialized to clients. */
|
|
23
|
-
detail?:
|
|
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;
|
|
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"}
|
package/dist/http/responses.d.ts
CHANGED
|
@@ -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":"
|
|
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"}
|
package/dist/http/responses.js
CHANGED
|
@@ -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."),
|
package/dist/http/schemas.d.ts
CHANGED
|
@@ -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":"
|
|
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"}
|
package/dist/http/schemas.js
CHANGED
|
@@ -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."),
|
package/dist/http/views.d.ts.map
CHANGED
|
@@ -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,
|
|
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"}
|
package/dist/http/views.js
CHANGED
|
@@ -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`). */
|
package/dist/query.d.ts.map
CHANGED
|
@@ -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;
|
|
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);
|
package/dist/recorder.d.ts.map
CHANGED
|
@@ -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,
|
|
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,
|
|
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"}
|
package/dist/seeds/example.js
CHANGED
|
@@ -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.
|
|
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.
|
|
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
|
+
"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": "
|
|
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.
|
|
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
|
-
|
|
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,
|
package/src/data/auditEvent.ts
CHANGED
|
@@ -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()
|
package/src/error/errors.ts
CHANGED
|
@@ -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?:
|
|
23
|
+
message?: UnmarkedString;
|
|
23
24
|
/** A remediation hint (CLI action line). */
|
|
24
|
-
action?:
|
|
25
|
+
action?: UnmarkedString;
|
|
25
26
|
/** Internal context for logs + audit. Never serialized to clients. */
|
|
26
|
-
detail?:
|
|
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`.
|
package/src/http/responses.ts
CHANGED
|
@@ -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."),
|
package/src/http/schemas.ts
CHANGED
|
@@ -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,
|
package/src/seeds/example.ts
CHANGED
|
@@ -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",
|
package/src/version.generated.ts
CHANGED