@pithy-sh/audit 0.1.0

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Pithy
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT License that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT License, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+the Software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @pithy-sh/audit
+
+A queryable audit trail for Pithy. Records security-relevant actions — logins, token refreshes, entitlement grants, admin config changes — as durable rows in your own D1, attributed to the right actor.
+
+Better Auth ships no audit plugin, so Pithy owns this.
+
+```sh
+pithy add audit
+```
+
+**Documentation: [pithy.sh/docs/capabilities/audit](https://pithy.sh/docs/capabilities/audit).** Overview, adding it, using it, and the reference: the event model, actors, querying, retention.
+
+_Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes there, not here._
+
+## License
+
+`FSL-1.1-MIT` (Functional Source License). Use it freely for any purpose except a competing product; it converts to MIT two years after each release. The audit trail feeds the premium dashboard, so it starts more restrictive than the MIT core capabilities (CLAUDE.md §Packaging). See `LICENSE`.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@pithy-sh/audit",
+  "version": "0.1.0",
+  "license": "FSL-1.1-MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/audit"
+  },
+  "files": [
+    "src",
+    "pithy.manifest.json",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project=node",
+    "test:workers": "vitest run --project=workers",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "@hono/zod-validator": "^0.9.0",
+    "@pithy-sh/cloudflare": "workspace:*",
+    "@pithy-sh/core": "workspace:*",
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@pithy-sh/tsconfig": "workspace:*",
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "kysely-d1": "^0.4.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.115.0"
+  }
+}

package/pithy.manifest.json

@@ -0,0 +1,19 @@
+{
+  "name": "audit",
+  "package": "@pithy-sh/audit",
+  "requiredBindings": [{ "type": "d1", "name": "DB" }],
+  "migrationNamespace": "audit",
+  "whenToEnable": "A queryable, tamper-resistant audit trail of security-relevant actions — logins, token refreshes, entitlement grants, admin config changes. Records who did what, when, and whether it succeeded, attributed to the right actor. Other capabilities emit through the core seam; auth needs it the moment it lands.",
+  "configOptions": [
+    {
+      "key": "database",
+      "default": "DB",
+      "describe": "The D1 binding the audit table and its migrations target. Defaults to `DB`, the shared app database. KV is not an option — an audit log is a query workload, not a key lookup."
+    },
+    {
+      "key": "basePath",
+      "default": "/audit",
+      "describe": "Where the control-plane routes that read the trail mount. Reads only — the trail is append-only and this surface never writes."
+    }
+  ]
+}

package/src/actions.ts

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+import { AuditAction } from "@pithy-sh/core/src/audit/auditEvent";
+import { AuditInvalidEventError } from "./error/errors";
+
+/**
+ * Author a capability's action constants. The taxonomy is **federated**: each capability owns and
+ * exports its own `domain/reason` action codes (`auth/login`, `entitlement/granted`) and adds them
+ * without touching core — the way migrations and table prefixes already federate per-capability.
+ *
+ * This validates every code against the shared {@link AuditAction} shape at author time, so a typo
+ * (a missing slash, an uppercase letter) fails loudly where the constant is declared rather than
+ * silently when an event is emitted. Returns the same object, typed, so call sites read
+ * `AuthAuditActions.login`:
+ *
+ * ```ts
+ * export const AuthAuditActions = defineAuditActions({
+ *   login: "auth/login",
+ *   tokenRefreshed: "auth/token_refreshed",
+ * });
+ * ```
+ */
+export function defineAuditActions<const T extends Record<string, string>>(actions: T): T {
+  for (const [name, code] of Object.entries(actions)) {
+    const parsed = AuditAction.safeParse(code);
+    if (!parsed.success) {
+      throw new AuditInvalidEventError({
+        message: `Invalid audit action code for "${name}": ${code}`,
+        action: "Use a lowercase namespaced `domain/reason` code, e.g. `auth/login`.",
+        detail: parsed.error.message,
+      });
+    }
+  }
+  return actions;
+}
+
+/**
+ * This capability's own action codes — the trail recording the reads of itself.
+ *
+ * **Reading an audit trail is a security-relevant action.** It is the record of who did what across
+ * every other capability, so a management client paging through it is doing something that has to be
+ * answerable later; a trail that records every write and no read cannot answer "who looked".
+ *
+ * They are separate codes rather than one, because the two reads disclose different things and a
+ * reviewer filtering the trail should not have to inspect metadata to tell them apart:
+ * `audit/trail_read` is a filtered page of structural fields, while `audit/event_read` is the full
+ * record of one event — the IP, the user-agent, and the capability metadata included.
+ *
+ * Yes, this appends to the table it just read. That is a loop by design, not by accident: the row it
+ * writes is one row, it is the only durable evidence the read happened, and the alternative is a
+ * surface that quietly exempts itself from the guarantee it exists to provide.
+ */
+export const AuditTrailActions = defineAuditActions({
+  /** A filtered page of the trail was read. */
+  trailRead: "audit/trail_read",
+  /** One event was read in full, network identifiers and metadata included. */
+  eventRead: "audit/event_read",
+});

package/src/capability.ts

@@ -0,0 +1,135 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
+import { workerIdentity } from "@pithy-sh/core/src/worker/identity";
+import { z } from "zod";
+import type { AuditDatabase } from "./data/tables";
+import { auditTables } from "./data/tables";
+import { auditAdminRoutes } from "./http/guards";
+import { registerAuditRoutes } from "./http/routes";
+import { audit_0001_init } from "./migrations/0001_init";
+import { recordAuditEvent } from "./recorder";
+import { auditExampleSeed } from "./seeds/example";
+import { PACKAGE_VERSION } from "./version.generated";
+
+/**
+ * Sort order of the audit migration within the audit database, relative to other capabilities
+ * (core low, app high). Unique per database; the migration registry composes the key
+ * `0250_audit_0001_init`.
+ */
+export const AUDIT_MIGRATION_ORDER = 250;
+
+/**
+ * The registry name the audit table joins. The store of record is D1, shared with the primary app
+ * database (`app`, the `DB` binding) by default — so the audit migration tracks alongside the app's
+ * in one `pithy_migrations` table rather than fighting it on a second provider over the same binding.
+ * The physical binding is config-selectable; this registry key is the coordination point capabilities
+ * use to share one database (CLAUDE.md §Data layer; isolating audit into its own D1 is a later issue).
+ */
+const AUDIT_DATABASE_NAME = "app" as const;
+
+/**
+ * Configuration for the audit capability, passed in `pithy.config.ts`. `database` names the D1
+ * **binding** the audit table lives in and writes go to, defaulting to `DB` (the shared app
+ * database). KV is deliberately not an option: an audit log is a query workload (by actor, action,
+ * time range, resource, outcome) and KV is get-by-key only.
+ *
+ * `basePath` is where the read-only control-plane routes mount. It is config rather than a constant
+ * for the reason every capability's is: an adopter may already own `/audit`, and the admin manifest
+ * reports whatever they chose, so a management client follows the move without either side
+ * coordinating.
+ */
+export const AuditConfig = z
+  .object({
+    database: z
+      .string()
+      .default("DB")
+      .describe("The D1 binding the audit table and its migrations target. Defaults to `DB`, the shared app database."),
+    basePath: z
+      .string()
+      .startsWith("/")
+      .default("/audit")
+      .describe(
+        "Where the control-plane routes that read the trail mount. Reads only — the trail is append-only and this surface never writes.",
+      ),
+  })
+  .describe("Configuration for the audit capability.");
+export type AuditConfig = z.output<typeof AuditConfig>;
+export type AuditConfigInput = z.input<typeof AuditConfig>;
+
+/** The audit capability, with its resolved binding attached for discovery. */
+export interface AuditCapability extends Capability {
+  /** The D1 binding the audit table lives in (the resolved `database` config). */
+  auditDatabase: string;
+}
+
+/**
+ * The audit capability. It contributes the `pithy_audit_events` table to the configured D1 binding
+ * (default `DB`) and installs the request-context `emit()` recorder via middleware — replacing core's
+ * no-op with a synchronous, non-fatal D1 writer. Any capability then records a security-relevant
+ * action with `c.var.emit(...)` without importing this package (principle 4).
+ */
+export function audit(config: AuditConfigInput = {}): AuditCapability {
+  const resolved = AuditConfig.parse(config);
+  const capability = defineCapability({
+    name: "audit",
+    // The package version this capability ships at, stamped by `scripts/stampVersions.ts` — a Worker
+    // cannot read its own package.json. Reported per capability by the control-plane manifest.
+    version: PACKAGE_VERSION,
+    config: AuditConfig,
+    requiredBindings: [{ type: "d1", name: resolved.database }],
+    databases: {
+      [AUDIT_DATABASE_NAME]: {
+        binding: resolved.database,
+        tables: auditTables,
+        migrationOrder: AUDIT_MIGRATION_ORDER,
+        migrations: { "0001_init": audit_0001_init },
+      },
+    },
+    seeds: [auditExampleSeed],
+    // Built from the resolved `basePath`, never the default: an adopter who mounts this at `/trail`
+    // gets a manifest naming their paths, where a client assuming the default would 404.
+    adminRoutes: auditAdminRoutes(resolved.basePath),
+    // The registry key is this package's own detail, so the routes are handed a resolver rather than
+    // being made to know it — the same reason the middleware below resolves lazily.
+    routes: registerAuditRoutes({
+      basePath: resolved.basePath,
+      database: (c) => (c.var.db as Record<typeof AUDIT_DATABASE_NAME, AuditDatabase>)[AUDIT_DATABASE_NAME],
+    }),
+    // Replace the no-op `emit` seam with a recorder over this request's audit database. The database
+    // is resolved lazily inside the closure — only when a route actually emits — so a request that
+    // never audits never triggers the lazy Kysely build. Runs after createBackend's default-setter
+    // (which seeds `db`, `log`, and the no-op `emit`), so `c.var.db` and `c.var.log` are ready by the
+    // time emit is called. A non-fatal write failure routes through the logger seam — replacing the
+    // former `console.error` stopgap — as a namespaced `audit/*` record on the `audit` sub-logger.
+    middleware: [
+      (app) => {
+        app.use("*", async (c, next) => {
+          // Origin is read from `c.env` here and handed to the recorder, so no emitter supplies it and
+          // none can override it. Read per request rather than once at capability construction: the
+          // capability object is built before any request exists, and `env` is only reachable from a
+          // context. `workerIdentity` never throws and returns nulls for whatever is unstamped, so a
+          // Worker predating these vars still records its events — just without an origin.
+          c.set("emit", (event) =>
+            recordAuditEvent(
+              (c.var.db as Record<typeof AUDIT_DATABASE_NAME, AuditDatabase>)[AUDIT_DATABASE_NAME],
+              event,
+              {
+                origin: workerIdentity(c.env),
+                onError: (error) => c.var.log.child("audit").error("audit event dropped", { error }),
+              },
+            ),
+          );
+          await next();
+        });
+      },
+    ],
+  });
+  return Object.assign(capability, { auditDatabase: resolved.database });
+}
+
+/** Whether a capability is the audit capability — carries its resolved binding. */
+export function isAuditCapability(capability: Capability): capability is AuditCapability {
+  return capability.name === "audit" && "auditDatabase" in capability;
+}

package/src/cli/emitFromCLI.ts

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import type { AuditEventInput } from "@pithy-sh/core/src/audit/auditEvent";
+import { auditDatabase } from "../data/tables";
+import { type AuditRecorderOptions, recordAuditEvent } from "../recorder";
+import type { ResolvedActor } from "./resolveActor";
+
+/**
+ * The event an `emitFromCLI` caller supplies — every audit field except the actor, which comes from
+ * {@link ResolvedActor} (resolved from the CF token, not the caller). The CLI describes *what*
+ * happened; the resolver decides *who*.
+ *
+ * Plus `environment`, which the CLI alone may state per event. In a Worker the origin is read from
+ * `env` and an emitter can never touch it — there the emitter is a request handler and the whole point
+ * is that it cannot lie. A CLI command is not that: it *is* the trusted process, there is no untrusted
+ * caller in it, and one invocation legitimately acts on several environments — `pithy storage provision`
+ * loops every managed environment in a single run. Nothing else knows which one a given event belongs
+ * to, so the event carries it.
+ */
+export type CliAuditEvent = Omit<AuditEventInput, "actorType" | "actorId"> & {
+  /**
+   * The environment this one event acted on. Overrides the emitter's configured origin environment;
+   * omitted, the configured one stands.
+   */
+  environment?: string | null;
+};
+
+/**
+ * Record an audit event from a Node/Bun context — the second emit path, for CLI-originated actions
+ * (`pithy migrate`, `pithy deploy`, `pithy secrets set`). The CLI can't use a D1 binding, so it
+ * writes over the REST API: `d1` is a `CloudflareD1Manager` from `@pithy-sh/cloudflare` (which
+ * implements `D1Database`), and the same Kysely/codec path the in-Worker recorder uses runs against
+ * it. The {@link ResolvedActor} is merged in, with its correlation metadata under the caller's own.
+ *
+ * Like the in-Worker recorder, this is **non-fatal**: a write failure is logged, never thrown, so an
+ * audit write never breaks the command it records.
+ */
+export async function emitFromCLI(
+  d1: D1Database,
+  event: CliAuditEvent,
+  actor: ResolvedActor,
+  options?: AuditRecorderOptions,
+): Promise<void> {
+  // `environment` is an origin field, not an event field — pulled off here so it reaches the origin
+  // rather than `AuditEvent`, which has no such key and would drop it silently.
+  const { environment, ...rest } = event;
+  const merged: AuditEventInput = {
+    ...rest,
+    actorType: actor.actorType,
+    actorId: actor.actorId,
+    // The caller's metadata wins on a key clash; the actor's correlation fields fill in the rest.
+    metadata: { ...actor.metadata, ...(event.metadata ?? {}) },
+  };
+  const origin =
+    environment === undefined
+      ? options?.origin
+      : {
+          project: options?.origin?.project ?? null,
+          environment,
+          worker: options?.origin?.worker ?? null,
+          version: options?.origin?.version ?? null,
+        };
+  await recordAuditEvent(auditDatabase(d1), merged, { ...options, ...(origin ? { origin } : {}) });
+}

package/src/cli/resolveActor.ts

@@ -0,0 +1,126 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+import type { AuditActorType, AuditMetadata } from "@pithy-sh/core/src/audit/auditEvent";
+import { messageOf } from "@pithy-sh/core/src/error/pithyError";
+
+/** The user-scoped slice: who is behind a `cfut_*` token. `clients.user()` satisfies it. */
+export interface CfUserActorSource {
+  /** The Cloudflare user behind a user token (`GET /user`). */
+  getUser(): Promise<{ id?: string; email?: string }>;
+}
+
+/** The account-scoped slice: which credential a `cfat_*` token is. `clients.accountTokens()` satisfies it. */
+export interface CfAccountTokenActorSource {
+  /** Verify the calling token against the account, returning its id + status (`GET /accounts/{id}/tokens/verify`). */
+  verifyToken(): Promise<{ id: string; status: string }>;
+  /** The token's name by id, or `null` when the caller may not read it (`GET /accounts/{id}/tokens/{id}`). */
+  getTokenName(tokenId: string): Promise<string | null>;
+}
+
+/**
+ * The slices of `@pithy-sh/cloudflare` actor resolution needs — declared structurally so the resolver
+ * is unit-testable with a fake and the audit package never hard-depends on the concrete managers.
+ * `{ user: clients.user(), accountTokens: clients.accountTokens() }` satisfies it.
+ *
+ * **Two scopes, not one, because a token is valid in exactly one of them.** An account-owned
+ * (`cfat_*`) token — the kind CLAUDE.md prefers and `pithy token mint` produces — answers
+ * `Invalid API Token` at every `/user/*` endpoint. A single flat source made the wrong scope
+ * reachable from the account path, and since resolution failure is never fatal, the whole preferred
+ * setup silently attributed to `system`. Split, the account path cannot reach a user endpoint at all.
+ */
+export interface CfActorSource {
+  /** User-scoped reads, for a `cfut_*` token. */
+  user: CfUserActorSource;
+  /** Account-scoped reads, for a `cfat_*` token. */
+  accountTokens: CfAccountTokenActorSource;
+}
+
+/** A resolved CLI actor: who to attribute a control-plane audit event to, plus correlation metadata. */
+export interface ResolvedActor {
+  /** The kind of principal. */
+  actorType: AuditActorType;
+  /** The principal's id (a user email, a token name), or null when unresolved. */
+  actorId: string | null;
+  /** Correlation detail for the event's `metadata` — never the raw token value. */
+  metadata: AuditMetadata;
+}
+
+/** The fallback actor when resolution can't attribute the action: `system`, with a note (never fatal). */
+function systemActor(note: string): ResolvedActor {
+  return { actorType: "system", actorId: null, metadata: { actorResolutionFailed: true, note } };
+}
+
+/**
+ * Resolve the actor behind a CF API token from its **prefix** — the only part read, never the value:
+ *
+ * - `cfut_*` (user token) → a human developer. Resolve the user's email via `GET /user`; the CF user
+ *   id rides in `metadata` for stable cross-reference. `actorType: "user"`, `actorId: <email>`.
+ * - `cfat_*` (account token) → a service account or CI pipeline. Verify the token **against the
+ *   account**, then read its name; `actorType: "service"`, `actorId: <token-name>` (the token id is
+ *   the fallback and rides in `metadata`).
+ *
+ * The name is best-effort by design. Reading a token record needs `API Tokens Read`, which the
+ * least-privilege tokens `pithy token mint` produces deliberately do not carry, so the account source
+ * answers `null` there and `actorId` falls back to the token id — which verify always yields, for any
+ * account token, with no permission at all. Attribution stays on the credential either way — once
+ * verify has named it, nothing about a decorative label may take that back — so a name read that
+ * *fails* rather than declining takes the same fallback, and records why in `metadata.cfTokenNameError`
+ * instead of vanishing. Widening the mint permission set to make the name readable would trade least
+ * privilege for a label.
+ *
+ * Resolution failure — a bad token, a network error, an unrecognized prefix — is **never fatal**: it
+ * returns a `system` actor with a `metadata` note, so the event is still written, just unattributed.
+ */
+export async function resolveActor(apiToken: string, source: CfActorSource): Promise<ResolvedActor> {
+  try {
+    if (apiToken.startsWith("cfut_")) {
+      const user = await source.user.getUser();
+      return {
+        actorType: "user",
+        actorId: user.email ?? user.id ?? null,
+        metadata: { cfTokenType: "user", cfUserId: user.id ?? null },
+      };
+    }
+    if (apiToken.startsWith("cfat_")) {
+      const verification = await source.accountTokens.verifyToken();
+      // Verify has already named the credential, so the name read cannot cost us the attribution: it
+      // falls back to the token id rather than collapsing a known credential to `system`. It does not
+      // pass unremarked, though — a trail that degrades quietly is the defect this path had. The two
+      // cases are different and the record says which: a **declined** read (the source answers `null`)
+      // is the ordinary least-privilege shape and needs no note, while a read that **failed** leaves
+      // its reason in `metadata` for whoever asks why the actor is an id and not a name.
+      let nameError: string | undefined;
+      const name = await source.accountTokens.getTokenName(verification.id).catch((error: unknown) => {
+        nameError = messageOf(error);
+        return null;
+      });
+      return {
+        actorType: "service",
+        actorId: name ?? verification.id,
+        metadata: {
+          cfTokenType: "account",
+          cfTokenId: verification.id,
+          cfTokenStatus: verification.status,
+          ...(nameError === undefined ? {} : { cfTokenNameError: nameError }),
+        },
+      };
+    }
+    return systemActor("Unrecognized Cloudflare API token prefix; expected `cfut_` or `cfat_`.");
+  } catch (error) {
+    return systemActor(`Cloudflare actor resolution failed: ${messageOf(error)}`);
+  }
+}
+
+/**
+ * A resolver that runs {@link resolveActor} **once** and caches the result for the lifetime of a CLI
+ * command — actor identity is resolved at session start, not per event. Memoizes the in-flight
+ * promise so concurrent emits share the single resolution.
+ */
+export function createCachedActorResolver(apiToken: string, source: CfActorSource): () => Promise<ResolvedActor> {
+  let cached: Promise<ResolvedActor> | undefined;
+  return () => {
+    cached ??= resolveActor(apiToken, source);
+    return cached;
+  };
+}

package/src/cloudflare-test.d.ts

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+/// <reference types="@cloudflare/vitest-plugin/types" />
+
+// Bindings the Workers-runtime test project provides to `*.workers.test.ts`, matching the Miniflare
+// config in `vitest.workers.config.ts`: the default audit D1 binding `DB`. `cloudflare:test` types
+// its `env` as `Cloudflare.Env`, so the test bindings are declared by augmenting that interface.
+declare namespace Cloudflare {
+  interface Env {
+    DB: D1Database;
+  }
+}