@wtfalch/authz-store 0.4.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`,
@@ -367,8 +381,9 @@ 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`.
 
-The rest of the host layer has not moved — tracked in
-https://github.com/wtfalch/authz/issues/83.
+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
@@ -435,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`
 
@@ -465,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/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,14 @@ 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/

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.

package/dist/erase.js

@@ -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.

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';

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';

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-entry.d.ts

@@ -8,4 +8,4 @@
  * `scripts/tests/package-contract.test.mjs`.
  */
 export { definePolicy, type PolicyData, type PolicyRoleTemplate, type StorePolicy, } from './policy.js';
-export type { StoreBinding } from './binding.js';
+export type { StoreBinding, HostResourceResolver, ResourceTarget } from './binding.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

@@ -68,4 +68,5 @@ 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

@@ -59,6 +59,7 @@ export function definePolicy(data, binding) {
         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/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.4.0",
+  "version": "0.5.0",
   "description": "Persistence and lifecycle for @wtfalch/authz: the storage a host would otherwise write itself.",
   "type": "module",
   "files": [
@@ -20,7 +20,7 @@
     "./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"