@wtfalch/audit 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# @wtfalch/audit
+
+The estate's append-only audit ledger, as a package: one table's shape and
+walls, a signer, readers, erasure and export. Per-app Postgres, a vocabulary
+the host supplies, no framework.
+
+It is **not** a service you call from outside. A host constructs the ledger
+once inside its trusted base, keeps the signer there, and hands each module
+that wants auditing a writer already bound to the actor the base resolved
+and the event names that module may use. The guarantee that a row's actor is
+real is the host's, and it holds only while the signer stays private.
+
+## What the package enforces, and what the host does
+
+| Concern | Where |
+| --- | --- |
+| Column bounds, JSON size, `namespace.name` action shape, subject pair, break-glass shape | `migrations/0001_audit.sql` CHECKs, and `rowSchema` before the insert |
+| Append-only: no DELETE, no TRUNCATE, UPDATE limited to what erasure touches | `audit_events_guard` trigger, plus a revoke from `<database>_rt` |
+| The closed sets: which events, actor classes, contexts, outcomes, reason codes | `LedgerVocabulary` in TypeScript at write time; the host's own CHECKs in the database when it has them |
+| Who may sign what | The host. The package checks no permission and reads no session |
+| Tenant visibility | Decided per event in the vocabulary, never per write |
+| Erasure | `audit_erase_person(subject, pseudonym, subject_email)`, ledger-only, `SECURITY DEFINER`; the host cleans its own tables in the same transaction |
+
+## Install
+
+```sh
+pnpm add @wtfalch/audit
+pnpm exec audit-migrations   # copies migrations/*.sql into drizzle/ as the next numbers
+```
+
+The copy is recorded in `drizzle/.audit-migrations.json`; running it again
+copies nothing. Apply the copied file with the host's own migrate script.
+
+## Use
+
+```ts
+import { core } from '@wtfalch/authz';
+import { createLedger, ledgerVocabularyFromCore } from '@wtfalch/audit';
+
+// Once, inside the trusted base.
+const ledger = createLedger({
+  vocabulary: ledgerVocabularyFromCore(core, {
+    'invoice.paid': { tenantVisible: true },
+  }),
+});
+
+// In a server action, inside the transaction that makes the change.
+await db.transaction(async (tx) => {
+  await tx.update(invoices).set({ paidAt: now }).where(eq(invoices.id, id));
+  await ledger.sign(tx, {
+    action: 'invoice.paid',
+    tenantId,
+    actor: { class: 'human', id: access.principal.id, display: access.principal.display },
+    context: 'standard',
+    target: { type: 'invoice', id },
+    after: { paidAt: now },
+    request: requestContext(),
+  });
+});
+
+// Readers. The host gates; a tenant-facing page always passes tenantVisibleOnly.
+const page = await ledger.page(db, { tenantId, tenantVisibleOnly: true, limit: 50 });
+const rows = await ledger.exportRows(db, tenantId);
+
+// Erasure, inside the host's own erasure transaction.
+const touched = await ledger.erase(tx, { subject: personId, pseudonym, email });
+```
+
+`ledgerVocabularyFromCore` refuses a host event in a namespace the core
+uses: `tenant.invoice_paid` is out, `invoice.paid` is in. The core's
+namespaces are the trusted base's.
+
+## Tests
+
+```sh
+pnpm test                                        # PGlite, in memory
+TEST_DATABASE_URL=postgres://... pnpm test       # a real Postgres; drops its public schema first
+```
+
+The real run adds the runtime-role test: `<database>_rt` may insert and
+call `audit_erase_person`, and may not update, delete or truncate.
+
+## Release
+
+Tag `v*`. The workflow builds, tests and publishes with npm trusted
+publishing; the first publish of a new package is done from a laptop.

package/dist/bin/copy.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Migrations in this estate are hand-written SQL, numbered per app, applied
+ * by psql on boot, additive. A package cannot own a number in an app's
+ * sequence, so this copies any migration the app has not yet copied into the
+ * app's `drizzle/` as the next numbers and records which in a manifest. The
+ * same mechanism `@wtfalch/threads` and `@wtfalch/reporting` use; the manifest name differs.
+ */
+export declare const MANIFEST = ".audit-migrations.json";
+export interface Manifest {
+    /** package file name -> the name it was copied to in the app */
+    copied: Record<string, string>;
+}
+export interface CopyResult {
+    copied: Array<{
+        from: string;
+        to: string;
+    }>;
+    manifest: Manifest;
+}
+export declare function copyMigrations(opts: {
+    from: string;
+    to: string;
+    version?: string;
+}): CopyResult;
+export declare function describeCopy(result: CopyResult): string;

package/dist/bin/copy.js

@@ -0,0 +1,55 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+/**
+ * Migrations in this estate are hand-written SQL, numbered per app, applied
+ * by psql on boot, additive. A package cannot own a number in an app's
+ * sequence, so this copies any migration the app has not yet copied into the
+ * app's `drizzle/` as the next numbers and records which in a manifest. The
+ * same mechanism `@wtfalch/threads` and `@wtfalch/reporting` use; the manifest name differs.
+ */
+export const MANIFEST = '.audit-migrations.json';
+const NUMBERED = /^(\d{4})_(.+\.sql)$/;
+function readManifest(dir) {
+    const file = join(dir, MANIFEST);
+    if (!existsSync(file))
+        return { copied: {} };
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    return { copied: parsed.copied ?? {} };
+}
+function nextNumber(dir) {
+    let max = -1;
+    for (const name of readdirSync(dir)) {
+        const m = NUMBERED.exec(name);
+        if (m?.[1])
+            max = Math.max(max, Number(m[1]));
+    }
+    return max + 1;
+}
+export function copyMigrations(opts) {
+    mkdirSync(opts.to, { recursive: true });
+    const manifest = readManifest(opts.to);
+    const copied = [];
+    const sources = readdirSync(opts.from)
+        .filter((n) => NUMBERED.test(n))
+        .sort();
+    let next = nextNumber(opts.to);
+    for (const name of sources) {
+        if (manifest.copied[name])
+            continue;
+        const rest = NUMBERED.exec(name)?.[2] ?? name;
+        const target = `${String(next).padStart(4, '0')}_${rest}`;
+        const body = readFileSync(join(opts.from, name), 'utf8');
+        const header = `-- Copied from @wtfalch/audit${opts.version ? ` ${opts.version}` : ''} (migrations/${name}) by audit-migrations.\n-- Do not edit here; the next package version ships the next file.\n\n`;
+        writeFileSync(join(opts.to, target), header + body);
+        manifest.copied[name] = target;
+        copied.push({ from: name, to: target });
+        next += 1;
+    }
+    writeFileSync(join(opts.to, MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`);
+    return { copied, manifest };
+}
+export function describeCopy(result) {
+    if (result.copied.length === 0)
+        return 'audit-migrations: nothing to copy';
+    return result.copied.map((c) => `audit-migrations: ${c.from} -> ${basename(c.to)}`).join('\n');
+}

package/dist/bin/migrations.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/migrations.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { copyMigrations, describeCopy } from './copy.js';
+/**
+ * `audit-migrations [dir]`: copy this package's migrations the app has
+ * not yet copied into `dir` (default `drizzle`) as the next numbers.
+ * Idempotent; run it after every upgrade of @wtfalch/audit, then commit
+ * what it wrote.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const from = join(here, '..', 'migrations');
+const to = resolve(process.cwd(), process.argv[2] ?? 'drizzle');
+const { version } = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf8'));
+console.log(describeCopy(copyMigrations({ from, to, version })));

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './ledger.js';
+export { AUDIT_LIMITS, type AuditRow, isJsonValue, rowSchema } from './schema.js';
+export * from './tables.js';
+export * from './vocabulary.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './ledger.js';
+export { AUDIT_LIMITS, isJsonValue, rowSchema } from './schema.js';
+export * from './tables.js';
+export * from './vocabulary.js';

package/dist/ledger.d.ts

@@ -0,0 +1,98 @@
+import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import { type AuditEventRow, auditEvents } from './tables.js';
+import type { LedgerVocabulary } from './vocabulary.js';
+/**
+ * The host's drizzle handle or a transaction open on it. postgres-js in the
+ * apps, PGlite in this package's own tests; the queries use nothing
+ * driver-specific.
+ */
+export type Handle = PgDatabase<PgQueryResultHKT, any, any>;
+/** Who did it. The host's trusted base fills this from the access it resolved; nothing else may. */
+export interface Actor {
+    readonly class: string;
+    readonly id: string;
+    readonly display: string;
+}
+/** What a caller of the signer supplies for one row. Everything else is filled in here. */
+export interface SignInput {
+    readonly action: string;
+    readonly tenantId: string | null;
+    readonly actor: Actor;
+    readonly context: string;
+    readonly target: {
+        readonly type: string;
+        readonly id: string;
+    };
+    readonly outcome?: string;
+    readonly sessionId?: string | null;
+    readonly reason?: string | null;
+    readonly reference?: string | null;
+    readonly request?: {
+        readonly id?: string | null;
+        readonly ip?: string | null;
+        readonly userAgent?: string | null;
+    };
+    /** Defaults to the vocabulary's decision for this event. A host may override for a single row and should rarely need to. */
+    readonly tenantVisible?: boolean;
+    readonly before?: unknown;
+    readonly after?: unknown;
+    /** The principal the event is about, when it is not the actor. */
+    readonly subject?: {
+        readonly class: string;
+        readonly id: string;
+    } | null;
+    readonly occurredAt?: Date;
+}
+export interface PageOptions {
+    /** One tenant's rows; `null` for rows with no tenant; omit for every tenant. */
+    readonly tenantId?: string | null;
+    /** Only rows the tenant's own log may show. A tenant-facing reader passes `true` and never lets a caller choose. */
+    readonly tenantVisibleOnly?: boolean;
+    readonly actorId?: string;
+    readonly subjectId?: string;
+    readonly action?: string;
+    readonly requestId?: string;
+    readonly after?: {
+        readonly occurredAt: Date;
+        readonly id: number;
+    };
+    readonly limit?: number;
+}
+export interface Page {
+    readonly items: readonly AuditEventRow[];
+    readonly next: {
+        readonly occurredAt: Date;
+        readonly id: number;
+    } | null;
+}
+export interface EraseInput {
+    readonly subject: string;
+    readonly pseudonym: string;
+    /** The person's address, so rows whose payloads name them and nothing else are swept too. */
+    readonly email?: string | null;
+}
+/**
+ * What `createLedger` returns. **`sign` is the signer.** A host constructs the
+ * ledger exactly once inside its trusted base, keeps `sign` there, and hands
+ * each service that wants auditing a writer already bound to the actor it
+ * resolved and the event names it may use. Nothing here checks a permission
+ * or reads a session: the guarantee that a row's actor is real is the host's,
+ * and it holds only while the signer stays private.
+ */
+export interface Ledger {
+    readonly vocabulary: LedgerVocabulary;
+    readonly tables: {
+        readonly events: typeof auditEvents;
+    };
+    /** Validates against the vocabulary and inserts, on the handle given: a transaction when the row must commit with the change it records. */
+    sign(handle: Handle, input: SignInput): Promise<void>;
+    /** Newest first, keyset on `(occurred_at, id)`. Applies no permission; the host gates and decides `tenantVisibleOnly`. */
+    page(handle: Handle, options?: PageOptions): Promise<Page>;
+    /** The one sanctioned write: `audit_erase_person`. Returns how many rows it touched. Call inside the host's erasure transaction. */
+    erase(handle: Handle, input: EraseInput): Promise<number>;
+    /** One tenant's rows, oldest first, for a tenant's export. Deterministic order; no secrets are in this table to omit. */
+    exportRows(handle: Handle, tenantId: string): Promise<readonly AuditEventRow[]>;
+}
+export declare function createLedger(options: {
+    vocabulary: LedgerVocabulary;
+}): Ledger;

package/dist/ledger.js

@@ -0,0 +1,114 @@
+import { and, asc, desc, eq, lt, or, sql } from 'drizzle-orm';
+import { rowSchema } from './schema.js';
+import { auditEvents } from './tables.js';
+export function createLedger(options) {
+    const { vocabulary } = options;
+    const schema = rowSchema(vocabulary);
+    async function sign(handle, input) {
+        const meta = vocabulary.events[input.action];
+        if (!meta) {
+            throw new Error(`audit: "${input.action}" is not an event this ledger's vocabulary declares`);
+        }
+        const occurredAt = input.occurredAt ?? new Date();
+        const row = schema.parse({
+            occurred_at: occurredAt.toISOString(),
+            tenant_id: input.tenantId,
+            actor_class: input.actor.class,
+            actor_id: input.actor.id,
+            actor_display: input.actor.display,
+            action: input.action,
+            target_type: input.target.type,
+            target_id: input.target.id,
+            outcome: input.outcome ?? vocabulary.outcomes[0],
+            context: input.context,
+            session_id: input.sessionId ?? null,
+            reason: input.reason ?? null,
+            reference: input.reference ?? null,
+            request_id: input.request?.id ?? null,
+            ip: input.request?.ip ?? null,
+            user_agent: input.request?.userAgent ?? null,
+            tenant_visible: input.tenantVisible ?? meta.tenantVisible,
+            before: input.before ?? null,
+            after: input.after ?? null,
+            erased_at: null,
+            schema_version: 1,
+            subject_class: input.subject?.class ?? null,
+            subject_id: input.subject?.id ?? null,
+        });
+        await handle.insert(auditEvents).values({
+            occurredAt,
+            tenantId: row.tenant_id,
+            actorClass: row.actor_class,
+            actorId: row.actor_id,
+            actorDisplay: row.actor_display,
+            action: row.action,
+            targetType: row.target_type,
+            targetId: row.target_id,
+            outcome: row.outcome,
+            context: row.context,
+            sessionId: row.session_id,
+            reason: row.reason,
+            reference: row.reference,
+            requestId: row.request_id,
+            ip: row.ip,
+            userAgent: row.user_agent,
+            tenantVisible: row.tenant_visible,
+            before: row.before,
+            after: row.after,
+            schemaVersion: row.schema_version,
+            subjectClass: row.subject_class,
+            subjectId: row.subject_id,
+        });
+    }
+    async function page(handle, options = {}) {
+        const limit = Math.max(1, Math.min(options.limit ?? 50, 200));
+        const conditions = [];
+        if (options.tenantId === null)
+            conditions.push(sql `${auditEvents.tenantId} is null`);
+        else if (options.tenantId !== undefined)
+            conditions.push(eq(auditEvents.tenantId, options.tenantId));
+        if (options.tenantVisibleOnly)
+            conditions.push(eq(auditEvents.tenantVisible, true));
+        if (options.actorId)
+            conditions.push(eq(auditEvents.actorId, options.actorId));
+        if (options.subjectId)
+            conditions.push(eq(auditEvents.subjectId, options.subjectId));
+        if (options.action)
+            conditions.push(eq(auditEvents.action, options.action));
+        if (options.requestId)
+            conditions.push(eq(auditEvents.requestId, options.requestId));
+        if (options.after) {
+            const { occurredAt, id } = options.after;
+            const keyset = or(lt(auditEvents.occurredAt, occurredAt), and(eq(auditEvents.occurredAt, occurredAt), lt(auditEvents.id, id)));
+            if (keyset)
+                conditions.push(keyset);
+        }
+        const rows = await handle
+            .select()
+            .from(auditEvents)
+            .where(conditions.length > 0 ? and(...conditions) : undefined)
+            .orderBy(desc(auditEvents.occurredAt), desc(auditEvents.id))
+            .limit(limit + 1);
+        const items = rows.slice(0, limit);
+        const last = items.at(-1);
+        return {
+            items,
+            next: rows.length > limit && last ? { occurredAt: last.occurredAt, id: last.id } : null,
+        };
+    }
+    async function erase(handle, input) {
+        const result = await handle.execute(sql `select audit_erase_person(${input.subject}, ${input.pseudonym}, ${input.email ?? null}) as n`);
+        const rows = Array.isArray(result)
+            ? result
+            : (result.rows ?? []);
+        return Number(rows[0]?.n ?? 0);
+    }
+    async function exportRows(handle, tenantId) {
+        return handle
+            .select()
+            .from(auditEvents)
+            .where(eq(auditEvents.tenantId, tenantId))
+            .orderBy(asc(auditEvents.occurredAt), asc(auditEvents.id));
+    }
+    return { vocabulary, tables: { events: auditEvents }, sign, page, erase, exportRows };
+}

package/dist/migrations/0001_audit.sql

@@ -0,0 +1,203 @@
+-- @wtfalch/audit: the append-only audit ledger. Mirrors src/tables.ts.
+--
+-- Every statement is idempotent. Applied by the host's own migrate script
+-- after the host copies this file into its drizzle/ directory as the next
+-- number (audit-migrations); never edited there.
+--
+-- What this file enforces is the ledger's SHAPE and its WALLS: bounded
+-- columns, JSON under 64 KB, the pairs that must appear together, the
+-- break-glass rule that a session row carries its session, reason and
+-- reference, and the three triggers plus the runtime-role revoke that make
+-- "append-only" true for a role that is not a superuser. The CLOSED SETS
+-- (which event names, actor classes, contexts, outcomes and reason codes a
+-- host admits) are the host's own vocabulary: enforced in TypeScript by the
+-- ledger at write time, and in the database by the host's own CHECKs when it
+-- has them (wtfalch/app-template's 0003 and 0007 do). A host with only this
+-- file gets the shape and the walls.
+--
+-- Estate-shaped: the DO block assumes a runtime role named <database>_rt that
+-- owns nothing and serves the app. Without it, the tables and the function
+-- exist and no revoke takes effect.
+--
+-- No foreign keys, on purpose: the trail outlives the tenant, the person and
+-- the credential it describes. `tenant_id` is a uuid because the estate's
+-- tenants are; a host with other ids alters the column in its own migration.
+
+create table if not exists audit_events (
+  id              bigint generated always as identity primary key,
+  occurred_at     timestamptz not null default now(),
+  tenant_id       uuid,
+  actor_class     text not null,
+  actor_id        text not null,
+  actor_display   text not null,
+  action          text not null,
+  target_type     text not null,
+  target_id       text not null,
+  outcome         text not null,
+  context         text not null,
+  session_id      text,
+  reason          text,
+  reference       text,
+  request_id      text,
+  ip              text,
+  user_agent      text,
+  tenant_visible  boolean not null,
+  before          jsonb,
+  after           jsonb,
+  -- Set by audit_erase_person. The row and actor_id survive; who that was
+  -- does not, once this is set.
+  erased_at       timestamptz,
+  schema_version  smallint not null default 1,
+  -- The principal the event was ABOUT, when that is not the actor: an
+  -- invitation's invitee, a membership's holder. What lets "events affecting
+  -- me" be answered without guessing from payloads.
+  subject_class   text,
+  subject_id      text,
+  constraint audit_events_actor_class_check check (length(actor_class) between 1 and 64),
+  constraint audit_events_actor_id_check check (length(actor_id) between 1 and 256),
+  constraint audit_events_actor_display_check check (length(actor_display) between 1 and 256),
+  constraint audit_events_action_shape_check check (action ~ '^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$'),
+  constraint audit_events_target_type_check check (length(target_type) between 1 and 64),
+  constraint audit_events_target_id_check check (length(target_id) between 1 and 256),
+  constraint audit_events_outcome_check check (length(outcome) between 1 and 32),
+  constraint audit_events_context_check check (length(context) between 1 and 32),
+  constraint audit_events_session_id_check check (session_id is null or length(session_id) <= 256),
+  constraint audit_events_reason_check check (reason is null or length(reason) <= 512),
+  constraint audit_events_reference_check check (reference is null or length(reference) <= 512),
+  constraint audit_events_request_id_check check (request_id is null or length(request_id) <= 128),
+  constraint audit_events_ip_check check (ip is null or length(ip) <= 64),
+  constraint audit_events_user_agent_check check (user_agent is null or length(user_agent) <= 1024),
+  constraint audit_events_before_check check (before is null or octet_length(before::text) <= 65536),
+  constraint audit_events_after_check check (after is null or octet_length(after::text) <= 65536),
+  -- A support-session row names its session, its reason and its reference.
+  -- Which reasons are admissible is the host's closed set.
+  constraint audit_events_break_glass_shape_check check (
+    context <> 'break_glass'
+    or (session_id is not null and reason is not null and reference is not null)
+  ),
+  constraint audit_events_subject_pair_check check ((subject_id is null) = (subject_class is null)),
+  constraint audit_events_subject_class_check check (subject_class is null or length(subject_class) between 1 and 64),
+  constraint audit_events_subject_id_check check (subject_id is null or length(subject_id) between 1 and 256)
+);
+
+-- (occurred_at, id) is the ordering; every reader pages on it.
+create index if not exists audit_events_tenant_time_idx
+  on audit_events (tenant_id, occurred_at desc, id desc);
+create index if not exists audit_events_actor_time_idx
+  on audit_events (actor_id, occurred_at desc);
+create index if not exists audit_events_action_time_idx
+  on audit_events (action, occurred_at desc);
+create index if not exists audit_events_subject_time_idx
+  on audit_events (subject_class, subject_id, occurred_at desc, id desc) where subject_id is not null;
+create index if not exists audit_events_request_idx
+  on audit_events (request_id, occurred_at desc) where request_id is not null;
+
+-- The second wall. The first is the revoke below, which stops the server; this
+-- stops the owner's own mistakes at a psql prompt. An UPDATE may change only
+-- the four columns erasure touches, and DELETE and TRUNCATE are refused
+-- outright. audit_erase_person passes through this trigger, not around it.
+create or replace function audit_events_guard() returns trigger
+language plpgsql as $$
+begin
+  if tg_op = 'DELETE' then
+    raise exception 'audit_events is append-only: delete refused';
+  elsif tg_op = 'TRUNCATE' then
+    raise exception 'audit_events is append-only: truncate refused';
+  elsif tg_op = 'UPDATE' then
+    if new.id is distinct from old.id
+      or new.occurred_at is distinct from old.occurred_at
+      or new.tenant_id is distinct from old.tenant_id
+      or new.actor_class is distinct from old.actor_class
+      or new.actor_id is distinct from old.actor_id
+      or new.action is distinct from old.action
+      or new.target_type is distinct from old.target_type
+      or new.target_id is distinct from old.target_id
+      or new.outcome is distinct from old.outcome
+      or new.context is distinct from old.context
+      or new.session_id is distinct from old.session_id
+      or new.reason is distinct from old.reason
+      or new.reference is distinct from old.reference
+      or new.request_id is distinct from old.request_id
+      or new.ip is distinct from old.ip
+      or new.user_agent is distinct from old.user_agent
+      or new.tenant_visible is distinct from old.tenant_visible
+      or new.schema_version is distinct from old.schema_version
+      or new.subject_class is distinct from old.subject_class
+      or new.subject_id is distinct from old.subject_id
+    then
+      raise exception 'audit_events is append-only: only actor_display, before, after and erased_at may change';
+    end if;
+  end if;
+  return new;
+end
+$$;
+drop trigger if exists audit_events_guarded_update on audit_events;
+create trigger audit_events_guarded_update
+  before update on audit_events
+  for each row execute function audit_events_guard();
+drop trigger if exists audit_events_no_delete on audit_events;
+create trigger audit_events_no_delete
+  before delete on audit_events
+  for each row execute function audit_events_guard();
+drop trigger if exists audit_events_no_truncate on audit_events;
+create trigger audit_events_no_truncate
+  before truncate on audit_events
+  for each statement execute function audit_events_guard();
+
+-- The one sanctioned write. Rows the person wrote (actor_id), rows written
+-- about them (subject_id), and rows whose payload carries their address:
+-- actor_display becomes the pseudonym on their own rows, before and after
+-- are replaced wholesale on every matched row, erased_at is set. actor_id
+-- and subject_id stay, so "somebody with this id did this" survives and
+-- "who that was" does not. Row counts never change. Ledger-only: a host's
+-- own tables (a profile, an invitation) are the host's to clean, in the same
+-- transaction, and its final `person.erased` row is written after this.
+create or replace function audit_erase_person(subject text, pseudonym text, subject_email text)
+returns integer
+language plpgsql
+security definer
+set search_path = pg_catalog, public
+as $$
+declare
+  touched integer;
+begin
+  if subject is null or length(subject) = 0 then
+    raise exception 'audit_erase_person: a subject id is required';
+  end if;
+  if pseudonym is null or length(pseudonym) = 0 or length(pseudonym) > 256 then
+    raise exception 'audit_erase_person: a pseudonym of 1 to 256 characters is required';
+  end if;
+  update audit_events
+     set actor_display = case when actor_id = subject then pseudonym else actor_display end,
+         before = case when before is null then null else '{"erased":true}'::jsonb end,
+         after = case when after is null then null else '{"erased":true}'::jsonb end,
+         erased_at = now()
+   where erased_at is null
+     and (
+       actor_id = subject
+       or subject_id = subject
+       or (
+         subject_email is not null
+         and length(subject_email) > 0
+         and (
+           lower(coalesce(before::text, '')) like '%' || lower(subject_email) || '%'
+           or lower(coalesce(after::text, '')) like '%' || lower(subject_email) || '%'
+         )
+       )
+     );
+  get diagnostics touched = row_count;
+  return touched;
+end
+$$;
+revoke all on function audit_erase_person(text, text, text) from public;
+
+do $$
+declare
+  rt text := current_database() || '_rt';
+begin
+  if exists (select 1 from pg_roles where rolname = rt) then
+    execute format('revoke update, delete, truncate on audit_events from %I', rt);
+    execute format('grant execute on function audit_erase_person(text, text, text) to %I', rt);
+  end if;
+end
+$$;

package/dist/schema.d.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { type LedgerVocabulary } from './vocabulary.js';
+/** The bounds every row honours, in characters; `jsonBytes` is `before` and `after`, each, serialised. Match `migrations/0001_audit.sql`. */
+export declare const AUDIT_LIMITS: {
+    readonly id: 256;
+    readonly display: 256;
+    readonly targetType: 64;
+    readonly reason: 512;
+    readonly reference: 512;
+    readonly requestId: 128;
+    readonly ip: 64;
+    readonly userAgent: 1024;
+    readonly jsonBytes: 65536;
+};
+/** A value that survives a JSON round trip unchanged: null, finite numbers, strings, booleans, arrays and plain objects of the same, with no cycle. */
+export declare function isJsonValue(value: unknown, seen?: WeakSet<object>): boolean;
+/**
+ * One row as the ledger writes it, for a given vocabulary. Unknown keys are
+ * refused, so a misspelt column fails loudly instead of vanishing. A row in
+ * the break-glass context must carry the session, a reason from the closed
+ * code set and a reference; every other row's reason is free text.
+ */
+export declare function rowSchema(vocabulary: LedgerVocabulary): z.ZodObject<{
+    occurred_at: z.ZodISODateTime;
+    tenant_id: z.ZodNullable<z.ZodString>;
+    actor_class: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    actor_id: z.ZodString;
+    actor_display: z.ZodString;
+    action: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    target_type: z.ZodString;
+    target_id: z.ZodString;
+    outcome: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    context: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    session_id: z.ZodNullable<z.ZodString>;
+    reason: z.ZodNullable<z.ZodString>;
+    reference: z.ZodNullable<z.ZodString>;
+    request_id: z.ZodNullable<z.ZodString>;
+    ip: z.ZodNullable<z.ZodString>;
+    user_agent: z.ZodNullable<z.ZodString>;
+    tenant_visible: z.ZodBoolean;
+    before: z.ZodNullable<z.ZodUnknown>;
+    after: z.ZodNullable<z.ZodUnknown>;
+    erased_at: z.ZodNullable<z.ZodISODateTime>;
+    schema_version: z.ZodLiteral<1>;
+    subject_class: z.ZodNullable<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+    subject_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type AuditRow = z.infer<ReturnType<typeof rowSchema>>;