@classytic/arc 2.41.1 → 2.44.0

package/dist/actionPermissions-5N04zBL4.mjs

@@ -0,0 +1,772 @@
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { f as createError } from "./errors-CW4anJBy.mjs";
+import { n as getUserRoles } from "./userHelpers-C76zD5pa.mjs";
+import { b as isElevated, n as PUBLIC_SCOPE, u as getRequestScope, x as isMember } from "./types-fvO6Ovzx.mjs";
+import { a as resolveEffectiveRoles, r as deriveHiddenFieldPermissions, t as applyFieldReadPermissions } from "./fields-A5crhsJb.mjs";
+import { t as buildRequestScopeProjection } from "./projection-wFoLqdss.mjs";
+import { n as requestContext } from "./requestContext-C10UeFe5.mjs";
+import { n as isTenantPreparation } from "./tenantPreparation-CBvvAcAj.mjs";
+import { n as evaluateAndApplyPermission } from "./authorizationDecision-wX3SA9w_.mjs";
+import { t as executePipeline } from "./pipe-D81zMtWs.mjs";
+import { n as idempotencyConfigProblem, t as declaresIdempotencyFence } from "./requirement-Bu50QALH.mjs";
+import { i as resolveResourceRateLimiter, r as recordUnenforcedRateLimit } from "./resourceRateLimit-urWPJxrt.mjs";
+import { n as arcRouteValidatorCompiler } from "./routeValidator-DHtpzrzk.mjs";
+import { isPaginatedResult, toCanonicalList } from "@classytic/repo-core/pagination";
+//#region src/core/fastifyAdapter.ts
+/** Type guard for Mongoose-like documents with toObject() */
+function isMongooseDoc(obj) {
+	return !!obj && typeof obj === "object" && "toObject" in obj && typeof obj.toObject === "function";
+}
+/** Apply an include/exclude field mask to a single object. */
+function applyFieldMaskToObject(obj, fieldMask) {
+	if (!obj || typeof obj !== "object") return obj;
+	const plain = isMongooseDoc(obj) ? obj.toObject() : obj;
+	const { include, exclude } = fieldMask;
+	if (include && include.length > 0) {
+		const filtered = {};
+		for (const field of include) if (field in plain) filtered[field] = plain[field];
+		return filtered;
+	}
+	if (exclude && exclude.length > 0) {
+		const filtered = { ...plain };
+		for (const field of exclude) delete filtered[field];
+		return filtered;
+	}
+	return plain;
+}
+/** Apply a field mask to an object or array of objects. */
+function applyFieldMask(data, fieldMask) {
+	if (!fieldMask) return data;
+	if (Array.isArray(data)) return data.map((item) => applyFieldMaskToObject(item, fieldMask));
+	if (data && typeof data === "object") return applyFieldMaskToObject(data, fieldMask);
+	return data;
+}
+/**
+* Project `FastifyRequest` into the `IRequestContext` controllers receive,
+* lifting scope, context, and a server accessor onto a flat, typed surface.
+*/
+function createRequestContext(req) {
+	const reqWithExtras = req;
+	const requestContext = reqWithExtras.context ?? {};
+	const srv = req.server;
+	const serverAccessor = {
+		events: srv && "events" in srv ? srv.events : void 0,
+		audit: srv && "audit" in srv ? srv.audit : void 0,
+		queryCache: srv && "queryCache" in srv ? srv.queryCache : void 0,
+		log: req.log
+	};
+	const rawScope = reqWithExtras.scope;
+	const scopeProjection = buildRequestScopeProjection(rawScope);
+	return {
+		query: reqWithExtras.query ?? {},
+		body: reqWithExtras.body ?? {},
+		params: reqWithExtras.params ?? {},
+		headers: reqWithExtras.headers,
+		user: reqWithExtras.user ? (() => {
+			const user = reqWithExtras.user;
+			const rawId = user._id ?? user.id;
+			const normalizedId = rawId ? String(rawId) : void 0;
+			return {
+				...user,
+				id: normalizedId,
+				_id: normalizedId
+			};
+		})() : null,
+		context: requestContext,
+		scope: scopeProjection,
+		metadata: {
+			...reqWithExtras.context,
+			arc: reqWithExtras.arc,
+			_scope: rawScope,
+			_ownershipCheck: reqWithExtras._ownershipCheck,
+			_crossTenantRead: reqWithExtras._crossTenantRead,
+			_tenantFields: reqWithExtras._tenantFields,
+			_policyFilters: reqWithExtras._policyFilters ?? {},
+			log: reqWithExtras.log
+		},
+		server: serverAccessor
+	};
+}
+/**
+* Typed auth context from an IRequestContext, for controller overrides.
+* For org scope, use `getControllerScope(req)`.
+*/
+function getControllerContext(req) {
+	return req.context ?? req.metadata ?? {};
+}
+/** The RequestScope set by auth adapters (`PUBLIC_SCOPE` when absent). */
+function getControllerScope(req) {
+	return req.metadata?._scope ?? PUBLIC_SCOPE;
+}
+/**
+* Per-field capability metadata for the current user. Only restricted fields
+* appear; clients default the rest to `{ readable: true, writable: true }`.
+*/
+function computeFieldCapabilities(fieldPerms, effectiveRoles) {
+	const caps = {};
+	for (const [field, perm] of Object.entries(fieldPerms)) {
+		let readable = true;
+		let writable = true;
+		switch (perm._type) {
+			case "hidden":
+				readable = false;
+				writable = false;
+				break;
+			case "visibleTo":
+				readable = perm.roles?.some((r) => effectiveRoles.includes(r)) ?? false;
+				break;
+			case "writableBy": writable = perm.roles?.some((r) => effectiveRoles.includes(r)) ?? false;
+		}
+		caps[field] = {
+			readable,
+			writable
+		};
+	}
+	return caps;
+}
+/**
+* Send a controller's `IControllerResponse` envelope (status, meta, headers)
+* through Fastify's reply, applying field masks and field read permissions.
+*
+* A bare return (no `data` key) is wrapped as `{ data, status: 200 }` so
+* `fields:` permissions still apply — otherwise restricted fields would leak.
+* The envelope remains the canonical contract.
+*/
+function sendControllerResponse(reply, response, request) {
+	if (response === null || typeof response !== "object" || !Object.hasOwn(response, "data")) response = {
+		data: response,
+		status: 200
+	};
+	const reqWithExtras = request;
+	const fieldMaskConfig = reqWithExtras?.fieldMask;
+	const arcMeta = reqWithExtras?.arc;
+	const scope = reqWithExtras?.scope ?? PUBLIC_SCOPE;
+	const fieldPerms = isElevated(scope) ? void 0 : arcMeta?.fields;
+	const effectiveRoles = fieldPerms ? resolveEffectiveRoles(getUserRoles(reqWithExtras?.user), isMember(scope) ? scope.orgRoles : []) : [];
+	const fieldCaps = fieldPerms ? computeFieldCapabilities(fieldPerms, effectiveRoles) : void 0;
+	const hasFieldRestrictions = !!(fieldMaskConfig || fieldPerms);
+	/** Apply both field mask and field-level permissions to a data item */
+	const applyPermissions = (data) => {
+		let result = fieldMaskConfig ? applyFieldMask(data, fieldMaskConfig) : data;
+		if (fieldPerms && result && typeof result === "object") {
+			if (Array.isArray(result)) result = result.map((item) => applyFieldReadPermissions(item, fieldPerms, effectiveRoles));
+			else result = applyFieldReadPermissions(result, fieldPerms, effectiveRoles);
+		}
+		return result;
+	};
+	if (response.headers) for (const [key, value] of Object.entries(response.headers)) reply.header(key, value);
+	if (response.data && typeof response.data === "object" && Array.isArray(response.data.data)) {
+		const payload = response.data;
+		const filteredRows = hasFieldRestrictions ? applyPermissions(payload.data) : payload.data;
+		let canonical;
+		if (isPaginatedResult(payload)) canonical = toCanonicalList({
+			...payload,
+			data: filteredRows
+		});
+		else if (typeof payload.page === "number" && typeof payload.limit === "number" && typeof payload.total === "number") canonical = toCanonicalList({
+			method: "offset",
+			data: filteredRows,
+			page: payload.page,
+			limit: payload.limit,
+			total: payload.total,
+			pages: payload.pages ?? Math.ceil(payload.total / Math.max(1, payload.limit)),
+			hasNext: payload.hasNext ?? false,
+			hasPrev: payload.hasPrev ?? false
+		});
+		else canonical = toCanonicalList(filteredRows);
+		reply.code(response.status ?? 200).send({
+			...canonical,
+			...response.meta ?? {},
+			...fieldCaps ? { fieldPermissions: fieldCaps } : {}
+		});
+		return;
+	}
+	const rawData = hasFieldRestrictions ? applyPermissions(response.data) : response.data;
+	const filteredData = rawData !== null && typeof rawData === "object" && typeof rawData.toJSON === "function" ? rawData.toJSON() : rawData;
+	const status = response.status ?? 200;
+	if (filteredData !== null && typeof filteredData === "object" && !Array.isArray(filteredData) && (response.meta || fieldCaps)) {
+		reply.code(status).send({
+			...filteredData,
+			...response.meta ?? {},
+			...fieldCaps ? { fieldPermissions: fieldCaps } : {}
+		});
+		return;
+	}
+	reply.code(status).send(filteredData);
+}
+/**
+* Bridge an `IController` method into a Fastify route handler, sending the
+* envelope through `sendControllerResponse`.
+*
+* @example
+* ```typescript
+* const controller = new BaseController(repository);
+* const listHandler = createFastifyHandler(controller.list.bind(controller));
+* fastify.get('/products', listHandler);
+* ```
+*/
+function createFastifyHandler(controllerMethod) {
+	return async (req, reply) => {
+		sendControllerResponse(reply, await controllerMethod(createRequestContext(req)), req);
+		return reply;
+	};
+}
+/**
+* Fastify handlers for each CRUD method of an IController.
+*
+* @example
+* ```typescript
+* const controller = new BaseController(repository);
+* const handlers = createCrudHandlers(controller);
+*
+* fastify.get('/', handlers.list);
+* fastify.get('/:id', handlers.get);
+* fastify.post('/', handlers.create);
+* fastify.patch('/:id', handlers.update);
+* fastify.delete('/:id', handlers.delete);
+* ```
+*/
+function createCrudHandlers(controller) {
+	return {
+		list: createFastifyHandler(controller.list.bind(controller)),
+		get: createFastifyHandler(controller.get.bind(controller)),
+		create: createFastifyHandler(controller.create.bind(controller)),
+		update: createFastifyHandler(controller.update.bind(controller)),
+		delete: createFastifyHandler(controller.delete.bind(controller))
+	};
+}
+//#endregion
+//#region src/core/middlewares/arcDecorator.ts
+/**
+* Build the `arcDecorator` preHandler for a resource.
+*
+* The decorator is a closure over frozen metadata — allocated once per
+* resource and shared across every request. Stamps `req.arc` with the
+* resource's field permissions, hooks, events bus, and schema options
+* so `sendControllerResponse`, `BaseController.run*`, and custom
+* middleware can read a consistent view.
+*
+* Also populates `requestContext.resourceName` for async-context access
+* in code paths that can't reach `req.arc` directly (e.g. detached logger
+* formatters).
+*/
+function buildArcDecorator(meta) {
+	const frozen = Object.freeze({
+		...meta,
+		fields: deriveHiddenFieldPermissions(meta.schemaOptions, meta.fields)
+	});
+	return async (req, _reply) => {
+		req.arc = frozen;
+		const store = requestContext.get();
+		if (store) store.resourceName = frozen.resourceName;
+	};
+}
+//#endregion
+//#region src/core/middlewares/auth.ts
+/**
+* A permission requires authentication unless it carries the `_isPublic`
+* marker set by `allowPublic()`. Absence of a permission is treated as
+* public (no auth) — matches historical CRUD behaviour.
+*/
+function requiresAuthentication(permission) {
+	if (!permission) return false;
+	return !permission._isPublic;
+}
+/**
+* Pick the right Fastify auth decorator for a single-permission route:
+*   - protected route → `fastify.authenticate` (401 on missing token)
+*   - public route    → `fastify.optionalAuthenticate` (parses token if present)
+*
+* Public routes still get optional auth so downstream multi-tenant filters
+* can narrow queries when a Bearer token IS supplied.
+*/
+function buildAuthMiddleware(fastify, permission) {
+	if (requiresAuthentication(permission)) return fastify.authenticate ?? null;
+	return fastify.optionalAuthenticate ?? null;
+}
+/**
+* Pick the right auth decorator for a multi-permission route (Action router).
+*
+* The input is the array of resolved per-action permissions — one slot per
+* action, in registration order, already flattened against `globalAuth`
+* fallback by the caller (`actionPermissions[name] ?? globalAuth`). A slot
+* may be `undefined` when the action has no per-action check AND no
+* `globalAuth` fallback — that is "public by omission" and must be honored
+* here the same way `buildActionPermissionMw` honors it (by skipping the
+* permission evaluation entirely). If we filtered undefineds out at this
+* layer, a mixed endpoint like `{ ping: undefined, promote: requireRoles(...) }`
+* would collapse to "all protected" and 401 the public `ping` action at the
+* auth layer before the permission prehandler could let it through.
+*
+* Rules:
+*   - ALL public (explicit allowPublic OR omission) → `optionalAuthenticate`
+*   - ALL protected                                 → `authenticate` (fail-fast)
+*   - MIXED                                         → `optionalAuthenticate`
+*     (parse token if present; per-action check fails-closed when user=null)
+*
+* The mixed case was previously handled by an in-handler
+* `fastify.authenticate()` call that bypassed the preHandler chain; this
+* helper moves that logic back into the preHandler stack so the request
+* lifecycle is consistent across router types.
+*/
+function buildAuthMiddlewareForPermissions(fastify, permissions) {
+	if (permissions.length === 0) return fastify.optionalAuthenticate ?? null;
+	const hasProtected = permissions.some((p) => requiresAuthentication(p));
+	const hasPublic = permissions.some((p) => p && p._isPublic === true) || permissions.some((p) => !p);
+	if (hasProtected && !hasPublic) return fastify.authenticate ?? null;
+	return fastify.optionalAuthenticate ?? null;
+}
+//#endregion
+//#region src/core/middlewares/chain.ts
+const validationGates = /* @__PURE__ */ new WeakSet();
+const replayBoundaries = /* @__PURE__ */ new WeakSet();
+/** Rate limiting belongs before a response cache or idempotency replay can return. */
+function isReplayBoundary(hook) {
+	return typeof hook === "function" && replayBoundaries.has(hook);
+}
+/** True iff `hook` is a validation gate built by `buildRouteHooks`. */
+function isValidationGate(hook) {
+	return typeof hook === "function" && validationGates.has(hook);
+}
+/**
+* Build the gate that surfaces a parked validation error. `format` may rethrow it in a
+* route-specific shape; whatever it does, a still-parked error is rethrown verbatim, so
+* invalid input never reaches a later hook or the handler.
+*/
+function buildValidationGate(format) {
+	const gate = async function arcValidationGate(req, reply) {
+		const parked = req.validationError;
+		if (!parked) return;
+		if (format) await format.call(this, req, reply);
+		if (reply.sent) return;
+		throw parked;
+	};
+	validationGates.add(gate);
+	return gate;
+}
+/**
+* Compose the route-level `onRequest` + `preHandler` arrays in the canonical
+* order. Every null/undefined entry is dropped. Keeps the three routers from
+* accidentally ordering the same ingredients differently (regression risk:
+* cache before auth → user-scoped cache keys leak across users; auth after
+* body parse → anonymous schema probing).
+*
+* onRequest constraints (Fastify lifecycle): `request.body` is undefined —
+* everything placed there must be header/cookie/param/query-driven. arc's
+* `authenticate` / `optionalAuthenticate` qualify by contract (Bearer
+* header, session cookie, api-key header); `preAuth` handlers exist
+* precisely to promote query tokens into headers (SSE `?token=`); the arc
+* decorator stamps static route metadata.
+*/
+function buildRouteHooks(parts) {
+	const gated = Boolean(parts.permissionMw);
+	const customMws = parts.customMws ?? [];
+	const tenancy = customMws.filter(isTenantPreparation);
+	const remaining = customMws.filter((middleware) => !isTenantPreparation(middleware));
+	if (parts.pluginMw) replayBoundaries.add(parts.pluginMw);
+	return {
+		onRequest: [
+			...parts.preAuth ?? [],
+			parts.arcDecorator,
+			parts.authMw ?? null
+		].filter(Boolean),
+		preHandler: [
+			gated ? parts.prePermission ?? null : null,
+			parts.permissionMw ?? null,
+			gated ? buildValidationGate(parts.validationFormatter) : null,
+			...tenancy,
+			...parts.routeGuards ?? [],
+			parts.pluginMw ?? null,
+			...remaining
+		].filter(Boolean),
+		attachValidation: gated
+	};
+}
+/**
+* Spread helper — turns `RouteHookChains` into the two Fastify route-option
+* fields, omitting empty arrays so routes without middleware stay
+* option-free (Fastify skips absent hooks faster than empty arrays).
+*/
+function routeHookOptions(hooks) {
+	return {
+		...hooks.attachValidation ? { attachValidation: true } : {},
+		...hooks.onRequest.length > 0 ? { onRequest: hooks.onRequest } : {},
+		...hooks.preHandler.length > 0 ? { preHandler: hooks.preHandler } : {}
+	};
+}
+/**
+* `RouteDefinition.preHandler` accepts two shapes:
+*
+*   1. **Array form** — `RouteHandlerMethod[]`. Used directly.
+*   2. **Factory form** — `(fastify) => RouteHandlerMethod[]`. Called once at
+*      route-registration time with the Fastify instance, so handlers can
+*      capture decorators (`fastify.authenticate`, `fastify.events`, etc.)
+*      that aren't on the request.
+*
+* The two forms are equally idiomatic, but the discrimination is by
+* `typeof preHandler === "function"`. Single-function shapes such as
+* `multipartBody({...})` (a `RouteHandlerMethod`) **structurally satisfy
+* the factory branch** at the call site, then fail with a cryptic
+* `Cannot read properties of undefined (reading 'content-type')` once the
+* handler runs with `fastify` in the request slot.
+*
+* This resolver:
+*   1. Distinguishes the two valid shapes.
+*   2. Validates the factory's RETURN — must be an array of functions.
+*   3. Throws an actionable error pointing at the route + the fix when
+*      a single `RouteHandlerMethod` was passed instead of an array, OR
+*      when a factory returned the wrong shape.
+*
+* The error message names the route (`{method} {path}`) and the
+* canonical fix (`preHandler: [yourHandler]`) so the failure mode is
+* obvious instead of debug-archaeology.
+*
+* @param preHandler  The `route.preHandler` value (any of the valid shapes
+*                    plus the common bare-handler mistake).
+* @param fastify     Passed to factory-form preHandlers.
+* @param routeId     `"GET /todos/:id/attach"` (or similar) — used in the
+*                    error message so a multi-route file points at the
+*                    actual offender.
+*/
+function resolveRoutePreHandlers(preHandler, fastify, routeId) {
+	if (preHandler === void 0 || preHandler === null) return [];
+	if (Array.isArray(preHandler)) return preHandler.filter((h) => typeof h === "function");
+	if (typeof preHandler === "function") {
+		let result;
+		try {
+			result = preHandler(fastify);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new TypeError(`Route ${routeId}: preHandler factory threw during route registration: ${msg}.\nIf you intended to pass a single handler (e.g. \`multipartBody({...})\`), wrap it in an array: \`preHandler: [yourHandler]\`. The factory form is \`(fastify) => RouteHandlerMethod[]\` — it must return an array.`, { cause: err instanceof Error ? err : void 0 });
+		}
+		if (result && typeof result.then === "function") result.catch(() => void 0);
+		if (!Array.isArray(result)) throw new TypeError(`Route ${routeId}: preHandler factory must return an array of handlers, got ${describeValue(result)}.\nCommon cause: passing a single \`RouteHandlerMethod\` (e.g. \`multipartBody({...})\`) where an array was expected. Wrap it: \`preHandler: [yourHandler]\`. The factory form \`(fastify) => RouteHandlerMethod[]\` is for cases that need the Fastify instance — e.g. \`(fastify) => [fastify.authenticate, myHandler]\`.`);
+		return result.filter((h) => typeof h === "function");
+	}
+	throw new TypeError(`Route ${routeId}: preHandler must be an array of handlers OR a factory \`(fastify) => RouteHandlerMethod[]\`. Got ${describeValue(preHandler)}.`);
+}
+function describeValue(v) {
+	if (v === null) return "null";
+	if (v === void 0) return "undefined";
+	if (typeof v === "function") return "a function (single handler — wrap in array)";
+	if (Array.isArray(v)) return `an array of length ${v.length}`;
+	return `${typeof v} (${JSON.stringify(v).slice(0, 80)})`;
+}
+//#endregion
+//#region src/core/middlewares/permissions.ts
+/**
+* Build a PermissionContext from a Fastify request. Extracted so the CRUD
+* permission middleware and the dynamic action-permission check use the same
+* field layout — divergence here silently broke policy filters for actions.
+*/
+function buildPermissionContext(req, opts) {
+	const reqWithExtras = req;
+	const params = req.params;
+	return {
+		user: reqWithExtras.user ?? null,
+		scope: getRequestScope(req),
+		request: req,
+		resource: opts.resource,
+		action: opts.action,
+		resourceId: opts.resourceId ?? params?.id,
+		params,
+		data: opts.data ?? req.body
+	};
+}
+/**
+* Static per-route CRUD permission gate. The permission and action are known
+* at route-registration time, so the gate is a plain preHandler.
+*
+* Actions use the dynamic counterpart `buildActionPermissionMw` — their
+* permission is resolved from `body.action` at request time.
+*/
+function buildCrudPermissionMw(permissionCheck, resourceName, action) {
+	if (!permissionCheck) return null;
+	return async (req, reply) => {
+		const context = buildPermissionContext(req, {
+			resource: resourceName,
+			action
+		});
+		await evaluateAndApplyPermission(permissionCheck, context, req, reply);
+	};
+}
+/**
+* Dynamic per-action permission gate for the action router.
+*
+* Resolves the permission from `body.action` at request time and runs
+* `evaluateAndApplyPermission` from the canonical `permissionMw` slot — so
+* `_policyFilters` and `request.scope` are installed BEFORE `pluginMw`
+* (idempotency) and `routeGuards` run. Previously this check lived inside
+* the main action handler, which meant idempotency recorded unauthorized
+* requests and route guards saw unfiltered scope — the very divergence
+* routerShared exists to prevent.
+*
+* Also acts as a defensive fallback for invalid action names — the
+* `oneOf` body schema normally rejects these at AJV validation, but
+* hosts that disable schema validation still get a 400 here.
+*/
+function buildActionPermissionMw(actionEnum, actionPermissions, globalAuth, resourceName) {
+	const enumSet = new Set(actionEnum);
+	const validActions = [...actionEnum];
+	return async (req, reply) => {
+		const body = req.body ?? {};
+		const action = body.action;
+		if (!action || !enumSet.has(action)) throw createError(400, `Invalid action '${action ?? ""}'. Valid actions: ${validActions.join(", ")}`, { validActions });
+		const permissionCheck = actionPermissions[action] ?? globalAuth;
+		if (!permissionCheck) return;
+		const { action: _discard, ...data } = body;
+		const params = req.params;
+		const context = buildPermissionContext(req, {
+			resource: resourceName,
+			action,
+			resourceId: params?.id,
+			data
+		});
+		await evaluateAndApplyPermission(permissionCheck, context, req, reply, { defaultDenialMessage: (user) => user ? `Permission denied for '${action}'` : "Authentication required" });
+	};
+}
+//#endregion
+//#region src/core/middlewares/pipeline.ts
+/**
+* Resolve pipeline steps for a specific operation.
+* Flat-array config applies to every op; map config applies per-op.
+*/
+function resolvePipelineSteps(pipeline, operation) {
+	if (!pipeline) return [];
+	if (Array.isArray(pipeline)) return pipeline;
+	return pipeline[operation] ?? [];
+}
+/**
+* Wrap a controller method (one that takes `IRequestContext` and returns
+* `IControllerResponse<T>`) with pipeline execution. Used by CRUD ops and
+* string-handler custom routes.
+*/
+function buildPipelineHandler(controllerMethod, steps, operation, resourceName) {
+	return async (req, reply) => {
+		const pipeCtx = {
+			...createRequestContext(req),
+			resource: resourceName,
+			operation
+		};
+		sendControllerResponse(reply, await executePipeline(steps, pipeCtx, (ctx) => controllerMethod(ctx), operation), req);
+	};
+}
+/**
+* Wrap an action handler (one that takes `(id, data, req)` and returns a raw
+* result) with pipeline execution. Returns a function that produces a full
+* `IControllerResponse<unknown>` — the action router feeds this directly into
+* `sendControllerResponse`, so field masking, custom status codes, `meta`,
+* `details`, and structured error codes from pipeline interceptors flow
+* through to the client unchanged.
+*
+* CRUD and actions now share the same parity invariant: a pipeline that
+* returns `{ success: false, status: 422, error, details, meta }` reaches the
+* client with all four fields intact. Previously the action path stringified
+* failures into a generic `Error` and dropped everything except `statusCode`.
+*
+* Handler throws still bubble out — the caller's try/catch handles `onError`
+* shaping and the generic `ACTION_FAILED` fallback.
+*/
+function buildActionPipelineHandler(handler, steps, operation, resourceName) {
+	if (steps.length === 0) return async (id, data, req) => ({
+		status: 200,
+		data: await handler(id, data, req)
+	});
+	return async (id, data, req) => {
+		const pipeCtx = {
+			...createRequestContext(req),
+			resource: resourceName,
+			operation
+		};
+		return executePipeline(steps, pipeCtx, async (_ctx) => ({
+			status: 200,
+			data: await handler(id, data, req)
+		}), operation);
+	};
+}
+//#endregion
+//#region src/core/middlewares/pluginMw.ts
+/**
+* Pick the request-lifecycle plugin middleware for an HTTP method:
+*   - GET / HEAD                  → response cache (if present)
+*   - POST / PUT / PATCH / DELETE → idempotency (if present); the middleware itself decides
+*     whether a key is honoured (plugin `methods`, or the route's `config.idempotency`)
+*
+* Either field may be `null` if the corresponding plugin wasn't registered.
+*/
+function selectPluginMw(method, mws) {
+	const upper = method.toUpperCase();
+	if (upper === "GET" || upper === "HEAD") return mws.cacheMw;
+	if (upper === "POST" || upper === "PUT" || upper === "PATCH" || upper === "DELETE") return mws.idempotencyMw;
+	return null;
+}
+/**
+* Resolve the default cache/idempotency middlewares for a resource.
+*
+* Skips response-cache when the resource has QueryCache active — QueryCache
+* handles caching at the controller level with SWR, so the HTTP-level
+* response-cache would double-cache.
+*/
+function resolveRouterPluginMw(fastify, resourceHasQueryCache) {
+	return {
+		cacheMw: !resourceHasQueryCache && fastify.hasDecorator("responseCache") ? fastify.responseCache.middleware : null,
+		idempotencyMw: fastify.hasDecorator("idempotency") ? fastify.idempotency.middleware : null
+	};
+}
+//#endregion
+//#region src/core/middlewares/rateLimit.ts
+/**
+* Build the per-route Fastify `config` object shared by the CRUD, custom, and
+* action routers. Two independent concerns ride on `routeOptions.config`:
+*   - `config.rateLimit`     — read by `@fastify/rate-limit`.
+*   - `config.cors`          — read by `@fastify/cors` as a per-route override.
+*   - `config.arcExtensions` — read by arc plugins (encryption, …) at request
+*     time, sourced from `defineResource({ extensions })`.
+*   - `config.idempotency`   — read by `idempotencyPlugin` (the key fence).
+*
+* Returns `{}` (no `config` key) when neither is present, so routes without
+* either stay config-free and the spread is a genuine no-op. Both fields are
+* optional in the return type, so no cast is needed when only one is set.
+*/
+function buildRouteConfig(rateLimitConfig, extensions, cors, idempotency) {
+	const hasCors = cors !== void 0;
+	if (!rateLimitConfig && !extensions && !hasCors && !idempotency) return {};
+	return { config: {
+		...rateLimitConfig ?? {},
+		...hasCors ? { cors } : {},
+		...extensions ? { arcExtensions: extensions } : {},
+		...idempotency ? { idempotency } : {}
+	} };
+}
+/**
+* Build the `config` object for Fastify route options so
+* @fastify/rate-limit picks up per-route overrides.
+*
+*   - `undefined`                 → no override (inherits instance config)
+*   - `false`                     → explicitly disable rate limiting
+*   - `{ max, timeWindow }`       → apply that limit
+*/
+function buildRateLimitConfig(rateLimit) {
+	if (rateLimit === void 0) return void 0;
+	if (rateLimit === false) return { rateLimit: false };
+	return { rateLimit: {
+		max: rateLimit.max,
+		timeWindow: rateLimit.timeWindow
+	} };
+}
+//#endregion
+//#region src/core/middlewares/registerRoute.ts
+/**
+* Register a route with friendly handling of `FST_ERR_DUPLICATED_ROUTE`.
+*
+* Boot-time `validateRouteCrudCollisions()` catches custom-route → auto-CRUD
+* overlaps before Fastify ever runs, but a few cases still slip through to
+* Fastify itself: two presets contributing the same `routes` entry, hosts
+* mounting two resources at the same prefix, custom routes that share a
+* URL with another plugin. Fastify's default message ("Method 'GET'
+* already declared for route '/'") gives no hint at the resource-shaped
+* fix — `disabledRoutes: ['list']` — so wrap it with one.
+*/
+function tryRegisterRoute(fastify, opts, context) {
+	const ratePolicy = opts.config?.rateLimit;
+	if (ratePolicy && typeof ratePolicy === "object" && typeof ratePolicy.max === "number" && typeof ratePolicy.timeWindow === "string") {
+		const limiter = resolveResourceRateLimiter(fastify);
+		if (!limiter && !recordUnenforcedRateLimit(fastify, context.resourceName)) throw new Error(`[arc] Resource "${context.resourceName}" declares rateLimit; register @fastify/rate-limit before mounting the resource, or disable rate limiting for the app (createApp({ rateLimit: false })).`);
+		if (!limiter) opts = {
+			...opts,
+			config: {
+				...opts.config,
+				rateLimit: false
+			}
+		};
+		else {
+			const policy = {
+				max: ratePolicy.max,
+				timeWindow: ratePolicy.timeWindow,
+				bucket: context.rateLimitBucket
+			};
+			const handlers = Array.isArray(opts.preHandler) ? opts.preHandler : opts.preHandler ? [opts.preHandler] : [];
+			const limit = async (req, reply) => {
+				const decision = await limiter.consume(context.resourceName, policy, {
+					scope: req.scope,
+					ip: req.ip
+				});
+				for (const [header, value] of Object.entries(decision.headers)) reply.header(header, value);
+				if (!decision.allowed) await reply.code(429).send({
+					code: "arc.rate_limited",
+					message: "Too many calls to this resource — retry later.",
+					status: 429
+				});
+			};
+			const replayIndex = handlers.findIndex(isReplayBoundary);
+			const at = replayIndex < 0 ? handlers.length : replayIndex;
+			opts = {
+				...opts,
+				config: {
+					...opts.config,
+					rateLimit: false
+				},
+				preHandler: [
+					...handlers.slice(0, at),
+					limit,
+					...handlers.slice(at)
+				]
+			};
+		}
+	}
+	const problem = idempotencyConfigProblem(opts.config);
+	if (problem) throw new Error(`[arc] ${String(opts.method)} ${opts.url} on resource "${context.resourceName}": config.idempotency: ${problem}.`);
+	if (declaresIdempotencyFence(opts.config) && !fastify.hasDecorator("idempotency")) throw new Error(`[arc] ${String(opts.method)} ${opts.url} on resource "${context.resourceName}" declares config.idempotency.required, but idempotencyPlugin is not registered — register it (enabled) before the resources, or drop the declaration.`);
+	if (opts.attachValidation === true) {
+		if (!(Array.isArray(opts.preHandler) ? opts.preHandler : [opts.preHandler]).some(isValidationGate)) throw new Error(`[arc] ${String(opts.method)} ${opts.url} on resource "${context.resourceName}" sets attachValidation without arc's validation gate — build its hooks with buildRouteHooks.`);
+	}
+	const validatorCompiler = opts.validatorCompiler ?? arcRouteValidatorCompiler(fastify);
+	try {
+		fastify.route(validatorCompiler ? {
+			...opts,
+			validatorCompiler
+		} : opts);
+	} catch (err) {
+		const fastifyErr = err;
+		if (fastifyErr?.code !== "FST_ERR_DUPLICATED_ROUTE") throw err;
+		const method = opts.method;
+		const url = opts.url;
+		const opHint = context.op ? ` (op: ${context.op})` : "";
+		const fixHint = context.op && [
+			"list",
+			"get",
+			"create",
+			"update",
+			"delete"
+		].includes(context.op) ? ` Suppress the auto-CRUD route with \`disabledRoutes: ['${context.op}']\`.` : " If a custom route in `routes:` collides with auto-CRUD, add `disabledRoutes: ['list' | 'get' | 'create' | 'update' | 'delete']` to `defineResource()` to suppress the matching auto-CRUD route.";
+		const enhanced = /* @__PURE__ */ new Error(`[arc] Duplicate route ${method} ${url} on resource "${context.resourceName}"${opHint}.${fixHint} Original: ${fastifyErr.message ?? "FST_ERR_DUPLICATED_ROUTE"}`);
+		enhanced.code = "FST_ERR_DUPLICATED_ROUTE";
+		enhanced.cause = err;
+		throw enhanced;
+	}
+}
+//#endregion
+//#region src/core/actionPermissions.ts
+/**
+* Return the effective `PermissionCheck` for a single action, or `undefined`
+* when the resource declares no gate at any level.
+*
+* Callers decide what "no gate" means:
+*   - HTTP: boot-time throw in `normalizeActionsToRouterConfig`.
+*   - MCP: tool-generation throw in `resourceToTools` (mirrors HTTP — the
+*     two surfaces fail closed identically so MCP can't expose an
+*     unauthenticated mutating tool when the HTTP plugin lifecycle hasn't
+*     run).
+*   - OpenAPI: docs advertise the endpoint as unauthenticated.
+*/
+function resolveActionPermission(input) {
+	const { action, resourcePermissions, resourceActionPermissions, globalAuth } = input;
+	const explicit = typeof action !== "function" && action.permissions ? action.permissions : void 0;
+	if (explicit) return explicit;
+	if (resourceActionPermissions) return resourceActionPermissions;
+	if (globalAuth) return globalAuth;
+	const updateFallback = resourcePermissions?.update;
+	if (updateFallback) return updateFallback;
+}
+//#endregion
+export { sendControllerResponse as C, getControllerScope as S, buildArcDecorator as _, resolveRouterPluginMw as a, createRequestContext as b, buildPipelineHandler as c, buildCrudPermissionMw as d, buildRouteHooks as f, buildAuthMiddlewareForPermissions as g, buildAuthMiddleware as h, buildRouteConfig as i, resolvePipelineSteps as l, routeHookOptions as m, tryRegisterRoute as n, selectPluginMw as o, resolveRoutePreHandlers as p, buildRateLimitConfig as r, buildActionPipelineHandler as s, resolveActionPermission as t, buildActionPermissionMw as u, createCrudHandlers as v, getControllerContext as x, createFastifyHandler as y };