@classytic/arc 2.19.0 → 2.21.0

package/dist/{core-Ba-6Sue6.mjs → core-DZ6Xe1jR.mjs}

@@ -1,18 +1,57 @@
-import { s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-gaEeMlz-.mjs";
+import { s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-DNre0wRg.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { r as ForbiddenError } from "./errors-DkO8Nk6-.mjs";
 import { b as isElevated, n as PUBLIC_SCOPE, x as isMember } from "./types-bHblZ9YN.mjs";
-import { p as assertValidConfig, x as getDefaultCrudSchemas } from "./utils-C6QQ9-hd.mjs";
-import { d as DEFAULT_FIELD_WRITE_DENIAL_POLICY, t as BaseController } from "./BaseController-Dy6EQHjM.mjs";
-import { F as applyFieldWritePermissions, L as resolveEffectiveRoles } from "./permissions-BPB1xqGf.mjs";
+import { M as assertValidConfig, l as getDefaultCrudSchemas } from "./utils-CO8a3B_1.mjs";
+import { d as DEFAULT_FIELD_WRITE_DENIAL_POLICY, t as BaseController } from "./BaseController-BnLYgE9A.mjs";
+import { a as selectPluginMw, c as buildPreHandlerChain, f as buildArcDecorator, i as resolveRouterPluginMw, l as resolveRoutePreHandlers, n as buildRateLimitConfig, r as buildRouteConfig, s as buildCrudPermissionMw, t as tryRegisterRoute, u as buildAuthMiddleware } from "./registerRoute-oGAl0oA8.mjs";
+import { I as applyFieldWritePermissions, R as resolveEffectiveRoles } from "./permissions-BJMuKMl7.mjs";
 import { t as getUserRoles } from "./types-XTApa8b6.mjs";
+import { t as applyPresets } from "./presets-gw0ciIUD.mjs";
 import { n as convertRouteSchema, t as convertOpenApiSchemas } from "./schemaConverter-U0MnO9vd.mjs";
 import { i as pipeUIMessageStreamToReply, r as isReadableStream } from "./streaming-BQcW6_Kq.mjs";
-import { a as createCrudHandlers, d as buildRequestScopeProjection, i as resolvePipelineSteps, o as createFastifyHandler, r as buildPipelineHandler, s as createRequestContext, t as resolveActionPermission } from "./actionPermissions-D7NGwcAR.mjs";
-import { a as selectPluginMw, c as buildPreHandlerChain, f as buildArcDecorator, i as resolveRouterPluginMw, l as resolveRoutePreHandlers, n as buildRateLimitConfig, r as buildRouteConfig, s as buildCrudPermissionMw, t as tryRegisterRoute, u as buildAuthMiddleware } from "./registerRoute-BdV8DDwU.mjs";
-import { t as applyPresets } from "./presets-BtyFwTO4.mjs";
 import { t as hasEvents } from "./typeGuards-C9KXUly6.mjs";
-import { t as pluralize } from "./pluralize-DccFV9R7.mjs";
+import { a as createCrudHandlers, d as buildRequestScopeProjection, i as resolvePipelineSteps, o as createFastifyHandler, r as buildPipelineHandler, s as createRequestContext, t as resolveActionPermission } from "./actionPermissions-ze70xXJi.mjs";
+import { t as pluralize } from "./pluralize-BhrgwZb9.mjs";
+//#region src/core/middlewares/fieldWrite.ts
+/**
+* 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";
+}
+//#endregion
 //#region src/core/aggregation/defineAggregation.ts
 /**
 * Declare a single resource aggregation. Exported configs flow into
@@ -59,45 +98,6 @@ function defineAggregation(config) {
 	return config;
 }
 //#endregion
-//#region src/core/middlewares/fieldWrite.ts
-/**
-* 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";
-}
-//#endregion
 //#region src/core/createCrudRouter.ts
 /**
 * Mount custom routes (from presets or user-defined `routes`) on Fastify.
@@ -177,7 +177,7 @@ function createCustomRoutes(fastify, routes, controller, options) {
 				}
 				return result;
 			} : handler,
-			...buildRouteConfig(rateLimitConfig, extensions)
+			...buildRouteConfig(route.rateLimit !== void 0 ? buildRateLimitConfig(route.rateLimit) : rateLimitConfig, extensions)
 		}, {
 			resourceName,
 			op: opName
@@ -949,6 +949,42 @@ function computeHasCrudRoutes(config) {
 	const disabled = new Set(config.disabledRoutes ?? []);
 	return !config.disableDefaultRoutes && CRUD_OPERATIONS.some((op) => !disabled.has(op));
 }
+const WRITE_OPERATIONS = /* @__PURE__ */ new Set([
+	"create",
+	"update",
+	"delete"
+]);
+/**
+* Public-by-omission CRUD diagnostic (post-preset).
+*
+* An omitted CRUD permission mounts the route with NO permission
+* middleware at all — unlike custom routes and actions, which fail boot
+* without one. That asymmetry silently shipped unauthenticated writes
+* (`permissions: readOnly()` pre-2.20 being the canonical victim).
+*
+* Runs against `resolvedConfig` — never the raw user config — so
+* permissions injected by presets (ownedByUser, multiTenant policy
+* wiring, ...) count as gates and don't false-positive.
+*
+* Severity ladder:
+*   - `warn` when any enabled WRITE op (create/update/delete) is ungated —
+*     this is real exposure the host must acknowledge.
+*   - `info` when only reads are ungated — public catalogs
+*     (`referenceData: true`) are a legitimate shape, but the host should
+*     still state intent with `permissions.fullPublic()` / `allowPublic()`.
+*/
+function collectUngatedCrudDiagnostics(config) {
+	if (config.disableDefaultRoutes) return [];
+	const disabled = new Set(config.disabledRoutes ?? []);
+	const permissions = config.permissions ?? {};
+	const ungated = CRUD_OPERATIONS.filter((op) => !disabled.has(op) && typeof permissions[op] !== "function");
+	if (ungated.length === 0) return [];
+	return [{
+		severity: ungated.some((op) => WRITE_OPERATIONS.has(op)) ? "warn" : "info",
+		code: "crud-public-by-omission",
+		message: `[Arc] Resource '${config.name}' mounts ${ungated.length} CRUD route(s) with no permission gate: ${ungated.join(", ")}.\nAn omitted permission mounts the route WITHOUT auth. State intent explicitly:\n  permissions: permissions.fullPublic()     // intentionally public\n  permissions: permissions.authenticated()  // require auth on every op\n  permissions: { ${ungated[0]}: requireAuth(), ... }  // per-operation`
+	}];
+}
 //#endregion
 //#region src/registry/resolveTenantPurge.ts
 const DEFAULT_PRIORITY = 100;
@@ -1032,7 +1068,10 @@ function buildGeneratedCrudSchemas(openApi, customSchemas) {
 		for (const [op, customSchema] of Object.entries(customSchemas)) {
 			const key = op;
 			const converted = convertRouteSchema(customSchema);
-			schemas[key] = schemas[key] ? deepMergeSchemas(schemas[key], converted) : converted;
+			schemas[key] = schemas[key] ? {
+				...schemas[key],
+				...converted
+			} : converted;
 		}
 	}
 	return schemas;
@@ -1102,7 +1141,7 @@ function deepMergeSchemas(base, override) {
 	if (!override) return base;
 	if (!base) return override;
 	const result = { ...base };
-	for (const [key, value] of Object.entries(override)) if (Array.isArray(value) && Array.isArray(result[key])) result[key] = [...new Set([...result[key], ...value])];
+	for (const [key, value] of Object.entries(override)) if (Array.isArray(value) && Array.isArray(result[key])) result[key] = [.../* @__PURE__ */ new Set([...result[key], ...value])];
 	else if (value && typeof value === "object" && !Array.isArray(value)) result[key] = deepMergeSchemas(result[key], value);
 	else result[key] = value;
 	return result;
@@ -1247,7 +1286,7 @@ function buildResourcePlugin(resource) {
 				extensions: resource.extensions
 			});
 			if (resource.actions && Object.keys(resource.actions).length > 0) {
-				const { createActionRouter } = await import("./createActionRouter-B_WzBFyf.mjs").then((n) => n.n);
+				const { createActionRouter } = await import("./createActionRouter-BWMDW-dL.mjs").then((n) => n.n);
 				createActionRouter(typedInstance, {
 					...normalizeActionsToRouterConfig(resource.actions, resource.actionPermissions, resource.tag, resource.permissions, resource.name, typedInstance.log),
 					resourceName: resource.name,
@@ -1262,7 +1301,7 @@ function buildResourcePlugin(resource) {
 				});
 			}
 			if (resource.aggregations && Object.keys(resource.aggregations).length > 0) {
-				const [{ createAggregationRouter }, { adapterSupportsAggregate, ArcAggregationConfigError }] = await Promise.all([import("./createAggregationRouter-B_G_nIjm.mjs"), import("./validate-CRcaWzp2.mjs").then((n) => n.r)]);
+				const [{ createAggregationRouter }, { adapterSupportsAggregate, ArcAggregationConfigError }] = await Promise.all([import("./createAggregationRouter-l5mNdYrZ.mjs"), import("./validate-C2mGgSXg.mjs").then((n) => n.r)]);
 				const repoForAgg = resource.controller?.repository ?? resource.repository;
 				if (!adapterSupportsAggregate(repoForAgg)) {
 					const undispatchable = Object.entries(resource.aggregations).filter(([, cfg]) => !cfg.materialized).map(([name]) => name);
@@ -1718,7 +1757,7 @@ function mergeUserOpenApiOverrides(openApiSchemas, userOverrides) {
 * call) since the set is fixed and the cost of re-allocating is a
 * pointless boot tax for hosts with hundreds of resources.
 */
-const CRUD_OP_NAMES = new Set([
+const CRUD_OP_NAMES = /* @__PURE__ */ new Set([
 	"create",
 	"update",
 	"delete",
@@ -1738,7 +1777,42 @@ function validateDefineResourceConfig(config) {
 	validatePermissionsShape(config);
 	validateCustomRoutePermissions(config);
 	validateActionsShape(config);
-	return collectRedundantFieldRuleDiagnostics(config);
+	return [...collectRedundantFieldRuleDiagnostics(config), ...collectReservedFilterNameDiagnostics(config)];
+}
+/**
+* Query-string param names arc's `QueryParser` reserves for
+* pagination/projection (`q.after ?? q.cursor` is the keyset cursor). A
+* document field with one of these names can never be filtered via the query
+* string — the parser consumes the name before it reaches the filter map — and
+* the same reservation flows into the MCP list-tool schema. Silent pre-2.20;
+* now surfaced.
+*/
+const RESERVED_QUERY_PARAMS = /* @__PURE__ */ new Set([
+	"page",
+	"limit",
+	"cursor",
+	"after",
+	"sort",
+	"search",
+	"select",
+	"populate"
+]);
+/**
+* Warn when a declared filterable field's NAME collides with a reserved query
+* param. Verified empirically (tests/e2e/reserved-field-name-collision.test.ts):
+* a field named `cursor`/`page` is silently unfilterable. Boot diagnostic, not
+* a hard error — the resource still works, the field just isn't query-filterable.
+*/
+function collectReservedFilterNameDiagnostics(config) {
+	const filterable = config.schemaOptions?.filterableFields;
+	if (!filterable) return [];
+	const collisions = filterable.filter((f) => RESERVED_QUERY_PARAMS.has(f));
+	if (collisions.length === 0) return [];
+	return [{
+		severity: "warn",
+		code: "filter-field-reserved-name",
+		message: `[Arc] Resource '${config.name}': filterable field(s) [${collisions.join(", ")}] collide with reserved query params (page, limit, cursor, after, sort, search, select, populate). The query parser consumes these names for pagination/projection, so filtering by them via the query string — and via the MCP list tool — will NOT work. Rename the field(s), or drop them from \`filterableFields\` if the collision is intended.`
+	}];
 }
 /** Permissions must be `PermissionCheck` functions, not arbitrary values. */
 function validatePermissionsShape(config) {
@@ -1820,6 +1894,7 @@ function defineResource(config) {
 	const configWithId = resolveIdField(normalisedConfig, repository);
 	const resolvedConfig = applyPresetsAndAutoInject(configWithId);
 	const hasCrudRoutes = computeHasCrudRoutes(resolvedConfig);
+	if (!normalisedConfig.skipValidation) diagnostics = diagnostics.concat(collectUngatedCrudDiagnostics(resolvedConfig));
 	const narrowedConfig = resolvedConfig;
 	const narrowedAdapter = configWithId.adapter;
 	const controller = resolveOrAutoCreateController(narrowedConfig, narrowedAdapter, repository, hasCrudRoutes);
@@ -1838,6 +1913,58 @@ function defineResource(config) {
 	return resource;
 }
 //#endregion
+//#region src/core/defineResource/seams.ts
+/** Plain object test — literals only; class instances must replace, not merge. */
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+/** Recursive plain-object merge; nested arrays REPLACE (they're value lists). */
+function mergePlain(base, next) {
+	const out = { ...base };
+	for (const [key, value] of Object.entries(next)) {
+		if (value === void 0) continue;
+		const existing = out[key];
+		out[key] = isPlainObject(existing) && isPlainObject(value) ? mergePlain(existing, value) : value;
+	}
+	return out;
+}
+/**
+* Canonical slot-aware merge of a base resource config with host seams.
+* Later seams win over earlier ones; `undefined` values never clobber.
+*
+* Merge semantics (value-driven — no per-slot registry to drift):
+*
+*   - **Top-level arrays CONCAT** — `routes`, `middlewares`, `presets`,
+*     `routeGuards`, `disabledRoutes`: additive collections, base first.
+*   - **Plain objects merge recursively** — `permissions`, `actions`,
+*     `schemaOptions` (incl. `fieldRules`), `aggregations`, `customSchemas`,
+*     `fields`, `cache`, `events`: per-key composition. Arrays NESTED inside
+*     them replace (they're value lists — enums, sort specs), not concat.
+*   - **Everything else last-wins** — class instances (`adapter`,
+*     `controller`, `queryParser`), functions, scalars.
+*
+* The single `as` at the return is the one documented erasure for the
+* {@link AdapterLike}-widened seam slots — inside the helper so no module
+* author ever writes one (mirrors mongokit's one-cast-at-the-boundary rule).
+*/
+function mergeResourceConfig(base, ...seams) {
+	const out = { ...base };
+	for (const seam of seams) {
+		if (!seam) continue;
+		for (const [key, value] of Object.entries(seam)) {
+			if (value === void 0) continue;
+			const existing = out[key];
+			if (Array.isArray(existing) && Array.isArray(value)) out[key] = [...existing, ...value];
+			else if (isPlainObject(existing) && isPlainObject(value)) out[key] = mergePlain(existing, value);
+			else if (Array.isArray(value)) out[key] = [...value];
+			else out[key] = value;
+		}
+	}
+	return out;
+}
+//#endregion
 //#region src/core/defineResourceVariants.ts
 /**
 * Define multiple resources from a shared base config and per-variant overrides.
@@ -1936,4 +2063,4 @@ function getEntityQuery(req) {
 	return { [getEntityIdField(req)]: id };
 }
 //#endregion
-export { defineResource as a, createCrudRouter as c, defineResourceVariants as i, createPermissionMiddleware as l, getEntityIdField as n, ResourceDefinition as o, getEntityQuery as r, defineAction as s, getEntityId as t, defineAggregation as u };
+export { mergeResourceConfig as a, defineAction as c, defineAggregation as d, defineResourceVariants as i, createCrudRouter as l, getEntityIdField as n, defineResource as o, getEntityQuery as r, ResourceDefinition as s, getEntityId as t, createPermissionMiddleware as u };

package/dist/{createActionRouter-B_WzBFyf.mjs → createActionRouter-BWMDW-dL.mjs}

@@ -1,9 +1,9 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
-import "./constants-gaEeMlz-.mjs";
+import "./constants-DNre0wRg.mjs";
 import { f as createError } from "./errors-DkO8Nk6-.mjs";
-import { i as resolvePipelineSteps, n as buildActionPipelineHandler, u as sendControllerResponse } from "./actionPermissions-D7NGwcAR.mjs";
-import { a as selectPluginMw, c as buildPreHandlerChain, d as buildAuthMiddlewareForPermissions, f as buildArcDecorator, i as resolveRouterPluginMw, n as buildRateLimitConfig, o as buildActionPermissionMw, r as buildRouteConfig, t as tryRegisterRoute } from "./registerRoute-BdV8DDwU.mjs";
-import { n as schemaIRToJsonSchemaBranch, t as normalizeSchemaIR } from "./schemaIR-D1MJwqmp.mjs";
+import { a as selectPluginMw, c as buildPreHandlerChain, d as buildAuthMiddlewareForPermissions, f as buildArcDecorator, i as resolveRouterPluginMw, n as buildRateLimitConfig, o as buildActionPermissionMw, r as buildRouteConfig, t as tryRegisterRoute } from "./registerRoute-oGAl0oA8.mjs";
+import { i as resolvePipelineSteps, n as buildActionPipelineHandler, u as sendControllerResponse } from "./actionPermissions-ze70xXJi.mjs";
+import { n as schemaIRToJsonSchemaBranch, t as normalizeSchemaIR } from "./schemaIR-ajetw3Fv.mjs";
 //#region src/core/createActionRouter.ts
 var createActionRouter_exports = /* @__PURE__ */ __exportAll({
 	buildActionBodySchema: () => buildActionBodySchema,

package/dist/{createAggregationRouter-B_G_nIjm.mjs → createAggregationRouter-l5mNdYrZ.mjs}

@@ -1,7 +1,7 @@
 import { f as createError, l as UnauthorizedError, r as ForbiddenError } from "./errors-DkO8Nk6-.mjs";
-import { a as selectPluginMw, c as buildPreHandlerChain, f as buildArcDecorator, i as resolveRouterPluginMw, n as buildRateLimitConfig, u as buildAuthMiddleware } from "./registerRoute-BdV8DDwU.mjs";
-import { n as validateAggregations } from "./validate-CRcaWzp2.mjs";
-import { t as buildAggregationHandler } from "./buildHandler-B0qvAguf.mjs";
+import { a as selectPluginMw, c as buildPreHandlerChain, f as buildArcDecorator, i as resolveRouterPluginMw, n as buildRateLimitConfig, u as buildAuthMiddleware } from "./registerRoute-oGAl0oA8.mjs";
+import { n as validateAggregations } from "./validate-C2mGgSXg.mjs";
+import { t as buildAggregationHandler } from "./buildHandler-D_2ULWxZ.mjs";
 //#region src/core/aggregation/createAggregationRouter.ts
 /**
 * Register one Fastify route per aggregation. No-op when the map is
@@ -39,7 +39,8 @@ function registerOne(fastify, normalized, ctx) {
 	const authMw = buildAuthMiddleware(fastify, config.permissions);
 	const permissionFn = config.permissions;
 	const permissionMw = async (req, _reply) => {
-		const raw = await permissionFn(buildPermissionContextLite(req, normalized.name));
+		const ctx = buildPermissionContextLite(req, normalized.name);
+		const raw = await permissionFn(ctx);
 		if (!normalizePermissionGranted(raw)) {
 			const status = req.user ? 403 : 401;
 			const reason = normalizePermissionReason(raw);