@classytic/arc 2.21.0 → 2.22.0

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

@@ -1,8 +1,55 @@
 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
@@ -310,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;
@@ -424,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;
@@ -480,7 +552,7 @@ async function registerElevation(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 { 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,
@@ -526,10 +598,10 @@ 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*$/, "");
@@ -640,6 +712,16 @@ async function registerResources(fastify, config, preResolvedModules) {
 		}
 		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) {
@@ -668,11 +750,11 @@ async function registerResources(fastify, config, preResolvedModules) {
 		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}`);
@@ -709,42 +791,69 @@ async function registerResources(fastify, config, preResolvedModules) {
 	});
 }
 //#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",
@@ -793,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.
@@ -805,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");
@@ -844,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");
 		}
@@ -1030,10 +1212,7 @@ 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();
@@ -1043,11 +1222,16 @@ async function createApp(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, {
@@ -1066,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");
@@ -1073,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);
 		}
@@ -1152,4 +1338,4 @@ const ArcFactory = {
 	}
 };
 //#endregion
-export { edgePreset as a, testingPreset as c, orderModules as d, resolveModule as f, developmentPreset as i, defineModule as l, createApp as n, getPreset as o, createApp_exports as r, productionPreset as s, ArcFactory as t, getModuleExports 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 };

package/dist/docs/index.d.mts

@@ -1,4 +1,4 @@
-import { p as RegistryEntry } from "../index-Dtrj6XZk.mjs";
+import { p as RegistryEntry } from "../index-DbtgCOCj.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-BE6wFpYv.mjs";
 import { FastifyPluginAsync } from "fastify";
 //#region src/docs/openapi/types.d.ts

package/dist/docs/index.mjs

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

package/dist/encryption/index.mjs

@@ -1,3 +1,5 @@
+import { t as ArcError } from "../errors-DkO8Nk6-.mjs";
+import { t as parseJsonBody } from "../jsonBody-BlzAoGCe.mjs";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/encryption/fieldCipher.ts
@@ -182,17 +184,19 @@ const encryptionPlugin = async (fastify, opts) => {
 	}
 	if (decryptRequests) fastify.addContentTypeParser(contentType, { parseAs: "string" }, async (request, body) => {
 		const provider = keyProvider;
-		const plaintext = await jweDecrypt(body, (kid) => provider.decryptionKey(kid, { request }), allowedAlgs, allowedEncs);
-		request.requestDecrypted = true;
-		if (plaintext.length === 0) return void 0;
+		let plaintext;
 		try {
-			return JSON.parse(plaintext);
+			plaintext = await jweDecrypt(body, (kid) => provider.decryptionKey(kid, { request }), allowedAlgs, allowedEncs);
 		} catch (cause) {
-			throw Object.assign(/* @__PURE__ */ new Error("[arc/encryption] decrypted request body is not valid JSON"), {
+			throw new ArcError("Invalid encrypted request body", {
+				code: "arc.bad_request",
 				statusCode: 400,
 				cause
 			});
 		}
+		request.requestDecrypted = true;
+		if (plaintext.length === 0) return void 0;
+		return parseJsonBody(plaintext, "Decrypted request body is not valid JSON");
 	});
 	fastify.addHook("preSerialization", async (request, reply, payload) => {
 		const directive = resolveDirective(request, defaultMode, fallback);

package/dist/{errorHandler-Dxf6P_kV.mjs → errorHandler-BTzXSwIg.mjs}

@@ -91,7 +91,7 @@ function mongooseValidationDetails(errors) {
 }
 async function errorHandlerPluginFn(fastify, options = {}) {
 	const isProduction = process.env.NODE_ENV === "production";
-	const { includeStack = !isProduction, onError, errorMap = {}, errorMappers = [], isDuplicateKeyError = defaultIsDuplicateKeyError } = options;
+	const { includeStack = !isProduction, exposeInternalMessages = !isProduction, onError, errorMap = {}, errorMappers = [], isDuplicateKeyError = defaultIsDuplicateKeyError } = options;
 	fastify.setErrorHandler(async (error, request, reply) => {
 		if (onError) try {
 			await onError(error, request);
@@ -112,6 +112,7 @@ async function errorHandlerPluginFn(fastify, options = {}) {
 			...Object.keys(meta).length > 0 ? { meta } : {}
 		};
 		const status = wire.status ?? 500;
+		if (status >= 500 && wire.code === "arc.internal_error" && !exposeInternalMessages) wire.message = "Internal Server Error";
 		if (status >= 500) request.log.error({
 			err: error,
 			status
@@ -120,11 +121,31 @@ async function errorHandlerPluginFn(fastify, options = {}) {
 			err: error,
 			status
 		}, "Client error");
-		if (isArcError(error) && error.cause) request.log.error({ cause: error.cause }, "Error cause chain");
+		if (isArcError(error) && error.cause) {
+			const causeLevel = status >= 500 ? "error" : "warn";
+			request.log[causeLevel]({ cause: error.cause }, "Error cause chain");
+		}
 		return reply.status(status).send(wire);
 	});
 }
 /**
+* Is `code` a caller-defined DOMAIN error code that is safe to surface on the
+* wire, as opposed to a framework/runtime code that must never leak?
+*
+* Rejects Fastify internals (`FST_*`) and Node system errnos (`ECONNREFUSED`,
+* `ENOENT`, …). Domain codes in the wild use separators (`PURCHASE_NOT_FOUND`,
+* `access.forbidden`) so they pass; a bare all-caps single word that collides
+* with the Node-errno shape (e.g. `EXPIRED`) is conservatively treated as a
+* runtime code — use a separatored code (`TOKEN_EXPIRED`) to surface it, or
+* throw via `createDomainError` which bypasses this heuristic entirely.
+*/
+function isDomainErrorCode(code) {
+	if (typeof code !== "string" || code.length === 0) return false;
+	if (code.startsWith("FST_")) return false;
+	if (/^E[A-Z]{2,}$/.test(code)) return false;
+	return true;
+}
+/**
 * Single-pass error → `ErrorContract` classifier. Dispatch order is fixed:
 *
 *   1. Class-based mappers (`instanceof`) — user-registered domain errors
@@ -167,7 +188,7 @@ function classify(error, ctx) {
 		};
 	}
 	if (typeof fastifyErr.statusCode === "number") return {
-		code: statusToArcCode(fastifyErr.statusCode),
+		code: (isDomainErrorCode(fastifyErr.code) ? fastifyErr.code : void 0) ?? statusToArcCode(fastifyErr.statusCode),
 		message: error.message || "Error",
 		status: fastifyErr.statusCode
 	};

package/dist/{errorHandler-B0e-bq-O.d.mts → errorHandler-C6yv4ZTW.d.mts}

@@ -18,6 +18,19 @@ interface ErrorMapper<T extends Error = Error> {
 interface ErrorHandlerOptions {
   /** Include `meta.stack` on the wire (defaults to `NODE_ENV !== 'production'`). */
   includeStack?: boolean;
+  /**
+   * Ship the raw `error.message` of UNCLASSIFIED 500s on the wire
+   * (defaults to `NODE_ENV !== 'production'`).
+   *
+   * Only the `arc.internal_error` fallback is affected — an unclassified
+   * throw carries whatever some driver/library put in the message (connection
+   * strings, file paths, SQL fragments), which must not reach clients in
+   * production. Deliberate 5xx contracts are untouched: `ArcError` /
+   * domain-coded throws (`payment.gateway.timeout`, …) keep their message
+   * because the thrower chose it for the client. The raw message is always
+   * logged via `request.log.error({ err })` regardless of this flag.
+   */
+  exposeInternalMessages?: boolean;
   /** Custom callback fired for every error — log to Sentry / Datadog / etc. */
   onError?: (error: Error, request: FastifyRequest) => void | Promise<void>;
   /** Map by `error.name` string. Lower priority than `errorMappers`. */

package/dist/factory/index.d.mts

@@ -1,6 +1,7 @@
-import { a as getModuleExports, c as LoadResourcesOptions, d as loadResources, i as defineModule, l as ResourceLike, n as ArcModuleInput, o as orderModules, r as ArcModuleRegistry, s as resolveModule, t as ArcModule, u as ResourceModule } from "../module-WeuU5jfd.mjs";
-import "../fastify-augmentation-DafigGQp.mjs";
-import { a as CustomPluginAuthOption, c as RawBodyOptions, d as preloadResourcesAsync, i as CustomAuthenticatorOption, l as UnderPressureOptions, n as BetterAuthOption, o as JwtAuthOption, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as preloadResources } from "../types-DpxoNX5v.mjs";
+import { a as getModuleExports, c as LoadResourcesOptions, d as loadResources, i as defineModule, l as ResourceLike, n as ArcModuleInput, o as orderModules, r as ArcModuleRegistry, s as resolveModule, t as ArcModule, u as ResourceModule } from "../module-B4u10iOJ.mjs";
+import "../fastify-augmentation-9_fuetB4.mjs";
+import { a as AuthOption, c as CustomPluginAuthOption, d as preloadResourcesAsync, i as UnderPressureOptions, l as JwtAuthOption, n as MultipartOptions, o as BetterAuthOption, r as RawBodyOptions, s as CustomAuthenticatorOption, t as CreateAppOptions, u as preloadResources } from "../index-BEu4wjbL.mjs";
+import { g as HealthCheck } from "../versioning-DLwklPlG.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 //#region src/factory/createApp.d.ts
 /**
@@ -32,6 +33,29 @@ declare const ArcFactory: {
   testing(options: Omit<CreateAppOptions, "preset">): Promise<FastifyInstance>;
 };
 //#endregion
+//#region src/factory/createWorker.d.ts
+interface WorkerHealthOptions {
+  /** Port for the worker's ONLY listener (liveness/readiness probes). */
+  port: number;
+  /** Bind host. Default `0.0.0.0`. */
+  host?: string;
+  /** Readiness checks — same contract as the API role's healthPlugin. */
+  checks?: HealthCheck[];
+}
+interface CreateWorkerOptions {
+  /** Opt-in probe listener. Omit = the worker binds NOTHING. */
+  health?: WorkerHealthOptions;
+}
+interface ArcWorker {
+  /** The underlying Fastify instance (decorations, inject, logs). */
+  app: FastifyInstance;
+  /** Typed module-export accessor — same contract as `getModuleExports`. */
+  exports<TExports = unknown>(name: string): TExports;
+  /** Close app → module onClose (reverse) → app onClose. Idempotent. */
+  close(): Promise<void>;
+}
+declare function createWorker(options: CreateAppOptions, workerOptions?: CreateWorkerOptions): Promise<ArcWorker>;
+//#endregion
 //#region src/factory/edge.d.ts
 interface FetchHandlerOptions {
   /**
@@ -91,9 +115,6 @@ declare const testingPreset: Partial<CreateAppOptions>;
  * when using `toFetchHandler()` (routes through Fastify's `.inject()`).
  */
 declare const edgePreset: Partial<CreateAppOptions>;
-/**
- * Get preset by name
- */
-declare function getPreset(name: "production" | "development" | "testing" | "edge"): Partial<CreateAppOptions>;
+declare function getPreset(name: "production" | "development" | "testing" | "edge" | "worker"): Partial<CreateAppOptions>;
 //#endregion
-export { ArcFactory, type ArcModule, type ArcModuleInput, type ArcModuleRegistry, type AuthOption, type BetterAuthOption, type CreateAppOptions, type CustomAuthenticatorOption, type CustomPluginAuthOption, type FetchHandlerOptions, type JwtAuthOption, type LoadResourcesOptions, type MultipartOptions, type RawBodyOptions, type ResourceLike, type ResourceModule, type UnderPressureOptions, createApp, defineModule, developmentPreset, edgePreset, getModuleExports, getPreset, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveModule, testingPreset, toFetchHandler };
+export { ArcFactory, type ArcModule, type ArcModuleInput, type ArcModuleRegistry, type ArcWorker, type AuthOption, type BetterAuthOption, type CreateAppOptions, type CreateWorkerOptions, type CustomAuthenticatorOption, type CustomPluginAuthOption, type FetchHandlerOptions, type JwtAuthOption, type LoadResourcesOptions, type MultipartOptions, type RawBodyOptions, type ResourceLike, type ResourceModule, type UnderPressureOptions, type WorkerHealthOptions, createApp, createWorker, defineModule, developmentPreset, edgePreset, getModuleExports, getPreset, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveModule, testingPreset, toFetchHandler };

package/dist/factory/index.mjs

@@ -1,6 +1,37 @@
-import { n as preloadResourcesAsync, t as preloadResources } from "../preloadResources-CHw3_oA_.mjs";
-import { a as edgePreset, c as testingPreset, d as orderModules, f as resolveModule, i as developmentPreset, l as defineModule, n as createApp, o as getPreset, s as productionPreset, t as ArcFactory, u as getModuleExports } from "../createApp-Bi61XxqU.mjs";
+import { a as edgePreset, c as testingPreset, d as getModuleExports, f as orderModules, h as preloadResourcesAsync, i as developmentPreset, l as workerPreset, m as preloadResources, n as createApp, o as getPreset, p as resolveModule, s as productionPreset, t as ArcFactory, u as defineModule } from "../createApp-Ci7yG5gv.mjs";
+import { t as healthPlugin } from "../health-ScyjIVo5.mjs";
 import { t as loadResources } from "../loadResources-DpU8pfjV.mjs";
+//#region src/factory/createWorker.ts
+async function createWorker(options, workerOptions = {}) {
+	const { auth: _auth, helmet: _helmet, cors: _cors, rateLimit: _rateLimit, multipart: _multipart, rawBody: _rawBody, sensible: _sensible, underPressure: _underPressure, replyHelpers: _replyHelpers, ...runtimeOptions } = options;
+	const app = await createApp({
+		...runtimeOptions,
+		preset: "worker",
+		...runtimeOptions.arcPlugins ? { arcPlugins: {
+			...workerPreset.arcPlugins,
+			...runtimeOptions.arcPlugins
+		} } : {}
+	});
+	if (workerOptions.health) {
+		const { port, host = "0.0.0.0", checks = [] } = workerOptions.health;
+		await app.register(healthPlugin, { checks });
+		await app.listen({
+			port,
+			host
+		});
+	} else await app.ready();
+	let closed = false;
+	return {
+		app,
+		exports: (name) => getModuleExports(app, name),
+		close: async () => {
+			if (closed) return;
+			closed = true;
+			await app.close();
+		}
+	};
+}
+//#endregion
 //#region src/factory/edge.ts
 /**
 * Convert a Fastify app into a Web Standards fetch handler.
@@ -47,4 +78,4 @@ function toFetchHandler(app, options = {}) {
 	};
 }
 //#endregion
-export { ArcFactory, createApp, defineModule, developmentPreset, edgePreset, getModuleExports, getPreset, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveModule, testingPreset, toFetchHandler };
+export { ArcFactory, createApp, createWorker, defineModule, developmentPreset, edgePreset, getModuleExports, getPreset, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveModule, testingPreset, toFetchHandler };