@classytic/arc 2.14.0 → 2.14.2

package/dist/{BaseController-DX_T-bDB.mjs → BaseController-Dv60tU83.mjs}

@@ -283,6 +283,36 @@ var BodySanitizer = class {
 	}
 };
 //#endregion
+//#region src/core/fieldRulePredicates.ts
+/**
+* True when the field is allowed to appear in client-readable surfaces
+* (response payloads, `select=` whitelists, `_distinct` queries).
+*
+* Mirror of every read-side gate. Don't reach for `rules.systemManaged`
+* here — that's a write rule.
+*/
+function isFieldReadable(rule) {
+	if (!rule) return true;
+	return rule.hidden !== true;
+}
+/**
+* The set of field names blocked from read-side surfaces (used by
+* `QueryResolver.sanitizeSelectAny` and `BaseCrudController._distinct`).
+*
+* Returns `null` (not an empty array) when there are no rules to apply,
+* so call-sites can early-out without creating empty allocations.
+*/
+function collectReadBlockedFields(schemaOptions) {
+	const fieldRules = schemaOptions?.fieldRules;
+	if (!fieldRules) return null;
+	const blocked = /* @__PURE__ */ new Set();
+	for (const [field, rule] of Object.entries(fieldRules)) {
+		if (!rule) continue;
+		if (!isFieldReadable(rule)) blocked.add(field);
+	}
+	return blocked.size > 0 ? blocked : null;
+}
+//#endregion
 //#region src/core/QueryResolver.ts
 /**
 * QueryResolver - Composable query resolution logic extracted from BaseController.
@@ -419,10 +449,15 @@ var QueryResolver = class {
 		});
 		return sanitized.length > 0 ? sanitized : void 0;
 	}
-	/** Get blocked fields from schema options */
+	/**
+	* Read-side allowlist gate for `select=` / `populate=`.
+	*
+	* Only `hidden: true` blocks. `systemManaged` is a *write* rule and
+	* doesn't gate visibility — see `core/fieldRulePredicates.ts`.
+	*/
 	getBlockedFields(schemaOptions) {
-		const fieldRules = schemaOptions.fieldRules ?? {};
-		return Object.entries(fieldRules).filter(([, rules]) => rules.systemManaged || rules.hidden).map(([field]) => field);
+		const blocked = collectReadBlockedFields(schemaOptions);
+		return blocked ? Array.from(blocked) : [];
 	}
 };
 //#endregion
@@ -873,15 +908,16 @@ var BaseCrudController = class {
 		};
 	}
 	/**
-	* True when `field` is safe to expose via `_distinct`. Mirrors the
-	* `select` allowlist — fields marked `hidden` or `systemManaged` in
-	* `schemaOptions.fieldRules` are NOT exposed (would leak password
-	* hashes, internal flags, etc).
+	* True when `field` is safe to expose via `_distinct`.
+	*
+	* Read-side gate only — only `hidden: true` blocks. `systemManaged`
+	* is a *write* rule (clients can't PATCH the value); the field is
+	* still in every list response, so blocking `_distinct` adds nothing
+	* but inconvenience. See `core/fieldRulePredicates.ts` for the
+	* canonical predicate shared with `QueryResolver`.
 	*/
 	isFieldExposedForRead(field) {
-		const rules = this.schemaOptions.fieldRules?.[field];
-		if (!rules) return true;
-		return !(rules.hidden || rules.systemManaged);
+		return isFieldReadable(this.schemaOptions.fieldRules?.[field]);
 	}
 	/** Execute list query through hooks (extracted for cache revalidation) */
 	async executeListQuery(options, req) {
@@ -1353,4 +1389,4 @@ function TreeMixin(Base) {
 */
 var BaseController = class extends SoftDeleteMixin(TreeMixin(SlugMixin(BulkMixin(BaseCrudController)))) {};
 //#endregion
-export { BulkMixin as a, BodySanitizer as c, SlugMixin as i, AccessControl as l, TreeMixin as n, BaseCrudController as o, SoftDeleteMixin as r, QueryResolver as s, BaseController as t };
+export { BulkMixin as a, collectReadBlockedFields as c, AccessControl as d, SlugMixin as i, isFieldReadable as l, TreeMixin as n, BaseCrudController as o, SoftDeleteMixin as r, QueryResolver as s, BaseController as t, BodySanitizer as u };

package/dist/auth/index.d.mts

@@ -1,4 +1,4 @@
-import { Rt as AuthHelpers, zt as AuthPluginOptions } from "../index-BtW7qYwa.mjs";
+import { Rt as AuthHelpers, zt as AuthPluginOptions } from "../index-Dwc0orNd.mjs";
 import { c as PermissionCheck } from "../fields-COhcH3fk.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-BD5nw6St.mjs";
 import { a as SessionManagerOptions, c as createSessionManager, i as SessionData, n as MemorySessionStoreOptions, o as SessionManagerResult, r as SessionCookieOptions, s as SessionStore, t as MemorySessionStore } from "../sessionManager-C4Le_UB3.mjs";
@@ -191,4 +191,81 @@ interface BetterAuthOpenApiOptions {
  */
 declare function extractBetterAuthOpenApi(authApi: Record<string, unknown>, options?: BetterAuthOpenApiOptions): ExternalOpenApiPaths;
 //#endregion
-export { type AuthPluginOptions, type BetterAuthAdapterOptions, type BetterAuthAdapterResult, type BetterAuthHandler, type BetterAuthOpenApiOptions, MemorySessionStore, type MemorySessionStoreOptions, type SessionCookieOptions, type SessionData, type SessionManagerOptions, type SessionManagerResult, type SessionStore, _default as authPlugin, authPlugin as authPluginFn, createBetterAuthAdapter, createSessionManager, extractBetterAuthOpenApi };
+//#region src/auth/trustedOrigins.d.ts
+/**
+ * `trustedOrigins` ↔ CORS-allowlist union helper.
+ *
+ * Better Auth's `trustedOrigins` (CSRF / origin guard) and Fastify's CORS
+ * `origin` allowlist are independent — a request that survives CORS still
+ * has to pass BA's origin check. When they drift, sign-in throws
+ * `Invalid origin` 401s that don't surface CORS errors in the network
+ * panel.
+ *
+ * Hosts have written the same union by hand in every app, with the same
+ * three corner cases (array → union with canonical URL, `true` → `["*"]`,
+ * `false`/undefined → just the canonical URL). This helper centralises
+ * that rule so a future change happens in one place.
+ *
+ * @example
+ * ```ts
+ * import { betterAuth } from "better-auth";
+ * import { mirrorTrustedOriginsFromCors } from "@classytic/arc/auth";
+ * import config from "#config";
+ *
+ * export const auth = betterAuth({
+ *   secret: config.betterAuth.secret,
+ *   baseURL: process.env.BETTER_AUTH_URL,
+ *   trustedOrigins: mirrorTrustedOriginsFromCors({
+ *     corsOrigins: config.cors.origins,    // string[] | true | false
+ *     canonicalUrl: config.frontend.url,   // FRONTEND_URL — used for email link templates
+ *   }),
+ *   // ...
+ * });
+ * ```
+ *
+ * Why both inputs:
+ * - `canonicalUrl` is the single URL embedded in BA's email templates
+ *   (invitation-accept, password-reset). It MUST be in `trustedOrigins`.
+ * - `corsOrigins` is the browser allowlist. Every entry there is a real
+ *   FE host that may attempt sign-in; missing one yields the silent 401.
+ *
+ * The union dedupes — passing `canonicalUrl` already in `corsOrigins` is
+ * fine and won't duplicate the entry.
+ */
+/**
+ * Shape arc's CORS plugin and most apps use:
+ *   - `string[]` — explicit allowlist
+ *   - `true` — wildcard (`*`)
+ *   - `false` / `undefined` — no extra origins beyond `canonicalUrl`
+ *
+ * Other shapes (regex, predicate function) aren't supported here — pass
+ * an explicit array if you have dynamic logic upstream.
+ */
+type CorsOriginsConfig = readonly string[] | boolean | undefined;
+interface MirrorTrustedOriginsOptions {
+  /**
+   * CORS allowlist as configured for Fastify's CORS plugin.
+   * Most apps read this from a `CORS_ORIGINS` env var (`*` → `true`,
+   * comma-separated → `string[]`).
+   */
+  corsOrigins: CorsOriginsConfig;
+  /**
+   * The single canonical FE URL used for email-link templates
+   * (invitation-accept, password-reset). Must be a trusted origin.
+   * Typically `FRONTEND_URL`.
+   */
+  canonicalUrl: string;
+}
+/**
+ * Compute BA's `trustedOrigins` as the union of `canonicalUrl` and the
+ * CORS allowlist.
+ *
+ * Returns:
+ *   - `["*"]` when `corsOrigins === true` (wildcard CORS).
+ *   - `[canonicalUrl, ...corsOrigins]` deduped when `corsOrigins` is an
+ *     array.
+ *   - `[canonicalUrl]` when `corsOrigins` is `false` / `undefined`.
+ */
+declare function mirrorTrustedOriginsFromCors(options: MirrorTrustedOriginsOptions): string[];
+//#endregion
+export { type AuthPluginOptions, type BetterAuthAdapterOptions, type BetterAuthAdapterResult, type BetterAuthHandler, type BetterAuthOpenApiOptions, type CorsOriginsConfig, MemorySessionStore, type MemorySessionStoreOptions, type MirrorTrustedOriginsOptions, type SessionCookieOptions, type SessionData, type SessionManagerOptions, type SessionManagerResult, type SessionStore, _default as authPlugin, authPlugin as authPluginFn, createBetterAuthAdapter, createSessionManager, extractBetterAuthOpenApi, mirrorTrustedOriginsFromCors };

package/dist/auth/index.mjs

@@ -1029,4 +1029,22 @@ function createSessionManager(options) {
 	};
 }
 //#endregion
-export { MemorySessionStore, authPlugin_default as authPlugin, authPlugin as authPluginFn, createBetterAuthAdapter, createSessionManager, extractBetterAuthOpenApi };
+//#region src/auth/trustedOrigins.ts
+/**
+* Compute BA's `trustedOrigins` as the union of `canonicalUrl` and the
+* CORS allowlist.
+*
+* Returns:
+*   - `["*"]` when `corsOrigins === true` (wildcard CORS).
+*   - `[canonicalUrl, ...corsOrigins]` deduped when `corsOrigins` is an
+*     array.
+*   - `[canonicalUrl]` when `corsOrigins` is `false` / `undefined`.
+*/
+function mirrorTrustedOriginsFromCors(options) {
+	const { corsOrigins, canonicalUrl } = options;
+	if (corsOrigins === true) return ["*"];
+	if (!corsOrigins) return [canonicalUrl];
+	return Array.from(new Set([canonicalUrl, ...corsOrigins]));
+}
+//#endregion
+export { MemorySessionStore, authPlugin_default as authPlugin, authPlugin as authPluginFn, createBetterAuthAdapter, createSessionManager, extractBetterAuthOpenApi, mirrorTrustedOriginsFromCors };

package/dist/{buildHandler-olo-gt94.mjs → buildHandler-jSZ6Fdvi.mjs}

@@ -195,10 +195,10 @@ function assertBucketFieldAllowed(input) {
 	if (dot > 0) {
 		const a = field.slice(0, dot);
 		if (lookupAliases.has(a)) return;
-		if (blockedFields.has(a)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" dateBucket "${alias}" references field "${field}" whose root "${a}" is marked hidden or systemManaged in schemaOptions.fieldRules. Bucketing on hidden fields would leak temporal info.`);
+		if (blockedFields.has(a)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" dateBucket "${alias}" references field "${field}" whose root "${a}" is blocked from aggregation (\`hidden: true\` or \`aggregable: false\` in schemaOptions.fieldRules). Bucketing hidden fields would leak temporal info.`);
 		return;
 	}
-	if (blockedFields.has(field)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" dateBucket "${alias}" references field "${field}", but the field is marked hidden or systemManaged in schemaOptions.fieldRules. Bucketing on hidden fields would leak temporal info.`);
+	if (blockedFields.has(field)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" dateBucket "${alias}" references field "${field}", but the field is blocked from aggregation (\`hidden: true\` or \`aggregable: false\` in schemaOptions.fieldRules). Bucketing hidden fields would leak temporal info.`);
 }
 /**
 * Map arc's declarative knobs onto repo-core's portable `AggExecutionHints`.
@@ -307,13 +307,34 @@ function collectLookupAliases(lookups) {
 	for (const lookup of lookups) aliases.add(lookup.as ?? lookup.from);
 	return aliases;
 }
+/**
+* Collect fields that aggregation MUST NOT reference.
+*
+* Default rule: only `hidden: true` blocks. `hidden` means the field is
+* omitted from list/get responses, so exposing it via aggregation would
+* leak data the client can't otherwise see. `systemManaged` is a write
+* rule (server stamps the value, clients can't PATCH it) — those fields
+* are still visible per-row, so aggregating them leaks nothing.
+*
+* Two opt-in overrides via `ArcFieldRule.aggregable`:
+*   - `aggregable: false` — explicit deny on a visible field (rare; use
+*     when the per-row value is fine but the across-row distribution is
+*     itself sensitive).
+*   - `aggregable: true` — explicit allow, even on a `hidden` field
+*     (escape hatch — caller asserts cardinality leak isn't a concern).
+*/
 function collectBlockedFields(schemaOptions) {
 	const blocked = /* @__PURE__ */ new Set();
 	const fieldRules = schemaOptions?.fieldRules;
 	if (!fieldRules) return blocked;
 	for (const [field, rules] of Object.entries(fieldRules)) {
 		if (!rules) continue;
-		if (rules.hidden || rules.systemManaged) blocked.add(field);
+		if (rules.aggregable === true) continue;
+		if (rules.aggregable === false) {
+			blocked.add(field);
+			continue;
+		}
+		if (rules.hidden) blocked.add(field);
 	}
 	return blocked;
 }
@@ -348,10 +369,10 @@ function assertFieldAllowed(context, ref, input) {
 	if (dot > 0) {
 		const alias = ref.slice(0, dot);
 		if (lookupAliases.has(alias)) return;
-		if (blockedFields.has(alias)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" references field "${ref}" in ${context} whose root "${alias}" is marked hidden or systemManaged in schemaOptions.fieldRules. Aggregating hidden fields would leak cardinality information.`);
+		if (blockedFields.has(alias)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" references field "${ref}" in ${context} whose root "${alias}" is blocked from aggregation (\`hidden: true\` or \`aggregable: false\` in schemaOptions.fieldRules). Aggregating hidden fields would leak cardinality information.`);
 		return;
 	}
-	if (blockedFields.has(ref)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" references field "${ref}" in ${context}, but the field is marked hidden or systemManaged in schemaOptions.fieldRules. Aggregating hidden fields would leak cardinality information.`);
+	if (blockedFields.has(ref)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" references field "${ref}" in ${context}, but the field is blocked from aggregation (\`hidden: true\` or \`aggregable: false\` in schemaOptions.fieldRules). Aggregating hidden fields would leak cardinality information.`);
 }
 function extractTenantFilter(tenantOptions) {
 	const out = {};
@@ -539,13 +560,73 @@ function parseDateRange(query, field) {
 	};
 }
 /**
+* Bracket-syntax operator shorthand → canonical Mongo operator. Mirrors
+* the `operators` map in `ArcQueryParser` so the aggregation route emits
+* the same shape the CRUD list route produces. Aggregations don't run
+* through the resource-level QueryParser (they have their own URL→IR
+* compile path), so this translation has to happen in arc itself —
+* downstream kits' filter compilers expect canonical `$gte/$lte/$in/...`
+* keys, not bare `gte/lte/in/...` shorthand.
+*/
+const OPERATOR_SHORTHAND = {
+	eq: "$eq",
+	ne: "$ne",
+	gt: "$gt",
+	gte: "$gte",
+	lt: "$lt",
+	lte: "$lte",
+	in: "$in",
+	nin: "$nin",
+	like: "$regex",
+	contains: "$regex",
+	regex: "$regex",
+	exists: "$exists",
+	size: "$size",
+	type: "$type"
+};
+const SHORTHAND_RANGE_OPS = new Set([
+	"gt",
+	"gte",
+	"lt",
+	"lte"
+]);
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+function tryCoerceDate(v) {
+	if (typeof v !== "string" || !ISO_DATE_RE.test(v)) return v;
+	const d = new Date(v);
+	return Number.isNaN(d.getTime()) ? v : d;
+}
+/**
+* Translate a qs-parsed nested-operator object (`{ field: { gte, lte } }`)
+* into Mongo-shape (`{ field: { $gte: Date, $lte: Date } }`). Only fires
+* when EVERY key is a known shorthand operator — leaves user-data
+* objects untouched so callers can still equality-match on a stored
+* sub-document.
+*/
+function expandShorthandOperators(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+	const nested = value;
+	const keys = Object.keys(nested);
+	if (keys.length === 0) return value;
+	if (!keys.every((k) => !k.startsWith("$") && OPERATOR_SHORTHAND[k] !== void 0)) return value;
+	const expanded = {};
+	for (const [op, opVal] of Object.entries(nested)) {
+		const mongoOp = OPERATOR_SHORTHAND[op];
+		if (!mongoOp) continue;
+		expanded[mongoOp] = SHORTHAND_RANGE_OPS.has(op) ? tryCoerceDate(opVal) : opVal;
+	}
+	return expanded;
+}
+/**
 * Strip control params (page/limit/sort/select/...) and the resource-
 * dispatch verbs from the query, leaving only filter predicates the
-* caller used to narrow the aggregation.
+* caller used to narrow the aggregation. Bracket-syntax operator
+* shorthand (`createdAt[gte]=...`) gets translated to canonical Mongo-
+* shape here so kits don't have to reimplement the URL grammar — same
+* contract `ArcQueryParser` enforces for the CRUD list route.
 *
 * The resulting record is shallow-merged into the AggRequest filter
-* via `compileAggRequest`. Bracket-syntax keys (`createdAt[gte]`) are
-* preserved — the kit's filter compiler handles them.
+* via `compileAggRequest`.
 */
 function extractCallerFilter(query) {
 	const out = {};
@@ -564,7 +645,7 @@ function extractCallerFilter(query) {
 	for (const [key, value] of Object.entries(query)) {
 		if (reserved.has(key)) continue;
 		if (value === void 0 || value === "") continue;
-		out[key] = value;
+		out[key] = expandShorthandOperators(value);
 	}
 	return out;
 }

package/dist/cli/commands/describe.d.mts

@@ -1,4 +1,4 @@
-import { V as ResourceDefinition, ft as RouteSchemaOptions, rt as RateLimitConfig } from "../../index-BtW7qYwa.mjs";
+import { V as ResourceDefinition, ft as RouteSchemaOptions, rt as RateLimitConfig } from "../../index-Dwc0orNd.mjs";
 
 //#region src/cli/commands/describe.d.ts
 interface DescribedResource {

package/dist/cli/commands/docs.mjs

@@ -1,5 +1,5 @@
 import { t as ResourceRegistry } from "../../ResourceRegistry-CTERg_2x.mjs";
-import { t as buildOpenApiSpec } from "../../openapi-noXno2CV.mjs";
+import { t as buildOpenApiSpec } from "../../openapi-BHXhoX8O.mjs";
 import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { mkdirSync, writeFileSync } from "node:fs";

package/dist/core/index.d.mts

@@ -1,3 +1,3 @@
-import { $t as SoftDeleteMixin, B as defineResource, Ct as AggregationConfig, Dt as AggregationMaterializedResult, Et as AggregationMaterializedContext, Ot as AggregationRateLimit, Qt as SoftDeleteExt, St as AggregationCacheConfig, Tt as AggregationIndexHint, V as ResourceDefinition, Zt as BaseController, _n as BodySanitizerConfig, an as BulkMixin, bt as AggMeasureInput, cn as QueryResolver, en as TreeExt, gn as BodySanitizer, hn as ListResult, in as BulkExt, kt as AggregationsMap, ln as QueryResolverConfig, nn as SlugExt, on as BaseControllerOptions, rn as SlugMixin, sn as BaseCrudController, tn as TreeMixin, vn as AccessControl, wt as AggregationDateRangeRequirement, xt as AggMeasureShorthand, yn as AccessControlConfig } from "../index-BtW7qYwa.mjs";
-import { C as MAX_FILTER_DEPTH, D as MutationOperation, E as MUTATION_OPERATIONS, O as RESERVED_QUERY_PARAMS, S as HookPhase, T as MAX_SEARCH_LENGTH, _ as DEFAULT_TENANT_FIELD, a as getControllerScope, b as HOOK_PHASES, c as createCrudRouter, d as CRUD_OPERATIONS, f as CrudOperation, g as DEFAULT_SORT, h as DEFAULT_MAX_LIMIT, i as getControllerContext, k as SYSTEM_FIELDS, l as createPermissionMiddleware, m as DEFAULT_LIMIT, n as createFastifyHandler, o as sendControllerResponse, p as DEFAULT_ID_FIELD, r as createRequestContext, s as defineResourceVariants, t as createCrudHandlers, u as defineAggregation, v as DEFAULT_UPDATE_METHOD, w as MAX_REGEX_LENGTH, x as HookOperation, y as HOOK_OPERATIONS } from "../index-Ds61mrJE.mjs";
-export { AccessControl, AccessControlConfig, AggMeasureInput, AggMeasureShorthand, AggregationCacheConfig, AggregationConfig, AggregationDateRangeRequirement, AggregationIndexHint, AggregationMaterializedContext, AggregationMaterializedResult, AggregationRateLimit, AggregationsMap, BaseController, BaseControllerOptions, BaseCrudController, BodySanitizer, BodySanitizerConfig, BulkExt, BulkMixin, CRUD_OPERATIONS, CrudOperation, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, HOOK_OPERATIONS, HOOK_PHASES, HookOperation, HookPhase, ListResult, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, MutationOperation, QueryResolver, QueryResolverConfig, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugExt, SlugMixin, SoftDeleteExt, SoftDeleteMixin, TreeExt, TreeMixin, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineAggregation, defineResource, defineResourceVariants, getControllerContext, getControllerScope, sendControllerResponse };
+import { $t as SoftDeleteMixin, B as defineResource, Ct as AggregationConfig, Dt as AggregationMaterializedResult, Et as AggregationMaterializedContext, Ot as AggregationRateLimit, Qt as SoftDeleteExt, St as AggregationCacheConfig, Tt as AggregationIndexHint, V as ResourceDefinition, Zt as BaseController, _n as BodySanitizerConfig, an as BulkMixin, bt as AggMeasureInput, cn as QueryResolver, en as TreeExt, gn as BodySanitizer, hn as ListResult, in as BulkExt, kt as AggregationsMap, ln as QueryResolverConfig, nn as SlugExt, on as BaseControllerOptions, rn as SlugMixin, sn as BaseCrudController, tn as TreeMixin, vn as AccessControl, wt as AggregationDateRangeRequirement, xt as AggMeasureShorthand, yn as AccessControlConfig } from "../index-Dwc0orNd.mjs";
+import { A as MAX_SEARCH_LENGTH, C as DEFAULT_UPDATE_METHOD, D as HookPhase, E as HookOperation, M as MutationOperation, N as RESERVED_QUERY_PARAMS, O as MAX_FILTER_DEPTH, P as SYSTEM_FIELDS, S as DEFAULT_TENANT_FIELD, T as HOOK_PHASES, _ as CrudOperation, a as createRequestContext, b as DEFAULT_MAX_LIMIT, c as sendControllerResponse, d as getEntityQuery, f as defineResourceVariants, g as CRUD_OPERATIONS, h as defineAggregation, i as createFastifyHandler, j as MUTATION_OPERATIONS, k as MAX_REGEX_LENGTH, l as getEntityId, m as createPermissionMiddleware, n as isFieldReadable, o as getControllerContext, p as createCrudRouter, r as createCrudHandlers, s as getControllerScope, t as collectReadBlockedFields, u as getEntityIdField, v as DEFAULT_ID_FIELD, w as HOOK_OPERATIONS, x as DEFAULT_SORT, y as DEFAULT_LIMIT } from "../index-D1-Kp_dP.mjs";
+export { AccessControl, AccessControlConfig, AggMeasureInput, AggMeasureShorthand, AggregationCacheConfig, AggregationConfig, AggregationDateRangeRequirement, AggregationIndexHint, AggregationMaterializedContext, AggregationMaterializedResult, AggregationRateLimit, AggregationsMap, BaseController, BaseControllerOptions, BaseCrudController, BodySanitizer, BodySanitizerConfig, BulkExt, BulkMixin, CRUD_OPERATIONS, CrudOperation, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, HOOK_OPERATIONS, HOOK_PHASES, HookOperation, HookPhase, ListResult, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, MutationOperation, QueryResolver, QueryResolverConfig, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugExt, SlugMixin, SoftDeleteExt, SoftDeleteMixin, TreeExt, TreeMixin, collectReadBlockedFields, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineAggregation, defineResource, defineResourceVariants, getControllerContext, getControllerScope, getEntityId, getEntityIdField, getEntityQuery, isFieldReadable, sendControllerResponse };

package/dist/core/index.mjs

@@ -1,5 +1,5 @@
 import { a as DEFAULT_SORT, c as HOOK_OPERATIONS, d as MAX_REGEX_LENGTH, f as MAX_SEARCH_LENGTH, h as SYSTEM_FIELDS, i as DEFAULT_MAX_LIMIT, l as HOOK_PHASES, m as RESERVED_QUERY_PARAMS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, p as MUTATION_OPERATIONS, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS, u as MAX_FILTER_DEPTH } from "../constants-Cxde4rpC.mjs";
-import { a as BulkMixin, c as BodySanitizer, i as SlugMixin, l as AccessControl, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, s as QueryResolver, t as BaseController } from "../BaseController-DX_T-bDB.mjs";
+import { a as BulkMixin, c as collectReadBlockedFields, d as AccessControl, i as SlugMixin, l as isFieldReadable, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, s as QueryResolver, t as BaseController, u as BodySanitizer } from "../BaseController-Dv60tU83.mjs";
 import { _ as getControllerContext, g as createRequestContext, h as createFastifyHandler, m as createCrudHandlers, v as getControllerScope, y as sendControllerResponse } from "../routerShared-DrOa-26E.mjs";
-import { a as createPermissionMiddleware, i as createCrudRouter, n as defineResource, o as defineAggregation, r as ResourceDefinition, t as defineResourceVariants } from "../core-DECn6zaU.mjs";
-export { AccessControl, BaseController, BaseCrudController, BodySanitizer, BulkMixin, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, QueryResolver, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugMixin, SoftDeleteMixin, TreeMixin, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineAggregation, defineResource, defineResourceVariants, getControllerContext, getControllerScope, sendControllerResponse };
+import { a as defineResource, c as createPermissionMiddleware, i as defineResourceVariants, l as defineAggregation, n as getEntityIdField, o as ResourceDefinition, r as getEntityQuery, s as createCrudRouter, t as getEntityId } from "../core-D29kkRL5.mjs";
+export { AccessControl, BaseController, BaseCrudController, BodySanitizer, BulkMixin, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, QueryResolver, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugMixin, SoftDeleteMixin, TreeMixin, collectReadBlockedFields, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineAggregation, defineResource, defineResourceVariants, getControllerContext, getControllerScope, getEntityId, getEntityIdField, getEntityQuery, isFieldReadable, sendControllerResponse };

package/dist/{core-DECn6zaU.mjs → core-D29kkRL5.mjs}

@@ -1,7 +1,7 @@
 import { s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-Cxde4rpC.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { A as assertValidConfig, l as getDefaultCrudSchemas } from "./utils-_h9B3c57.mjs";
-import { t as BaseController } from "./BaseController-DX_T-bDB.mjs";
+import { t as BaseController } from "./BaseController-Dv60tU83.mjs";
 import { t as applyPresets } from "./presets-BbkjdPeH.mjs";
 import { n as convertRouteSchema, t as convertOpenApiSchemas } from "./schemaConverter-De34B1ZG.mjs";
 import { t as hasEvents } from "./typeGuards-BzkXkvVv.mjs";
@@ -121,7 +121,7 @@ function createCustomRoutes(fastify, routes, controller, options) {
 * @param options    - Router configuration
 */
 function createCrudRouter(fastify, controller, options = {}) {
-	const { tag = "Resource", schemas = {}, permissions = {}, middlewares = {}, routeGuards = [], routes: customRoutes = [], disableDefaultRoutes = false, disabledRoutes = [], resourceName = "unknown", schemaOptions, rateLimit, pipe: pipeline, fields: fieldPermissions, updateMethod = DEFAULT_UPDATE_METHOD } = options;
+	const { tag = "Resource", schemas = {}, permissions = {}, middlewares = {}, routeGuards = [], routes: customRoutes = [], disableDefaultRoutes = false, disabledRoutes = [], resourceName = "unknown", schemaOptions, rateLimit, pipe: pipeline, fields: fieldPermissions, updateMethod = DEFAULT_UPDATE_METHOD, idField } = options;
 	const rateLimitConfig = buildRateLimitConfig(rateLimit);
 	const resourceHasQueryCache = fastify.hasDecorator("queryCache") && controller && typeof controller._cacheConfig !== "undefined" && controller._cacheConfig !== void 0;
 	const pluginMw = resolveRouterPluginMw(fastify, Boolean(resourceHasQueryCache));
@@ -131,7 +131,8 @@ function createCrudRouter(fastify, controller, options = {}) {
 		permissions,
 		hooks: fastify.arc?.hooks,
 		events: fastify.events,
-		fields: fieldPermissions
+		fields: fieldPermissions,
+		idField
 	});
 	const mw = {
 		list: middlewares.list ?? [],
@@ -926,15 +927,17 @@ function buildResourcePlugin(resource) {
 				rateLimit: resource.rateLimit,
 				updateMethod: resource.updateMethod,
 				pipe: resource.pipe,
-				fields: resource.fields
+				fields: resource.fields,
+				idField: resource.idField
 			});
 			if (resource.actions && Object.keys(resource.actions).length > 0) {
-				const { createActionRouter } = await import("./createActionRouter-CBxLLbn3.mjs").then((n) => n.n);
+				const { createActionRouter } = await import("./createActionRouter-S3MLVYot.mjs").then((n) => n.n);
 				createActionRouter(typedInstance, {
 					...normalizeActionsToRouterConfig(resource.actions, resource.actionPermissions, resource.tag, resource.permissions, resource.name, typedInstance.log),
 					resourceName: resource.name,
 					fields: resource.fields,
 					schemaOptions: resource.schemaOptions,
+					idField: resource.idField,
 					permissions: resource.permissions,
 					routeGuards: resource.routeGuards,
 					pipeline: resource.pipe,
@@ -942,7 +945,7 @@ function buildResourcePlugin(resource) {
 				});
 			}
 			if (resource.aggregations && Object.keys(resource.aggregations).length > 0) {
-				const { createAggregationRouter } = await import("./createAggregationRouter-CRIBv4sC.mjs");
+				const { createAggregationRouter } = await import("./createAggregationRouter-DhR-Ofiz.mjs");
 				const repoForAgg = resource.controller?.repository;
 				const buildOptions = (req) => {
 					return resource.controller?.tenantRepoOptions?.(req) ?? {};
@@ -1293,6 +1296,7 @@ function validateDefineResourceConfig(config) {
 	validatePermissionsShape(config);
 	validateCustomRoutePermissions(config);
 	validateActionsShape(config);
+	warnRedundantFieldRules(config);
 }
 /** Permissions must be `PermissionCheck` functions, not arbitrary values. */
 function validatePermissionsShape(config) {
@@ -1308,6 +1312,33 @@ function validateCustomRoutePermissions(config) {
 	for (const route of config.routes ?? []) if (typeof route.permissions !== "function") throw new Error(`[Arc] Resource '${config.name}' route ${route.method} ${route.path}: permissions is required and must be a PermissionCheck function.`);
 }
 /**
+* Surface common field-rule misconfigurations at boot — non-fatal,
+* just a `console.warn` so hosts notice and clean up.
+*
+* Catches:
+*   1. `immutable: true` + `immutableAfterCreate: true` — `immutable`
+*      already covers `immutableAfterCreate`. Picking both signals the
+*      author wasn't sure which to use.
+*   2. `systemManaged: true` + `readonly: true` — both are write rules
+*      and `BodySanitizer` strips on either; the second flag is dead.
+*   3. `hidden: true` + `aggregable: false` — `hidden` already blocks
+*      aggregation; `aggregable: false` is redundant.
+*
+* NOT a hard error — write-rule overlap is harmless at runtime, just
+* noisy in code review.
+*/
+function warnRedundantFieldRules(config) {
+	const fieldRules = config.schemaOptions?.fieldRules;
+	if (!fieldRules) return;
+	for (const [field, rule] of Object.entries(fieldRules)) {
+		if (!rule) continue;
+		const r = rule;
+		if (r.immutable === true && r.immutableAfterCreate === true) console.warn(`[Arc] Resource '${config.name}' fieldRules.${field}: \`immutable: true\` already implies \`immutableAfterCreate: true\` — drop the second flag.`);
+		if (r.systemManaged === true && r.readonly === true) console.warn(`[Arc] Resource '${config.name}' fieldRules.${field}: \`systemManaged\` and \`readonly\` both strip writes — pick one (\`systemManaged\` is the canonical name).`);
+		if (r.hidden === true && r.aggregable === false) console.warn(`[Arc] Resource '${config.name}' fieldRules.${field}: \`hidden: true\` already blocks aggregation — \`aggregable: false\` is redundant.`);
+	}
+}
+/**
 * Actions (v2.8) — name must not collide with CRUD ops; handler +
 * permissions must have the right shapes. Fail at boot so production
 * never ships a misconfigured action endpoint.
@@ -1396,4 +1427,70 @@ function defineResourceVariants(base, variants) {
 	return out;
 }
 //#endregion
-export { createPermissionMiddleware as a, createCrudRouter as i, defineResource as n, defineAggregation as o, ResourceDefinition as r, defineResourceVariants as t };
+//#region src/core/entityHelpers.ts
+/**
+* Per-request entity helpers — read the resource binding (idField + the
+* URL `:id` value) off `req.arc`.
+*
+* Action handlers receive their `id` argument as the raw URL `:id` value.
+* When the resource declares a custom `idField` (`slug`, `reportId`, …)
+* that's NOT the document `_id`, a naive `Model.findById(id)` silently
+* returns null. The historical footgun was a `findById(id)` typo where
+* the handler author hadn't realised that `:id` resolves to the friendly
+* handle.
+*
+* `getEntityQuery(req)` produces the canonical filter shape so handlers
+* compose lookups with no resource-config recall:
+*
+* ```ts
+* actions: {
+*   archive: {
+*     handler: async (id, data, req) => {
+*       const doc = await Model.findOne(getEntityQuery(req));
+*       if (!doc) throw new NotFoundError("Order");
+*       // ...
+*     },
+*   },
+* }
+* ```
+*
+* The router populates `req.arc.idField` and `req.arc.entityId` before
+* invoking the handler — these helpers are zero-cost reads.
+*/
+/**
+* Read the resource's configured `idField` for the current request.
+* Falls back to the framework default (`_id`) when the route hasn't
+* bound an idField — keeps handlers safe to author without checking
+* the resource config.
+*/
+function getEntityIdField(req) {
+	return req.arc?.idField ?? "_id";
+}
+/**
+* Read the URL `:id` path param value as the resource handle.
+* Returns `undefined` when the route has no `:id` segment (collection
+* routes) — handlers that need the entity must be on row routes.
+*/
+function getEntityId(req) {
+	if (req.arc?.entityId !== void 0) return req.arc.entityId;
+	return req.params?.id;
+}
+/**
+* Compose a `findOne` filter that resolves the current request's
+* entity, regardless of whether the resource binds `_id` or a custom
+* field. Idiomatic shape for arc action handlers.
+*
+* ```ts
+* const doc = await Model.findOne(getEntityQuery(req));
+* ```
+*
+* Returns `{}` when the route has no entity context (collection routes
+* or tests bypassing the router) — caller decides what that means.
+*/
+function getEntityQuery(req) {
+	const id = getEntityId(req);
+	if (id === void 0) return {};
+	return { [getEntityIdField(req)]: id };
+}
+//#endregion
+export { defineResource as a, createPermissionMiddleware as c, defineResourceVariants as i, defineAggregation as l, getEntityIdField as n, ResourceDefinition as o, getEntityQuery as r, createCrudRouter as s, getEntityId as t };

package/dist/{createActionRouter-CBxLLbn3.mjs → createActionRouter-S3MLVYot.mjs}

@@ -1,4 +1,5 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
+import "./constants-Cxde4rpC.mjs";
 import { f as createError } from "./errors-j4aJm1Wg.mjs";
 import { a as buildAuthMiddlewareForPermissions, c as buildPreHandlerChain, f as resolveRouterPluginMw, l as buildRateLimitConfig, n as buildActionPipelineHandler, p as selectPluginMw, r as buildArcDecorator, t as buildActionPermissionMw, u as resolvePipelineSteps, y as sendControllerResponse } from "./routerShared-DrOa-26E.mjs";
 import { n as schemaIRToJsonSchemaBranch, t as normalizeSchemaIR } from "./schemaIR-lYhC2gE5.mjs";
@@ -16,7 +17,7 @@ var createActionRouter_exports = /* @__PURE__ */ __exportAll({
 * (keyed by `body.action` at request time).
 */
 function createActionRouter(fastify, config) {
-	const { tag, resourceName = tag ?? "action", actions, actionPermissions = {}, actionSchemas = {}, globalAuth, onError, fields: fieldPermissions, schemaOptions, permissions: resourcePermissions, routeGuards = [], pipeline, rateLimit } = config;
+	const { tag, resourceName = tag ?? "action", actions, actionPermissions = {}, actionSchemas = {}, globalAuth, onError, fields: fieldPermissions, schemaOptions, idField = "_id", permissions: resourcePermissions, routeGuards = [], pipeline, rateLimit } = config;
 	const actionEnum = Object.keys(actions);
 	if (actionEnum.length === 0) {
 		fastify.log.warn("[createActionRouter] No actions defined, skipping route creation");
@@ -43,7 +44,8 @@ function createActionRouter(fastify, config) {
 		permissions: resourcePermissions,
 		hooks: fastify.arc?.hooks,
 		events: fastify.events,
-		fields: fieldPermissions
+		fields: fieldPermissions,
+		idField
 	});
 	const authMw = buildAuthMiddlewareForPermissions(fastify, actionEnum.map((name) => actionPermissions[name] ?? globalAuth));
 	const pluginMw = resolveRouterPluginMw(fastify, false);
@@ -69,6 +71,11 @@ function createActionRouter(fastify, config) {
 		handler: async (req, reply) => {
 			const { action, ...data } = req.body;
 			const { id } = req.params;
+			const reqWithExtras = req;
+			reqWithExtras.arc = {
+				...reqWithExtras.arc ?? {},
+				entityId: id
+			};
 			const handler = wrappedHandlers.get(action);
 			if (!handler) throw createError(400, `Invalid action '${action}'. Valid actions: ${actionEnum.join(", ")}`, { validActions: actionEnum });
 			try {

package/dist/{createAggregationRouter-CRIBv4sC.mjs → createAggregationRouter-DhR-Ofiz.mjs}

@@ -1,6 +1,6 @@
 import { f as createError, l as UnauthorizedError, r as ForbiddenError } from "./errors-j4aJm1Wg.mjs";
 import { c as buildPreHandlerChain, f as resolveRouterPluginMw, i as buildAuthMiddleware, l as buildRateLimitConfig, p as selectPluginMw, r as buildArcDecorator } from "./routerShared-DrOa-26E.mjs";
-import { r as validateAggregations, t as buildAggregationHandler } from "./buildHandler-olo-gt94.mjs";
+import { r as validateAggregations, t as buildAggregationHandler } from "./buildHandler-jSZ6Fdvi.mjs";
 //#region src/core/aggregation/createAggregationRouter.ts
 /**
 * Register one Fastify route per aggregation. No-op when the map is

package/dist/{createApp-XX2-N0Yd.mjs → createApp-BarYhXCZ.mjs}

@@ -393,9 +393,10 @@ async function registerOne(parent, resource) {
 	try {
 		await parent.register(resource.toPlugin());
 	} catch (err) {
-		const msg = err instanceof Error ? err.message : String(err);
-		parent.log.error(`Failed to register resource "${name}": ${msg}`);
-		throw new Error(`Resource "${name}" failed to register: ${msg}. Check the resource definition, adapter, and permissions.`, { cause: err });
+		const rawMsg = err instanceof Error ? err.message : String(err);
+		const stripped = rawMsg.replace(new RegExp(`^Resource "${name}"\\s*`), "").replace(/\.+\s*$/, "");
+		parent.log.error(`Failed to register resource "${name}": ${rawMsg}`);
+		throw new Error(`Resource "${name}" failed to register — ${stripped}.`, { cause: err });
 	}
 }
 /**

package/dist/docs/index.d.mts

@@ -1,4 +1,4 @@
-import { p as RegistryEntry } from "../index-BtW7qYwa.mjs";
+import { p as RegistryEntry } from "../index-Dwc0orNd.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-BD5nw6St.mjs";
 import { FastifyPluginAsync } from "fastify";
 

package/dist/docs/index.mjs

@@ -1,5 +1,5 @@
 import { t as getUserRoles } from "../types-D57iXYb8.mjs";
-import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-noXno2CV.mjs";
+import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-BHXhoX8O.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/scalar.ts
 const scalarPlugin = async (fastify, opts = {}) => {