@classytic/arc 2.28.0 → 2.30.0

package/dist/{index-BMnbzvtO.d.mts → index-Ch16aAah.d.mts}

@@ -1,6 +1,6 @@
 import { r as CacheStore, t as CacheLogger } from "./interface-BGZCzOGL.mjs";
 import { i as RequestScope, n as Mandate } from "./types-DjC-KUCz.mjs";
-import { n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "./types-Dmw-6Qeo.mjs";
+import { i as PermissionContext, r as PermissionCheck, t as AuthorizationDecision } from "./types-ChvvVNP8.mjs";
 import { FastifyReply, FastifyRequest } from "fastify";
 //#region src/permissions/agent.d.ts
 /**
@@ -164,11 +164,35 @@ declare function requireAgentScope<TDoc = Record<string, unknown>>(opts: Require
 //#endregion
 //#region src/permissions/applyPermissionResult.d.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.
+ * A permission check returns either a bare boolean (terse allow/deny sugar) or
+ * a full {@link AuthorizationDecision}. There is no legacy `PermissionResult` —
+ * `AuthorizationDecision` is arc's single authorization contract.
  */
-declare function normalizePermissionResult(result: boolean | PermissionResult): PermissionResult;
+type PermissionCheckReturn = boolean | AuthorizationDecision;
+/**
+ * Normalize a check return into the canonical {@link AuthorizationDecision}.
+ * A boolean promotes to `{ effect: "allow" | "deny" }`; a decision passes
+ * through. This is the ONE place booleans are promoted, so the rest of the
+ * pipeline only ever handles decisions.
+ */
+declare function normalizeToDecision(result: PermissionCheckReturn): AuthorizationDecision;
+/**
+ * Run a permission check and return a canonical {@link AuthorizationDecision} —
+ * the transport-neutral PDP (HTTP, aggregation, MCP, and any future transport).
+ * A thin mapper over {@link evaluatePermissionOutcome}:
+ *
+ *   - a structured `ArcError` is RE-THROWN so the transport surfaces it verbatim
+ *     (e.g. a tier gate throwing `arc.tier_required` with machine-readable meta);
+ *   - any OTHER throw is fail-closed to a `deny` decision (a broken check must
+ *     never fall open to a 500 that skips authorization).
+ *
+ * Pure w.r.t. the request — it neither reads a reply nor mutates the request.
+ * Callers translate the returned decision into their own response mechanism and
+ * apply side-effects via {@link applyAuthorizationDecision}. HTTP additionally
+ * hardens a *thrown* check to 403-even-when-anonymous — that transport-specific
+ * nuance lives in {@link evaluateAndApplyPermission}, not here.
+ */
+declare function evaluatePermissionDecision(check: PermissionCheck, context: PermissionContext): Promise<AuthorizationDecision>;
 /**
  * Minimal shape of a Fastify request that can receive permission side-effects.
  * We avoid depending on the full augmented `FastifyRequest` type here because
@@ -180,8 +204,9 @@ type RequestSink = FastifyRequest & {
   scope?: RequestScope;
 };
 /**
- * Apply a granted `PermissionResult` to a Fastify request — merges row-level
- * filters into `_policyFilters` and conditionally installs the scope.
+ * Apply an allowed {@link AuthorizationDecision} to a Fastify request — conjoins
+ * the decision's row-level `policy` 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
@@ -189,13 +214,47 @@ type RequestSink = FastifyRequest & {
  * 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.
+ * Safe to call with a denied decision — it simply no-ops. Callers should still
+ * check `decision.effect` and send an error response before reaching here, but
+ * this function tolerates the misuse defensively.
+ *
+ * This is the enforcement point (PEP) — the ONE place scope + data policy are
+ * installed (and the obligation seam lives).
+ */
+declare function applyAuthorizationDecision(decision: AuthorizationDecision, request: RequestSink): void;
+/**
+ * @deprecated Renamed to {@link applyAuthorizationDecision} — the contract is an
+ * `AuthorizationDecision`, not a `PermissionResult`. This alias is kept for
+ * back-compat and will be removed in a future major.
  */
-declare function applyPermissionResult(result: PermissionResult, request: RequestSink): void;
+declare const applyPermissionResult: typeof applyAuthorizationDecision;
+//#endregion
+//#region src/permissions/context.d.ts
+/**
+ * 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.
+ */
+declare function scopeOf(ctx: PermissionContext): RequestScope;
 //#endregion
 //#region src/permissions/core.d.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
+ */
+declare function allow(extra?: Omit<AuthorizationDecision, "effect">): AuthorizationDecision;
+/**
+ * Build a `deny` {@link AuthorizationDecision} with an optional human-readable
+ * reason (parallels Cedar's `forbid`). The idiomatic "refuse" return.
+ */
+declare function deny(reason?: string): AuthorizationDecision;
 /**
  * Allow public access (no authentication required).
  *
@@ -272,11 +331,18 @@ declare function requireOwnership<TDoc = Record<string, unknown>>(ownerField?: E
 /**
  * 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
@@ -449,6 +515,120 @@ declare function createOrgPermissions(config: {
  */
 declare function createDynamicPermissionMatrix(config: DynamicPermissionMatrixConfig): DynamicPermissionMatrix;
 //#endregion
+//#region src/permissions/explain.d.ts
+/**
+ * The statically-known requirement of a permission check.
+ *
+ * - `public` — `allowPublic()`; anyone passes.
+ * - `roles` — grants if the caller holds ANY of these (platform OR org roles,
+ *   unioned — matches how `requireRoles`/`requireOrgRole`/`anyOf` compose).
+ * - `authenticated` — the check reads request-time facts (custom auth, service
+ *   scope, ownership, scope-context, grants) that no static analysis can decide;
+ *   the definitive answer is computed per request. Treat as "server decides".
+ */
+type PermissionRequirement = {
+  readonly kind: "public";
+} | {
+  readonly kind: "roles";
+  readonly roles: readonly string[];
+} | {
+  readonly kind: "authenticated";
+};
+/**
+ * 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).
+ */
+declare function describePermission(check: PermissionCheck): PermissionRequirement;
+/** Result of {@link explainAccess}. */
+interface AccessExplanation {
+  /**
+   * `allow` / `deny` are DEFINITIVE from static metadata (public, or a role
+   * match against the supplied principal). `conditional` means the gate reads
+   * request-time state, so the real decision is made per request — this is not a
+   * denial, it is "cannot be determined statically".
+   */
+  decision: "allow" | "deny" | "conditional";
+  /** Human-readable rationale, safe to surface in a UI or an audit report. */
+  reason: string;
+  /** The check's static requirement (the same value {@link describePermission} returns). */
+  requirement: PermissionRequirement;
+}
+/**
+ * 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"] } }
+ */
+declare function explainAccess(check: PermissionCheck, principal?: {
+  roles?: readonly string[];
+  orgRoles?: readonly string[];
+}): AccessExplanation;
+/**
+ * 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.
+ */
+declare function describePermissionMap(permissions: Readonly<Record<string, PermissionCheck | undefined>>): Record<string, PermissionRequirement>;
+/**
+ * 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.
+ */
+declare function collectPublicSurface(permissions: Readonly<Record<string, PermissionCheck | undefined>>): string[];
+//#endregion
+//#region src/permissions/filter-merge.d.ts
+/**
+ * Policy-filter composition — logical AND, never last-writer-wins.
+ *
+ * Row-level policy filters can arrive from several INDEPENDENT sources for one
+ * request: a tenant preset, an `ownedByUser` grant, an `allOf(...)` branch, a
+ * host permission check. Every one of them is a RESTRICTION the row must
+ * satisfy, so composing them is logical AND.
+ *
+ * The historical `{ ...base, ...incoming }` shallow spread did NOT implement AND:
+ * when two sources constrained the SAME key with different values, the later one
+ * silently REPLACED the earlier one — widening (or erasing) a restriction another
+ * layer deliberately imposed. That is a defense-in-depth defect, not a
+ * refinement. "Later can refine" is only sound when the refinement is provably
+ * narrower, and a bare overwrite proves nothing.
+ *
+ * {@link conjoinPolicyFilters} composes with AND semantics while preserving the
+ * common case byte-for-byte:
+ *
+ *  - key present on only one side      → carried through flat. Non-overlapping
+ *    filters (the ~99% case) produce exactly the same object the old spread did,
+ *    so there is ZERO behavior change for them.
+ *  - same key, deep-equal value        → kept once (idempotent — e.g. two checks
+ *    both pinning the same `organizationId`).
+ *  - same key, DIFFERENT value         → BOTH constraints are preserved under an
+ *    `$and`, so a row must satisfy both. For flat equality that conjunction is
+ *    unsatisfiable, so the query returns nothing — the safe, correct outcome for
+ *    contradictory policies (deny), and the earlier restriction is never dropped.
+ *
+ * Adapter safety: mongokit / sqlitekit compile `$and` natively at the DB layer,
+ * and arc's in-memory `simpleEqualityMatcher` (AccessControl.checkPolicyFilters)
+ * already fail-closes on operator-shaped filters. So a produced `$and` is either
+ * evaluated correctly by the DB or rejected fail-closed in memory — both safe.
+ *
+ * This is the pragmatic, adapter-neutral form of the AND semantics. A canonical
+ * filter IR in `repo-core` (nested and/or/not nodes each adapter compiles) is the
+ * fuller design, but this closes the security defect without one.
+ */
+/**
+ * Conjoin two policy-filter maps with AND semantics. Never silently overwrites a
+ * same-key constraint with a different value — conflicting keys are preserved
+ * under `$and`. See the module doc for the full contract.
+ */
+declare function conjoinPolicyFilters(base: Record<string, unknown> | undefined, incoming: Record<string, unknown> | undefined): Record<string, unknown>;
+//#endregion
 //#region src/permissions/grants.d.ts
 /**
  * The grant-mode lattice, weakest → strongest. Holding a mode satisfies
@@ -474,7 +654,7 @@ declare function modeSatisfies(held: string | undefined, required: GrantMode): b
  * - `{ mode }` — the strongest mode the caller holds on `ctx.resourceId`;
  *   the combinator applies the lattice against the required mode.
  * - `{ filters }` — list-shaped resolution: row filters that scope the
- *   query to visible records (flows through `PermissionResult.filters` →
+ *   query to visible records (flows through the decision's `policy` →
  *   `_policyFilters` → the repository query). Grants access with the
  *   filters attached.
  * - `{ mode, filters }` — mode gates; filters ride along when it passes.
@@ -655,8 +835,8 @@ declare function requireScopeContext<TDoc = Record<string, unknown>>(keyOrMap: s
  *
  * **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).
@@ -664,9 +844,9 @@ declare function requireScopeContext<TDoc = Record<string, unknown>>(keyOrMap: s
  * @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'),
  *   ),
  * }
@@ -772,4 +952,4 @@ declare function fullPublic<TDoc = Record<string, unknown>>(overrides?: Permissi
  */
 declare function readOnly<TDoc = Record<string, unknown>>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
 //#endregion
-export { allOf as A, applyPermissionResult as B, requireGrant as C, PermissionEventBus as D, DynamicPermissionMatrixConfig as E, requireAuth as F, requireDPoP as G, RequireAgentScopeOptions as H, requireOwnership as I, requireMandate as K, requireRoles as L, anyOf as M, denyAll as N, createDynamicPermissionMatrix as O, not as P, roles as R, modeSatisfies as S, DynamicPermissionMatrix as T, RequireMandateOptions as U, normalizePermissionResult as V, requireAgentScope as W, createRoleHierarchy as _, permissionMatrix as a, GrantResolution as b, publicReadAdminWrite as c, requireOrgMembership as d, requireOrgRole as f, RoleHierarchy as g, requireTeamMembership as h, ownerWithAdminBypass as i, allowPublic as j, createOrgPermissions as k, readOnly as l, requireServiceScope as m, authenticated as n, presets_d_exports as o, requireScopeContext as p, fullPublic as r, publicRead as s, adminOnly as t, requireOrgInScope as u, GRANT_MODES as v, ConnectEventsOptions as w, RequireGrantOptions as x, GrantMode as y, when as z };
+export { evaluatePermissionDecision as $, explainAccess as A, anyOf as B, requireGrant as C, collectPublicSurface as D, PermissionRequirement as E, createDynamicPermissionMatrix as F, requireOwnership as G, denyAll as H, createOrgPermissions as I, when as J, requireRoles as K, allOf as L, DynamicPermissionMatrix as M, DynamicPermissionMatrixConfig as N, describePermission as O, PermissionEventBus as P, applyPermissionResult as Q, allow as R, modeSatisfies as S, AccessExplanation as T, not as U, deny as V, requireAuth as W, PermissionCheckReturn as X, scopeOf as Y, applyAuthorizationDecision as Z, createRoleHierarchy as _, permissionMatrix as a, requireMandate as at, GrantResolution as b, publicReadAdminWrite as c, requireOrgMembership as d, normalizeToDecision as et, requireOrgRole as f, RoleHierarchy as g, requireTeamMembership as h, ownerWithAdminBypass as i, requireDPoP as it, ConnectEventsOptions as j, describePermissionMap as k, readOnly as l, requireServiceScope as m, authenticated as n, RequireMandateOptions as nt, presets_d_exports as o, requireScopeContext as p, roles as q, fullPublic as r, requireAgentScope as rt, publicRead as s, adminOnly as t, RequireAgentScopeOptions as tt, requireOrgInScope as u, GRANT_MODES as v, conjoinPolicyFilters as w, RequireGrantOptions as x, GrantMode as y, allowPublic as z };

package/dist/{index-CjVg-Epg.d.mts → index-Cx7bro4R.d.mts}

@@ -1,7 +1,7 @@
-import { C as RequestContext, Et as ActionDefinition, F as FastifyWithDecorators, H as CrudController, L as RequestWithExtras, Lt as IController, Rt as IControllerResponse, T as CrudRouterOptions, U as ResourceConfig, V as ResourceDefinition, et as RouteSchemaOptions, jt as RouteMcpConfig, tt as ArcFieldRule, ut as AggregationConfig, zt as IRequestContext } from "./index-DPRH0Cme.mjs";
+import { C as RequestContext, Et as ActionDefinition, F as FastifyWithDecorators, H as CrudController, L as RequestWithExtras, Lt as IController, Rt as IControllerResponse, T as CrudRouterOptions, U as ResourceConfig, V as ResourceDefinition, et as RouteSchemaOptions, jt as RouteMcpConfig, tt as ArcFieldRule, ut as AggregationConfig, zt as IRequestContext } from "./index-Q5gzEIWY.mjs";
 import { i as RequestScope } from "./types-DjC-KUCz.mjs";
-import { c as AnyRecord, t as PermissionCheck } from "./types-Dmw-6Qeo.mjs";
-import "./fastify-augmentation-OzYGIiU1.mjs";
+import { l as AnyRecord, r as PermissionCheck } from "./types-ChvvVNP8.mjs";
+import "./fastify-augmentation-0WhPnUH7.mjs";
 import { FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
 import { z } from "zod";
 import { DataAdapter } from "@classytic/repo-core/adapter";
@@ -170,7 +170,7 @@ declare function defineAction<TSchema extends z.ZodTypeAny | undefined = undefin
 //#endregion
 //#region src/core/defineResource/seams.d.ts
 /**
- * Structural adapter boundary — the `ControllerLike` pattern (v2.10.6)
+ * Structural adapter boundary — the `ControllerLike` pattern
  * applied to adapters. `DataAdapter<T>` is invariant in `T`, so a
  * `DataAdapter<HydratedDocument<IProduct>>` built by the HOST does not
  * assign to a module's `DataAdapter<AnyRecord>` slot; before this type,