@classytic/arc 2.30.0 → 2.31.0

package/dist/permissions/index.d.mts

@@ -1,4 +1,5 @@
-import { a as UserBase, c as normalizeRoles, i as PermissionContext, n as DataPolicy, r as PermissionCheck, s as getUserRoles, t as AuthorizationDecision } from "../types-ChvvVNP8.mjs";
-import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, n as FieldPermissionMap, o as fields, r as FieldPermissionType, s as resolveEffectiveRoles, t as FieldPermission } from "../fields-D3lhgzhD.mjs";
-import { $ as evaluatePermissionDecision, A as explainAccess, B as anyOf, C as requireGrant, D as collectPublicSurface, E as PermissionRequirement, F as createDynamicPermissionMatrix, G as requireOwnership, H as denyAll, I as createOrgPermissions, J as when, K as requireRoles, L as allOf, M as DynamicPermissionMatrix, N as DynamicPermissionMatrixConfig, O as describePermission, P as PermissionEventBus, Q as applyPermissionResult, R as allow, S as modeSatisfies, T as AccessExplanation, U as not, V as deny, W as requireAuth, X as PermissionCheckReturn, Y as scopeOf, Z as applyAuthorizationDecision, _ as createRoleHierarchy, a as permissionMatrix, at as requireMandate, b as GrantResolution, c as publicReadAdminWrite, d as requireOrgMembership, et as normalizeToDecision, f as requireOrgRole, g as RoleHierarchy, h as requireTeamMembership, i as ownerWithAdminBypass, it as requireDPoP, j as ConnectEventsOptions, k as describePermissionMap, l as readOnly, m as requireServiceScope, n as authenticated, nt as RequireMandateOptions, o as presets_d_exports, p as requireScopeContext, q as roles, r as fullPublic, rt as requireAgentScope, s as publicRead, t as adminOnly, tt as RequireAgentScopeOptions, u as requireOrgInScope, v as GRANT_MODES, w as conjoinPolicyFilters, x as RequireGrantOptions, y as GrantMode, z as allowPublic } from "../index-Ch16aAah.mjs";
-export { type AccessExplanation, type AuthorizationDecision, type ConnectEventsOptions, type DataPolicy, type DynamicPermissionMatrix, type DynamicPermissionMatrixConfig, type FieldPermission, type FieldPermissionMap, type FieldPermissionType, GRANT_MODES, type GrantMode, type GrantResolution, type PermissionCheck, type PermissionCheckReturn, type PermissionContext, type PermissionEventBus, type PermissionRequirement, type RequireAgentScopeOptions, type RequireGrantOptions, type RequireMandateOptions, type RoleHierarchy, type UserBase, adminOnly, allOf, allow, allowPublic, anyOf, applyAuthorizationDecision, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, collectPublicSurface, conjoinPolicyFilters, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, deny, denyAll, describePermission, describePermissionMap, evaluatePermissionDecision, explainAccess, fields, fullPublic, getUserRoles, modeSatisfies, normalizeRoles, normalizeToDecision, not, ownerWithAdminBypass, permissionMatrix, presets_d_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireGrant, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, scopeOf, when };
+
+import { a as UserBase, c as normalizeRoles, i as PermissionContext, n as DataPolicy, r as PermissionCheck, s as getUserRoles, t as AuthorizationDecision } from "../types-B7XeLEgK.mjs";
+import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, n as FieldPermissionMap, o as fields, r as FieldPermissionType, s as resolveEffectiveRoles, t as FieldPermission } from "../fields-I_EeRWND.mjs";
+import { $ as evaluatePermissionDecision, A as explainAccess, B as anyOf, C as requireGrant, D as collectPublicSurface, E as PermissionRequirement, F as createDynamicPermissionMatrix, G as requireOwnership, H as denyAll, I as createOrgPermissions, J as roles, K as requirePlatformRole, L as allOf, M as DynamicPermissionMatrix, N as DynamicPermissionMatrixConfig, O as describePermission, P as PermissionEventBus, Q as applyAuthorizationDecision, R as allow, S as modeSatisfies, T as AccessExplanation, U as not, V as deny, W as requireAuth, X as scopeOf, Y as when, Z as PermissionCheckReturn, _ as createRoleHierarchy, a as permissionMatrix, at as requireMandate, b as GrantResolution, c as publicReadAdminWrite, d as requireOrgMembership, et as normalizeToDecision, f as requireOrgRole, g as RoleHierarchy, h as requireTeamMembership, i as ownerWithAdminBypass, it as requireDPoP, j as ConnectEventsOptions, k as describePermissionMap, l as readOnly, m as requireServiceScope, n as authenticated, nt as RequireMandateOptions, o as presets_d_exports, p as requireScopeContext, q as requireRoles, r as fullPublic, rt as requireAgentScope, s as publicRead, t as adminOnly, tt as RequireAgentScopeOptions, u as requireOrgInScope, v as GRANT_MODES, w as conjoinPolicyFilters, x as RequireGrantOptions, y as GrantMode, z as allowPublic } from "../index-CEJNZFtX.mjs";
+export { type AccessExplanation, type AuthorizationDecision, type ConnectEventsOptions, type DataPolicy, type DynamicPermissionMatrix, type DynamicPermissionMatrixConfig, type FieldPermission, type FieldPermissionMap, type FieldPermissionType, GRANT_MODES, type GrantMode, type GrantResolution, type PermissionCheck, type PermissionCheckReturn, type PermissionContext, type PermissionEventBus, type PermissionRequirement, type RequireAgentScopeOptions, type RequireGrantOptions, type RequireMandateOptions, type RoleHierarchy, type UserBase, adminOnly, allOf, allow, allowPublic, anyOf, applyAuthorizationDecision, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, collectPublicSurface, conjoinPolicyFilters, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, deny, denyAll, describePermission, describePermissionMap, evaluatePermissionDecision, explainAccess, fields, fullPublic, getUserRoles, modeSatisfies, normalizeRoles, normalizeToDecision, not, ownerWithAdminBypass, permissionMatrix, presets_d_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireGrant, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requirePlatformRole, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, scopeOf, when };

package/dist/permissions/index.mjs

@@ -1,5 +1,6 @@
-import { n as getUserRoles, r as normalizeRoles } from "../userHelpers-Cg_y3fBz.mjs";
-import { a as normalizeToDecision, i as evaluatePermissionDecision, n as applyPermissionResult, o as conjoinPolicyFilters, t as applyAuthorizationDecision } from "../applyPermissionResult-Cf6zUCvb.mjs";
-import { i as resolveEffectiveRoles, n as applyFieldWritePermissions, r as fields, t as applyFieldReadPermissions } from "../fields-CQ_7KQWw.mjs";
-import { A as allow, B as when, C as requireScopeContext, D as requireDPoP, E as requireAgentScope, F as not, I as requireAuth, L as requireOwnership, M as anyOf, N as deny, O as requireMandate, P as denyAll, R as requireRoles, S as requireOrgRole, T as requireTeamMembership, V as scopeOf, _ as explainAccess, a as permissionMatrix, b as requireOrgInScope, c as publicReadAdminWrite, d as GRANT_MODES, f as modeSatisfies, g as describePermissionMap, h as describePermission, i as ownerWithAdminBypass, j as allowPublic, k as allOf, l as readOnly, m as collectPublicSurface, n as authenticated, o as presets_exports, p as requireGrant, r as fullPublic, s as publicRead, t as adminOnly, u as createRoleHierarchy, v as createDynamicPermissionMatrix, w as requireServiceScope, x as requireOrgMembership, y as createOrgPermissions, z as roles } from "../permissions-Bfu_8y1U.mjs";
-export { GRANT_MODES, adminOnly, allOf, allow, allowPublic, anyOf, applyAuthorizationDecision, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, collectPublicSurface, conjoinPolicyFilters, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, deny, denyAll, describePermission, describePermissionMap, evaluatePermissionDecision, explainAccess, fields, fullPublic, getUserRoles, modeSatisfies, normalizeRoles, normalizeToDecision, not, ownerWithAdminBypass, permissionMatrix, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireGrant, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, scopeOf, when };
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { a as conjoinPolicyFilters, i as normalizeToDecision, r as evaluatePermissionDecision, t as applyAuthorizationDecision } from "../authorizationDecision-ChvUQGG1.mjs";
+import { n as getUserRoles, r as normalizeRoles } from "../userHelpers-ChYJ6CdK.mjs";
+import { i as resolveEffectiveRoles, n as applyFieldWritePermissions, r as fields, t as applyFieldReadPermissions } from "../fields-CB5Cuzk9.mjs";
+import { A as allow, B as roles, C as requireScopeContext, D as requireDPoP, E as requireAgentScope, F as not, H as scopeOf, I as requireAuth, L as requireOwnership, M as anyOf, N as deny, O as requireMandate, P as denyAll, R as requirePlatformRole, S as requireOrgRole, T as requireTeamMembership, V as when, _ as explainAccess, a as permissionMatrix, b as requireOrgInScope, c as publicReadAdminWrite, d as GRANT_MODES, f as modeSatisfies, g as describePermissionMap, h as describePermission, i as ownerWithAdminBypass, j as allowPublic, k as allOf, l as readOnly, m as collectPublicSurface, n as authenticated, o as presets_exports, p as requireGrant, r as fullPublic, s as publicRead, t as adminOnly, u as createRoleHierarchy, v as createDynamicPermissionMatrix, w as requireServiceScope, x as requireOrgMembership, y as createOrgPermissions, z as requireRoles } from "../permissions-L--QDAir.mjs";
+export { GRANT_MODES, adminOnly, allOf, allow, allowPublic, anyOf, applyAuthorizationDecision, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, collectPublicSurface, conjoinPolicyFilters, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, deny, denyAll, describePermission, describePermissionMap, evaluatePermissionDecision, explainAccess, fields, fullPublic, getUserRoles, modeSatisfies, normalizeRoles, normalizeToDecision, not, ownerWithAdminBypass, permissionMatrix, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireGrant, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requirePlatformRole, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, scopeOf, when };

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

@@ -1,9 +1,10 @@
-import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.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 { 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, n as PUBLIC_SCOPE, o as getMandate, p as getServiceScopes, u as getRequestScope, v as hasOrgAccess, x as isMember } from "./types-CSyCxl2V.mjs";
-import { a as normalizeToDecision, o as conjoinPolicyFilters } from "./applyPermissionResult-Cf6zUCvb.mjs";
-import { t as MemoryCacheStore } from "./memory-CmnzXE5Z.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
 /**
@@ -106,6 +107,7 @@ function requireAuth() {
 		if (!ctx.user) return deny("Authentication required");
 		return true;
 	};
+	check._requiresAuth = true;
 	return check;
 }
 function requireRoles(rolesOrFirst, optionsOrSecond, ...rest) {
@@ -139,6 +141,36 @@ function requireRoles(rolesOrFirst, optionsOrSecond, ...rest) {
 	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;
+}
+/**
 * Short-form alias of `requireRoles()`. Identical behavior — checks both
 * platform roles AND org roles. Prefer `requireRoles` for new code; this
 * exists for call sites that want a terser name.
@@ -234,6 +266,15 @@ function allOf(...checks) {
 		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;
 }
 /**
@@ -269,6 +310,7 @@ function anyOf(...checks) {
 		}
 		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;
 }
@@ -818,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;
@@ -851,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)}`);
 		}
@@ -889,7 +972,8 @@ function createDynamicPermissionMatrix(config) {
 			try {
 				matrix = await resolveMatrix(ctx, scope.organizationId, orgRoles);
 			} catch (error) {
-				return deny(`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 deny(`Missing permission: ${resource}:${action}`);
 			return true;
@@ -925,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)}`);
@@ -935,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();
@@ -975,15 +1061,30 @@ function createDynamicPermissionMatrix(config) {
 //#region src/permissions/explain.ts
 /**
 * Extract a check's static requirement from its `PermissionCheckMeta`. Public
-* wins; then the union of platform + org roles a role gate declares; otherwise
-* "authenticated" (auth-required / custom / request-time checks).
+* 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
+		roles,
+		conditional
 	};
 	return { kind: "authenticated" };
 }
@@ -1008,23 +1109,63 @@ function explainAccess(check, principal) {
 		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: `requires one of: ${requirement.roles.join(", ")}`,
+		reason: rolesText,
 		requirement
 	};
-	const held = /* @__PURE__ */ new Set([...principal.roles ?? [], ...principal.orgRoles ?? []]);
 	const matched = requirement.roles.filter((r) => held.has(r));
-	return matched.length > 0 ? {
+	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
-	} : {
-		decision: "deny",
-		reason: `requires one of: ${requirement.roles.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
@@ -1167,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) {
@@ -1372,4 +1545,4 @@ function readOnly(overrides) {
 	}, overrides);
 }
 //#endregion
-export { allow as A, when as B, requireScopeContext as C, requireDPoP as D, requireAgentScope as E, not as F, requireAuth as I, requireOwnership as L, anyOf as M, deny as N, requireMandate as O, denyAll as P, requireRoles as R, requireOrgRole as S, requireTeamMembership as T, scopeOf 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, roles as z };
+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 };

package/dist/{pipe-BOLmGIxa.mjs → pipe-DRDNsI2T.mjs}

@@ -1,4 +1,5 @@
-import { r as ForbiddenError } from "./errors-DkO8Nk6-.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { r as ForbiddenError } from "./errors-Cj42AntO.mjs";
 //#region src/pipeline/pipe.ts
 /**
 * Compose pipeline steps into an ordered array.

package/dist/pipeline/index.d.mts

@@ -1,4 +1,5 @@
-import { Ct as PipelineStep, Rt as IControllerResponse, St as PipelineContext, _t as Guard, bt as OperationFilter, vt as Interceptor, wt as Transform, xt as PipelineConfig, yt as NextFunction } from "../index-Q5gzEIWY.mjs";
+
+import { Ct as PipelineStep, Rt as IControllerResponse, St as PipelineContext, _t as Guard, bt as OperationFilter, vt as Interceptor, wt as Transform, xt as PipelineConfig, yt as NextFunction } from "../index-CpzxqePp.mjs";
 //#region src/pipeline/guard.d.ts
 interface GuardOptions {
   operations?: OperationFilter;

package/dist/pipeline/index.mjs

@@ -1,4 +1,5 @@
-import { n as pipe, t as executePipeline } from "../pipe-BOLmGIxa.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { n as pipe, t as executePipeline } from "../pipe-DRDNsI2T.mjs";
 //#region src/pipeline/guard.ts
 /**
 * Create a named guard.

package/dist/{pipeline-BJnpkY9i.mjs → pipeline-UPQFatit.mjs}

@@ -1,8 +1,9 @@
-import { n as getUserRoles } from "./userHelpers-Cg_y3fBz.mjs";
-import { b as isElevated, n as PUBLIC_SCOPE, x as isMember } from "./types-CSyCxl2V.mjs";
-import { i as resolveEffectiveRoles, t as applyFieldReadPermissions } from "./fields-CQ_7KQWw.mjs";
-import { t as executePipeline } from "./pipe-BOLmGIxa.mjs";
-import { t as buildRequestScopeProjection } from "./projection-UBDgfMwu.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { n as getUserRoles } from "./userHelpers-ChYJ6CdK.mjs";
+import { b as isElevated, n as PUBLIC_SCOPE, x as isMember } from "./types-Cys0ko9Z.mjs";
+import { i as resolveEffectiveRoles, t as applyFieldReadPermissions } from "./fields-CB5Cuzk9.mjs";
+import { t as executePipeline } from "./pipe-DRDNsI2T.mjs";
+import { t as buildRequestScopeProjection } from "./projection-BHw6xlOQ.mjs";
 import { isPaginatedResult, toCanonicalList } from "@classytic/repo-core/pagination";
 //#region src/core/fastifyAdapter.ts
 /** Type guard for Mongoose-like documents with toObject() */

package/dist/plugins/index.d.mts

@@ -1,10 +1,11 @@
-import { At as RouteDefinition, J as PresetHook, Q as MiddlewareConfig, et as RouteSchemaOptions } from "../index-Q5gzEIWY.mjs";
-import { l as AnyRecord } from "../types-ChvvVNP8.mjs";
-import { i as errorHandlerPlugin, n as ErrorMapper, r as defaultIsDuplicateKeyError, t as ErrorHandlerOptions } from "../errorHandler-C6yv4ZTW.mjs";
-import { _ as _default$3, d as ScheduleStats, f as SchedulesPluginOptions, g as HealthOptions, h as HealthCheck, m as schedulesPlugin, p as _default$7, u as ScheduleDefinition, v as healthPlugin } from "../types-D_n8L6VY.mjs";
-import { a as arcCorePlugin, i as _default, n as ArcCorePluginOptions, r as PluginMeta, t as ArcCore } from "../fastify-augmentation-0WhPnUH7.mjs";
-import { _ as CachingRule, a as MetricsCollector, c as metricsPlugin, d as _default$5, f as realtimePlugin, g as CachingOptions, h as ssePlugin, i as MetricEntry, l as ChangeOperation, m as _default$8, n as _default$9, o as MetricsOptions, p as SSEOptions, r as versioningPlugin, s as _default$4, t as VersioningOptions, u as RealtimeOptions, v as _default$1, y as cachingPlugin } from "../versioning-DXgY5BUm.mjs";
-import { t as TracingOptions } from "../tracing-CsGKQJGg.mjs";
+
+import { At as RouteDefinition, J as PresetHook, Q as MiddlewareConfig, et as RouteSchemaOptions } from "../index-CpzxqePp.mjs";
+import { l as AnyRecord } from "../types-B7XeLEgK.mjs";
+import { i as errorHandlerPlugin, n as ErrorMapper, r as defaultIsDuplicateKeyError, t as ErrorHandlerOptions } from "../errorHandler-CpYUJmPA.mjs";
+import { _ as _default$3, d as ScheduleStats, f as SchedulesPluginOptions, g as HealthOptions, h as HealthCheck, m as schedulesPlugin, p as _default$7, u as ScheduleDefinition, v as healthPlugin } from "../types-CBgvkp8O.mjs";
+import { a as arcCorePlugin, i as _default, n as ArcCorePluginOptions, r as PluginMeta, t as ArcCore } from "../fastify-augmentation-zh0_AYHa.mjs";
+import { _ as CachingRule, a as MetricsCollector, c as metricsPlugin, d as _default$5, f as realtimePlugin, g as CachingOptions, h as ssePlugin, i as MetricEntry, l as ChangeOperation, m as _default$8, n as _default$9, o as MetricsOptions, p as SSEOptions, r as versioningPlugin, s as _default$4, t as VersioningOptions, u as RealtimeOptions, v as _default$1, y as cachingPlugin } from "../versioning-D_rhHfZm.mjs";
+import { t as TracingOptions } from "../tracing-Dro5eH6j.mjs";
 import { PaginatedResult } from "@classytic/repo-core/pagination";
 import { FastifyInstance, FastifyPluginAsync } from "fastify";
 //#region src/plugins/createPlugin.d.ts

package/dist/plugins/index.mjs

@@ -1,18 +1,19 @@
-import { p as MUTATION_OPERATIONS } from "../constants-DNre0wRg.mjs";
-import { c as getOrgId } from "../types-CSyCxl2V.mjs";
-import { n as requestContext } from "../requestContext-MrlJwECf.mjs";
-import { t as hasEvents } from "../typeGuards-C9KXUly6.mjs";
-import { t as HookSystem } from "../HookSystem-WkIougo6.mjs";
-import { t as ResourceRegistry } from "../ResourceRegistry-y9Hnypus.mjs";
-import { a as requestIdPlugin, i as createRequestIdGenerator, n as health_default, o as requestId_default, s as sanitizeRequestId, t as healthPlugin } from "../health-CB_m4S32.mjs";
-import { n as caching_default, t as cachingPlugin } from "../caching-_NJeDd1_.mjs";
-import { n as errorHandlerPlugin, t as defaultIsDuplicateKeyError } from "../errorHandler-Bq2OeEQL.mjs";
-import { n as metrics_default, t as metricsPlugin } from "../metrics-fdxI5mn_.mjs";
-import { n as realtime_default, t as realtimePlugin } from "../realtime-B9nmIY5V.mjs";
-import { t as replyHelpersPlugin } from "../replyHelpers-67tRawQZ.mjs";
-import { n as schedules_default, t as schedulesPlugin } from "../schedules-CjOd2MG9.mjs";
-import { n as sse_default, t as ssePlugin } from "../sse-BQ1w0dfl.mjs";
-import { n as versioning_default, t as versioningPlugin } from "../versioning-gKWyryT3.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { p as MUTATION_OPERATIONS } from "../constants-D3Dv4LAV.mjs";
+import { c as getOrgId } from "../types-Cys0ko9Z.mjs";
+import { n as requestContext } from "../requestContext-2TxXOJ7T.mjs";
+import { t as hasEvents } from "../typeGuards-B0ryPo3I.mjs";
+import { t as HookSystem } from "../HookSystem-BcmPyq5I.mjs";
+import { t as ResourceRegistry } from "../ResourceRegistry-qq0mn2s9.mjs";
+import { a as requestIdPlugin, i as createRequestIdGenerator, n as health_default, o as requestId_default, s as sanitizeRequestId, t as healthPlugin } from "../health-DjZYjM7H.mjs";
+import { n as caching_default, t as cachingPlugin } from "../caching-BFHA6Scf.mjs";
+import { n as errorHandlerPlugin, t as defaultIsDuplicateKeyError } from "../errorHandler-C5NeD6bT.mjs";
+import { n as metrics_default, t as metricsPlugin } from "../metrics-CUdw_wLB.mjs";
+import { n as realtime_default, t as realtimePlugin } from "../realtime-C5NoxWFY.mjs";
+import { t as replyHelpersPlugin } from "../replyHelpers-DIiZKGUt.mjs";
+import { n as schedules_default, t as schedulesPlugin } from "../schedules-DdtlICTf.mjs";
+import { n as sse_default, t as ssePlugin } from "../sse-CUTo9y0X.mjs";
+import { n as versioning_default, t as versioningPlugin } from "../versioning-CHDTor3P.mjs";
 import fp from "fastify-plugin";
 //#region src/core/arcCorePlugin.ts
 const arcCorePlugin = async (fastify, opts = {}) => {

package/dist/plugins/response-cache.d.mts

@@ -1,3 +1,4 @@
+
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 //#region src/plugins/response-cache.d.ts
 interface ResponseCacheRule {

package/dist/plugins/response-cache.mjs

@@ -1,4 +1,5 @@
-import { t as hasEvents } from "../typeGuards-C9KXUly6.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { t as hasEvents } from "../typeGuards-B0ryPo3I.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/response-cache.ts
 /**

package/dist/plugins/tracing-entry.d.mts

@@ -1,2 +1,3 @@
-import { a as traced, i as isTracingAvailable, n as _default, r as createSpan, t as TracingOptions } from "../tracing-CsGKQJGg.mjs";
+
+import { a as traced, i as isTracingAvailable, n as _default, r as createSpan, t as TracingOptions } from "../tracing-Dro5eH6j.mjs";
 export { type TracingOptions, createSpan, isTracingAvailable, traced, _default as tracingPlugin };

package/dist/plugins/tracing-entry.mjs

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 import { createRequire } from "node:module";
 import fp from "fastify-plugin";
 //#region src/plugins/tracing.ts
@@ -58,7 +59,7 @@ try {
 function createTracerProvider(options) {
 	if (!isAvailable || !NodeTracerProvider || !BatchSpanProcessor || !OTLPTraceExporter) return null;
 	const { serviceName = "@classytic/arc", serviceVersion, exporterUrl = "http://localhost:4318/v1/traces" } = options;
-	const resolvedVersion = serviceVersion ?? "2.30.0";
+	const resolvedVersion = serviceVersion ?? "2.31.0";
 	const exporter = new OTLPTraceExporter({ url: exporterUrl });
 	const provider = new NodeTracerProvider({ resource: { attributes: {
 		"service.name": serviceName,

package/dist/{pluralize-BhrgwZb9.mjs → pluralize-O0FZgESl.mjs}

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 //#region src/utils/pluralize.ts
 /**
 * Lightweight English pluralization for the Arc CLI.