@classytic/arc 2.20.0 → 2.22.0

package/dist/{createApp-D6uwzCKu.mjs → createApp-Ci7yG5gv.mjs}

@@ -1,8 +1,183 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
-import { arcLog } from "./logger/index.mjs";
+import { arcLog, configureArcLogger, createPinoWriter } from "./logger/index.mjs";
 import { n as PUBLIC_SCOPE } from "./types-bHblZ9YN.mjs";
+import { t as createTenantKeyGenerator } from "./rateLimitKey-BoWRH3e7.mjs";
+import { t as createRequestIdGenerator } from "./requestId-5BhTVzBv.mjs";
+import { t as parseJsonBody } from "./jsonBody-BlzAoGCe.mjs";
 import Fastify from "fastify";
 import qs from "qs";
+//#region src/testing/preloadResources.ts
+/**
+* Normalize an eager `import.meta.glob` result into a `ResourceLike[]`.
+*
+* Accepts either:
+* - `{ import: 'default' }` form: values are the resource directly
+* - default form: values are the full module — picks first export with `toPlugin()`
+*
+* Throws if any module doesn't yield a valid `ResourceLike`.
+*/
+function preloadResources(globResult) {
+	const resources = [];
+	for (const [path, value] of Object.entries(globResult)) {
+		const resource = pickResource(value);
+		if (!resource) throw new Error(`preloadResources: ${path} does not export a valid resource.\n    Expected: a default export OR a named export with toPlugin().`);
+		resources.push(resource);
+	}
+	return resources.sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
+}
+/**
+* Normalize a lazy `import.meta.glob` result into a `Promise<ResourceLike[]>`.
+*
+* Use this when resources depend on prior bootstrap (e.g., engine init) and
+* cannot be evaluated at import time of the preload file.
+*/
+async function preloadResourcesAsync(globResult) {
+	return (await Promise.all(Object.entries(globResult).map(async ([path, loader]) => {
+		const resource = pickResource(await loader());
+		if (!resource) throw new Error(`preloadResourcesAsync: ${path} does not export a valid resource.\n    Expected: a default export OR a named export with toPlugin().`);
+		return resource;
+	}))).sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
+}
+function pickResource(value) {
+	if (!value || typeof value !== "object") return void 0;
+	if (typeof value.toPlugin === "function") return value;
+	const mod = value;
+	const candidates = [
+		mod.default,
+		mod.resource,
+		...Object.values(mod)
+	];
+	for (const c of candidates) if (c && typeof c === "object" && typeof c.toPlugin === "function") return c;
+}
+//#endregion
+//#region src/factory/module.ts
+/**
+* Resolve any module-input form to a concrete `ArcModule`. A thunk is invoked
+* (this is where a dynamic `import()` fires); a promise (or plain module) is
+* awaited. Called once per module at the start of the bootstrap phase.
+*/
+async function resolveModule(input) {
+	const resolved = typeof input === "function" ? await input() : await input;
+	if (!resolved || typeof resolved !== "object" || typeof resolved.name !== "string") throw new Error("[arc] a `modules` entry resolved to something that is not an ArcModule (expected an object with a string `name`). Check dynamic-import thunks return `createXModule(deps)` (or the module object), not the namespace.");
+	return resolved;
+}
+/**
+* Order modules for composition by their `dependsOn` edges — a STABLE
+* topological sort. Called once at the start of the bootstrap phase; every
+* subsequent phase (bootstrap, resources, afterResources, and reverse-order
+* onClose) iterates the returned list, so a module's declared dependencies are
+* always composed before it.
+*
+* "Stable" = modules with no edge between them keep their original list order,
+* so declaring `dependsOn` on one module never silently reorders an unrelated
+* one. Backward compatible: a `modules` array with NO `dependsOn` anywhere is
+* returned unchanged.
+*
+* Fail-fast — throws (never reorders past a broken contract) on:
+*   - duplicate module names (the name is the graph key)
+*   - a `dependsOn` name not present in the composed set
+*   - a self-reference (`dependsOn` includes the module's own name)
+*   - a dependency cycle (reports the concrete `a → b → … → a` path)
+*/
+function orderModules(modules) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const m of modules) {
+		if (byName.has(m.name)) throw new Error(`[arc] Duplicate module name "${m.name}" — composed twice; check your modules array.`);
+		byName.set(m.name, m);
+	}
+	for (const m of modules) for (const dep of m.dependsOn ?? []) {
+		if (dep === m.name) throw new Error(`[arc] module "${m.name}" dependsOn itself — remove the self-reference.`);
+		if (!byName.has(dep)) throw new Error(`[arc] module "${m.name}" dependsOn "${dep}", which is not composed. Add the "${dep}" module to createApp({ modules }) (before this one is fine — arc orders them), or drop the dependency. Composed modules: ${[...byName.keys()].join(", ") || "(none)"}.`);
+	}
+	if (modules.every((m) => !m.dependsOn || m.dependsOn.length === 0)) return [...modules];
+	const originalIndex = /* @__PURE__ */ new Map();
+	let nextIndex = 0;
+	for (const m of modules) originalIndex.set(m.name, nextIndex++);
+	const pendingDeps = new Map(modules.map((m) => [m.name, (m.dependsOn ?? []).length]));
+	const dependents = /* @__PURE__ */ new Map();
+	for (const m of modules) for (const dep of m.dependsOn ?? []) {
+		const list = dependents.get(dep);
+		if (list) list.push(m.name);
+		else dependents.set(dep, [m.name]);
+	}
+	const ordered = [];
+	const remaining = new Set(modules.map((m) => m.name));
+	while (remaining.size > 0) {
+		let pick;
+		let pickIndex = Number.POSITIVE_INFINITY;
+		for (const name of remaining) {
+			if (pendingDeps.get(name) !== 0) continue;
+			const index = originalIndex.get(name) ?? Number.POSITIVE_INFINITY;
+			if (index < pickIndex) {
+				pick = name;
+				pickIndex = index;
+			}
+		}
+		if (pick === void 0) throw new Error(describeModuleCycle(remaining, byName));
+		const picked = byName.get(pick);
+		if (!picked) throw new Error(`[arc] internal: ordered module "${pick}" is missing from the index`);
+		ordered.push(picked);
+		remaining.delete(pick);
+		for (const dependent of dependents.get(pick) ?? []) pendingDeps.set(dependent, (pendingDeps.get(dependent) ?? 1) - 1);
+	}
+	return ordered;
+}
+/** Walk the still-unordered subgraph for one concrete cycle path. */
+function describeModuleCycle(remaining, byName) {
+	const stack = [];
+	const onStack = /* @__PURE__ */ new Set();
+	const done = /* @__PURE__ */ new Set();
+	let cycle = null;
+	const walk = (name) => {
+		if (cycle) return;
+		stack.push(name);
+		onStack.add(name);
+		for (const dep of byName.get(name)?.dependsOn ?? []) {
+			if (!remaining.has(dep)) continue;
+			if (onStack.has(dep)) {
+				cycle = [...stack.slice(stack.indexOf(dep)), dep];
+				return;
+			}
+			if (!done.has(dep)) walk(dep);
+			if (cycle) return;
+		}
+		onStack.delete(name);
+		stack.pop();
+		done.add(name);
+	};
+	for (const name of remaining) {
+		if (!done.has(name)) walk(name);
+		if (cycle) break;
+	}
+	return `[arc] module dependency cycle: ${cycle ? cycle.join(" → ") : [...remaining].join(", ")}. Modules cannot dependsOn each other circularly — break it with a shared module both point at, or wire the softer direction through an event/port instead of a hard dependsOn.`;
+}
+/**
+* Identity helper for authoring a typed module — mirrors `defineResource`.
+* Gives inference + a single obvious construction site; does no work.
+*
+* `TExports` is inferred from the `bootstrap` return value, so a module
+* author gets a typed public export for free:
+*
+* ```ts
+* export const accountingModule = (deps: Deps) =>
+*   defineModule({
+*     name: "accounting",
+*     bootstrap: async () => createAccountingEngine(deps), // TExports inferred
+*   });
+* ```
+*/
+function defineModule(module) {
+	return module;
+}
+function getModuleExports(fastify, name) {
+	const modules = fastify.arc?.modules;
+	if (!modules || !Object.hasOwn(modules, name)) {
+		const available = modules ? Object.keys(modules) : [];
+		throw new Error(`[arc] no public export recorded for module "${name}".\nA module's export is its bootstrap() return value; it is readable only AFTER that module's bootstrap ran (dependsOn / list order = init order).\nModules with recorded exports: ${available.length ? available.join(", ") : "(none)"}.`);
+	}
+	return modules[name];
+}
+//#endregion
 //#region src/factory/presets.ts
 /**
 * Production preset - strict security, performance optimized
@@ -182,8 +357,33 @@ const edgePreset = {
 /**
 * Get preset by name
 */
+/**
+* Worker preset (2.23) — the headless process role. Flips the HTTP surface
+* off and enables the `mountRoutes: false` primitive; runtime tiers
+* (events, jobs, schedules, caching, audit, usage) stay AS CONFIGURED by
+* the host's options. Per the preset contract, explicit narrow settings
+* win — `arcPlugins: { metrics: true }` re-enables Prometheus on workers,
+* `auth: {...}` keeps auth. See wiki/factory.md § createWorker.
+*/
+const workerPreset = {
+	mountRoutes: false,
+	auth: false,
+	helmet: false,
+	cors: false,
+	rateLimit: false,
+	underPressure: false,
+	sensible: false,
+	arcPlugins: {
+		requestId: false,
+		health: false,
+		sse: false,
+		metrics: false,
+		gracefulShutdown: true
+	}
+};
 function getPreset(name) {
 	switch (name) {
+		case "worker": return workerPreset;
 		case "production": return productionPreset;
 		case "development": return developmentPreset;
 		case "testing": return testingPreset;
@@ -296,7 +496,7 @@ async function registerAuth(fastify, config, trackPlugin) {
 	}
 	switch (authConfig.type) {
 		case "betterAuth": {
-			const { plugin, openapi } = authConfig.betterAuth;
+			const { plugin, openapi } = typeof authConfig.betterAuth === "function" ? await authConfig.betterAuth() : authConfig.betterAuth;
 			await fastify.register(plugin);
 			trackPlugin("auth-better-auth");
 			const arc = fastify.arc;
@@ -344,11 +544,20 @@ async function registerElevation(fastify, config, trackPlugin) {
 }
 /**
 * Register error handler plugin (opt-out).
+*
+* `moduleErrorMappers` — mappers shipped by composed arc modules
+* (`defineModule({ errorMappers })`), appended AFTER host-declared mappers
+* so host config keeps priority. Collected by `createApp` from the
+* pre-resolved module graph.
 */
-async function registerErrorHandler(fastify, config, trackPlugin) {
+async function registerErrorHandler(fastify, config, trackPlugin, moduleErrorMappers) {
 	if (config.errorHandler === false) return;
-	const { errorHandlerPlugin } = await import("./errorHandler-Dxf6P_kV.mjs").then((n) => n.r);
-	const errorOpts = typeof config.errorHandler === "object" ? config.errorHandler : { includeStack: config.preset !== "production" };
+	const { errorHandlerPlugin } = await import("./errorHandler-BTzXSwIg.mjs").then((n) => n.r);
+	let errorOpts = typeof config.errorHandler === "object" ? config.errorHandler : { includeStack: config.preset !== "production" };
+	if (moduleErrorMappers && moduleErrorMappers.length > 0) errorOpts = {
+		...errorOpts,
+		errorMappers: [...errorOpts.errorMappers ?? [], ...moduleErrorMappers]
+	};
 	await fastify.register(errorHandlerPlugin, errorOpts);
 	trackPlugin("arc-error-handler", errorOpts);
 	fastify.log.debug("Arc error handler enabled");
@@ -384,143 +593,15 @@ function createOptionalAuthenticate(authenticate) {
 	};
 }
 //#endregion
-//#region src/factory/module.ts
-/**
-* Resolve any module-input form to a concrete `ArcModule`. A thunk is invoked
-* (this is where a dynamic `import()` fires); a promise (or plain module) is
-* awaited. Called once per module at the start of the bootstrap phase.
-*/
-async function resolveModule(input) {
-	const resolved = typeof input === "function" ? await input() : await input;
-	if (!resolved || typeof resolved !== "object" || typeof resolved.name !== "string") throw new Error("[arc] a `modules` entry resolved to something that is not an ArcModule (expected an object with a string `name`). Check dynamic-import thunks return `createXModule(deps)` (or the module object), not the namespace.");
-	return resolved;
-}
-/**
-* Order modules for composition by their `dependsOn` edges — a STABLE
-* topological sort. Called once at the start of the bootstrap phase; every
-* subsequent phase (bootstrap, resources, afterResources, and reverse-order
-* onClose) iterates the returned list, so a module's declared dependencies are
-* always composed before it.
-*
-* "Stable" = modules with no edge between them keep their original list order,
-* so declaring `dependsOn` on one module never silently reorders an unrelated
-* one. Backward compatible: a `modules` array with NO `dependsOn` anywhere is
-* returned unchanged.
-*
-* Fail-fast — throws (never reorders past a broken contract) on:
-*   - duplicate module names (the name is the graph key)
-*   - a `dependsOn` name not present in the composed set
-*   - a self-reference (`dependsOn` includes the module's own name)
-*   - a dependency cycle (reports the concrete `a → b → … → a` path)
-*/
-function orderModules(modules) {
-	const byName = /* @__PURE__ */ new Map();
-	for (const m of modules) {
-		if (byName.has(m.name)) throw new Error(`[arc] Duplicate module name "${m.name}" — composed twice; check your modules array.`);
-		byName.set(m.name, m);
-	}
-	for (const m of modules) for (const dep of m.dependsOn ?? []) {
-		if (dep === m.name) throw new Error(`[arc] module "${m.name}" dependsOn itself — remove the self-reference.`);
-		if (!byName.has(dep)) throw new Error(`[arc] module "${m.name}" dependsOn "${dep}", which is not composed. Add the "${dep}" module to createApp({ modules }) (before this one is fine — arc orders them), or drop the dependency. Composed modules: ${[...byName.keys()].join(", ") || "(none)"}.`);
-	}
-	if (modules.every((m) => !m.dependsOn || m.dependsOn.length === 0)) return [...modules];
-	const originalIndex = /* @__PURE__ */ new Map();
-	let nextIndex = 0;
-	for (const m of modules) originalIndex.set(m.name, nextIndex++);
-	const pendingDeps = new Map(modules.map((m) => [m.name, (m.dependsOn ?? []).length]));
-	const dependents = /* @__PURE__ */ new Map();
-	for (const m of modules) for (const dep of m.dependsOn ?? []) {
-		const list = dependents.get(dep);
-		if (list) list.push(m.name);
-		else dependents.set(dep, [m.name]);
-	}
-	const ordered = [];
-	const remaining = new Set(modules.map((m) => m.name));
-	while (remaining.size > 0) {
-		let pick;
-		let pickIndex = Number.POSITIVE_INFINITY;
-		for (const name of remaining) {
-			if (pendingDeps.get(name) !== 0) continue;
-			const index = originalIndex.get(name) ?? Number.POSITIVE_INFINITY;
-			if (index < pickIndex) {
-				pick = name;
-				pickIndex = index;
-			}
-		}
-		if (pick === void 0) throw new Error(describeModuleCycle(remaining, byName));
-		const picked = byName.get(pick);
-		if (!picked) throw new Error(`[arc] internal: ordered module "${pick}" is missing from the index`);
-		ordered.push(picked);
-		remaining.delete(pick);
-		for (const dependent of dependents.get(pick) ?? []) pendingDeps.set(dependent, (pendingDeps.get(dependent) ?? 1) - 1);
-	}
-	return ordered;
-}
-/** Walk the still-unordered subgraph for one concrete cycle path. */
-function describeModuleCycle(remaining, byName) {
-	const stack = [];
-	const onStack = /* @__PURE__ */ new Set();
-	const done = /* @__PURE__ */ new Set();
-	let cycle = null;
-	const walk = (name) => {
-		if (cycle) return;
-		stack.push(name);
-		onStack.add(name);
-		for (const dep of byName.get(name)?.dependsOn ?? []) {
-			if (!remaining.has(dep)) continue;
-			if (onStack.has(dep)) {
-				cycle = [...stack.slice(stack.indexOf(dep)), dep];
-				return;
-			}
-			if (!done.has(dep)) walk(dep);
-			if (cycle) return;
-		}
-		onStack.delete(name);
-		stack.pop();
-		done.add(name);
-	};
-	for (const name of remaining) {
-		if (!done.has(name)) walk(name);
-		if (cycle) break;
-	}
-	return `[arc] module dependency cycle: ${cycle ? cycle.join(" → ") : [...remaining].join(", ")}. Modules cannot dependsOn each other circularly — break it with a shared module both point at, or wire the softer direction through an event/port instead of a hard dependsOn.`;
-}
-/**
-* Identity helper for authoring a typed module — mirrors `defineResource`.
-* Gives inference + a single obvious construction site; does no work.
-*
-* `TExports` is inferred from the `bootstrap` return value, so a module
-* author gets a typed public export for free:
-*
-* ```ts
-* export const accountingModule = (deps: Deps) =>
-*   defineModule({
-*     name: "accounting",
-*     bootstrap: async () => createAccountingEngine(deps), // TExports inferred
-*   });
-* ```
-*/
-function defineModule(module) {
-	return module;
-}
-function getModuleExports(fastify, name) {
-	const modules = fastify.arc?.modules;
-	if (!modules || !Object.hasOwn(modules, name)) {
-		const available = modules ? Object.keys(modules) : [];
-		throw new Error(`[arc] no public export recorded for module "${name}".\nA module's export is its bootstrap() return value; it is readable only AFTER that module's bootstrap ran (dependsOn / list order = init order).\nModules with recorded exports: ${available.length ? available.join(", ") : "(none)"}.`);
-	}
-	return modules[name];
-}
-//#endregion
 //#region src/factory/registerResources.ts
 function isResourcesFactory(value) {
 	return typeof value === "function";
 }
 /** Register a single resource with descriptive error on failure. */
-async function registerOne(parent, resource) {
+async function registerOne(parent, resource, mountRoutes) {
 	const name = resource.name ?? "unknown";
 	try {
-		await parent.register(resource.toPlugin());
+		await parent.register(resource.toPlugin(), mountRoutes === false ? { arcMountRoutes: false } : {});
 	} catch (err) {
 		const rawMsg = err instanceof Error ? err.message : String(err);
 		const stripped = rawMsg.replace(new RegExp(`^Resource "${name}"\\s*`), "").replace(/\.+\s*$/, "");
@@ -553,7 +634,7 @@ async function registerOne(parent, resource) {
 *                                  THEN app onClose, in ONE hook so module
 *                                  teardown runs before shared infra closes.
 */
-async function registerResources(fastify, config) {
+async function registerResources(fastify, config, preResolvedModules) {
 	if (config.preset === "production") {
 		if (config.strictResources === void 0) config = {
 			...config,
@@ -564,7 +645,7 @@ async function registerResources(fastify, config) {
 			strictResourceDir: true
 		};
 	}
-	const modules = orderModules(await Promise.all((config.modules ?? []).map((m) => resolveModule(m))));
+	const modules = preResolvedModules ?? orderModules(await Promise.all((config.modules ?? []).map((m) => resolveModule(m))));
 	if (config.plugins) {
 		await config.plugins(fastify);
 		fastify.log.debug("Custom plugins registered");
@@ -617,7 +698,7 @@ async function registerResources(fastify, config) {
 	let discoveryPath;
 	let discoveryYieldedZero = false;
 	if (resolvedResources === void 0 && config.resourceDir) {
-		const { loadResources } = await import("./loadResources-B8UmpITt.mjs").then((n) => n.n);
+		const { loadResources } = await import("./loadResources-DpU8pfjV.mjs").then((n) => n.n);
 		const { resolve, dirname } = await import("node:path");
 		const { fileURLToPath } = await import("node:url");
 		const rawDir = config.resourceDir;
@@ -631,6 +712,16 @@ async function registerResources(fastify, config) {
 		}
 		resolvedResources = discovered;
 	}
+	if (modules.length && resolvedResources && resolvedResources.length > 0) {
+		const owned = /* @__PURE__ */ new Set();
+		for (const m of modules) for (const name of m.owns ?? []) owned.add(name);
+		if (owned.size > 0) {
+			const before = resolvedResources.length;
+			resolvedResources = resolvedResources.filter((r) => !(r.name != null && owned.has(r.name)));
+			const dropped = before - resolvedResources.length;
+			if (dropped > 0) fastify.log.debug(`[arc] ${dropped} app resource(s) superseded by module owns() — the module version registers instead`);
+		}
+	}
 	if (modules.length) {
 		const moduleResources = [];
 		for (const m of modules) {
@@ -659,11 +750,11 @@ async function registerResources(fastify, config) {
 		const root = [];
 		for (const resource of resolvedResources) if (resource.skipGlobalPrefix) root.push(resource);
 		else prefixed.push(resource);
-		for (const resource of root) await registerOne(fastify, resource);
+		for (const resource of root) await registerOne(fastify, resource, config.mountRoutes);
 		if (prefixed.length) if (config.resourcePrefix) await fastify.register(async (scoped) => {
-			for (const resource of prefixed) await registerOne(scoped, resource);
+			for (const resource of prefixed) await registerOne(scoped, resource, config.mountRoutes);
 		}, { prefix: config.resourcePrefix });
-		else for (const resource of prefixed) await registerOne(fastify, resource);
+		else for (const resource of prefixed) await registerOne(fastify, resource, config.mountRoutes);
 		const names = resolvedResources.map((r) => r.name ?? "?").join(", ");
 		const prefix = config.resourcePrefix ? ` (prefix: ${config.resourcePrefix})` : "";
 		fastify.log.info(`${resolvedResources.length} resource(s) registered${prefix}: ${names}`);
@@ -700,42 +791,69 @@ async function registerResources(fastify, config) {
 	});
 }
 //#endregion
-//#region src/factory/registerSecurity.ts
+//#region src/factory/security/cors.ts
 /**
-* Translate `skipPaths` sugar into a `@fastify/rate-limit` `allowList`
-* function. A user-supplied `allowList` (array of IPs or function) is
-* preserved and OR-ed with the path match.
+* Headers ARC ITSELF reads from cross-origin requests. Auto-merged into a
+* host-declared CORS `allowedHeaders` allow-list (2.22) so hosts never
+* enumerate framework internals. Lowercase — header names are
+* case-insensitive and @fastify/cors joins them verbatim.
 */
-function buildRateLimitOpts(input) {
-	const { skipPaths, allowList, ...rest } = input;
-	if (!skipPaths || skipPaths.length === 0) return allowList === void 0 ? rest : {
-		...rest,
-		allowList
-	};
-	const matchesPath = compilePathMatcher(skipPaths);
-	const combined = async (req, key) => {
-		const path = (req.url ?? "").split("?", 1)[0] ?? "";
-		if (matchesPath(path)) return true;
-		if (typeof allowList === "function") return await allowList(req, key);
-		if (Array.isArray(allowList)) return allowList.includes(key);
-		return false;
-	};
+const ARC_PROTOCOL_HEADERS = [
+	"x-organization-id",
+	"x-arc-scope",
+	"x-request-id"
+];
+/**
+* Response headers ARC'S OWN auth protocol emits that cross-origin JS MUST
+* be able to read. Better Auth's bearer plugin returns the session token in
+* `set-auth-token` — without exposing it, cross-origin clients (Capacitor /
+* Ionic WebViews at `https://localhost`, cross-domain SPAs) complete the
+* login POST but can never READ the token, so bearer auth silently dies
+* (login appears to succeed, then every request is unauthenticated).
+* Unlike `allowedHeaders`, an UNSET `exposedHeaders` is NOT safe — CORS
+* exposes nothing beyond the safelist by default — so this is always
+* merged, creating the list when the host declared none.
+*/
+const ARC_EXPOSED_HEADERS = ["set-auth-token"];
+/**
+* Default `Access-Control-Max-Age` (seconds) when the host didn't set one.
+* Arc's CORS method/header lists are static per deploy, so letting browsers
+* cache the preflight kills the extra OPTIONS round-trip on every request —
+* on high-latency links (mobile webviews) that's a visible chunk of every
+* API call. Browsers clamp internally (Chromium 2h, Firefox 24h).
+*/
+const DEFAULT_CORS_MAX_AGE = 86400;
+/**
+* Resolve the host's CORS config into `@fastify/cors` options + warnings.
+* Throws on the one configuration arc refuses to ship (see module header).
+* Callers decide only HOW to surface warnings — the policy is all here.
+*/
+function resolveCorsOptions(config) {
+	const corsOptions = { ...config.cors ?? {} };
+	const warnings = [];
+	const originDeclared = "origin" in corsOptions && corsOptions.origin !== void 0;
+	if (config.preset === "production" && !originDeclared) warnings.push("CORS origin is not explicitly configured in production. Browser apps: set cors.origin to allowed domains (e.g. ['https://app.example.com']) with credentials: true. Server-to-server / API-key services: cors: { origin: '*', credentials: false } OR cors: false to disable. Tip: when wiring cors.origin from an env var, fail fast on missing (`if (!process.env.ALLOWED_ORIGINS) throw ...`) instead of letting `undefined` slip through.");
+	if (corsOptions.credentials === true && corsOptions.origin === "*") throw new Error("[Arc] cors: `origin: '*'` cannot be combined with `credentials: true`.\nReflecting arbitrary origins with credentials lets any website read authenticated responses (CSRF-adjacent data theft).\nFix one of:\n  • cors: { origin: ['https://app.example.com'], credentials: true }  — explicit allow-list\n  • cors: { origin: /\\.example\\.com$/, credentials: true }            — pattern allow-list\n  • cors: { origin: '*', credentials: false }                         — public, uncredentialed API");
+	if (Array.isArray(corsOptions.allowedHeaders)) {
+		const allowed = [...corsOptions.allowedHeaders];
+		const declared = new Set(allowed.map((h) => h.toLowerCase()));
+		for (const arcHeader of ARC_PROTOCOL_HEADERS) if (!declared.has(arcHeader)) allowed.push(arcHeader);
+		corsOptions.allowedHeaders = allowed;
+	}
+	{
+		const exposed = Array.isArray(corsOptions.exposedHeaders) ? [...corsOptions.exposedHeaders] : typeof corsOptions.exposedHeaders === "string" ? corsOptions.exposedHeaders.split(",").map((h) => h.trim()) : [];
+		const declared = new Set(exposed.map((h) => h.toLowerCase()));
+		for (const arcHeader of ARC_EXPOSED_HEADERS) if (!declared.has(arcHeader)) exposed.push(arcHeader);
+		corsOptions.exposedHeaders = exposed;
+	}
+	if (corsOptions.maxAge === void 0) corsOptions.maxAge = DEFAULT_CORS_MAX_AGE;
 	return {
-		...rest,
-		allowList: combined
-	};
-}
-function compilePathMatcher(patterns) {
-	const prefixes = [];
-	const exact = /* @__PURE__ */ new Set();
-	for (const p of patterns) if (p.endsWith("*")) prefixes.push(p.slice(0, -1));
-	else exact.add(p);
-	return (path) => {
-		if (exact.has(path)) return true;
-		for (const pre of prefixes) if (path.startsWith(pre)) return true;
-		return false;
+		options: corsOptions,
+		warnings
 	};
 }
+//#endregion
+//#region src/factory/security/pluginLoader.ts
 const PLUGIN_REGISTRY = {
 	cors: {
 		package: "@fastify/cors",
@@ -784,6 +902,77 @@ async function loadPlugin(name, logger) {
 		throw new Error(`Failed to load plugin '${name}': ${err.message}`);
 	}
 }
+//#endregion
+//#region src/factory/security/rateLimit.ts
+/** "Unlimited" as a number — @fastify/rate-limit's `max` fn must return one. */
+const UNLIMITED_MAX = Number.MAX_SAFE_INTEGER;
+/**
+* Expand `plan` sugar (2.22) into `@fastify/rate-limit` primitives: a
+* per-request async `max` that resolves the caller's plan once (cached
+* per request), and — unless the host supplied one — the tenant
+* keyGenerator so buckets follow actors, not IPs. Unknown plans and
+* resolver errors fall back to `plan.default`, then the global `max`
+* (fail-safe: never fail-open to unlimited).
+*/
+function buildPlanOpts(rest, plan) {
+	const globalMax = typeof rest.max === "number" ? rest.max : 100;
+	const fallbackLimit = plan.default !== void 0 ? plan.limits[plan.default] ?? { max: globalMax } : { max: globalMax };
+	const planCache = /* @__PURE__ */ new WeakMap();
+	const limitOf = (req) => {
+		let cached = planCache.get(req);
+		if (!cached) {
+			cached = Promise.resolve().then(() => plan.resolve(req)).then((name) => name !== void 0 ? plan.limits[name] ?? fallbackLimit : fallbackLimit).catch(() => fallbackLimit);
+			planCache.set(req, cached);
+		}
+		return cached;
+	};
+	return {
+		...rest,
+		max: async (req, _key) => {
+			const limit = await limitOf(req);
+			return limit === false ? UNLIMITED_MAX : limit.max;
+		},
+		keyGenerator: rest.keyGenerator ?? createTenantKeyGenerator()
+	};
+}
+/**
+* Translate `skipPaths` sugar into a `@fastify/rate-limit` `allowList`
+* function. A user-supplied `allowList` (array of IPs or function) is
+* preserved and OR-ed with the path match.
+*/
+function buildRateLimitOpts(input) {
+	const { skipPaths, allowList, plan, ...bare } = input;
+	const rest = plan ? buildPlanOpts(bare, plan) : bare;
+	if (!skipPaths || skipPaths.length === 0) return allowList === void 0 ? rest : {
+		...rest,
+		allowList
+	};
+	const matchesPath = compilePathMatcher(skipPaths);
+	const combined = async (req, key) => {
+		const path = (req.url ?? "").split("?", 1)[0] ?? "";
+		if (matchesPath(path)) return true;
+		if (typeof allowList === "function") return await allowList(req, key);
+		if (Array.isArray(allowList)) return allowList.includes(key);
+		return false;
+	};
+	return {
+		...rest,
+		allowList: combined
+	};
+}
+function compilePathMatcher(patterns) {
+	const prefixes = [];
+	const exact = /* @__PURE__ */ new Set();
+	for (const p of patterns) if (p.endsWith("*")) prefixes.push(p.slice(0, -1));
+	else exact.add(p);
+	return (path) => {
+		if (exact.has(path)) return true;
+		for (const pre of prefixes) if (path.startsWith(pre)) return true;
+		return false;
+	};
+}
+//#endregion
+//#region src/factory/registerSecurity.ts
 /**
 * Register security plugins (Helmet, CORS, Rate Limiting).
 * All enabled by default — set to `false` to opt out.
@@ -796,10 +985,8 @@ async function registerSecurityPlugins(fastify, config) {
 	} else fastify.log.warn("Helmet disabled - security headers not applied");
 	if (config.cors !== false) {
 		const cors = await loadPlugin("cors");
-		const corsOptions = { ...config.cors ?? {} };
-		const originDeclared = "origin" in corsOptions && corsOptions.origin !== void 0;
-		if (config.preset === "production" && !originDeclared) fastify.log.warn("CORS origin is not explicitly configured in production. Browser apps: set cors.origin to allowed domains (e.g. ['https://app.example.com']) with credentials: true. Server-to-server / API-key services: cors: { origin: '*', credentials: false } OR cors: false to disable. Tip: when wiring cors.origin from an env var, fail fast on missing (`if (!process.env.ALLOWED_ORIGINS) throw ...`) instead of letting `undefined` slip through.");
-		if (corsOptions.credentials && corsOptions.origin === "*") corsOptions.origin = true;
+		const { options: corsOptions, warnings } = resolveCorsOptions(config);
+		for (const warning of warnings) fastify.log.warn(warning);
 		await fastify.register(cors, corsOptions);
 		fastify.log.debug("CORS enabled");
 	} else fastify.log.warn("CORS disabled");
@@ -835,13 +1022,17 @@ async function registerUtilityPlugins(fastify, config) {
 	if (config.multipart !== false) {
 		const multipart = await loadPlugin("multipart", fastify.log);
 		if (multipart) {
+			const hostMultipart = typeof config.multipart === "object" && config.multipart !== null ? config.multipart : {};
 			await fastify.register(multipart, {
+				throwFileSizeLimit: true,
+				...hostMultipart,
 				limits: {
 					fileSize: 10 * 1024 * 1024,
-					files: 10
-				},
-				throwFileSizeLimit: true,
-				...config.multipart
+					files: 10,
+					fields: 100,
+					parts: 120,
+					...hostMultipart.limits
+				}
 			});
 			fastify.log.debug("Multipart (file uploads) enabled");
 		}
@@ -1006,7 +1197,7 @@ Missing:\n${lines}\n\nFix: pass durable adapters under \`stores\`, or use runtim
 *
 * Boot order:
 * ```
-* 0. Logger, validation, preset merge
+* 0. Logger, validation → beforeBoot() (DB connect etc.), preset merge
 * 1. Create Fastify instance
 * 2. Security plugins (Helmet, CORS, Rate Limit) — opt-out
 * 3. Utility plugins (Under Pressure, Sensible, Multipart, Raw Body)
@@ -1021,21 +1212,26 @@ Missing:\n${lines}\n\nFix: pass durable adapters under \`stores\`, or use runtim
 * ```
 */
 async function createApp(options) {
-	if (options.debug !== void 0 && options.debug !== false) {
-		const { configureArcLogger } = await import("./logger/index.mjs");
-		configureArcLogger({ debug: options.debug });
-	}
+	if (options.debug !== void 0 && options.debug !== false) configureArcLogger({ debug: options.debug });
 	validateAuthOptions(options);
 	const deferredWarnings = validateDistributedRuntime(options);
+	if (options.beforeBoot) await options.beforeBoot();
 	const config = {
 		...options.preset ? getPreset(options.preset) : {},
 		...options
 	};
+	const resolvedModules = orderModules(await Promise.all((config.modules ?? []).map((m) => resolveModule(m))));
+	const moduleErrorMappers = resolvedModules.flatMap((m) => m.errorMappers ?? []);
+	const resolvedLogger = resolveLoggerConfig(config.logger);
 	const fastify = Fastify({
-		logger: resolveLoggerConfig(config.logger),
+		logger: resolvedLogger,
+		genReqId: createRequestIdGenerator(),
 		trustProxy: config.trustProxy ?? false,
 		pluginTimeout: config.pluginTimeout ?? 1e4,
 		...config.bodyLimit !== void 0 ? { bodyLimit: config.bodyLimit } : {},
+		...config.requestTimeout !== void 0 ? { requestTimeout: config.requestTimeout } : {},
+		...config.connectionTimeout !== void 0 ? { connectionTimeout: config.connectionTimeout } : {},
+		...config.keepAliveTimeout !== void 0 ? { keepAliveTimeout: config.keepAliveTimeout } : {},
 		allowErrorHandlerOverride: true,
 		routerOptions: {
 			querystringParser: (str) => qs.parse(str, {
@@ -1054,6 +1250,10 @@ async function createApp(options) {
 			keywords: ["example", ...config.ajv?.keywords ?? []]
 		} }
 	});
+	if (resolvedLogger !== false) configureArcLogger({
+		...options.debug !== void 0 && options.debug !== false ? { debug: options.debug } : {},
+		writer: createPinoWriter(fastify.log)
+	});
 	for (const warning of deferredWarnings) fastify.log.warn(warning);
 	if (config.typeProvider === "typebox") try {
 		const { TypeBoxValidatorCompiler } = await import("@fastify/type-provider-typebox");
@@ -1061,12 +1261,10 @@ async function createApp(options) {
 	} catch {
 		fastify.log.warn("typeProvider: \"typebox\" requested but @fastify/type-provider-typebox is not installed.");
 	}
-	const sjp = await import("secure-json-parse");
 	fastify.removeContentTypeParser("application/json");
 	fastify.addContentTypeParser("application/json", { parseAs: "string" }, (_req, body, done) => {
-		if (!body || body.length === 0) return done(null, void 0);
 		try {
-			done(null, sjp.parse(body));
+			done(null, parseJsonBody(body));
 		} catch (err) {
 			done(err);
 		}
@@ -1086,8 +1284,8 @@ async function createApp(options) {
 	decorateRequestScope(fastify);
 	await registerAuth(fastify, config, trackPlugin);
 	await registerElevation(fastify, config, trackPlugin);
-	await registerErrorHandler(fastify, config, trackPlugin);
-	await registerResources(fastify, config);
+	await registerErrorHandler(fastify, config, trackPlugin, moduleErrorMappers);
+	await registerResources(fastify, config, resolvedModules);
 	if (config.replyHelpers) {
 		const { replyHelpersPlugin } = await import("./replyHelpers-67tRawQZ.mjs").then((n) => n.n);
 		await fastify.register(replyHelpersPlugin);
@@ -1140,4 +1338,4 @@ const ArcFactory = {
 	}
 };
 //#endregion
-export { getModuleExports as a, developmentPreset as c, productionPreset as d, testingPreset as f, defineModule as i, edgePreset as l, createApp as n, orderModules as o, createApp_exports as r, resolveModule as s, ArcFactory as t, getPreset as u };
+export { edgePreset as a, testingPreset as c, getModuleExports as d, orderModules as f, preloadResourcesAsync as h, developmentPreset as i, workerPreset as l, preloadResources as m, createApp as n, getPreset as o, resolveModule as p, createApp_exports as r, productionPreset as s, ArcFactory as t, defineModule as u };