@pithy-sh/audit 0.1.2 → 0.1.3

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 (56) hide show
  1. package/dist/actions.d.ts +41 -0
  2. package/dist/actions.d.ts.map +1 -0
  3. package/dist/actions.js +55 -0
  4. package/dist/capability.d.ts +40 -0
  5. package/dist/capability.d.ts.map +1 -0
  6. package/dist/capability.js +86 -0
  7. package/dist/cli/emitFromCLI.d.ts +35 -0
  8. package/dist/cli/emitFromCLI.d.ts.map +1 -0
  9. package/dist/cli/emitFromCLI.js +37 -0
  10. package/dist/cli/resolveActor.d.ts +74 -0
  11. package/dist/cli/resolveActor.d.ts.map +1 -0
  12. package/dist/cli/resolveActor.js +83 -0
  13. package/dist/data/auditEvent.d.ts +57 -0
  14. package/dist/data/auditEvent.d.ts.map +1 -0
  15. package/dist/data/auditEvent.js +46 -0
  16. package/dist/data/tables.d.ts +52 -0
  17. package/dist/data/tables.d.ts.map +1 -0
  18. package/dist/data/tables.js +15 -0
  19. package/dist/error/errors.d.ts +41 -0
  20. package/dist/error/errors.d.ts.map +1 -0
  21. package/dist/error/errors.js +30 -0
  22. package/dist/http/guards.d.ts +68 -0
  23. package/dist/http/guards.d.ts.map +1 -0
  24. package/dist/http/guards.js +80 -0
  25. package/dist/http/responses.d.ts +158 -0
  26. package/dist/http/responses.d.ts.map +1 -0
  27. package/dist/http/responses.js +71 -0
  28. package/dist/http/routes.d.ts +59 -0
  29. package/dist/http/routes.d.ts.map +1 -0
  30. package/dist/http/routes.js +125 -0
  31. package/dist/http/schemas.d.ts +45 -0
  32. package/dist/http/schemas.d.ts.map +1 -0
  33. package/dist/http/schemas.js +68 -0
  34. package/dist/http/views.d.ts +53 -0
  35. package/dist/http/views.d.ts.map +1 -0
  36. package/dist/http/views.js +79 -0
  37. package/dist/index.d.ts +16 -0
  38. package/dist/index.d.ts.map +1 -0
  39. package/dist/index.js +10 -0
  40. package/dist/migrations/0001_init.d.ts +19 -0
  41. package/dist/migrations/0001_init.d.ts.map +1 -0
  42. package/dist/migrations/0001_init.js +45 -0
  43. package/dist/query.d.ts +103 -0
  44. package/dist/query.d.ts.map +1 -0
  45. package/dist/query.js +95 -0
  46. package/dist/recorder.d.ts +80 -0
  47. package/dist/recorder.d.ts.map +1 -0
  48. package/dist/recorder.js +64 -0
  49. package/dist/seeds/example.d.ts +16 -0
  50. package/dist/seeds/example.d.ts.map +1 -0
  51. package/dist/seeds/example.js +194 -0
  52. package/dist/version.generated.d.ts +5 -0
  53. package/dist/version.generated.d.ts.map +1 -0
  54. package/dist/version.generated.js +7 -0
  55. package/package.json +21 -10
  56. package/src/version.generated.ts +1 -1
@@ -0,0 +1,15 @@
1
+ import { AuditEventRow } from "./auditEvent.js";
2
+ import { createDatabase } from "@pithy-sh/core/src/data/db";
3
+ //#region src/data/tables.ts
4
+ /**
5
+ * The audit capability's table map: camelCase keys (CamelCasePlugin emits the snake_case
6
+ * `pithy_audit_` SQL). One source of truth, shared by the capability wiring (`capability.ts`), the
7
+ * recorder, and the query helper so all three type against the same schema.
8
+ */
9
+ const auditTables = { pithyAuditEvents: AuditEventRow };
10
+ /** Build the audit Kysely over a D1 binding (or a REST `D1Database` from `@pithy-sh/cloudflare`). */
11
+ function auditDatabase(d1) {
12
+ return createDatabase(d1, auditTables);
13
+ }
14
+ //#endregion
15
+ export { auditDatabase, auditTables };
@@ -0,0 +1,41 @@
1
+ import { PithyError } from "@pithy-sh/core/src/error/pithyError";
2
+ import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
3
+ /**
4
+ * Audit recorder throw sugar. The `audit/*` codes live in core's closed `KitErrorPayload` union
5
+ * (CLAUDE.md §Errors: capabilities add their codes to the one union); these subclasses are the
6
+ * package-local vehicles that set one of those members — the same pattern as core's `NotFoundError`
7
+ * and `@pithy-sh/cloudflare`'s error classes. Runtime code here builds one of these, never a plain
8
+ * `new Error`.
9
+ *
10
+ * Both are recorded **non-fatally**: the recorder constructs one to represent a failure it logs, but
11
+ * never throws it into the audited action. `detail` carries throw-site context for logs; it is never
12
+ * serialized to a client (the HTTP codec strips it).
13
+ */
14
+ /** Variable parts each subclass accepts; `code`/`status` are fixed by the subclass. */
15
+ interface AuditErrorArgs {
16
+ /** Override the public, safe-to-expose message. */
17
+ message?: string;
18
+ /** A remediation hint (CLI action line). */
19
+ action?: string;
20
+ /** Internal context for logs + audit. Never serialized to clients. */
21
+ detail?: string;
22
+ /**
23
+ * Values a translating client interpolates into its own wording for this code. Client-facing, so —
24
+ * unlike `action` and `detail` — these cross the boundary with `message`.
25
+ */
26
+ params?: MessageParams;
27
+ }
28
+ /** An audit event failed validation against the `AuditEvent` schema (bad action, outcome, or actor). */
29
+ export declare class AuditInvalidEventError extends PithyError {
30
+ constructor(args?: AuditErrorArgs, options?: {
31
+ cause?: unknown;
32
+ });
33
+ }
34
+ /** Persisting an audit event to D1 failed after retries. Logged, never thrown to a client. */
35
+ export declare class AuditWriteFailedError extends PithyError {
36
+ constructor(args?: AuditErrorArgs, options?: {
37
+ cause?: unknown;
38
+ });
39
+ }
40
+ export {};
41
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +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"}
@@ -0,0 +1,30 @@
1
+ import { PithyError } from "@pithy-sh/core/src/error/pithyError";
2
+ //#region src/error/errors.ts
3
+ /** An audit event failed validation against the `AuditEvent` schema (bad action, outcome, or actor). */
4
+ var AuditInvalidEventError = class extends PithyError {
5
+ constructor(args = {}, options) {
6
+ super({
7
+ code: "audit/invalid_event",
8
+ status: 400,
9
+ message: args.message ?? "An audit event failed validation.",
10
+ action: args.action,
11
+ detail: args.detail,
12
+ params: args.params
13
+ }, options);
14
+ }
15
+ };
16
+ /** Persisting an audit event to D1 failed after retries. Logged, never thrown to a client. */
17
+ var AuditWriteFailedError = class extends PithyError {
18
+ constructor(args = {}, options) {
19
+ super({
20
+ code: "audit/write_failed",
21
+ status: 500,
22
+ message: args.message ?? "Failed to persist an audit event.",
23
+ action: args.action,
24
+ detail: args.detail,
25
+ params: args.params
26
+ }, options);
27
+ }
28
+ };
29
+ //#endregion
30
+ export { AuditInvalidEventError, AuditWriteFailedError };
@@ -0,0 +1,68 @@
1
+ import type { AdminRoute } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
2
+ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
3
+ /**
4
+ * Audit's control-plane scopes, and the admin surface a manifest advertises.
5
+ *
6
+ * **Every route here is `control-plane`, every route here is a read, and there are no others.** The
7
+ * trail has no end-user surface — a user does not read the record of themselves being audited — so
8
+ * there is nothing for `requireAuth()` to gate, and putting it on these routes would deny every
9
+ * legitimate management call permanently: the seam deliberately leaves `c.var.auth` null for a
10
+ * control-plane caller, and no credential could ever satisfy it. The gate is imported from core
11
+ * rather than copied, because core is a hard dependency of every capability, so importing it cannot
12
+ * leave a deployment without one; with the seam uncomposed `requireControlPlane` raises
13
+ * `controlplane/not_connected` rather than passing.
14
+ *
15
+ * **Nothing here writes.** The trail is append-only by construction and stays that way: there is no
16
+ * delete route, no edit route, and no retention control on this surface. A management credential that
17
+ * could erase an audit row is a management credential that can erase the evidence of its own use.
18
+ *
19
+ * ## Two read scopes, because two reads disclose different things
20
+ *
21
+ * The tempting shape is one `audit:read`. It is wrong on the merits for the same reason a single
22
+ * `payments:admin` flag was: it makes the safe operation and the dangerous one the same grant.
23
+ *
24
+ * A **page of the trail** answers who did what, when, and whether it worked. That is the "recent
25
+ * activity" pane, it is what an operator looks at all day, and its projection carries no network
26
+ * identifier and no capability payload.
27
+ *
28
+ * **One event in full** additionally carries the client IP, the user-agent, and the capability's own
29
+ * `metadata` bag — which routinely holds the email address, the resource name, or the reason a
30
+ * capability recorded alongside its event. Bulk-harvesting those over a whole trail is a privacy
31
+ * incident, and requiring a second scope is what makes it a decision the adopter makes rather than
32
+ * one a listing credential comes with. Since the two are separate routes, a credential holding only
33
+ * the detail scope cannot enumerate the trail to find ids to read, and a credential holding only the
34
+ * list scope cannot resolve one. `scopeCovers` matches exactly — no prefix, no wildcard — so holding
35
+ * one confers nothing about the other.
36
+ *
37
+ * The names are constants rather than config: a configurable scope name is a way to misconfigure a
38
+ * default-denied gate into a differently-named one, and they are the join key with what
39
+ * `pithy dashboard connect` offers an adopter to grant.
40
+ */
41
+ /**
42
+ * Page the trail: who acted, what they did, when, against what, and whether it was allowed. The
43
+ * everyday read, and deliberately the one that carries no IP address and no capability metadata.
44
+ */
45
+ export declare const AUDIT_TRAIL_READ_SCOPE: ControlPlaneScope;
46
+ /**
47
+ * Read one event in full — the client IP, the user-agent, and the capability's `metadata` bag with it.
48
+ * The forensic read, and the more dangerous of the two: this is where the trail's personal data is.
49
+ */
50
+ export declare const AUDIT_EVENT_DETAIL_READ_SCOPE: ControlPlaneScope;
51
+ /**
52
+ * Every control-plane scope audit defines — what `pithy dashboard connect` offers for this capability,
53
+ * and the list a manifest or a doc quotes rather than re-typing.
54
+ */
55
+ export declare const AUDIT_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[];
56
+ /**
57
+ * Audit's management surface, as `GET /control-plane/manifest` reports it.
58
+ *
59
+ * Declared beside the scopes so the scope a route demands and the scope a manifest advertises are the
60
+ * same constant, read from one place. `basePath` is a parameter and never a default: an adopter who
61
+ * mounted audit at `/trail` must get a manifest naming `/trail/events`, or a client composing its
62
+ * calls from the manifest would 404 against exactly the adopters who customized anything.
63
+ *
64
+ * The summaries say what the operation is *for*. A client renders these beside a pane somebody is
65
+ * about to open over other people's activity.
66
+ */
67
+ export declare function auditAdminRoutes(basePath: string): AdminRoute[];
68
+ //# sourceMappingURL=guards.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/http/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sDAAsD,CAAC;AACvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAAuC,CAAC;AAE7E;;;GAGG;AACH,eAAO,MAAM,6BAA6B,EAAE,iBAA8C,CAAC;AAE3F;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,iBAAiB,EAGlE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,CAgB/D"}
@@ -0,0 +1,80 @@
1
+ //#region src/http/guards.ts
2
+ /**
3
+ * Audit's control-plane scopes, and the admin surface a manifest advertises.
4
+ *
5
+ * **Every route here is `control-plane`, every route here is a read, and there are no others.** The
6
+ * trail has no end-user surface — a user does not read the record of themselves being audited — so
7
+ * there is nothing for `requireAuth()` to gate, and putting it on these routes would deny every
8
+ * legitimate management call permanently: the seam deliberately leaves `c.var.auth` null for a
9
+ * control-plane caller, and no credential could ever satisfy it. The gate is imported from core
10
+ * rather than copied, because core is a hard dependency of every capability, so importing it cannot
11
+ * leave a deployment without one; with the seam uncomposed `requireControlPlane` raises
12
+ * `controlplane/not_connected` rather than passing.
13
+ *
14
+ * **Nothing here writes.** The trail is append-only by construction and stays that way: there is no
15
+ * delete route, no edit route, and no retention control on this surface. A management credential that
16
+ * could erase an audit row is a management credential that can erase the evidence of its own use.
17
+ *
18
+ * ## Two read scopes, because two reads disclose different things
19
+ *
20
+ * The tempting shape is one `audit:read`. It is wrong on the merits for the same reason a single
21
+ * `payments:admin` flag was: it makes the safe operation and the dangerous one the same grant.
22
+ *
23
+ * A **page of the trail** answers who did what, when, and whether it worked. That is the "recent
24
+ * activity" pane, it is what an operator looks at all day, and its projection carries no network
25
+ * identifier and no capability payload.
26
+ *
27
+ * **One event in full** additionally carries the client IP, the user-agent, and the capability's own
28
+ * `metadata` bag — which routinely holds the email address, the resource name, or the reason a
29
+ * capability recorded alongside its event. Bulk-harvesting those over a whole trail is a privacy
30
+ * incident, and requiring a second scope is what makes it a decision the adopter makes rather than
31
+ * one a listing credential comes with. Since the two are separate routes, a credential holding only
32
+ * the detail scope cannot enumerate the trail to find ids to read, and a credential holding only the
33
+ * list scope cannot resolve one. `scopeCovers` matches exactly — no prefix, no wildcard — so holding
34
+ * one confers nothing about the other.
35
+ *
36
+ * The names are constants rather than config: a configurable scope name is a way to misconfigure a
37
+ * default-denied gate into a differently-named one, and they are the join key with what
38
+ * `pithy dashboard connect` offers an adopter to grant.
39
+ */
40
+ /**
41
+ * Page the trail: who acted, what they did, when, against what, and whether it was allowed. The
42
+ * everyday read, and deliberately the one that carries no IP address and no capability metadata.
43
+ */
44
+ const AUDIT_TRAIL_READ_SCOPE = "audit:events:read";
45
+ /**
46
+ * Read one event in full — the client IP, the user-agent, and the capability's `metadata` bag with it.
47
+ * The forensic read, and the more dangerous of the two: this is where the trail's personal data is.
48
+ */
49
+ const AUDIT_EVENT_DETAIL_READ_SCOPE = "audit:events:read_detail";
50
+ /**
51
+ * Every control-plane scope audit defines — what `pithy dashboard connect` offers for this capability,
52
+ * and the list a manifest or a doc quotes rather than re-typing.
53
+ */
54
+ const AUDIT_CONTROL_PLANE_SCOPES = [AUDIT_TRAIL_READ_SCOPE, AUDIT_EVENT_DETAIL_READ_SCOPE];
55
+ /**
56
+ * Audit's management surface, as `GET /control-plane/manifest` reports it.
57
+ *
58
+ * Declared beside the scopes so the scope a route demands and the scope a manifest advertises are the
59
+ * same constant, read from one place. `basePath` is a parameter and never a default: an adopter who
60
+ * mounted audit at `/trail` must get a manifest naming `/trail/events`, or a client composing its
61
+ * calls from the manifest would 404 against exactly the adopters who customized anything.
62
+ *
63
+ * The summaries say what the operation is *for*. A client renders these beside a pane somebody is
64
+ * about to open over other people's activity.
65
+ */
66
+ function auditAdminRoutes(basePath) {
67
+ return [{
68
+ method: "GET",
69
+ path: `${basePath}/events`,
70
+ scope: AUDIT_TRAIL_READ_SCOPE,
71
+ summary: "Page the trail, newest first, filtered by actor, action, resource, outcome, severity, origin, and time."
72
+ }, {
73
+ method: "GET",
74
+ path: `${basePath}/events/:eventId`,
75
+ scope: AUDIT_EVENT_DETAIL_READ_SCOPE,
76
+ summary: "Read one event in full, including the client IP, user-agent, and capability metadata."
77
+ }];
78
+ }
79
+ //#endregion
80
+ export { AUDIT_CONTROL_PLANE_SCOPES, AUDIT_EVENT_DETAIL_READ_SCOPE, AUDIT_TRAIL_READ_SCOPE, auditAdminRoutes };
@@ -0,0 +1,158 @@
1
+ import { z } from "zod";
2
+ /**
3
+ * One event as the listing shows it — everything but the network identifiers and the metadata bag.
4
+ *
5
+ * The type is derived from this object rather than declared beside it, so a field cannot exist in one
6
+ * and not the other.
7
+ */
8
+ export declare const AuditEventView: z.ZodObject<{
9
+ eventId: z.ZodString;
10
+ occurredAt: z.ZodISODateTime;
11
+ action: z.ZodString;
12
+ outcome: z.ZodEnum<{
13
+ denied: "denied";
14
+ failure: "failure";
15
+ success: "success";
16
+ }>;
17
+ severity: z.ZodEnum<{
18
+ critical: "critical";
19
+ info: "info";
20
+ warning: "warning";
21
+ }>;
22
+ actorType: z.ZodEnum<{
23
+ anonymous: "anonymous";
24
+ "control-plane": "control-plane";
25
+ service: "service";
26
+ system: "system";
27
+ user: "user";
28
+ }>;
29
+ actorId: z.ZodNullable<z.ZodString>;
30
+ sessionId: z.ZodNullable<z.ZodString>;
31
+ resourceType: z.ZodNullable<z.ZodString>;
32
+ resourceId: z.ZodNullable<z.ZodString>;
33
+ requestId: z.ZodNullable<z.ZodString>;
34
+ project: z.ZodNullable<z.ZodString>;
35
+ environment: z.ZodNullable<z.ZodString>;
36
+ worker: z.ZodNullable<z.ZodString>;
37
+ version: z.ZodNullable<z.ZodString>;
38
+ tenant: z.ZodNullable<z.ZodString>;
39
+ }, z.core.$strip>;
40
+ export type AuditEventView = z.output<typeof AuditEventView>;
41
+ /**
42
+ * One event in full — the listing view plus the three fields the detail scope exists to separate.
43
+ *
44
+ * Re-described after `.extend()`: extending builds a new schema, and a description does not follow it.
45
+ */
46
+ export declare const AuditEventDetailView: z.ZodObject<{
47
+ eventId: z.ZodString;
48
+ occurredAt: z.ZodISODateTime;
49
+ action: z.ZodString;
50
+ outcome: z.ZodEnum<{
51
+ denied: "denied";
52
+ failure: "failure";
53
+ success: "success";
54
+ }>;
55
+ severity: z.ZodEnum<{
56
+ critical: "critical";
57
+ info: "info";
58
+ warning: "warning";
59
+ }>;
60
+ actorType: z.ZodEnum<{
61
+ anonymous: "anonymous";
62
+ "control-plane": "control-plane";
63
+ service: "service";
64
+ system: "system";
65
+ user: "user";
66
+ }>;
67
+ actorId: z.ZodNullable<z.ZodString>;
68
+ sessionId: z.ZodNullable<z.ZodString>;
69
+ resourceType: z.ZodNullable<z.ZodString>;
70
+ resourceId: z.ZodNullable<z.ZodString>;
71
+ requestId: z.ZodNullable<z.ZodString>;
72
+ project: z.ZodNullable<z.ZodString>;
73
+ environment: z.ZodNullable<z.ZodString>;
74
+ worker: z.ZodNullable<z.ZodString>;
75
+ version: z.ZodNullable<z.ZodString>;
76
+ tenant: z.ZodNullable<z.ZodString>;
77
+ ip: z.ZodNullable<z.ZodString>;
78
+ userAgent: z.ZodNullable<z.ZodString>;
79
+ metadata: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
80
+ }, z.core.$strip>;
81
+ export type AuditEventDetailView = z.output<typeof AuditEventDetailView>;
82
+ /** `GET {base}/events`. */
83
+ export declare const AuditEventsResponse: z.ZodObject<{
84
+ events: z.ZodArray<z.ZodObject<{
85
+ eventId: z.ZodString;
86
+ occurredAt: z.ZodISODateTime;
87
+ action: z.ZodString;
88
+ outcome: z.ZodEnum<{
89
+ denied: "denied";
90
+ failure: "failure";
91
+ success: "success";
92
+ }>;
93
+ severity: z.ZodEnum<{
94
+ critical: "critical";
95
+ info: "info";
96
+ warning: "warning";
97
+ }>;
98
+ actorType: z.ZodEnum<{
99
+ anonymous: "anonymous";
100
+ "control-plane": "control-plane";
101
+ service: "service";
102
+ system: "system";
103
+ user: "user";
104
+ }>;
105
+ actorId: z.ZodNullable<z.ZodString>;
106
+ sessionId: z.ZodNullable<z.ZodString>;
107
+ resourceType: z.ZodNullable<z.ZodString>;
108
+ resourceId: z.ZodNullable<z.ZodString>;
109
+ requestId: z.ZodNullable<z.ZodString>;
110
+ project: z.ZodNullable<z.ZodString>;
111
+ environment: z.ZodNullable<z.ZodString>;
112
+ worker: z.ZodNullable<z.ZodString>;
113
+ version: z.ZodNullable<z.ZodString>;
114
+ tenant: z.ZodNullable<z.ZodString>;
115
+ }, z.core.$strip>>;
116
+ nextCursor: z.ZodNullable<z.ZodString>;
117
+ }, z.core.$strip>;
118
+ export type AuditEventsResponse = z.output<typeof AuditEventsResponse>;
119
+ /** `GET {base}/events/:eventId`. */
120
+ export declare const AuditEventResponse: z.ZodObject<{
121
+ event: z.ZodObject<{
122
+ eventId: z.ZodString;
123
+ occurredAt: z.ZodISODateTime;
124
+ action: z.ZodString;
125
+ outcome: z.ZodEnum<{
126
+ denied: "denied";
127
+ failure: "failure";
128
+ success: "success";
129
+ }>;
130
+ severity: z.ZodEnum<{
131
+ critical: "critical";
132
+ info: "info";
133
+ warning: "warning";
134
+ }>;
135
+ actorType: z.ZodEnum<{
136
+ anonymous: "anonymous";
137
+ "control-plane": "control-plane";
138
+ service: "service";
139
+ system: "system";
140
+ user: "user";
141
+ }>;
142
+ actorId: z.ZodNullable<z.ZodString>;
143
+ sessionId: z.ZodNullable<z.ZodString>;
144
+ resourceType: z.ZodNullable<z.ZodString>;
145
+ resourceId: z.ZodNullable<z.ZodString>;
146
+ requestId: z.ZodNullable<z.ZodString>;
147
+ project: z.ZodNullable<z.ZodString>;
148
+ environment: z.ZodNullable<z.ZodString>;
149
+ worker: z.ZodNullable<z.ZodString>;
150
+ version: z.ZodNullable<z.ZodString>;
151
+ tenant: z.ZodNullable<z.ZodString>;
152
+ ip: z.ZodNullable<z.ZodString>;
153
+ userAgent: z.ZodNullable<z.ZodString>;
154
+ metadata: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
155
+ }, z.core.$strip>;
156
+ }, z.core.$strip>;
157
+ export type AuditEventResponse = z.output<typeof AuditEventResponse>;
158
+ //# sourceMappingURL=responses.d.ts.map
@@ -0,0 +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"}
@@ -0,0 +1,71 @@
1
+ import { AuditActorType, AuditMetadata, AuditOutcome, AuditSeverity } from "@pithy-sh/core/src/audit/auditEvent";
2
+ import { z } from "zod";
3
+ //#region src/http/responses.ts
4
+ /**
5
+ * What the audit routes return, as Zod objects a management client can validate against.
6
+ *
7
+ * `schemas.ts` bounds what a caller may send; this file states what it gets back. Both halves of the
8
+ * contract are runtime values for the same reason: a client reading a customer's Worker is crossing a
9
+ * trust boundary in *both* directions, and a TypeScript interface is erased before it can help — it
10
+ * cannot check a response, so every client that had only an interface hand-wrote a mirror of it, and
11
+ * the mirror drifted the first time a field landed here.
12
+ *
13
+ * **No codecs, and no transform anywhere in this file.** These schemas describe JSON on the wire, so
14
+ * parsing one must hand back exactly what went in — that is what lets `responses.test.ts` compare the
15
+ * parsed value with the projection's output and fail on a field either side forgot. A `SQLiteDate`
16
+ * here would decode an ISO string into a `Date` and quietly make that comparison meaningless.
17
+ *
18
+ * The projections that fill these live in `views.ts`, which documents *why* each field is in one view
19
+ * and not the other. This file is the shape; that file is the argument.
20
+ *
21
+ * **A field added here later is `.optional()`, not merely `.nullable()`.** This module is read across a
22
+ * version boundary — a management client validates a response with this schema against a customer's
23
+ * Worker at whatever kit version it is on — so an additive required key fails `safeParse` for everyone
24
+ * below that release and takes the whole pane with it (#450). Absent then means *this Worker cannot
25
+ * say*, which is a different fact from `null`.
26
+ */
27
+ /** Where a page resumes, or the end of the list. */
28
+ const NextCursor = z.string().nullable().describe("Where the next page resumes. Null at the end of the list. Opaque — pass it back verbatim.");
29
+ /**
30
+ * One event as the listing shows it — everything but the network identifiers and the metadata bag.
31
+ *
32
+ * The type is derived from this object rather than declared beside it, so a field cannot exist in one
33
+ * and not the other.
34
+ */
35
+ const AuditEventView = z.object({
36
+ eventId: z.string().describe("The event's stable public id (the recorder's UUID)."),
37
+ occurredAt: z.iso.datetime().describe("When it happened, ISO-8601."),
38
+ action: z.string().describe("The `domain/reason` action code."),
39
+ outcome: AuditOutcome.describe("Whether it succeeded, failed, or was denied."),
40
+ severity: AuditSeverity.describe("How serious it is, orthogonal to the outcome."),
41
+ actorType: AuditActorType.describe("The kind of principal that acted."),
42
+ actorId: z.string().nullable().describe("The acting principal's stable id, or null."),
43
+ sessionId: z.string().nullable().describe("The session the action belongs to — a row id, never a token — or null."),
44
+ resourceType: z.string().nullable().describe("The kind of thing acted on, or null."),
45
+ resourceId: z.string().nullable().describe("The thing acted on, or null."),
46
+ requestId: z.string().nullable().describe("The request correlation id, or null."),
47
+ project: z.string().nullable().describe("The project the recorder stamped, or null when it recorded none."),
48
+ environment: z.string().nullable().describe("The environment the recording Worker served, or null."),
49
+ worker: z.string().nullable().describe("The `apps/<name>` Worker that recorded it, or null for a CLI action."),
50
+ version: z.string().nullable().describe("The Cloudflare build id that recorded it, or null."),
51
+ tenant: z.string().nullable().describe("The tenant the action was taken for, or null when it was not tenant-scoped.")
52
+ }).describe("One audit event as the listing shows it. No client IP, no user-agent, no metadata bag.");
53
+ /**
54
+ * One event in full — the listing view plus the three fields the detail scope exists to separate.
55
+ *
56
+ * Re-described after `.extend()`: extending builds a new schema, and a description does not follow it.
57
+ */
58
+ const AuditEventDetailView = AuditEventView.extend({
59
+ ip: z.string().nullable().describe("The client IP the request came from, or null. Personal data; behind its own scope."),
60
+ userAgent: z.string().nullable().describe("The client user-agent, or null. A device fingerprint; behind its own scope."),
61
+ metadata: AuditMetadata.nullable().describe("The capability's own structured detail, or null. Arbitrary payload; behind its own scope.")
62
+ }).describe("One audit event in full — the listing view plus the client IP, user-agent, and metadata bag.");
63
+ /** `GET {base}/events`. */
64
+ const AuditEventsResponse = z.object({
65
+ events: z.array(AuditEventView).describe("The page, newest first."),
66
+ nextCursor: NextCursor
67
+ }).describe("A filtered, resumable page of the audit trail.");
68
+ /** `GET {base}/events/:eventId`. */
69
+ const AuditEventResponse = z.object({ event: AuditEventDetailView.describe("The event, with the fields the detail scope gates.") }).describe("One audit event in full.");
70
+ //#endregion
71
+ export { AuditEventDetailView, AuditEventResponse, AuditEventView, AuditEventsResponse };
@@ -0,0 +1,59 @@
1
+ import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
2
+ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
3
+ import type { VerificationStrategy } from "@pithy-sh/core/src/http/verification";
4
+ import type { Context, Hono } from "hono";
5
+ import type { AuditDatabase } from "../data/tables";
6
+ /**
7
+ * The audit routes, their verification strategies, and what each accepts:
8
+ *
9
+ * GET /audit/events → a page of the trail (control-plane: audit:events:read) query: ListAuditEventsQuery
10
+ * GET /audit/events/:eventId → one event in full (control-plane: audit:events:read_detail) param: AuditEventIdParam
11
+ *
12
+ * **Both are reads, and there is nothing else.** The trail is append-only: no route here deletes,
13
+ * edits, or prunes, because a management credential that could erase an audit row could erase the
14
+ * evidence of its own use. Retention is a lifecycle concern for a Workflow, not a button on a
15
+ * dashboard.
16
+ *
17
+ * **Neither has an end-user surface.** A user does not call the record of themselves being audited,
18
+ * so `requireAuth()` appears nowhere in this file — and must not: the seam leaves `c.var.auth` null
19
+ * for a control-plane caller by design, so an auth gate would deny every legitimate management call
20
+ * permanently, with no credential able to fix it.
21
+ *
22
+ * **Validators sit after the gate on both lines.** A validator ahead of it turns a 403 into a 400 and
23
+ * tells an unverified caller which requests were well-formed — here that is a live oracle for which
24
+ * projects, Workers, and action codes this deployment records.
25
+ */
26
+ /**
27
+ * What every route this capability mounts declares: its path, its strategy, and the scope it checks.
28
+ *
29
+ * Exported so a test asserts against the declaration rather than against a middleware count. Counting
30
+ * `app.routes` entries proves that *something* runs before the handler — a bare `zValidator` satisfies
31
+ * it — and cannot prove *what*. This is a declaration, so it can drift from the router;
32
+ * `routeContract.test.ts` checks it against Hono in both directions, so a route added without an entry
33
+ * and an entry naming no route both fail.
34
+ */
35
+ export interface AuditRouteDeclaration {
36
+ readonly method: "GET";
37
+ /** The path relative to the configured `basePath`, e.g. `/events`. */
38
+ readonly path: string;
39
+ readonly strategy: VerificationStrategy;
40
+ /** The control-plane scope this route checks. */
41
+ readonly scope: ControlPlaneScope;
42
+ }
43
+ /** Every route, and how it is gated. */
44
+ export declare const AUDIT_ROUTES: readonly AuditRouteDeclaration[];
45
+ /** How the audit sub-router is built. */
46
+ export interface AuditRoutesOptions {
47
+ /**
48
+ * The path the routes mount under — **required, with no fallback here**. The default lives in
49
+ * `AuditConfig`, and the capability passes its resolved value to both this and `auditAdminRoutes`,
50
+ * so the mounted path and the advertised path are one value read twice rather than two defaults
51
+ * that can drift apart.
52
+ */
53
+ basePath: string;
54
+ /** The audit database for this request — resolved by the capability, which owns the registry key. */
55
+ database: (c: Context<PithyHonoEnv>) => AuditDatabase;
56
+ }
57
+ /** Register the audit sub-router. Returned as the capability's `routes` hook. */
58
+ export declare function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<PithyHonoEnv>) => void;
59
+ //# sourceMappingURL=routes.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAG7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAGrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAOpD;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IACvB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AAED,wCAAwC;AACxC,eAAO,MAAM,YAAY,EAAE,SAAS,qBAAqB,EAGxD,CAAC;AAEF,yCAAyC;AACzC,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,qGAAqG;IACrG,QAAQ,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,aAAa,CAAC;CACvD;AA2CD,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,kBAAkB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAqFlG"}