@classytic/arc 2.28.0 → 2.31.0

package/dist/{permissions-BrtiBKGs.mjs → permissions-L--QDAir.mjs}

@@ -1,10 +1,69 @@
-import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
-import { n as getUserRoles } from "./userHelpers-Cg_y3fBz.mjs";
-import { C as isService, S as isOrgInScope, a as getDPoPJkt, b as isElevated, d as getScopeContext, f as getScopeContextMap, g as getUserId, m as getTeamId, o as getMandate, p as getServiceScopes, u as getRequestScope, v as hasOrgAccess, x as isMember } from "./types-CSyCxl2V.mjs";
-import { t as MemoryCacheStore } from "./memory-CmnzXE5Z.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-CUsjNX9R.mjs";
+import { arcLog } from "./logger/index.mjs";
+import { a as conjoinPolicyFilters, i as normalizeToDecision } from "./authorizationDecision-ChvUQGG1.mjs";
+import { n as getUserRoles } from "./userHelpers-ChYJ6CdK.mjs";
+import { C as isService, S as isOrgInScope, a as getDPoPJkt, b as isElevated, d as getScopeContext, f as getScopeContextMap, g as getUserId, m as getTeamId, n as PUBLIC_SCOPE, o as getMandate, p as getServiceScopes, u as getRequestScope, v as hasOrgAccess, x as isMember } from "./types-Cys0ko9Z.mjs";
+import { t as MemoryCacheStore } from "./memory-DR6wpa9F.mjs";
 import { randomUUID } from "node:crypto";
+//#region src/permissions/context.ts
+/**
+* PermissionContext accessors (arc 2.30 — transport-neutral evaluation).
+*
+* The goal of the standardized authorization core is that a `PermissionCheck`
+* reads FACTS off its {@link PermissionContext}, never off a raw
+* `FastifyRequest`. That makes evaluation:
+*   - pure (a combinator can hand a child a NEW context with an updated scope
+*     instead of mutating `request.scope` — see `algebra.ts`),
+*   - transport-neutral (MCP / jobs / websockets build a context directly, no
+*     `fakeRequest`),
+*   - unit-testable (no Fastify object required).
+*
+* `scopeOf` is the single seam every primitive uses to read the request scope.
+* It prefers the context's first-class `scope` (set by combinators + adapters)
+* and falls back to the raw request during migration (the `ctx.request` shim
+* removed in the final phase). Once `scope` is populated everywhere, the
+* fallback is dead and drops out.
+*/
+/**
+* Resolve the request scope for a permission check. Prefers the context's
+* first-class `scope`; falls back to the raw HTTP `request.scope` when present,
+* else `PUBLIC_SCOPE`. Primitives MUST use this instead of touching
+* `ctx.request` so scope threads through combinators and non-HTTP transports
+* (MCP, jobs) — which have no request — resolve identity correctly.
+*/
+function scopeOf(ctx) {
+	if (ctx.scope) return ctx.scope;
+	return ctx.request ? getRequestScope(ctx.request) : PUBLIC_SCOPE;
+}
+//#endregion
 //#region src/permissions/core.ts
 /**
+* Build an `allow` {@link AuthorizationDecision}, optionally attaching a row-level
+* `policy` and/or a `scope` to install. The idiomatic "grant" return for arc
+* 2.30 checks (parallels Cedar's `permit`).
+*
+* @example
+* return allow();                                  // simple grant
+* return allow({ policy: { ownerId: userId } });   // grant + row policy
+*/
+function allow(extra) {
+	return extra ? {
+		effect: "allow",
+		...extra
+	} : { effect: "allow" };
+}
+/**
+* Build a `deny` {@link AuthorizationDecision} with an optional human-readable
+* reason (parallels Cedar's `forbid`). The idiomatic "refuse" return.
+*/
+function deny(reason) {
+	return reason ? {
+		effect: "deny",
+		reason
+	} : { effect: "deny" };
+}
+/**
 * Normalize a `string | [readonly string[]]` rest-args tuple into a single
 * `readonly string[]`. Lets a permission helper accept BOTH variadic and
 * array call shapes from one overload signature.
@@ -45,12 +104,10 @@ function allowPublic() {
 */
 function requireAuth() {
 	const check = (ctx) => {
-		if (!ctx.user) return {
-			granted: false,
-			reason: "Authentication required"
-		};
+		if (!ctx.user) return deny("Authentication required");
 		return true;
 	};
+	check._requiresAuth = true;
 	return check;
 }
 function requireRoles(rolesOrFirst, optionsOrSecond, ...rest) {
@@ -69,24 +126,48 @@ function requireRoles(rolesOrFirst, optionsOrSecond, ...rest) {
 	}
 	const includeOrgRoles = options?.includeOrgRoles ?? true;
 	const check = (ctx) => {
-		if (!ctx.user) return {
-			granted: false,
-			reason: "Authentication required"
-		};
+		if (!ctx.user) return deny("Authentication required");
 		const userRoles = getUserRoles(ctx.user);
 		if (options?.bypassRoles?.some((r) => userRoles.includes(r))) return true;
 		if (roles.some((r) => userRoles.includes(r))) return true;
 		if (includeOrgRoles) {
-			const scope = getRequestScope(ctx.request);
+			const scope = scopeOf(ctx);
 			if (isElevated(scope)) return true;
 			if (isMember(scope) && roles.some((r) => scope.orgRoles.includes(r))) return true;
 		}
-		return {
-			granted: false,
-			reason: `Required roles: ${roles.join(", ")}`
-		};
+		return deny(`Required roles: ${roles.join(", ")}`);
+	};
+	check._roles = roles;
+	return check;
+}
+/**
+* Require a PLATFORM role — global roles only. An organization role can never
+* satisfy this gate.
+*
+* `requireRoles(["ops"])` also accepts an ORG role named `ops` (that is its
+* documented default), and `requireOrgRole("manager")` grants ANY organization's
+* manager. Both return a bare allow with no policy, so a surface that is global
+* by construction — a queue dashboard, a cluster-wide operations endpoint —
+* cannot distinguish them from a real operator gate by looking at the decision.
+* That makes "platform-only" a property the check has to DECLARE, which is what
+* `_platformOnly` records and what such a surface can then require.
+*
+* Elevated scope passes: platform admin is the identity this gate is for.
+*
+* @example
+* permissions: { list: requirePlatformRole("platform-ops") }
+*/
+function requirePlatformRole(...args) {
+	const roles = normalizeVariadicOrArray(args);
+	const check = (ctx) => {
+		if (isElevated(scopeOf(ctx))) return true;
+		if (!ctx.user) return deny("Authentication required");
+		const userRoles = getUserRoles(ctx.user);
+		if (roles.some((r) => userRoles.includes(r))) return true;
+		return deny(`Required platform roles: ${roles.join(", ")}`);
 	};
 	check._roles = roles;
+	check._platformOnly = true;
 	return check;
 }
 /**
@@ -97,19 +178,13 @@ function requireRoles(rolesOrFirst, optionsOrSecond, ...rest) {
 function roles(...args) {
 	const roleList = normalizeVariadicOrArray(args);
 	const check = (ctx) => {
-		if (!ctx.user) return {
-			granted: false,
-			reason: "Authentication required"
-		};
+		if (!ctx.user) return deny("Authentication required");
 		const userRoles = getUserRoles(ctx.user);
 		if (roleList.some((r) => userRoles.includes(r))) return true;
-		const scope = getRequestScope(ctx.request);
+		const scope = scopeOf(ctx);
 		if (isElevated(scope)) return true;
 		if (isMember(scope) && roleList.some((r) => scope.orgRoles.includes(r))) return true;
-		return {
-			granted: false,
-			reason: `Required roles: ${roleList.join(", ")}`
-		};
+		return deny(`Required roles: ${roleList.join(", ")}`);
 	};
 	check._roles = roleList;
 	return check;
@@ -128,31 +203,29 @@ function roles(...args) {
 */
 function requireOwnership(ownerField = "userId", options) {
 	return (ctx) => {
-		if (!ctx.user) return {
-			granted: false,
-			reason: "Authentication required"
-		};
+		if (!ctx.user) return deny("Authentication required");
 		const userRoles = getUserRoles(ctx.user);
 		if (options?.bypassRoles?.some((r) => userRoles.includes(r))) return true;
-		const userId = getUserId(getRequestScope(ctx.request)) ?? ctx.user.id ?? ctx.user._id;
-		if (!userId) return {
-			granted: false,
-			reason: "User identity missing (no id or _id)"
-		};
-		return {
-			granted: true,
-			filters: { [ownerField]: userId }
-		};
+		const userId = getUserId(scopeOf(ctx)) ?? ctx.user.id ?? ctx.user._id;
+		if (!userId) return deny("User identity missing (no id or _id)");
+		return allow({ policy: { [ownerField]: userId } });
 	};
 }
 /**
 * Combine multiple checks — ALL must pass (AND logic).
 *
-* Each child runs against the **accumulated** state of previous children:
-*   - `filters` from earlier children merge into the next child's `_policyFilters`
-*   - `scope` from earlier children installs on the request before the next child runs
+* Evaluation is PURE — nothing is written to the request. Each child runs
+* against the accumulated state of previous children, threaded through a fresh
+* child context:
+*   - `policy` from earlier children is CONJOINED (logical AND) — a later child
+*     can add or narrow restrictions but never silently replaces an earlier
+*     child's constraint on the same key (conflicting values are preserved under
+*     `$and`; see `conjoinPolicyFilters`)
+*   - `scope` installed by an earlier child is visible to the next through
+*     `scopeOf(ctx)`, and never downgrades an already-authoritative scope
 *
-* The final result carries both merged `filters` and merged `scope`.
+* The returned decision carries the merged `policy` + `scope`; the enforcement
+* point (`applyAuthorizationDecision`) applies them to the request once.
 *
 * @example
 * ```typescript
@@ -163,50 +236,46 @@ function requireOwnership(ownerField = "userId", options) {
 * ```
 */
 function allOf(...checks) {
-	return async (ctx) => {
+	const check = async (ctx) => {
 		let mergedFilters = {};
 		let installedScope;
-		const sink = ctx.request;
-		const originalFilters = sink._policyFilters;
-		const originalScope = sink.scope;
-		try {
-			for (const check of checks) {
-				const result = await check(ctx);
-				const normalized = typeof result === "boolean" ? { granted: result } : result;
-				if (!normalized.granted) {
-					sink._policyFilters = originalFilters;
-					sink.scope = originalScope;
-					return normalized;
-				}
-				if (normalized.filters) {
-					mergedFilters = {
-						...mergedFilters,
-						...normalized.filters
-					};
-					sink._policyFilters = {
-						...sink._policyFilters ?? {},
-						...normalized.filters
-					};
-				}
-				if (normalized.scope) {
-					const current = sink.scope;
-					if (!current || current.kind === "public") {
-						sink.scope = normalized.scope;
-						installedScope = normalized.scope;
-					} else if (!installedScope) installedScope = normalized.scope;
-				}
-			}
-		} catch (err) {
-			sink._policyFilters = originalFilters;
-			sink.scope = originalScope;
-			throw err;
+		let threaded = ctx.scope;
+		let childCtx = ctx;
+		for (const inner of checks) {
+			const decision = normalizeToDecision(await inner(childCtx));
+			if (decision.effect !== "allow") return deny(decision.reason);
+			if (decision.policy) mergedFilters = conjoinPolicyFilters(mergedFilters, decision.policy);
+			if (decision.scope && (!threaded || threaded.kind === "public")) {
+				threaded = decision.scope;
+				installedScope = decision.scope;
+			} else if (decision.scope && !installedScope) installedScope = decision.scope;
+			if (threaded !== childCtx.scope) childCtx = {
+				...childCtx,
+				scope: threaded
+			};
 		}
-		return {
-			granted: true,
-			filters: Object.keys(mergedFilters).length > 0 ? mergedFilters : void 0,
-			scope: installedScope
-		};
+		return allow({
+			...Object.keys(mergedFilters).length > 0 ? { policy: mergedFilters } : {},
+			...installedScope ? { scope: installedScope } : {}
+		});
 	};
+	const roleBranches = checks.filter((c) => (c._roles?.length ?? 0) > 0 || (c._orgRoles?.length ?? 0) > 0);
+	if (checks.length > 0 && checks.every((c) => c._isPublic)) check._isPublic = true;
+	else if (roleBranches.length === 1) {
+		const [rb] = roleBranches;
+		if (rb?._roles?.length) check._roles = [...rb._roles];
+		if (rb?._orgRoles?.length) check._orgRoles = [...rb._orgRoles];
+	}
+	const scopeContext = {};
+	let scopeConflict = false;
+	for (const c of checks) for (const [dim, val] of Object.entries(c._scopeContext ?? {})) if (dim in scopeContext && scopeContext[dim] !== val) scopeConflict = true;
+	else scopeContext[dim] = val;
+	if (Object.keys(scopeContext).length > 0) check._scopeContext = scopeContext;
+	const hasMetaSurface = (c) => Boolean(c._isPublic || c._roles?.length || c._orgRoles?.length || c._scopeContext && Object.keys(c._scopeContext).length > 0);
+	const opaqueBranch = checks.some((c) => !hasMetaSurface(c) && !c._requiresAuth);
+	const childConditional = checks.some((c) => c._conditional);
+	if (opaqueBranch || scopeConflict || childConditional) check._conditional = true;
+	return check;
 }
 /**
 * Combine multiple checks — ANY must pass (OR logic).
@@ -219,19 +288,31 @@ function allOf(...checks) {
 * ```
 */
 function anyOf(...checks) {
-	return async (ctx) => {
+	const check = async (ctx) => {
 		const reasons = [];
-		for (const check of checks) {
-			const result = await check(ctx);
-			const normalized = typeof result === "boolean" ? { granted: result } : result;
-			if (normalized.granted) return normalized;
-			if (normalized.reason) reasons.push(normalized.reason);
+		for (const inner of checks) {
+			const decision = normalizeToDecision(await inner(ctx));
+			if (decision.effect === "allow") return allow({
+				...decision.policy ? { policy: decision.policy } : {},
+				...decision.scope ? { scope: decision.scope } : {}
+			});
+			if (decision.reason) reasons.push(decision.reason);
 		}
-		return {
-			granted: false,
-			reason: reasons.join("; ")
-		};
+		return deny(reasons.join("; "));
 	};
+	if (checks.some((c) => c._isPublic)) check._isPublic = true;
+	else if (checks.every((c) => (c._roles?.length ?? 0) > 0 || (c._orgRoles?.length ?? 0) > 0)) {
+		const roles = /* @__PURE__ */ new Set();
+		const orgRoles = /* @__PURE__ */ new Set();
+		for (const c of checks) {
+			for (const r of c._roles ?? []) roles.add(r);
+			for (const r of c._orgRoles ?? []) orgRoles.add(r);
+		}
+		if (roles.size > 0) check._roles = [...roles];
+		if (orgRoles.size > 0) check._orgRoles = [...orgRoles];
+		if (checks.some((c) => c._conditional)) check._conditional = true;
+	}
+	return check;
 }
 /**
 * Invert a permission check. Grants when the wrapped check denies, denies
@@ -251,11 +332,7 @@ function anyOf(...checks) {
 */
 function not(check, reason = "Access denied") {
 	return async (ctx) => {
-		const result = await check(ctx);
-		return (typeof result === "boolean" ? { granted: result } : result).granted ? {
-			granted: false,
-			reason
-		} : true;
+		return normalizeToDecision(await check(ctx)).effect === "allow" ? deny(reason) : true;
 	};
 }
 /**
@@ -267,10 +344,7 @@ function not(check, reason = "Access denied") {
 * ```
 */
 function denyAll(reason = "Access denied") {
-	return () => ({
-		granted: false,
-		reason
-	});
+	return () => deny(reason);
 }
 /**
 * Dynamic permission based on a condition function.
@@ -284,11 +358,7 @@ function denyAll(reason = "Access denied") {
 */
 function when(condition) {
 	return async (ctx) => {
-		const result = await condition(ctx);
-		return {
-			granted: result,
-			reason: result ? void 0 : "Condition not met"
-		};
+		return await condition(ctx) ? allow() : deny("Condition not met");
 	};
 }
 //#endregion
@@ -349,16 +419,10 @@ const DEFAULT_TTL_GRACE_MS = 3e4;
 */
 function requireDPoP() {
 	const check = (ctx) => {
-		const scope = getRequestScope(ctx.request);
+		const scope = scopeOf(ctx);
 		if (isElevated(scope)) return true;
-		if (!isService(scope)) return {
-			granted: false,
-			reason: "DPoP-bound service identity required. Configure your authenticate callback to set scope.dpopJkt after verifying the DPoP proof header (RFC 9449)."
-		};
-		if (!getDPoPJkt(scope)) return {
-			granted: false,
-			reason: "Sender-constrained credential required (DPoP). Inbound token is bearer; replay-resistance is mandatory on this endpoint."
-		};
+		if (!isService(scope)) return deny("DPoP-bound service identity required. Configure your authenticate callback to set scope.dpopJkt after verifying the DPoP proof header (RFC 9449).");
+		if (!getDPoPJkt(scope)) return deny("Sender-constrained credential required (DPoP). Inbound token is bearer; replay-resistance is mandatory on this endpoint.");
 		return true;
 	};
 	check._dpopRequired = true;
@@ -404,38 +468,20 @@ function requireMandate(capability, opts = {}) {
 	const ttlGrace = opts.ttlGraceMs ?? DEFAULT_TTL_GRACE_MS;
 	const noElevatedBypass = opts.noElevatedBypass === true;
 	const check = (ctx) => {
-		const scope = getRequestScope(ctx.request);
+		const scope = scopeOf(ctx);
 		if (isElevated(scope) && !noElevatedBypass) return true;
 		const mandate = getMandate(scope);
-		if (!mandate) return {
-			granted: false,
-			reason: `Capability mandate required (${capability}). Configure your authenticate callback to populate request.scope.mandate after verifying the mandate JWT/VC.`
-		};
-		if (mandate.capability !== capability) return {
-			granted: false,
-			reason: `Mandate authorizes "${mandate.capability}", not "${capability}"`
-		};
-		if (mandate.expiresAt !== void 0 && Date.now() > mandate.expiresAt + ttlGrace) return {
-			granted: false,
-			reason: `Mandate expired at ${new Date(mandate.expiresAt).toISOString()}`
-		};
+		if (!mandate) return deny(`Capability mandate required (${capability}). Configure your authenticate callback to populate request.scope.mandate after verifying the mandate JWT/VC.`);
+		if (mandate.capability !== capability) return deny(`Mandate authorizes "${mandate.capability}", not "${capability}"`);
+		if (mandate.expiresAt !== void 0 && Date.now() > mandate.expiresAt + ttlGrace) return deny(`Mandate expired at ${new Date(mandate.expiresAt).toISOString()}`);
 		if (opts.audience) {
 			const required = typeof opts.audience === "function" ? opts.audience(ctx) : opts.audience;
-			if (required && mandate.audience && mandate.audience !== required) return {
-				granted: false,
-				reason: `Mandate is bound to "${mandate.audience}", not "${required}"`
-			};
-			if (required && !mandate.audience) return {
-				granted: false,
-				reason: `Mandate must be bound to "${required}" (no audience claim)`
-			};
+			if (required && mandate.audience && mandate.audience !== required) return deny(`Mandate is bound to "${mandate.audience}", not "${required}"`);
+			if (required && !mandate.audience) return deny(`Mandate must be bound to "${required}" (no audience claim)`);
 		}
 		if (opts.validateAmount) {
 			const result = opts.validateAmount(ctx, mandate);
-			if (result !== true) return {
-				granted: false,
-				reason: typeof result === "string" ? result : `Action exceeds mandate cap ${mandate.cap}${mandate.currency ? ` ${mandate.currency}` : ""}`
-			};
+			if (result !== true) return deny(typeof result === "string" ? result : `Action exceeds mandate cap ${mandate.cap}${mandate.currency ? ` ${mandate.currency}` : ""}`);
 		}
 		return true;
 	};
@@ -482,30 +528,18 @@ function requireAgentScope(opts) {
 	const dpopCheck = needsDPoP ? requireDPoP() : null;
 	const requiredScopes = scopes && scopes.length > 0 ? [...scopes] : null;
 	const check = async (ctx) => {
-		const scope = getRequestScope(ctx.request);
+		const scope = scopeOf(ctx);
 		if (isElevated(scope) && !mandateOpts.noElevatedBypass) return true;
-		if (!isService(scope)) return {
-			granted: false,
-			reason: "Service identity required (machine principal). Agent flows must authenticate as a service, not a logged-in user."
-		};
+		if (!isService(scope)) return deny("Service identity required (machine principal). Agent flows must authenticate as a service, not a logged-in user.");
 		if (requiredScopes) {
 			const granted = scope.scopes ?? [];
-			if (!requiredScopes.some((s) => granted.includes(s))) return {
-				granted: false,
-				reason: `Service identity is missing required OAuth scope(s): ${requiredScopes.join(", ")}`
-			};
+			if (!requiredScopes.some((s) => granted.includes(s))) return deny(`Service identity is missing required OAuth scope(s): ${requiredScopes.join(", ")}`);
 		}
 		const mandateResult = await mandateCheck(ctx);
-		if (mandateResult !== true) return typeof mandateResult === "object" ? mandateResult : {
-			granted: false,
-			reason: "Mandate check failed"
-		};
+		if (mandateResult !== true) return typeof mandateResult === "object" ? mandateResult : deny("Mandate check failed");
 		if (dpopCheck) {
 			const dpopResult = await dpopCheck(ctx);
-			if (dpopResult !== true) return typeof dpopResult === "object" ? dpopResult : {
-				granted: false,
-				reason: "DPoP binding required"
-			};
+			if (dpopResult !== true) return typeof dpopResult === "object" ? dpopResult : deny("DPoP binding required");
 		}
 		return true;
 	};
@@ -521,9 +555,9 @@ function requireAgentScope(opts) {
 /**
 * Permission Scope — checks bound to RequestScope.
 *
-* All read `request.scope` populated by an auth adapter (Better Auth bridge,
-* JWT custom auth, or an upstream permission check returning
-* `PermissionResult.scope`).
+* All read the request scope via `scopeOf(ctx)` - populated by an auth adapter
+* (Better Auth bridge, JWT custom auth) or threaded from an upstream check's
+* `AuthorizationDecision.scope`.
 */
 /**
 * Require an org-bound caller. Grants for `member`, `service`, and
@@ -544,15 +578,9 @@ function requireAgentScope(opts) {
 */
 function requireOrgMembership() {
 	const check = (ctx) => {
-		if (hasOrgAccess(getRequestScope(ctx.request))) return true;
-		if (!ctx.user) return {
-			granted: false,
-			reason: "Authentication required"
-		};
-		return {
-			granted: false,
-			reason: "Organization membership required"
-		};
+		if (hasOrgAccess(scopeOf(ctx))) return true;
+		if (!ctx.user) return deny("Authentication required");
+		return deny("Organization membership required");
 	};
 	check._orgPermission = "membership";
 	return check;
@@ -579,25 +607,13 @@ function requireOrgMembership() {
 function requireOrgRole(...args) {
 	const roles = normalizeVariadicOrArray(args);
 	const check = (ctx) => {
-		const scope = getRequestScope(ctx.request);
+		const scope = scopeOf(ctx);
 		if (isElevated(scope)) return true;
-		if (isService(scope)) return {
-			granted: false,
-			reason: "Service scopes (API keys) cannot satisfy requireOrgRole. Use requireServiceScope(...) for machine identities, or compose with anyOf(requireOrgRole(...), requireServiceScope(...)) to accept both."
-		};
-		if (!ctx.user) return {
-			granted: false,
-			reason: "Authentication required"
-		};
-		if (!isMember(scope)) return {
-			granted: false,
-			reason: "Organization membership required"
-		};
+		if (isService(scope)) return deny("Service scopes (API keys) cannot satisfy requireOrgRole. Use requireServiceScope(...) for machine identities, or compose with anyOf(requireOrgRole(...), requireServiceScope(...)) to accept both.");
+		if (!ctx.user) return deny("Authentication required");
+		if (!isMember(scope)) return deny("Organization membership required");
 		if (roles.some((r) => scope.orgRoles.includes(r))) return true;
-		return {
-			granted: false,
-			reason: `Required org roles: ${roles.join(", ")}`
-		};
+		return deny(`Required org roles: ${roles.join(", ")}`);
 	};
 	check._orgRoles = roles;
 	return check;
@@ -629,18 +645,12 @@ function requireServiceScope(...args) {
 	const required = normalizeVariadicOrArray(args);
 	if (required.length === 0) throw new Error("requireServiceScope() requires at least one scope string (e.g. requireServiceScope('jobs:write'))");
 	const check = (ctx) => {
-		const scope = getRequestScope(ctx.request);
+		const scope = scopeOf(ctx);
 		if (isElevated(scope)) return true;
-		if (!isService(scope)) return {
-			granted: false,
-			reason: "Service identity required (API key). For human users, use requireOrgRole(...) or compose with anyOf(requireOrgRole(...), requireServiceScope(...))."
-		};
+		if (!isService(scope)) return deny("Service identity required (API key). For human users, use requireOrgRole(...) or compose with anyOf(requireOrgRole(...), requireServiceScope(...)).");
 		const granted = getServiceScopes(scope);
 		if (required.some((r) => granted.includes(r))) return true;
-		return {
-			granted: false,
-			reason: `Required service scopes: ${required.join(", ")} (granted: ${granted.length > 0 ? granted.join(", ") : "none"})`
-		};
+		return deny(`Required service scopes: ${required.join(", ")} (granted: ${granted.length > 0 ? granted.join(", ") : "none"})`);
 	};
 	check._serviceScopes = required;
 	return check;
@@ -678,23 +688,14 @@ function requireScopeContext(keyOrMap, value) {
 	const requiredKeys = Object.keys(required);
 	if (requiredKeys.length === 0) throw new Error("requireScopeContext() requires at least one key (e.g. requireScopeContext('branchId'))");
 	const check = (ctx) => {
-		const scope = getRequestScope(ctx.request);
+		const scope = scopeOf(ctx);
 		if (isElevated(scope)) return true;
-		if (!getScopeContextMap(scope)) return {
-			granted: false,
-			reason: "Scope context required (member, service, or elevated scope). Populate request.scope.context in your auth function."
-		};
+		if (!getScopeContextMap(scope)) return deny("Scope context required (member, service, or elevated scope). Populate request.scope.context in your auth function.");
 		for (const key of requiredKeys) {
 			const expected = required[key];
 			const actual = getScopeContext(scope, key);
-			if (actual === void 0) return {
-				granted: false,
-				reason: `Required scope context key "${key}" is missing`
-			};
-			if (expected !== void 0 && actual !== expected) return {
-				granted: false,
-				reason: `Required scope context "${key}" must equal "${expected}" (got "${actual}")`
-			};
+			if (actual === void 0) return deny(`Required scope context key "${key}" is missing`);
+			if (expected !== void 0 && actual !== expected) return deny(`Required scope context "${key}" must equal "${expected}" (got "${actual}")`);
 		}
 		return true;
 	};
@@ -711,8 +712,8 @@ function requireScopeContext(keyOrMap, value) {
 *
 * **Two call shapes:**
 * ```typescript
-* requireOrgInScope('acme-holding')                          // static
-* requireOrgInScope((ctx) => ctx.request.params.orgId)       // dynamic
+* requireOrgInScope('acme-holding')                    // static
+* requireOrgInScope((ctx) => ctx.params?.orgId)        // dynamic — from ctx facts, not the raw request
 * ```
 *
 * `elevated` scope grants unconditionally (cross-org bypass).
@@ -720,9 +721,9 @@ function requireScopeContext(keyOrMap, value) {
 * @example
 * ```typescript
 * permissions: {
-*   list: requireOrgInScope((ctx) => ctx.request.params.orgId),
+*   list: requireOrgInScope((ctx) => ctx.params?.orgId),
 *   create: allOf(
-*     requireOrgInScope((ctx) => ctx.request.body?.organizationId),
+*     requireOrgInScope((ctx) => (ctx.data as { organizationId?: string })?.organizationId),
 *     requireOrgRole('admin'),
 *   ),
 * }
@@ -731,18 +732,12 @@ function requireScopeContext(keyOrMap, value) {
 function requireOrgInScope(target) {
 	if (target === void 0 || target === null) throw new Error("requireOrgInScope() requires a target org id (string) or an extractor function");
 	const check = (ctx) => {
-		const scope = getRequestScope(ctx.request);
+		const scope = scopeOf(ctx);
 		if (isElevated(scope)) return true;
 		const targetOrgId = typeof target === "function" ? target(ctx) : target;
-		if (!targetOrgId) return {
-			granted: false,
-			reason: "requireOrgInScope: target org id could not be resolved from the request"
-		};
+		if (!targetOrgId) return deny("requireOrgInScope: target org id could not be resolved from the request");
 		if (isOrgInScope(scope, targetOrgId)) return true;
-		return {
-			granted: false,
-			reason: `Target organization "${targetOrgId}" is not in the caller's org hierarchy`
-		};
+		return deny(`Target organization "${targetOrgId}" is not in the caller's org hierarchy`);
 	};
 	check._orgInScopeTarget = target;
 	return check;
@@ -762,20 +757,11 @@ function requireOrgInScope(target) {
 */
 function requireTeamMembership() {
 	const check = (ctx) => {
-		if (!ctx.user) return {
-			granted: false,
-			reason: "Authentication required"
-		};
-		const scope = getRequestScope(ctx.request);
+		if (!ctx.user) return deny("Authentication required");
+		const scope = scopeOf(ctx);
 		if (isElevated(scope)) return true;
-		if (!isMember(scope)) return {
-			granted: false,
-			reason: "Organization membership required"
-		};
-		if (!getTeamId(scope)) return {
-			granted: false,
-			reason: "No active team"
-		};
+		if (!isMember(scope)) return deny("Organization membership required");
+		if (!getTeamId(scope)) return deny("No active team");
 		return true;
 	};
 	check._teamPermission = "membership";
@@ -832,21 +818,12 @@ function createOrgPermissions(config) {
 	return {
 		can(permissions) {
 			return (ctx) => {
-				if (!ctx.user) return {
-					granted: false,
-					reason: "Authentication required"
-				};
-				const scope = getRequestScope(ctx.request);
+				if (!ctx.user) return deny("Authentication required");
+				const scope = scopeOf(ctx);
 				if (isElevated(scope)) return true;
-				if (!isMember(scope)) return {
-					granted: false,
-					reason: "Organization membership required"
-				};
+				if (!isMember(scope)) return deny("Organization membership required");
 				if (hasPermissions(scope.orgRoles, permissions)) return true;
-				return {
-					granted: false,
-					reason: `Missing permissions: ${Object.entries(permissions).map(([r, a]) => `${r}:[${a.join(",")}]`).join(", ")}`
-				};
+				return deny(`Missing permissions: ${Object.entries(permissions).map(([r, a]) => `${r}:[${a.join(",")}]`).join(", ")}`);
 			};
 		},
 		requireRole(...roles) {
@@ -873,7 +850,7 @@ function createOrgPermissions(config) {
 * - Cross-node invalidation via the event bus
 */
 function createDynamicPermissionMatrix(config) {
-	const logger = config.logger ?? console;
+	const logger = config.logger ?? arcLog("permissions:dynamic");
 	const configuredTtlSeconds = config.cache?.ttlSeconds ?? 0;
 	const hasExternalStore = !!config.cacheStore;
 	const cacheTtlSeconds = configuredTtlSeconds > 0 ? configuredTtlSeconds : hasExternalStore ? 300 : 0;
@@ -883,20 +860,66 @@ function createDynamicPermissionMatrix(config) {
 	}) : void 0;
 	const cacheStore = config.cacheStore ?? internalStore;
 	const trackedKeys = /* @__PURE__ */ new Set();
+	const orgKeyIndex = /* @__PURE__ */ new Map();
+	const maxTrackedKeys = config.cache?.maxEntries ?? 1e4;
+	/**
+	* Record a key and ENFORCE the cap in the same step.
+	*
+	* The cap has to live here rather than at the write site: a node that mostly
+	* READS a shared cache registers on every hit but may rarely set, so a
+	* cap applied only after a `set` never runs and the bookkeeping grows with
+	* every distinct org/user/role combination the node has ever seen — unbounded,
+	* and outliving the cache entries themselves, which the external store expires
+	* on its own schedule. Eviction is insertion-ordered (`Set` iteration order),
+	* so the oldest bookkeeping goes first; dropping a key only costs a missed
+	* local invalidation for an entry that will still expire by TTL.
+	*/
+	const registerKey = (orgId, key) => {
+		trackedKeys.add(key);
+		const bucket = orgId ?? "no-org";
+		let keys = orgKeyIndex.get(bucket);
+		if (!keys) {
+			keys = /* @__PURE__ */ new Set();
+			orgKeyIndex.set(bucket, keys);
+		}
+		keys.add(key);
+		if (trackedKeys.size > maxTrackedKeys) {
+			const overflow = trackedKeys.size - maxTrackedKeys;
+			const iter = trackedKeys.values();
+			for (let i = 0; i < overflow; i++) {
+				const oldest = iter.next().value;
+				if (oldest) forgetKey(oldest);
+			}
+		}
+	};
+	const forgetKey = (key) => {
+		trackedKeys.delete(key);
+		for (const [bucket, keys] of orgKeyIndex) if (keys.delete(key) && keys.size === 0) orgKeyIndex.delete(bucket);
+	};
 	const nodeId = randomUUID().slice(0, 8);
 	const DEFAULT_EVENT_TYPE = "arc.permissions.invalidated";
 	let eventBridge = null;
 	async function localInvalidateByOrg(orgId) {
 		if (!cacheStore) return;
 		const prefix = `${orgId}::`;
-		const toDelete = [];
-		for (const key of trackedKeys) if (key.startsWith(prefix)) toDelete.push(key);
+		if (cacheStore.clear) try {
+			await cacheStore.clear(`${prefix}*`);
+			const keys = orgKeyIndex.get(orgId);
+			if (keys) for (const k of keys) trackedKeys.delete(k);
+			orgKeyIndex.delete(orgId);
+			return;
+		} catch (error) {
+			logger.warn(`[DynamicPermissionMatrix] invalidateByOrg clear('${prefix}*') failed — falling back to per-key delete: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		const toDelete = new Set(orgKeyIndex.get(orgId) ?? []);
+		for (const key of trackedKeys) if (key.startsWith(prefix)) toDelete.add(key);
 		for (const key of toDelete) try {
 			await cacheStore.delete(key);
-			trackedKeys.delete(key);
+			forgetKey(key);
 		} catch (error) {
 			logger.warn(`[DynamicPermissionMatrix] invalidateByOrg delete failed for '${key}': ${error instanceof Error ? error.message : String(error)}`);
 		}
+		orgKeyIndex.delete(orgId);
 	}
 	function isActionAllowed(actions, action) {
 		if (!actions || actions.length === 0) return false;
@@ -916,27 +939,22 @@ function createDynamicPermissionMatrix(config) {
 	}
 	async function resolveMatrix(ctx, orgId, orgRoles) {
 		if (!cacheStore) return config.resolveRolePermissions(ctx);
-		const cacheKey = config.cache?.key?.(ctx) ?? buildDefaultCacheKey(ctx, orgId, orgRoles);
+		const customKey = config.cache?.key?.(ctx);
+		const cacheKey = customKey ? `${orgId ?? "no-org"}::${(orgRoles ?? []).slice().sort().join(",")}::${customKey}` : buildDefaultCacheKey(ctx, orgId, orgRoles);
 		if (!cacheKey) return config.resolveRolePermissions(ctx);
 		try {
 			const hit = await cacheStore.get(cacheKey);
-			if (hit) return hit;
+			if (hit) {
+				registerKey(orgId, cacheKey);
+				return hit;
+			}
 		} catch (error) {
 			logger.warn(`[DynamicPermissionMatrix] Cache get failed for '${cacheKey}': ${error instanceof Error ? error.message : String(error)}`);
 		}
 		const value = await config.resolveRolePermissions(ctx);
 		try {
 			await cacheStore.set(cacheKey, value, cacheTtlSeconds);
-			trackedKeys.add(cacheKey);
-			const maxTracked = config.cache?.maxEntries ?? 1e4;
-			if (trackedKeys.size > maxTracked) {
-				const overflow = trackedKeys.size - maxTracked;
-				const iter = trackedKeys.values();
-				for (let i = 0; i < overflow; i++) {
-					const oldest = iter.next().value;
-					if (oldest) trackedKeys.delete(oldest);
-				}
-			}
+			registerKey(orgId, cacheKey);
 		} catch (error) {
 			logger.warn(`[DynamicPermissionMatrix] Cache set failed for '${cacheKey}': ${error instanceof Error ? error.message : String(error)}`);
 		}
@@ -944,34 +962,20 @@ function createDynamicPermissionMatrix(config) {
 	}
 	function can(required) {
 		return async (ctx) => {
-			if (!ctx.user) return {
-				granted: false,
-				reason: "Authentication required"
-			};
-			const scope = getRequestScope(ctx.request);
+			if (!ctx.user) return deny("Authentication required");
+			const scope = scopeOf(ctx);
 			if (isElevated(scope)) return true;
-			if (!isMember(scope)) return {
-				granted: false,
-				reason: "Organization membership required"
-			};
+			if (!isMember(scope)) return deny("Organization membership required");
 			const orgRoles = scope.orgRoles;
-			if (orgRoles.length === 0) return {
-				granted: false,
-				reason: "Not a member of this organization"
-			};
+			if (orgRoles.length === 0) return deny("Not a member of this organization");
 			let matrix;
 			try {
 				matrix = await resolveMatrix(ctx, scope.organizationId, orgRoles);
 			} catch (error) {
-				return {
-					granted: false,
-					reason: `Permission matrix resolution failed: ${error instanceof Error ? error.message : String(error)}`
-				};
+				logger.warn(`[DynamicPermissionMatrix] matrix resolution failed for org '${scope.organizationId ?? "?"}': ${error instanceof Error ? error.message : String(error)}`);
+				return deny("Permission policy is temporarily unavailable");
 			}
-			for (const [resource, actions] of Object.entries(required)) for (const action of actions) if (!orgRoles.some((role) => roleAllows(matrix, role, resource, action))) return {
-				granted: false,
-				reason: `Missing permission: ${resource}:${action}`
-			};
+			for (const [resource, actions] of Object.entries(required)) for (const action of actions) if (!orgRoles.some((role) => roleAllows(matrix, role, resource, action))) return deny(`Missing permission: ${resource}:${action}`);
 			return true;
 		};
 	}
@@ -1005,6 +1009,7 @@ function createDynamicPermissionMatrix(config) {
 			if (cacheStore.clear) try {
 				await cacheStore.clear();
 				trackedKeys.clear();
+				orgKeyIndex.clear();
 				return;
 			} catch (error) {
 				logger.warn(`[DynamicPermissionMatrix] cacheStore.clear failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -1015,6 +1020,7 @@ function createDynamicPermissionMatrix(config) {
 				logger.warn(`[DynamicPermissionMatrix] Cache delete failed for '${key}': ${error instanceof Error ? error.message : String(error)}`);
 			}
 			trackedKeys.clear();
+			orgKeyIndex.clear();
 		},
 		async connectEvents(events, options) {
 			if (eventBridge) await this.disconnectEvents();
@@ -1052,8 +1058,187 @@ function createDynamicPermissionMatrix(config) {
 	};
 }
 //#endregion
+//#region src/permissions/explain.ts
+/**
+* Extract a check's static requirement from its `PermissionCheckMeta`. Public
+* wins; then a scope-context gate (optionally with roles); then the union of
+* platform + org roles a role gate declares; otherwise "authenticated"
+* (auth-required / custom / request-time checks). An `allOf` that couldn't be
+* fully captured statically carries `conditional: true` (see `_conditional`).
+*/
+function describePermission(check) {
+	if (check._isPublic) return { kind: "public" };
+	const roles = [...check._roles ?? [], ...check._orgRoles ?? []];
+	const scope = check._scopeContext;
+	const conditional = check._conditional ? true : void 0;
+	if (scope && Object.keys(scope).length > 0) return roles.length > 0 ? {
+		kind: "scoped",
+		scope,
+		roles,
+		conditional
+	} : {
+		kind: "scoped",
+		scope,
+		conditional
+	};
+	if (roles.length > 0) return {
+		kind: "roles",
+		roles,
+		conditional
+	};
+	return { kind: "authenticated" };
+}
+/**
+* Explain whether a principal (by roles) passes a permission check, from static
+* metadata alone — for permission-matrix UIs, docs, and audits. Omit `principal`
+* to get the requirement-only view (roles → `conditional`).
+*
+* @example
+* explainAccess(requireRoles("admin"), { roles: ["editor"] })
+* // → { decision: "deny", reason: "requires one of: admin", requirement: { kind: "roles", roles: ["admin"] } }
+*/
+function explainAccess(check, principal) {
+	const requirement = describePermission(check);
+	if (requirement.kind === "public") return {
+		decision: "allow",
+		reason: "public — no authentication required",
+		requirement
+	};
+	if (requirement.kind === "authenticated") return {
+		decision: "conditional",
+		reason: "requires authentication; decided per request",
+		requirement
+	};
+	const held = /* @__PURE__ */ new Set([...principal?.roles ?? [], ...principal?.orgRoles ?? []]);
+	if (requirement.kind === "scoped") {
+		const scopeReason = describeScope(requirement.scope);
+		const rolesReason = requirement.roles?.length ? `role(s) ${requirement.roles.join(", ")} + ` : "";
+		if (requirement.roles?.length && principal && !requirement.roles.some((r) => held.has(r))) return {
+			decision: "deny",
+			reason: `requires ${rolesReason}${scopeReason}`,
+			requirement
+		};
+		if (!principal?.scope) return {
+			decision: "conditional",
+			reason: `requires ${rolesReason}${scopeReason}`,
+			requirement
+		};
+		if (!Object.entries(requirement.scope).every(([dim, val]) => val === void 0 ? principal.scope?.[dim] !== void 0 : principal.scope?.[dim] === val)) return {
+			decision: "deny",
+			reason: `requires ${rolesReason}${scopeReason}`,
+			requirement
+		};
+		if (requirement.conditional) return {
+			decision: "conditional",
+			reason: `in scope ${scopeReason}; additional runtime conditions apply`,
+			requirement
+		};
+		return {
+			decision: "allow",
+			reason: `granted in scope: ${scopeReason}`,
+			requirement
+		};
+	}
+	const rolesText = `requires one of: ${requirement.roles.join(", ")}`;
+	if (!principal) return {
+		decision: "conditional",
+		reason: rolesText,
+		requirement
+	};
+	const matched = requirement.roles.filter((r) => held.has(r));
+	if (matched.length === 0) return {
+		decision: "deny",
+		reason: rolesText,
+		requirement
+	};
+	if (requirement.conditional) return {
+		decision: "conditional",
+		reason: `has role(s) ${matched.join(", ")}; additional runtime conditions apply`,
+		requirement
+	};
+	return {
+		decision: "allow",
+		reason: `granted via role(s): ${matched.join(", ")}`,
+		requirement
+	};
+}
+/** Render a scope-context requirement as a readable clause: `branchRole=head_office`. */
+function describeScope(scope) {
+	return Object.entries(scope).map(([dim, val]) => val === void 0 ? `${dim} (any)` : `${dim}=${val}`).join(", ");
+}
+/**
+* Introspect a whole permission map (`{ list, get, create, ... }` or any
+* action→check record) into `action → requirement`. The reusable core of a
+* `/permissions/matrix` endpoint or an access audit — framework-owned, so a host
+* never hand-rolls `(check as any)._roles` peeking. Undefined slots (a CRUD op
+* with no gate = public-by-omission) surface as `public` so the inventory is
+* honest about what's exposed.
+*/
+function describePermissionMap(permissions) {
+	const out = {};
+	for (const [action, check] of Object.entries(permissions)) out[action] = check ? describePermission(check) : { kind: "public" };
+	return out;
+}
+/**
+* The public attack surface of a permission map — the actions reachable with NO
+* authentication (explicit `allowPublic()` or public-by-omission). Empty is the
+* healthy default for a protected resource; a non-empty list is what a
+* "what's exposed?" audit report should show.
+*/
+function collectPublicSurface(permissions) {
+	return Object.entries(describePermissionMap(permissions)).filter(([, req]) => req.kind === "public").map(([action]) => action);
+}
+//#endregion
 //#region src/permissions/grants.ts
 /**
+* Per-record grants — the `requireGrant` combinator + mode lattice.
+*
+* The one ACL idea arc's permission vocabulary lacked (design verdict:
+* `designs/record-sharing.md`): subject × record × mode grants, Puter-style,
+* WITHOUT Puter's mistakes. Arc ships only the GATE — grant storage is a
+* host `defineResource` (tenant-scoped, `audit: true`, any kit via
+* repo-core's `RepositoryLike`), and the `resolve` callback is structural,
+* so core stays DB-agnostic and storage-free by construction.
+*
+* What this design deliberately avoids (verified against Puter's source):
+*   - string-typed permissions (`fs:<uuid>:read` VARCHARs that silently
+*     never match when malformed) → typed {@link GrantMode} union
+*   - per-item ACL checks on list responses (their readdir returns
+*     unfiltered children; the UI stats each item — N+1) → resolutions
+*     return a row `policy` that composes into THE list query via the
+*     decision's `policy` → `_policyFilters` (one paginated, correct query)
+*   - un-revocable capability tokens → share links should reference a
+*     grant ROW (`subjectType: 'link'`); delete the row, the link dies
+*
+* @example
+* ```ts
+* // Host owns the grants table — it's just a resource:
+* //   { resource, resourceId, subjectType: 'user'|'team'|'link',
+* //     subjectId, mode, grantedBy, expiresAt? }
+* import { anyOf, requireGrant, requireOwnership } from '@classytic/arc/permissions';
+*
+* defineResource({
+*   name: 'document',
+*   permissions: {
+*     get:    anyOf(requireOwnership('ownerId'), requireGrant({ mode: 'read',  resolve })),
+*     update: anyOf(requireOwnership('ownerId'), requireGrant({ mode: 'write', resolve })),
+*     list:   requireGrant({
+*       mode: 'list',
+*       // List-shaped resolution: return filters — owner OR granted ids.
+*       resolve: async (ctx) => ({
+*         filters: {
+*           $or: [
+*             { ownerId: ctx.user?.id },
+*             { _id: { $in: await grants.grantedIds(ctx) } },
+*           ],
+*         },
+*       }),
+*     }),
+*   },
+* });
+* ```
+*/
+/**
 * The grant-mode lattice, weakest → strongest. Holding a mode satisfies
 * every mode at or below it (`write` ⊇ `read` ⊇ `list` ⊇ `see`); `manage`
 * (grant/revoke rights) satisfies everything. Same semantics as Puter's
@@ -1095,36 +1280,21 @@ function requireGrant(options) {
 		try {
 			resolution = await resolve(ctx);
 		} catch (err) {
-			ctx.request.log?.warn?.({
+			ctx.request?.log?.warn?.({
 				err,
 				resource: ctx.resource,
 				action: ctx.action
 			}, "requireGrant: resolve threw — denying (fail-closed)");
-			return {
-				granted: false,
-				reason: "Grant lookup failed"
-			};
+			return deny("Grant lookup failed");
 		}
 		if (typeof resolution === "boolean") return resolution;
 		const { mode: held, filters, reason } = resolution;
 		if (held !== void 0) {
-			if (!modeSatisfies(held, required)) return {
-				granted: false,
-				...reason ? { reason } : {}
-			};
-			return {
-				granted: true,
-				...filters ? { filters } : {}
-			};
+			if (!modeSatisfies(held, required)) return deny(reason);
+			return allow(filters ? { policy: filters } : void 0);
 		}
-		if (filters !== void 0) return {
-			granted: true,
-			filters
-		};
-		return {
-			granted: false,
-			...reason ? { reason } : {}
-		};
+		if (filters !== void 0) return allow({ policy: filters });
+		return deny(reason);
 	};
 }
 //#endregion
@@ -1138,27 +1308,59 @@ function requireGrant(options) {
 */
 function createRoleHierarchy(map) {
 	const cache = /* @__PURE__ */ new Map();
-	function resolveRole(role, visited) {
-		if (visited.has(role)) return [];
-		visited.add(role);
+	/**
+	* Resolve a role's transitive expansion.
+	*
+	* `stack` is the CURRENT recursion path (a DFS stack), NOT a shared visited
+	* accumulator: a role is added on entry and REMOVED on exit, so sibling
+	* branches never pollute each other. Without this, a diamond `A→B→D`, `A→C→D`
+	* would let B's traversal leave `D` in a shared set, making C's `D` look like a
+	* back-edge and caching `C` WITHOUT `D` — a nondeterministic under-grant.
+	*
+	* Returns `cyclic` = whether a back-edge into `stack` was cut anywhere in the
+	* subtree. A cyclic subtree's result depends on the entry path, so it is NOT
+	* cached (recomputed each call — correct, if unmemoized). Acyclic subtrees (the
+	* norm) cache safely.
+	*/
+	function resolveRole(role, stack) {
+		if (stack.has(role)) return {
+			roles: [],
+			cyclic: true
+		};
 		const cached = cache.get(role);
-		if (cached) return cached;
+		if (cached) return {
+			roles: cached,
+			cyclic: false
+		};
 		const children = map[role];
 		if (!children || children.length === 0) {
 			cache.set(role, [role]);
-			return [role];
+			return {
+				roles: [role],
+				cyclic: false
+			};
 		}
+		stack.add(role);
 		const result = [role];
-		for (const child of children) result.push(...resolveRole(child, visited));
+		let cyclic = false;
+		for (const child of children) {
+			const childResult = resolveRole(child, stack);
+			result.push(...childResult.roles);
+			if (childResult.cyclic) cyclic = true;
+		}
+		stack.delete(role);
 		const deduped = [...new Set(result)];
-		cache.set(role, deduped);
-		return deduped;
+		if (!cyclic) cache.set(role, deduped);
+		return {
+			roles: deduped,
+			cyclic
+		};
 	}
 	return {
 		expand(roles) {
 			if (roles.length === 0) return [];
 			const all = /* @__PURE__ */ new Set();
-			for (const role of roles) for (const expanded of resolveRole(role, /* @__PURE__ */ new Set())) all.add(expanded);
+			for (const role of roles) for (const expanded of resolveRole(role, /* @__PURE__ */ new Set()).roles) all.add(expanded);
 			return [...all];
 		},
 		includes(userRoles, requiredRole) {
@@ -1343,4 +1545,4 @@ function readOnly(overrides) {
 	}, overrides);
 }
 //#endregion
-export { requireAuth as A, requireDPoP as C, anyOf as D, allowPublic as E, requireRoles as M, roles as N, denyAll as O, when as P, requireAgentScope as S, allOf as T, requireOrgMembership as _, permissionMatrix as a, requireServiceScope as b, publicReadAdminWrite as c, GRANT_MODES as d, modeSatisfies as f, requireOrgInScope as g, createOrgPermissions as h, ownerWithAdminBypass as i, requireOwnership as j, not as k, readOnly as l, createDynamicPermissionMatrix as m, authenticated as n, presets_exports as o, requireGrant as p, fullPublic as r, publicRead as s, adminOnly as t, createRoleHierarchy as u, requireOrgRole as v, requireMandate as w, requireTeamMembership as x, requireScopeContext as y };
+export { allow as A, roles as B, requireScopeContext as C, requireDPoP as D, requireAgentScope as E, not as F, scopeOf as H, requireAuth as I, requireOwnership as L, anyOf as M, deny as N, requireMandate as O, denyAll as P, requirePlatformRole as R, requireOrgRole as S, requireTeamMembership as T, when as V, explainAccess as _, permissionMatrix as a, requireOrgInScope as b, publicReadAdminWrite as c, GRANT_MODES as d, modeSatisfies as f, describePermissionMap as g, describePermission as h, ownerWithAdminBypass as i, allowPublic as j, allOf as k, readOnly as l, collectPublicSurface as m, authenticated as n, presets_exports as o, requireGrant as p, fullPublic as r, publicRead as s, adminOnly as t, createRoleHierarchy as u, createDynamicPermissionMatrix as v, requireServiceScope as w, requireOrgMembership as x, createOrgPermissions as y, requireRoles as z };