@wtfalch/authz-store 0.3.0 → 0.5.0

package/README.md

@@ -15,10 +15,24 @@ package rather than a subpath on the engine.
 
 ## Status
 
-**Published.** `@wtfalch/authz-store` is on npm at 0.2.1. "Depend" here means a
-pin in that host's `package.json`, not a verified deployment: Boule (`manage`)
-pins 0.2.1, `people` pins 0.2.1, and otf's `web/` pins 0.2.0. archon still carries its own copy of
-this layer, unmoved.
+**Published at 0.4.0; host adoption is incomplete.** Checked on 2026-09-30
+against the npm registry (latest 0.4.0, shasum
+`9305f37cc20d79a469cbaacde80990e295ebc2df`) and the repository manifest.
+The registry exports both the main entry and the client-safe `./policy` entry.
+Extraction waves 1–11 are implemented in this package; publishing issues
+[#123](https://github.com/wtfalch/authz/issues/123) and
+[#128](https://github.com/wtfalch/authz/issues/128) are closed.
+
+Current host pins and remaining adoption work are recorded in the
+[shared persistence map](../../docs/shared-persistence-map.md#current-status-2026-09-30).
+A manifest pin establishes a source dependency, not a deployment or full
+adoption. Archon pins 0.4.0 and has merged wave 1, with a local access-loader
+exception pending [#130](https://github.com/wtfalch/authz/issues/130). Boule
+pins 0.2.1, OTF `web/` pins 0.2.0, and the people package pins 0.2.1.
+
+The following wave notes describe the extraction steps in order. References
+to modules being host-side at a particular wave describe that step, not the
+current adoption status of every host.
 
 Moved so far: credential secrets, the `ScopedDb` seam, every table definition,
 `ownerCoverage`, wave 1 (authz#83): `StoreBinding` (the `applicationId`,
@@ -235,9 +249,10 @@ cycle; a later issue in the people repo makes it reuse this copy rather than
 carry its own. Every row helper is exported under a name distinct from its
 policy-layer counterpart (`insertMembershipRow`, `deleteMembershipRow`,
 `changeRoleRow`, `guardStaysHeldRow`, `membersOfRow`), since the two layers
-would otherwise claim the same five names on one package surface; none of
-the five is part of this package's public surface, since nothing outside
-`src/memberships.ts` needs them. `identityWhere` is not duplicated: people's
+would otherwise claim the same five names on one package surface. As of
+0.4.0 (https://github.com/wtfalch/people/issues/16) all five are exported
+from the main entry, so `@wtfalch/people` can call this copy instead of
+carrying its own — see the 0.4.0 note below. `identityWhere` is not duplicated: people's
 own copy tests the same three columns as `src/assignments.ts`'s, in a
 different argument order `and()` doesn't care about, so `membership-rows.ts`
 imports that one. `roster.js`'s `profiles` left join (a member with no
@@ -326,7 +341,7 @@ otf, not moved.
 Wave 11d (authz#83) moves Boule's own `src/lib/authz/erase.ts`, `alerts.ts`
 and `startup.ts` into `src/erase.ts`, `src/alerts.ts` and `src/startup.ts`.
 `erase.ts` moves `pseudonymFor` and `erasePerson`, the one sanctioned write
-to `authz_events`; the SQL function it calls (`erase_person`, `SECURITY
+to `authz_events`; the SQL function it calls (`authz_erase_person`, `SECURITY
 DEFINER`, a pinned `search_path`) ships as `migrations/0006_erase_person.sql`,
 sweeping `authz_events` and `invitations` the way Boule's
 `drizzle/0008_erasure_and_boot.sql` did. Boule's own function also scrubbed
@@ -346,8 +361,29 @@ to check simply does not call it, rather than this framework-neutral package
 reading `process.env` to decide the same thing for itself — and its
 `housekeeping` becomes a second structural port, `HousekeepingRegistry`.
 
-The rest of the host layer has not moved — tracked in
-https://github.com/wtfalch/authz/issues/83.
+0.4.0 (authz#83 round 2, files#112): `loadAccess`'s credential-chain walk in
+`src/policy-access.ts` now selects only `issuerId`, `issuerClass`, `expiresAt`
+and `revokedAt` off `credentials`, instead of every column. files and ai
+dropped `secret_hash`, `secret_prefix` and `keys_issued_id` on purpose, and a
+plain `select()` there named them anyway, failing every service-credential
+request with "column does not exist". `export.ts`, `person-records.ts` and
+`credentials.ts` already select explicit column lists and were left as they
+are: each genuinely needs the secret/keys column it names (an export row's
+`secretPrefix`, a revoke's `keysIssuedId`, `credentialsFor`'s display
+`secretPrefix`), so narrowing further would break them, not fix them.
+
+0.4.0 also renames the SQL function `migrations/0006_erase_person.sql`
+creates, from `erase_person` to `authz_erase_person`. The old name collided
+with each host's own erasure function of the same name and signature, which
+also scrubs a host's `profiles`; `migrateStore`'s `CREATE OR REPLACE FUNCTION`
+replaced a host's function outright, silently dropping that scrub. 0.3.0
+published an hour before this fix and no persistent database had applied
+0006 yet, so this is a same-file rename, not a new numbered migration.
+`src/erase.ts` calls `authz_erase_person`.
+
+Extraction is complete through wave 11. Remaining host adoption and the
+resource-resolution extension are tracked in
+https://github.com/wtfalch/authz/issues/83 and the current-status map above.
 
 New here, not moved: `authz_grants`, grants stored per person rather than
 compiled from a role, and `guestGrants`, which reads a tenant's guest grants
@@ -361,6 +397,43 @@ the tables from the drizzle definitions. `src/migrate.test.ts` applies the
 shipped SQL instead and fails when the two disagree on a column, a type,
 nullability or an index name.
 
+## 0.4.0
+
+`StoreBinding` (`src/binding.ts`) gains `hostEvents?: readonly string[]`: a host's own audit
+event names (archon: `flag.changed`, `cms.published`, `key.rotated`; files/ai/integrations:
+`mail.*`, `storage.*`, `integrations.*`), beyond `@wtfalch/authz`'s core events, so a host writes
+its own events through the same `record`/`recordAs`/`writeServiceEvent` path core events use,
+never a second one of its own (authz#83, archon#72). `definePolicy(data, binding)` accepts
+`hostEvents` in `binding` and carries it onto the returned `StorePolicy`; a `hostEvents` name that
+repeats a core event name is a configuration error and `definePolicy` throws. `recordAs` and
+`writeServiceEvent` each gain an optional trailing `binding` parameter, since neither had one to
+read `hostEvents` off before.
+
+`EventInput.action` (on `record`, `recordAs` and `writeServiceEvent`) is now `EventName |
+(string & {})`: core names still autocomplete, and any other string is accepted only when it is
+listed in the binding's `hostEvents`; anything else throws before the row is built any further,
+naming the action. **The store's own baseline `authz_events_action_check` constraint still lists
+core events only** — this package's migrations are unchanged. A host that adopts `hostEvents` must
+widen that CHECK in its own migration first (hosts that don't adopt keep their existing
+constraint as-is).
+
+0.4.0 (authz#83 round 2) adds a `./policy` subpath export
+(https://github.com/wtfalch/boule/pull/162): `definePolicy` plus `StorePolicy`,
+`StoreBinding`, `PolicyData` and `PolicyRoleTemplate`, and nothing else, for a
+client component that only needs the policy catalogue for permission labels.
+The main entry (`.`) still exports everything it does today — this is
+additive — but it also drags in `migrateStore`, which imports
+`node:fs/promises` and breaks a production client build; `./policy`'s import
+graph is proved free of any `node:` module, `drizzle-orm` or a database handle
+by `scripts/tests/package-contract.test.mjs`. 0.4.0 also exports the five
+membership row helpers from `src/membership-rows.ts` off the main entry —
+`insertMembershipRow`, `deleteMembershipRow`, `changeRoleRow`,
+`guardStaysHeldRow`, `membersOfRow` — so `@wtfalch/people` can call this
+package's copy instead of carrying its own
+(https://github.com/wtfalch/people/issues/16). No behaviour change: each
+helper writes an audit row only when a `MembershipRowAuditOptions` writer is
+passed, exactly as before.
+
 ## Migrations
 
 The package ships its own SQL in `migrations/`, and `migrateStore(db)` applies
@@ -377,18 +450,28 @@ app owns:
   list that app's offered permissions.
 - The foreign key from `break_glass_sessions.operator_id` to `profiles`.
 
-The baseline is for a new database. manage and otf `web/` already have these
-tables, so each needs a one-off reconciliation: bring the schema to the
-baseline, then insert `0001_baseline.sql` into `authz_store_migrations` by
-hand. otf also lacks `authz_roles.updated_by` and the `'activation'`
-assignment source.
-
-What a host must supply is growing, and it is all explicit: a module that needs
-the host's `APPLICATION_ID` and `PLATFORM_ID` takes them as a `PolicyBinding`
-argument rather than importing them, because the two applications differ there.
-
-The remaining ~12,800 lines, and the one-off migration each application needs to
-adopt them, are not started.
+The baseline is for a new database. An existing host must verify its schema
+and migration history before adopting it. Its reconciliation brings the
+schema to the baseline before recording `0001_baseline.sql` in
+`authz_store_migrations`; it must preserve runtime-role privileges and the
+host-specific constraints above. The historical map records OTF's missing
+`authz_roles.updated_by` and `'activation'` assignment source; verify these
+against the host being migrated rather than assuming that snapshot is current.
+
+Version 0.4.0 creates `authz_erase_person`, keeping host erasure separate.
+A host whose database already recorded an older `0006_erase_person.sql` must
+check which function was installed: changing a dependency pin does not replay
+an applied migration. Reconcile with a new additive host migration and retain
+host-owned profile/reporting scrubs. Boule's upgrade prerequisite is tracked
+in [boule#163](https://github.com/wtfalch/boule/issues/163). No deployed migration
+history was inspected for this status update.
+
+Hosts pass their application id, platform id and catalogue through
+`StoreBinding`/`StorePolicy`; the store does not import host constants.
+
+The remaining work is adoption of the extracted modules, host resource-resolution
+support and each host's verified reconciliation. Follow the current-status map
+and host issues; the historical line count is not a current migration estimate.
 
 ## Why it is not part of `@wtfalch/authz`
 
@@ -407,3 +490,43 @@ framework-neutral package cannot import it, so that import is dropped here. A
 host that wants the guard re-exports these functions through its own
 `server-only` module. `generateCredentialSecret` reaching a client bundle is the
 thing worth preventing.
+
+
+## Host resource lookups
+
+`StoreBinding.resolveResource` extends `policyResource`, `loadAccess` and `refreshAccess`
+with authoritative metadata for host-owned resource types (authz#130). The callback receives
+the caller's database transaction and an immutable target containing `applicationId`,
+`platformId`, `organisationId`, `type` and `id`. It returns an `AccessResource` or `undefined`:
+
+```ts
+const policy = definePolicy(catalogueData, {
+  applicationId: APPLICATION_ID,
+  platformId: PLATFORM_ID,
+  resolveResource: async (tx, target) => {
+    if (target.type !== 'files.file') return undefined;
+    // This host function queries its own table using BOTH organisationId and id.
+    const row = await findFile(tx, target.organisationId, target.id);
+    if (!row) return undefined;
+    return {
+      ...target,
+      teamId: row.teamId,
+      owner: { id: row.ownerId, class: row.ownerClass },
+    };
+  },
+});
+```
+
+This callback is trusted server configuration. The host must query authoritative rows
+in the supplied transaction, constrain them to the requested organisation and resource,
+and return `undefined` for missing resources or optional modules. The store rejects a
+result with a different application, platform, organisation, type or id. Lookup errors
+propagate. An unresolved resource cannot establish the team containment needed to
+delegate a team-scoped grant to one resource. Core `team` and `audit`
+lookups keep their store checks and never fall through to the callback.
+
+`definePolicy` retains the callback on the binding, so `refreshAccess` uses it when
+re-reading credential lineage before a mutation. Keep callbacks and their database
+imports in server modules; the `./policy` export remains safe to import for client
+catalogue labels. This API requires the next store release; published 0.4.0 does not
+include it. Host adoption and release remain separate steps under authz#83.

package/dist/activations.js

@@ -108,7 +108,8 @@ function entryBoundary(catalogue, permission, tenantId) {
  * calling `compileRoleGrants`: eligibility only needs to know a permission is
  * *named*, not perform a full grant compile, and a standing custom role can
  * never contain a non-assignable permission in the first place (creating one
- * would already have failed `roleAssignmentRefusal`), so nothing here can
+ * would already have failed `roleAssignmentRefusal`: a custom role has no
+ * guards and is not keyed `owner`), so nothing here can
  * throw the way minting a fresh role below can.
  */
 async function eligibleElevatedPermissions(tx, binding, tenantId, elevated, principal) {
@@ -231,10 +232,10 @@ export async function requestActivation(access, db, scopeColumn, policy, options
         }
         if (refusal !== null) {
             // compileRoleGrants throws for any entry whose permission is
-            // `assignable: false` on a non-built-in role -- see Boule's own
-            // comment (activations.ts): every coApproval permission was one of
-            // these on the package version this file was ported from, so none of
-            // them could be minted into an activation's role either.
+            // `assignable: false` on a role that is neither keyed `owner` nor
+            // guarded by an owner-only permission for an `ownerGuarded` entry. An
+            // activation's minted role is neither, so a permission like that
+            // cannot be minted into one.
             return refused('invalid_role', 'One or more of these permissions cannot yet be granted through a time-boxed activation.');
         }
         await tx.insert(policyRoles).values({

package/dist/audit.d.ts

@@ -1,4 +1,5 @@
 import { type ActorClass, type Context, type EventName, type Outcome } from '@wtfalch/authz';
+import type { StoreBinding } from './binding.js';
 import type { DbOrTx } from './scoped.js';
 import type { Access, Principal } from './types.js';
 /**
@@ -6,6 +7,10 @@ import type { Access, Principal } from './types.js';
  * context, the session, the timestamp, the schema version) is filled in by
  * `record`, `recordAs` or `writeServiceEvent` below, never by the caller, so
  * a feature module cannot sign a row as someone it is not (D9).
+ *
+ * `action` accepts a core `EventName` (still autocompletes) or any other
+ * string (0.4.0): a host's own event, checked at write time against the
+ * `hostEvents` on the binding reachable from the call — see `insertEvent`.
  */
 export interface EventInput {
     readonly teamId?: string;
@@ -13,7 +18,7 @@ export interface EventInput {
         readonly id: string;
         readonly class: ActorClass;
     };
-    readonly action: EventName;
+    readonly action: EventName | (string & {});
     readonly tenantId: string | null;
     readonly targetType: string;
     readonly targetId: string;
@@ -50,20 +55,28 @@ export declare function record(tx: DbOrTx, access: Access, input: EventInput): P
  * resolves nothing before the tenant row exists, so there is no membership
  * to build one from. Never carries a break-glass session, because there is
  * no session without an `Access` to hold it.
+ *
+ * `binding` (0.4.0) is optional because every call inside this package
+ * writes a core event; it exists so a caller recording its own host event
+ * through `recordAs` (there is no `Access` here to read one from, unlike
+ * `record`) can pass whatever `StoreBinding` it has in scope.
  */
-export declare function recordAs(tx: DbOrTx, actor: Principal, context: Context, input: EventInput): Promise<void>;
+export declare function recordAs(tx: DbOrTx, actor: Principal, context: Context, input: EventInput, binding?: StoreBinding): Promise<void>;
 /**
  * The bootstrap, migration, deploy and job rows: written as `service`, never
  * as a person or a credential, because nothing signed in to cause them.
  * `context` defaults to `standard`; pass `'operator'` for a row about the
  * operator tenant specifically (an operator-only system role changing, say).
+ *
+ * `binding` (0.4.0): this function had no binding parameter before, so one
+ * is added here, optional, for a caller recording its own host event.
  */
 export declare function writeServiceEvent(tx: DbOrTx, actor: {
     readonly id: string;
     readonly display: string;
 }, input: EventInput & {
     readonly context?: 'standard' | 'operator';
-}): Promise<void>;
+}, binding?: StoreBinding): Promise<void>;
 /** One row of the tenant's own security log, already narrowed to what the tenant may see. */
 export interface SecurityLogEntry {
     readonly id: number;

package/dist/audit.js

@@ -2,6 +2,14 @@ import { authzEventSchema, core, tenantVisibleByDefault, } from '@wtfalch/authz'
 import { and, desc, eq, lt, or } from 'drizzle-orm';
 import { permitsRead } from './policy-access.js';
 import { authzEvents } from './schema.js';
+/** The core event list as a plain set, for a fast membership check against a caller's action. */
+const CORE_EVENTS = new Set(core.events);
+/**
+ * Any one core event name, used only to stand in for a validated host action
+ * when `insertEvent` asks `authzEventSchema` to check every other field
+ * (see the comment there) — never written to a row.
+ */
+const FIRST_CORE_EVENT = core.events[0];
 /**
  * The one place a row actually gets built and inserted. Every field the
  * schema requires is filled in here, the candidate row is validated with
@@ -13,8 +21,25 @@ import { authzEvents } from './schema.js';
  * inside a transaction; callers that need this row atomic with another
  * write (which is every authority write except a service log) pass their
  * own transaction through.
+ *
+ * `hostEvents` (0.4.0) is the calling binding's own event names, beyond the
+ * core list. `action` is accepted when it is a core event or listed in
+ * `hostEvents`; anything else throws here, before `row` is built any
+ * further and before anything reaches `tx.insert`, naming the action in the
+ * message. `authzEventSchema`'s own `action` field only knows the core
+ * list (it lives in `@wtfalch/authz`, which has no notion of a host's
+ * vocabulary), so once a host action has passed the membership check above,
+ * the schema is asked to validate a copy of `row` with `action` swapped for
+ * an arbitrary core event — every other field is still validated exactly as
+ * `authzEventSchema` does today, and the swapped value is never the one
+ * written; `row.action` (the real value) is what actually reaches the insert
+ * below.
  */
-async function insertEvent(tx, actor, context, sessionId, input) {
+async function insertEvent(tx, actor, context, sessionId, input, hostEvents) {
+    const isCoreAction = CORE_EVENTS.has(input.action);
+    if (!isCoreAction && !hostEvents?.includes(input.action)) {
+        throw new Error(`unknown audit action "${input.action}": not a core event and not listed in this binding's hostEvents`);
+    }
     const occurredAt = new Date();
     const row = {
         occurred_at: occurredAt.toISOString(),
@@ -33,13 +58,17 @@ async function insertEvent(tx, actor, context, sessionId, input) {
         request_id: input.request?.id ?? null,
         ip: input.request?.ip ?? null,
         user_agent: input.request?.userAgent ?? null,
+        // A host event is outside the core `tenantVisible` list by construction
+        // (`tenantVisibleByDefault` only knows core `EventName`s), so it defaults
+        // to false unless the caller says otherwise; the cast is safe because the
+        // function only ever does a `Set.has` lookup against a plain string.
         tenant_visible: input.tenantVisible ?? tenantVisibleByDefault(input.action),
         before: input.before ?? null,
         after: input.after ?? null,
         erased_at: null,
         schema_version: core.version,
     };
-    authzEventSchema.parse(row);
+    authzEventSchema.parse(isCoreAction ? row : { ...row, action: FIRST_CORE_EVENT });
     await tx.insert(authzEvents).values({
         occurredAt,
         tenantId: row.tenant_id,
@@ -93,26 +122,34 @@ export async function record(tx, access, input) {
             reference: input.reference ?? grant.reference,
         }
         : input;
-    await insertEvent(tx, { class: access.actor.class, id: access.actor.id, display: access.actor.display }, access.context, access.breakGlass?.id ?? null, withSession);
+    await insertEvent(tx, { class: access.actor.class, id: access.actor.id, display: access.actor.display }, access.context, access.breakGlass?.id ?? null, withSession, access.binding.hostEvents);
 }
 /**
  * The same insert for a write with no `Access` yet: self-serve `createTenant`
  * resolves nothing before the tenant row exists, so there is no membership
  * to build one from. Never carries a break-glass session, because there is
  * no session without an `Access` to hold it.
+ *
+ * `binding` (0.4.0) is optional because every call inside this package
+ * writes a core event; it exists so a caller recording its own host event
+ * through `recordAs` (there is no `Access` here to read one from, unlike
+ * `record`) can pass whatever `StoreBinding` it has in scope.
  */
-export async function recordAs(tx, actor, context, input) {
-    await insertEvent(tx, { class: actor.class, id: actor.id, display: actor.display }, context, null, input);
+export async function recordAs(tx, actor, context, input, binding) {
+    await insertEvent(tx, { class: actor.class, id: actor.id, display: actor.display }, context, null, input, binding?.hostEvents);
 }
 /**
  * The bootstrap, migration, deploy and job rows: written as `service`, never
  * as a person or a credential, because nothing signed in to cause them.
  * `context` defaults to `standard`; pass `'operator'` for a row about the
  * operator tenant specifically (an operator-only system role changing, say).
+ *
+ * `binding` (0.4.0): this function had no binding parameter before, so one
+ * is added here, optional, for a caller recording its own host event.
  */
-export async function writeServiceEvent(tx, actor, input) {
+export async function writeServiceEvent(tx, actor, input, binding) {
     const { context = 'standard', ...rest } = input;
-    await insertEvent(tx, { class: 'service', id: actor.id, display: actor.display }, context, null, rest);
+    await insertEvent(tx, { class: 'service', id: actor.id, display: actor.display }, context, null, rest, binding?.hostEvents);
 }
 /**
  * The tenant's own security log: what happened to this organisation's

package/dist/binding.d.ts

@@ -1,5 +1,12 @@
-import type { ResourceCatalogue, ResourcePermission } from '@wtfalch/authz';
+import type { AccessResource, ResourceCatalogue, ResourcePermission } from '@wtfalch/authz';
 import type { PolicyBinding } from './owners.js';
+import type { DbOrTx } from './scoped.js';
+/** Exact tenant resource identity requested by the shared access loader. */
+export type ResourceTarget = Pick<AccessResource, 'applicationId' | 'platformId' | 'type' | 'id'> & {
+    readonly organisationId: string;
+};
+/** A trusted host lookup, using the caller's transaction and tenant predicate. */
+export type HostResourceResolver = (tx: DbOrTx, target: ResourceTarget) => Promise<AccessResource | undefined>;
 /**
  * `PolicyBinding` (`applicationId`, `platformId`) plus the host's own resource catalogue. The
  * store has no catalogue of its own — each host defines its own permissions — so every moved
@@ -8,6 +15,23 @@ import type { PolicyBinding } from './owners.js';
  */
 export interface StoreBinding extends PolicyBinding {
     readonly catalogue: ResourceCatalogue;
+    /**
+     * Resolve host-owned resource types for delegation and credential lineage. Return undefined
+     * for an absent module or resource. Query authoritative rows in `tx`, constrained to the
+     * requested organisation and id. Team and audit resources remain store-owned. A result
+     * whose application, platform, organisation, type or id differs from the target is rejected.
+     * Lookup errors propagate; they never confer access.
+     */
+    readonly resolveResource?: HostResourceResolver;
+    /**
+     * The host's own audit event names, beyond `@wtfalch/authz`'s core events (0.4.0). A host
+     * records its own events (archon: `flag.changed`, `cms.published`, `key.rotated`; files/ai/
+     * integrations: `mail.*`, `storage.*`, `integrations.*`) through the same `record`/`recordAs`/
+     * `writeServiceEvent` write path core events use, rather than a second one of its own. The
+     * store's own baseline `authz_events_action_check` constraint lists core events only; a host
+     * that lists names here must widen that check in its own migration.
+     */
+    readonly hostEvents?: readonly string[];
 }
 /**
  * The one lookup every moved module did as `catalogue[permission]`. A tiny helper rather than

package/dist/boot.d.ts

@@ -1,4 +1,4 @@
-import type { TenantKind } from '@wtfalch/authz';
+import { type TenantKind } from '@wtfalch/authz';
 import type { StoreBinding } from './binding.js';
 import type { StorePolicy } from './policy.js';
 import type { DbOrTx } from './scoped.js';
@@ -35,9 +35,11 @@ export declare function ensureBuiltInRoles(tx: DbOrTx, policy: StorePolicy, tena
  * exist from before this change shipped) without duplicating or throwing.
  *
  * Stored `built_in: true`, not the `false` `starterRoles()` itself declares,
- * for the reasons the host's own boot.ts documents (`@wtfalch/authz`'s
- * `compileRoleGrants` refuses a non-`assignable` entry unless the role is
- * `built_in`, and today's owner/admin templates carry several).
+ * for the reasons the host's own boot.ts documents. `built_in` does not let a
+ * role hold a locked power: `@wtfalch/authz`'s `compileRoleGrants` lets a
+ * non-`assignable` entry onto the role keyed `owner`, or, for an
+ * `ownerGuarded` permission, onto a role guarded by an owner-only permission,
+ * whatever the row's `built_in` flag says.
  */
 export declare function seedStarterRoles(tx: DbOrTx, policy: StorePolicy, tenant: {
     id: string;

package/dist/boot.js

@@ -1,5 +1,7 @@
 import { randomUUID } from 'node:crypto';
+import { compileRoleGrants, resourceRoleSchema, } from '@wtfalch/authz';
 import { and, eq } from 'drizzle-orm';
+import { primaryAssignment } from './assignments.js';
 import { writeServiceEvent } from './audit.js';
 import { policyRole, requirePolicySchema } from './policy-access.js';
 import { policyRoles } from './policy-schema.js';
@@ -27,14 +29,49 @@ export const content = (role) => canonical({
     label: role.label,
     description: role.description,
 });
+/**
+ * A stored role that does not compile makes `loadPolicyState` throw for every access check in the
+ * tenant, and an unchanged revision is never rewritten, so refuse such a template before anything
+ * is written. The schema is checked first, then each entry alone so the error can name the
+ * permission.
+ */
+function assertTemplateCompiles(policy, template) {
+    const parsed = resourceRoleSchema.safeParse({ id: 'template', ...template });
+    if (!parsed.success)
+        throw new Error(`Role template ${template.key} is invalid: ${parsed.error.issues
+            .map((i) => `${i.path.join('.') || '(role)'}: ${i.message}`)
+            .join('; ')}`);
+    const role = parsed.data;
+    const assignment = primaryAssignment(role, { id: 'template', class: 'human' });
+    for (const entry of role.entries) {
+        try {
+            compileRoleGrants({ ...role, entries: [entry] }, assignment, policy.catalogue);
+        }
+        catch {
+            const p = Object.hasOwn(policy.catalogue, entry.permission)
+                ? policy.catalogue[entry.permission]
+                : undefined;
+            const shapeOk = p?.scopes.includes(entry.scope.kind) &&
+                p.boundaries.includes(entry.boundary.kind) &&
+                p.relations.includes(entry.relation);
+            throw new Error(p && shapeOk && !p.assignable
+                ? `Role template ${template.key} cannot hold ${entry.permission}: it is a locked (non-assignable) permission this role may not hold. Mark it ownerGuarded in the catalogue and guard the role with an owner-only permission (non-assignable, not ownerGuarded).`
+                : `Role template ${template.key} has an entry for ${entry.permission} that does not fit the catalogue: unknown permission, or a scope, boundary or relation it does not allow.`);
+        }
+    }
+}
 /** Called in the tenant creation/deploy transaction while its tenant row is locked. */
 export async function ensureBuiltInRoles(tx, policy, tenant) {
+    // Validate every template before the first write, so a bad one never leaves a partial write.
+    const templates = policy.builtInRoles(tenant.id, tenant.kind);
+    for (const template of templates)
+        assertTemplateCompiles(policy, template);
     const rows = await tx
         .select()
         .from(policyRoles)
         .where(and(eq(policyRoles.tenantId, tenant.id), eq(policyRoles.applicationId, policy.applicationId), eq(policyRoles.platformId, policy.platformId)));
     const result = [];
-    for (const template of policy.builtInRoles(tenant.id, tenant.kind)) {
+    for (const template of templates) {
         const existing = rows.find((r) => r.key === template.key);
         let status = 'unchanged';
         if (existing) {
@@ -99,12 +136,17 @@ export async function ensureBuiltInRoles(tx, policy, tenant) {
  * exist from before this change shipped) without duplicating or throwing.
  *
  * Stored `built_in: true`, not the `false` `starterRoles()` itself declares,
- * for the reasons the host's own boot.ts documents (`@wtfalch/authz`'s
- * `compileRoleGrants` refuses a non-`assignable` entry unless the role is
- * `built_in`, and today's owner/admin templates carry several).
+ * for the reasons the host's own boot.ts documents. `built_in` does not let a
+ * role hold a locked power: `@wtfalch/authz`'s `compileRoleGrants` lets a
+ * non-`assignable` entry onto the role keyed `owner`, or, for an
+ * `ownerGuarded` permission, onto a role guarded by an owner-only permission,
+ * whatever the row's `built_in` flag says.
  */
 export async function seedStarterRoles(tx, policy, tenant) {
-    const rows = policy.starterRoles(tenant.id, tenant.kind).map((template) => ({
+    const templates = policy.starterRoles(tenant.id, tenant.kind);
+    for (const template of templates)
+        assertTemplateCompiles(policy, template);
+    const rows = templates.map((template) => ({
         id: randomUUID(),
         tenantId: tenant.id,
         applicationId: policy.applicationId,

package/dist/erase.d.ts

@@ -39,7 +39,7 @@ export interface ErasureHost {
  *
  * 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
+ * the role keyed `owner` in the operator tenant can hold 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.
@@ -48,7 +48,7 @@ export interface ErasureHost {
  * 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
+ * through `authz_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`,

package/dist/erase.js

@@ -6,7 +6,7 @@ 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
+ * `migrations/0006_erase_person.sql`'s `authz_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`,
@@ -53,7 +53,7 @@ function rowsOf(result) {
  *
  * 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
+ * the role keyed `owner` in the operator tenant can hold 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.
@@ -62,7 +62,7 @@ function rowsOf(result) {
  * 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
+ * through `authz_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`,
@@ -90,7 +90,7 @@ export async function erasePerson(operatorAccess, db, scopeColumn, principalId,
         // 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 result = await tx.execute(sql `select authz_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

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { attachProposals, authzEvents, breakGlassSessions, credentials, invitati
 export { ownerCoverage, ownerSeatCovered, principalIsReachable, type OwnerCoverage, type OwnerCoverageOptions, type PolicyBinding, } from './owners.js';
 export { migrateStore } from './migrate.js';
 export { guestGrants, policyGrants, type GrantStatus, type GuestGrant } from './grants.js';
-export { permissionOf, type StoreBinding } from './binding.js';
+export { permissionOf, type StoreBinding, type HostResourceResolver, type ResourceTarget, } from './binding.js';
 export { isCustomRoleKey } from './role-keys.js';
 export { type Access, type BreakGlassGrant, type Context, type Principal, type Result, type TenantRow, done, isUuid, refused, tenantTag, } from './types.js';
 export { policyResource } from './policy-resources.js';
@@ -38,3 +38,4 @@ export { archiveTeam, assignAppRole, changeTeamParticipant, deleteAppRole, remov
 export { exportTenant, type ExportActor, type ExportedAttachProposal, type ExportedAuditRow, type ExportedCredential, type ExportedInvitation, type ExportedMembership, type ExportedRole, type ExportedTenant, } from './export.js';
 export { eventsFor, type EventPage, type EventsForOptions, type EventSummary, } from './events.js';
 export { platformFrozen, setPlatformFrozen } from './platform.js';
+export { changeRoleRow, deleteMembershipRow, guardStaysHeldRow, insertMembershipRow, membersOfRow, type ChangeRoleRowInput, type ChangeRoleRowResult, type DeleteMembershipRowInput, type DeleteMembershipRowResult, type InsertMembershipRowInput, type InsertMembershipRowResult, type MembershipRosterRow, type MembershipRowAuditActor, type MembershipRowAuditEvent, type MembershipRowAuditOptions, } from './membership-rows.js';

package/dist/index.js

@@ -6,7 +6,7 @@ export { attachProposals, authzEvents, breakGlassSessions, credentials, invitati
 export { ownerCoverage, ownerSeatCovered, principalIsReachable, } from './owners.js';
 export { migrateStore } from './migrate.js';
 export { guestGrants, policyGrants } from './grants.js';
-export { permissionOf } from './binding.js';
+export { permissionOf, } from './binding.js';
 export { isCustomRoleKey } from './role-keys.js';
 export { done, isUuid, refused, tenantTag, } from './types.js';
 export { policyResource } from './policy-resources.js';
@@ -38,3 +38,4 @@ export { archiveTeam, assignAppRole, changeTeamParticipant, deleteAppRole, remov
 export { exportTenant, } from './export.js';
 export { eventsFor, } from './events.js';
 export { platformFrozen, setPlatformFrozen } from './platform.js';
+export { changeRoleRow, deleteMembershipRow, guardStaysHeldRow, insertMembershipRow, membersOfRow, } from './membership-rows.js';

package/dist/memberships.js

@@ -176,6 +176,10 @@ export async function changeRole(access, db, scopeColumn, options) {
         const reason = roleAssignmentRefusal(fresh, role, primaryAssignment(role, principal, previous?.expiresAt?.getTime()), self ? null : 'members:grant');
         if (reason)
             return refused(self ? 'self_promotion' : reason, 'You cannot delegate that role.');
+        // A self-change skips the `members:grant` operation (and with it the guard check) above, but a
+        // guarded role must still only reach someone who holds every guard.
+        if (self && role.guards.some((guard) => !permits(fresh, guard)))
+            return refused('self_promotion', 'You cannot delegate that role.');
         if (before &&
             before.id !== role.id &&
             !(await guardStaysHeld(tx, fresh.binding, fresh.tenant.id, [policyRole(before)], principal)))

package/dist/policy-access.js

@@ -277,8 +277,17 @@ export async function loadAccess(tx, binding, db, scopeColumn, principal, tenant
             if (visited.has(`${cursor.class}:${cursor.id}`) || visited.size >= 32)
                 return null;
             visited.add(`${cursor.class}:${cursor.id}`);
+            // Narrow to the columns this walk reads: a service-credential chain
+            // never needs `secretHash`/`secretPrefix`/`keysIssuedId`, and a host
+            // that dropped those columns (files, ai) would otherwise fail every
+            // request through this path with "column does not exist".
             const [credential] = await tx
-                .select()
+                .select({
+                issuerId: credentials.issuerId,
+                issuerClass: credentials.issuerClass,
+                expiresAt: credentials.expiresAt,
+                revokedAt: credentials.revokedAt,
+            })
                 .from(credentials)
                 .where(and(eq(credentials.id, cursor.id), eq(credentials.kind, cursor.class)))
                 .limit(1);

package/dist/policy-entry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@wtfalch/authz-store/policy` — a client-safe subpath for `definePolicy` and the types its
+ * signature needs. The main entry (`.`) re-exports `migrateStore`, which imports
+ * `node:fs/promises`, so a client component that only reads the policy catalogue for permission
+ * labels cannot import from `.` without pulling Node into a production browser build
+ * (https://github.com/wtfalch/boule/pull/162). Nothing this module imports, directly or
+ * transitively, may import a `node:` module, `drizzle-orm`, or a database handle — proved by
+ * `scripts/tests/package-contract.test.mjs`.
+ */
+export { definePolicy, type PolicyData, type PolicyRoleTemplate, type StorePolicy, } from './policy.js';
+export type { StoreBinding, HostResourceResolver, ResourceTarget } from './binding.js';

package/dist/policy-entry.js

@@ -0,0 +1,10 @@
+/**
+ * `@wtfalch/authz-store/policy` — a client-safe subpath for `definePolicy` and the types its
+ * signature needs. The main entry (`.`) re-exports `migrateStore`, which imports
+ * `node:fs/promises`, so a client component that only reads the policy catalogue for permission
+ * labels cannot import from `.` without pulling Node into a production browser build
+ * (https://github.com/wtfalch/boule/pull/162). Nothing this module imports, directly or
+ * transitively, may import a `node:` module, `drizzle-orm`, or a database handle — proved by
+ * `scripts/tests/package-contract.test.mjs`.
+ */
+export { definePolicy, } from './policy.js';

package/dist/policy-resources.js

@@ -4,14 +4,16 @@ import { authzEvents } from './schema.js';
 import { isUuid } from './types.js';
 /** Authoritative resource metadata, shared by delegation and credential lineage evaluation. */
 export async function policyResource(tx, binding, organisationId, type, id) {
-    const base = {
+    const base = Object.freeze({
         applicationId: binding.applicationId,
         platformId: binding.platformId,
         organisationId,
         type,
         id,
-    };
-    if (type === 'team' && isUuid(id)) {
+    });
+    if (type === 'team') {
+        if (!isUuid(id))
+            return undefined;
         const [row] = await tx
             .select({ id: accessTeams.id })
             .from(accessTeams)
@@ -19,7 +21,9 @@ export async function policyResource(tx, binding, organisationId, type, id) {
             .limit(1);
         return row ? { ...base, teamId: id } : undefined;
     }
-    if (type === 'audit' && /^\d{1,15}$/.test(id)) {
+    if (type === 'audit') {
+        if (!/^\d{1,15}$/.test(id))
+            return undefined;
         const [row] = await tx
             .select({
             teamId: authzEvents.teamId,
@@ -42,5 +46,13 @@ export async function policyResource(tx, binding, organisationId, type, id) {
                 : {}),
         };
     }
-    return undefined;
+    const resource = await binding.resolveResource?.(tx, base);
+    if (!resource ||
+        resource.applicationId !== base.applicationId ||
+        resource.platformId !== base.platformId ||
+        resource.organisationId !== base.organisationId ||
+        resource.type !== base.type ||
+        resource.id !== base.id)
+        return undefined;
+    return resource;
 }

package/dist/policy.d.ts

@@ -57,8 +57,16 @@ export interface StorePolicy extends StoreBinding {
  * Builds a `StorePolicy` from a host's own `policy-catalogue.json` data and its
  * `{ applicationId, platformId }`. Generic over the host's data because every host's catalogue
  * differs; this function is the one piece of that shape both applications wrote identically.
+ *
+ * `binding.hostEvents` (0.4.0), when given, is carried onto the returned `StorePolicy` unchanged
+ * so `record`/`recordAs`/`writeServiceEvent` can validate a host's own audit actions against it.
+ * A name in `hostEvents` that repeats a core event name is a configuration error — it would make
+ * an audit row ambiguous about which vocabulary it came from — so this throws rather than let it
+ * pass silently.
  */
 export declare function definePolicy(data: PolicyData, binding: {
     readonly applicationId: string;
     readonly platformId: string;
+    readonly hostEvents?: readonly string[];
+    readonly resolveResource?: StoreBinding['resolveResource'];
 }): StorePolicy;

package/dist/policy.js

@@ -1,10 +1,22 @@
-import { defineResourceCatalogue, } from '@wtfalch/authz';
+import { core, defineResourceCatalogue, } from '@wtfalch/authz';
 /**
  * Builds a `StorePolicy` from a host's own `policy-catalogue.json` data and its
  * `{ applicationId, platformId }`. Generic over the host's data because every host's catalogue
  * differs; this function is the one piece of that shape both applications wrote identically.
+ *
+ * `binding.hostEvents` (0.4.0), when given, is carried onto the returned `StorePolicy` unchanged
+ * so `record`/`recordAs`/`writeServiceEvent` can validate a host's own audit actions against it.
+ * A name in `hostEvents` that repeats a core event name is a configuration error — it would make
+ * an audit row ambiguous about which vocabulary it came from — so this throws rather than let it
+ * pass silently.
  */
 export function definePolicy(data, binding) {
+    const coreEvents = new Set(core.events);
+    for (const name of binding.hostEvents ?? []) {
+        if (coreEvents.has(name)) {
+            throw new Error(`definePolicy: hostEvents "${name}" collides with a core event name; a host event must not reuse one`);
+        }
+    }
     const namespaces = [
         ...new Set(Object.keys(data.permissions).map((key) => key.split(/[.:]/)[0])),
     ];
@@ -46,6 +58,8 @@ export function definePolicy(data, binding) {
         applicationId: binding.applicationId,
         platformId: binding.platformId,
         catalogue,
+        hostEvents: binding.hostEvents,
+        resolveResource: binding.resolveResource,
         defaultCeiling: data.defaultCeiling,
         maxDepth: data.maxDepth,
         elevated: new Set(data.elevated),

package/dist/role-keys.d.ts

@@ -1,7 +1,8 @@
 /**
  * Custom role keys always start with `c_` (enforced at creation, the host's `createRole`); every
  * other key — including a starter role's, whether or not its row is still `built_in` — names an
- * app-defined role. Several modules need "is this key one this app controls" rather than "is this
+ * app-defined role. `built_in` says nothing about which permissions a role may hold: that is
+ * the role key `owner` or an owner-only guard (`compileRoleGrants`). Several modules need "is this key one this app controls" rather than "is this
  * row currently marked built-in", because a starter role's `built_in` flag can differ between an
  * old tenant (`true`) and a new one (`false`) while the key means the same thing in both (ADR
  * 0016). No imports, so any module can depend on it without risking a cycle.

package/dist/role-keys.js

@@ -1,7 +1,8 @@
 /**
  * Custom role keys always start with `c_` (enforced at creation, the host's `createRole`); every
  * other key — including a starter role's, whether or not its row is still `built_in` — names an
- * app-defined role. Several modules need "is this key one this app controls" rather than "is this
+ * app-defined role. `built_in` says nothing about which permissions a role may hold: that is
+ * the role key `owner` or an owner-only guard (`compileRoleGrants`). Several modules need "is this key one this app controls" rather than "is this
  * row currently marked built-in", because a starter role's `built_in` flag can differ between an
  * old tenant (`true`) and a new one (`false`) while the key means the same thing in both (ADR
  * 0016). No imports, so any module can depend on it without risking a cycle.

package/dist/roles.d.ts

@@ -11,13 +11,19 @@ export interface EditableRole extends ResourceRole {
     readonly editable: boolean;
 }
 export declare function rolesForEditor(access: Access): Promise<EditableRole[]>;
-/** Definition edits must cover both its full scope and every existing recipient/scope. */
+/**
+ * Definition edits must cover both its full scope and every existing recipient/scope, and the
+ * editor must hold every guard of the role (an owner-guarded role can only be edited by someone
+ * the guards admit, i.e. an owner). Callers check the role both before and after an edit.
+ */
 export declare function canEditDefinition(access: Access, role: ResourceRole): boolean;
 export interface CreateRoleOptions {
     readonly key: string;
     readonly name: string;
     readonly description?: string;
     readonly entries: ResourceRole['entries'];
+    /** Catalogue permissions the editor must hold to assign or edit the role; default none. */
+    readonly guards?: readonly string[];
 }
 export interface UpdateRoleOptions {
     readonly key: string;
@@ -25,6 +31,8 @@ export interface UpdateRoleOptions {
     readonly name?: string;
     readonly description?: string;
     readonly entries?: ResourceRole['entries'];
+    /** Replaces the guards; the editor must hold every old and every new guard. */
+    readonly guards?: readonly string[];
 }
 export interface DeleteRoleOptions {
     readonly key: string;

package/dist/roles.js

@@ -31,14 +31,21 @@ export async function rolesForEditor(access) {
         editable: !role.builtIn && permits(access, 'roles:update') && canEditDefinition(access, role),
     }));
 }
-/** Definition edits must cover both its full scope and every existing recipient/scope. */
+/**
+ * Definition edits must cover both its full scope and every existing recipient/scope, and the
+ * editor must hold every guard of the role (an owner-guarded role can only be edited by someone
+ * the guards admit, i.e. an owner). Callers check the role both before and after an edit.
+ */
 export function canEditDefinition(access, role) {
+    if (role.guards.some((guard) => !permits(access, guard)))
+        return false;
     if (roleAssignmentRefusal(access, role, primaryAssignment(role, { id: 'prospective-person', class: 'human' }), null))
         return false;
     return access.policyState.assignmentRows
         .filter((a) => a.roleId === role.id && (!a.expiresAt || a.expiresAt.getTime() > Date.now()))
         .every((a) => !roleAssignmentRefusal(access, role, policyAssignment(a), null));
 }
+const knownGuards = (access, guards) => guards.every((g) => Object.hasOwn(access.binding.catalogue, g));
 const invalid = () => refused('invalid_role', 'Choose valid operations, boundaries and scopes within your authority.');
 export async function createRole(access, db, scopeColumn, options) {
     if (access.context === 'break_glass')
@@ -49,6 +56,9 @@ export async function createRole(access, db, scopeColumn, options) {
             return refused('no_permission', 'You cannot create roles here.');
         if (!/^c_[a-z0-9_-]{1,61}$/.test(options.key))
             return refused('invalid_key', 'Choose a custom role key starting with c_.');
+        const guards = [...new Set(options.guards ?? [])];
+        if (!knownGuards(fresh, guards))
+            return invalid();
         const candidate = resourceRoleSchema.safeParse({
             id: randomUUID(),
             key: options.key,
@@ -60,7 +70,7 @@ export async function createRole(access, db, scopeColumn, options) {
             revision: 1,
             builtIn: false,
             entries: options.entries,
-            guards: [],
+            guards,
         });
         if (!candidate.success || !canEditDefinition(fresh, candidate.data))
             return invalid();
@@ -84,7 +94,7 @@ export async function createRole(access, db, scopeColumn, options) {
             revision: role.revision,
             builtIn: false,
             entries: role.entries,
-            guards: [],
+            guards: role.guards,
             createdBy: fresh.actor.id,
         });
         await record(tx, fresh, {
@@ -116,9 +126,11 @@ export async function updateRole(access, db, scopeColumn, options) {
             label: options.name ?? before.label,
             description: options.description ?? before.description,
             entries: options.entries ?? before.entries,
+            guards: options.guards ? [...new Set(options.guards)] : before.guards,
             revision: before.revision + 1,
         });
         if (!parsed.success ||
+            !knownGuards(fresh, parsed.data.guards) ||
             !canEditDefinition(fresh, before) ||
             !canEditDefinition(fresh, parsed.data))
             return invalid();
@@ -129,6 +141,7 @@ export async function updateRole(access, db, scopeColumn, options) {
             name: after.label,
             description: after.description,
             entries: after.entries,
+            guards: after.guards,
             revision: after.revision,
             updatedAt: new Date(),
             // ADR 0016's Aged-and-Independent approver rule reads this to exclude

package/dist/schema.d.ts

@@ -1457,6 +1457,23 @@ export declare const authzEvents: import("drizzle-orm/pg-core").PgTableWithColum
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        tenantDisplay: import("drizzle-orm/pg-core").PgColumn<{
+            name: "tenant_display";
+            tableName: "authz_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         teamId: import("drizzle-orm/pg-core").PgColumn<{
             name: "team_id";
             tableName: "authz_events";
@@ -1610,6 +1627,23 @@ export declare const authzEvents: import("drizzle-orm/pg-core").PgTableWithColum
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        targetDisplay: import("drizzle-orm/pg-core").PgColumn<{
+            name: "target_display";
+            tableName: "authz_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         outcome: import("drizzle-orm/pg-core").PgColumn<{
             name: "outcome";
             tableName: "authz_events";

package/dist/schema.js

@@ -169,6 +169,10 @@ export const authzEvents = pgTable('authz_events', {
     id: bigint('id', { mode: 'number' }).generatedAlwaysAsIdentity().primaryKey(),
     occurredAt: timestamp('occurred_at', { withTimezone: true }).notNull().default(sql `now()`),
     tenantId: uuid('tenant_id'),
+    // What the tenant was CALLED when this happened, beside its id so the row still reads once
+    // the organisation is closed. Null on a row written before this column existed, or when
+    // tenantId itself is null. Never rewritten once set (authz_events_guard enforces it).
+    tenantDisplay: text('tenant_display'),
     teamId: uuid('team_id'),
     subjectId: text('subject_id'),
     subjectClass: text('subject_class'),
@@ -178,6 +182,9 @@ export const authzEvents = pgTable('authz_events', {
     action: text('action').notNull(),
     targetType: text('target_type').notNull(),
     targetId: text('target_id').notNull(),
+    // Same as tenantDisplay, for the target: what it was CALLED when this happened. Null on a row
+    // written before this column existed.
+    targetDisplay: text('target_display'),
     outcome: text('outcome').notNull(),
     context: text('context').notNull(),
     sessionId: text('session_id'),

package/dist/tenants.d.ts

@@ -204,8 +204,8 @@ export declare function createTenantAsOperator(operatorAccess: Access, db: DbOrT
 export declare function deleteJustCreatedTenant(operatorAccess: Access, db: DbOrTx, scopeColumn: Scope['column'], tenantId: string): Promise<Result<void>>;
 /**
  * Archives a tenant from inside it, by whoever holds `tenant:delete` there
- * (the owner: the permission is not assignable, so no other system role
- * carries it). Refused while the tenant holds children (D19's fifth rule):
+ * (the owner: the permission is not assignable and not owner-guarded, so no
+ * role other than the one keyed `owner` can carry it). Refused while the tenant holds children (D19's fifth rule):
  * an archived parent's own state says nothing about the organisations
  * hanging off it, so those must be detached or archived on purpose first,
  * not silently along for the ride.

package/dist/tenants.js

@@ -761,8 +761,8 @@ export async function deleteJustCreatedTenant(operatorAccess, db, scopeColumn, t
 }
 /**
  * Archives a tenant from inside it, by whoever holds `tenant:delete` there
- * (the owner: the permission is not assignable, so no other system role
- * carries it). Refused while the tenant holds children (D19's fifth rule):
+ * (the owner: the permission is not assignable and not owner-guarded, so no
+ * role other than the one keyed `owner` can carry it). Refused while the tenant holds children (D19's fifth rule):
  * an archived parent's own state says nothing about the organisations
  * hanging off it, so those must be detached or archived on purpose first,
  * not silently along for the ride.

package/migrations/0006_erase_person.sql

@@ -9,8 +9,17 @@
 --
 -- Additive, per every other file in this directory: never edit this file
 -- once shipped, a change is a new numbered one.
+--
+-- 0.4.0 note: this function was originally named `erase_person`, the same
+-- name and signature as each host's own erasure function (the one that also
+-- scrubs `profiles`). `migrateStore` replaces a same-named function outright,
+-- so applying this migration silently dropped a host's own `profiles` scrub.
+-- Renamed here to `authz_erase_person` before any persistent database ever
+-- applied it: 0.3.0 published an hour before this fix, and no host had run
+-- this migration against a real database yet, so this is a same-file rename,
+-- not a new numbered migration.
 
--- ------------------------------------------------------- erase_person(...)
+-- ----------------------------------------------- authz_erase_person(...)
 -- The single sanctioned write to `authz_events` (D9, M3).
 --
 -- Two walls stand between the running app and its own audit log, and this
@@ -40,7 +49,7 @@
 -- unqualified name through the caller's `search_path` runs whatever they put
 -- in front of it, with the owner's privileges, which is the standard way
 -- this feature becomes a privilege escalation.
-CREATE OR REPLACE FUNCTION "erase_person"("subject" text, "pseudonym" text, "subject_email" text)
+CREATE OR REPLACE FUNCTION "authz_erase_person"("subject" text, "pseudonym" text, "subject_email" text)
 RETURNS integer
 LANGUAGE plpgsql
 SECURITY DEFINER
@@ -50,10 +59,10 @@ DECLARE
   touched integer;
 BEGIN
   IF "subject" IS NULL OR length("subject") = 0 THEN
-    RAISE EXCEPTION 'erase_person: a subject id is required';
+    RAISE EXCEPTION 'authz_erase_person: a subject id is required';
   END IF;
   IF "pseudonym" IS NULL OR length("pseudonym") = 0 OR length("pseudonym") > 256 THEN
-    RAISE EXCEPTION 'erase_person: a pseudonym of 1 to 256 characters is required';
+    RAISE EXCEPTION 'authz_erase_person: a pseudonym of 1 to 256 characters is required';
   END IF;
 
   -- Rows this person WROTE, and rows written ABOUT them.
@@ -115,7 +124,7 @@ $$;
 -- runtime role may be handed this one without gaining any other access to
 -- the table. Revoked from PUBLIC first, since Postgres grants EXECUTE on a
 -- new function to PUBLIC by default.
-REVOKE ALL ON FUNCTION "erase_person"(text, text, text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION "authz_erase_person"(text, text, text) FROM PUBLIC;
 --> statement-breakpoint
 
 -- The store has no runtime-role convention of its own, unlike Boule's fixed
@@ -128,7 +137,7 @@ DECLARE
   rt text := current_database() || '_rt';
 BEGIN
   IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = rt) THEN
-    EXECUTE format('GRANT EXECUTE ON FUNCTION "erase_person"(text, text, text) TO %I', rt);
+    EXECUTE format('GRANT EXECUTE ON FUNCTION "authz_erase_person"(text, text, text) TO %I', rt);
   END IF;
 END
 $$;

package/migrations/0007_event_display_columns.sql

@@ -0,0 +1,52 @@
+-- authz_events gains target_display and tenant_display, matching how
+-- actor_display already works: written once by whoever signs the row, never
+-- rewritten afterward. See https://github.com/wtfalch/authz/issues/69.
+ALTER TABLE "authz_events" ADD COLUMN "tenant_display" text;
+--> statement-breakpoint
+ALTER TABLE "authz_events" ADD COLUMN "target_display" text;
+--> statement-breakpoint
+ALTER TABLE "authz_events" ADD CONSTRAINT "authz_events_tenant_display_check"
+  CHECK (((tenant_display IS NULL) OR ((length(tenant_display) >= 1) AND (length(tenant_display) <= 256))));
+--> statement-breakpoint
+ALTER TABLE "authz_events" ADD CONSTRAINT "authz_events_target_display_check"
+  CHECK (((target_display IS NULL) OR ((length(target_display) >= 1) AND (length(target_display) <= 256))));
+--> statement-breakpoint
+-- Extend the append-only guard: target_display and tenant_display join the immutable set (they are
+-- never rewritten, unlike actor_display/before/after/erased_at, which an erasure may still touch).
+CREATE OR REPLACE FUNCTION authz_events_guard()
+ RETURNS trigger
+ LANGUAGE plpgsql
+AS $function$
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    RAISE EXCEPTION 'authz_events is append-only: delete refused';
+  ELSIF TG_OP = 'TRUNCATE' THEN
+    RAISE EXCEPTION 'authz_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."tenant_display" IS DISTINCT FROM OLD."tenant_display"
+      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."target_display" IS DISTINCT FROM OLD."target_display"
+      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"
+    THEN
+      RAISE EXCEPTION 'authz_events is append-only: only actor_display, before, after and erased_at may change';
+    END IF;
+  END IF;
+  RETURN NEW;
+END
+$function$;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/authz-store",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Persistence and lifecycle for @wtfalch/authz: the storage a host would otherwise write itself.",
   "type": "module",
   "files": [
@@ -13,10 +13,14 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./policy": {
+      "types": "./dist/policy-entry.d.ts",
+      "default": "./dist/policy-entry.js"
+    },
     "./package.json": "./package.json"
   },
   "peerDependencies": {
-    "@wtfalch/authz": "^0.16.0",
+    "@wtfalch/authz": "^0.17.0",
     "@wtfalch/db": "0.4.0",
     "drizzle-orm": ">=0.39.3 <1.0.0",
     "zod": "^4.1.13"