@classytic/arc 2.28.0 → 2.30.0

package/dist/{permissions-BrtiBKGs.mjs → permissions-Bfu_8y1U.mjs}

@@ -1,10 +1,68 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.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, o as getMandate, p as getServiceScopes, u as getRequestScope, v as hasOrgAccess, x as isMember } from "./types-CSyCxl2V.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 { 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,10 +103,7 @@ 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;
 	};
 	return check;
@@ -69,22 +124,16 @@ 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;
@@ -97,19 +146,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 +171,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 +204,37 @@ 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];
+	}
+	return check;
 }
 /**
 * Combine multiple checks — ANY must pass (OR logic).
@@ -219,19 +247,30 @@ 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];
+	}
+	return check;
 }
 /**
 * Invert a permission check. Grants when the wrapped check denies, denies
@@ -251,11 +290,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 +302,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 +316,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 +377,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 +426,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 +486,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 +513,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 +536,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 +565,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 +603,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 +646,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 +670,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 +679,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 +690,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 +715,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 +776,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 +808,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;
@@ -944,34 +879,19 @@ 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)}`
-				};
+				return deny(`Permission matrix resolution failed: ${error instanceof Error ? error.message : String(error)}`);
 			}
-			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;
 		};
 	}
@@ -1052,8 +972,132 @@ function createDynamicPermissionMatrix(config) {
 	};
 }
 //#endregion
+//#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).
+*/
+function describePermission(check) {
+	if (check._isPublic) return { kind: "public" };
+	const roles = [...check._roles ?? [], ...check._orgRoles ?? []];
+	if (roles.length > 0) return {
+		kind: "roles",
+		roles
+	};
+	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
+	};
+	if (!principal) return {
+		decision: "conditional",
+		reason: `requires one of: ${requirement.roles.join(", ")}`,
+		requirement
+	};
+	const held = /* @__PURE__ */ new Set([...principal.roles ?? [], ...principal.orgRoles ?? []]);
+	const matched = requirement.roles.filter((r) => held.has(r));
+	return matched.length > 0 ? {
+		decision: "allow",
+		reason: `granted via role(s): ${matched.join(", ")}`,
+		requirement
+	} : {
+		decision: "deny",
+		reason: `requires one of: ${requirement.roles.join(", ")}`,
+		requirement
+	};
+}
+/**
+* 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 +1139,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
@@ -1343,4 +1372,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, 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 };