@classytic/arc 2.22.0 → 2.25.0

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

@@ -1,496 +1,8 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.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-bHblZ9YN.mjs";
-import { t as getUserRoles } from "./types-XTApa8b6.mjs";
-import { t as MemoryCacheStore } from "./memory-CLXA2VeJ.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";
 import { randomUUID } from "node:crypto";
-//#region src/permissions/fields.ts
-/**
-* Field-Level Permissions
-*
-* Control field visibility and writability per role.
-* Integrated into the response path (read) and sanitization path (write).
-*
-* @example
-* ```typescript
-* import { fields, defineResource } from '@classytic/arc';
-*
-* const userResource = defineResource({
-*   name: 'user',
-*   adapter: userAdapter,
-*   fields: {
-*     salary: fields.visibleTo(['admin', 'hr']),
-*     internalNotes: fields.writableBy(['admin']),
-*     email: fields.redactFor(['viewer']),
-*     password: fields.hidden(),
-*   },
-* });
-* ```
-*/
-/** Type guard for Mongoose-like documents with toObject() */
-function isMongooseDoc(obj) {
-	return !!obj && typeof obj === "object" && "toObject" in obj && typeof obj.toObject === "function";
-}
-const fields = {
-	/**
-	* Field is never included in responses. Not writable via API.
-	*
-	* @example
-	* ```typescript
-	* fields: { password: fields.hidden() }
-	* ```
-	*/
-	hidden() {
-		return { _type: "hidden" };
-	},
-	/**
-	* Field is only visible to users with specified roles.
-	* Other users don't see the field at all.
-	*
-	* @example
-	* ```typescript
-	* fields: { salary: fields.visibleTo(['admin', 'hr']) }
-	* ```
-	*/
-	visibleTo(roles) {
-		return {
-			_type: "visibleTo",
-			roles
-		};
-	},
-	/**
-	* Field is only writable by users with specified roles.
-	* All users can still read the field. Users without the role
-	* have the field silently stripped from write operations.
-	*
-	* @example
-	* ```typescript
-	* fields: { role: fields.writableBy(['admin']) }
-	* ```
-	*/
-	writableBy(roles) {
-		return {
-			_type: "writableBy",
-			roles
-		};
-	},
-	/**
-	* Field is redacted (replaced with a placeholder) for specified roles.
-	* Other users see the real value.
-	*
-	* @param roles - Roles that see the redacted value
-	* @param redactValue - Replacement value (default: '***')
-	*
-	* @example
-	* ```typescript
-	* fields: {
-	*   email: fields.redactFor(['viewer']),
-	*   ssn: fields.redactFor(['basic'], '***-**-****'),
-	* }
-	* ```
-	*/
-	redactFor(roles, redactValue = "***") {
-		return {
-			_type: "redactFor",
-			roles,
-			redactValue
-		};
-	}
-};
-/**
-* Apply field-level READ permissions to a response object.
-* Strips hidden fields, enforces visibility, and applies redaction.
-*
-* @param data - The response object (mutated in place for performance)
-* @param fieldPermissions - Field permission map from resource config
-* @param userRoles - Current user's roles (empty array for unauthenticated)
-* @returns The filtered object
-*/
-function applyFieldReadPermissions(data, fieldPermissions, userRoles) {
-	if (!data || typeof data !== "object") return data;
-	const result = { ...isMongooseDoc(data) ? data.toObject() : data };
-	for (const [field, perm] of Object.entries(fieldPermissions)) switch (perm._type) {
-		case "hidden":
-			delete result[field];
-			break;
-		case "visibleTo":
-			if (!perm.roles?.some((r) => userRoles.includes(r))) delete result[field];
-			break;
-		case "redactFor":
-			if (perm.roles?.some((r) => userRoles.includes(r))) result[field] = perm.redactValue ?? "***";
-			break;
-		case "writableBy": break;
-	}
-	return result;
-}
-/**
-* Apply field-level WRITE permissions to request body.
-*
-* Returns both the filtered body and the list of denied fields. Callers are
-* expected to reject the request when `deniedFields.length > 0` — silently
-* stripping fields hides misconfigurations and real attacks. See
-* `BodySanitizer` for the default policy.
-*
-* @param body - The request body (returns a new filtered copy)
-* @param fieldPermissions - Field permission map from resource config
-* @param userRoles - Current user's roles
-*/
-function applyFieldWritePermissions(body, fieldPermissions, userRoles) {
-	const result = { ...body };
-	const deniedFields = [];
-	for (const [field, perm] of Object.entries(fieldPermissions)) switch (perm._type) {
-		case "hidden":
-			if (field in result) {
-				deniedFields.push(field);
-				delete result[field];
-			}
-			break;
-		case "writableBy":
-			if (field in result && !perm.roles?.some((r) => userRoles.includes(r))) {
-				deniedFields.push(field);
-				delete result[field];
-			}
-			break;
-	}
-	return {
-		body: result,
-		deniedFields
-	};
-}
-/**
-* Resolve effective roles by merging global user roles with org-level roles.
-*
-* Global roles come from `req.user.role` (normalized via getUserRoles()).
-* Org roles come from `req.context.orgRoles` (set by BA adapter's org bridge).
-*
-* When no org context exists, returns global roles only — backward compatible.
-*/
-function resolveEffectiveRoles(userRoles, orgRoles) {
-	if (orgRoles.length === 0) return [...userRoles];
-	if (userRoles.length === 0) return [...orgRoles];
-	return [.../* @__PURE__ */ new Set([...userRoles, ...orgRoles])];
-}
-//#endregion
-//#region src/permissions/applyPermissionResult.ts
-/**
-* Normalize a permission check return value (`boolean | PermissionResult`)
-* into a concrete `PermissionResult`. This is the only place in Arc that
-* promotes booleans to results — keeps the type narrowing honest everywhere.
-*/
-function normalizePermissionResult(result) {
-	if (typeof result === "boolean") return { granted: result };
-	return result;
-}
-/**
-* Apply a granted `PermissionResult` to a Fastify request — merges row-level
-* filters into `_policyFilters` and conditionally installs the scope.
-*
-* **Scope install rule:** only writes `scope` when the current request scope
-* is absent or `public`. This prevents downgrading an already-authenticated
-* request (e.g. Better Auth set `member`, then a permission check returns a
-* narrower `service` scope — the original `member` wins because it came from
-* a more authoritative source).
-*
-* Safe to call with a non-granted result — it simply no-ops. Callers should
-* still check `result.granted` and send an error response before reaching here,
-* but this function tolerates the misuse defensively.
-*/
-function applyPermissionResult(result, request) {
-	if (!result.granted) return;
-	if (result.filters) request._policyFilters = {
-		...request._policyFilters ?? {},
-		...result.filters
-	};
-	if (result.scope) {
-		const current = request.scope;
-		if (!current || current.kind === "public") request.scope = result.scope;
-	}
-}
-/**
-* Max length of a `PermissionResult.reason` string before we fall back to the
-* generic default message. Upstream checks can return arbitrary strings; we
-* clamp to prevent accidental leakage of internal diagnostics or oversized
-* payloads via the 4xx response body.
-*/
-const MAX_DENIAL_REASON_LENGTH = 100;
-/**
-* End-to-end evaluator: runs the permission check, catches throws, normalizes
-* the result, sends a 401/403 response on denial, and applies side-effects on
-* grant. Returns `true` if the caller should continue, `false` if a response
-* has been sent and the caller should return.
-*
-* This is the single source of truth for the 5-step sequence shared by the
-* CRUD router, action router, and MCP tool handlers:
-*
-*   1. `try { await check(ctx) } catch { reply 403 }`
-*   2. `normalizePermissionResult(result)`
-*   3. If denied → 401 (no user) or 403 (user) with clamped reason
-*   4. If granted → `applyPermissionResult` (filters + scope)
-*   5. Return true/false so the caller knows whether to keep going
-*
-* Context construction, pre-check auth gating, and success-path handler
-* invocation stay at the callsite — those are genuinely different per router
-* and don't belong here.
-*
-* @returns `true` if authorized (caller continues), `false` if a response was sent
-*/
-async function evaluateAndApplyPermission(check, context, request, reply, opts) {
-	let result;
-	try {
-		result = await check(context);
-	} catch (err) {
-		request.log?.warn?.({
-			err,
-			resource: context.resource,
-			action: context.action
-		}, "Permission check threw");
-		reply.code(403).send({
-			code: "arc.forbidden",
-			message: "Permission denied",
-			status: 403
-		});
-		return false;
-	}
-	const permResult = normalizePermissionResult(result);
-	if (!permResult.granted) {
-		const defaultMsg = opts?.defaultDenialMessage?.(context.user) ?? (context.user ? "Permission denied" : "Authentication required");
-		const reason = permResult.reason && permResult.reason.length <= MAX_DENIAL_REASON_LENGTH ? permResult.reason : defaultMsg;
-		const status = context.user ? 403 : 401;
-		reply.code(status).send({
-			code: context.user ? "arc.forbidden" : "arc.unauthorized",
-			message: reason,
-			status
-		});
-		return false;
-	}
-	applyPermissionResult(permResult, request);
-	return true;
-}
-//#endregion
-//#region src/permissions/agent.ts
-/**
-* Agent-Auth Permission Helpers — DPoP + capability mandates for AI-agent flows
-*
-* Three checks for the 2025 agent-authorization stack (AP2 / Stripe x402 /
-* MCP authorization / RFC 9700 / RFC 9449 / RFC 9728):
-*
-* - `requireDPoP()`           — token must be sender-constrained (RFC 9449)
-* - `requireMandate(cap, …)`  — capability mandate must authorize this action
-* - `requireAgentScope(opts)` — composite gate: service identity + mandate + DPoP
-*
-* Arc reads `request.scope.mandate` and `request.scope.dpopJkt` populated by
-* your `authenticate` callback. Arc does **not** parse mandate JWTs/VCs or
-* verify DPoP proofs — that's a 1-2 line `jose` call in your authenticator.
-* Arc validates *what's already proved* against the action being attempted.
-*
-* @example
-* ```typescript
-* import { requireDPoP, requireMandate, requireAgentScope } from '@classytic/arc/permissions';
-*
-* defineResource({
-*   name: 'invoice',
-*   permissions: {
-*     pay: requireAgentScope({
-*       capability: 'payment.charge',
-*       requireDPoP: true,
-*       validateAmount: (ctx, mandate) =>
-*         typeof ctx.data?.amount === 'number' && ctx.data.amount <= (mandate.cap ?? 0),
-*       audience: (ctx) => `invoice:${ctx.params?.id}`,
-*     }),
-*   },
-* });
-* ```
-*/
-/** Default grace window for mandate `expiresAt` — accommodates clock skew. */
-const DEFAULT_TTL_GRACE_MS = 3e4;
-/**
-* Require a sender-constrained credential — the inbound token MUST carry a
-* DPoP proof (RFC 9449) bound to a known key. Arc reads `scope.dpopJkt` (the
-* JWK SHA-256 thumbprint per RFC 7638); your `authenticate` function performs
-* the cryptographic `jose.dpop.verify(...)` and sets the field on success.
-*
-* **Pass behavior:**
-* - `service` scope where `dpopJkt` is set → grant
-* - `elevated` scope → grant (platform admin bypass)
-* - Anything else → deny with a clear reason
-*
-* Use for high-value endpoints where bearer-token replay must be impossible:
-* payment charges, data exports, account-takeover-class admin actions.
-*
-* @example
-* ```typescript
-* permissions: { charge: allOf(requireServiceScope('payment.write'), requireDPoP()) }
-* ```
-*/
-function requireDPoP() {
-	const check = (ctx) => {
-		const scope = getRequestScope(ctx.request);
-		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."
-		};
-		return true;
-	};
-	check._dpopRequired = true;
-	return check;
-}
-/**
-* Require a capability mandate (AP2 / x402 / MCP authorization) that
-* authorizes the action being attempted.
-*
-* The mandate is set on `request.scope.mandate` by your authenticate function
-* after verifying the inbound mandate JWT/VC. This check validates that the
-* presented mandate covers the requested capability, hasn't expired, is bound
-* to the right resource (when `audience` opt is set), and respects the
-* mandate's numeric ceiling (when `validateAmount` opt is set).
-*
-* **Pass behavior:**
-* - `elevated` scope → grant unless `noElevatedBypass: true`
-* - `service` scope with mandate matching `capability`, not expired, and
-*   passing `validateAmount` + `audience` checks → grant
-* - Anything else → deny with a precise reason
-*
-* Pair with `requireDPoP()` for replay-resistance, or use the bundled
-* `requireAgentScope(...)` to declare both at once.
-*
-* @example
-* ```typescript
-* // Single payment charge — amount must fit the mandate's cap
-* permissions: {
-*   pay: requireMandate('payment.charge', {
-*     validateAmount: (ctx, m) => (ctx.data as { amount: number }).amount <= (m.cap ?? 0),
-*     audience: (ctx) => `invoice:${ctx.params?.id}`,
-*   }),
-* }
-*
-* // Boolean capability — presence of mandate is the gate
-* permissions: {
-*   exportData: requireMandate('data.export'),
-* }
-* ```
-*/
-function requireMandate(capability, opts = {}) {
-	if (!capability || typeof capability !== "string") throw new Error("requireMandate(capability) requires a non-empty capability string (e.g. 'payment.charge')");
-	const ttlGrace = opts.ttlGraceMs ?? DEFAULT_TTL_GRACE_MS;
-	const noElevatedBypass = opts.noElevatedBypass === true;
-	const check = (ctx) => {
-		const scope = getRequestScope(ctx.request);
-		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 (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 (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}` : ""}`
-			};
-		}
-		return true;
-	};
-	check._mandateCapability = capability;
-	return check;
-}
-/**
-* Composite gate for AI-agent / M2M flows on protected resources.
-*
-* Bundles the three things every high-value agent endpoint needs:
-* 1. **Service identity** — `scope.kind === 'service'` with `clientId`
-* 2. **Capability mandate** — narrows what *this request* may do
-* 3. **DPoP binding** — credential cannot be replayed from a different key
-*
-* Use this instead of hand-composing `allOf(requireServiceScope(...),
-* requireMandate(...), requireDPoP())` — fewer ways to misconfigure, one
-* meta-tag downstream tools (audit, MCP, OpenAPI) can read.
-*
-* @example
-* ```typescript
-* import { requireAgentScope } from '@classytic/arc/permissions';
-*
-* defineResource({
-*   name: 'invoice',
-*   actions: {
-*     pay: {
-*       handler: payInvoice,
-*       permissions: requireAgentScope({
-*         capability: 'payment.charge',
-*         scopes: ['payment.write'],
-*         requireDPoP: true,
-*         audience: (ctx) => `invoice:${ctx.params?.id}`,
-*         validateAmount: (ctx, m) => (ctx.data as { amount: number }).amount <= (m.cap ?? 0),
-*       }),
-*     },
-*   },
-* });
-* ```
-*/
-function requireAgentScope(opts) {
-	const { capability, scopes, requireDPoP: needsDPoP = true, ...mandateOpts } = opts;
-	if (!capability) throw new Error("requireAgentScope({ capability }) is required");
-	const mandateCheck = requireMandate(capability, mandateOpts);
-	const dpopCheck = needsDPoP ? requireDPoP() : null;
-	const requiredScopes = scopes && scopes.length > 0 ? [...scopes] : null;
-	const check = async (ctx) => {
-		const scope = getRequestScope(ctx.request);
-		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 (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(", ")}`
-			};
-		}
-		const mandateResult = await mandateCheck(ctx);
-		if (mandateResult !== true) return typeof mandateResult === "object" ? mandateResult : {
-			granted: false,
-			reason: "Mandate check failed"
-		};
-		if (dpopCheck) {
-			const dpopResult = await dpopCheck(ctx);
-			if (dpopResult !== true) return typeof dpopResult === "object" ? dpopResult : {
-				granted: false,
-				reason: "DPoP binding required"
-			};
-		}
-		return true;
-	};
-	check._agentScope = {
-		capability,
-		scopes: requiredScopes ?? void 0,
-		dpop: needsDPoP
-	};
-	return check;
-}
-//#endregion
 //#region src/permissions/core.ts
 /**
 * Normalize a `string | [readonly string[]]` rest-args tuple into a single
@@ -780,6 +292,231 @@ function when(condition) {
 	};
 }
 //#endregion
+//#region src/permissions/agent.ts
+/**
+* Agent-Auth Permission Helpers — DPoP + capability mandates for AI-agent flows
+*
+* Three checks for the 2025 agent-authorization stack (AP2 / Stripe x402 /
+* MCP authorization / RFC 9700 / RFC 9449 / RFC 9728):
+*
+* - `requireDPoP()`           — token must be sender-constrained (RFC 9449)
+* - `requireMandate(cap, …)`  — capability mandate must authorize this action
+* - `requireAgentScope(opts)` — composite gate: service identity + mandate + DPoP
+*
+* Arc reads `request.scope.mandate` and `request.scope.dpopJkt` populated by
+* your `authenticate` callback. Arc does **not** parse mandate JWTs/VCs or
+* verify DPoP proofs — that's a 1-2 line `jose` call in your authenticator.
+* Arc validates *what's already proved* against the action being attempted.
+*
+* @example
+* ```typescript
+* import { requireDPoP, requireMandate, requireAgentScope } from '@classytic/arc/permissions';
+*
+* defineResource({
+*   name: 'invoice',
+*   permissions: {
+*     pay: requireAgentScope({
+*       capability: 'payment.charge',
+*       requireDPoP: true,
+*       validateAmount: (ctx, mandate) =>
+*         typeof ctx.data?.amount === 'number' && ctx.data.amount <= (mandate.cap ?? 0),
+*       audience: (ctx) => `invoice:${ctx.params?.id}`,
+*     }),
+*   },
+* });
+* ```
+*/
+/** Default grace window for mandate `expiresAt` — accommodates clock skew. */
+const DEFAULT_TTL_GRACE_MS = 3e4;
+/**
+* Require a sender-constrained credential — the inbound token MUST carry a
+* DPoP proof (RFC 9449) bound to a known key. Arc reads `scope.dpopJkt` (the
+* JWK SHA-256 thumbprint per RFC 7638); your `authenticate` function performs
+* the cryptographic `jose.dpop.verify(...)` and sets the field on success.
+*
+* **Pass behavior:**
+* - `service` scope where `dpopJkt` is set → grant
+* - `elevated` scope → grant (platform admin bypass)
+* - Anything else → deny with a clear reason
+*
+* Use for high-value endpoints where bearer-token replay must be impossible:
+* payment charges, data exports, account-takeover-class admin actions.
+*
+* @example
+* ```typescript
+* permissions: { charge: allOf(requireServiceScope('payment.write'), requireDPoP()) }
+* ```
+*/
+function requireDPoP() {
+	const check = (ctx) => {
+		const scope = getRequestScope(ctx.request);
+		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."
+		};
+		return true;
+	};
+	check._dpopRequired = true;
+	return check;
+}
+/**
+* Require a capability mandate (AP2 / x402 / MCP authorization) that
+* authorizes the action being attempted.
+*
+* The mandate is set on `request.scope.mandate` by your authenticate function
+* after verifying the inbound mandate JWT/VC. This check validates that the
+* presented mandate covers the requested capability, hasn't expired, is bound
+* to the right resource (when `audience` opt is set), and respects the
+* mandate's numeric ceiling (when `validateAmount` opt is set).
+*
+* **Pass behavior:**
+* - `elevated` scope → grant unless `noElevatedBypass: true`
+* - `service` scope with mandate matching `capability`, not expired, and
+*   passing `validateAmount` + `audience` checks → grant
+* - Anything else → deny with a precise reason
+*
+* Pair with `requireDPoP()` for replay-resistance, or use the bundled
+* `requireAgentScope(...)` to declare both at once.
+*
+* @example
+* ```typescript
+* // Single payment charge — amount must fit the mandate's cap
+* permissions: {
+*   pay: requireMandate('payment.charge', {
+*     validateAmount: (ctx, m) => (ctx.data as { amount: number }).amount <= (m.cap ?? 0),
+*     audience: (ctx) => `invoice:${ctx.params?.id}`,
+*   }),
+* }
+*
+* // Boolean capability — presence of mandate is the gate
+* permissions: {
+*   exportData: requireMandate('data.export'),
+* }
+* ```
+*/
+function requireMandate(capability, opts = {}) {
+	if (!capability || typeof capability !== "string") throw new Error("requireMandate(capability) requires a non-empty capability string (e.g. 'payment.charge')");
+	const ttlGrace = opts.ttlGraceMs ?? DEFAULT_TTL_GRACE_MS;
+	const noElevatedBypass = opts.noElevatedBypass === true;
+	const check = (ctx) => {
+		const scope = getRequestScope(ctx.request);
+		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 (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 (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}` : ""}`
+			};
+		}
+		return true;
+	};
+	check._mandateCapability = capability;
+	return check;
+}
+/**
+* Composite gate for AI-agent / M2M flows on protected resources.
+*
+* Bundles the three things every high-value agent endpoint needs:
+* 1. **Service identity** — `scope.kind === 'service'` with `clientId`
+* 2. **Capability mandate** — narrows what *this request* may do
+* 3. **DPoP binding** — credential cannot be replayed from a different key
+*
+* Use this instead of hand-composing `allOf(requireServiceScope(...),
+* requireMandate(...), requireDPoP())` — fewer ways to misconfigure, one
+* meta-tag downstream tools (audit, MCP, OpenAPI) can read.
+*
+* @example
+* ```typescript
+* import { requireAgentScope } from '@classytic/arc/permissions';
+*
+* defineResource({
+*   name: 'invoice',
+*   actions: {
+*     pay: {
+*       handler: payInvoice,
+*       permissions: requireAgentScope({
+*         capability: 'payment.charge',
+*         scopes: ['payment.write'],
+*         requireDPoP: true,
+*         audience: (ctx) => `invoice:${ctx.params?.id}`,
+*         validateAmount: (ctx, m) => (ctx.data as { amount: number }).amount <= (m.cap ?? 0),
+*       }),
+*     },
+*   },
+* });
+* ```
+*/
+function requireAgentScope(opts) {
+	const { capability, scopes, requireDPoP: needsDPoP = true, ...mandateOpts } = opts;
+	if (!capability) throw new Error("requireAgentScope({ capability }) is required");
+	const mandateCheck = requireMandate(capability, mandateOpts);
+	const dpopCheck = needsDPoP ? requireDPoP() : null;
+	const requiredScopes = scopes && scopes.length > 0 ? [...scopes] : null;
+	const check = async (ctx) => {
+		const scope = getRequestScope(ctx.request);
+		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 (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(", ")}`
+			};
+		}
+		const mandateResult = await mandateCheck(ctx);
+		if (mandateResult !== true) return typeof mandateResult === "object" ? mandateResult : {
+			granted: false,
+			reason: "Mandate check failed"
+		};
+		if (dpopCheck) {
+			const dpopResult = await dpopCheck(ctx);
+			if (dpopResult !== true) return typeof dpopResult === "object" ? dpopResult : {
+				granted: false,
+				reason: "DPoP binding required"
+			};
+		}
+		return true;
+	};
+	check._agentScope = {
+		capability,
+		scopes: requiredScopes ?? void 0,
+		dpop: needsDPoP
+	};
+	return check;
+}
+//#endregion
 //#region src/permissions/scope.ts
 /**
 * Permission Scope — checks bound to RequestScope.
@@ -1315,6 +1052,82 @@ function createDynamicPermissionMatrix(config) {
 	};
 }
 //#endregion
+//#region src/permissions/grants.ts
+/**
+* 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
+* `see < list < read < write` hierarchy with `manage` folded into the
+* lattice top instead of a separate string namespace.
+*/
+const GRANT_MODES = [
+	"see",
+	"list",
+	"read",
+	"write",
+	"manage"
+];
+/**
+* Does a HELD mode satisfy a REQUIRED mode? Lattice implication —
+* `modeSatisfies('write', 'read') === true`, `modeSatisfies('see', 'read')
+* === false`. Unknown strings (a corrupted grant row) never satisfy
+* anything: fail-closed.
+*/
+function modeSatisfies(held, required) {
+	if (held === void 0) return false;
+	const heldRank = GRANT_MODES.indexOf(held);
+	if (heldRank === -1) return false;
+	return heldRank >= GRANT_MODES.indexOf(required);
+}
+/**
+* Per-record grant gate. Same combinator tier as `requireOwnership` —
+* compose with `anyOf`/`allOf` like any other `PermissionCheck`.
+*
+* Fail-closed contract: resolver throws → denied (logged via
+* `ctx.request.log`); resolution carries neither `mode` nor `filters` →
+* denied; unknown/corrupted mode strings → denied.
+*/
+function requireGrant(options) {
+	const { mode: required, resolve, bypassRoles } = options;
+	return async (ctx) => {
+		if (bypassRoles && ctx.user && getUserRoles(ctx.user).some((r) => bypassRoles.includes(r))) return true;
+		let resolution;
+		try {
+			resolution = await resolve(ctx);
+		} catch (err) {
+			ctx.request.log?.warn?.({
+				err,
+				resource: ctx.resource,
+				action: ctx.action
+			}, "requireGrant: resolve threw — denying (fail-closed)");
+			return {
+				granted: false,
+				reason: "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 (filters !== void 0) return {
+			granted: true,
+			filters
+		};
+		return {
+			granted: false,
+			...reason ? { reason } : {}
+		};
+	};
+}
+//#endregion
 //#region src/permissions/roleHierarchy.ts
 /**
 * Create a role hierarchy from a parent → children map.
@@ -1530,4 +1343,4 @@ function readOnly(overrides) {
 	}, overrides);
 }
 //#endregion
-export { requireDPoP as A, not as C, roles as D, requireRoles as E, applyFieldReadPermissions as F, applyFieldWritePermissions as I, fields as L, applyPermissionResult as M, evaluateAndApplyPermission as N, when as O, normalizePermissionResult as P, resolveEffectiveRoles as R, denyAll as S, requireOwnership as T, requireServiceScope as _, permissionMatrix as a, allowPublic as b, publicReadAdminWrite as c, createDynamicPermissionMatrix as d, createOrgPermissions as f, requireScopeContext as g, requireOrgRole as h, ownerWithAdminBypass as i, requireMandate as j, requireAgentScope as k, readOnly as l, requireOrgMembership as m, authenticated as n, presets_exports as o, requireOrgInScope as p, fullPublic as r, publicRead as s, adminOnly as t, createRoleHierarchy as u, requireTeamMembership as v, requireAuth as w, anyOf as x, allOf as y };
+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 };