@wtfalch/authz-store 0.2.0 → 0.3.0

package/dist/resource-access.js

@@ -0,0 +1,656 @@
+import { randomUUID } from 'node:crypto';
+import { compileRoleGrants, resourceAccess, resourceScopeSchema, } from '@wtfalch/authz';
+import { and, desc, eq, inArray, lt, ne, or, sql } from 'drizzle-orm';
+import { z } from 'zod';
+import { record } from './audit.js';
+import { guardStaysHeld } from './memberships.js';
+import { auditedReadGate, loadAccess, policyRole, refreshAccess, restriction, } from './policy-access.js';
+import { policyResource } from './policy-resources.js';
+import { policyAssignments, policyRoles } from './policy-schema.js';
+import { accessTeamMembers, accessTeams } from './resource-schema.js';
+import { createRole, deleteRole, updateRole } from './roles.js';
+import { authzEvents } from './schema.js';
+import { done, refused, tenantTag } from './types.js';
+/**
+ * Wave 11a (authz#83), moved from Boule's own `src/lib/authz/resource-access.ts` (814 lines):
+ * `resourceOverview`, `saveAppRole`, `assignAppRole`, `removeAppAssignment`, `deleteAppRole`,
+ * `saveTeam`, `archiveTeam`, `changeTeamParticipant`, `scopedAuditLog`, and the shared
+ * `resourceAccessFor` request-time evaluator both Boule and archon read teams, app roles and the
+ * scoped audit log through. Boule's copy was the newest of the two hosts' (archon and otf never
+ * grew `resourceOverview`'s `canReadPeople` field); kept here.
+ *
+ * `APPLICATION_ID`/`PLATFORM_ID`/`catalogue` (Boule's own `policy-catalogue.ts`) become
+ * `access.binding`, the same as every other moved module. Every exported function now takes
+ * `db: DbOrTx` and `scopeColumn: Scope['column']` explicitly — Boule's `db` was its own root
+ * handle, imported directly and defaulted onto `resourceAccessFor`'s second parameter; the store
+ * has no database of its own to default to. `resourceAccessFor` itself reloads access from the
+ * database on every call (Boule's own choice, not a redundancy introduced here): the request-time
+ * evaluator it returns is deliberately re-read fresh rather than trusted from whatever `Access`
+ * the caller already held, so it takes the same `tx`/`db`/`scopeColumn` triple `loadAccess` does.
+ *
+ * `appRolePermissionsSchema` was a module-level zod schema closed over Boule's own `catalogue`
+ * constant; since the store has no catalogue of its own, it is now a function of
+ * `ResourceCatalogue` (`access.binding.catalogue`), and so is the private `roleInputSchema` that
+ * embeds it. Every validation rule inside both is unchanged. `assignmentInput` and `teamInput`
+ * needed no catalogue and stay plain module-level schemas.
+ *
+ * Boule's `import { db } from '@/lib/db/root'` and `import 'server-only'` are gone; its `asc`,
+ * `memberships` (table), `tenants` (table), `TenantRow` and `policyAssignment` imports were
+ * already unused in the original file — five names in all — and are dropped rather than carried
+ * over.
+ */
+const appRolePermissionsSchema = (catalogue) => z
+    .array(z
+    .object({
+    permission: z
+        .string()
+        .refine((key) => Object.hasOwn(catalogue, key), 'Unknown app permission'),
+    relation: z.enum(['any', 'owner', 'actor', 'subject']),
+})
+    .strict())
+    .max(100)
+    .superRefine((entries, ctx) => {
+    const seen = new Set();
+    for (const entry of entries) {
+        if (seen.has(entry.permission) ||
+            !catalogue[entry.permission]?.relations.includes(entry.relation))
+            ctx.addIssue({
+                code: 'custom',
+                message: `Invalid or duplicate choice for ${entry.permission}`,
+            });
+        seen.add(entry.permission);
+    }
+});
+const roleInputSchema = (catalogue) => z
+    .object({
+    id: z.uuid().optional(),
+    revision: z.number().int().positive().optional(),
+    name: z.string().trim().min(1).max(100),
+    description: z.string().trim().max(1000),
+    permissions: appRolePermissionsSchema(catalogue),
+})
+    .strict();
+const assignmentInput = z
+    .object({
+    roleId: z.uuid(),
+    principalId: z.string().min(1).max(256).nullable(),
+    teamId: z.uuid().nullable(),
+    recipientDescendants: z.boolean(),
+    scope: resourceScopeSchema,
+    expiresAt: z.iso.datetime().nullable(),
+})
+    .strict()
+    .refine((v) => (v.principalId === null) !== (v.teamId === null), 'Choose a person or a team')
+    .refine((v) => !v.recipientDescendants || v.teamId !== null, 'Child participants require a team');
+const asPrincipal = (access) => ({
+    id: access.actor.id,
+    class: access.actor.class,
+});
+const target = (access, type, id, teamId = null) => ({
+    applicationId: access.binding.applicationId,
+    platformId: access.binding.platformId,
+    organisationId: access.tenant.id,
+    type,
+    id,
+    teamId,
+});
+/** Every surface consumes the same request-time evaluator and canonical stored assignments. */
+export async function resourceAccessFor(access, tx, db, scopeColumn) {
+    const fresh = await loadAccess(tx, access.binding, db, scopeColumn, access.actor, access.tenant.id);
+    if (!fresh)
+        throw new Error('Organisation participation ended');
+    const state = fresh.policyState;
+    const foreignRoles = await tx
+        .select({ id: policyRoles.id })
+        .from(policyRoles)
+        .where(and(eq(policyRoles.tenantId, access.tenant.id), ne(policyRoles.applicationId, access.binding.applicationId)))
+        .limit(1);
+    return {
+        foreignPolicy: foreignRoles.length > 0,
+        evaluator: fresh.authority,
+        teams: state.teams.filter((t) => t.tenantId === access.tenant.id),
+        participants: state.participants.filter((t) => t.tenantId === access.tenant.id),
+        roleRows: state.roleRows.map((r) => ({
+            ...r,
+            permissions: r.entries.map(({ permission, relation }) => ({ permission, relation })),
+        })),
+        assignmentRows: state.assignmentRows,
+        grants: state.grants,
+        identities: new Map(state.memberRows
+            .filter((m) => m.principalClass === 'human')
+            .map((m) => [m.principalId, { id: m.principalId, class: 'human' }])),
+    };
+}
+async function writer(access, db, scopeColumn, run) {
+    if (access.actor.class !== 'human' || access.context === 'break_glass')
+        return refused('context', 'Use your own signed-in account to change access.');
+    return db.transaction(async (tx) => {
+        const fresh = await refreshAccess(tx, db, scopeColumn, access);
+        if (!fresh || fresh.readOnly)
+            return refused('state', 'This organisation is not open for changes.');
+        return run(tx, fresh, await resourceAccessFor(fresh, tx, db, scopeColumn));
+    });
+}
+const noPermission = () => refused('no_permission', 'Your current roles do not allow this operation in that scope.');
+const auditJson = (value) => JSON.parse(JSON.stringify(value));
+export async function resourceOverview(access, db, scopeColumn) {
+    const state = await resourceAccessFor(access, db, db, scopeColumn);
+    const canReadRoles = state.evaluator.allows('roles:read', target(access, 'role', access.tenant.id));
+    const visibleTeams = state.teams.filter((team) => !team.archivedAt &&
+        state.evaluator.allows('teams:read', target(access, 'team', team.id, team.id)));
+    return {
+        teams: visibleTeams.map((team) => ({
+            ...team,
+            parentId: visibleTeams.some((t) => t.id === team.parentId) ? team.parentId : null,
+            canUpdate: state.evaluator.allows('teams:update', target(access, 'team', team.id, team.id)),
+            canCreateChild: state.evaluator.allows('teams:create', target(access, 'team', team.id, team.id)),
+            canAddPeople: state.evaluator.allows('teams.people:add', target(access, 'team', team.id, team.id)),
+            canRemovePeople: state.evaluator.allows('teams.people:remove', target(access, 'team', team.id, team.id)),
+            canArchive: state.evaluator.allows('teams:archive', target(access, 'team', team.id, team.id)),
+            canReadPeople: state.evaluator.allows('teams.people:read', target(access, 'team', team.id, team.id)),
+        })),
+        participants: state.participants.filter((p) => state.evaluator.allows('teams.people:read', target(access, 'team', p.teamId, p.teamId))),
+        roles: canReadRoles ? state.roleRows : [],
+        assignments: canReadRoles ? state.assignmentRows : [],
+        canReadRoles,
+        canReadTeams: state.evaluator.clauses('teams:read').length > 0,
+        canCreateTeam: state.evaluator.allows('teams:create', target(access, 'team', access.tenant.id)),
+        canCreateRole: state.evaluator.allows('roles:create', target(access, 'role', access.tenant.id)),
+        canAssign: state.evaluator.allows('roles:assign', target(access, 'role', access.tenant.id)),
+        canUnassign: state.evaluator.allows('roles:unassign', target(access, 'role', access.tenant.id)),
+        canDeleteRoles: state.evaluator.allows('roles:delete', target(access, 'role', access.tenant.id)),
+        canEditTeams: state.evaluator.allows('teams:update', target(access, 'team', access.tenant.id)),
+        canEditRoles: state.evaluator.allows('roles:update', target(access, 'role', access.tenant.id)),
+        canReadAudit: state.evaluator.clauses('platform.audit:read').length > 0,
+    };
+}
+export async function saveAppRole(access, db, scopeColumn, input) {
+    const parsed = roleInputSchema(access.binding.catalogue).safeParse(input);
+    if (!parsed.success)
+        return refused('invalid_role', 'Choose valid operations and relations.');
+    const options = parsed.data;
+    const current = await loadAccess(db, access.binding, db, scopeColumn, access.actor, access.tenant.id);
+    if (!current)
+        return noPermission();
+    const previous = options.id
+        ? current.policyState.roleRows.find((r) => r.id === options.id)
+        : undefined;
+    if (options.id && !previous)
+        return refused('missing', 'This role no longer exists.');
+    if (previous &&
+        new Set(previous.entries.map((e) => e.permission)).size !== previous.entries.length)
+        return refused('complex_role', 'Edit this role through the complete policy API so every boundary and scope is preserved.');
+    const entries = options.permissions.map((p) => ({
+        permission: p.permission,
+        relation: p.relation,
+        boundary: previous?.entries.find((e) => e.permission === p.permission)?.boundary ?? {
+            kind: 'organisation',
+            organisationId: access.tenant.id,
+        },
+        scope: previous?.entries.find((e) => e.permission === p.permission)?.scope ?? {
+            kind: 'organisation',
+        },
+    }));
+    if (previous) {
+        const result = await updateRole(access, db, scopeColumn, {
+            key: previous.key,
+            revision: options.revision ?? 0,
+            name: options.name,
+            description: options.description || options.name,
+            entries,
+        });
+        return result.ok ? done({ id: previous.id }, result.tags) : result;
+    }
+    const key = `c_${randomUUID().replaceAll('-', '')}`;
+    const result = await createRole(access, db, scopeColumn, {
+        key,
+        name: options.name,
+        description: options.description || options.name,
+        entries,
+    });
+    if (!result.ok)
+        return result;
+    const [created] = await db
+        .select({ id: policyRoles.id })
+        .from(policyRoles)
+        .where(and(eq(policyRoles.tenantId, access.tenant.id), eq(policyRoles.key, key)));
+    if (!created)
+        throw new Error('Created role missing');
+    return done(created, result.tags);
+}
+function buildAssignmentGrants(access, assignment, role) {
+    try {
+        return compileRoleGrants(policyRole(role), {
+            id: assignment.id ?? 'new',
+            roleId: role.id,
+            applicationId: access.binding.applicationId,
+            platformId: access.binding.platformId,
+            organisationId: access.tenant.id,
+            boundary: assignment.boundary,
+            scope: assignment.scope,
+            recipient: assignment.principalId
+                ? {
+                    kind: 'principal',
+                    principal: { id: assignment.principalId, class: assignment.principalClass },
+                }
+                : {
+                    kind: 'team',
+                    teamId: assignment.teamId,
+                    descendants: assignment.recipientDescendants,
+                },
+            ...(assignment.expiresAt ? { expiresAt: assignment.expiresAt.getTime() } : {}),
+        }, access.binding.catalogue);
+    }
+    catch {
+        return null;
+    }
+}
+export async function assignAppRole(access, db, scopeColumn, input) {
+    const parsed = assignmentInput.safeParse(input);
+    if (!parsed.success)
+        return refused('invalid_assignment', 'Choose a valid role, recipient, scope and expiry.');
+    const options = parsed.data;
+    return writer(access, db, scopeColumn, async (tx, fresh, state) => {
+        if (!state.evaluator.allows('roles:assign', target(fresh, 'role', fresh.tenant.id)))
+            return noPermission();
+        const role = state.roleRows.find((r) => r.id === options.roleId);
+        if (!role)
+            return refused('role', 'This role is unavailable.');
+        if (options.principalId && state.identities.get(options.principalId)?.class !== 'human')
+            return refused('person', 'Choose someone who belongs to this organisation.');
+        const activeTeam = (id) => state.teams.some((t) => t.id === id && !t.archivedAt);
+        if ((options.teamId && !activeTeam(options.teamId)) ||
+            (options.scope.kind === 'team' && !activeTeam(options.scope.teamId)))
+            return refused('team', 'Choose an active team in this organisation.');
+        const expiresAt = options.expiresAt ? new Date(options.expiresAt) : null;
+        if (expiresAt && expiresAt.getTime() <= Date.now())
+            return refused('expiry', 'Choose a future expiry.');
+        if (role.guards.some((p) => !state.evaluator.allows(p, target(fresh, fresh.binding.catalogue[p]?.resourceType ?? 'unknown', fresh.tenant.id))))
+            return noPermission();
+        const candidate = {
+            ...options,
+            expiresAt,
+            tenantId: fresh.tenant.id,
+            applicationId: fresh.binding.applicationId,
+            platformId: fresh.binding.platformId,
+            principalClass: options.principalId ? 'human' : null,
+            boundary: { kind: 'organisation', organisationId: fresh.tenant.id },
+        };
+        const grants = buildAssignmentGrants(fresh, candidate, role);
+        if (!grants)
+            return refused('grant', 'The assignment is invalid.');
+        let resource;
+        if (options.scope.kind === 'resource') {
+            resource = await lookupResource(tx, fresh, options.scope.resourceType, options.scope.resourceId);
+            if (!resource)
+                return refused('resource', 'The selected resource is unavailable.');
+        }
+        if (grants.length === 0 || !grants.every((g) => state.evaluator.canDelegate(g, resource)))
+            return refused('delegation', 'You cannot grant these operations with that data scope.');
+        if (state.assignmentRows.length >= 1000)
+            return refused('limit', 'This organisation already has 1,000 app role assignments.');
+        const [row] = await tx
+            .insert(policyAssignments)
+            .values({ ...candidate, createdBy: fresh.actor.id })
+            .returning({ id: policyAssignments.id });
+        if (!row)
+            throw new Error('Assignment write returned no row');
+        await record(tx, fresh, {
+            action: 'membership.role_changed',
+            tenantId: fresh.tenant.id,
+            targetType: 'app_role_assignment',
+            targetId: row.id,
+            after: auditJson(candidate),
+        });
+        return done(row, [tenantTag(fresh.tenant.id)]);
+    });
+}
+export async function removeAppAssignment(access, db, scopeColumn, id) {
+    if (!z.uuid().safeParse(id).success)
+        return refused('id', 'Invalid assignment.');
+    return writer(access, db, scopeColumn, async (tx, fresh, state) => {
+        if (!state.evaluator.allows('roles:unassign', target(fresh, 'role', fresh.tenant.id)))
+            return noPermission();
+        const row = state.assignmentRows.find((a) => a.id === id);
+        if (!row)
+            return refused('missing', 'This assignment no longer exists.');
+        if (row.source === 'inherited')
+            return refused('inherited', 'Manage this assignment at its source organisation.');
+        const role = state.roleRows.find((r) => r.id === row.roleId);
+        if (!role)
+            return refused('role', 'The role no longer exists.');
+        if (role.guards.some((p) => !state.evaluator.allows(p, target(fresh, fresh.binding.catalogue[p]?.resourceType ?? 'unknown', fresh.tenant.id))))
+            return noPermission();
+        if (row.principalId &&
+            row.principalClass &&
+            !(await guardStaysHeld(tx, fresh.binding, fresh.tenant.id, [policyRole(role)], {
+                id: row.principalId,
+                class: row.principalClass,
+            })))
+            return refused('last_owner', 'Appoint another independent owner first.');
+        const grants = state.grants.filter((g) => g.id.startsWith(`${id}:`));
+        if (!(await Promise.all(grants.map((g) => delegable(tx, fresh, state, g)))).every(Boolean))
+            return refused('delegation', 'This assignment is outside your delegation authority.');
+        await tx
+            .delete(policyAssignments)
+            .where(and(eq(policyAssignments.tenantId, fresh.tenant.id), eq(policyAssignments.id, id)));
+        await record(tx, fresh, {
+            action: 'membership.ended',
+            tenantId: fresh.tenant.id,
+            targetType: 'app_role_assignment',
+            targetId: id,
+            before: auditJson(row),
+        });
+        return done(undefined, [tenantTag(fresh.tenant.id)]);
+    });
+}
+export async function deleteAppRole(access, db, scopeColumn, id) {
+    const current = await loadAccess(db, access.binding, db, scopeColumn, access.actor, access.tenant.id);
+    const role = current?.policyState.roleRows.find((r) => r.id === id);
+    if (!role)
+        return refused('missing', 'This role no longer exists.');
+    return deleteRole(access, db, scopeColumn, { key: role.key });
+}
+const teamInput = z
+    .object({
+    id: z.uuid().optional(),
+    name: z.string().trim().min(1).max(100),
+    parentId: z.uuid().nullable().optional(),
+})
+    .strict();
+export async function saveTeam(access, db, scopeColumn, input) {
+    const parsed = teamInput.safeParse(input);
+    if (!parsed.success)
+        return refused('invalid_team', 'Choose a name and a valid parent team.');
+    return writer(access, db, scopeColumn, async (tx, fresh, state) => {
+        const previous = parsed.data.id
+            ? state.teams.find((t) => t.id === parsed.data.id && !t.archivedAt)
+            : undefined;
+        const options = {
+            ...parsed.data,
+            parentId: parsed.data.parentId === undefined ? (previous?.parentId ?? null) : parsed.data.parentId,
+        };
+        if (options.id && !previous)
+            return refused('team', 'This team is unavailable.');
+        if (options.parentId && !state.teams.some((t) => t.id === options.parentId && !t.archivedAt))
+            return refused('parent', 'Choose an active parent team in this organisation.');
+        const location = previous?.id ?? options.parentId;
+        if (!state.evaluator.allows(previous ? 'teams:update' : 'teams:create', target(fresh, 'team', location ?? fresh.tenant.id, location)))
+            return noPermission();
+        const moving = previous && previous.parentId !== options.parentId;
+        if (moving) {
+            if (state.foreignPolicy)
+                return refused('foreign_policy', 'A connected application must validate changes to this shared team hierarchy.');
+            if (!state.evaluator.allows('teams:update', target(fresh, 'team', fresh.tenant.id)) ||
+                !state.evaluator.allows('roles:assign', target(fresh, 'role', fresh.tenant.id)) ||
+                !state.grants
+                    .filter((g) => g.recipient.kind === 'team' ||
+                    [g.scope, ...(g.constraints ?? [])].some((s) => s.kind !== 'organisation'))
+                    .every((g) => (g.expiresAt !== undefined && g.expiresAt <= Date.now()) ||
+                    state.evaluator.canDelegate({
+                        ...g,
+                        scope: { kind: 'organisation' },
+                        constraints: [],
+                        relation: 'any',
+                    })))
+                return refused('delegation', 'Moving teams requires organisation-wide administration and authority over the affected access policies.');
+        }
+        // Validate the complete prospective tree, including descendants of a moved team.
+        const nextId = previous?.id ?? randomUUID();
+        const nextTeams = [
+            ...state.teams
+                .filter((t) => t.id !== nextId)
+                .map((t) => ({ id: t.id, parentId: t.parentId, organisationId: t.tenantId })),
+            { id: nextId, parentId: options.parentId, organisationId: fresh.tenant.id },
+        ];
+        if (nextTeams.length > 1000)
+            return refused('limit', 'This organisation already has 1,000 teams.');
+        try {
+            resourceAccess({
+                applicationId: fresh.binding.applicationId,
+                platformId: fresh.binding.platformId,
+                organisations: [{ id: fresh.tenant.id, restrictions: restriction(fresh.tenant) }],
+                platformRestrictions: {
+                    kind: 'operator',
+                    state: 'active',
+                    ceiling: [],
+                    selfDenied: [],
+                    denied: [],
+                    support: null,
+                    frozen: fresh.policyState.tenantRows.find((t) => t.kind === 'operator')?.frozen ?? false,
+                },
+                principal: asPrincipal(fresh),
+                catalogue: fresh.binding.catalogue,
+                teams: nextTeams,
+                memberships: [],
+                grants: [],
+                now: Date.now(),
+            });
+        }
+        catch {
+            return refused('hierarchy', 'A team cannot contain itself or create a hierarchy deeper than 64 teams.');
+        }
+        if (previous)
+            await tx
+                .update(accessTeams)
+                .set({ name: options.name, parentId: options.parentId })
+                .where(and(eq(accessTeams.tenantId, fresh.tenant.id), eq(accessTeams.id, previous.id)));
+        else
+            await tx.insert(accessTeams).values({
+                id: nextId,
+                tenantId: fresh.tenant.id,
+                name: options.name,
+                parentId: options.parentId,
+            });
+        await record(tx, fresh, {
+            action: 'tenant.settings_changed',
+            tenantId: fresh.tenant.id,
+            teamId: nextId,
+            targetType: 'team',
+            targetId: nextId,
+            before: previous ? { name: previous.name, parentId: previous.parentId } : null,
+            after: { name: options.name, parentId: options.parentId },
+        });
+        return done({ id: nextId }, [tenantTag(fresh.tenant.id)]);
+    });
+}
+export async function archiveTeam(access, db, scopeColumn, id) {
+    if (!z.uuid().safeParse(id).success)
+        return refused('id', 'Invalid team.');
+    return writer(access, db, scopeColumn, async (tx, fresh, state) => {
+        if (state.foreignPolicy)
+            return refused('foreign_policy', 'A connected application must validate changes to this shared team hierarchy.');
+        const team = state.teams.find((t) => t.id === id && !t.archivedAt);
+        if (!team)
+            return refused('team', 'This team is unavailable.');
+        if (!state.evaluator.allows('teams:archive', target(fresh, 'team', id, id)))
+            return noPermission();
+        const inUse = state.roleRows.some((r) => r.entries.some((e) => (e.scope.kind === 'team' && e.scope.teamId === id) ||
+            (e.scope.kind === 'resource' &&
+                e.scope.resourceType === 'team' &&
+                e.scope.resourceId === id))) ||
+            state.teams.some((t) => t.parentId === id && !t.archivedAt) ||
+            state.participants.some((p) => p.teamId === id) ||
+            state.assignmentRows.some((a) => a.teamId === id ||
+                (a.scope.kind === 'team' && a.scope.teamId === id) ||
+                (a.scope.kind === 'resource' &&
+                    a.scope.resourceType === 'team' &&
+                    a.scope.resourceId === id));
+        if (inUse)
+            return refused('in_use', 'Move child teams and remove this team’s participants and assignments before archiving it.');
+        await tx
+            .update(accessTeams)
+            .set({ archivedAt: new Date() })
+            .where(and(eq(accessTeams.tenantId, fresh.tenant.id), eq(accessTeams.id, id)));
+        await record(tx, fresh, {
+            action: 'tenant.settings_changed',
+            tenantId: fresh.tenant.id,
+            teamId: id,
+            targetType: 'team',
+            targetId: id,
+            after: { archived: true },
+        });
+        return done(undefined, [tenantTag(fresh.tenant.id)]);
+    });
+}
+export async function changeTeamParticipant(access, db, scopeColumn, input) {
+    const parsed = z
+        .object({ teamId: z.uuid(), principalId: z.string().min(1).max(256), remove: z.boolean() })
+        .strict()
+        .safeParse(input);
+    if (!parsed.success)
+        return refused('input', 'Choose a team and a person.');
+    const options = parsed.data;
+    return writer(access, db, scopeColumn, async (tx, fresh, state) => {
+        if (state.foreignPolicy)
+            return refused('foreign_policy', 'A connected application must validate changes to this team’s participants.');
+        const person = state.identities.get(options.principalId);
+        if (!person ||
+            person.class !== 'human' ||
+            !state.teams.some((t) => t.id === options.teamId && !t.archivedAt))
+            return refused('person', 'Choose an existing person and an active team in this organisation.');
+        if (!state.evaluator.allows(options.remove ? 'teams.people:remove' : 'teams.people:add', target(fresh, 'team', options.teamId, options.teamId)))
+            return noPermission();
+        // Participation changes must cover every assignment whose scope or recipients change.
+        const under = (teamId, root) => {
+            let cursor = teamId;
+            while (cursor !== null) {
+                if (cursor === root)
+                    return true;
+                cursor = state.teams.find((t) => t.id === cursor)?.parentId ?? null;
+            }
+            return false;
+        };
+        for (const g of state.grants) {
+            if (g.expiresAt !== undefined && g.expiresAt <= Date.now())
+                continue;
+            const receives = g.recipient.kind === 'team'
+                ? g.recipient.descendants
+                    ? under(options.teamId, g.recipient.teamId)
+                    : g.recipient.teamId === options.teamId
+                : g.recipient.principal.id === person.id &&
+                    g.recipient.principal.class === person.class &&
+                    [g.scope, ...(g.constraints ?? [])].some((s) => s.kind === 'own_teams');
+            if (!receives)
+                continue;
+            const proposed = {
+                ...g,
+                recipient: { kind: 'principal', principal: person },
+                constraints: g.constraints?.map((s) => s.kind === 'own_teams'
+                    ? { kind: 'team', teamId: options.teamId, descendants: s.descendants }
+                    : s),
+                scope: g.scope.kind === 'own_teams'
+                    ? { kind: 'team', teamId: options.teamId, descendants: g.scope.descendants }
+                    : g.scope,
+            };
+            if (!(await delegable(tx, fresh, state, proposed)))
+                return refused('delegation', 'This team carries access outside your delegation authority.');
+        }
+        if (options.remove)
+            await tx
+                .delete(accessTeamMembers)
+                .where(and(eq(accessTeamMembers.tenantId, fresh.tenant.id), eq(accessTeamMembers.teamId, options.teamId), eq(accessTeamMembers.principalId, person.id), eq(accessTeamMembers.principalClass, person.class)));
+        else
+            await tx
+                .insert(accessTeamMembers)
+                .values({
+                tenantId: fresh.tenant.id,
+                teamId: options.teamId,
+                principalId: person.id,
+                principalClass: person.class,
+            })
+                .onConflictDoNothing();
+        await record(tx, fresh, {
+            action: options.remove ? 'membership.ended' : 'membership.created',
+            tenantId: fresh.tenant.id,
+            teamId: options.teamId,
+            subject: person,
+            targetType: 'team_participant',
+            targetId: person.id,
+            after: { teamId: options.teamId, removed: options.remove },
+        });
+        return done(undefined, [tenantTag(fresh.tenant.id)]);
+    });
+}
+async function delegable(tx, access, state, grant) {
+    if (grant.expiresAt !== undefined && grant.expiresAt <= Date.now())
+        return true;
+    const scope = [grant.scope, ...(grant.constraints ?? [])].find((s) => s.kind === 'resource');
+    const resource = scope?.kind === 'resource'
+        ? await lookupResource(tx, access, scope.resourceType, scope.resourceId)
+        : undefined;
+    return state.evaluator.canDelegate(grant, resource);
+}
+const lookupResource = (tx, access, type, id) => policyResource(tx, access.binding, access.tenant.id, type, id);
+/** Location AND relation stay paired for each grant, then clauses are ORed inside the tenant boundary. */
+function auditClause(access, clause) {
+    if (clause.applicationId !== access.binding.applicationId ||
+        clause.platformId !== access.binding.platformId ||
+        clause.resourceType !== 'audit' ||
+        clause.organisationId !== access.tenant.id)
+        return sql `false`;
+    const filters = [eq(authzEvents.tenantId, clause.organisationId)];
+    if (clause.teamIds !== null)
+        filters.push(clause.teamIds.length ? inArray(authzEvents.teamId, [...clause.teamIds]) : sql `false`);
+    if (clause.resourceId !== undefined)
+        filters.push(/^\d{1,15}$/.test(clause.resourceId)
+            ? eq(authzEvents.id, Number(clause.resourceId))
+            : sql `false`);
+    if (clause.relation === 'actor')
+        filters.push(eq(authzEvents.actorId, access.actor.id), eq(authzEvents.actorClass, access.actor.class));
+    else if (clause.relation === 'subject')
+        filters.push(eq(authzEvents.subjectId, access.actor.id), eq(authzEvents.subjectClass, access.actor.class));
+    else if (clause.relation !== 'any')
+        filters.push(sql `false`);
+    return and(...filters) ?? sql `true`;
+}
+export async function scopedAuditLog(access, db, scopeColumn, options = {}) {
+    const { evaluator } = await resourceAccessFor(access, db, db, scopeColumn);
+    const clauses = evaluator.clauses('platform.audit:read');
+    if (!(await auditedReadGate(access, db, 'platform.audit:read', clauses.length > 0)))
+        return null;
+    if (options.id !== undefined && !/^\d{1,15}$/.test(options.id))
+        return null;
+    const limit = Number.isFinite(options.limit)
+        ? Math.max(1, Math.min(100, Math.floor(options.limit ?? 50)))
+        : 50;
+    const conditions = [
+        eq(authzEvents.tenantId, access.tenant.id),
+        eq(authzEvents.tenantVisible, true),
+        or(...clauses.map((c) => auditClause(access, c))) ?? sql `false`,
+    ];
+    if (options.id)
+        conditions.push(eq(authzEvents.id, Number(options.id)));
+    if (options.after) {
+        if (!Number.isFinite(options.after.occurredAt.getTime()) ||
+            !Number.isSafeInteger(options.after.id))
+            return null;
+        conditions.push(or(lt(authzEvents.occurredAt, options.after.occurredAt), and(eq(authzEvents.occurredAt, options.after.occurredAt), lt(authzEvents.id, options.after.id))) ?? sql `false`);
+    }
+    // Deliberately minimal projection: no payload, actor identity, target identity, reasons, IP or references.
+    const rows = await db
+        .select({
+        id: authzEvents.id,
+        occurredAt: authzEvents.occurredAt,
+        action: authzEvents.action,
+        outcome: authzEvents.outcome,
+        teamId: authzEvents.teamId,
+    })
+        .from(authzEvents)
+        .where(and(...conditions))
+        .orderBy(desc(authzEvents.occurredAt), desc(authzEvents.id))
+        .limit(limit + 1);
+    const items = rows.slice(0, limit);
+    const last = items.at(-1);
+    // A read of the audit trail is itself audited (0.9.0), like `securityLogFor`.
+    await record(db, access, {
+        action: 'audit_log.viewed',
+        tenantId: access.tenant.id,
+        targetType: 'audit',
+        targetId: access.tenant.id,
+    });
+    return {
+        items,
+        next: rows.length > limit && last ? { occurredAt: last.occurredAt, id: last.id } : null,
+    };
+}

package/dist/role-keys.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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
+ * 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.
+ */
+export declare const isCustomRoleKey: (key: string) => boolean;

package/dist/role-keys.js

@@ -0,0 +1,9 @@
+/**
+ * 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
+ * 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.
+ */
+export const isCustomRoleKey = (key) => key.startsWith('c_');