permdock 0.1.0 → 0.2.0

package/dist/{permdock-yoZ7EjxX.js → permdock-CzqXjCpU.js}

@@ -1,21 +1,31 @@
 import { n as isReadonlyArray, r as sole, t as compact } from "./compact-y6vfu2_f.js";
-import { n as freezeDeep, t as freezeCopy } from "./freeze-y1_jQL4v.js";
-import { C as ownGet, S as isForbiddenKey, a as formerKeys, c as getResource, d as isFieldRelation, g as listPermissions, i as findPermission, p as isPrincipalRelation, r as expandRelation, u as isEdgeRelation } from "./permissions-DC7GROPA.js";
-import { a as hasConditionOp } from "./refs-ChLSxbST.js";
-import { d as role, h as normalizeWhere, i as declaredRoleNames$1, l as normalizeApproval, n as assertApprovalRelations, p as applyQuota, s as grantList, u as normalizeAssurance } from "./policy-ANp36PnI.js";
-import { a as resolveScope, c as scopeChain, f as tenantOf, i as normalizeMemberships, l as scopeIdOf, o as rootMembershipId, r as findScope, s as rootScope, u as scopeList } from "./scopes-cKVp_WTw.js";
-import { S as isRole, T as synthesiseRole, a as authenticated, b as findRole, f as relationCondition, h as resourceRoleCondition, i as assurance, l as matchGrantee, o as combineWhere, r as asGrantee, s as flattenGrantee, w as listRoles } from "./grantee-Bv04_Vzf.js";
-import { a as approvalMessage, i as PermDockValidationError, n as PermDockDeniedError, o as deniedMessage, s as wireDenials, t as PermDockApprovalRequiredError } from "./errors-Iy71s7Oj.js";
-import { a as whereFromGrants, c as versionOf, d as delegatedPermissions, f as resourceIdOf, g as evaluateCondition, h as simulateArazzo, i as snapshotGrant, l as canonicalJson, m as isArazzoSimulateInput, o as decisionToken, r as signSnapshot, s as payloadDigest, t as buildSnapshot, u as coveredByDelegation } from "./snapshot-DE8dE_hz.js";
+import { n as freezeDeep, t as freezeCopy } from "./freeze-CrU8nQeX.js";
+import { E as ownGet, T as isForbiddenKey, _ as listPermissions, a as formerKeys, c as getResource, d as isEdgeRelation, f as isFieldRelation, i as findPermission, m as isPrincipalRelation, o as formerScopes, r as expandRelation } from "./permissions-DVoF6dMt.js";
+import { a as hasConditionOp } from "./refs-KYb4ntaz.js";
+import { d as normalizeApproval, f as normalizeAssurance, g as applyQuota, i as declaredRoleNames$1, l as levelCondition, m as role, n as assertApprovalRelations, s as grantList, u as levelNames, v as normalizeWhere } from "./policy-xyWg7QdR.js";
+import { n as PermDockValidationError } from "./validation-error-CnjZ4t92.js";
+import { a as wireDenials } from "./problem-details-_AMOYz-w.js";
+import { a as deniedMessage, i as approvalMessage, n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "./errors-Cz5zn0mW.js";
+import { n as sameId } from "./ids-DC4V4CFu.js";
+import { a as normalizeMemberships, c as rootScope, d as scopeList, f as subjectForPermission, i as keepsPermission, l as scopeChain, m as tenantOf, o as resolveScope, s as rootMembershipId, u as scopeIdOf } from "./scopes-CVdPrWN-.js";
+import { a as whereFromGrants, c as rowIdOf, d as isArazzoSimulateInput, f as simulateArazzo, i as signSnapshot, l as rowValues, p as evaluateCondition, r as snapshotGrant, s as isRowPair, t as buildSnapshot } from "./snapshot-Enxd0n-s.js";
 import { t as parseDuration } from "./duration-xK2jGFVc.js";
-import { a as matchScopedMembership, c as partitionsOf, f as tenantsOf, h as sanitizeContext, i as isMembershipExpired, l as relatesTo, m as pickVisible, p as grantCoversField, r as inTeam, s as nowSeconds, t as isActive, u as resolveActiveTenant } from "./validity-D0uRmJKJ.js";
+import { D as synthesiseRole, E as listRoles, S as findRole, _ as resourceRoleCondition, a as authenticated, d as matchGrantee, i as assurance, m as relationCondition, o as combineWhere, r as asGrantee, s as flattenGrantee, w as isRole } from "./grantee-Cv5Sogfv.js";
+import { t as canonicalJson } from "./canonical-json-DemiK4Vp.js";
+import { n as pickVisible, r as sanitizeContext, t as grantCoversField } from "./fields-BMl1RxoX.js";
+import { a as isMembershipExpired, d as partitionsOf, f as relatesTo, g as tenantsOf, h as scopeField, i as inTeam, o as matchScopedMembership, p as resolveActiveTenant, r as heldRoleNamesIn, t as isActive, u as nowSeconds } from "./validity-uOp8UpYn.js";
 import { t as requiresApproval } from "./approval-required-TzNB9oQA.js";
-import { r as mergeHostedGrants, t as isPortableCondition } from "./hosted-BwKQ1BTA.js";
+import { r as mergeHostedGrants, t as isPortableCondition } from "./hosted-DJQw46hn.js";
 import { n as isThenable, t as ignoreRejection } from "./thenable-okc2xDsj.js";
 import { t as byCodePoint } from "./compare-pfyVnBjE.js";
-import { a as relationWalk, i as relationReader, n as pendingRelations, o as resolveRelated, r as relationId } from "./relations-r4soIFZB.js";
+import { a as relationWalk, i as relationReader, n as pendingRelations, o as resolveRelated, r as relationId } from "./relations-cjOL01hZ.js";
+import { i as requiresStandIn, n as coversRequirements, r as delegatedPermissions, t as coveredByDelegation } from "./delegation-D8pUEuce.js";
+import { t as resourceIdOf } from "./resource-ref-CaS9yVPi.js";
+import { n as payloadDigest, r as versionOf, t as decisionToken } from "./token-CIWxJOCh.js";
 import { i as isSubject, r as isPrincipal, t as anonymousSubject } from "./subject-C6dLxqHU.js";
 //#region src/core/approval-policies.ts
+/** The denial detail when an `ApprovalPolicySource` fails: every call an allow would grant denies with reason `approval`. */
+const APPROVAL_POLICY_UNAVAILABLE = "approval-policy-unavailable";
 function memoryApprovalPolicies(policies) {
 	const entries = [...policies];
 	return Object.freeze({ approvalPoliciesFor(query) {
@@ -28,17 +38,13 @@ function isRecord(value) {
 function isStringList(value) {
 	return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
-/**
-* One raw entry checked against the policy: `null` when it names no
-* permission the policy declares (it applies to nothing), `undefined` when
-* it is invalid.
-*/
-function loadOne(policy, raw) {
-	if (!isRecord(raw) || typeof raw["permission"] !== "string") return;
+function checkOne(policy, raw) {
+	if (!isRecord(raw) || typeof raw["permission"] !== "string") return { problem: "invalid" };
 	const permission = findPermission(policy.permissions, raw["permission"]);
-	if (permission === void 0) return null;
+	if (permission === void 0) return { problem: "unknown-permission" };
 	const { tenant, actors, where, check, approval } = raw;
-	if (tenant !== void 0 && typeof tenant !== "string" || actors !== void 0 && !isStringList(actors) || where !== void 0 && !isPortableCondition(where) || check !== void 0 && !isPortableCondition(check) || isRecord(approval) && approval["escalation"] !== void 0 || approval !== "human" && !isRecord(approval)) return;
+	if (tenant !== void 0 && typeof tenant !== "string" || actors !== void 0 && !isStringList(actors) || where !== void 0 && !isPortableCondition(where) || check !== void 0 && !isPortableCondition(check) || approval !== "human" && !isRecord(approval)) return { problem: "invalid" };
+	if (where !== void 0 && permission.kind !== "instance") return { problem: "where-on-collection" };
 	let normalized;
 	try {
 		normalized = normalizeApproval(approval, permission.key);
@@ -47,18 +53,47 @@ function loadOne(policy, raw) {
 			approval: normalized
 		}], policy.resources);
 	} catch {
-		return;
+		return { problem: "invalid" };
 	}
-	if (normalized === void 0) return;
-	if (normalized !== "human" && normalized.staleOn !== void 0 && (permission.kind !== "instance" || policy.resources.get(permission.resource)?.version === void 0)) return;
-	return compact({
+	if (normalized === void 0) return { problem: "invalid" };
+	if (normalized !== "human" && normalized.staleOn !== void 0 && (permission.kind !== "instance" || policy.resources.get(permission.resource)?.version === void 0)) return { problem: "stale-on-without-version" };
+	return { entry: compact({
 		permission: permission.key,
 		tenant,
 		actors: actors === void 0 ? void 0 : new Set(actors),
 		where: where === void 0 ? void 0 : normalizeWhere(where),
 		check: check === void 0 ? void 0 : normalizeWhere(check),
 		approval: normalized
-	});
+	}) };
+}
+/**
+* Checks one entry against the policy the way `approvalPoliciesFor` loads
+* it, for an application to refuse a bad entry when it is saved instead of
+* finding every call denied. Never throws.
+*/
+function validateApprovalPolicy(policy, entry) {
+	try {
+		const checked = checkOne(policy, entry);
+		return "problem" in checked ? {
+			ok: false,
+			problem: checked.problem
+		} : { ok: true };
+	} catch {
+		return {
+			ok: false,
+			problem: "invalid"
+		};
+	}
+}
+/**
+* One raw entry checked against the policy: `null` when it names no
+* permission the policy declares (it applies to nothing), `undefined` when
+* it does not load.
+*/
+function loadOne(policy, raw) {
+	const checked = checkOne(policy, raw);
+	if ("entry" in checked) return checked.entry;
+	return checked.problem === "unknown-permission" ? null : void 0;
 }
 function loadAll(policy, raw) {
 	if (!Array.isArray(raw)) return "failed";
@@ -103,6 +138,17 @@ function asStages(approval) {
 		quorum: approval.quorum
 	})];
 }
+/** An entry's stages, each carrying the entry's escalation unless it has its own. */
+function entryStages(approval) {
+	const stages = asStages(approval);
+	if (approval === "human" || approval.escalation === void 0) return stages;
+	const escalation = approval.escalation;
+	return stages.map((stage) => stage.escalation === void 0 ? compact({
+		by: stage.by,
+		quorum: stage.quorum,
+		escalation
+	}) : stage);
+}
 function shorter(a, b) {
 	if (a === void 0) return b;
 	if (b === void 0) return a;
@@ -124,8 +170,9 @@ function tightenApproval(code, entries, input) {
 	let distinct = false;
 	let staleOn;
 	let ttl;
-	for (const part of parts) {
-		for (const stage of asStages(part)) {
+	for (const [index, part] of parts.entries()) {
+		const fromCode = code !== void 0 && index === 0;
+		for (const stage of fromCode ? asStages(part) : entryStages(part)) {
 			const key = JSON.stringify(stage);
 			if (!seen.has(key)) {
 				seen.add(key);
@@ -173,7 +220,8 @@ function identity(membership) {
 		membership.member?.group ?? null,
 		[...membership.eligible ?? []].toSorted(),
 		membership.managedBy ?? null,
-		[...membership.entitlements ?? []].toSorted()
+		[...membership.entitlements ?? []].toSorted(),
+		membership.keep === void 0 ? null : [...membership.keep].toSorted()
 	]);
 }
 /**
@@ -245,7 +293,8 @@ function asMembershipSource(input) {
 /**
 * Trust the memberships the verified token carries, and read `source` only
 * when the token marks them truncated. With `version`, a token minted before
-* the latest membership change is stale for the policy's `fresh` permissions.
+* the latest membership change is stale for the policy's `fresh` permissions,
+* or with `onStale: 'reread'` has its memberships read from `source` instead.
 */
 function claimsFirst(source, options = {}) {
 	const inner = asMembershipSource(source);
@@ -254,6 +303,7 @@ function claimsFirst(source, options = {}) {
 		membershipsFor: (principal, query) => inner.membershipsFor(principal, query),
 		...inner.list === void 0 ? {} : { list: (query) => inner.list?.(query) ?? [] },
 		...version === void 0 ? {} : { version },
+		...options.onStale === "reread" ? { onStale: "reread" } : {},
 		claimsFirst: true
 	};
 }
@@ -261,6 +311,33 @@ function claimsFirst(source, options = {}) {
 function isExternallyManaged(membership) {
 	return membership.managedBy === "idp";
 }
+/**
+* How many principals hold `role` in one scope instance now, from the
+* source's member list (`MembershipSource.list`): live memberships of exactly
+* that scope and instance, each principal counted once. The `holders` a
+* `decideRoleChange` with `min`, `max` or `transferOnly` needs. `undefined`
+* when the source cannot list or the read fails, which that check denies.
+*/
+async function countHolders(source, query) {
+	const composed = asMembershipSource(source);
+	if (composed.list === void 0) return;
+	const role = typeof query.role === "string" ? query.role : query.role.key;
+	try {
+		const entries = await composed.list({
+			scope: query.scope,
+			id: query.id
+		});
+		const now = Math.floor(Date.now() / 1e3);
+		const holders = /* @__PURE__ */ new Set();
+		for (const entry of entries) {
+			const membership = entry.membership;
+			if (membership.scope === query.scope && membership.id === query.id && membership.roles.includes(role) && (membership.expiresAt === void 0 || membership.expiresAt > now)) holders.add(entry.principal.id);
+		}
+		return holders.size;
+	} catch {
+		return;
+	}
+}
 //#endregion
 //#region src/core/custom-roles.ts
 /** The current key for a stored key, current or former; `undefined` when neither. */
@@ -269,7 +346,30 @@ function currentKey(policy, raw) {
 	if (leaf === void 0) return;
 	return leaf.key === raw || formerKeys(leaf).includes(raw) ? leaf.key : void 0;
 }
-const GRANT_KEYS = /* @__PURE__ */ new Set(["permission", "effect"]);
+const GRANT_KEYS = /* @__PURE__ */ new Set([
+	"permission",
+	"effect",
+	"level"
+]);
+/** `where` narrowed by a level; the empty level (`{}`) leaves it as is. */
+function andWhere(where, level) {
+	if (level.op === "and" && level.conditions.length === 0) return where;
+	return where === void 0 ? level : {
+		op: "and",
+		conditions: [where, level]
+	};
+}
+/** A ceiling grant narrowed by a level's condition and marked with the level. */
+function leveled(grant, level, condition) {
+	const where = andWhere(grant.where, condition);
+	const check = grant.check === void 0 ? void 0 : andWhere(grant.check, condition);
+	return freezeDeep({
+		...grant,
+		level,
+		...where === void 0 ? {} : { where },
+		...check === void 0 ? {} : { check }
+	});
+}
 /**
 * The scope a custom role is held at: `scope` (a name or alias), the second
 * scope for the `team` input shape, else the first scope. `undefined` when
@@ -372,8 +472,11 @@ function resolveCustomRole(policy, role) {
 	};
 	const included = [];
 	const includedKeys = /* @__PURE__ */ new Set();
-	const allowKeys = /* @__PURE__ */ new Set();
+	const allowKeys = /* @__PURE__ */ new Map();
 	const denyKeys = /* @__PURE__ */ new Set();
+	const allowAll = (key) => {
+		allowKeys.set(key, "all");
+	};
 	for (const name of Array.isArray(role.includes) ? role.includes : []) {
 		if (typeof name !== "string" || !declared.has(name)) {
 			drop({
@@ -390,7 +493,7 @@ function resolveCustomRole(policy, role) {
 			} else if (ceilingSet.has(grant)) {
 				included.push(grant);
 				includedKeys.add(key);
-			} else if (ceilingKeys.has(key)) allowKeys.add(key);
+			} else if (ceilingKeys.has(key)) allowAll(key);
 			else drop({
 				permission: key,
 				reason: "outside-ceiling"
@@ -421,7 +524,9 @@ function resolveCustomRole(policy, role) {
 			to: key
 		});
 		const effect = entry.effect ?? "allow";
-		if (Object.keys(entry).some((name) => !GRANT_KEYS.has(name)) || effect !== "allow" && effect !== "deny") {
+		const extra = Object.keys(entry).some((name) => !GRANT_KEYS.has(name));
+		const level = entry.level;
+		if (extra || effect !== "allow" && effect !== "deny" || effect === "deny" && level !== void 0) {
 			drop({
 				permission: key,
 				reason: "condition-not-allowed"
@@ -433,6 +538,21 @@ function resolveCustomRole(policy, role) {
 			denyKeys.add(key);
 			continue;
 		}
+		let narrowing;
+		if (level !== void 0) {
+			const leaf = findPermission(policy.permissions, key);
+			const condition = typeof level === "string" && leaf?.kind === "instance" ? levelCondition(policy, leaf.resource, level) : void 0;
+			if (condition === void 0) {
+				drop({
+					permission: key,
+					reason: "unknown-level",
+					level: String(level)
+				});
+				denyKeys.add(key);
+				continue;
+			}
+			narrowing = [String(level), condition];
+		}
 		if (!ceilingKeys.has(key)) {
 			drop({
 				permission: key,
@@ -440,19 +560,27 @@ function resolveCustomRole(policy, role) {
 			});
 			continue;
 		}
-		allowKeys.add(key);
+		const held = allowKeys.get(key);
+		if (narrowing === void 0) allowAll(key);
+		else if (held === void 0) allowKeys.set(key, new Map([narrowing]));
+		else if (held !== "all") held.set(...narrowing);
 	}
 	const out = [];
 	const push = (grant) => {
 		if (!out.includes(grant)) out.push(grant);
 	};
 	for (const grant of included) if (grant.effect === "deny" || !denyKeys.has(grant.permission.key)) push(grant);
-	for (const key of allowKeys) {
+	for (const [key, levels] of allowKeys) {
 		if (denyKeys.has(key) || includedKeys.has(key)) continue;
 		const sources = /* @__PURE__ */ new Set();
-		for (const grant of ceiling) if (grant.permission.key === key) {
-			push(grant);
+		for (const grant of ceiling) {
+			if (grant.permission.key !== key) continue;
 			sources.add(soleRole(grant) ?? "");
+			if (levels === "all") {
+				push(grant);
+				continue;
+			}
+			for (const [level, condition] of levels) push(leveled(grant, level, condition));
 		}
 		for (const grant of all) if (grant.effect === "deny" && grant.permission.key === key && sources.has(soleRole(grant) ?? "")) push(grant);
 	}
@@ -490,12 +618,17 @@ function customGrantsFor(policy, roles) {
 	}
 	return out;
 }
+/** The well-formed tenant (not platform) custom roles; a declared role name is never one. */
+function tenantCustomRoles(policy, roles) {
+	const declared = declaredRoleNames$1(policy);
+	return roles.filter((role) => wellFormed(role) && !isGlobalCustomRole(role) && !declared.has(role.name));
+}
 /** A membership at the role's scope, inside its tenant (and instance, when pinned), naming it. */
 function holdsCustomRole(membership, role, scopes) {
 	if (isGlobalCustomRole(role)) return false;
 	const scope = customRoleScope(role, scopes);
 	const id = customRoleId(role);
-	return scope !== void 0 && membership.scope === scope && tenantOf(membership, scopes) === role.tenant && (id === void 0 || membership.id === id) && membership.roles.includes(role.name);
+	return scope !== void 0 && membership.scope === scope && sameId(tenantOf(membership, scopes), role.tenant) && (id === void 0 || sameId(membership.id, id)) && membership.roles.includes(role.name);
 }
 /** Whether `principal.roles` names the platform custom role. */
 function holdsGlobalCustomRole(roles, role) {
@@ -503,7 +636,7 @@ function holdsGlobalCustomRole(roles, role) {
 }
 /** A tenant's custom role inside that tenant, or a platform custom role anywhere. */
 function isCustomRoleName(name, roles, tenant) {
-	return roles.some((item) => wellFormed(item) && item.name === name && (isGlobalCustomRole(item) || tenant !== void 0 && item.tenant === tenant));
+	return roles.some((item) => wellFormed(item) && item.name === name && (isGlobalCustomRole(item) || tenant !== void 0 && sameId(item.tenant, tenant)));
 }
 /**
 * The compact JWT form of custom roles for the `memberships[].grants` claim
@@ -520,7 +653,14 @@ function customRoleClaim(roles, policy) {
 		const includes = Array.isArray(role.includes) ? role.includes : [];
 		const grants = Array.isArray(role.grants) ? role.grants : [];
 		for (const name of includes) entries.push(`@${name}`);
-		for (const grant of grants) entries.push(grant.effect === "deny" ? `-${keyOf(grant.permission)}` : keyOf(grant.permission));
+		for (const grant of grants) {
+			if (grant.effect === "deny") {
+				entries.push(`-${keyOf(grant.permission)}`);
+				continue;
+			}
+			const level = grant.level;
+			entries.push(typeof level === "string" && level !== "" ? `${keyOf(grant.permission)}@${level}` : keyOf(grant.permission));
+		}
 		claim[role.name] = entries;
 	}
 	return freezeDeep(claim);
@@ -704,7 +844,7 @@ function activate(policy, subject, input, now = nowSeconds()) {
 	if (binding === void 0 || activation === void 0) return activationDenied("unknown-role");
 	const scopes = scopeList(policy.scopes);
 	const scope = resolveScope(scopes, input.scope) ?? input.scope;
-	const eligible = (principal.memberships ?? []).find((membership) => membership.scope === scope && membership.id === input.id && !isMembershipExpired(membership, now) && (membership.eligible ?? []).includes(roleName) && withinAgrees(scopes, membership.within, input.within));
+	const eligible = (principal.memberships ?? []).find((membership) => membership.scope === scope && sameId(membership.id, input.id) && !isMembershipExpired(membership, now) && (membership.eligible ?? []).includes(roleName) && withinAgrees(scopes, membership.within, input.within));
 	if (eligible === void 0) return activationDenied("no-membership");
 	const within = eligible.within;
 	if (activation.justification === "required") {
@@ -903,20 +1043,30 @@ function matchWriteScope(match, instance, current, next) {
 	const moved = match(next);
 	return moved.ok ? first : moved;
 }
-function isRowPair(value) {
-	return value !== null && typeof value === "object" && "current" in value && "next" in value;
-}
 function isGlobalRole(value) {
 	return value !== null && typeof value === "object" && Reflect.get(value, "scope") === "global";
 }
 function onlyGlobal(roles) {
 	return Array.isArray(roles) ? roles.filter(isGlobalRole) : [];
 }
-function customRolesFor(source, tenants, auth, signedIn = false) {
+/** The `customRoles` option as a source: a factory is called with the resolved subject, and a throw reads none. */
+function roleSourceFor(option, subject, auth) {
+	if (typeof option !== "function") return option;
+	try {
+		return option(subject);
+	} catch {
+		auth.push({
+			reason: "source-threw",
+			source: "customRoles"
+		});
+		return;
+	}
+}
+function customRolesFor(source, tenants, auth, globalHeld, heldIn) {
 	if (source === void 0) return [];
 	const loaded = [];
 	for (const tenant of tenants) try {
-		loaded.push(source.rolesFor(tenant));
+		loaded.push(source.rolesFor(tenant, { held: heldIn(tenant) }));
 	} catch {
 		auth.push({
 			reason: "source-threw",
@@ -924,8 +1074,8 @@ function customRolesFor(source, tenants, auth, signedIn = false) {
 		});
 		loaded.push([]);
 	}
-	if (signedIn && source.globalRoles !== void 0) try {
-		const roles = source.globalRoles();
+	if (globalHeld !== void 0 && source.globalRoles !== void 0) try {
+		const roles = source.globalRoles({ held: globalHeld });
 		loaded.push(isThenable(roles) ? roles.then(onlyGlobal) : onlyGlobal(roles));
 	} catch {
 		auth.push({
@@ -989,6 +1139,87 @@ function expandRoleNames(names, declared, custom, tenant) {
 function declaredRoleNames(policy) {
 	return policy.index.declaredRoles;
 }
+const NEVER = {
+	op: "or",
+	conditions: []
+};
+function isUnconditionedAllow(grant, now) {
+	return grant.where === void 0 && grant.check === void 0 && grant.closure === void 0 && grant.portable && grant.purpose === void 0 && grant.viaOnly === void 0 && grant.requires === void 0 && isActive(grant.validity, now);
+}
+/**
+* The row condition a grant's `requires` adds: the row's instance of some
+* scope is one where the subject holds `key` through a role grant without a
+* row condition, minus the instances a deny of `key` reaches at that scope.
+* `undefined` when the subject holds `key` globally that way, so every row
+* passes. The in-process mirror of the SQL `permdock_has_permission` and
+* `permitted_<scope>_ids_by_permission`.
+*/
+function requirementCondition(policy, subject, keys, resource, now, customRoles, customGrants) {
+	let where;
+	for (const key of keys) where = combineWhere(where, keyRequirement(policy, subject, key, resource, now, customRoles, customGrants));
+	return where;
+}
+function keyRequirement(policy, subject, key, resource, now, customRoles, customGrants) {
+	const principal = subject.principal;
+	if (principal === null) return NEVER;
+	const scopes = scopeList(policy.scopes);
+	const declared = declaredRoleNames(policy);
+	const global = new Set(expandRoleNames(principal.roles ?? [], declared, customRoles, principal.tenant).roles);
+	const held = (principal.memberships ?? []).filter((membership) => !isMembershipExpired(membership, now) && keepsPermission(membership, key)).map((membership) => ({
+		membership,
+		roles: new Set(expandRoleNames(membership.roles, declared, customRoles, tenantOf(membership, scopes)).roles)
+	}));
+	const allowed = /* @__PURE__ */ new Map();
+	const denied = /* @__PURE__ */ new Map();
+	let globalAllow = false;
+	let globalDeny = false;
+	const note = (effect, membership) => {
+		if (membership === void 0) {
+			if (effect === "allow") globalAllow = true;
+			else globalDeny = true;
+			return;
+		}
+		if (membership.scope === void 0 || membership.id === void 0) return;
+		const target = effect === "allow" ? allowed : denied;
+		const ids = target.get(membership.scope) ?? /* @__PURE__ */ new Set();
+		ids.add(membership.id);
+		target.set(membership.scope, ids);
+	};
+	const applies = (grant) => grant.effect === "allow" ? isUnconditionedAllow(grant, now) : isActive(grant.validity, now);
+	for (const grant of policy.index.grantsByKey.get(key) ?? []) {
+		const items = flattenGrantee(grant.to);
+		if (grant.breakGlass !== void 0 || !applies(grant) || items.length === 0 || !items.every((item) => item.kind === "role")) continue;
+		const roles = items.flatMap((item) => item.kind === "role" ? [item] : []);
+		if (!roles.every((item) => item.scope !== "global" || global.has(item.role))) continue;
+		const scoped = roles.filter((item) => item.scope !== "global");
+		if (scoped.length === 0) {
+			note(grant.effect);
+			continue;
+		}
+		for (const entry of held) if (scoped.every((item) => typeof item.scope === "string" && entry.membership.scope === item.scope && entry.roles.has(item.role))) note(grant.effect, entry.membership);
+	}
+	for (const { grant, role } of customGrants) {
+		if (grant.permission.key !== key || !applies(grant)) continue;
+		if (holdsGlobalCustomRole(principal.roles, role)) note(grant.effect);
+		for (const entry of held) if (holdsCustomRole(entry.membership, role, scopes)) note(grant.effect, entry.membership);
+	}
+	if (globalAllow && !globalDeny) return;
+	const parts = [];
+	for (const name of resource === void 0 ? [] : partitionsOf(resource, scopes)) {
+		const field = scopeField(resource, name, scopes);
+		const deniedIds = denied.get(name);
+		const ids = [...allowed.get(name) ?? []].filter((id) => deniedIds?.has(id) !== true).toSorted();
+		if (field !== void 0 && ids.length > 0) parts.push({
+			op: "in",
+			field,
+			value: ids
+		});
+	}
+	return sole(parts) ?? {
+		op: "or",
+		conditions: parts
+	};
+}
 function alternativesFor(policy, permission, subject, now, env) {
 	return listPermissions(policy.permissions).filter((leaf) => leaf.resource === permission.resource && leaf.key !== permission.key).filter((leaf) => {
 		return evaluate(policy, subject, leaf, void 0, {
@@ -998,11 +1229,35 @@ function alternativesFor(policy, permission, subject, now, env) {
 		}, {
 			...env,
 			emit: false,
-			skipAlternatives: true
+			skipAlternatives: true,
+			outcomeOnly: true
 		}).outcome === "granted";
 	});
 }
-function evaluateGrantCondition(grant, permission, current, next, subject, now, scopes, relations) {
+function inheritedVerdict(policy, subject, resource, id, key, now, env) {
+	const leaf = findPermission(policy.permissions, key);
+	const loaded = env.relations?.row({
+		resource,
+		id
+	});
+	if (leaf === void 0 || loaded === void 0) return "relation-unavailable";
+	if (loaded === "pending" || loaded === "failed") return "relation-unavailable";
+	if (loaded.row === null) return false;
+	const decision = evaluate(policy, subject, leaf, loaded.row, {
+		trusted: true,
+		source: "simulate",
+		now
+	}, {
+		...env,
+		emit: false,
+		skipAlternatives: true,
+		outcomeOnly: true
+	});
+	if (decision.outcome === "granted") return true;
+	const reasons = decision.outcome === "denied" ? decision.denials.map((denial) => denial.reason) : [];
+	return reasons.includes("relation-unavailable") ? "relation-unavailable" : reasons.includes("relation-depth") ? "relation-depth" : false;
+}
+function evaluateGrantCondition(grant, permission, current, next, subject, now, scopes, relations, permitted) {
 	let unknown;
 	const onOpaque = () => {
 		unknown ??= "opaque-condition";
@@ -1012,7 +1267,7 @@ function evaluateGrantCondition(grant, permission, current, next, subject, now,
 			unknown ??= "relation-unavailable";
 			return false;
 		}
-		const verdict = resolveRelated(condition, row, subject, now, relations);
+		const verdict = resolveRelated(condition, row, subject, now, relations, permitted);
 		if (verdict === "relation-depth" || verdict === "relation-unavailable") {
 			unknown ??= verdict;
 			return false;
@@ -1140,12 +1395,12 @@ function traceOf(tracer) {
 		skipped: tracer.skipped
 	};
 }
-function evaluate(policy, subject, permission, data, options, env) {
+function evaluate(policy, given, permission, data, options, env) {
+	const subject = subjectForPermission(given, permission.key);
 	const now = options.now ?? nowSeconds();
 	const trusted = options.trusted === true;
 	const resource = getResource(policy.permissions, permission.resource);
-	let current = data;
-	let next = data;
+	let { current, next } = rowValues(permission, data);
 	const tracer = options.explain === true ? {
 		evaluated: 0,
 		allows: [],
@@ -1153,21 +1408,13 @@ function evaluate(policy, subject, permission, data, options, env) {
 		skipped: []
 	} : void 0;
 	const complete = (decision, membership) => {
-		const final = freezeDeep(tracer === void 0 ? decision : {
+		const final = env.outcomeOnly === true ? decision : freezeDeep(tracer === void 0 ? decision : {
 			...decision,
 			trace: traceOf(tracer)
 		});
-		finish(policy, subject, permission, current, final, options, env, trusted, membership);
+		finish(policy, given, permission, current, final, options, env, trusted, membership);
 		return final;
 	};
-	if (permission.kind === "instance" && isRowPair(data)) {
-		current = data.current;
-		next = data.next;
-	}
-	if (permission.kind === "collection") {
-		current = void 0;
-		next = data;
-	}
 	try {
 		if (data !== void 0 || permission.kind === "instance" && policy.validate === "always") {
 			const validated = validateBoundary(permission, resource, permission.kind === "instance" && isRowPair(data) ? data.current : data, policy.validate, trusted, options.boundary ?? "manual");
@@ -1323,7 +1570,7 @@ function evaluate(policy, subject, permission, data, options, env) {
 				const matchRow = (row) => matchScopedMembership(subject, roleItem.scope, roleItem.role, row, scopes, resource, policy.resources, now, (membership) => {
 					if (custom === void 0) return expandRoleNames(membership.roles, declared, env.customRoles, tenantOf(membership, scopes)).roles;
 					return holdsCustomRole(membership, custom, scopes) ? [custom.name] : [];
-				}, env.team, walkRole);
+				}, env.team, walkRole, permission.kind === "instance", options.scope);
 				const scopeMatch = matchWriteScope(matchRow, permission.kind === "instance", current, next);
 				if (!scopeMatch.ok) {
 					denials.push({
@@ -1347,11 +1594,12 @@ function evaluate(policy, subject, permission, data, options, env) {
 			else skip(tracer, grant, permission.key, "validity");
 			continue;
 		}
+		const requirement = grant.requires === void 0 || grant.effect !== "allow" ? void 0 : requirementCondition(policy, subject, grant.requires, resource, now, env.customRoles, env.customGrants);
 		const merged = freezeDeep(compact({
 			...grant,
-			where: combineWhere(grant.where, granteeMatch.where)
+			where: combineWhere(combineWhere(grant.where, granteeMatch.where), requirement)
 		}));
-		const condition = evaluateGrantCondition(merged, permission, current, next, subject, now, scopes, env.relations);
+		const condition = evaluateGrantCondition(merged, permission, current, next, subject, now, scopes, env.relations, (target, id, key) => inheritedVerdict(policy, given, target, id, key, now, env));
 		if (!condition.matched && grant.effect === "deny" && isUnevaluable(condition.reason) && grantCoversField(grant.fields, options.field, grant.effect)) {
 			if (condition.reason === "closure-error") emitSafe(env.listeners.error, condition.cause ?? /* @__PURE__ */ new Error("closure-error"), env.listeners);
 			tracer?.denies.push(matchedOf(merged, permission.key));
@@ -1442,7 +1690,12 @@ function evaluate(policy, subject, permission, data, options, env) {
 		}],
 		alternatives: env.skipAlternatives ? [] : alternativesFor(policy, permission, subject, now, env)
 	});
-	const delegationMiss = coveredByDelegation(permission, subject.delegation, resourceIdOf(current), subject.actor !== void 0 && ceiling === void 0);
+	const unscoped = subject.actor !== void 0 && ceiling === void 0;
+	let delegationMiss = coveredByDelegation(permission, subject.delegation, resourceIdOf(current), unscoped);
+	const requirementsCovered = allows.filter((candidate) => coversRequirements(policy.permissions, candidate.grant.requires, subject.delegation, resourceIdOf(current), unscoped));
+	let usable = delegationMiss === void 0 ? requirementsCovered : requirementsCovered.filter((candidate) => requiresStandIn(candidate.grant));
+	if (delegationMiss === "not-delegated" && usable.length > 0) delegationMiss = void 0;
+	if (delegationMiss === void 0 && usable.length === 0) delegationMiss = "not-delegated";
 	if (delegationMiss !== void 0) return complete({
 		outcome: "denied",
 		denials: [{
@@ -1452,12 +1705,12 @@ function evaluate(policy, subject, permission, data, options, env) {
 		alternatives: env.skipAlternatives ? [] : alternativesFor(policy, permission, subject, now, env)
 	});
 	const approvalPolicies = env.approvalPolicies;
-	if (approvalPolicies === "failed" && allows.length > 0) return complete({
+	if (approvalPolicies === "failed" && usable.length > 0) return complete({
 		outcome: "denied",
 		denials: [{
 			role: null,
 			reason: "approval",
-			detail: "approval-policy-unavailable"
+			detail: APPROVAL_POLICY_UNAVAILABLE
 		}],
 		alternatives: []
 	});
@@ -1474,7 +1727,7 @@ function evaluate(policy, subject, permission, data, options, env) {
 	let matchedAllow;
 	let approval;
 	let quotaState = {};
-	for (const candidate of allows) {
+	for (const candidate of usable) {
 		approval = approvalOf(candidate);
 		const consume = !requiresApproval(approval) && shouldConsumeQuota(options.source, env.simulated);
 		const quota = applyQuota({
@@ -1509,9 +1762,9 @@ function evaluate(policy, subject, permission, data, options, env) {
 		denials: quotaDenials.length > 0 ? quotaDenials : denials,
 		alternatives: env.skipAlternatives ? [] : alternativesFor(policy, permission, subject, now, env)
 	});
-	const resourceId = permission.kind === "collection" ? "*" : current !== null && typeof current === "object" ? String(current[resource?.id ?? "id"] ?? "*") : "*";
+	const resourceId = permission.kind === "collection" ? "*" : rowIdOf(current, resource?.id);
 	const version = approval !== void 0 && approval !== "human" && approval.staleOn === "resource-change" && resource?.version !== void 0 ? versionOf(current, resource.version) : void 0;
-	const token = env.simulated ? "pd1.simulated" : decisionToken({
+	const token = env.simulated ? "pd1.simulated" : env.outcomeOnly === true ? "pd1.outcome" : decisionToken({
 		key: permission.key,
 		resourceId,
 		principal: subject.principal,
@@ -1647,7 +1900,7 @@ function audiencesOf(policy, names) {
 /** Whether `membership` is the instance itself or one of its ancestors named in `within`. */
 function coversInstance(membership, scopes, scope, id, within) {
 	if (membership.scope === void 0 || membership.id === void 0) return false;
-	if (membership.scope === scope) return membership.id === id;
+	if (membership.scope === scope) return sameId(membership.id, id);
 	if (!scopeChain(scopes, scope).slice(1).includes(membership.scope)) return false;
 	const wanted = within === void 0 ? void 0 : Object.entries(within).find(([key]) => resolveScope(scopes, key) === membership.scope)?.[1] ?? void 0;
 	return wanted !== void 0 && scopeIdOf(membership, membership.scope) === wanted;
@@ -1661,7 +1914,22 @@ function rolesAtInstance(policy, principal, scopes, scope, id, within, now) {
 }
 /** Whether the principal holds `role` on a live membership of exactly this instance. */
 function holdsAt(principal, role, scope, id, now) {
-	return (principal.memberships ?? []).some((membership) => membership.scope === scope && membership.id === id && !isMembershipExpired(membership, now) && membership.roles.includes(role));
+	return (principal.memberships ?? []).some((membership) => membership.scope === scope && sameId(membership.id, id) && !isMembershipExpired(membership, now) && membership.roles.includes(role));
+}
+function includedRoles(role) {
+	return isReadonlyArray(role.includes) ? role.includes.filter((name) => typeof name === "string") : [];
+}
+/**
+* The membership kinds a custom role may be held through: those every
+* included declared role with `for` allows. `undefined` when none restricts.
+*/
+function customForKinds(policy, role) {
+	let kinds;
+	for (const name of includedRoles(role)) {
+		const listed = bindingOf(policy, name)?.for;
+		if (listed !== void 0) kinds = kinds === void 0 ? listed : kinds.filter((kind) => listed.includes(kind));
+	}
+	return kinds;
 }
 function conflictsWith(policy, role) {
 	const out = new Set(bindingOf(policy, role)?.exclusiveWith ?? []);
@@ -1707,7 +1975,7 @@ function heldAnchor(principal, scopes, scope, id, now) {
 * The one rule check behind `permdock.decideRoleChange`. The actor is always
 * the instance's own principal; nothing in `change` can stand in for it.
 */
-function decideRoleChange(policy, principal, scopes, change, authority, now, options = {}) {
+function decideRoleChange(policy, principal, scopes, change, customRoles, authority, now, options = {}) {
 	const name = typeof change?.role === "string" ? change.role : change?.role?.key;
 	const denials = [];
 	const deny = (reason, detail) => {
@@ -1737,12 +2005,15 @@ function decideRoleChange(policy, principal, scopes, change, authority, now, opt
 		return done(null);
 	}
 	const binding = bindingOf(policy, name);
-	if (!declaredRoleNames$1(policy).has(name)) {
+	const declared = declaredRoleNames$1(policy).has(name);
+	const named = declared ? [] : tenantCustomRoles(policy, customRoles).filter((role) => role.name === name);
+	if (!declared && named.length === 0) {
 		deny("unknown-role");
 		return done(null);
 	}
 	const scope = resolveScope(scopes, change.scope);
-	const on = binding?.on ?? findRole(policy.vocabulary?.roles, name)?.on;
+	const customAt = named.map((role) => customRoleScope(role, scopes));
+	const on = declared ? binding?.on ?? findRole(policy.vocabulary?.roles, name)?.on : customAt.includes(scope) ? scope : customAt[0];
 	const heldAt = typeof on === "string" ? resolveScope(scopes, on) : void 0;
 	if (scope === void 0 || heldAt === void 0 || heldAt !== scope) {
 		deny("scope", { expected: heldAt ?? null });
@@ -1768,6 +2039,11 @@ function decideRoleChange(policy, principal, scopes, change, authority, now, opt
 		});
 		return done(null);
 	}
+	const custom = named.find((role) => sameId(role.tenant, tenant) && customRoleScope(role, scopes) === scope && sameId(customRoleId(role) ?? change.id, change.id));
+	if (!declared && custom === void 0) {
+		deny("unknown-role");
+		return done(null);
+	}
 	if (target.managedBy === "idp") {
 		deny("externally-managed");
 		return done(null);
@@ -1783,19 +2059,21 @@ function decideRoleChange(policy, principal, scopes, change, authority, now, opt
 	} else {
 		if (self) deny(kind === "revoke" ? "self-demotion" : "not-assignable-by", { self: true });
 		const allowed = authority(tenant);
-		if (!allowed.assignable.has(name)) deny("not-assignable-by");
-		else if (usesAssigns(policy) && !allowed.manage) {
+		const revocable = kind === "revoke" && custom !== void 0 && allowed.inert?.has(name);
+		if (!allowed.assignable.has(name) && revocable !== true) deny("not-assignable-by");
+		else if (custom === void 0 && usesAssigns(policy) && !allowed.manage) {
 			const held = rolesAtInstance(policy, principal, scopes, scope, change.id, within, now);
 			by = held.find((role) => bindingOf(policy, role)?.assigns?.includes(name) === true) ?? null;
 			if (by === null) deny("not-assignable-by", { held });
 		}
 	}
 	if (kind !== "revoke" && !already) {
-		if (!mayHoldVia(policy, name, target.via)) deny("not-allowed-for-membership", {
+		const kinds = custom === void 0 ? binding?.for : customForKinds(policy, custom);
+		if (kinds !== void 0 && (target.via === void 0 || !kinds.includes(target.via))) deny("not-allowed-for-membership", {
 			via: target.via ?? null,
-			for: binding?.for
+			for: kinds
 		});
-		const conflicts = conflictsWith(policy, name);
+		const conflicts = custom === void 0 ? conflictsWith(policy, name) : new Set(includedRoles(custom).flatMap((include) => Array.from(conflictsWith(policy, include))));
 		const clash = targetRoles.filter((role) => conflicts.has(role));
 		if (clash.length > 0) deny("conflicting-role", { with: clash });
 	}
@@ -1849,7 +2127,7 @@ async function discoverRole(item, allow, ctx) {
 		ctx.incomplete();
 		return;
 	}
-	const key = findScope(ctx.scopes, item.scope)?.key;
+	const key = scopeField(ctx.resource, item.scope, ctx.scopes);
 	const id = key === void 0 ? void 0 : relationId(ownGet(ctx.row, key));
 	if (id === void 0) return;
 	const members = await ctx.list(item.scope, id);
@@ -2002,6 +2280,7 @@ function discover(grant, item, ctx) {
 		case "plan":
 		case "actor":
 		case "assurance":
+		case "inherit":
 			ctx.incomplete();
 			return Promise.resolve();
 		default: return unknownKind(item, ctx);
@@ -2069,7 +2348,7 @@ async function whoCan(input) {
 	};
 	await Promise.all((policy.index.grantsByKey.get(permission.key) ?? []).flatMap((grant) => flattenGrantee(grant.to).map((item) => discover(grant, item, ctx))));
 	const root = rootScope(scopes);
-	const tenantKey = root === void 0 ? void 0 : findScope(scopes, root)?.key;
+	const tenantKey = root === void 0 ? void 0 : scopeField(getResource(policy.permissions, permission.resource), root, scopes);
 	const tenant = tenantKey === void 0 ? void 0 : relationId(ownGet(row, tenantKey));
 	const env = {
 		emit: false,
@@ -2161,8 +2440,8 @@ function heldRoleNames(policy, subject, tenant, only, now) {
 	if (only?.scope !== void 0 && scope === void 0) return [];
 	const names = new Set(scope === void 0 ? subject.principal.roles ?? [] : []);
 	for (const membership of subject.principal.memberships ?? []) {
-		if (isMembershipExpired(membership, now)) continue;
-		if (!(scope === void 0 ? tenantOf(membership, scopes) === tenant : membership.scope === scope && (only?.id === void 0 || membership.id === only.id))) continue;
+		if (isMembershipExpired(membership, now) || membership.keep !== void 0) continue;
+		if (!(scope === void 0 ? tenantOf(membership, scopes) === tenant : membership.scope === scope && (only?.id === void 0 || sameId(membership.id, only.id)))) continue;
 		for (const role of membership.roles) names.add(role);
 	}
 	return rankRoles(policy, [...names]);
@@ -2183,11 +2462,12 @@ function roleLeaf(policy, name) {
 function graphAware(grant, where) {
 	const combined = combineWhere(grant.where, where);
 	const graph = hasConditionOp(combined, "related");
+	const inherits = flattenGrantee(grant.to).some((item) => item.kind === "inherit");
 	return freezeDeep(compact({
 		...grant,
 		where: combined,
 		portable: graph ? false : grant.portable,
-		graph: graph && grant.portable ? true : void 0
+		graph: graph && grant.portable && !inherits ? true : void 0
 	}));
 }
 /**
@@ -2215,33 +2495,35 @@ function collectSnapshotGrants(policy, subject, customRoles, now = nowSeconds(),
 		roles: new Set(expandRoleNames(membership.roles, declared, customRoles, tenantOf(membership, scopes)).roles)
 	}));
 	const holds = (entry, item) => entry.roles.has(item.role) && (typeof item.scope === "string" ? entry.membership.scope === item.scope : entry.membership.on !== void 0);
+	const requirementOf = (grant, resource) => grant.requires === void 0 || grant.effect !== "allow" ? void 0 : requirementCondition(policy, subject, grant.requires, resource, now, customRoles, customGrants);
 	const out = [];
 	for (const grant of grantList(policy)) {
+		if (mode === "held" && !coversRequirements(policy.permissions, grant.requires, subject.delegation)) continue;
 		const resource = getResource(policy.permissions, grant.permission.resource);
 		const match = matchGrantee(grant.to, subject, now, resource, scopes, policy.resources);
 		if (skip(grant, match)) continue;
 		const roleItems = flattenGrantee(grant.to).filter((item) => item.kind === "role");
 		if (roleItems.length > 0 && subject.principal === null) continue;
 		if (!roleItems.every((item) => item.scope !== "global" || global.roles.includes(item.role))) continue;
-		const merged = graphAware(grant, match.where);
+		const merged = graphAware(grant, combineWhere(match.where, requirementOf(grant, resource)));
 		const scoped = roleItems.filter((item) => item.scope !== "global");
 		if (scoped.length === 0) {
 			out.push({ grant: merged });
 			continue;
 		}
-		for (const entry of held) if (scoped.every((item) => item.kind === "role" && holds(entry, item))) out.push({
+		for (const entry of held) if (keepsPermission(entry.membership, grant.permission.key) && scoped.every((item) => item.kind === "role" && holds(entry, item))) out.push({
 			grant: merged,
 			membership: entry.membership
 		});
 	}
 	for (const { grant, role } of customGrants) {
 		const globalHeld = holdsGlobalCustomRole(subject.principal?.roles, role);
-		const holders = held.filter((entry) => holdsCustomRole(entry.membership, role, scopes));
+		const holders = held.filter((entry) => keepsPermission(entry.membership, grant.permission.key) && holdsCustomRole(entry.membership, role, scopes));
 		if (holders.length === 0 && !globalHeld) continue;
 		const resource = getResource(policy.permissions, grant.permission.resource);
 		const match = matchGrantee(grant.to, subject, now, resource, scopes, policy.resources);
 		if (skip(grant, match)) continue;
-		const merged = graphAware(grant, match.where);
+		const merged = graphAware(grant, combineWhere(match.where, requirementOf(grant, resource)));
 		if (globalHeld) out.push({ grant: merged });
 		for (const entry of holders) out.push({
 			grant: merged,
@@ -2262,6 +2544,20 @@ function assignableCandidates(policy) {
 	return rankRoles(policy, [...new Set(names)]).map((name) => roleLeaf(policy, name));
 }
 /**
+* The levels a held allow of a permission covers: its own `level`, every
+* level when it has no row condition, or the levels whose condition equals
+* its condition.
+*/
+function heldLevels(policy, grant, names) {
+	if (grant.level !== void 0) return [grant.level];
+	if (grant.where === void 0) return names;
+	const held = canonicalJson(grant.where);
+	return names.filter((name) => {
+		const condition = levelCondition(policy, grant.permission.resource, name);
+		return condition !== void 0 && canonicalJson(condition) === held;
+	});
+}
+/**
 * What the subject may hand out in `tenant`: declared assignable roles and the
 * tenant custom-role ceiling, narrowed by `allowed` (`RoleSource.assignable`),
 * then intersected with the permissions the subject holds there. Holding a
@@ -2272,7 +2568,9 @@ function assignableIn(policy, subject, customRoles, customGrants, tenant, allowe
 	if (principal === null) return {
 		roles: [],
 		permissions: [],
-		manage: false
+		levels: {},
+		manage: false,
+		inert: []
 	};
 	const scopes = scopeList(policy.scopes);
 	const scoped = tenant === void 0 ? subject : freezeDeep(compact({
@@ -2282,7 +2580,8 @@ function assignableIn(policy, subject, customRoles, customGrants, tenant, allowe
 			tenant: resolveActiveTenant(principal, tenant, scopes, now)
 		})
 	}));
-	const heldKeys = new Set(collectSnapshotGrants(policy, scoped, customRoles, now, customGrants).filter((item) => item.grant.effect === "allow" && (item.membership === void 0 || !global && tenantOf(item.membership, scopes) === tenant && !isMembershipExpired(item.membership, now))).map((item) => item.grant.permission.key));
+	const heldGrants = collectSnapshotGrants(policy, scoped, customRoles, now, customGrants).filter((item) => item.grant.effect === "allow" && (item.membership === void 0 || !global && tenantOf(item.membership, scopes) === tenant && !isMembershipExpired(item.membership, now))).map((item) => item.grant);
+	const heldKeys = new Set(heldGrants.map((grant) => grant.permission.key));
 	const heldNames = heldRoleNames(policy, subject, tenant, void 0, now);
 	const quiet = {
 		emit: false,
@@ -2313,10 +2612,72 @@ function assignableIn(policy, subject, customRoles, customGrants, tenant, allowe
 	});
 	const root = global ? "global" : rootScope(scopes);
 	const ceiling = new Set((root === void 0 ? [] : ceilingGrants(policy, root, allowed)).map((grant) => grant.permission.key));
+	const permissions = listPermissions(policy.permissions).filter((leaf) => ceiling.has(leaf.key) && (manage || heldKeys.has(leaf.key)));
+	const offeredLevels = (key, names) => {
+		if (manage) return names;
+		const reached = new Set(heldGrants.filter((grant) => grant.permission.key === key).flatMap((grant) => heldLevels(policy, grant, names)));
+		return names.filter((name) => reached.has(name));
+	};
+	const levels = {};
+	for (const leaf of permissions) {
+		const names = leaf.kind === "instance" ? levelNames(policy, leaf.resource) : [];
+		if (names.length > 0) levels[leaf.key] = offeredLevels(leaf.key, names);
+	}
+	const ceilingKeys = /* @__PURE__ */ new Map();
+	const mayHandOut = (scope, grant) => {
+		const key = grant.permission.key;
+		let keys = ceilingKeys.get(scope);
+		if (keys === void 0) {
+			keys = new Set(ceilingGrants(policy, scope, allowed).map((item) => item.permission.key));
+			ceilingKeys.set(scope, keys);
+		}
+		if (!keys.has(key) || !(manage || heldKeys.has(key))) return false;
+		const names = grant.permission.kind === "instance" ? levelNames(policy, grant.permission.resource) : [];
+		if (names.length === 0) return true;
+		const offered = offeredLevels(key, names);
+		return heldLevels(policy, grant, names).every((name) => offered.includes(name));
+	};
+	const custom = global || tenant === void 0 ? {
+		roles: [],
+		inert: []
+	} : assignableCustomRoles(policy, customRoles, tenant, manage ? void 0 : roles, mayHandOut);
 	return {
-		roles,
-		permissions: listPermissions(policy.permissions).filter((leaf) => ceiling.has(leaf.key) && (manage || heldKeys.has(leaf.key))),
-		manage
+		roles: [...roles, ...custom.roles],
+		permissions,
+		levels,
+		manage,
+		inert: custom.inert
+	};
+}
+/**
+* The tenant's custom roles the subject may hand out: held at a scope it may
+* assign declared roles at (any scope with `meta.manageRoles`), allowing at
+* least one permission after the ceiling, and only permissions and levels it
+* may hand out at that scope. A role that allows nothing is `inert`.
+*/
+function assignableCustomRoles(policy, customRoles, tenant, declared, mayHandOut) {
+	const scopes = scopeList(policy.scopes);
+	const root = rootScope(scopes);
+	const assignsAt = declared === void 0 ? void 0 : new Set(declared.map((leaf) => leaf.on === void 0 ? root : resolveScope(scopes, leaf.on)));
+	const out = /* @__PURE__ */ new Map();
+	const inert = /* @__PURE__ */ new Set();
+	for (const role of tenantCustomRoles(policy, customRoles)) {
+		if (role.tenant !== tenant || out.has(role.name)) continue;
+		const at = customRoleScope(role, scopes);
+		if (at === void 0 || assignsAt !== void 0 && !assignsAt.has(at)) continue;
+		const { grants } = resolveCustomRole(policy, role);
+		if (!grants.some((grant) => grant.effect === "allow")) {
+			inert.add(role.name);
+			continue;
+		}
+		if (grants.every((grant) => grant.effect === "deny" || mayHandOut(at, grant))) out.set(role.name, synthesiseRole(role.name, {
+			on: at,
+			assignable: true
+		}));
+	}
+	return {
+		roles: [...out.values()].toSorted((a, b) => a.key.localeCompare(b.key)),
+		inert: [...inert].filter((name) => !out.has(name)).toSorted()
 	};
 }
 /** The one path from a resolved subject to a `Snapshot`; pure apart from the default clock. */
@@ -2340,14 +2701,16 @@ function snapshotOf(policy, subject, options) {
 		now: Math.floor(now),
 		vocabulary: policy.vocabulary,
 		scopes: snapshotScopes(policy),
+		idOf: (name) => getResource(policy.permissions, name)?.id,
 		delegated: delegatedPermissions(policy.delegations, subject, new Set(roles), now),
 		assignable: (tenant) => {
 			const found = assignableIn(policy, subject, options.customRoles, customGrants, tenant, options.assignable?.get(tenant), now);
-			return {
+			return compact({
 				tenant,
 				roles: found.roles.map((leaf) => leaf.key),
-				permissions: found.permissions
-			};
+				permissions: found.permissions,
+				levels: Object.keys(found.levels).length === 0 ? void 0 : found.levels
+			});
 		}
 	}));
 }
@@ -2356,12 +2719,18 @@ function snapshotScopes(policy) {
 	if (policy.scopes.length === 0) return;
 	const resources = [...policy.resources.values()];
 	return policy.scopes.map((scope) => {
-		const partitioned = resources.filter((node) => partitionsOf(node, policy.scopes).includes(scope.name)).map((node) => node.name);
+		const nodes = resources.filter((node) => partitionsOf(node, policy.scopes).includes(scope.name));
+		const partitioned = nodes.map((node) => node.name);
+		const fields = Object.fromEntries(nodes.flatMap((node) => {
+			const field = scopeField(node, scope.name, policy.scopes);
+			return field === void 0 || field === scope.key ? [] : [[node.name, field]];
+		}));
 		return compact({
 			name: scope.name,
 			key: scope.key ?? "",
 			within: scope.within,
-			resources: partitioned.length === 0 ? void 0 : partitioned
+			resources: partitioned.length === 0 ? void 0 : partitioned,
+			fields: Object.keys(fields).length === 0 ? void 0 : fields
 		});
 	});
 }
@@ -2457,7 +2826,8 @@ function buildInstance(policy, subject, envBase, team) {
 			scope: permission.scope,
 			resource: resourceRef,
 			subject,
-			message: deniedMessage(permission.key, subject.principal?.id, decision.denials, decision.alternatives.map((leaf) => leaf.key))
+			message: deniedMessage(permission.key, subject.principal?.id, decision.denials, decision.alternatives.map((leaf) => leaf.key)),
+			...data === void 0 || resource === void 0 ? {} : { disclosure: resource.disclosure }
 		});
 	};
 	const instance = {
@@ -2473,7 +2843,10 @@ function buildInstance(policy, subject, envBase, team) {
 			let granted = 0;
 			let denied = 0;
 			let approvalRequired = 0;
-			const quiet = envFor(false);
+			const quiet = {
+				...envFor(false, true),
+				outcomeOnly: true
+			};
 			const trusted = options?.trusted ?? true;
 			const decideOptions = {
 				...options,
@@ -2533,6 +2906,7 @@ function buildInstance(policy, subject, envBase, team) {
 				graph: envBase.relations !== void 0,
 				scopes: scopeList(policy.scopes),
 				partitioned: (name, key) => relatesTo(getResource(policy.permissions, permission.resource), key, name, scopeList(policy.scopes)),
+				fieldOf: (name) => scopeField(getResource(policy.permissions, permission.resource), name, scopeList(policy.scopes)),
 				tenant: subject.principal?.tenant,
 				team,
 				now: nowSeconds(),
@@ -2615,7 +2989,7 @@ function buildInstance(policy, subject, envBase, team) {
 				relationCache
 			}, team);
 		}),
-		snapshot(options) {
+		snapshot: ((options) => {
 			const snapshot = snapshotOf(policy, subject, compact({
 				customRoles: envBase.customRoles,
 				customGrants,
@@ -2626,7 +3000,7 @@ function buildInstance(policy, subject, envBase, team) {
 			}));
 			if (options?.signer !== void 0) return signSnapshot(snapshot, options.signer, options.audience);
 			return snapshot;
-		},
+		}),
 		on(event, handler) {
 			const set = listeners[event];
 			set.add(handler);
@@ -2687,24 +3061,111 @@ function buildInstance(policy, subject, envBase, team) {
 			const tenant = options?.tenant ?? subject.principal?.tenant;
 			return tenant === void 0 ? [] : assignableAt(tenant).permissions;
 		},
+		assignableLevels(permission, options) {
+			const of = (found) => (Object.hasOwn(found.levels, permission.key) ? found.levels[permission.key] : void 0) ?? [];
+			if (options?.scope === "global") return of(assignableIn(policy, subject, envBase.customRoles, customGrants, void 0, void 0, nowSeconds(), true));
+			const tenant = options?.tenant ?? subject.principal?.tenant;
+			return tenant === void 0 ? [] : of(assignableAt(tenant));
+		},
 		decideRoleChange(change, options) {
-			return decideRoleChange(policy, subject.principal, scopeList(policy.scopes), change, (tenant) => {
+			return decideRoleChange(policy, subject.principal, scopeList(policy.scopes), change, envBase.customRoles, (tenant) => {
 				const found = assignableAt(tenant);
 				return {
 					assignable: new Set(found.roles.map((leaf) => leaf.key)),
-					manage: found.manage
+					manage: found.manage,
+					inert: new Set(found.inert)
 				};
 			}, nowSeconds(), options);
 		},
 		activate(input) {
 			return activate(policy, subject, input, nowSeconds());
 		},
+		derive(options) {
+			const scopes = scopeList(policy.scopes);
+			const tenants = tenantsOf(subject.principal, scopes);
+			const auth = [];
+			const named = options.customRoles === void 0 ? void 0 : roleSourceFor(options.customRoles, subject, auth);
+			const roleSource = options.customRoles === void 0 ? envBase.roleSource : named;
+			const roles = options.customRoles === void 0 ? envBase.customRoles : customRolesFor(named, tenants, auth, subject.principal === null ? void 0 : subject.principal.roles ?? [], (tenant) => heldRoleNamesIn(subject.principal, scopes, tenant));
+			const names = options.customRoles === void 0 ? envBase.assignable : assignableNamesFor(named, tenants, auth);
+			const approvals = options.approvalPolicies === void 0 ? envBase.approvalPolicies : approvalPoliciesFor(policy, options.approvalPolicies, tenants, auth);
+			const relationSource = options.relations ?? envBase.relations;
+			const build = (loadedRoles, loadedNames, loadedApprovals) => buildInstance(policy, subject, compact({
+				...envBase,
+				customRoles: loadedRoles,
+				roleSource,
+				assignable: loadedNames,
+				approvalPolicies: loadedApprovals,
+				relations: relationSource,
+				relationCache: options.relations === void 0 ? relationCache : void 0,
+				queuedAuth: auth,
+				queuedErrors: []
+			}), team);
+			if (isThenable(roles) || isThenable(names) || isThenable(approvals)) return Promise.all([
+				roles,
+				names,
+				approvals
+			]).then(([loadedRoles, loadedNames, loadedApprovals]) => build(loadedRoles, loadedNames, loadedApprovals));
+			return build(roles, names, approvals);
+		},
 		subject
 	};
 	return Object.freeze(instance);
 }
 //#endregion
+//#region src/core/oauth-scopes.ts
+/**
+* `delegation` with every coarse OAuth scope the policy declares in
+* `oauthScopes` followed by the scopes of the permissions it covers, so the
+* delegation checks downstream match them. The token's scopes stay first and
+* unchanged; an undeclared scope expands to nothing.
+*/
+function expandOAuthScopes(policy, delegation) {
+	const declared = policy.oauthScopes;
+	const scopes = delegation?.scopes;
+	if (declared === void 0 || delegation === void 0 || scopes === void 0) return delegation;
+	const out = new Set(scopes);
+	for (const entry of declared) if (scopes.includes(entry.scope)) for (const scope of entry.scopes) out.add(scope);
+	return out.size === scopes.length ? delegation : {
+		...delegation,
+		scopes: [...out]
+	};
+}
+/** The coarse scopes the policy declares that cover `permission`, in declaration order. */
+function coarseScopesFor(policy, permission) {
+	return (policy.oauthScopes ?? []).filter((entry) => entry.permissions.includes(permission.key)).map((entry) => entry.scope);
+}
+/** Every token scope that reaches `permission`: its own, any it was renamed from, and the coarse scopes covering it. */
+function scopesReaching(policy, permission) {
+	return [
+		permission.scope,
+		...formerScopes(permission),
+		...coarseScopesFor(policy, permission)
+	];
+}
+/**
+* The scope an `insufficient_scope` challenge names for `permission`: the
+* first coarse scope that covers it, which the authorization server issues,
+* else the permission's own scope.
+*/
+function challengeScope(policy, permission) {
+	return coarseScopesFor(policy, permission)[0] ?? permission.scope;
+}
+//#endregion
 //#region src/core/resolve-subject.ts
+/**
+* The tenant a user API key holds its owner to (`Credential.tenant`): only
+* the memberships inside it count, and no global role.
+*/
+function heldTenantOf(principal) {
+	const credential = principal["credential"];
+	if (credential === null || typeof credential !== "object" || !Object.hasOwn(credential, "tenant") || !Object.hasOwn(credential, "kind")) return;
+	const record = credential;
+	return record.kind === "user" && typeof record.tenant === "string" && record.tenant !== "" ? record.tenant : void 0;
+}
+function outsideHeld(held, options) {
+	return held !== void 0 && options.tenant !== void 0 && options.tenant !== held;
+}
 function assemblePrincipal(policy, user, options, auth) {
 	let principal;
 	let context = {};
@@ -2712,6 +3173,7 @@ function assemblePrincipal(policy, user, options, auth) {
 	let delegation = options.delegation;
 	let session = options.session;
 	let expiresAt = options.expiresAt;
+	let liveSession;
 	try {
 		if (user === null || user === void 0) principal = policy.subject(user);
 		else if (isSubject(user)) {
@@ -2721,6 +3183,7 @@ function assemblePrincipal(policy, user, options, auth) {
 			delegation = user.delegation ?? delegation;
 			session = user.session ?? session;
 			expiresAt = user.expiresAt ?? expiresAt;
+			liveSession = user.liveSession === true ? true : void 0;
 		} else if (isPrincipal(user)) principal = user;
 		else principal = policy.subject(user);
 	} catch {
@@ -2731,30 +3194,73 @@ function assemblePrincipal(policy, user, options, auth) {
 	let live = false;
 	const source = options.memberships === void 0 ? void 0 : asMembershipSource(options.memberships);
 	const fromClaims = source?.claimsFirst === true && principal?.memberships !== void 0 && principal.membershipsTruncated !== true;
-	if (principal !== null && source !== void 0 && !fromClaims) {
-		live = true;
+	const read = (from, of) => {
 		try {
-			memberships = source.membershipsFor(compact({
-				id: principal.id,
-				kind: principal.kind
+			return from.membershipsFor(compact({
+				id: of.id,
+				kind: of.kind
 			}), compact({ tenant: options.tenant }));
 		} catch {
 			auth.push({
 				reason: "source-threw",
 				source: "memberships"
 			});
-			memberships = [];
+			return [];
 		}
+	};
+	let stale;
+	if (principal !== null && source !== void 0 && !fromClaims) {
+		live = true;
+		memberships = read(source, principal);
+	} else if (principal?.memberships !== void 0 && fromClaims && source.onStale === "reread" && source.version !== void 0) {
+		const reread = rereadStale(source, principal, principal.memberships, () => read(source, principal), auth);
+		memberships = reread.memberships;
+		stale = reread.stale;
 	}
-	return {
+	return compact({
 		principal,
 		context: contextResult,
 		actor,
-		delegation,
+		delegation: expandOAuthScopes(policy, delegation),
 		session,
 		expiresAt,
 		memberships,
-		live
+		live,
+		stale,
+		liveSession: principal === null ? void 0 : liveSession
+	});
+}
+function versionQuery(principal) {
+	return compact({
+		id: principal.id,
+		roles: principal.roles,
+		memberships: principal.memberships
+	});
+}
+function rereadStale(source, principal, claims, read, auth) {
+	const claimed = principal.authzVersion;
+	const judge = (current) => typeof claimed === "number" && current !== void 0 && claimed >= current ? "fresh" : "reread";
+	const unknown = () => {
+		auth.push({
+			reason: "source-threw",
+			source: "memberships"
+		});
+		return "unknown";
+	};
+	let freshness;
+	try {
+		const current = source.version?.(versionQuery(principal));
+		freshness = isThenable(current) ? Promise.resolve(current).then(judge, unknown) : judge(current);
+	} catch {
+		freshness = unknown();
+	}
+	if (isThenable(freshness)) return {
+		memberships: freshness.then((found) => found === "reread" ? read() : claims),
+		stale: freshness.then((found) => found === "unknown")
+	};
+	return {
+		memberships: freshness === "reread" ? read() : claims,
+		stale: freshness === "unknown"
 	};
 }
 function finishSubject(policy, assembled, context, input, options, extra) {
@@ -2766,7 +3272,10 @@ function finishSubject(policy, assembled, context, input, options, extra) {
 		expiresAt: assembled.expiresAt
 	}));
 	const scopes = scopeList(policy.scopes);
-	const { roles, memberships } = applyRoleKinds(policy, assembled.principal.roles, normalizeMemberships(input, scopes));
+	const held = heldTenantOf(assembled.principal);
+	const kinds = applyRoleKinds(policy, assembled.principal.roles, normalizeMemberships(input, scopes));
+	const roles = held === void 0 ? kinds.roles : [];
+	const memberships = held === void 0 ? kinds.memberships : outsideHeld(held, options) ? [] : kinds.memberships.filter((membership) => tenantOf(membership, scopes) === held);
 	const plans = [.../* @__PURE__ */ new Set([...assembled.principal.plans ?? [], ...extra.plans])];
 	const withMemberships = freezeCopy(compact({
 		...assembled.principal,
@@ -2782,11 +3291,14 @@ function finishSubject(policy, assembled, context, input, options, extra) {
 		context: freezeCopy(context),
 		session: assembled.session,
 		expiresAt: assembled.expiresAt,
-		stale: extra.stale ? true : void 0
+		stale: extra.stale ? true : void 0,
+		liveSession: assembled.liveSession
 	}));
 }
 function activeTenantOf(policy, assembled, memberships, options) {
 	if (assembled.principal === null) return;
+	const held = heldTenantOf(assembled.principal);
+	if (held !== void 0) return outsideHeld(held, options) ? void 0 : held;
 	return resolveActiveTenant({
 		...assembled.principal,
 		memberships
@@ -2807,12 +3319,13 @@ function settle(value, fallback, onError) {
 function staleness(policy, assembled, options, auth) {
 	const principal = assembled.principal;
 	if ((policy.fresh ?? []).length === 0 || principal === null || assembled.live) return false;
+	if (assembled.stale !== void 0) return assembled.stale;
 	const source = options.memberships === void 0 ? void 0 : asMembershipSource(options.memberships);
 	const claimed = principal.authzVersion;
 	if (source?.version === void 0 || typeof claimed !== "number") return true;
 	const compare = (current) => current === void 0 || claimed < current;
 	try {
-		const current = source.version({ id: principal.id });
+		const current = source.version(versionQuery(principal));
 		return isThenable(current) ? settle(Promise.resolve(current).then(compare), true, () => {
 			auth.push({
 				reason: "source-threw",
@@ -2832,7 +3345,7 @@ function cleanNames(list) {
 }
 function entitlementsOf(assembled, tenant, options, auth) {
 	const source = options.entitlements;
-	if (source === void 0 || assembled.principal === null) return [];
+	if (source === void 0 || assembled.principal === null || outsideHeld(heldTenantOf(assembled.principal), options)) return [];
 	try {
 		const found = source.entitlementsFor({ id: assembled.principal.id }, compact({ tenant }));
 		return isThenable(found) ? settle(Promise.resolve(found).then(cleanNames), [], () => {
@@ -2921,9 +3434,11 @@ function hostedPolicy(policy, source) {
 }
 function instantiate(codePolicy, subject, options, auth) {
 	const { policy, errors } = hostedPolicy(codePolicy, options.policies);
-	const tenants = tenantsOf(subject.principal, scopeList(policy.scopes));
-	const customRoles = customRolesFor(options.customRoles, tenants, auth, subject.principal !== null);
-	const assignable = assignableNamesFor(options.customRoles, tenants, auth);
+	const scopes = scopeList(policy.scopes);
+	const tenants = tenantsOf(subject.principal, scopes);
+	const roleSource = roleSourceFor(options.customRoles, subject, auth);
+	const customRoles = customRolesFor(roleSource, tenants, auth, subject.principal === null ? void 0 : subject.principal.roles ?? [], (tenant) => heldRoleNamesIn(subject.principal, scopes, tenant));
+	const assignable = assignableNamesFor(roleSource, tenants, auth);
 	const approvals = approvalPoliciesFor(policy, options.approvalPolicies, tenants, auth);
 	const build = (roles, names, approvalPolicies) => buildInstance(policy, subject, compact({
 		customRoles: roles,
@@ -2931,7 +3446,7 @@ function instantiate(codePolicy, subject, options, auth) {
 		limits: options.limits,
 		limitCache: /* @__PURE__ */ new Map(),
 		simulated: false,
-		roleSource: options.customRoles,
+		roleSource,
 		assignable: names,
 		queuedAuth: auth,
 		queuedErrors: errors,
@@ -2953,4 +3468,4 @@ function createPermDock(policy, user, options = {}) {
 	return instantiate(policy, subject, options, auth);
 }
 //#endregion
-export { approvalPoliciesFor as _, snapshotScopes as a, supportAccess as c, membershipsClaim as d, resolveCustomRole as f, isExternallyManaged as g, composeMemberships as h, snapshotOf as i, customRoleClaim as l, claimsFirst as m, resolveSubject as n, declaredRoleNames as o, validateCustomRole as p, collectSnapshotGrants as r, breakGlass as s, createPermDock as t, customRoleScope as u, memoryApprovalPolicies as v };
+export { countHolders as C, memoryApprovalPolicies as D, approvalPoliciesFor as E, validateApprovalPolicy as O, composeMemberships as S, APPROVAL_POLICY_UNAVAILABLE as T, leveled as _, collectSnapshotGrants as a, validateCustomRole as b, rankRoles as c, breakGlass as d, supportAccess as f, customRoleScope as g, customRoleClaim as h, scopesReaching as i, usesAssigns as l, ceilingGrants as m, resolveSubject as n, snapshotOf as o, andWhere as p, challengeScope as r, snapshotScopes as s, createPermDock as t, declaredRoleNames as u, membershipsClaim as v, isExternallyManaged as w, claimsFirst as x, resolveCustomRole as y };