@classytic/arc 2.28.0 → 2.30.0

package/dist/{types-Dmw-6Qeo.d.mts → types-ChvvVNP8.d.mts}

@@ -95,6 +95,56 @@ declare function getUserRoles(user: {
 } | null | undefined): string[];
 //#endregion
 //#region src/permissions/types.d.ts
+/**
+ * Row-level data policy — the constraint every returned/queried row must
+ * satisfy. This is arc's **Mongo-style record dialect** (`{ ownerId }`,
+ * `{ $or: [...] }`, `{ status: { $ne: "archived" } }`), the ONE canonical
+ * internal representation every permission helper emits and every enforcement
+ * seam composes (`conjoinPolicyFilters`).
+ *
+ * It is compiled to the portable repo-core `Filter` IR at the repository
+ * boundary (`core/repositoryFilter.ts` → `policyRecordToFilter`) so it runs
+ * identically on Mongo / SQL / any kit — arc's answer to oso-style "data
+ * filtering" + Postgres RLS, but datastore-portable and in-process. The IR is a
+ * boundary/compile concern, NOT the decision surface: keeping the decision in
+ * one record dialect means composition (`allOf`/`anyOf`/`conjoin`) has a single
+ * well-defined shape instead of a `Filter | Record` union the composer can't
+ * honor.
+ */
+type DataPolicy = Record<string, unknown>;
+/**
+ * The canonical authorization decision (arc 2.30). A single typed value that
+ * cleanly separates the concerns a permission check expresses:
+ *
+ *  - `effect` — allow / deny (Cedar / XACML decision)
+ *  - `reason` — human-readable diagnostic for the denial (explainability)
+ *  - `policy` — row-level {@link DataPolicy} to enforce at the repository
+ *  - `scope`  — identity/context to install on the request (PIP)
+ *
+ * Build one with the `allow()` / `deny()` constructors. A check may also return
+ * a bare `boolean` (terse allow/deny), normalized via `normalizeToDecision`.
+ *
+ * NOTE: arc deliberately does NOT model XACML-style "obligations" on the
+ * decision. Audit and field redaction are first-class arc subsystems already
+ * (`audit: true` on a resource; field-level read/write permissions), so an
+ * obligations channel would be a second, unenforced way to ask for the same
+ * effects. If a future need arises it will ship WITH a dispatcher that every
+ * enforcement surface runs — never as a declared-but-ignored contract.
+ */
+interface AuthorizationDecision {
+  /** Allow or deny. */
+  effect: "allow" | "deny";
+  /** Human-readable denial reason (surfaced in error messages / explain). */
+  reason?: string;
+  /** Row-level data policy to enforce at the repository layer. */
+  policy?: DataPolicy;
+  /**
+   * Scope to install on `request.scope` when allowed — flows to
+   * `metadata._scope` for tenant-field filtering. The clean integration point
+   * for custom auth (API keys, service accounts, gateway headers).
+   */
+  scope?: RequestScope;
+}
 /**
  * User base interface - minimal shape Arc expects
  * Your actual User can have any additional fields
@@ -107,25 +157,33 @@ interface UserBase {
   [key: string]: unknown;
 }
 /**
- * Extract normalized roles from a user object.
+ * Context passed to permission check functions.
  *
- * Reads `user.role` which can be:
- * - A comma-separated string: `"superadmin,user"` (Better Auth admin plugin)
- * - A string array: `["admin", "user"]` (JWT / custom auth)
- * - A single string: `"admin"`
- */
-/**
- * Normalize a raw role value (string, comma-separated string, or array) into a string[].
- * Shared low-level helper used by both getUserRoles() and the Better Auth adapter.
- */
-/**
- * Context passed to permission check functions
+ * arc 2.30: checks read FACTS off this context — never off a raw request. Use
+ * `scopeOf(ctx)` (from `./context.js`) to read the scope; it prefers the
+ * first-class {@link PermissionContext.scope} and lets combinators thread an
+ * updated scope to child checks WITHOUT mutating the request. `request` is a
+ * transport escape hatch (present for HTTP; absent for MCP/jobs/ws) and is being
+ * retired as the primary channel.
  */
 interface PermissionContext<TDoc = Record<string, unknown>> {
   /** Authenticated user or null if unauthenticated */
   user: UserBase | null;
-  /** Fastify request object */
-  request: FastifyRequest;
+  /**
+   * Resolved request scope (identity + tenant/org context). First-class so
+   * combinators can thread an accumulated scope purely and non-HTTP transports
+   * need no request. Read via `scopeOf(ctx)`.
+   */
+  scope?: RequestScope;
+  /**
+   * Raw Fastify request — transport escape hatch, present ONLY on the HTTP
+   * surface. It is `undefined` for MCP, jobs, and any non-Fastify transport, so
+   * a permission check must NOT depend on it: read identity via `scopeOf(ctx)`,
+   * inputs via `ctx.data` / `ctx.params`, and host facts via `ctx.attributes`.
+   * Kept solely for genuinely HTTP-coupled checks (e.g. a usage meter on
+   * `request.server`) which are inherently transport-specific.
+   */
+  request?: FastifyRequest;
   /** Resource name being accessed */
   resource: string;
   /** Action being performed (list, get, create, update, delete, or custom operation name) */
@@ -136,93 +194,40 @@ interface PermissionContext<TDoc = Record<string, unknown>> {
   params?: Record<string, string>;
   /** Request body data */
   data?: Partial<TDoc> | Record<string, unknown>;
-}
-/**
- * Result from a permission check.
- *
- * Permission checks can do three things:
- * 1. **Grant or deny** access (`granted`, `reason`)
- * 2. **Attach row-level filters** (`filters`) — these merge into `_policyFilters`
- *    and narrow subsequent queries (e.g. `{ userId: ctx.user.id }` for ownership)
- * 3. **Install the request scope** (`scope`) — when a custom authenticator wants
- *    to set tenant/identity context directly from the permission layer, without
- *    relying on a separate auth plugin
- *
- * The `scope` field is the clean integration point for custom auth strategies
- * (API keys, service accounts, gateway headers). When present, Arc writes it to
- * `request.scope` which then flows through the normal tenant-filtering pipeline
- * (QueryResolver + AccessControl). This is the idiomatic way to wire non-Better-Auth
- * identity providers into Arc's multi-tenancy without touching the auth plugin layer.
- *
- * @example
- * ```typescript
- * // Custom API-key auth — grant access AND install a service scope in one step
- * export function requireApiKey(): PermissionCheck {
- *   return async ({ request }) => {
- *     const apiKey = request.headers['x-api-key'] as string | undefined;
- *     if (!apiKey) return { granted: false, reason: 'Missing API key' };
- *
- *     const client = await ClientModel.findOne({ apiKey });
- *     if (!client) return { granted: false, reason: 'Invalid API key' };
- *
- *     return {
- *       granted: true,
- *       // Install service scope — Arc writes this to request.scope automatically,
- *       // and tenantField filtering picks it up via metadata._scope
- *       scope: {
- *         kind: 'service',
- *         clientId: String(client._id),
- *         organizationId: String(client.companyId),
- *         scopes: client.allowedScopes,
- *       },
- *       // Optional row-level narrowing (e.g. per-project API keys)
- *       filters: client.projectId ? { projectId: client.projectId } : undefined,
- *     };
- *   };
- * }
- * ```
- */
-interface PermissionResult {
-  /** Whether access is granted */
-  granted: boolean;
-  /** Reason for denial (for error messages) */
-  reason?: string;
-  /** Query filters to apply (for ownership / row-level security patterns) */
-  filters?: Record<string, unknown>;
   /**
-   * Install this scope on `request.scope` when granted. Flows through to
-   * `metadata._scope` and is read by QueryResolver / AccessControl for
-   * tenant-field filtering. Use this to wire custom auth (API keys, service
-   * accounts, gateway headers) into Arc's multi-tenancy without a separate
-   * auth plugin.
+   * Transport/host-supplied attributes a check may need for ABAC decisions
+   * (headers, claims, feature flags) without reaching into the raw request.
    */
-  scope?: RequestScope;
+  attributes?: Readonly<Record<string, unknown>>;
 }
 /**
- * Permission Check Function
+ * Permission Check Function — THE way to define permissions in Arc.
  *
- * THE ONLY way to define permissions in Arc.
- * Returns boolean, PermissionResult, or Promise of either.
+ * Returns a `boolean` (terse allow/deny) or an {@link AuthorizationDecision}
+ * (effect + optional data `policy` and `scope`). Build decisions with the
+ * `allow()` / `deny()` constructors from `@classytic/arc/permissions`.
  *
  * @example
  * ```typescript
- * // Simple boolean return
+ * // Simple boolean
  * const isAdmin: PermissionCheck = (ctx) => getUserRoles(ctx.user).includes('admin');
  *
- * // With filters for ownership
- * const ownedByUser: PermissionCheck = (ctx) => ({
- *   granted: true,
- *   filters: { userId: ctx.user?.id }
- * });
+ * // Grant + row-level data policy (ownership)
+ * const ownedByUser: PermissionCheck = (ctx) =>
+ *   allow({ policy: { userId: ctx.user?.id } });
  *
- * // Async check
- * const canAccessOrg: PermissionCheck = async (ctx) => {
- *   const isMember = await checkMembership(ctx.user?.id, ctx.organizationId);
- *   return { granted: isMember, reason: isMember ? undefined : 'Not a member' };
+ * // Custom API-key auth — grant AND install a service scope
+ * const requireApiKey: PermissionCheck = async ({ request }) => {
+ *   const client = await lookup(request.headers['x-api-key']);
+ *   if (!client) return deny('Invalid API key');
+ *   return allow({
+ *     scope: { kind: 'service', clientId: String(client._id), organizationId: String(client.companyId) },
+ *     ...(client.projectId ? { policy: { projectId: client.projectId } } : {}),
+ *   });
  * };
  * ```
  */
-type PermissionCheck<TDoc = Record<string, unknown>> = ((context: PermissionContext<TDoc>) => boolean | PermissionResult | Promise<boolean | PermissionResult>) & PermissionCheckMeta;
+type PermissionCheck<TDoc = Record<string, unknown>> = ((context: PermissionContext<TDoc>) => boolean | AuthorizationDecision | Promise<boolean | AuthorizationDecision>) & PermissionCheckMeta;
 /**
  * Optional metadata attached to permission check functions.
  * Used for OpenAPI data, introspection, and route-level auth decisions.
@@ -287,4 +292,4 @@ interface PermissionCheckMeta {
   };
 }
 //#endregion
-export { getUserId as a, AnyRecord as c, ObjectId as d, UserLike as f, UserBase as i, ArcRequest as l, PermissionContext as n, getUserRoles as o, UserOrganization as p, PermissionResult as r, normalizeRoles as s, PermissionCheck as t, JWTPayload as u };
+export { UserBase as a, normalizeRoles as c, JWTPayload as d, ObjectId as f, PermissionContext as i, AnyRecord as l, UserOrganization as m, DataPolicy as n, getUserId as o, UserLike as p, PermissionCheck as r, getUserRoles as s, AuthorizationDecision as t, ArcRequest as u };

package/dist/{types-Cu6vVJmh.d.mts → types-D_n8L6VY.d.mts}

@@ -1,4 +1,4 @@
-import { r as EventHandler } from "./EventTransport-QmY7A258.mjs";
+import { n as DomainEvent, r as EventHandler } from "./EventTransport-QmY7A258.mjs";
 import { n as ErrorMapper } from "./errorHandler-C6yv4ZTW.mjs";
 import { FastifyInstance, FastifyPluginAsync } from "fastify";
 import { LockAdapter } from "@classytic/repo-core/lock";
@@ -343,6 +343,37 @@ interface EventHandlerDefinition {
    * `inventory.order-created`; Arc does not silently rewrite public names.
    */
   name?: string;
+  /**
+   * Contain handler failures inside an error boundary — arc wraps `handler`
+   * with `wrapWithBoundary`, so a throw is logged (through `fastify.log`, with
+   * `{ err, event, eventId, handler }`) and swallowed instead of reaching the
+   * transport.
+   *
+   * **Off by default, deliberately.** Reaching the transport is what makes the
+   * durable path work: `RedisStreamTransport` leaves the message unacked, so it
+   * is redelivered and eventually DLQ'd. Silently swallowing by default would
+   * turn every module handler into best-effort delivery.
+   *
+   * Turn it ON for fire-and-forget work — projections, cache invalidation,
+   * notification fan-out — where a failure must not block the ack and a retry
+   * would only delay the next event's resync. That is precisely the case where
+   * a module author would otherwise abandon this arm for an imperative
+   * `subscribeWithBoundary` call in `afterResources` and lose arc's
+   * teardown-before-`onClose` guarantee.
+   *
+   * ```ts
+   * defineModule({ name: "search", eventHandlers: [
+   *   { name: "search.reindex", event: "product:*", handler: reindex, boundary: true },
+   * ] })
+   * ```
+   *
+   * The object form adds an `onError` sink (metrics / alerting) in place of the
+   * default log; it runs INSIDE the boundary, so a throwing `onError` is itself
+   * caught and logged rather than escaping.
+   */
+  boundary?: boolean | {
+    onError?: (error: Error, event: DomainEvent) => void | Promise<void>;
+  };
 }
 interface ArcModule<TExports = unknown> {
   /** Stable identifier — appears in boot logs and duplicate-module detection. */

package/dist/usage/index.d.mts

@@ -1,5 +1,5 @@
 import { i as RequestScope } from "../types-DjC-KUCz.mjs";
-import { n as PermissionContext, t as PermissionCheck } from "../types-Dmw-6Qeo.mjs";
+import { i as PermissionContext, r as PermissionCheck } from "../types-ChvvVNP8.mjs";
 import { UsageBucket, UsageStore, usagePeriod } from "@classytic/repo-core/usage";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 //#region src/usage/requireQuota.d.ts

package/dist/utils/index.d.mts

@@ -1,6 +1,6 @@
-import { $ as OpenApiSchemas, S as QueryParserInterface, b as ParsedQuery } from "../index-DPRH0Cme.mjs";
+import { $ as OpenApiSchemas, S as QueryParserInterface, b as ParsedQuery } from "../index-Q5gzEIWY.mjs";
 import { F as getHeader, I as requireSingleHeaderValue, P as ArcHeaders } from "../types-DjC-KUCz.mjs";
-import { a as getUserId, c as AnyRecord, o as getUserRoles, s as normalizeRoles } from "../types-Dmw-6Qeo.mjs";
+import { c as normalizeRoles, l as AnyRecord, o as getUserId, s as getUserRoles } from "../types-ChvvVNP8.mjs";
 import { n as ErrorMapper } from "../errorHandler-C6yv4ZTW.mjs";
 import { a as NotFoundError, c as RateLimitError, d as ValidationError, f as createDomainError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorOptions, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-DHcHVAgk.mjs";
 import { errorContractSchema, errorDetailSchema } from "@classytic/repo-core/errors";
@@ -1313,9 +1313,6 @@ interface StateMachine {
    * Record a transition
    */
   recordTransition?(from: string, to: string, action: string, metadata?: Record<string, unknown>): void;
-  /**
-   * Clear history
-   */
   clearHistory?(): void;
   /**
    * Get available actions for current status