@pithy-sh/audit 0.4.0 → 0.6.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.
@@ -1 +1 @@
1
- {"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,0CAA0C,CAAC;AAE7F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAWzC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW;;;iBAc8B,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AACvD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,MAAM,GAAE,gBAAqB,GAAG,eAAe,CA4DpE;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,eAAe,CAEvF"}
1
+ {"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,0CAA0C,CAAC;AAG7F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAWzC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW;;;iBAc8B,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AACvD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,MAAM,GAAE,gBAAqB,GAAG,eAAe,CAgFpE;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,eAAe,CAEvF"}
@@ -1,6 +1,6 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
- import { auditTables } from "./data/tables.js";
3
+ import { auditDatabase, auditTables } from "./data/tables.js";
4
4
  import { auditAdminRoutes } from "./http/guards.js";
5
5
  import { registerAuditRoutes } from "./http/routes.js";
6
6
  import { audit_0001_init } from "./migrations/0001_init.js";
@@ -9,6 +9,7 @@ import { recordAuditEvent } from "./recorder.js";
9
9
  import { auditExampleSeed } from "./seeds/example.js";
10
10
  import { PACKAGE_NAME, PACKAGE_VERSION } from "./version.generated.js";
11
11
  import { defineCapability } from "@pithy-sh/core/src/capability/capability";
12
+ import { createWorkerLogger } from "@pithy-sh/core/src/logger/worker";
12
13
  import { workerIdentity } from "@pithy-sh/core/src/worker/identity";
13
14
  import { z } from "zod";
14
15
  //#region src/capability.ts
@@ -68,6 +69,23 @@ function audit(config = {}) {
68
69
  }
69
70
  } },
70
71
  seeds: [auditExampleSeed],
72
+ auditRecorder: (env) => {
73
+ const log = createWorkerLogger({ name: "audit" });
74
+ const binding = env[resolved.database];
75
+ return async (event) => {
76
+ if (typeof binding !== "object" || binding === null) {
77
+ log.error("audit event dropped", {
78
+ reason: `no ${resolved.database} binding`,
79
+ action: event.action
80
+ });
81
+ return;
82
+ }
83
+ await recordAuditEvent(auditDatabase(binding), event, {
84
+ origin: workerIdentity(env),
85
+ onError: (error) => log.error("audit event dropped", { error })
86
+ });
87
+ };
88
+ },
71
89
  adminRoutes: auditAdminRoutes(resolved.basePath),
72
90
  routes: registerAuditRoutes({
73
91
  basePath: resolved.basePath,
@@ -18,7 +18,7 @@ import { z } from "zod";
18
18
  * on both sides. Exported so the recorder encodes the column through the same codec it is read back
19
19
  * with, rather than hand-rolling `JSON.stringify` (CLAUDE.md §Data layer).
20
20
  */
21
- export declare const AuditMetadataColumn: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
21
+ export declare const AuditMetadataColumn: import("@pithy-sh/core/src/data/codecs").SqliteJson<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
22
22
  export declare const AuditEventRow: z.ZodObject<{
23
23
  id: z.ZodNumber;
24
24
  eventId: z.ZodString;
@@ -53,7 +53,7 @@ export declare const AuditEventRow: z.ZodObject<{
53
53
  ip: z.ZodNullable<z.ZodString>;
54
54
  userAgent: z.ZodNullable<z.ZodString>;
55
55
  requestId: z.ZodNullable<z.ZodString>;
56
- metadata: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
56
+ metadata: z.ZodNullable<import("@pithy-sh/core/src/data/codecs").SqliteJson<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
57
57
  project: z.ZodNullable<z.ZodString>;
58
58
  environment: z.ZodNullable<z.ZodString>;
59
59
  worker: z.ZodNullable<z.ZodString>;
@@ -1 +1 @@
1
- {"version":3,"file":"auditEvent.d.ts","sourceRoot":"","sources":["../../src/data/auditEvent.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;GAWG;AACH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,gIAA4B,CAAC;AAE7D,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuF2F,CAAC;AACtH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC"}
1
+ {"version":3,"file":"auditEvent.d.ts","sourceRoot":"","sources":["../../src/data/auditEvent.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;GAWG;AACH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,6FAA4B,CAAC;AAE7D,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuF2F,CAAC;AACtH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC"}
@@ -43,7 +43,7 @@ export declare const auditTables: {
43
43
  ip: import("zod").ZodNullable<import("zod").ZodString>;
44
44
  userAgent: import("zod").ZodNullable<import("zod").ZodString>;
45
45
  requestId: import("zod").ZodNullable<import("zod").ZodString>;
46
- metadata: import("zod").ZodNullable<import("zod").ZodCodec<import("zod").ZodUnion<readonly [import("zod").ZodString, import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>]>, import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>>;
46
+ metadata: import("zod").ZodNullable<import("@pithy-sh/core/src/data/codecs").SqliteJson<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>>;
47
47
  project: import("zod").ZodNullable<import("zod").ZodString>;
48
48
  environment: import("zod").ZodNullable<import("zod").ZodString>;
49
49
  worker: import("zod").ZodNullable<import("zod").ZodString>;
@@ -2,6 +2,7 @@
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
3
  import { PithyError } from "@pithy-sh/core/src/error/pithyError";
4
4
  import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
5
+ import type { UnmarkedString } from "@pithy-sh/core/src/privacy/types";
5
6
  /**
6
7
  * Audit recorder throw sugar. The `audit/*` codes live in core's closed `KitErrorPayload` union
7
8
  * (CLAUDE.md §Errors: capabilities add their codes to the one union); these subclasses are the
@@ -16,11 +17,11 @@ import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
16
17
  /** Variable parts each subclass accepts; `code`/`status` are fixed by the subclass. */
17
18
  interface AuditErrorArgs {
18
19
  /** Override the public, safe-to-expose message. */
19
- message?: string;
20
+ message?: UnmarkedString;
20
21
  /** A remediation hint (CLI action line). */
21
- action?: string;
22
+ action?: UnmarkedString;
22
23
  /** Internal context for logs + audit. Never serialized to clients. */
23
- detail?: string;
24
+ detail?: UnmarkedString;
24
25
  /**
25
26
  * Values a translating client interpolates into its own wording for this code. Client-facing, so —
26
27
  * unlike `action` and `detail` — these cross the boundary with `message`.
@@ -1 +1 @@
1
- {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/error/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;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"}
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/error/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAEvE;;;;;;;;;;GAUG;AAEH,uFAAuF;AACvF,UAAU,cAAc;IACtB,mDAAmD;IACnD,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,sEAAsE;IACtE,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,wGAAwG;AACxG,qBAAa,sBAAuB,SAAQ,UAAU;IACpD,YAAY,IAAI,GAAE,cAAmB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYnE;CACF;AAED,8FAA8F;AAC9F,qBAAa,qBAAsB,SAAQ,UAAU;IACnD,YAAY,IAAI,GAAE,cAAmB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYnE;CACF"}
@@ -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.4.0";
6
+ export declare const PACKAGE_VERSION = "0.6.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.4.0";
7
+ const PACKAGE_VERSION = "0.6.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.4.0",
3
+ "version": "0.6.0",
4
4
  "license": "FSL-1.1-MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -38,7 +38,7 @@
38
38
  "@hono/zod-validator": "^0.9.0"
39
39
  },
40
40
  "peerDependencies": {
41
- "@pithy-sh/core": "^0.11.0",
41
+ "@pithy-sh/core": "^0.13.0",
42
42
  "hono": "^4.13.2",
43
43
  "kysely": "^0.29.0",
44
44
  "zod": "^4.4.0"
package/src/capability.ts CHANGED
@@ -1,11 +1,14 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: FSL-1.1-MIT
3
3
 
4
+ import type { D1Database } from "@cloudflare/workers-types";
5
+ import type { AuditEventInput } from "@pithy-sh/core/src/audit/auditEvent";
4
6
  import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
7
+ import { createWorkerLogger } from "@pithy-sh/core/src/logger/worker";
5
8
  import { workerIdentity } from "@pithy-sh/core/src/worker/identity";
6
9
  import { z } from "zod";
7
10
  import type { AuditDatabase } from "./data/tables";
8
- import { auditTables } from "./data/tables";
11
+ import { auditDatabase, auditTables } from "./data/tables";
9
12
  import { auditAdminRoutes } from "./http/guards";
10
13
  import { registerAuditRoutes } from "./http/routes";
11
14
  import { audit_0001_init } from "./migrations/0001_init";
@@ -92,6 +95,24 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
92
95
  },
93
96
  },
94
97
  seeds: [auditExampleSeed],
98
+ // The same recorder for code with no request — a Workflow step, which has `env` and nothing else (#622).
99
+ // Built over the binding this config names, stamped with the env's own origin, and non-fatal on the same
100
+ // terms as the middleware's: a missing binding or a failed insert drops the event and logs it, and the
101
+ // step it records stands. Found by core's `composedAuditEmit`, so the step imports nothing from here.
102
+ auditRecorder: (env) => {
103
+ const log = createWorkerLogger({ name: "audit" });
104
+ const binding = env[resolved.database];
105
+ return async (event: AuditEventInput) => {
106
+ if (typeof binding !== "object" || binding === null) {
107
+ log.error("audit event dropped", { reason: `no ${resolved.database} binding`, action: event.action });
108
+ return;
109
+ }
110
+ await recordAuditEvent(auditDatabase(binding as D1Database), event, {
111
+ origin: workerIdentity(env),
112
+ onError: (error) => log.error("audit event dropped", { error }),
113
+ });
114
+ };
115
+ },
95
116
  // Built from the resolved `basePath`, never the default: an adopter who mounts this at `/trail`
96
117
  // gets a manifest naming their paths, where a client assuming the default would 404.
97
118
  adminRoutes: auditAdminRoutes(resolved.basePath),
@@ -115,7 +136,9 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
115
136
  // capability object is built before any request exists, and `env` is only reachable from a
116
137
  // context. `workerIdentity` never throws and returns nulls for whatever is unstamped, so a
117
138
  // Worker predating these vars still records its events — just without an origin.
118
- c.set("emit", (event) =>
139
+ // The parameter is annotated: `AuditEmit` is generic over `metadata` so a call site carrying a
140
+ // privacy-marked value fails to compile (#132), and the recorder is the one place every event lands.
141
+ c.set("emit", (event: AuditEventInput) =>
119
142
  recordAuditEvent(
120
143
  (c.var.db as Record<typeof AUDIT_DATABASE_NAME, AuditDatabase>)[AUDIT_DATABASE_NAME],
121
144
  event,
@@ -3,6 +3,7 @@
3
3
 
4
4
  import { PithyError } from "@pithy-sh/core/src/error/pithyError";
5
5
  import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
6
+ import type { UnmarkedString } from "@pithy-sh/core/src/privacy/types";
6
7
 
7
8
  /**
8
9
  * Audit recorder throw sugar. The `audit/*` codes live in core's closed `KitErrorPayload` union
@@ -19,11 +20,11 @@ import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
19
20
  /** Variable parts each subclass accepts; `code`/`status` are fixed by the subclass. */
20
21
  interface AuditErrorArgs {
21
22
  /** Override the public, safe-to-expose message. */
22
- message?: string;
23
+ message?: UnmarkedString;
23
24
  /** A remediation hint (CLI action line). */
24
- action?: string;
25
+ action?: UnmarkedString;
25
26
  /** Internal context for logs + audit. Never serialized to clients. */
26
- detail?: string;
27
+ detail?: UnmarkedString;
27
28
  /**
28
29
  * Values a translating client interpolates into its own wording for this code. Client-facing, so —
29
30
  * unlike `action` and `detail` — these cross the boundary with `message`.
@@ -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.4.0";
16
+ export const PACKAGE_VERSION = "0.6.0";