@wtfalch/authz-store 0.2.0 → 0.3.0

package/dist/credentials.d.ts

@@ -0,0 +1,94 @@
+import { type CredentialKind } from '@wtfalch/authz';
+import type { DbOrTx, Scope } from './scoped.js';
+import { type Access, type Result } from './types.js';
+/**
+ * What this store's issued credentials carry as `SignableRow.grants` (authz#95
+ * decision 2, moved from Boule's own `ManageKeyGrant`). Opaque to the Worker
+ * and to `@wtfalch/keys` itself -- only a host's own bearer-authentication path
+ * reads it.
+ *
+ * A grant carries only the id of the `credentials` row it was minted for.
+ * This store's own tenant, role, membership and assignment tables are re-read
+ * fresh on every request regardless of what that row says (`loadAccess`), so
+ * there is nothing about the row's own columns worth pinning into the signed
+ * grant -- only which row a presented secret is allowed to stand for at all.
+ */
+export type StoreKeyGrant = {
+    readonly credentialId: string;
+};
+/**
+ * The store's own structural port over `@wtfalch/keys/issued`'s
+ * `CredentialIssuer<TGrant>`. `mintCredential` only ever calls `issue()` and
+ * `revokeCredential` only ever calls `revoke()` -- `check()`, `rotate()` and
+ * `lineageOf()` belong to a host's own bearer path and rotation console,
+ * neither of which lives here -- so the port names only the two, in exactly
+ * the shapes those two functions call them.
+ *
+ * A host builds a real one with `createCredentialIssuer` from
+ * `@wtfalch/keys/issued`; that package is a `devDependency` of this one
+ * (its type test, `credentials.test.ts`, is the only place this package
+ * imports it), never a runtime import here, so there is no default issuer to
+ * fall back to. Every caller must pass its own.
+ */
+export interface CredentialIssuerPort<TGrant> {
+    issue(request: {
+        readonly grants: readonly TGrant[];
+        /** The id of the credential minting this one, or `null` for a root mint. */
+        readonly minter: string | null;
+        readonly expiresAt: number;
+    }): Promise<{
+        readonly ok: true;
+        readonly id: string;
+        readonly keyPrefix: string;
+        /** Shown exactly once; `null` on an idempotent replay. */
+        readonly secret: string | null;
+    } | {
+        readonly ok: false;
+        readonly reason: string;
+    }>;
+    revoke(id: string): Promise<unknown>;
+}
+export interface MintCredentialOptions {
+    readonly kind: CredentialKind;
+    readonly name: string;
+    readonly role: string;
+    readonly expiresAt?: Date;
+}
+export interface MintedCredential {
+    readonly id: string;
+    readonly secret: string;
+    readonly secretPrefix: string;
+}
+/**
+ * Issuer identity, expiry and scoped assignments are persisted together and
+ * rechecked on every request. `issuer` is required: this package mints no
+ * credential of its own accord, a host always supplies the one it built.
+ */
+export declare function mintCredential(access: Access, db: DbOrTx, scopeColumn: Scope['column'], issuer: Pick<CredentialIssuerPort<StoreKeyGrant>, 'issue'>, options: MintCredentialOptions): Promise<Result<MintedCredential>>;
+/** Every descendant loses authority through fresh lineage evaluation, including across inherited memberships. `issuer` is required, the same as `mintCredential`. */
+export declare function revokeCredential(access: Access, db: DbOrTx, scopeColumn: Scope['column'], issuer: Pick<CredentialIssuerPort<StoreKeyGrant>, 'revoke'>, credentialId: string): Promise<Result<void>>;
+export interface CredentialSummary {
+    readonly id: string;
+    readonly kind: string;
+    readonly name: string;
+    readonly secretPrefix: string | null;
+    readonly role: string | null;
+    readonly createdAt: Date;
+    readonly expiresAt: Date | null;
+    readonly revokedAt: Date | null;
+    readonly lastUsedAt: Date | null;
+    /** Who minted it: a person's display name, or -- when a credential minted
+     *  this one -- that credential's own name. Never the raw `issuerId`. */
+    readonly issuer: string;
+}
+/**
+ * What a host must supply to name a human issuer. `credentialsFor` no longer
+ * joins a host's own `profiles` table directly (that table is the host's,
+ * not the store's); it batches every human `issuerId` on the page into one
+ * call instead. A host returns a person's display name, falling back to
+ * their email itself, the same fallback Boule's own join order gave.
+ */
+export interface IssuerNames {
+    personNames(ids: readonly string[]): Promise<ReadonlyMap<string, string>>;
+}
+export declare function credentialsFor(access: Access, db: DbOrTx, names: IssuerNames): Promise<readonly CredentialSummary[] | null>;

package/dist/credentials.js

@@ -0,0 +1,230 @@
+import { randomUUID } from 'node:crypto';
+import { core } from '@wtfalch/authz';
+import { and, desc, eq, sql } from 'drizzle-orm';
+import { alias } from 'drizzle-orm/pg-core';
+import { identityWhere, primaryAssignment, primaryRoleKey, roleAssignmentRefusal, writePrimaryAssignment, } from './assignments.js';
+import { record } from './audit.js';
+import { permits, permitsRead, refreshAccess } from './policy-access.js';
+import { propagateMembershipChange, writerFromAccess } from './propagate.js';
+import { isCustomRoleKey } from './role-keys.js';
+import { roleDef } from './roles.js';
+import { credentials, memberships } from './schema.js';
+import { childrenOf } from './tree.js';
+import { done, isUuid, refused, tenantTag } from './types.js';
+/**
+ * `@wtfalch/keys/issued`'s `issue()` requires a concrete `expiresAt`, unlike
+ * this package's own pre-cutover scheme which stored `null` for "does not
+ * expire". A hundred years stands in for that: long enough that nothing
+ * operational treats it differently from "never", and far enough out that it
+ * is never mistaken for a deliberately-chosen near expiry.
+ */
+const NO_EXPIRY_MS = 100 * 365 * 24 * 60 * 60 * 1000;
+/**
+ * Issuer identity, expiry and scoped assignments are persisted together and
+ * rechecked on every request. `issuer` is required: this package mints no
+ * credential of its own accord, a host always supplies the one it built.
+ */
+export async function mintCredential(access, db, scopeColumn, issuer, options) {
+    if (access.context === 'break_glass')
+        return refused('break_glass', 'Support sessions cannot create credentials.');
+    if (!core.credentialKinds.includes(options.kind))
+        return refused('unknown_kind', 'Unknown credential kind.');
+    const name = options.name.trim();
+    if (!name || name.length > 120)
+        return refused('invalid_name', 'Use a name of 1–120 characters.');
+    if (options.expiresAt &&
+        (!Number.isFinite(options.expiresAt.getTime()) || options.expiresAt.getTime() <= Date.now()))
+        return refused('invalid_expiry', 'Choose a future expiry.');
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass' || !permits(fresh, 'credentials:create'))
+            return refused('no_permission', 'You cannot create credentials here.');
+        const role = await roleDef(tx, fresh.binding, fresh.tenant, options.role);
+        if (!role)
+            return refused('unknown_role', 'This role no longer exists.');
+        // Not `!role.builtIn`: a starter role (ADR 0016) is `built_in: false` for
+        // a tenant created after that change but is still app-defined, not
+        // tenant-authored, so it can still cross organisation boundaries.
+        if (isCustomRoleKey(role.key) && (await childrenOf(tx, fresh.tenant.id)).length)
+            return refused('custom_role_with_children', 'Custom roles cannot be inherited by another organisation.');
+        const id = randomUUID();
+        const principal = { id, class: options.kind };
+        let expiresAt = options.expiresAt ?? new Date(Date.now() + NO_EXPIRY_MS);
+        if (fresh.actor.class !== 'human') {
+            const [issuerRow] = await tx
+                .select({ expiresAt: credentials.expiresAt })
+                .from(credentials)
+                .where(and(eq(credentials.id, fresh.actor.id), eq(credentials.kind, fresh.actor.class)));
+            if (!issuerRow)
+                return refused('issuer_missing', 'The issuing credential no longer exists.');
+            if (issuerRow.expiresAt && issuerRow.expiresAt.getTime() < expiresAt.getTime())
+                expiresAt = issuerRow.expiresAt;
+        }
+        const reason = roleAssignmentRefusal(fresh, role, primaryAssignment(role, principal, expiresAt.getTime()), 'members:grant');
+        if (reason)
+            return refused(reason, 'This credential would exceed your delegation authority.');
+        // `minter: null` always: this row's own issuerId/issuerClass columns
+        // already carry this credential's lineage, and `@wtfalch/keys/issued`'s
+        // own minter chain buys nothing on top for a store that re-checks
+        // tenant/role/membership fresh on every request anyway (`loadAccess`).
+        const issued = await issuer.issue({
+            grants: [{ credentialId: id }],
+            minter: null,
+            expiresAt: expiresAt.getTime(),
+        });
+        if (!issued.ok || !issued.secret) {
+            return refused('mint_failed', 'Could not mint this credential right now.');
+        }
+        await tx.insert(credentials).values({
+            id,
+            tenantId: fresh.tenant.id,
+            kind: options.kind,
+            name,
+            secretPrefix: issued.keyPrefix,
+            keysIssuedId: issued.id,
+            createdBy: fresh.actor.id,
+            issuerId: fresh.actor.id,
+            issuerClass: fresh.actor.class,
+            expiresAt,
+        });
+        await tx.insert(memberships).values({
+            tenantId: fresh.tenant.id,
+            principalId: id,
+            principalClass: options.kind,
+            source: 'direct',
+            tenantName: fresh.tenant.name,
+            grantedBy: fresh.actor.id,
+        });
+        await writePrimaryAssignment(tx, fresh.binding, role, principal, {
+            createdBy: fresh.actor.id,
+            expiresAt,
+        });
+        await record(tx, fresh, {
+            action: 'credential.minted',
+            tenantId: fresh.tenant.id,
+            targetType: 'credential',
+            targetId: id,
+            after: {
+                kind: options.kind,
+                name,
+                roleId: role.id,
+                issuer: { id: fresh.actor.id, class: fresh.actor.class },
+                expiresAt: expiresAt.toISOString(),
+            },
+        });
+        const tags = await propagateMembershipChange(tx, fresh.binding, writerFromAccess(fresh), fresh.tenant.id, id);
+        return done({ id, secret: issued.secret, secretPrefix: issued.keyPrefix }, [
+            tenantTag(fresh.tenant.id),
+            ...tags,
+        ]);
+    });
+}
+/** Every descendant loses authority through fresh lineage evaluation, including across inherited memberships. `issuer` is required, the same as `mintCredential`. */
+export async function revokeCredential(access, db, scopeColumn, issuer, credentialId) {
+    if (access.context === 'break_glass')
+        return refused('break_glass', 'Support sessions cannot revoke credentials.');
+    if (!isUuid(credentialId))
+        return refused('credential_not_found', 'This credential does not exist.');
+    let keysIssuedId = null;
+    const result = await db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.context === 'break_glass' || !permits(fresh, 'credentials:revoke'))
+            return refused('no_permission', 'You cannot revoke credentials here.');
+        const [row] = await tx
+            .select({
+            id: credentials.id,
+            kind: credentials.kind,
+            revokedAt: credentials.revokedAt,
+            keysIssuedId: credentials.keysIssuedId,
+        })
+            .from(credentials)
+            .where(and(eq(credentials.id, credentialId), eq(credentials.tenantId, fresh.tenant.id)));
+        if (!row)
+            return refused('credential_not_found', 'This credential does not belong here.');
+        if (row.revokedAt)
+            return refused('already_revoked', 'This credential was already revoked.');
+        await tx.update(credentials).set({ revokedAt: new Date() }).where(eq(credentials.id, row.id));
+        keysIssuedId = row.keysIssuedId;
+        await tx
+            .delete(memberships)
+            .where(identityWhere(fresh.tenant.id, { id: row.id, class: row.kind }));
+        await record(tx, fresh, {
+            action: 'credential.revoked',
+            tenantId: fresh.tenant.id,
+            targetType: 'credential',
+            targetId: row.id,
+        });
+        const tags = await propagateMembershipChange(tx, fresh.binding, writerFromAccess(fresh), fresh.tenant.id, row.id);
+        return done(undefined, [tenantTag(fresh.tenant.id), ...tags]);
+    });
+    // After the transaction commits, not inside it: `issuer.revoke()` opens its
+    // own transaction against a host's shared `db` handle, a different
+    // connection than `tx` above, so nesting it inside `tx` would let it commit
+    // a keys-side revoke that this transaction could still roll back.
+    // `credentials.revoked_at` is what a host's own bearer path actually gates
+    // on, so a crash between the two leaves this credential refused either way
+    // -- never leaves it live. Null on a pre-cutover row, which has nothing in
+    // `keys_issued_credentials` to revoke. A failure here is logged, not
+    // thrown: the revoke above has committed, so the caller's answer is
+    // already true.
+    if (result.ok && keysIssuedId) {
+        try {
+            await issuer.revoke(keysIssuedId);
+        }
+        catch (error) {
+            console.error('[credentials] keys-side revoke failed; the credential is refused', error);
+        }
+    }
+    return result;
+}
+/**
+ * A second name for `credentials`, so a row's own issuer -- when the issuer
+ * is itself a credential rather than a person -- can be joined without
+ * colliding with the row it names.
+ */
+const issuerCredentials = alias(credentials, 'issuer_credentials');
+export async function credentialsFor(access, db, names) {
+    if (!(await permitsRead(access, db, 'credentials:read')))
+        return null;
+    const rows = await db
+        .select({
+        id: credentials.id,
+        kind: credentials.kind,
+        name: credentials.name,
+        secretPrefix: credentials.secretPrefix,
+        createdAt: credentials.createdAt,
+        expiresAt: credentials.expiresAt,
+        revokedAt: credentials.revokedAt,
+        lastUsedAt: credentials.lastUsedAt,
+        role: sql `case when ${memberships.principalId} is null then null else ${primaryRoleKey(access.binding)} end`,
+        issuerId: credentials.issuerId,
+        issuerClass: credentials.issuerClass,
+        // Exactly one of these two resolves, depending on `issuerClass`: a
+        // human issuer's id (looked up through `names` below) or the
+        // credential that minted this one. Neither can match the other's row
+        // (`issuerClass` picks one path), so there is never a fan-out to
+        // coalesce away.
+        issuerCredentialName: issuerCredentials.name,
+    })
+        .from(credentials)
+        .leftJoin(memberships, and(eq(memberships.tenantId, credentials.tenantId), eq(memberships.principalClass, credentials.kind), sql `${memberships.principalId}=${credentials.id}::text`))
+        // `credentials.id` is `uuid`; `issuerId` is `text` because it also has to
+        // hold a human's string subject id. Casting the uuid side to text, not
+        // the other way round, is the same direction the `memberships` join
+        // above already takes.
+        .leftJoin(issuerCredentials, and(eq(credentials.issuerClass, issuerCredentials.kind), sql `${issuerCredentials.id}::text = ${credentials.issuerId}`))
+        .where(eq(credentials.tenantId, access.tenant.id))
+        .orderBy(desc(credentials.createdAt));
+    const humanIssuerIds = [
+        ...new Set(rows.filter((r) => r.issuerClass === 'human').map((r) => r.issuerId)),
+    ];
+    const personName = humanIssuerIds.length
+        ? await names.personNames(humanIssuerIds)
+        : new Map();
+    return rows.map(({ issuerId, issuerClass, issuerCredentialName, ...r }) => ({
+        ...r,
+        issuer: (issuerClass === 'human' ? personName.get(issuerId) : undefined) ??
+            issuerCredentialName ??
+            'An issuer no longer on record',
+    }));
+}

package/dist/denial.d.ts

@@ -0,0 +1,9 @@
+import type { ResourceDenial } from '@wtfalch/authz';
+import type { Access } from './types.js';
+/**
+ * Only `explain` moves here. The host's `DENIAL_EVENTS` table maps a permission id to one core
+ * event name, keyed to that one host's own permission ids — a table like that belongs to the
+ * host that defines the permissions, not to a package with no catalogue of its own — so it stays
+ * in the hosts.
+ */
+export declare function explain(source: ResourceDenial | null, permission: string, access: Access): string;

package/dist/denial.js

@@ -0,0 +1,49 @@
+/**
+ * Only `explain` moves here. The host's `DENIAL_EVENTS` table maps a permission id to one core
+ * event name, keyed to that one host's own permission ids — a table like that belongs to the
+ * host that defines the permissions, not to a package with no catalogue of its own — so it stays
+ * in the hosts.
+ */
+export function explain(source, permission, access) {
+    const operation = access.binding.catalogue[permission]?.label ?? permission;
+    if (source === null)
+        return `You may ${operation}.`;
+    switch (source) {
+        case 'state':
+            return `This organisation is ${access.tenant.state}.`;
+        case 'ceiling':
+            return `This organisation has not been offered ${operation}.`;
+        case 'self_denied':
+            return `This organisation has disabled ${operation}.`;
+        case 'session':
+            return `${operation} is unavailable in this support session.`;
+        case 'frozen':
+            return `${operation} is unavailable while the platform is frozen.`;
+        case 'depth':
+            return `${operation} can only be held directly by a person, never delegated.`;
+        case 'cosign':
+            return `${operation} needs another person's approval before it takes effect.`;
+        case 'budget':
+            return `${operation} has reached its limit for this period.`;
+        case 'purpose':
+            return `${operation} needs a stated purpose that matches what this grant allows.`;
+        case 'conditions':
+            return `${operation} does not meet the conditions this grant requires.`;
+        case 'boundary':
+            return `${operation} does not reach this organisation.`;
+        case 'kind':
+            return `${operation} does not apply to this kind of organisation.`;
+        case 'denied':
+            return `${operation} has been explicitly denied here.`;
+        case 'unknown':
+            return `${operation} is not a recognised operation.`;
+        case 'grant':
+            return `Your current assignments do not allow ${operation} here.`;
+        case 'guest':
+            return `${operation} is not available to a guest.`;
+        default: {
+            const exhaustive = source;
+            return exhaustive;
+        }
+    }
+}

package/dist/erase.d.ts

@@ -0,0 +1,58 @@
+import type { DbOrTx, Scope } from './scoped.js';
+import type { Access, Result } from './types.js';
+/**
+ * Stable and derived from the subject id, never random and never a counter:
+ * the same person has to read the same way across every row of theirs and
+ * across two separate runs of this function, or the log stops being
+ * followable at exactly the moment somebody needs to follow it. sha256 of
+ * the id, truncated to 16 hex characters purely to keep the column short; a
+ * truncated cryptographic hash still makes finding a second id that collides
+ * with it infeasible.
+ */
+export declare function pseudonymFor(subjectId: string): string;
+export interface ErasePersonResult {
+    /** How many `authz_events` rows the sweep touched. Zero on a second call: `erased_at` is already set, so nothing matches. */
+    readonly rowsErased: number;
+}
+/**
+ * What a host must supply about the person being erased and its own
+ * personal-data tables. `profiles` and `reporting_erase_person` were
+ * Boule's own reads and writes against tables this package does not own;
+ * this port replaces both. `emailOf` replaces the `profiles` read (the
+ * email is what almost every audit payload carrying this person's data
+ * actually holds, and most of those rows were written by somebody else, so
+ * the sweep needs the address to reach rows that are ABOUT this person
+ * rather than only rows written BY them). `eraseHostRecords` replaces both
+ * the `profiles` scrub and the analytics erase: person rows go, rollups
+ * carry no identifier and stay.
+ */
+export interface ErasureHost {
+    emailOf(tx: DbOrTx, principalId: string): Promise<string | null>;
+    eraseHostRecords(tx: DbOrTx, principalId: string, pseudonym: string): Promise<void>;
+}
+/**
+ * Erases a person from the record: `actor_id` and every row survive, so
+ * "someone with this id did this" still holds; `actor_display` and the
+ * personal fields inside `before`/`after` become a stable pseudonym, and
+ * whatever personal fields the host's own tables carry are scrubbed the same
+ * way through `host.eraseHostRecords` (D9, X6 M3).
+ *
+ * Gated on the operator tenant's own `people:erase`: operator scope,
+ * sensitive and unassignable, the same shape `owners:install` has, so only
+ * the operator tenant's owner holds it. A caller reaches this through its
+ * own permission check first, which is what a host wires up to write the
+ * denied `person.erased` row on a refusal; this function's own checks are
+ * the second net, the same as `installOwner`'s.
+ *
+ * Refused under a break-glass context (D8): no session ever changes the
+ * record of what happened, and rewriting it is exactly that.
+ *
+ * One transaction, in this order and never the other way round: the sweep
+ * through `erase_person` and `host.eraseHostRecords` first, then the
+ * `person.erased` audit row. Writing the event first would make it a
+ * candidate for its own sweep the moment the erased subject is the
+ * operator's own id (self-erasure), since the sweep matches on `actor_id`,
+ * and the erasure would then have no record of itself. Written after, it is
+ * never touched by the call that just ran.
+ */
+export declare function erasePerson(operatorAccess: Access, db: DbOrTx, scopeColumn: Scope['column'], principalId: string, host: ErasureHost): Promise<Result<ErasePersonResult>>;

package/dist/erase.js

@@ -0,0 +1,108 @@
+import { createHash } from 'node:crypto';
+import { sql } from 'drizzle-orm';
+import { record } from './audit.js';
+import { permitsPlatform, refreshAccess } from './policy-access.js';
+import { done, refused } from './types.js';
+/**
+ * The single sanctioned write to `authz_events` (D9, X6 M3, Tests 29).
+ *
+ * `migrations/0006_erase_person.sql`'s `erase_person` is a `SECURITY
+ * DEFINER` function owned by the migration role: the runtime role has no
+ * UPDATE on `authz_events` at all (0001's grants), and a trigger refuses any
+ * UPDATE on that table touching a column outside `actor_display`, `before`,
+ * `after` and `erased_at` (0001). The function passes the first wall
+ * because it runs with the owner's privileges, and it passes the second by
+ * construction, touching only those four columns, never around the trigger.
+ * This module is the only caller; a host wires it up so that nothing else
+ * in the app may erase a row, because nothing else holds `people:erase`.
+ *
+ * This file takes the host's raw handle the same way `install-owner.ts`
+ * does: `erasePerson` has no tenant to be scoped to (a person's audit rows
+ * span every tenant they ever acted in) and opens the one transaction it
+ * runs in itself.
+ */
+/**
+ * Non-secret prefix on every erasure pseudonym, so a reader recognises one on
+ * sight without the prefix itself revealing anything about the id it
+ * replaced.
+ */
+const PSEUDONYM_PREFIX = 'erased-person-';
+/**
+ * Stable and derived from the subject id, never random and never a counter:
+ * the same person has to read the same way across every row of theirs and
+ * across two separate runs of this function, or the log stops being
+ * followable at exactly the moment somebody needs to follow it. sha256 of
+ * the id, truncated to 16 hex characters purely to keep the column short; a
+ * truncated cryptographic hash still makes finding a second id that collides
+ * with it infeasible.
+ */
+export function pseudonymFor(subjectId) {
+    const digest = createHash('sha256').update(subjectId).digest('hex').slice(0, 16);
+    return `${PSEUDONYM_PREFIX}${digest}`;
+}
+/** postgres-js returns the rows as the result; node-postgres and PGlite wrap them in `rows` (migrate.ts's own `rowsOf`, one raw call). */
+function rowsOf(result) {
+    return Array.isArray(result) ? result : (result.rows ?? []);
+}
+/**
+ * Erases a person from the record: `actor_id` and every row survive, so
+ * "someone with this id did this" still holds; `actor_display` and the
+ * personal fields inside `before`/`after` become a stable pseudonym, and
+ * whatever personal fields the host's own tables carry are scrubbed the same
+ * way through `host.eraseHostRecords` (D9, X6 M3).
+ *
+ * Gated on the operator tenant's own `people:erase`: operator scope,
+ * sensitive and unassignable, the same shape `owners:install` has, so only
+ * the operator tenant's owner holds it. A caller reaches this through its
+ * own permission check first, which is what a host wires up to write the
+ * denied `person.erased` row on a refusal; this function's own checks are
+ * the second net, the same as `installOwner`'s.
+ *
+ * Refused under a break-glass context (D8): no session ever changes the
+ * record of what happened, and rewriting it is exactly that.
+ *
+ * One transaction, in this order and never the other way round: the sweep
+ * through `erase_person` and `host.eraseHostRecords` first, then the
+ * `person.erased` audit row. Writing the event first would make it a
+ * candidate for its own sweep the moment the erased subject is the
+ * operator's own id (self-erasure), since the sweep matches on `actor_id`,
+ * and the erasure would then have no record of itself. Written after, it is
+ * never touched by the call that just ran.
+ */
+export async function erasePerson(operatorAccess, db, scopeColumn, principalId, host) {
+    if (operatorAccess.context === 'break_glass') {
+        return refused('break_glass', 'A support session never erases a person.');
+    }
+    if (operatorAccess.tenant.kind !== 'operator' ||
+        !permitsPlatform(operatorAccess, 'people:erase')) {
+        return refused('no_permission', 'You do not have permission to erase a person.');
+    }
+    if (principalId.length === 0) {
+        return refused('invalid_principal', 'A person id is required.');
+    }
+    const pseudonym = pseudonymFor(principalId);
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, operatorAccess);
+        if (!fresh || fresh.context !== 'operator' || !permitsPlatform(fresh, 'people:erase'))
+            return refused('no_permission', 'Your authority changed.');
+        const currentAccess = fresh;
+        // Read before the sweep clears it; see the `ErasureHost` doc for why
+        // this needs the address rather than only the actor id.
+        const rawEmail = await host.emailOf(tx, principalId);
+        const subjectEmail = rawEmail?.trim().toLowerCase() ?? null;
+        const result = await tx.execute(sql `select erase_person(${principalId}, ${pseudonym}, ${subjectEmail}) as touched`);
+        const [row] = rowsOf(result);
+        const rowsErased = Number(row?.touched ?? 0);
+        // The host's own personal-data tables: `profiles` and whatever an
+        // analytics package tracks. Called here so it commits with the rest.
+        await host.eraseHostRecords(tx, principalId, pseudonym);
+        await record(tx, currentAccess, {
+            action: 'person.erased',
+            tenantId: null,
+            targetType: 'person',
+            targetId: principalId,
+            after: { pseudonym },
+        });
+        return done({ rowsErased }, []);
+    });
+}

package/dist/events.d.ts

@@ -0,0 +1,77 @@
+import type { DbOrTx } from './scoped.js';
+import type { Access } from './types.js';
+/**
+ * Reading the audit trail back.
+ *
+ * Newest first, keyset-paged on `(occurred_at, id)` descending, which is
+ * exactly `authz_events_tenant_time_idx`. Offset paging would re-scan the
+ * whole prefix on every page of a table that only grows, and this one is
+ * appended to by every grant, revoke, state change and break-glass session
+ * in the app.
+ */
+/** One row of the trail, without its payload. See `EventsForOptions.tenantId` for the scope. */
+export interface EventSummary {
+    readonly id: number;
+    readonly occurredAt: Date;
+    readonly tenantId: string | null;
+    readonly actorClass: string;
+    readonly actorId: string;
+    readonly actorDisplay: string;
+    readonly action: string;
+    readonly targetType: string;
+    readonly targetId: string;
+    readonly outcome: string;
+    readonly context: string;
+    readonly reason: string | null;
+    readonly reference: string | null;
+    /**
+     * `erased_at` is set, so `before` and `after` were nulled by
+     * `erasePerson` and the row is a tombstone with its shape intact. Said
+     * plainly rather than shown as an empty change, because "nothing changed"
+     * and "we no longer keep what changed" are different facts and a reader
+     * who cannot tell them apart mis-reads the trail.
+     */
+    readonly erased: boolean;
+}
+export interface EventPage {
+    readonly items: readonly EventSummary[];
+    readonly next: {
+        readonly occurredAt: Date;
+        readonly id: number;
+    } | null;
+}
+export interface EventsForOptions {
+    /**
+     * One tenant's rows. Omitted means this `Access`'s own tenant, unless the
+     * actor holds `audit:read-all`, in which case it means every tenant — the
+     * operator console's view of the estate.
+     */
+    readonly tenantId?: string;
+    readonly actorId?: string;
+    readonly action?: string;
+    readonly after?: {
+        readonly occurredAt: Date;
+        readonly id: number;
+    };
+    readonly limit?: number;
+}
+/**
+ * One page of the trail, or `null` when this `Access` may not read it.
+ *
+ * **`null`, never an empty page**, for the reason `membersOf` gives: a caller
+ * that cannot tell "you may not see this" from "there is nothing to see"
+ * draws a false conclusion, and here the false conclusion is "nothing has
+ * happened in this organisation", which is the opposite of what an audit
+ * surface exists to say.
+ *
+ * Two permissions, and the difference is not cosmetic. `audit:read` reads
+ * one's own tenant. `audit:read-all` reads every tenant, and only it sees
+ * rows with `tenant_visible = false` — the operator-only rows, which is where
+ * a break-glass session into somebody's organisation is recorded. A tenant
+ * admin reading their own log must not be shown those, or the support session
+ * they were never told about becomes visible in a list they can already open.
+ * So the flag is applied here, not left to the page: a page that forgot it
+ * would leak by omission, and this is the only place that knows both the
+ * actor's permissions and the row.
+ */
+export declare function eventsFor(access: Access, db: DbOrTx, options?: EventsForOptions): Promise<EventPage | null>;