@classytic/arc 2.11.4 → 2.13.1

package/dist/{index-rHjXmJar.d.mts → index-BTqLEvhu.d.mts}

@@ -1,8 +1,168 @@
 import { r as CacheStore, t as CacheLogger } from "./interface-beEtJyWM.mjs";
-import { r as RequestScope } from "./types-DDyTPc6y.mjs";
-import { c as PermissionCheck, l as PermissionContext, u as PermissionResult } from "./fields-BRjxOAFp.mjs";
+import { i as RequestScope, n as Mandate } from "./types-CTYvcwHe.mjs";
+import { c as PermissionCheck, l as PermissionContext, u as PermissionResult } from "./fields-COhcH3fk.mjs";
 import { FastifyReply, FastifyRequest } from "fastify";
 
+//#region src/permissions/agent.d.ts
+/**
+ * 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()) }
+ * ```
+ */
+declare function requireDPoP<TDoc = Record<string, unknown>>(): PermissionCheck<TDoc>;
+/**
+ * Options for `requireMandate(capability, opts)`.
+ */
+interface RequireMandateOptions<TDoc = Record<string, unknown>> {
+  /**
+   * Custom validator for the mandate's numeric ceiling against the inbound
+   * request. Arc passes the request body / params; you decide whether the
+   * action stays within the mandate's `cap`.
+   *
+   * Return `true` to accept, `false` (or a string reason) to deny. When
+   * omitted, arc skips amount validation — useful for boolean-capability
+   * mandates where presence of the mandate IS the authorization (no cap).
+   *
+   * @example
+   * ```typescript
+   * validateAmount: (ctx, mandate) => {
+   *   const amount = (ctx.data as { amount?: number })?.amount ?? 0;
+   *   if (amount <= (mandate.cap ?? 0)) return true;
+   *   return `Amount ${amount} exceeds mandate cap ${mandate.cap}`;
+   * }
+   * ```
+   */
+  validateAmount?: (ctx: PermissionContext<TDoc>, mandate: Readonly<Mandate>) => boolean | string;
+  /**
+   * Resource the mandate must be bound to (`Mandate.audience`). Pass a
+   * static value or a function that derives it from the request (typically
+   * `ctx.params.id`). When set and the mandate's `audience` doesn't match,
+   * the request is denied — prevents a payment-mandate for invoice A being
+   * replayed against invoice B.
+   */
+  audience?: string | ((ctx: PermissionContext<TDoc>) => string | undefined);
+  /**
+   * Clock-skew tolerance for `Mandate.expiresAt`, in milliseconds.
+   * Default `30_000` (30s).
+   */
+  ttlGraceMs?: number;
+  /**
+   * When `true`, `elevated` scope is NOT allowed to bypass the mandate check.
+   * Defaults to `false` — platform admins normally bypass everything.
+   * Set when you genuinely want "even an admin needs a mandate" semantics
+   * (audited break-glass actions, regulated payment flows).
+   */
+  noElevatedBypass?: boolean;
+}
+/**
+ * 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'),
+ * }
+ * ```
+ */
+declare function requireMandate<TDoc = Record<string, unknown>>(capability: string, opts?: RequireMandateOptions<TDoc>): PermissionCheck<TDoc>;
+/**
+ * Options for `requireAgentScope(opts)`.
+ */
+interface RequireAgentScopeOptions<TDoc = Record<string, unknown>> extends RequireMandateOptions<TDoc> {
+  /**
+   * Capability the mandate must authorize (e.g., `payment.charge`,
+   * `inbox.send`). Required.
+   */
+  capability: string;
+  /**
+   * When `true`, the inbound credential must also be DPoP-bound (RFC 9449).
+   * Defaults to `true` — sender-constrained credentials are the standard
+   * for high-value agent flows. Set `false` only when you intentionally
+   * accept bearer tokens (rare; usually a regression).
+   */
+  requireDPoP?: boolean;
+  /**
+   * Optional OAuth-style scope strings the service identity must hold in
+   * addition to the mandate (e.g., `['payment.write']`). Pairs with the
+   * mandate's narrower per-request authorization — scopes answer "ever
+   * allowed?", mandate answers "right now?".
+   */
+  scopes?: readonly string[];
+}
+/**
+ * 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),
+ *       }),
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function requireAgentScope<TDoc = Record<string, unknown>>(opts: RequireAgentScopeOptions<TDoc>): PermissionCheck<TDoc>;
+//#endregion
 //#region src/permissions/applyPermissionResult.d.ts
 /**
  * Normalize a permission check return value (`boolean | PermissionResult`)
@@ -512,4 +672,4 @@ declare function fullPublic<TDoc = any>(overrides?: PermissionOverrides<TDoc>):
  */
 declare function readOnly<TDoc = any>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
 //#endregion
-export { requireRoles as A, allOf as C, not as D, denyAll as E, when as M, applyPermissionResult as N, requireAuth as O, normalizePermissionResult as P, createOrgPermissions as S, anyOf as T, ConnectEventsOptions as _, presets_d_exports as a, PermissionEventBus as b, readOnly as c, requireOrgRole as d, requireScopeContext as f, createRoleHierarchy as g, RoleHierarchy as h, ownerWithAdminBypass as i, roles as j, requireOwnership as k, requireOrgInScope as l, requireTeamMembership as m, authenticated as n, publicRead as o, requireServiceScope as p, fullPublic as r, publicReadAdminWrite as s, adminOnly as t, requireOrgMembership as u, DynamicPermissionMatrix as v, allowPublic as w, createDynamicPermissionMatrix as x, DynamicPermissionMatrixConfig as y };
+export { requireRoles as A, allOf as C, not as D, denyAll as E, RequireAgentScopeOptions as F, RequireMandateOptions as I, requireAgentScope as L, when as M, applyPermissionResult as N, requireAuth as O, normalizePermissionResult as P, requireDPoP as R, createOrgPermissions as S, anyOf as T, ConnectEventsOptions as _, presets_d_exports as a, PermissionEventBus as b, readOnly as c, requireOrgRole as d, requireScopeContext as f, createRoleHierarchy as g, RoleHierarchy as h, ownerWithAdminBypass as i, roles as j, requireOwnership as k, requireOrgInScope as l, requireTeamMembership as m, authenticated as n, publicRead as o, requireServiceScope as p, fullPublic as r, publicReadAdminWrite as s, adminOnly as t, requireOrgMembership as u, DynamicPermissionMatrix as v, allowPublic as w, createDynamicPermissionMatrix as x, DynamicPermissionMatrixConfig as y, requireMandate as z };