@classytic/arc 2.21.0 → 2.22.0

package/dist/{fastify-augmentation-DafigGQp.d.mts → fastify-augmentation-9_fuetB4.d.mts}

@@ -1,6 +1,6 @@
-import { bn as HookSystem, z as ResourceRegistry } from "./index-Dtrj6XZk.mjs";
+import { bn as HookSystem, z as ResourceRegistry } from "./index-DbtgCOCj.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-BE6wFpYv.mjs";
-import { r as ArcModuleRegistry } from "./module-WeuU5jfd.mjs";
+import { r as ArcModuleRegistry } from "./module-B4u10iOJ.mjs";
 import { FastifyPluginAsync } from "fastify";
 //#region src/core/arcCorePlugin.d.ts
 interface ArcCorePluginOptions {

package/dist/fields-D3lhgzhD.d.mts

@@ -0,0 +1,121 @@
+//#region src/permissions/fields.d.ts
+/**
+ * Field-Level Permissions
+ *
+ * Control field visibility and writability per role.
+ * Integrated into the response path (read) and sanitization path (write).
+ *
+ * @example
+ * ```typescript
+ * import { fields, defineResource } from '@classytic/arc';
+ *
+ * const userResource = defineResource({
+ *   name: 'user',
+ *   adapter: userAdapter,
+ *   fields: {
+ *     salary: fields.visibleTo(['admin', 'hr']),
+ *     internalNotes: fields.writableBy(['admin']),
+ *     email: fields.redactFor(['viewer']),
+ *     password: fields.hidden(),
+ *   },
+ * });
+ * ```
+ */
+type FieldPermissionType = "hidden" | "visibleTo" | "writableBy" | "redactFor";
+interface FieldPermission {
+  readonly _type: FieldPermissionType;
+  readonly roles?: readonly string[];
+  readonly redactValue?: unknown;
+}
+type FieldPermissionMap = Record<string, FieldPermission>;
+declare const fields: {
+  /**
+   * Field is never included in responses. Not writable via API.
+   *
+   * @example
+   * ```typescript
+   * fields: { password: fields.hidden() }
+   * ```
+   */
+  hidden(): FieldPermission;
+  /**
+   * Field is only visible to users with specified roles.
+   * Other users don't see the field at all.
+   *
+   * @example
+   * ```typescript
+   * fields: { salary: fields.visibleTo(['admin', 'hr']) }
+   * ```
+   */
+  visibleTo(roles: readonly string[]): FieldPermission;
+  /**
+   * Field is only writable by users with specified roles.
+   * All users can still read the field. Users without the role
+   * have the field silently stripped from write operations.
+   *
+   * @example
+   * ```typescript
+   * fields: { role: fields.writableBy(['admin']) }
+   * ```
+   */
+  writableBy(roles: readonly string[]): FieldPermission;
+  /**
+   * Field is redacted (replaced with a placeholder) for specified roles.
+   * Other users see the real value.
+   *
+   * @param roles - Roles that see the redacted value
+   * @param redactValue - Replacement value (default: '***')
+   *
+   * @example
+   * ```typescript
+   * fields: {
+   *   email: fields.redactFor(['viewer']),
+   *   ssn: fields.redactFor(['basic'], '***-**-****'),
+   * }
+   * ```
+   */
+  redactFor(roles: readonly string[], redactValue?: unknown): FieldPermission;
+};
+/**
+ * Apply field-level READ permissions to a response object.
+ * Strips hidden fields, enforces visibility, and applies redaction.
+ *
+ * @param data - The response object (mutated in place for performance)
+ * @param fieldPermissions - Field permission map from resource config
+ * @param userRoles - Current user's roles (empty array for unauthenticated)
+ * @returns The filtered object
+ */
+declare function applyFieldReadPermissions<T extends Record<string, unknown>>(data: T, fieldPermissions: FieldPermissionMap, userRoles: readonly string[]): T;
+/**
+ * Result of applying write permissions — includes both the filtered body
+ * and the list of fields that were stripped so callers can decide whether
+ * to reject the request (secure default) or silently strip (legacy).
+ */
+interface FieldWritePermissionResult<T extends Record<string, unknown>> {
+  readonly body: T;
+  readonly deniedFields: readonly string[];
+}
+/**
+ * Apply field-level WRITE permissions to request body.
+ *
+ * Returns both the filtered body and the list of denied fields. Callers are
+ * expected to reject the request when `deniedFields.length > 0` — silently
+ * stripping fields hides misconfigurations and real attacks. See
+ * `BodySanitizer` for the default policy.
+ *
+ * @param body - The request body (returns a new filtered copy)
+ * @param fieldPermissions - Field permission map from resource config
+ * @param userRoles - Current user's roles
+ */
+declare function applyFieldWritePermissions<T extends Record<string, unknown>>(body: T, fieldPermissions: FieldPermissionMap, userRoles: readonly string[]): FieldWritePermissionResult<T>;
+/**
+ * Resolve effective roles by merging global user roles with org-level roles.
+ *
+ * Global roles come from `req.user.role` (normalized via getUserRoles()).
+ * Org roles come from `req.context.orgRoles` (set by BA adapter's org bridge).
+ *
+ * When no org context exists, returns global roles only — backward compatible.
+ */
+declare function resolveEffectiveRoles(userRoles: readonly string[], orgRoles: readonly string[]): string[];
+//#endregion
+export { applyFieldWritePermissions as a, applyFieldReadPermissions as i, FieldPermissionMap as n, fields as o, FieldPermissionType as r, resolveEffectiveRoles as s, FieldPermission as t };

package/dist/health-ScyjIVo5.mjs

@@ -0,0 +1,202 @@
+import fp from "fastify-plugin";
+//#region src/plugins/health.ts
+function createHttpMetrics() {
+	return {
+		requestsTotal: {},
+		requestDurations: [],
+		_ringIndex: 0,
+		startTime: Date.now()
+	};
+}
+const healthPlugin = async (fastify, opts = {}) => {
+	const { prefix = "/_health", checks = [], metrics = false, metricsCollector, version, collectHttpMetrics = metrics } = opts;
+	const httpMetrics = createHttpMetrics();
+	fastify.get(prefix, { schema: {
+		tags: ["Health"],
+		summary: "Liveness probe (alias for /live)",
+		description: "Returns 200 if the process is alive",
+		response: { 200: {
+			type: "object",
+			properties: {
+				status: {
+					type: "string",
+					enum: ["ok"]
+				},
+				timestamp: { type: "string" },
+				version: { type: "string" }
+			}
+		} }
+	} }, async () => ({
+		status: "ok",
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		...version ? { version } : {}
+	}));
+	fastify.get(`${prefix}/live`, { schema: {
+		tags: ["Health"],
+		summary: "Liveness probe",
+		description: "Returns 200 if the process is alive",
+		response: { 200: {
+			type: "object",
+			properties: {
+				status: {
+					type: "string",
+					enum: ["ok"]
+				},
+				timestamp: { type: "string" },
+				version: { type: "string" }
+			}
+		} }
+	} }, async () => {
+		return {
+			status: "ok",
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			...version ? { version } : {}
+		};
+	});
+	fastify.get(`${prefix}/ready`, { schema: {
+		tags: ["Health"],
+		summary: "Readiness probe",
+		description: "Returns 200 if all dependencies are healthy",
+		response: {
+			200: {
+				type: "object",
+				properties: {
+					status: {
+						type: "string",
+						enum: ["ready", "not_ready"]
+					},
+					timestamp: { type: "string" },
+					checks: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								name: { type: "string" },
+								healthy: { type: "boolean" },
+								duration: { type: "number" },
+								error: { type: "string" }
+							}
+						}
+					}
+				}
+			},
+			503: {
+				type: "object",
+				properties: {
+					status: {
+						type: "string",
+						enum: ["not_ready"]
+					},
+					timestamp: { type: "string" },
+					checks: { type: "array" }
+				}
+			}
+		}
+	} }, async (_, reply) => {
+		const results = await runChecks(checks);
+		const criticalFailed = results.some((r) => !r.healthy && (checks.find((c) => c.name === r.name)?.critical ?? true));
+		const response = {
+			status: criticalFailed ? "not_ready" : "ready",
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			checks: results
+		};
+		if (criticalFailed) reply.code(503);
+		return response;
+	});
+	if (metrics) fastify.get(`${prefix}/metrics`, async (_, reply) => {
+		reply.type("text/plain; charset=utf-8");
+		if (metricsCollector) return await metricsCollector();
+		const uptime = process.uptime();
+		const memory = process.memoryUsage();
+		const cpu = process.cpuUsage();
+		const lines = [
+			"# HELP process_uptime_seconds Process uptime in seconds",
+			"# TYPE process_uptime_seconds gauge",
+			`process_uptime_seconds ${uptime.toFixed(2)}`,
+			"",
+			"# HELP process_memory_heap_bytes Heap memory usage in bytes",
+			"# TYPE process_memory_heap_bytes gauge",
+			`process_memory_heap_bytes{type="used"} ${memory.heapUsed}`,
+			`process_memory_heap_bytes{type="total"} ${memory.heapTotal}`,
+			"",
+			"# HELP process_memory_rss_bytes RSS memory in bytes",
+			"# TYPE process_memory_rss_bytes gauge",
+			`process_memory_rss_bytes ${memory.rss}`,
+			"",
+			"# HELP process_memory_external_bytes External memory in bytes",
+			"# TYPE process_memory_external_bytes gauge",
+			`process_memory_external_bytes ${memory.external}`,
+			"",
+			"# HELP process_cpu_user_microseconds User CPU time in microseconds",
+			"# TYPE process_cpu_user_microseconds counter",
+			`process_cpu_user_microseconds ${cpu.user}`,
+			"",
+			"# HELP process_cpu_system_microseconds System CPU time in microseconds",
+			"# TYPE process_cpu_system_microseconds counter",
+			`process_cpu_system_microseconds ${cpu.system}`,
+			""
+		];
+		if (collectHttpMetrics && Object.keys(httpMetrics.requestsTotal).length > 0) {
+			lines.push("# HELP http_requests_total Total HTTP requests by status code", "# TYPE http_requests_total counter");
+			for (const [status, count] of Object.entries(httpMetrics.requestsTotal)) lines.push(`http_requests_total{status="${status}"} ${count}`);
+			lines.push("");
+			if (httpMetrics.requestDurations.length > 0) {
+				const sorted = [...httpMetrics.requestDurations].sort((a, b) => a - b);
+				const p50 = sorted[Math.floor(sorted.length * .5)] || 0;
+				const p95 = sorted[Math.floor(sorted.length * .95)] || 0;
+				const p99 = sorted[Math.floor(sorted.length * .99)] || 0;
+				const sum = sorted.reduce((a, b) => a + b, 0);
+				lines.push("# HELP http_request_duration_milliseconds HTTP request duration", "# TYPE http_request_duration_milliseconds summary", `http_request_duration_milliseconds{quantile="0.5"} ${p50.toFixed(2)}`, `http_request_duration_milliseconds{quantile="0.95"} ${p95.toFixed(2)}`, `http_request_duration_milliseconds{quantile="0.99"} ${p99.toFixed(2)}`, `http_request_duration_milliseconds_sum ${sum.toFixed(2)}`, `http_request_duration_milliseconds_count ${sorted.length}`, "");
+			}
+		}
+		return lines.join("\n");
+	});
+	if (collectHttpMetrics) fastify.addHook("onResponse", async (_request, reply) => {
+		const duration = reply.elapsedTime;
+		const statusBucket = `${Math.floor(reply.statusCode / 100)}xx`;
+		httpMetrics.requestsTotal[statusBucket] = (httpMetrics.requestsTotal[statusBucket] || 0) + 1;
+		if (httpMetrics.requestDurations.length < 1e4) httpMetrics.requestDurations.push(duration);
+		else httpMetrics.requestDurations[httpMetrics._ringIndex % 1e4] = duration;
+		httpMetrics._ringIndex = httpMetrics._ringIndex + 1;
+	});
+	fastify.log?.debug?.(`Health plugin registered at ${prefix} (alias), ${prefix}/live, ${prefix}/ready${metrics ? `, ${prefix}/metrics` : ""}`);
+};
+/**
+* Run all health checks with timeout
+*/
+async function runChecks(checks) {
+	const results = [];
+	for (const check of checks) {
+		const start = Date.now();
+		const timeout = check.timeout ?? 5e3;
+		let timer;
+		try {
+			const checkPromise = Promise.resolve(check.check());
+			const timeoutPromise = new Promise((_, reject) => {
+				timer = setTimeout(() => reject(/* @__PURE__ */ new Error("Health check timeout")), timeout);
+			});
+			const healthy = await Promise.race([checkPromise, timeoutPromise]);
+			results.push({
+				name: check.name,
+				healthy: Boolean(healthy),
+				duration: Date.now() - start
+			});
+		} catch (err) {
+			results.push({
+				name: check.name,
+				healthy: false,
+				duration: Date.now() - start,
+				error: err.message
+			});
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	}
+	return results;
+}
+var health_default = fp(healthPlugin, {
+	name: "arc-health",
+	fastify: "5.x"
+});
+//#endregion
+export { health_default as n, healthPlugin as t };

package/dist/hooks/index.d.mts

@@ -1,2 +1,2 @@
-import { Cn as afterDelete, Dn as beforeUpdate, En as beforeDelete, On as createHookSystem, Sn as afterCreate, Tn as beforeCreate, _n as HookOperation, bn as HookSystem, gn as HookHandler, hn as HookContext, kn as defineHook, mn as DefineHookOptions, vn as HookPhase, wn as afterUpdate, xn as HookSystemOptions, yn as HookRegistration } from "../index-Dtrj6XZk.mjs";
+import { Cn as afterDelete, Dn as beforeUpdate, En as beforeDelete, On as createHookSystem, Sn as afterCreate, Tn as beforeCreate, _n as HookOperation, bn as HookSystem, gn as HookHandler, hn as HookContext, kn as defineHook, mn as DefineHookOptions, vn as HookPhase, wn as afterUpdate, xn as HookSystemOptions, yn as HookRegistration } from "../index-DbtgCOCj.mjs";
 export { type DefineHookOptions, type HookContext, type HookHandler, type HookOperation, type HookPhase, type HookRegistration, HookSystem, type HookSystemOptions, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/idempotency/index.mjs

@@ -287,12 +287,14 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		});
 		fastify.decorateRequest("idempotencyKey", void 0);
 		fastify.decorateRequest("idempotencyReplayed", false);
+		fastify.decorateRequest("_idempotencyFullKey", void 0);
 		fastify.log?.debug?.("Idempotency plugin disabled");
 		return;
 	}
 	const methodSet = new Set(methods.map((m) => m.toUpperCase()));
 	fastify.decorateRequest("idempotencyKey", void 0);
 	fastify.decorateRequest("idempotencyReplayed", false);
+	fastify.decorateRequest("_idempotencyFullKey", void 0);
 	/**
 	* Check if this request should use idempotency
 	*/

package/dist/{types-DpxoNX5v.d.mts → index-BEu4wjbL.d.mts}

@@ -1,13 +1,13 @@
-import { Ut as Authenticator } from "./index-Dtrj6XZk.mjs";
+import { Ut as Authenticator } from "./index-DbtgCOCj.mjs";
 import { r as CacheStore } from "./interface-C1_WLTMK.mjs";
 import { n as ElevationOptions } from "./elevation-C9s5hFP_.mjs";
 import { a as EventTransport } from "./EventTransport-QmY7A258.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-BE6wFpYv.mjs";
 import { r as QueryCachePluginOptions } from "./queryCachePlugin-CfYWq-Ak.mjs";
-import { t as ErrorHandlerOptions } from "./errorHandler-B0e-bq-O.mjs";
-import { l as ResourceLike, n as ArcModuleInput } from "./module-WeuU5jfd.mjs";
+import { t as ErrorHandlerOptions } from "./errorHandler-C6yv4ZTW.mjs";
+import { l as ResourceLike, n as ArcModuleInput } from "./module-B4u10iOJ.mjs";
 import { t as EventPluginOptions } from "./eventPlugin-A6EbthXR.mjs";
-import { _ as HealthOptions, f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-DQ4mCvg0.mjs";
+import { _ as HealthOptions, f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-DLwklPlG.mjs";
 import { r as IdempotencyStore } from "./interface-Uk8ONJv7.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
 //#region src/testing/preloadResources.d.ts
@@ -33,30 +33,7 @@ declare function preloadResources(globResult: EagerGlobResult): ResourceLike[];
  */
 declare function preloadResourcesAsync(globResult: LazyGlobResult): Promise<ResourceLike[]>;
 //#endregion
-//#region src/factory/types.d.ts
-type CorsOptions = Record<string, unknown> & {
-  origin?: unknown;
-  credentials?: boolean;
-  methods?: string[];
-  allowedHeaders?: string[];
-};
-type HelmetOptions = Record<string, unknown>;
-type RateLimitOpts = Record<string, unknown> & {
-  max?: number;
-  timeWindow?: string | number;
-  /**
-   * Path patterns to exempt from rate limiting. Supports exact match
-   * (`/health`) or prefix match with trailing `*` (`/api/auth/*`).
-   *
-   * Implemented by synthesising a `@fastify/rate-limit` `allowList`
-   * function. When combined with a user-supplied `allowList`, both
-   * are OR-ed together (path OR ip/custom match skips the limit).
-   *
-   * Use this for endpoints that are hit frequently but independently
-   * of user traffic — session heartbeat, webhooks, health probes.
-   */
-  skipPaths?: string[];
-};
+//#region src/factory/types/auth.d.ts
 /**
  * Arc's built-in JWT auth
  *
@@ -161,13 +138,29 @@ interface JwtAuthOption {
  * });
  * ```
  */
+/** The shape `createBetterAuthAdapter()` returns. */
+interface BetterAuthAdapterResult {
+  plugin: FastifyPluginAsync;
+  openapi?: ExternalOpenApiPaths;
+}
 interface BetterAuthOption {
   type: "betterAuth";
-  /** Better Auth adapter — pass the result of createBetterAuthAdapter() */
-  betterAuth: {
-    plugin: FastifyPluginAsync;
-    openapi?: ExternalOpenApiPaths;
-  };
+  /**
+   * Better Auth adapter — the result of `createBetterAuthAdapter()`, or a
+   * sync/async THUNK returning it (2.22). The thunk resolves during auth
+   * registration — AFTER `beforeBoot` — for adapters whose construction
+   * needs a live DB (Better Auth's `mongodbAdapter(mongoose.connection
+   * .getClient().db())` requires an OPEN connection, so an eager value
+   * forces hosts back into connect-before-createApp ordering dances):
+   *
+   * ```typescript
+   * createApp({
+   *   beforeBoot: () => connectDatabase(),
+   *   auth: { type: 'betterAuth', betterAuth: () => createBetterAuthAdapter({ auth: getAuth() }) },
+   * });
+   * ```
+   */
+  betterAuth: BetterAuthAdapterResult | (() => BetterAuthAdapterResult | Promise<BetterAuthAdapterResult>);
 }
 /**
  * Custom auth plugin — full control over authentication setup
@@ -234,6 +227,112 @@ interface CustomAuthenticatorOption {
  * - `CustomAuthenticatorOption` — A bare authenticate function (`type: 'authenticator'`)
  */
 type AuthOption = false | JwtAuthOption | BetterAuthOption | CustomPluginAuthOption | CustomAuthenticatorOption;
+//#endregion
+//#region src/factory/types/plugin-options.d.ts
+/**
+ * Plugin-specific option shapes for `createApp()` — under-pressure,
+ * multipart, and raw-body plugin configuration.
+ */
+interface UnderPressureOptions {
+  /** Expose `/_status` route for health checks (default: false) */
+  exposeStatusRoute?: boolean;
+  /** Event loop lag threshold in ms — requests rejected above this (default: 1000) */
+  maxEventLoopDelay?: number;
+  /** V8 heap usage threshold in bytes — requests rejected above this */
+  maxHeapUsedBytes?: number;
+  /** RSS memory threshold in bytes — requests rejected above this */
+  maxRssBytes?: number;
+}
+interface MultipartOptions {
+  limits?: {
+    /** Max file size in bytes (default: Fastify default ~1MB) */
+    fileSize?: number;
+    /** Max number of files per request */
+    files?: number;
+  };
+}
+interface RawBodyOptions {
+  /** Body field name to store raw body on (default: 'rawBody') */
+  field?: string;
+  /** Apply to all routes globally (default: false) */
+  global?: boolean;
+  /** Encoding for raw body string (default: 'utf8') */
+  encoding?: string;
+  /** Parse raw body before other parsers (default: false) */
+  runFirst?: boolean;
+}
+//#endregion
+//#region src/factory/types/security.d.ts
+/**
+ * Security-plugin option shapes — CORS / Helmet / rate-limit config for
+ * `createApp()`, including plan-aware rate limiting (2.22).
+ */
+type CorsOptions = Record<string, unknown> & {
+  origin?: unknown;
+  credentials?: boolean;
+  methods?: string[];
+  allowedHeaders?: string[];
+};
+type HelmetOptions = Record<string, unknown>;
+type RateLimitOpts = Record<string, unknown> & {
+  max?: number;
+  timeWindow?: string | number;
+  /**
+   * Path patterns to exempt from rate limiting. Supports exact match
+   * (`/health`) or prefix match with trailing `*` (`/api/auth/*`).
+   *
+   * Implemented by synthesising a `@fastify/rate-limit` `allowList`
+   * function. When combined with a user-supplied `allowList`, both
+   * are OR-ed together (path OR ip/custom match skips the limit).
+   *
+   * Use this for endpoints that are hit frequently but independently
+   * of user traffic — session heartbeat, webhooks, health probes.
+   */
+  skipPaths?: string[];
+  /**
+   * Plan-aware limits (2.22) — resolve the caller's plan per request and
+   * apply that plan's ceiling instead of the global `max`:
+   *
+   * ```typescript
+   * rateLimit: {
+   *   timeWindow: '1 minute',
+   *   plan: {
+   *     resolve: (req) => lookupPlan(req),            // 'free' | 'pro' | ...
+   *     limits: { free: { max: 60 }, pro: { max: 1000 }, enterprise: false },
+   *     default: 'free',
+   *   },
+   * }
+   * ```
+   *
+   * `false` = effectively unlimited. When `plan` is set and no
+   * `keyGenerator` is supplied, arc defaults to the tenant key chain
+   * (org → user → client → IP) so buckets follow actors, not addresses.
+   *
+   * Timing caveat: the limiter runs before route-level auth, so
+   * `req.scope` may be unresolved for token-authenticated calls —
+   * `resolve` receives the RAW request and may need to derive the plan
+   * from its own header/token/session lookup. Same caveat as
+   * `createTenantKeyGenerator`'s IP fallback (documented there).
+   */
+  plan?: RateLimitPlanConfig;
+};
+/** Plan-aware rate limiting (2.22) — see `rateLimit.plan` on CreateAppOptions. */
+interface RateLimitPlanConfig {
+  /**
+   * Name the caller's plan from the raw request. Return `undefined` to
+   * fall back to `default`. Sync or async; a throwing resolver also
+   * falls back (limits must fail-safe, not fail-open to unlimited).
+   */
+  resolve: (req: import("fastify").FastifyRequest) => string | undefined | Promise<string | undefined>;
+  /** Per-plan ceilings within the shared `timeWindow`. `false` = effectively unlimited. */
+  limits: Record<string, {
+    max: number;
+  } | false>;
+  /** Plan used when `resolve` returns undefined/unknown or throws. Default: fall back to the global `max`. */
+  default?: string;
+}
+//#endregion
+//#region src/factory/types/app-options.d.ts
 /**
  * CreateApp Options
  *
@@ -276,8 +375,18 @@ type AuthOption = false | JwtAuthOption | BetterAuthOption | CustomPluginAuthOpt
  * ```
  */
 interface CreateAppOptions {
-  /** Environment preset: 'production', 'development', 'testing', or 'edge' */
-  preset?: "production" | "development" | "testing" | "edge";
+  /** Environment preset: 'production', 'development', 'testing', 'edge', or 'worker' */
+  preset?: "production" | "development" | "testing" | "edge" | "worker";
+  /**
+   * Route-mounting switch (2.23) — the worker-role primitive. `false`
+   * registers every resource's shared runtime state (registry metadata +
+   * adapter, hooks, cache-invalidation rules) WITHOUT mounting any routes,
+   * so headless processes keep tenant-purge cascade, per-resource audit,
+   * and events metadata intact. Set by `preset: 'worker'` /
+   * `createWorker()`; hosts composing a custom worker shape may set it
+   * directly. Default: true (routes mount).
+   */
+  mountRoutes?: boolean;
   /**
    * Runtime profile for store backends.
    * - 'memory' (default): Uses in-memory stores. Suitable for single-instance deployments.
@@ -324,10 +433,50 @@ interface CreateAppOptions {
    * ```
    */
   debug?: boolean | string;
-  /** Trust proxy headers (X-Forwarded-For, etc.) */
-  trustProxy?: boolean;
+  /**
+   * Trust proxy headers (X-Forwarded-For, etc.). Pass-through to Fastify's
+   * `trustProxy` server option — all its forms are supported, not just the
+   * boolean:
+   *
+   * - `true` — trust ALL proxies (only safe when the app is never directly
+   *   reachable; a spoofed `X-Forwarded-For` otherwise forges `request.ip`,
+   *   which feeds rate-limit keys and audit logs)
+   * - `1` — trust exactly one hop (typical single LB / reverse proxy)
+   * - `'10.0.0.0/8'` / `['10.0.0.0/8', '172.16.0.0/12']` — trust only these
+   *   CIDR ranges
+   *
+   * @example
+   * ```ts
+   * createApp({ preset: 'production', trustProxy: 1 });          // one LB hop
+   * createApp({ preset: 'production', trustProxy: '10.0.0.0/8' }); // VPC proxies
+   * ```
+   */
+  trustProxy?: boolean | string | string[] | number;
   /** Fastify plugin/onReady timeout in ms (default: 10_000). Raise for slow boot work (index materialisation, WAL replay, external warm-up). */
   pluginTimeout?: number;
+  /**
+   * Max time in ms the server waits to RECEIVE an entire request
+   * (headers + body). Pass-through to Fastify's `requestTimeout` (Node's
+   * `server.requestTimeout`). Default `0` defers to Node's own 300s bound
+   * — slow-loris requests are already cut off there, so arc doesn't
+   * override; tighten (e.g. `30_000`) for APIs that never accept slow
+   * uploads. Response duration (SSE, streaming) is NOT affected.
+   */
+  requestTimeout?: number;
+  /**
+   * Max time in ms to establish a connection before the socket is
+   * destroyed. Pass-through to Fastify's `connectionTimeout` (Node's
+   * `server.timeout`). Default `0` = no limit (Node's `headersTimeout`
+   * ~60s still bounds idle pre-request sockets).
+   */
+  connectionTimeout?: number;
+  /**
+   * Keep-alive idle timeout in ms (Node's `server.keepAliveTimeout`,
+   * default 72_000). MUST be longer than the idle timeout of any load
+   * balancer in front of the app (ALB default 60s) or the LB reuses
+   * sockets the server just closed → intermittent 502s.
+   */
+  keepAliveTimeout?: number;
   /**
    * Maximum JSON body size in bytes. Pass-through to Fastify's
    * server-level `bodyLimit` option; default is Fastify's 1 MiB
@@ -933,33 +1082,5 @@ interface CreateAppOptions {
   /** Hook called when the app is shutting down */
   onClose?: (fastify: FastifyInstance) => void | Promise<void>;
 }
-interface UnderPressureOptions {
-  /** Expose `/_status` route for health checks (default: false) */
-  exposeStatusRoute?: boolean;
-  /** Event loop lag threshold in ms — requests rejected above this (default: 1000) */
-  maxEventLoopDelay?: number;
-  /** V8 heap usage threshold in bytes — requests rejected above this */
-  maxHeapUsedBytes?: number;
-  /** RSS memory threshold in bytes — requests rejected above this */
-  maxRssBytes?: number;
-}
-interface MultipartOptions {
-  limits?: {
-    /** Max file size in bytes (default: Fastify default ~1MB) */
-    fileSize?: number;
-    /** Max number of files per request */
-    files?: number;
-  };
-}
-interface RawBodyOptions {
-  /** Body field name to store raw body on (default: 'rawBody') */
-  field?: string;
-  /** Apply to all routes globally (default: false) */
-  global?: boolean;
-  /** Encoding for raw body string (default: 'utf8') */
-  encoding?: string;
-  /** Parse raw body before other parsers (default: false) */
-  runFirst?: boolean;
-}
 //#endregion
-export { CustomPluginAuthOption as a, RawBodyOptions as c, preloadResourcesAsync as d, CustomAuthenticatorOption as i, UnderPressureOptions as l, BetterAuthOption as n, JwtAuthOption as o, CreateAppOptions as r, MultipartOptions as s, AuthOption as t, preloadResources as u };
+export { AuthOption as a, CustomPluginAuthOption as c, preloadResourcesAsync as d, UnderPressureOptions as i, JwtAuthOption as l, MultipartOptions as n, BetterAuthOption as o, RawBodyOptions as r, CustomAuthenticatorOption as s, CreateAppOptions as t, preloadResources as u };

package/dist/{index-B5N-NaHs.d.mts → index-D8MKYGDa.d.mts}

@@ -1,7 +1,7 @@
-import { C as RequestContext, Et as AggregationConfig, F as FastifyWithDecorators, H as ActionDefinition, K as ArcFieldRule, L as RequestWithExtras, T as CrudRouterOptions, V as ResourceDefinition, bt as IControllerResponse, ht as RouteSchemaOptions, pt as RouteMcpConfig, q as CrudController, qt as AnyRecord, st as ResourceConfig, xt as IRequestContext, yt as IController } from "./index-Dtrj6XZk.mjs";
+import { C as RequestContext, Et as ActionDefinition, F as FastifyWithDecorators, H as CrudController, L as RequestWithExtras, Lt as IController, Rt as IControllerResponse, T as CrudRouterOptions, U as ResourceConfig, V as ResourceDefinition, et as RouteSchemaOptions, jt as RouteMcpConfig, qt as AnyRecord, tt as ArcFieldRule, ut as AggregationConfig, zt as IRequestContext } from "./index-DbtgCOCj.mjs";
 import { i as RequestScope } from "./types-DH0GupI7.mjs";
-import { c as PermissionCheck } from "./fields-BGqrAa_u.mjs";
-import "./fastify-augmentation-DafigGQp.mjs";
+import { t as PermissionCheck } from "./types-Csxga7d3.mjs";
+import "./fastify-augmentation-9_fuetB4.mjs";
 import { FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
 import { z } from "zod";
 import { DataAdapter } from "@classytic/repo-core/adapter";