@pithy-sh/audit 0.2.6 → 0.3.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/cli/resolveActor.d.ts +12 -2
- package/dist/cli/resolveActor.d.ts.map +1 -1
- package/dist/cli/resolveActor.js +14 -3
- package/dist/http/routes.d.ts +1 -1
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +15 -4
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/package.json +4 -4
- package/src/cli/resolveActor.ts +32 -3
- package/src/http/routes.ts +18 -6
- package/src/version.generated.ts +1 -1
|
@@ -36,6 +36,16 @@ export interface CfActorSource {
|
|
|
36
36
|
/** Account-scoped reads, for a `cfat_*` token. */
|
|
37
37
|
accountTokens: CfAccountTokenActorSource;
|
|
38
38
|
}
|
|
39
|
+
/**
|
|
40
|
+
* What the caller knows about the credential that the token's spelling cannot say.
|
|
41
|
+
*
|
|
42
|
+
* `kind: "session"` is a signed-in Cloudflare session (#759): an OAuth access token, opaque, carrying
|
|
43
|
+
* neither `cfut_` nor `cfat_`. The caller resolved the credential and knows; inferring it from the
|
|
44
|
+
* spelling would make a prefix change at Cloudflare a silent change of actor.
|
|
45
|
+
*/
|
|
46
|
+
export interface ResolveActorOptions {
|
|
47
|
+
kind?: "session";
|
|
48
|
+
}
|
|
39
49
|
/** A resolved CLI actor: who to attribute a control-plane audit event to, plus correlation metadata. */
|
|
40
50
|
export interface ResolvedActor {
|
|
41
51
|
/** The kind of principal. */
|
|
@@ -66,11 +76,11 @@ export interface ResolvedActor {
|
|
|
66
76
|
* Resolution failure — a bad token, a network error, an unrecognized prefix — is **never fatal**: it
|
|
67
77
|
* returns a `system` actor with a `metadata` note, so the event is still written, just unattributed.
|
|
68
78
|
*/
|
|
69
|
-
export declare function resolveActor(apiToken: string, source: CfActorSource): Promise<ResolvedActor>;
|
|
79
|
+
export declare function resolveActor(apiToken: string, source: CfActorSource, options?: ResolveActorOptions): Promise<ResolvedActor>;
|
|
70
80
|
/**
|
|
71
81
|
* A resolver that runs {@link resolveActor} **once** and caches the result for the lifetime of a CLI
|
|
72
82
|
* command — actor identity is resolved at session start, not per event. Memoizes the in-flight
|
|
73
83
|
* promise so concurrent emits share the single resolution.
|
|
74
84
|
*/
|
|
75
|
-
export declare function createCachedActorResolver(apiToken: string, source: CfActorSource): () => Promise<ResolvedActor>;
|
|
85
|
+
export declare function createCachedActorResolver(apiToken: string, source: CfActorSource, options?: ResolveActorOptions): () => Promise<ResolvedActor>;
|
|
76
86
|
//# sourceMappingURL=resolveActor.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"resolveActor.d.ts","sourceRoot":"","sources":["../../src/cli/resolveActor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAGzF,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,OAAO,IAAI,OAAO,CAAC;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,8GAA8G;AAC9G,MAAM,WAAW,yBAAyB;IACxC,oHAAoH;IACpH,WAAW,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,4GAA4G;IAC5G,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACvD;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,IAAI,EAAE,iBAAiB,CAAC;IACxB,kDAAkD;IAClD,aAAa,EAAE,yBAAyB,CAAC;CAC1C;AAED,wGAAwG;AACxG,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,SAAS,EAAE,cAAc,CAAC;IAC1B,gFAAgF;IAChF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iFAAiF;IACjF,QAAQ,EAAE,aAAa,CAAC;CACzB;AAOD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,YAAY,
|
|
1
|
+
{"version":3,"file":"resolveActor.d.ts","sourceRoot":"","sources":["../../src/cli/resolveActor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAGzF,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,OAAO,IAAI,OAAO,CAAC;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,8GAA8G;AAC9G,MAAM,WAAW,yBAAyB;IACxC,oHAAoH;IACpH,WAAW,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,4GAA4G;IAC5G,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACvD;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,IAAI,EAAE,iBAAiB,CAAC;IACxB,kDAAkD;IAClD,aAAa,EAAE,yBAAyB,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED,wGAAwG;AACxG,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,SAAS,EAAE,cAAc,CAAC;IAC1B,gFAAgF;IAChF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iFAAiF;IACjF,QAAQ,EAAE,aAAa,CAAC;CACzB;AAOD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,aAAa,CAAC,CAgDxB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,mBAAwB,GAChC,MAAM,OAAO,CAAC,aAAa,CAAC,CAM9B"}
|
package/dist/cli/resolveActor.js
CHANGED
|
@@ -34,8 +34,19 @@ function systemActor(note) {
|
|
|
34
34
|
* Resolution failure — a bad token, a network error, an unrecognized prefix — is **never fatal**: it
|
|
35
35
|
* returns a `system` actor with a `metadata` note, so the event is still written, just unattributed.
|
|
36
36
|
*/
|
|
37
|
-
async function resolveActor(apiToken, source) {
|
|
37
|
+
async function resolveActor(apiToken, source, options = {}) {
|
|
38
38
|
try {
|
|
39
|
+
if (options.kind === "session") {
|
|
40
|
+
const user = await source.user.getUser();
|
|
41
|
+
return {
|
|
42
|
+
actorType: "user",
|
|
43
|
+
actorId: user.email ?? user.id ?? null,
|
|
44
|
+
metadata: {
|
|
45
|
+
cfTokenType: "session",
|
|
46
|
+
cfUserId: user.id ?? null
|
|
47
|
+
}
|
|
48
|
+
};
|
|
49
|
+
}
|
|
39
50
|
if (apiToken.startsWith("cfut_")) {
|
|
40
51
|
const user = await source.user.getUser();
|
|
41
52
|
return {
|
|
@@ -74,10 +85,10 @@ async function resolveActor(apiToken, source) {
|
|
|
74
85
|
* command — actor identity is resolved at session start, not per event. Memoizes the in-flight
|
|
75
86
|
* promise so concurrent emits share the single resolution.
|
|
76
87
|
*/
|
|
77
|
-
function createCachedActorResolver(apiToken, source) {
|
|
88
|
+
function createCachedActorResolver(apiToken, source, options = {}) {
|
|
78
89
|
let cached;
|
|
79
90
|
return () => {
|
|
80
|
-
cached ??= resolveActor(apiToken, source);
|
|
91
|
+
cached ??= resolveActor(apiToken, source, options);
|
|
81
92
|
return cached;
|
|
82
93
|
};
|
|
83
94
|
}
|
package/dist/http/routes.d.ts
CHANGED
|
@@ -29,7 +29,7 @@ import type { AuditDatabase } from "../data/tables";
|
|
|
29
29
|
* What every route this capability mounts declares: its path, its strategy, and the scope it checks.
|
|
30
30
|
*
|
|
31
31
|
* Exported so a test asserts against the declaration rather than against a middleware count. Counting
|
|
32
|
-
* `app.routes` entries proves that *something* runs before the handler — a bare `
|
|
32
|
+
* `app.routes` entries proves that *something* runs before the handler — a bare `validate` satisfies
|
|
33
33
|
* it — and cannot prove *what*. This is a declaration, so it can drift from the router;
|
|
34
34
|
* `routeContract.test.ts` checks it against Hono in both directions, so a route added without an entry
|
|
35
35
|
* and an entry naming no route both fail.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAG7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAIrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAOpD;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IACvB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AAED,wCAAwC;AACxC,eAAO,MAAM,YAAY,EAAE,SAAS,qBAAqB,EAGxD,CAAC;AAEF,yCAAyC;AACzC,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,qGAAqG;IACrG,QAAQ,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,aAAa,CAAC;CACvD;AA2CD,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,kBAAkB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAiGlG"}
|
package/dist/http/routes.js
CHANGED
|
@@ -3,12 +3,13 @@
|
|
|
3
3
|
import { AuditTrailActions } from "../actions.js";
|
|
4
4
|
import { AUDIT_EVENT_DETAIL_READ_SCOPE, AUDIT_TRAIL_READ_SCOPE } from "./guards.js";
|
|
5
5
|
import { pageAuditEvents, readAuditEvent } from "../query.js";
|
|
6
|
+
import { AuditEventResponse, AuditEventsResponse } from "./responses.js";
|
|
6
7
|
import { AuditEventIdParam, ListAuditEventsQuery } from "./schemas.js";
|
|
7
8
|
import { auditEventDetailView, auditEventView } from "./views.js";
|
|
8
9
|
import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
|
|
9
|
-
import { zValidator } from "@hono/zod-validator";
|
|
10
10
|
import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
|
|
11
|
-
import {
|
|
11
|
+
import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
|
|
12
|
+
import { validate } from "@pithy-sh/core/src/http/validation";
|
|
12
13
|
//#region src/http/routes.ts
|
|
13
14
|
/** Every route, and how it is gated. */
|
|
14
15
|
const AUDIT_ROUTES = [{
|
|
@@ -67,7 +68,12 @@ function registerAuditRoutes(options) {
|
|
|
67
68
|
* CONTROL-PLANE READ. A filtered, resumable page of the trail — keyset, never offset, because the
|
|
68
69
|
* table is appended to while it is being read and an offset page silently skips records.
|
|
69
70
|
*/
|
|
70
|
-
app.get(`${base}/events`,
|
|
71
|
+
app.get(`${base}/events`, describeRoute({
|
|
72
|
+
summary: "Page through the audit trail, newest first.",
|
|
73
|
+
verification: "control-plane",
|
|
74
|
+
scopes: [AUDIT_TRAIL_READ_SCOPE],
|
|
75
|
+
responses: { 200: AuditEventsResponse }
|
|
76
|
+
}), requireControlPlane(AUDIT_TRAIL_READ_SCOPE), validate("query", ListAuditEventsQuery), async (c) => {
|
|
71
77
|
const operator = caller(c);
|
|
72
78
|
const query = c.req.valid("query");
|
|
73
79
|
const page = await pageAuditEvents(database(c), query);
|
|
@@ -96,7 +102,12 @@ function registerAuditRoutes(options) {
|
|
|
96
102
|
* CONTROL-PLANE READ, the forensic one. Returns the client IP, the user-agent, and the capability's
|
|
97
103
|
* metadata bag, which is why it sits behind its own scope rather than the listing's.
|
|
98
104
|
*/
|
|
99
|
-
app.get(`${base}/events/:eventId`,
|
|
105
|
+
app.get(`${base}/events/:eventId`, describeRoute({
|
|
106
|
+
summary: "Read one audit event in full, with its IP, user-agent and metadata.",
|
|
107
|
+
verification: "control-plane",
|
|
108
|
+
scopes: [AUDIT_EVENT_DETAIL_READ_SCOPE],
|
|
109
|
+
responses: { 200: AuditEventResponse }
|
|
110
|
+
}), requireControlPlane(AUDIT_EVENT_DETAIL_READ_SCOPE), validate("param", AuditEventIdParam), async (c) => {
|
|
100
111
|
const operator = caller(c);
|
|
101
112
|
const { eventId } = c.req.valid("param");
|
|
102
113
|
const row = await readAuditEvent(database(c), eventId);
|
|
@@ -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.3.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.3.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.3.0",
|
|
4
4
|
"license": "FSL-1.1-MIT",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -38,13 +38,13 @@
|
|
|
38
38
|
"@hono/zod-validator": "^0.9.0"
|
|
39
39
|
},
|
|
40
40
|
"peerDependencies": {
|
|
41
|
-
"@pithy-sh/core": "^0.
|
|
41
|
+
"@pithy-sh/core": "^0.10.0",
|
|
42
42
|
"hono": "^4.13.2",
|
|
43
43
|
"kysely": "^0.29.0",
|
|
44
44
|
"zod": "^4.4.0"
|
|
45
45
|
},
|
|
46
46
|
"devDependencies": {
|
|
47
|
-
"@cloudflare/vitest-plugin": "^1.
|
|
47
|
+
"@cloudflare/vitest-plugin": "^1.4.2",
|
|
48
48
|
"@pithy-sh/core": "workspace:*",
|
|
49
49
|
"@pithy-sh/tsconfig": "workspace:*",
|
|
50
50
|
"@types/node": "^22.15.0",
|
|
@@ -55,7 +55,7 @@
|
|
|
55
55
|
"tsdown": "^0.23.0",
|
|
56
56
|
"typescript": "^7.0.2",
|
|
57
57
|
"vitest": "^4.1.0",
|
|
58
|
-
"wrangler": "^4.
|
|
58
|
+
"wrangler": "^4.151.0",
|
|
59
59
|
"zod": "^4.4.0"
|
|
60
60
|
}
|
|
61
61
|
}
|
package/src/cli/resolveActor.ts
CHANGED
|
@@ -36,6 +36,17 @@ export interface CfActorSource {
|
|
|
36
36
|
accountTokens: CfAccountTokenActorSource;
|
|
37
37
|
}
|
|
38
38
|
|
|
39
|
+
/**
|
|
40
|
+
* What the caller knows about the credential that the token's spelling cannot say.
|
|
41
|
+
*
|
|
42
|
+
* `kind: "session"` is a signed-in Cloudflare session (#759): an OAuth access token, opaque, carrying
|
|
43
|
+
* neither `cfut_` nor `cfat_`. The caller resolved the credential and knows; inferring it from the
|
|
44
|
+
* spelling would make a prefix change at Cloudflare a silent change of actor.
|
|
45
|
+
*/
|
|
46
|
+
export interface ResolveActorOptions {
|
|
47
|
+
kind?: "session";
|
|
48
|
+
}
|
|
49
|
+
|
|
39
50
|
/** A resolved CLI actor: who to attribute a control-plane audit event to, plus correlation metadata. */
|
|
40
51
|
export interface ResolvedActor {
|
|
41
52
|
/** The kind of principal. */
|
|
@@ -72,8 +83,22 @@ function systemActor(note: string): ResolvedActor {
|
|
|
72
83
|
* Resolution failure — a bad token, a network error, an unrecognized prefix — is **never fatal**: it
|
|
73
84
|
* returns a `system` actor with a `metadata` note, so the event is still written, just unattributed.
|
|
74
85
|
*/
|
|
75
|
-
export async function resolveActor(
|
|
86
|
+
export async function resolveActor(
|
|
87
|
+
apiToken: string,
|
|
88
|
+
source: CfActorSource,
|
|
89
|
+
options: ResolveActorOptions = {},
|
|
90
|
+
): Promise<ResolvedActor> {
|
|
76
91
|
try {
|
|
92
|
+
// A signed-in session names the person through `GET /user`, which `user-details.read` grants (#759).
|
|
93
|
+
// Its access token carries neither prefix, so the caller — which resolved the credential — says so.
|
|
94
|
+
if (options.kind === "session") {
|
|
95
|
+
const user = await source.user.getUser();
|
|
96
|
+
return {
|
|
97
|
+
actorType: "user",
|
|
98
|
+
actorId: user.email ?? user.id ?? null,
|
|
99
|
+
metadata: { cfTokenType: "session", cfUserId: user.id ?? null },
|
|
100
|
+
};
|
|
101
|
+
}
|
|
77
102
|
if (apiToken.startsWith("cfut_")) {
|
|
78
103
|
const user = await source.user.getUser();
|
|
79
104
|
return {
|
|
@@ -117,10 +142,14 @@ export async function resolveActor(apiToken: string, source: CfActorSource): Pro
|
|
|
117
142
|
* command — actor identity is resolved at session start, not per event. Memoizes the in-flight
|
|
118
143
|
* promise so concurrent emits share the single resolution.
|
|
119
144
|
*/
|
|
120
|
-
export function createCachedActorResolver(
|
|
145
|
+
export function createCachedActorResolver(
|
|
146
|
+
apiToken: string,
|
|
147
|
+
source: CfActorSource,
|
|
148
|
+
options: ResolveActorOptions = {},
|
|
149
|
+
): () => Promise<ResolvedActor> {
|
|
121
150
|
let cached: Promise<ResolvedActor> | undefined;
|
|
122
151
|
return () => {
|
|
123
|
-
cached ??= resolveActor(apiToken, source);
|
|
152
|
+
cached ??= resolveActor(apiToken, source, options);
|
|
124
153
|
return cached;
|
|
125
154
|
};
|
|
126
155
|
}
|
package/src/http/routes.ts
CHANGED
|
@@ -1,20 +1,20 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
3
|
|
|
4
|
-
import { zValidator } from "@hono/zod-validator";
|
|
5
4
|
import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
|
|
6
5
|
import type { ControlPlaneContext } from "@pithy-sh/core/src/controlPlane/context";
|
|
7
6
|
import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
|
|
8
7
|
import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
|
|
9
8
|
import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
|
|
10
|
-
import {
|
|
9
|
+
import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
|
|
10
|
+
import { validate } from "@pithy-sh/core/src/http/validation";
|
|
11
11
|
import type { VerificationStrategy } from "@pithy-sh/core/src/http/verification";
|
|
12
12
|
import type { Context, Hono } from "hono";
|
|
13
13
|
import { AuditTrailActions } from "../actions";
|
|
14
14
|
import type { AuditDatabase } from "../data/tables";
|
|
15
15
|
import { pageAuditEvents, readAuditEvent } from "../query";
|
|
16
16
|
import { AUDIT_EVENT_DETAIL_READ_SCOPE, AUDIT_TRAIL_READ_SCOPE } from "./guards";
|
|
17
|
-
import
|
|
17
|
+
import { AuditEventResponse, AuditEventsResponse } from "./responses";
|
|
18
18
|
import { AuditEventIdParam, ListAuditEventsQuery } from "./schemas";
|
|
19
19
|
import { auditEventDetailView, auditEventView } from "./views";
|
|
20
20
|
|
|
@@ -43,7 +43,7 @@ import { auditEventDetailView, auditEventView } from "./views";
|
|
|
43
43
|
* What every route this capability mounts declares: its path, its strategy, and the scope it checks.
|
|
44
44
|
*
|
|
45
45
|
* Exported so a test asserts against the declaration rather than against a middleware count. Counting
|
|
46
|
-
* `app.routes` entries proves that *something* runs before the handler — a bare `
|
|
46
|
+
* `app.routes` entries proves that *something* runs before the handler — a bare `validate` satisfies
|
|
47
47
|
* it — and cannot prove *what*. This is a declaration, so it can drift from the router;
|
|
48
48
|
* `routeContract.test.ts` checks it against Hono in both directions, so a route added without an entry
|
|
49
49
|
* and an entry naming no route both fail.
|
|
@@ -129,8 +129,14 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
129
129
|
*/
|
|
130
130
|
app.get(
|
|
131
131
|
`${base}/events`,
|
|
132
|
+
describeRoute({
|
|
133
|
+
summary: "Page through the audit trail, newest first.",
|
|
134
|
+
verification: "control-plane",
|
|
135
|
+
scopes: [AUDIT_TRAIL_READ_SCOPE],
|
|
136
|
+
responses: { 200: AuditEventsResponse },
|
|
137
|
+
}),
|
|
132
138
|
requireControlPlane(AUDIT_TRAIL_READ_SCOPE),
|
|
133
|
-
|
|
139
|
+
validate("query", ListAuditEventsQuery),
|
|
134
140
|
async (c) => {
|
|
135
141
|
const operator = caller(c);
|
|
136
142
|
const query = c.req.valid("query");
|
|
@@ -172,8 +178,14 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
172
178
|
*/
|
|
173
179
|
app.get(
|
|
174
180
|
`${base}/events/:eventId`,
|
|
181
|
+
describeRoute({
|
|
182
|
+
summary: "Read one audit event in full, with its IP, user-agent and metadata.",
|
|
183
|
+
verification: "control-plane",
|
|
184
|
+
scopes: [AUDIT_EVENT_DETAIL_READ_SCOPE],
|
|
185
|
+
responses: { 200: AuditEventResponse },
|
|
186
|
+
}),
|
|
175
187
|
requireControlPlane(AUDIT_EVENT_DETAIL_READ_SCOPE),
|
|
176
|
-
|
|
188
|
+
validate("param", AuditEventIdParam),
|
|
177
189
|
async (c) => {
|
|
178
190
|
const operator = caller(c);
|
|
179
191
|
const { eventId } = c.req.valid("param");
|
package/src/version.generated.ts
CHANGED