@pithy-sh/audit 0.1.1 → 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.
- package/dist/actions.d.ts +41 -0
- package/dist/actions.d.ts.map +1 -0
- package/dist/actions.js +55 -0
- package/dist/capability.d.ts +40 -0
- package/dist/capability.d.ts.map +1 -0
- package/dist/capability.js +86 -0
- package/dist/cli/emitFromCLI.d.ts +35 -0
- package/dist/cli/emitFromCLI.d.ts.map +1 -0
- package/dist/cli/emitFromCLI.js +37 -0
- package/dist/cli/resolveActor.d.ts +74 -0
- package/dist/cli/resolveActor.d.ts.map +1 -0
- package/dist/cli/resolveActor.js +83 -0
- package/dist/data/auditEvent.d.ts +57 -0
- package/dist/data/auditEvent.d.ts.map +1 -0
- package/dist/data/auditEvent.js +46 -0
- package/dist/data/tables.d.ts +52 -0
- package/dist/data/tables.d.ts.map +1 -0
- package/dist/data/tables.js +15 -0
- package/dist/error/errors.d.ts +41 -0
- package/dist/error/errors.d.ts.map +1 -0
- package/dist/error/errors.js +30 -0
- package/dist/http/guards.d.ts +68 -0
- package/dist/http/guards.d.ts.map +1 -0
- package/dist/http/guards.js +80 -0
- package/dist/http/responses.d.ts +158 -0
- package/dist/http/responses.d.ts.map +1 -0
- package/dist/http/responses.js +71 -0
- package/dist/http/routes.d.ts +59 -0
- package/dist/http/routes.d.ts.map +1 -0
- package/dist/http/routes.js +125 -0
- package/dist/http/schemas.d.ts +45 -0
- package/dist/http/schemas.d.ts.map +1 -0
- package/dist/http/schemas.js +68 -0
- package/dist/http/views.d.ts +53 -0
- package/dist/http/views.d.ts.map +1 -0
- package/dist/http/views.js +79 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +10 -0
- package/dist/migrations/0001_init.d.ts +19 -0
- package/dist/migrations/0001_init.d.ts.map +1 -0
- package/dist/migrations/0001_init.js +45 -0
- package/dist/query.d.ts +103 -0
- package/dist/query.d.ts.map +1 -0
- package/dist/query.js +95 -0
- package/dist/recorder.d.ts +80 -0
- package/dist/recorder.d.ts.map +1 -0
- package/dist/recorder.js +64 -0
- package/dist/seeds/example.d.ts +16 -0
- package/dist/seeds/example.d.ts.map +1 -0
- package/dist/seeds/example.js +194 -0
- package/dist/version.generated.d.ts +5 -0
- package/dist/version.generated.d.ts.map +1 -0
- package/dist/version.generated.js +7 -0
- package/package.json +21 -10
- 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"}
|