@classytic/arc 2.18.5 → 2.20.0

package/dist/encryption/index.mjs

@@ -0,0 +1,270 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import fp from "fastify-plugin";
+//#region src/encryption/fieldCipher.ts
+/**
+* Field-level cipher — `node:crypto` AES-256-GCM, zero external deps.
+*
+* Used by `mode: 'fields'` to encrypt individual field values in place while
+* leaving the JSON structure intact. The envelope is an authenticated,
+* versioned, `kid`-tagged token:
+*
+*   arc.v1.<b64url(kid)>.<b64url(iv)>.<b64url(ciphertext)>.<b64url(tag)>
+*
+* This is NOT a hand-rolled cipher — it's the correct use of a vetted AEAD
+* primitive (AES-256-GCM): a fresh random 96-bit IV per operation (never
+* caller-supplied — IV reuse under GCM is catastrophic), authentication via
+* the GCM tag, and a version prefix so the format can evolve. Same shape, in
+* spirit, as MongoDB CSFLE's BSON-binary subtype-6 envelope. For
+* cross-vendor interop or asymmetric keys use `mode: 'jwe'` (RFC 7516)
+* instead.
+*/
+const ENVELOPE_PREFIX = "arc.v1";
+const IV_BYTES = 12;
+const KEY_BYTES = 32;
+function b64url(buf) {
+	return buf.toString("base64url");
+}
+function toKeyBuffer(key) {
+	if (Buffer.isBuffer(key)) {
+		if (key.length !== KEY_BYTES) throw new Error(`[arc/encryption] field-mode key must be ${KEY_BYTES} bytes (AES-256); got ${key.length}`);
+		return key;
+	}
+	if (key instanceof Uint8Array) return toKeyBuffer(Buffer.from(key));
+	throw new Error("[arc/encryption] field-mode key must be a 32-byte Buffer/Uint8Array. For asymmetric or cross-vendor encryption use mode: 'jwe'.");
+}
+/** Encrypt a UTF-8 string into the `arc.v1` field envelope. */
+function encryptField(plaintext, kid, key) {
+	const secret = toKeyBuffer(key);
+	const iv = randomBytes(IV_BYTES);
+	const cipher = createCipheriv("aes-256-gcm", secret, iv);
+	const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+	const tag = cipher.getAuthTag();
+	return [
+		ENVELOPE_PREFIX,
+		b64url(Buffer.from(kid, "utf8")),
+		b64url(iv),
+		b64url(ciphertext),
+		b64url(tag)
+	].join(".");
+}
+/** Returns the parsed envelope, or `null` when the token isn't `arc.v1`. */
+function parseFieldEnvelope(token) {
+	if (typeof token !== "string") return null;
+	const parts = token.split(".");
+	if (parts.length !== 6) return null;
+	const [v0, v1, kidPart, ivPart, ctPart, tagPart] = parts;
+	if (`${v0}.${v1}` !== ENVELOPE_PREFIX) return null;
+	if (kidPart === void 0 || ivPart === void 0 || ctPart === void 0 || tagPart === void 0) return null;
+	try {
+		return {
+			kid: Buffer.from(kidPart, "base64url").toString("utf8"),
+			iv: Buffer.from(ivPart, "base64url"),
+			ciphertext: Buffer.from(ctPart, "base64url"),
+			tag: Buffer.from(tagPart, "base64url")
+		};
+	} catch {
+		return null;
+	}
+}
+/** Decrypt a parsed `arc.v1` envelope with the resolved key. Throws on tamper. */
+function decryptField(envelope, key) {
+	const decipher = createDecipheriv("aes-256-gcm", toKeyBuffer(key), envelope.iv);
+	decipher.setAuthTag(envelope.tag);
+	return Buffer.concat([decipher.update(envelope.ciphertext), decipher.final()]).toString("utf8");
+}
+//#endregion
+//#region src/encryption/jose.ts
+let josePromise;
+/** Load `jose` once, caching the module. Throws an actionable error if absent. */
+async function loadJose() {
+	if (!josePromise) josePromise = import("jose").then((m) => m, (cause) => {
+		josePromise = void 0;
+		throw new Error("[arc/encryption] mode 'jwe' requires the optional peer dependency `jose`. Install it with `npm i jose`, or use mode: 'fields' (node:crypto, no dependency).", { cause });
+	});
+	return josePromise;
+}
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/** Encrypt a UTF-8 string into a JWE compact serialization. */
+async function jweEncrypt(plaintext, active, alg, enc) {
+	return new (await (loadJose())).CompactEncrypt(encoder.encode(plaintext)).setProtectedHeader({
+		alg: active.alg ?? alg,
+		enc,
+		kid: active.kid
+	}).encrypt(active.key);
+}
+/**
+* Decrypt a JWE compact string. `resolve` maps the header `kid` to a key;
+* the allowlists are enforced by `jose` so a malicious header can't downgrade
+* the algorithm.
+*/
+async function jweDecrypt(jwe, resolve, allowedAlgs, allowedEncs) {
+	const { plaintext } = await (await loadJose()).compactDecrypt(jwe, async (header) => {
+		if (!header.kid) throw new Error("[arc/encryption] inbound JWE is missing the `kid` header");
+		const key = await resolve(header.kid);
+		if (key === void 0) throw new Error(`[arc/encryption] no decryption key for kid '${header.kid}'`);
+		return key;
+	}, {
+		keyManagementAlgorithms: [...allowedAlgs],
+		contentEncryptionAlgorithms: [...allowedEncs]
+	});
+	return decoder.decode(plaintext);
+}
+//#endregion
+//#region src/encryption/resolver.ts
+function routeDirective(request) {
+	return (request.routeOptions?.config)?.arcExtensions?.encryption;
+}
+function finalize(directive, defaultMode) {
+	if (directive.enabled === false) return null;
+	return {
+		mode: directive.mode ?? defaultMode,
+		fields: directive.fields ?? []
+	};
+}
+/**
+* Resolve the active directive for a request, or `null` to skip encryption.
+*
+* @param request     incoming request (carries route config)
+* @param defaultMode plugin-level default mode
+* @param fallback    plugin-level `routes` matcher (optional)
+*/
+function resolveDirective(request, defaultMode, fallback) {
+	const declared = routeDirective(request);
+	if (declared) return finalize(declared, defaultMode);
+	if (fallback) {
+		const result = fallback(request);
+		if (result === true) return {
+			mode: defaultMode,
+			fields: []
+		};
+		if (result && typeof result === "object") return finalize(result, defaultMode);
+	}
+	return null;
+}
+//#endregion
+//#region src/encryption/encryptionPlugin.ts
+function getPath(obj, path) {
+	let cur = obj;
+	for (const seg of path.split(".")) {
+		if (cur === null || typeof cur !== "object") return void 0;
+		cur = cur[seg];
+	}
+	return cur;
+}
+function setPath(obj, path, value) {
+	const segs = path.split(".");
+	const last = segs[segs.length - 1];
+	if (last === void 0) return;
+	let cur = obj;
+	for (let i = 0; i < segs.length - 1; i++) {
+		const seg = segs[i];
+		if (seg === void 0) return;
+		const next = cur[seg];
+		if (next === null || typeof next !== "object") return;
+		cur = next;
+	}
+	cur[last] = value;
+}
+const encryptionPlugin = async (fastify, opts) => {
+	const { enabled = true, keyProvider, mode: defaultMode = "jwe", alg = "RSA-OAEP-256", enc = "A256GCM", routes: fallback, decryptRequests = true, contentType = "application/jose", responseContentType = "application/jose", flagHeader = "x-encrypted" } = opts;
+	fastify.decorateRequest("requestDecrypted", false);
+	fastify.decorateRequest("responseEncrypted", false);
+	if (enabled === false) {
+		fastify.log?.debug?.("[arc/encryption] disabled");
+		return;
+	}
+	if (!keyProvider) throw new Error("[arc/encryption] `keyProvider` is required when the plugin is enabled.");
+	const allowedAlgs = opts.allowedAlgs ?? [alg];
+	const allowedEncs = opts.allowedEncs ?? [enc];
+	function setFlag(reply) {
+		if (flagHeader) reply.header(flagHeader, "true");
+	}
+	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;
+		try {
+			return JSON.parse(plaintext);
+		} catch (cause) {
+			throw Object.assign(/* @__PURE__ */ new Error("[arc/encryption] decrypted request body is not valid JSON"), {
+				statusCode: 400,
+				cause
+			});
+		}
+	});
+	fastify.addHook("preSerialization", async (request, reply, payload) => {
+		const directive = resolveDirective(request, defaultMode, fallback);
+		if (!directive) return payload;
+		if (payload === null || typeof payload !== "object") return payload;
+		if (directive.mode === "fields") {
+			if (directive.fields.length === 0) return payload;
+			const { kid, key } = await keyProvider.encryptionKey({ request });
+			const obj = payload;
+			let touched = false;
+			for (const path of directive.fields) {
+				const value = getPath(obj, path);
+				if (value === void 0 || value === null) continue;
+				setPath(obj, path, encryptField(JSON.stringify(value), kid, key));
+				touched = true;
+			}
+			if (touched) {
+				setFlag(reply);
+				request.responseEncrypted = true;
+			}
+			return payload;
+		}
+		const active = await keyProvider.encryptionKey({ request });
+		const jwe = await jweEncrypt(JSON.stringify(payload), active, alg, enc);
+		reply.header("content-type", responseContentType);
+		setFlag(reply);
+		reply.serializer((p) => p);
+		request.responseEncrypted = true;
+		return jwe;
+	});
+	fastify.log?.debug?.({
+		mode: defaultMode,
+		alg,
+		enc
+	}, "[arc/encryption] enabled");
+};
+var encryptionPlugin_default = fp(encryptionPlugin, {
+	name: "arc-encryption",
+	fastify: "5.x"
+});
+//#endregion
+//#region src/encryption/keyProvider.ts
+/**
+* A static, in-memory key provider with `kid`-based rotation. Keys are held
+* for the process lifetime — resolve them from env / a secrets file at boot
+* and pass the imported key material in (don't re-parse PEM per request).
+*
+* @example symmetric field mode
+* ```ts
+* const provider = createStaticKeyProvider({
+*   encryptionKey: { kid: "2026-06", key: Buffer.from(process.env.FIELD_KEY!, "base64") },
+* });
+* ```
+*
+* @example asymmetric JWE (jose key material)
+* ```ts
+* const provider = createStaticKeyProvider({
+*   encryptionKey: { kid: "client-1", key: await importSPKI(clientPubPem, "RSA-OAEP-256") },
+*   decryptionKeys: { "server-1": await importPKCS8(serverPrivPem, "RSA-OAEP-256") },
+* });
+* ```
+*/
+function createStaticKeyProvider(options) {
+	const { encryptionKey } = options;
+	const decryptionKeys = {
+		[encryptionKey.kid]: encryptionKey.key,
+		...options.decryptionKeys
+	};
+	return {
+		encryptionKey: () => encryptionKey,
+		decryptionKey: (kid) => decryptionKeys[kid]
+	};
+}
+//#endregion
+export { createStaticKeyProvider, decryptField, encryptionPlugin_default as default, encryptField, encryptionPlugin, parseFieldEnvelope };

package/dist/events/index.mjs

@@ -417,12 +417,13 @@ function repositoryAsOutboxStore(repository) {
 		},
 		async getPending(limit) {
 			const now = /* @__PURE__ */ new Date();
-			return unwrapDocs(await r.getAll({
+			const result = await r.getAll({
 				filters: claimableFilter(now),
 				sort: { createdAt: 1 },
 				page: 1,
 				limit
-			})).map((d) => d.event).filter(isWellFormed);
+			});
+			return unwrapDocs(result).map((d) => d.event).filter(isWellFormed);
 		},
 		async claimPending(options) {
 			const limit = options?.limit ?? DEFAULT_CLAIM_LIMIT;
@@ -493,12 +494,13 @@ function repositoryAsOutboxStore(repository) {
 			}
 		},
 		async getDeadLettered(limit) {
-			return unwrapDocs(await r.getAll({
+			const result = await r.getAll({
 				filters: eq("status", "dead_letter"),
 				sort: { [idField]: 1 },
 				page: 1,
 				limit
-			})).filter((d) => isWellFormed(d.event)).map((d) => ({
+			});
+			return unwrapDocs(result).filter((d) => isWellFormed(d.event)).map((d) => ({
 				event: d.event,
 				error: {
 					message: d.lastError?.message ?? "unknown",
@@ -513,13 +515,14 @@ function repositoryAsOutboxStore(repository) {
 			const cutoff = new Date(Date.now() - olderThanMs);
 			let totalDeleted = 0;
 			for (;;) {
-				const batch = unwrapDocs(await r.getAll({
+				const result = await r.getAll({
 					filters: and(eq("status", "delivered"), lte("deliveredAt", cutoff)),
 					sort: { deliveredAt: 1 },
 					page: 1,
 					limit: DEFAULT_PURGE_BATCH,
 					select: idField
-				}));
+				});
+				const batch = unwrapDocs(result);
 				if (batch.length === 0) break;
 				const ids = batch.map((d) => d[idField]);
 				const res = await r.deleteMany(anyOf(idField, ids));

package/dist/factory/index.d.mts

@@ -1,4 +1,5 @@
-import { a as CustomPluginAuthOption, c as RawBodyOptions, d as preloadResourcesAsync, f as LoadResourcesOptions, h as loadResources, i as CustomAuthenticatorOption, l as UnderPressureOptions, m as ResourceModule, n as BetterAuthOption, o as JwtAuthOption, p as ResourceLike, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as preloadResources } from "../types-CmkknLzI.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-JYH9V0I8.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-BHMKlMBU.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 
 //#region src/factory/createApp.d.ts
@@ -95,4 +96,4 @@ declare const edgePreset: Partial<CreateAppOptions>;
  */
 declare function getPreset(name: "production" | "development" | "testing" | "edge"): Partial<CreateAppOptions>;
 //#endregion
-export { ArcFactory, 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, developmentPreset, edgePreset, getPreset, loadResources, preloadResources, preloadResourcesAsync, productionPreset, testingPreset, toFetchHandler };
+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 };

package/dist/factory/index.mjs

@@ -1,5 +1,5 @@
 import { n as preloadResourcesAsync, t as preloadResources } from "../preloadResources-CHw3_oA_.mjs";
-import { a as edgePreset, c as testingPreset, i as developmentPreset, n as createApp, o as getPreset, s as productionPreset, t as ArcFactory } from "../createApp--703hQE1.mjs";
+import { a as getModuleExports, c as developmentPreset, d as productionPreset, f as testingPreset, i as defineModule, l as edgePreset, n as createApp, o as orderModules, s as resolveModule, t as ArcFactory, u as getPreset } from "../createApp-D6uwzCKu.mjs";
 import { t as loadResources } from "../loadResources-B8UmpITt.mjs";
 //#region src/factory/edge.ts
 /**
@@ -47,4 +47,4 @@ function toFetchHandler(app, options = {}) {
 	};
 }
 //#endregion
-export { ArcFactory, createApp, developmentPreset, edgePreset, getPreset, loadResources, preloadResources, preloadResourcesAsync, productionPreset, testingPreset, toFetchHandler };
+export { ArcFactory, createApp, defineModule, developmentPreset, edgePreset, getModuleExports, getPreset, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveModule, testingPreset, toFetchHandler };

package/dist/{fastify-augmentation-Cxb0ROIw.d.mts → fastify-augmentation-CCQJEDgh.d.mts}

@@ -1,5 +1,6 @@
-import { yn as HookSystem, z as ResourceRegistry } from "./index-CHNQIhcb.mjs";
+import { bn as HookSystem, z as ResourceRegistry } from "./index-_--GyzcO.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-BE6wFpYv.mjs";
+import { r as ArcModuleRegistry } from "./module-JYH9V0I8.mjs";
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/core/arcCorePlugin.d.ts
@@ -28,6 +29,16 @@ interface ArcCore {
   externalOpenApiPaths: ExternalOpenApiPaths[];
   /** Registered plugins for introspection */
   plugins: Map<string, PluginMeta>;
+  /**
+   * Module public exports — `bootstrap()` return values keyed by module name
+   * (see `src/factory/module.ts`). Read via `getModuleExports(fastify, name)`:
+   * augment `ArcModuleRegistry` once and the name infers the export type;
+   * otherwise pass it inline. `Partial<ArcModuleRegistry>` gives augmented
+   * apps typed direct access (`fastify.arc.modules.order`), while the
+   * `Record<string, unknown>` intersection keeps un-augmented reads open.
+   * Populated lazily by `registerResources` — absent until a module exports.
+   */
+  modules?: Partial<ArcModuleRegistry> & Record<string, unknown>;
 }
 declare const arcCorePlugin: FastifyPluginAsync<ArcCorePluginOptions>;
 declare const _default: FastifyPluginAsync<ArcCorePluginOptions>;

package/dist/{generate-Brans3fW.mjs → generate-usRSdQmP.mjs}

@@ -1,4 +1,4 @@
-import { t as pluralize } from "./pluralize-DccFV9R7.mjs";
+import { t as pluralize } from "./pluralize-BhrgwZb9.mjs";
 import { join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 //#region src/cli/commands/generate/name-helpers.ts
@@ -601,9 +601,10 @@ async function generate(type, args) {
 	if (!type) throw new Error("Missing type argument\nUsage: arc generate <resource|controller|model|repository|schemas> <name>");
 	const [name, ...restArgs] = args;
 	if (!name) throw new Error("Missing name argument\nUsage: arc generate <type> <name>\nExample: arc generate resource product");
+	if (!/^[A-Za-z][A-Za-z0-9-]*$/.test(name)) throw new Error(`Invalid name "${name}". Use kebab-case: a letter followed by letters, digits, or hyphens (e.g. 'product', 'order-line'). No slashes, dots, spaces, or path segments.`);
 	const capitalizedName = toPascalCase(name);
 	const lowerName = name.toLowerCase();
-	if ((type === "resource" || type === "r" || type === "model" || type === "m") && new Set([
+	if ((type === "resource" || type === "r" || type === "model" || type === "m") && (/* @__PURE__ */ new Set([
 		"user",
 		"session",
 		"account",
@@ -614,7 +615,7 @@ async function generate(type, args) {
 		"team",
 		"team-member",
 		"apikey"
-	]).has(lowerName)) {
+	])).has(lowerName)) {
 		console.warn(`\n[arc generate] "${lowerName}" is a Better Auth-owned collection.\nBetter Auth's organization/admin/bearer plugins write this collection directly,\nso generating a parallel arc model would create a duplicate registration.\n\nRecommended pattern:\n  import { createBetterAuthOverlay } from '@classytic/mongokit/better-auth';\n  const adapter = await createBetterAuthOverlay({\n    auth, mongoose, collection: '${lowerName}',\n  });\n  // ...then \`defineResource({ name: '${lowerName}', adapter, ... })\` reads\n  //    BA's collection through arc with full pagination/filters/permissions.\n\nAborting. Re-run with a different name if you need a separate domain model.\n`);
 		return;
 	}

package/dist/hooks/index.d.mts

@@ -1,2 +1,2 @@
-import { Cn as afterUpdate, Dn as createHookSystem, En as beforeUpdate, On as defineHook, Sn as afterDelete, Tn as beforeDelete, _n as HookPhase, bn as HookSystemOptions, gn as HookOperation, hn as HookHandler, mn as HookContext, pn as DefineHookOptions, vn as HookRegistration, wn as beforeCreate, xn as afterCreate, yn as HookSystem } from "../index-CHNQIhcb.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-_--GyzcO.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

@@ -387,7 +387,7 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		const statusCode = reply.statusCode;
 		if (statusCode < 200 || statusCode >= 300) return payload;
 		const headersToCache = {};
-		const excludeHeaders = new Set([
+		const excludeHeaders = /* @__PURE__ */ new Set([
 			"content-length",
 			"transfer-encoding",
 			"connection",

package/dist/{index-CRKiiP5o.d.mts → index-CdFkIMEd.d.mts}

@@ -669,6 +669,11 @@ declare function fullPublic<TDoc = Record<string, unknown>>(overrides?: Permissi
 /**
  * Read-only: list + get authenticated, write operations denied.
  * Useful for computed/derived resources.
+ *
+ * Writes carry an explicit `denyAll` check — an omitted CRUD permission
+ * mounts the route with NO gate (public-by-omission), so leaving
+ * create/update/delete undefined here would expose unauthenticated writes.
+ * Hosts that disable write routes entirely (`disabledRoutes`) are unaffected.
  */
 declare function readOnly<TDoc = Record<string, unknown>>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
 //#endregion

package/dist/{index-Dh0_RSTd.d.mts → index-DUa8WHz3.d.mts}

@@ -1,4 +1,4 @@
-import { C as RequestContext, F as FastifyWithDecorators, H as ActionDefinition, K as ArcFieldRule, Kt as AnyRecord, L as RequestWithExtras, T as CrudRouterOptions, Tt as AggregationConfig, V as ResourceDefinition, bt as IRequestContext, ft as RouteMcpConfig, mt as RouteSchemaOptions, q as CrudController, st as ResourceConfig, vt as IController, yt as IControllerResponse } from "./index-CHNQIhcb.mjs";
+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-_--GyzcO.mjs";
 import { i as RequestScope } from "./types-LNebCoJx.mjs";
 import { c as PermissionCheck } from "./fields-C7ahdGYf.mjs";
 import { FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
@@ -300,7 +300,7 @@ declare function sendControllerResponse<T>(reply: FastifyReply, response: IContr
  * fastify.get('/products', listHandler);
  * ```
  */
-declare function createFastifyHandler<T>(controllerMethod: (req: IRequestContext) => Promise<IControllerResponse<T>>): (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+declare function createFastifyHandler<T>(controllerMethod: (req: IRequestContext) => Promise<IControllerResponse<T>>): (req: FastifyRequest, reply: FastifyReply) => Promise<FastifyReply>;
 /**
  * Create Fastify adapters for all CRUD methods of an IController
  *
@@ -319,11 +319,11 @@ declare function createFastifyHandler<T>(controllerMethod: (req: IRequestContext
  * ```
  */
 declare function createCrudHandlers<TDoc>(controller: IController<TDoc>): {
-  list: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
-  get: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
-  create: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
-  update: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
-  delete: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  list: (req: FastifyRequest, reply: FastifyReply) => Promise<FastifyReply>;
+  get: (req: FastifyRequest, reply: FastifyReply) => Promise<FastifyReply>;
+  create: (req: FastifyRequest, reply: FastifyReply) => Promise<FastifyReply>;
+  update: (req: FastifyRequest, reply: FastifyReply) => Promise<FastifyReply>;
+  delete: (req: FastifyRequest, reply: FastifyReply) => Promise<FastifyReply>;
 };
 //#endregion
 //#region src/core/fieldRulePredicates.d.ts

package/dist/{index-CHNQIhcb.d.mts → index-_--GyzcO.d.mts}

@@ -2467,6 +2467,25 @@ interface RouteDefinition {
    * pipeline entirely.
    */
   readonly fieldWrite?: boolean;
+  /**
+   * Per-route rate limit. A custom route is its own Fastify route, so this
+   * overrides the resource-level `rateLimit` for THIS endpoint only:
+   *
+   *   - omitted                → inherit the resource-level limit (or app default)
+   *   - `false`                → disable rate limiting on this route
+   *   - `{ max, timeWindow }`  → apply this specific limit
+   *
+   * Requires `@fastify/rate-limit` registered (arc's factory wires it by
+   * default). Use for an expensive `/export` or an auth-sensitive `/reset`
+   * that needs a tighter cap than the resource's read-heavy CRUD, or `false`
+   * on an internal health/webhook route that must not be throttled.
+   *
+   * Note: this is per-route because each custom route is a distinct endpoint.
+   * `actions` share ONE `POST /:id/action` mount by design, so a per-ACTION
+   * limit can't be expressed here — throttle a specific action by promoting
+   * it to a dedicated `routes:` entry, or rely on the resource-level limit.
+   */
+  readonly rateLimit?: RateLimitConfig | false;
   /**
    * Fastify route schema. Each slot (`body`, `querystring`, `params`,
    * `headers`, `response[status]`) accepts a plain JSON Schema object
@@ -2504,7 +2523,15 @@ interface RouteDefinition {
  * ID, action-specific data, and the request.
  */
 type ActionHandlerFn = (id: string, data: Record<string, unknown>, req: RequestWithExtras) => Promise<unknown>;
-/** Full action configuration with handler, permissions, and schema. */
+/**
+ * Full action configuration with handler, permissions, and schema.
+ *
+ * Rate limiting is intentionally NOT per-action: every action shares one
+ * `POST /:id/action` (or `POST /action`) mount, so Fastify's per-route limit
+ * can't distinguish them. Actions inherit the resource-level `rateLimit`; to
+ * throttle a specific operation, promote it to a `routes:` entry (which
+ * supports `RouteDefinition.rateLimit`).
+ */
 interface ActionDefinition {
   readonly handler: ActionHandlerFn;
   /** Per-action permission (overrides resource-level `actionPermissions`) */
@@ -2667,6 +2694,48 @@ interface ResourcePermissions {
   update?: PermissionCheck;
   delete?: PermissionCheck;
 }
+/**
+ * Plugin extension namespace — arc's typed escape hatch for attaching
+ * declarative, per-resource config that **plugins** read at request time.
+ *
+ * This interface is intentionally **empty in core**. Each optional plugin
+ * augments it via TypeScript declaration merging to register its own typed
+ * slice — exactly the model Fastify uses for `FastifyInstance` decorators.
+ * A host that never installs a plugin never sees its key; a host that does
+ * gets full autocomplete + compile-time checking on the matching
+ * `extensions` block, and a typo (`extensions: { encyrption: … }`) is a
+ * type error rather than a silent no-op.
+ *
+ * **The "React for backend" composition model.** `defineResource()` is the
+ * declarative component, `extensions` is its typed props bag, and plugins
+ * are the providers that consume those props at the framework boundary.
+ * Adding a cross-cutting capability becomes *additive* — a plugin ships a
+ * subpath + a one-line `declare module` augmentation, with no new
+ * first-class `ResourceConfig` field and no core release per feature.
+ *
+ * Arc threads the declared `extensions` onto every generated route's
+ * Fastify `config` (see `createCrudRouter`), so a plugin reads its slice
+ * at request time via `request.routeOptions.config.arcExtensions` without
+ * re-deriving which resource a route belongs to.
+ *
+ * @example A plugin registers its slice (in `@classytic/arc/encryption`)
+ * ```ts
+ * declare module "@classytic/arc/types" {
+ *   interface ResourceExtensions {
+ *     encryption?: import("@classytic/arc/encryption").EncryptionDirective;
+ *   }
+ * }
+ * ```
+ *
+ * @example A host declares it on a resource
+ * ```ts
+ * defineResource({
+ *   name: "payment",
+ *   extensions: { encryption: { mode: "fields", fields: ["cardNumber", "cvv"] } },
+ * });
+ * ```
+ */
+interface ResourceExtensions {}
 interface ResourceConfig<TDoc = AnyRecord> {
   name: string;
   displayName?: string;
@@ -3097,6 +3166,26 @@ interface ResourceConfig<TDoc = AnyRecord> {
   audit?: boolean | {
     operations?: ("create" | "update" | "delete")[];
   };
+  /**
+   * Typed plugin-extension namespace — declarative per-resource config that
+   * arc plugins read at request time. Empty by default; each installed
+   * plugin augments {@link ResourceExtensions} with its own typed slice via
+   * `declare module`. See {@link ResourceExtensions} for the full rationale
+   * and the "React for backend" composition model.
+   *
+   * Threaded onto every generated route's Fastify `config` as
+   * `config.arcExtensions`, so a plugin reads its slice via
+   * `request.routeOptions.config.arcExtensions` without a resource lookup.
+   *
+   * @example
+   * ```ts
+   * defineResource({
+   *   name: "payment",
+   *   extensions: { encryption: { mode: "fields", fields: ["cardNumber"] } },
+   * });
+   * ```
+   */
+  extensions?: ResourceExtensions;
 }
 //#endregion
 //#region src/core/defineResource/diagnostics.d.ts
@@ -3189,6 +3278,7 @@ declare class ResourceDefinition<TDoc = AnyRecord> {
    */
   readonly onFieldWriteDenied?: "reject" | "strip";
   readonly cache?: ResourceCacheConfig;
+  readonly extensions?: ResourceExtensions;
   readonly referenceData: boolean;
   /**
    * Per-resource MCP opt-out. `false` keeps the resource out of every
@@ -3544,6 +3634,18 @@ type FastifyWithDecorators = FastifyInstance & {
 };
 /** Handler signature for middleware functions. */
 type MiddlewareHandler = (request: RequestWithExtras, reply: FastifyReply) => Promise<unknown>;
+/**
+ * Route-config augmentation — arc stamps `defineResource({ extensions })`
+ * onto every generated route's Fastify `config` under `arcExtensions`, so
+ * plugins read their typed slice at request time via
+ * `request.routeOptions.config.arcExtensions` without re-resolving which
+ * resource a route belongs to. Type-only; see `ResourceExtensions`.
+ */
+declare module "fastify" {
+  interface FastifyContextConfig {
+    arcExtensions?: ResourceExtensions;
+  }
+}
 //#endregion
 //#region src/types/plugins.d.ts
 interface GracefulShutdownOptions {
@@ -3619,6 +3721,13 @@ interface CrudRouterOptions {
    * re-reading resource config. Defaults to `_id`.
    */
   idField?: string;
+  /**
+   * Resource-level plugin extensions (`defineResource({ extensions })`).
+   * Stamped onto every registered route's Fastify `config.arcExtensions`
+   * so request-time plugins (encryption, …) read their typed slice without
+   * re-resolving which resource a route belongs to. See `ResourceExtensions`.
+   */
+  extensions?: ResourceExtensions;
 }
 //#endregion
 //#region src/types/query.d.ts
@@ -4032,4 +4141,4 @@ interface ValidateOptions {
   strict?: boolean;
 }
 //#endregion
-export { OnTenantDeleteConfig as $, BaseController as $t, RequestIdOptions as A, ArcDeleteResult as An, AggregationRateLimit as At, defineResource as B, AuthHelpers as Bt, RequestContext as C, afterUpdate as Cn, AggMeasureShorthand as Ct, HealthCheck as D, createHookSystem as Dn, AggregationIndexHint as Dt, GracefulShutdownOptions as E, beforeUpdate as En, AggregationDateRangeRequirement as Et, FastifyWithDecorators as F, ControllerConfigurableOptions as Fn, OperationFilter as Ft, ActionsMap as G, TokenPair as Gt, ActionDefinition as H, Authenticator as Ht, MiddlewareHandler as I, ControllerConstructionOptions as In, PipelineConfig as It, CrudRouteKey as J, ArcRequest as Jt, ArcFieldRule as K, AnyRecord as Kt, RequestWithExtras as L, ListResult as Ln, PipelineContext as Lt, EventsDecorator as M, ArcListResult as Mn, Guard as Mt, FastifyRequestExtras as N, ArcUpdateResult as Nn, Interceptor as Nt, HealthOptions as O, defineHook as On, AggregationMaterializedContext as Ot, FastifyWithAuth as P, BaseControllerOptions as Pn, NextFunction as Pt, MiddlewareConfig as Q, UserOrganization as Qt, RegisterOptions as R, BodySanitizer as Rn, PipelineStep as Rt, QueryParserInterface as S, afterDelete as Sn, AggMeasureInput as St, CrudRouterOptions as T, beforeDelete as Tn, AggregationConfig as Tt, ActionEntry as U, AuthenticatorContext as Ut, ResourceDefinition as V, AuthPluginOptions as Vt, ActionHandlerFn as W, JwtContext as Wt, EventDefinition as X, ObjectId as Xt, CrudSchemas as Y, JWTPayload as Yt, FieldRule$1 as Z, UserLike as Zt, ControllerQueryOptions as _, HookPhase as _n, FastifyHandler as _t, InferAdapterDoc as a, SlugMixin as an, ResolvedTenantPurge as at, ParsedQuery as b, HookSystemOptions as bn, IRequestContext as bt, TypedController as c, BaseCrudController as cn, ResourceHookContext as ct, PaginationResult as d, AccessControl as dn, RouteDefinition as dt, SoftDeleteExt as en, OpenApiSchemas as et, IntrospectionData as f, AccessControlConfig as fn, RouteMcpConfig as ft, ArcInternalMetadata as g, HookOperation as gn, ControllerLike as gt, ResourceMetadata as h, HookHandler as hn, ControllerHandler as ht, ValidationResult as i, SlugExt as in, RateLimitConfig as it, ArcDecorator as j, ArcGetResult as jn, AggregationsMap as jt, IntrospectionPluginOptions as k, ArcCreateResult as kn, AggregationMaterializedResult as kt, TypedRepository as l, QueryResolver as ln, ResourceHooks as lt, RegistryStats as m, HookContext as mn, RouteSchemaOptions as mt, ConfigError as n, TreeExt as nn, PresetHook as nt, InferDocType as o, BulkExt as on, ResourceCacheConfig as ot, RegistryEntry as p, DefineHookOptions as pn, RouteMethod as pt, CrudController as q, ApiResponse as qt, ValidateOptions as r, TreeMixin as rn, PresetResult as rt, InferResourceDoc as s, BulkMixin as sn, ResourceConfig as st, RouteHandlerMethod$1 as t, SoftDeleteMixin as tn, PresetFunction as tt, TypedResourceConfig as u, QueryResolverConfig as un, ResourcePermissions as ut, LookupOption as v, HookRegistration as vn, IController as vt, ServiceContext as w, beforeCreate as wn, AggregationCacheConfig as wt, PopulateOption as x, afterCreate as xn, RouteHandler as xt, OwnershipCheck as y, HookSystem as yn, IControllerResponse as yt, ResourceRegistry as z, BodySanitizerConfig as zn, Transform as zt };
+export { OnTenantDeleteConfig as $, UserOrganization as $t, RequestIdOptions as A, ArcCreateResult as An, AggregationMaterializedResult as At, defineResource as B, BodySanitizerConfig as Bn, Transform as Bt, RequestContext as C, afterDelete as Cn, AggMeasureInput as Ct, HealthCheck as D, beforeUpdate as Dn, AggregationDateRangeRequirement as Dt, GracefulShutdownOptions as E, beforeDelete as En, AggregationConfig as Et, FastifyWithDecorators as F, BaseControllerOptions as Fn, NextFunction as Ft, ActionsMap as G, JwtContext as Gt, ActionDefinition as H, AuthPluginOptions as Ht, MiddlewareHandler as I, ControllerConfigurableOptions as In, OperationFilter as It, CrudRouteKey as J, ApiResponse as Jt, ArcFieldRule as K, TokenPair as Kt, RequestWithExtras as L, ControllerConstructionOptions as Ln, PipelineConfig as Lt, EventsDecorator as M, ArcGetResult as Mn, AggregationsMap as Mt, FastifyRequestExtras as N, ArcListResult as Nn, Guard as Nt, HealthOptions as O, createHookSystem as On, AggregationIndexHint as Ot, FastifyWithAuth as P, ArcUpdateResult as Pn, Interceptor as Pt, MiddlewareConfig as Q, UserLike as Qt, RegisterOptions as R, ListResult as Rn, PipelineContext as Rt, QueryParserInterface as S, afterCreate as Sn, RouteHandler as St, CrudRouterOptions as T, beforeCreate as Tn, AggregationCacheConfig as Tt, ActionEntry as U, Authenticator as Ut, ResourceDefinition as V, AuthHelpers as Vt, ActionHandlerFn as W, AuthenticatorContext as Wt, EventDefinition as X, JWTPayload as Xt, CrudSchemas as Y, ArcRequest as Yt, FieldRule$1 as Z, ObjectId as Zt, ControllerQueryOptions as _, HookOperation as _n, ControllerLike as _t, InferAdapterDoc as a, SlugExt as an, ResolvedTenantPurge as at, ParsedQuery as b, HookSystem as bn, IControllerResponse as bt, TypedController as c, BulkMixin as cn, ResourceExtensions as ct, PaginationResult as d, QueryResolverConfig as dn, ResourcePermissions as dt, BaseController as en, OpenApiSchemas as et, IntrospectionData as f, AccessControl as fn, RouteDefinition as ft, ArcInternalMetadata as g, HookHandler as gn, ControllerHandler as gt, ResourceMetadata as h, HookContext as hn, RouteSchemaOptions as ht, ValidationResult as i, TreeMixin as in, RateLimitConfig as it, ArcDecorator as j, ArcDeleteResult as jn, AggregationRateLimit as jt, IntrospectionPluginOptions as k, defineHook as kn, AggregationMaterializedContext as kt, TypedRepository as l, BaseCrudController as ln, ResourceHookContext as lt, RegistryStats as m, DefineHookOptions as mn, RouteMethod as mt, ConfigError as n, SoftDeleteMixin as nn, PresetHook as nt, InferDocType as o, SlugMixin as on, ResourceCacheConfig as ot, RegistryEntry as p, AccessControlConfig as pn, RouteMcpConfig as pt, CrudController as q, AnyRecord as qt, ValidateOptions as r, TreeExt as rn, PresetResult as rt, InferResourceDoc as s, BulkExt as sn, ResourceConfig as st, RouteHandlerMethod$1 as t, SoftDeleteExt as tn, PresetFunction as tt, TypedResourceConfig as u, QueryResolver as un, ResourceHooks as ut, LookupOption as v, HookPhase as vn, FastifyHandler as vt, ServiceContext as w, afterUpdate as wn, AggMeasureShorthand as wt, PopulateOption as x, HookSystemOptions as xn, IRequestContext as xt, OwnershipCheck as y, HookRegistration as yn, IController as yt, ResourceRegistry as z, BodySanitizer as zn, PipelineStep as zt };