@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.
@@ -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,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAsClG;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,CAM/G"}
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"}
@@ -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
  }
@@ -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 `zValidator` satisfies
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":"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"}
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"}
@@ -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 { validationHook } from "@pithy-sh/core/src/http/validation";
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`, requireControlPlane(AUDIT_TRAIL_READ_SCOPE), zValidator("query", ListAuditEventsQuery, validationHook), async (c) => {
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`, requireControlPlane(AUDIT_EVENT_DETAIL_READ_SCOPE), zValidator("param", AuditEventIdParam, validationHook), async (c) => {
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.2.6";
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.2.6";
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.2.6",
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.8.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.0.0",
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.115.0",
58
+ "wrangler": "^4.151.0",
59
59
  "zod": "^4.4.0"
60
60
  }
61
61
  }
@@ -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(apiToken: string, source: CfActorSource): Promise<ResolvedActor> {
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(apiToken: string, source: CfActorSource): () => Promise<ResolvedActor> {
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
  }
@@ -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 { validationHook } from "@pithy-sh/core/src/http/validation";
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 type { AuditEventResponse, AuditEventsResponse } from "./responses";
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 `zValidator` satisfies
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
- zValidator("query", ListAuditEventsQuery, validationHook),
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
- zValidator("param", AuditEventIdParam, validationHook),
188
+ validate("param", AuditEventIdParam),
177
189
  async (c) => {
178
190
  const operator = caller(c);
179
191
  const { eventId } = c.req.valid("param");
@@ -13,4 +13,4 @@
13
13
  export const PACKAGE_NAME = "@pithy-sh/audit";
14
14
 
15
15
  /** This package's version, stamped from its own package.json at generation time. */
16
- export const PACKAGE_VERSION = "0.2.6";
16
+ export const PACKAGE_VERSION = "0.3.0";