@pithy-sh/audit 0.1.0

package/src/recorder.ts

@@ -0,0 +1,155 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+import { AuditEvent, type AuditEventInput } from "@pithy-sh/core/src/audit/auditEvent";
+import type { AuditEmit } from "@pithy-sh/core/src/audit/recorder";
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { type D1RetryOptions, withD1Retry } from "@pithy-sh/core/src/data/withD1Retry";
+import { messageOf, PithyError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import { AuditMetadataColumn } from "./data/auditEvent";
+import type { AuditDatabase } from "./data/tables";
+import { AuditInvalidEventError, AuditWriteFailedError } from "./error/errors";
+
+/**
+ * The D1-backed audit recorder. `recordAuditEvent` performs a **synchronous, non-fatal** insert: it
+ * awaits a direct `INSERT` into `pithy_audit_events` inside the handler, before the response — so the
+ * event is durably persisted by the time the caller gets a reply — and it **never throws**. A write
+ * failure (or an invalid event) is converted to a namespaced `PithyError` and handed to `onError`
+ * (logged by default), so an audit write can never break the action it records (CLAUDE.md §Security:
+ * audit is a non-blocking side effect).
+ *
+ * The insert is wrapped in {@link withD1Retry} to ride out transient `timeout`/`database-busy` faults
+ * before falling through to the non-fatal drop; its always-on idempotency guard means a retry after a
+ * transport hiccup never double-writes.
+ */
+
+/**
+ * Where the recording happened — the origin columns, supplied to the **recorder**, never by an
+ * emitter.
+ *
+ * This is deliberately not a field on `AuditEvent`. Origin is a property of the *writer*, not of the
+ * action, and putting it on the event seam would make it caller-settable: any of the ~40 `c.var.emit`
+ * sites could then claim to be another Worker, another environment, or another project, and the column
+ * would be worth nothing precisely when it mattered. Binding it here means an emitter cannot set it,
+ * cannot omit it, and cannot get it wrong.
+ *
+ * Every field is nullable because every field is genuinely unknowable in some real case: a Worker
+ * scaffolded before the vars existed carries none of them, and `worker` is always null for a
+ * CLI-originated action, which came from no Worker at all.
+ *
+ * **`tenant` is deliberately not here.** It is the mirror image of these: whose action it was is a
+ * property of the *action*, not of the writer, and no `env` var can know it — so it lives on
+ * `AuditEvent`, comes from the emitter, and this recorder can neither default it nor check it. That is
+ * the honest trade. Putting it here would mean stamping every row in a multi-tenant Worker with one
+ * constant, which is precisely the gap the column exists to close.
+ */
+export interface AuditOrigin {
+  /** The owning project, from the Worker's `PROJECT` var or the CLI's resolved project name. */
+  project: string | null;
+  /** The environment served, from `ENVIRONMENT` or the command's `--env`. */
+  environment: string | null;
+  /** The recording Worker's `apps/<name>` directory name; null for a CLI action. */
+  worker: string | null;
+  /**
+   * The Cloudflare version id of the build recording the event, from `CF_VERSION_METADATA`; null for a
+   * CLI action and for a Worker that does not declare the binding.
+   *
+   * Required-but-nullable rather than optional, deliberately: making it optional would let a
+   * construction site forget it and silently record null, and there are three of them — this recorder,
+   * `emitFromCLI`, and the CLI's own `cliOrigin()`. A required field makes the compiler find all three.
+   */
+  version: string | null;
+}
+
+/** No origin established — what an unstamped Worker and an un-migrated caller both record. */
+const NO_ORIGIN: AuditOrigin = { project: null, environment: null, worker: null, version: null };
+
+/** Options for the recorder. All optional; the defaults route failures to a sink and retry transient D1 faults. */
+export interface AuditRecorderOptions {
+  /**
+   * Where this recorder is writing from, stamped onto every event it records. Omitted, the three
+   * columns are `null` — the same shape as a row written before they existed, which is the truthful
+   * answer rather than a guess.
+   */
+  origin?: AuditOrigin;
+  /**
+   * Called with the namespaced failure when an event can't be validated or persisted. The audit write
+   * is non-fatal, so this is the only signal a drop happened. The audit capability wires it to the core
+   * logger seam (`c.var.log.error(...)`); when omitted the failure is dropped silently — pass a sink.
+   */
+  onError?: (error: PithyError) => void;
+  /** Retry tuning for the insert. Defaults to retrying `timeout` and `database-busy`. */
+  retry?: D1RetryOptions;
+}
+
+/** Map any caught failure to its namespaced audit `PithyError`. A bad event is `invalid_event`; anything else is `write_failed`. */
+function toAuditError(error: unknown): PithyError {
+  if (error instanceof PithyError) return error;
+  if (error instanceof z.ZodError) {
+    return new AuditInvalidEventError({ detail: error.message }, { cause: error });
+  }
+  return new AuditWriteFailedError({ detail: messageOf(error) }, { cause: error });
+}
+
+/**
+ * Record one audit event. Validates the event against the core {@link AuditEvent} seam, stamps
+ * `occurredAt` when the emitter did not, encodes every column through its codec, and inserts the row
+ * — all wrapped so no failure escapes. Returns when the event is persisted (or its failure logged).
+ */
+export async function recordAuditEvent(
+  db: AuditDatabase,
+  input: AuditEventInput,
+  options?: AuditRecorderOptions,
+): Promise<void> {
+  const onError = options?.onError ?? (() => {});
+  const origin = options?.origin ?? NO_ORIGIN;
+  try {
+    const event = AuditEvent.parse(input);
+    const occurredAt = event.occurredAt ?? new Date();
+    // Generated once, before the retry wrapper, so every retry of this one record reuses it. A
+    // post-commit transport failure then retries onto the unique eventId index — a UNIQUE violation
+    // the guard reads as "already landed", not a duplicate row.
+    const eventId = crypto.randomUUID();
+    await withD1Retry(
+      () =>
+        db
+          .insertInto("pithyAuditEvents")
+          .values({
+            eventId,
+            occurredAt: SQLiteDate.encode(occurredAt),
+            action: event.action,
+            outcome: event.outcome,
+            severity: event.severity,
+            actorType: event.actorType,
+            actorId: event.actorId ?? null,
+            sessionId: event.sessionId ?? null,
+            resourceType: event.resourceType ?? null,
+            resourceId: event.resourceId ?? null,
+            ip: event.ip ?? null,
+            userAgent: event.userAgent ?? null,
+            requestId: event.requestId ?? null,
+            metadata: event.metadata == null ? null : AuditMetadataColumn.encode(event.metadata),
+            // From `event`, and it is the only dimension column that is. The recorder cannot forge this
+            // one and cannot default it: `origin` is read from the Worker's own vars, and no var knows
+            // which customer an action was taken for. So it is exactly as trustworthy as the emit site,
+            // and omitted it is null — "not tenant-scoped" — rather than a guess.
+            tenant: event.tenant ?? null,
+            // Last, and from `options` rather than `event` — the event cannot reach these columns.
+            project: origin.project,
+            environment: origin.environment,
+            worker: origin.worker,
+            version: origin.version,
+          })
+          .execute(),
+      options?.retry,
+    );
+  } catch (error) {
+    onError(toAuditError(error));
+  }
+}
+
+/** Bind a recorder to one audit database — the `emit` seam `@pithy-sh/audit` installs on the request context. */
+export function createAuditEmit(db: AuditDatabase, options?: AuditRecorderOptions): AuditEmit {
+  return (input) => recordAuditEvent(db, input, options);
+}

package/src/seeds/example.ts

@@ -0,0 +1,189 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+import { EXAMPLE_ADA, EXAMPLE_ALAN, EXAMPLE_GRACE } from "@pithy-sh/core/src/seed/exampleIdentities";
+import { d1SeedGroup, defineSeed, type SeedSet } from "@pithy-sh/core/src/seed/seed";
+import { AuditEventRow } from "../data/auditEvent";
+
+/**
+ * Where the audit example set sorts in the project's seed registry. It runs after `auth` (100), whose
+ * example seeds the users these events are attributed to, so every `actorId`/`resourceId` here points
+ * at a user that already exists.
+ */
+const AUDIT_EXAMPLE_SEED_ORDER = 150;
+
+/**
+ * A short, realistic timeline ending "now", so the seeded events land across a dashboard's recency and
+ * time-range views instead of all sharing one timestamp.
+ */
+const minutesAgo = (minutes: number): Date => new Date(Date.now() - minutes * 60_000);
+
+/**
+ * The origin every example row carries — so a dev database looks like a real one, and the origin
+ * filters have something to return.
+ *
+ * `project` and `worker` are fixture constants in this file's own `example-` idiom: fictional, obviously
+ * so, and stable. **`environment` is null, and that asymmetry is deliberate.** A seed row is a static
+ * literal, but this set runs in both `dev` and `staging` (`environments` below) and nothing rewrites a
+ * row per run — so any environment written here would be a lie in half the runs it appears in. The other
+ * two are properties of the fiction; the environment is a property of the run, and the fixture does not
+ * know it. Null is what "not recorded" looks like everywhere else in this column, which is also the
+ * state of every row written before the origin migration.
+ */
+const EXAMPLE_ORIGIN = { project: "example-app", environment: null, worker: "api", version: null } as const;
+
+/**
+ * Two fictional tenants, so a dev database can show what the tenant filter is for.
+ *
+ * **Ada's events are split across both**, deliberately: one person administering two accounts is the
+ * case `actorId` cannot answer, and a fixture where every actor sat in exactly one tenant would make
+ * the column look redundant. One row is left with no tenant at all — null is a value, not a gap. It is
+ * the shape every row in a single-tenant app has, and it gives the "belongs to no tenant" filter
+ * something to return.
+ */
+const EXAMPLE_TENANT_ACME = "example-tenant-acme";
+const EXAMPLE_TENANT_GLOBEX = "example-tenant-globex";
+
+/**
+ * A handful of example audit events — the durable, queryable trail the licensed dashboard reads. They
+ * are attributed to the shared cast from `@pithy-sh/core` ({@link EXAMPLE_ADA} et al.), so the audit
+ * trail lines up with the same users `auth` seeds and `leaderboard`/`ledger`/`multiplayer` reference:
+ * a fresh backend with `seed.includeExamples` on has a dashboard with something to show.
+ *
+ * The set is deliberately spread across the taxonomy the dashboard filters on — every `outcome`
+ * (`success`/`failure`/`denied`), a range of `severity` (`info`→`critical`), and both `user` and
+ * `system` actors — and across the domains that matter to a licensed product (`auth`, `entitlement`,
+ * `admin`, `ledger`): a successful sign-in, a denied one, an entitlement grant, an admin config change,
+ * a critical token-reuse alert, and a balance debit. Composed only when the project turns on
+ * `seed.includeExamples`, and only for `dev`/`staging` — an example fixture never targets production.
+ */
+export const auditExampleSeed: SeedSet = defineSeed({
+  name: "example",
+  order: AUDIT_EXAMPLE_SEED_ORDER,
+  environments: ["dev", "staging"],
+  example: true,
+  d1: [
+    d1SeedGroup("app", "pithyAuditEvents", AuditEventRow, [
+      {
+        id: 1,
+        eventId: "example-audit-0001",
+        occurredAt: minutesAgo(90),
+        action: "auth/login",
+        outcome: "success",
+        severity: "info",
+        actorType: "user",
+        actorId: EXAMPLE_ADA.id,
+        sessionId: "example-session-ada",
+        resourceType: null,
+        resourceId: null,
+        ip: "203.0.113.10",
+        userAgent: "PithyDemo/1.0 (dev seed)",
+        requestId: "example-req-0001",
+        metadata: { method: "magic_link" },
+        tenant: EXAMPLE_TENANT_ACME,
+        ...EXAMPLE_ORIGIN,
+      },
+      {
+        id: 2,
+        eventId: "example-audit-0002",
+        occurredAt: minutesAgo(75),
+        action: "auth/login",
+        outcome: "denied",
+        severity: "warning",
+        actorType: "user",
+        actorId: EXAMPLE_GRACE.id,
+        sessionId: null,
+        resourceType: null,
+        resourceId: null,
+        ip: "203.0.113.22",
+        userAgent: "PithyDemo/1.0 (dev seed)",
+        requestId: "example-req-0002",
+        metadata: { reason: "expired_link" },
+        tenant: EXAMPLE_TENANT_GLOBEX,
+        ...EXAMPLE_ORIGIN,
+      },
+      {
+        id: 3,
+        eventId: "example-audit-0003",
+        occurredAt: minutesAgo(60),
+        action: "entitlement/granted",
+        outcome: "success",
+        severity: "info",
+        actorType: "system",
+        actorId: null,
+        sessionId: null,
+        // The two halves of a payments subject, spelled in the two columns the trail already had:
+        // `resourceType` is the kind (`user` or `organization` — `PaymentsSubjectType`) and `resourceId`
+        // is its id. An entitlement is held by a subject, never by a bare id, so a row naming only the
+        // id would be as ambiguous here as it would be in the table it describes.
+        resourceType: "user",
+        resourceId: EXAMPLE_ALAN.id,
+        ip: null,
+        userAgent: null,
+        requestId: "example-req-0003",
+        metadata: { plan: "pro", grantedBy: "system" },
+        tenant: EXAMPLE_TENANT_ACME,
+        ...EXAMPLE_ORIGIN,
+      },
+      {
+        id: 4,
+        eventId: "example-audit-0004",
+        occurredAt: minutesAgo(40),
+        action: "admin/config_changed",
+        outcome: "success",
+        severity: "warning",
+        actorType: "user",
+        actorId: EXAMPLE_ADA.id,
+        sessionId: "example-session-ada",
+        resourceType: "config",
+        resourceId: "billing",
+        ip: "203.0.113.10",
+        userAgent: "PithyDemo/1.0 (dev seed)",
+        requestId: "example-req-0004",
+        metadata: { field: "seatLimit", from: 5, to: 10 },
+        // The same actor as event 1, in the other tenant — what `actorId` alone cannot tell apart.
+        tenant: EXAMPLE_TENANT_GLOBEX,
+        ...EXAMPLE_ORIGIN,
+      },
+      {
+        id: 5,
+        eventId: "example-audit-0005",
+        occurredAt: minutesAgo(20),
+        action: "auth/token_reuse_detected",
+        outcome: "denied",
+        severity: "critical",
+        actorType: "user",
+        actorId: EXAMPLE_GRACE.id,
+        sessionId: null,
+        resourceType: "session",
+        resourceId: "example-family-grace",
+        ip: "198.51.100.7",
+        userAgent: "curl/8.4.0",
+        requestId: "example-req-0005",
+        metadata: { familyId: "example-family-grace", action: "family_revoked" },
+        tenant: EXAMPLE_TENANT_GLOBEX,
+        ...EXAMPLE_ORIGIN,
+      },
+      {
+        id: 6,
+        eventId: "example-audit-0006",
+        occurredAt: minutesAgo(5),
+        action: "ledger/debit",
+        outcome: "success",
+        severity: "info",
+        actorType: "user",
+        actorId: EXAMPLE_ALAN.id,
+        sessionId: "example-session-alan",
+        resourceType: "ledger",
+        resourceId: "coins",
+        ip: "203.0.113.31",
+        userAgent: "PithyDemo/1.0 (dev seed)",
+        requestId: "example-req-0006",
+        metadata: { amount: 50, currency: "coins" },
+        // No tenant, on purpose: the shape every row in a single-tenant app has.
+        tenant: null,
+        ...EXAMPLE_ORIGIN,
+      },
+    ]),
+  ],
+});

package/src/version.generated.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+// GENERATED by scripts/stampVersions.ts — do not edit by hand. Regenerate with `bun run stamp-versions`.
+//
+// A Worker cannot read its own package.json, so this is how @pithy-sh/audit knows its own version at
+// runtime. The capability attaches it, and `GET /control-plane/manifest` reports it per capability —
+// which is what answers "should this project upgrade" and "is this customer exposed to what we just
+// fixed". Those questions are only answerable per module, because a project composes some capabilities
+// and not others.
+
+/** This package's npm name — the join key against a release feed. */
+export const PACKAGE_NAME = "@pithy-sh/audit";
+
+/** This package's version, stamped from its own package.json at generation time. */
+export const PACKAGE_VERSION = "0.1.0";