@classytic/arc 2.18.2 → 2.18.3

package/dist/routerShared-Dl0A77Ba.mjs

@@ -1,724 +0,0 @@
-import { h as SYSTEM_FIELDS } from "./constants-TrJVIJl0.mjs";
-import { f as createError, r as ForbiddenError } from "./errors-j4aJm1Wg.mjs";
-import { b as isElevated, c as getOrgId, g as getUserId, n as PUBLIC_SCOPE, x as isMember } from "./types-Bi0r0vjG.mjs";
-import { n as requestContext } from "./requestContext-DDLS3NVU.mjs";
-import { I as evaluateAndApplyPermission, M as applyFieldWritePermissions, P as resolveEffectiveRoles, j as applyFieldReadPermissions } from "./permissions-B1Qy55fg.mjs";
-import { t as getUserRoles } from "./types-DV9WDfeg.mjs";
-import { t as executePipeline } from "./pipe-DiCyvyPN.mjs";
-import { isPaginatedResult, toCanonicalList } from "@classytic/repo-core/pagination";
-//#region src/core/BodySanitizer.ts
-/**
-* BodySanitizer - Composable body sanitization logic extracted from BaseController.
-*
-* Strips readonly fields, system-managed fields, and applies field-level
-* write permissions from request bodies before create/update operations.
-*
-* Designed to be used standalone or composed into controllers.
-*/
-const DEFAULT_FIELD_WRITE_DENIAL_POLICY = "reject";
-var BodySanitizer = class {
-	schemaOptions;
-	onFieldWriteDenied;
-	constructor(config) {
-		this.schemaOptions = config.schemaOptions;
-		this.onFieldWriteDenied = config.onFieldWriteDenied ?? "reject";
-	}
-	/**
-	* Strip readonly and system-managed fields from request body.
-	* Prevents clients from overwriting _id, timestamps, __v, etc.
-	*
-	* Also applies field-level write permissions when the request has
-	* field permission metadata.
-	*/
-	sanitize(body, _operation, req, meta) {
-		let sanitized = { ...body };
-		for (const field of SYSTEM_FIELDS) delete sanitized[field];
-		const scopeForRules = req ? (meta ?? req.metadata)?._scope ?? PUBLIC_SCOPE : void 0;
-		const scopeIsElevated = scopeForRules ? isElevated(scopeForRules) : false;
-		const fieldRules = this.schemaOptions.fieldRules ?? {};
-		for (const [field, rules] of Object.entries(fieldRules)) {
-			const bypass = Boolean(rules.preserveForElevated) && scopeIsElevated;
-			if ((rules.systemManaged || rules.readonly) && !bypass) delete sanitized[field];
-			if (_operation === "update" && (rules.immutable || rules.immutableAfterCreate) && !bypass) delete sanitized[field];
-		}
-		if (req) {
-			const arcContext = meta ?? req.metadata;
-			const scope = arcContext?._scope ?? PUBLIC_SCOPE;
-			if (!isElevated(scope)) {
-				const fieldPerms = arcContext?.arc?.fields;
-				if (fieldPerms) {
-					const effectiveRoles = resolveEffectiveRoles(getUserRoles(req.user), isMember(scope) ? scope.orgRoles : []);
-					const { body: filtered, deniedFields } = applyFieldWritePermissions(sanitized, fieldPerms, effectiveRoles);
-					if (deniedFields.length > 0 && this.onFieldWriteDenied === "reject") throw new ForbiddenError(`Not permitted to write field${deniedFields.length === 1 ? "" : "s"}: ${deniedFields.join(", ")}`);
-					sanitized = filtered;
-				}
-			}
-		}
-		return sanitized;
-	}
-};
-//#endregion
-//#region src/scope/projection.ts
-/**
-* Compute the request-scope projection. Returns `undefined` when no
-* scope is attached (public / unscoped routes) so hosts can idiomatically
-* write `ctx.scope?.organizationId` without a double-null check.
-*/
-function buildRequestScopeProjection(scope) {
-	if (!scope) return void 0;
-	return {
-		organizationId: getOrgId(scope),
-		userId: getUserId(scope),
-		orgRoles: isMember(scope) ? scope.orgRoles : void 0
-	};
-}
-//#endregion
-//#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 field mask to a single object
-* Filters fields based on include/exclude rules
-*/
-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 field mask to response data (handles both objects and arrays)
-*/
-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 curated `IRequestContext` shape that
-* arc's controllers receive. This is a developer-facing facade, not a
-* portability boundary — arc is Fastify-only. The projection lifts the
-* fields tenant-scoped controllers reach for (`organizationId`,
-* `teamId`, `scope`, `context`, server accessor) onto a flat, typed
-* surface so handler code doesn't have to dig through Fastify's
-* decorator surface or `req.metadata._scope` internals.
-*/
-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,
-			_policyFilters: reqWithExtras._policyFilters ?? {},
-			log: reqWithExtras.log
-		},
-		server: serverAccessor
-	};
-}
-/**
-* Get typed auth context from an IRequestContext.
-* Use this in controller overrides to access request context.
-*
-* For org scope, use `getControllerScope(req)` instead.
-*/
-function getControllerContext(req) {
-	return req.context ?? req.metadata ?? {};
-}
-/**
-* Get request scope from an IRequestContext.
-* Returns the RequestScope set by auth adapters.
-*/
-function getControllerScope(req) {
-	return req.metadata?._scope ?? PUBLIC_SCOPE;
-}
-/**
-* Compute per-field capability metadata for the current user.
-* Only includes fields that have restrictions — unrestricted fields
-* are omitted (frontend defaults 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;
-				break;
-		}
-		caps[field] = {
-			readable,
-			writable
-		};
-	}
-	return caps;
-}
-/**
-* Send a controller's `IControllerResponse` through Fastify's reply.
-*
-* The `IControllerResponse<T>` envelope is arc's internal pipeline
-* contract — it's how custom `status`, `meta`, `headers`, and field
-* permissions thread from a handler through interceptors to the wire
-* without each step having to touch `reply` directly. Not a portability
-* abstraction (arc is Fastify-only); a pipeline-internal one.
-*
-* **Auto-envelope of bare returns.** Custom route handlers are
-* expected to return the envelope shape so this function can apply
-* field permissions, attach `fieldCaps`, and flatten paginated lists.
-* A handler that returns raw `T` (array, plain object, primitive) used
-* to silently produce a broken response — `response.data` was
-* `undefined`, the body sent was `undefined`, and any declared
-* `fields:` permission map was bypassed (the leak shape mentora
-* flagged). 2.17 detects bare returns and wraps them into
-* `{ data: response, status: 200 }` before the field-permission
-* pipeline runs, so `fields:` applies to ALL custom routes whether the
-* handler envelopes its return value or not. The envelope shape is
-* still the canonical contract — auto-wrapping is a safety net, not
-* an invitation to drop the envelope.
-*/
-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 (`(ctx: IRequestContext) => Promise<IControllerResponse<T>>`)
-* into a Fastify route handler. Translates between arc's curated request
-* context surface and Fastify's request/reply, and routes the envelope
-* through `sendControllerResponse` so the pipeline applies field
-* permissions, status, and meta uniformly. Internal plumbing, not a
-* portability layer — arc is Fastify-only.
-*
-* @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);
-	};
-}
-/**
-* Create Fastify adapters for all CRUD methods of an IController
-*
-* Returns Fastify-compatible handlers for each CRUD operation
-*
-* @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/routerShared.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 });
-	return async (req, _reply) => {
-		req.arc = frozen;
-		const store = requestContext.get();
-		if (store) store.resourceName = frozen.resourceName;
-	};
-}
-/**
-* 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;
-}
-/**
-* 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,
-		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) => {
-		await evaluateAndApplyPermission(permissionCheck, buildPermissionContext(req, {
-			resource: resourceName,
-			action
-		}), 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;
-		await evaluateAndApplyPermission(permissionCheck, buildPermissionContext(req, {
-			resource: resourceName,
-			action,
-			resourceId: params?.id,
-			data
-		}), req, reply, { defaultDenialMessage: (user) => user ? `Permission denied for '${action}'` : "Authentication required" });
-	};
-}
-/**
-* 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) => {
-		sendControllerResponse(reply, await executePipeline(steps, {
-			...createRequestContext(req),
-			resource: resourceName,
-			operation
-		}, (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) => {
-		return executePipeline(steps, {
-			...createRequestContext(req),
-			resource: resourceName,
-			operation
-		}, async (_ctx) => ({
-			status: 200,
-			data: await handler(id, data, req)
-		}), operation);
-	};
-}
-/**
-* 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
-	} };
-}
-/**
-* Pick the request-lifecycle plugin middleware for an HTTP method:
-*   - GET / HEAD        → response cache (if present)
-*   - POST / PUT / PATCH → idempotency (if present)
-*   - DELETE            → none
-*
-* 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") 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
-	};
-}
-/**
-* Compose preHandler[] in the canonical order. Every null/undefined entry is
-* dropped. Keeps CRUD and Action routers from accidentally ordering the same
-* ingredients differently (regression risk: cache before auth → user-scoped
-* cache keys leak across users).
-*
-* Canonical order:
-*   preAuth → arcDecorator → authMw → permissionMw → pluginMw → routeGuards → customMws
-*/
-function buildPreHandlerChain(parts) {
-	return [
-		...parts.preAuth ?? [],
-		parts.arcDecorator,
-		parts.authMw ?? null,
-		parts.permissionMw ?? null,
-		parts.pluginMw ?? null,
-		...parts.routeGuards ?? [],
-		...parts.customMws ?? []
-	].filter(Boolean);
-}
-/**
-* `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)})`;
-}
-/**
-* Build a preHandler that enforces field-write permissions on the request body.
-*
-* Auto-CRUD's create/update routes get this for free via `BodySanitizer.sanitize()`
-* inside `BaseController`. Custom routes (`config.routes`, presets, action endpoints)
-* never went through that path — so a host that declared
-* `fields: { role: fields.writableBy(['admin']) }` and a custom
-* `POST /users/promote` happily accepted `{ role: 'admin' }` from any caller.
-*
-* This preHandler closes that gap. It applies ONLY the `applyFieldWritePermissions`
-* step — no `SYSTEM_FIELDS` strip, no `fieldRules` strip — because custom-route
-* bodies don't necessarily mirror the resource's adapter shape, and we'd
-* generate surprising 403s by enforcing rules tied to that shape.
-*
-* Returns `null` when the resource has no field permissions configured — the
-* caller should then skip wiring it into the preHandler chain.
-*/
-function buildFieldWritePreHandler(fieldPermissions, policy = DEFAULT_FIELD_WRITE_DENIAL_POLICY) {
-	if (!fieldPermissions || Object.keys(fieldPermissions).length === 0) return null;
-	return async (request, _reply) => {
-		const body = request.body;
-		if (!body || typeof body !== "object" || Array.isArray(body)) return;
-		const scope = request.scope ?? PUBLIC_SCOPE;
-		if (isElevated(scope)) return;
-		const { body: filtered, deniedFields } = applyFieldWritePermissions(body, fieldPermissions, resolveEffectiveRoles(getUserRoles(request.user), isMember(scope) ? scope.orgRoles : []));
-		if (deniedFields.length > 0 && policy === "reject") throw new ForbiddenError(`Not permitted to write field${deniedFields.length === 1 ? "" : "s"}: ${deniedFields.join(", ")}`);
-		request.body = filtered;
-	};
-}
-/**
-* True for HTTP methods that carry a request body and should run the
-* field-write preHandler. GET/DELETE/HEAD/OPTIONS skip enforcement.
-*/
-function methodCarriesBody(method) {
-	const m = method.toUpperCase();
-	return m === "POST" || m === "PUT" || m === "PATCH";
-}
-/**
-* 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) {
-	try {
-		fastify.route(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
-export { buildRequestScopeProjection as C, sendControllerResponse as S, createCrudHandlers as _, buildAuthMiddlewareForPermissions as a, getControllerContext as b, buildPipelineHandler as c, methodCarriesBody as d, resolvePipelineSteps as f, tryRegisterRoute as g, selectPluginMw as h, buildAuthMiddleware as i, buildPreHandlerChain as l, resolveRouterPluginMw as m, buildActionPipelineHandler as n, buildCrudPermissionMw as o, resolveRoutePreHandlers as p, buildArcDecorator as r, buildFieldWritePreHandler as s, buildActionPermissionMw as t, buildRateLimitConfig as u, createFastifyHandler as v, BodySanitizer as w, getControllerScope as x, createRequestContext as y };