@classytic/arc 2.18.5 → 2.20.0

package/dist/{createApp--703hQE1.mjs → createApp-D6uwzCKu.mjs}

@@ -245,7 +245,7 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules) {
 		trackPlugin("arc-caching", opts);
 	}
 	if (config.arcPlugins?.queryCache) {
-		const { queryCachePlugin } = await import("./queryCachePlugin-emHb0CuX.mjs").then((n) => n.n);
+		const { queryCachePlugin } = await import("./queryCachePlugin-DzqLN904.mjs").then((n) => n.n);
 		const opts = config.arcPlugins.queryCache === true ? {} : config.arcPlugins.queryCache;
 		const store = config.stores?.queryCache ?? new (await (import("./memory-CLXA2VeJ.mjs").then((n) => n.n))).MemoryCacheStore();
 		await fastify.register(queryCachePlugin, {
@@ -384,6 +384,134 @@ 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";
@@ -401,15 +529,29 @@ async function registerOne(parent, resource) {
 	}
 }
 /**
-* Execute the full resource lifecycle:
-* 1. plugins()                   — infra (DB, data, webhooks)
-* 2. bootstrap[]                 — domain init (singletons, event handlers)
-* 3. resources factory (if any)  — resolved AFTER bootstrap, so engine-backed
+* Execute the full resource lifecycle. The module graph is resolved + ordered
+* by `dependsOn` (stable topological sort) once, up FRONT — before any
+* side-effecting plugin — so a bad graph fails fast with no half-initialised
+* infra. Every phase below iterates that order; each module phase runs BEFORE
+* its app-level counterpart:
+*
+* 1.  resolve + orderModules     — validate the graph (dup names, missing/self
+*                                  deps, cycles fail fast) BEFORE side effects
+* 2.  plugins()                  — app infra (DB, data, webhooks)
+* 3.  module.plugins             — module infra, dependsOn order, before bootstraps
+* 4a. module.bootstrap           — engine init (return value → arc.modules[name])
+* 4b. bootstrap[]                — app-level domain init
+* 5.  resources factory (if any) — resolved AFTER bootstrap, so engine-backed
 *                                  adapters can `await ensureEngine()` and pass
 *                                  live models/repos into `defineResource(...)`
-* 4. resources[]                 — register each (split by prefix)
-* 5. afterResources()            — post-registration wiring
-* 6. onReady/onClose             — lifecycle hooks
+* 5b. module resources           — RESOLVED after the app factory, but PREPENDED
+*                                  so they REGISTER before app resources (two
+*                                  orderings, both intentional — see §5b)
+* 6.  module.afterResources → afterResources()  — post-registration wiring
+* 7.  onReady                    — lifecycle hook
+* 7b. onClose                    — module.onClose (reverse composition order)
+*                                  THEN app onClose, in ONE hook so module
+*                                  teardown runs before shared infra closes.
 */
 async function registerResources(fastify, config) {
 	if (config.preset === "production") {
@@ -422,10 +564,37 @@ async function registerResources(fastify, config) {
 			strictResourceDir: true
 		};
 	}
+	const modules = orderModules(await Promise.all((config.modules ?? []).map((m) => resolveModule(m))));
 	if (config.plugins) {
 		await config.plugins(fastify);
 		fastify.log.debug("Custom plugins registered");
 	}
+	for (const m of modules) {
+		if (!m.plugins) continue;
+		try {
+			await m.plugins(fastify);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new Error(`[arc] module "${m.name}" plugins() threw: ${msg}`, { cause: err });
+		}
+	}
+	for (const m of modules) {
+		if (!m.bootstrap) continue;
+		let exported;
+		try {
+			exported = await m.bootstrap(fastify);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new Error(`[arc] module "${m.name}" bootstrap threw: ${msg}`, { cause: err });
+		}
+		if (exported !== void 0) {
+			const arc = fastify.arc;
+			if (!arc) throw new Error(`[arc] module "${m.name}" returned a public export but fastify.arc is not decorated — arcCorePlugin must register first.`);
+			if (!arc.modules) arc.modules = Object.create(null);
+			arc.modules[m.name] = exported;
+		}
+	}
+	if (modules.length) fastify.log.debug(`${modules.length} module(s) composed (in dependency order): ${modules.map((m) => m.name).join(" → ")}`);
 	if (config.bootstrap?.length) {
 		for (const init of config.bootstrap) await init(fastify);
 		fastify.log.debug(`${config.bootstrap.length} bootstrap function(s) executed`);
@@ -462,6 +631,20 @@ async function registerResources(fastify, config) {
 		}
 		resolvedResources = discovered;
 	}
+	if (modules.length) {
+		const moduleResources = [];
+		for (const m of modules) {
+			if (!m.resources) continue;
+			try {
+				const rs = typeof m.resources === "function" ? await m.resources(fastify) : m.resources;
+				moduleResources.push(...rs);
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				throw new Error(`[arc] module "${m.name}" resources factory threw: ${msg}. Check the module's bootstrap ran and its adapters received booted engines.`, { cause: err });
+			}
+		}
+		if (moduleResources.length) resolvedResources = [...moduleResources, ...resolvedResources ?? []];
+	}
 	if (resolvedResources && resolvedResources.length > 0) {
 		const seen = /* @__PURE__ */ new Set();
 		for (const resource of resolvedResources) if (resource.name) {
@@ -490,6 +673,15 @@ async function registerResources(fastify, config) {
 		const hints = discoveryYieldedZero ? ` but yielded 0 resources. Check the path, file naming (*.resource.{ts,js,mts,mjs}), and runtime layout (src/ vs dist/). Use \`strictResourceDir: true\` to fail boot.` : "";
 		fastify.log.warn(`0 resources registered${prefix}${scanned}${hints}`);
 	}
+	for (const m of modules) {
+		if (!m.afterResources) continue;
+		try {
+			await m.afterResources(fastify);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new Error(`[arc] module "${m.name}" afterResources() threw: ${msg}`, { cause: err });
+		}
+	}
 	if (config.afterResources) {
 		await config.afterResources(fastify);
 		fastify.log.debug("afterResources hook executed");
@@ -500,12 +692,12 @@ async function registerResources(fastify, config) {
 			await onReady(fastify);
 		});
 	}
-	if (config.onClose) {
-		const onClose = config.onClose;
-		fastify.addHook("onClose", async () => {
-			await onClose(fastify);
-		});
-	}
+	const closers = modules.filter((m) => m.onClose).reverse();
+	const appOnClose = config.onClose;
+	if (closers.length || appOnClose) fastify.addHook("onClose", async () => {
+		for (const m of closers) await m.onClose?.(fastify);
+		if (appOnClose) await appOnClose(fastify);
+	});
 }
 //#endregion
 //#region src/factory/registerSecurity.ts
@@ -522,7 +714,8 @@ function buildRateLimitOpts(input) {
 	};
 	const matchesPath = compilePathMatcher(skipPaths);
 	const combined = async (req, key) => {
-		if (matchesPath((req.url ?? "").split("?", 1)[0] ?? "")) return true;
+		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;
@@ -711,7 +904,7 @@ var createApp_exports = /* @__PURE__ */ __exportAll({
 	createApp: () => createApp,
 	resolveLoggerConfig: () => resolveLoggerConfig
 });
-const MEMORY_STORE_NAMES = new Set(["memory", "memory-cache"]);
+const MEMORY_STORE_NAMES = /* @__PURE__ */ new Set(["memory", "memory-cache"]);
 /**
 * Default redact paths layered into Fastify's pino logger when the host
 * doesn't supply a `logger.redact` of their own. Covers the common token /
@@ -947,4 +1140,4 @@ const ArcFactory = {
 	}
 };
 //#endregion
-export { edgePreset as a, testingPreset as c, developmentPreset as i, createApp as n, getPreset as o, createApp_exports as r, productionPreset as s, ArcFactory as t };
+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 };

package/dist/docs/index.d.mts

@@ -1,4 +1,4 @@
-import { p as RegistryEntry } from "../index-CHNQIhcb.mjs";
+import { p as RegistryEntry } from "../index-_--GyzcO.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-BE6wFpYv.mjs";
 import { FastifyPluginAsync } from "fastify";
 

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-xVJibapr.mjs";
+import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-Dq6RbEGK.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/scalar.ts
 const scalarPlugin = async (fastify, opts = {}) => {

package/dist/encryption/index.d.mts

@@ -0,0 +1,222 @@
+import { FastifyPluginAsync, FastifyRequest } from "fastify";
+
+//#region src/encryption/types.d.ts
+/** JWE key-management algorithm — the protected-header `alg`. */
+type JweAlg = "RSA-OAEP-256" | "RSA-OAEP-384" | "RSA-OAEP-512" | "ECDH-ES" | "ECDH-ES+A256KW" | "A256GCMKW" | "dir";
+/** JWE content-encryption algorithm — the protected-header `enc`. AEAD only. */
+type JweEnc = "A128GCM" | "A192GCM" | "A256GCM";
+/** Encryption strategy for a route's response. */
+type EncryptionMode = "jwe" | "fields";
+/**
+ * Opaque key material. For `jwe` mode this is a `jose` `KeyLike` /
+ * `CryptoKey` / `Uint8Array`; for `fields` mode a 32-byte secret
+ * (`Buffer` / `Uint8Array`). Kept `unknown` at the contract layer so the
+ * `KeyProvider` interface carries no hard `jose` type dependency — hosts
+ * without `jose` installed can still implement field-mode providers.
+ */
+type KeyMaterial = unknown;
+/** A key paired with its identifier — what encrypt operations consume. */
+interface ActiveKey {
+  /** Key id, stamped into the JWE `kid` header / field envelope for rotation. */
+  readonly kid: string;
+  /** The key material (public key for JWE, 32-byte secret for fields). */
+  readonly key: KeyMaterial;
+  /** Optional per-key `alg` override (else the plugin default applies). */
+  readonly alg?: JweAlg;
+}
+/** Context handed to the key provider so resolution can be request-scoped. */
+interface KeyContext {
+  readonly request: FastifyRequest;
+}
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Pluggable key resolution. Arc owns the request-time plumbing — `kid` →
+ * key, algorithm allowlist enforcement; the host owns the trust store —
+ * which keys are valid and where they live (file / env / AWS KMS / GCP KMS
+ * / Vault). Encryption and decryption are deliberately separate operations
+ * because they often use DIFFERENT keys (JWE: a public key encrypts the
+ * outbound response, a private key by `kid` decrypts the inbound request —
+ * exactly Visa's two-key-pair model).
+ *
+ * Rotation mirrors `@fastify/secure-session`: the active key encrypts; any
+ * key resolvable by `kid` can decrypt, so you can roll keys without dropping
+ * in-flight traffic.
+ */
+interface KeyProvider {
+  /** Active key for encrypting OUTBOUND responses. */
+  encryptionKey(ctx: KeyContext): MaybePromise<ActiveKey>;
+  /** Resolve a DECRYPTION key by the inbound message's `kid`. */
+  decryptionKey(kid: string, ctx: KeyContext): MaybePromise<KeyMaterial | undefined>;
+}
+/**
+ * Per-resource encryption directive — the typed slice plugins register on
+ * `ResourceExtensions`. Declared on a resource via
+ * `defineResource({ extensions: { encryption: { … } } })`; arc threads it
+ * to request time on `request.routeOptions.config.arcExtensions.encryption`.
+ */
+interface EncryptionDirective {
+  /** Strategy. Defaults to the plugin-level `mode` (default `'jwe'`). */
+  readonly mode?: EncryptionMode;
+  /**
+   * For `mode: 'fields'` — dot-paths of fields to encrypt, resolved against
+   * the serialized response body (e.g. `'cardNumber'`, `'account.iban'`).
+   * Ignored for `mode: 'jwe'` (the whole body is encrypted).
+   */
+  readonly fields?: readonly string[];
+  /**
+   * Explicit opt-out — set `false` to disable encryption for this resource
+   * even when a plugin-level default (`routes`) would otherwise apply.
+   */
+  readonly enabled?: boolean;
+}
+/**
+ * Plugin-level options. `keyProvider` is the only required field; everything
+ * else has a secure default.
+ */
+interface EncryptionOptions {
+  /**
+   * Master on/off. Default `true`. Set `false` to register the plugin as a
+   * typed no-op (config-gated environments) — same pattern as
+   * `idempotencyPlugin`.
+   */
+  readonly enabled?: boolean;
+  /** Key provider — resolves `kid` → key for encrypt/decrypt. Required. */
+  readonly keyProvider: KeyProvider;
+  /** Default mode when a route opts in without naming one. Default `'jwe'`. */
+  readonly mode?: EncryptionMode;
+  /** JWE key-management algorithm. Default `'RSA-OAEP-256'`. */
+  readonly alg?: JweAlg;
+  /** JWE content-encryption algorithm. Default `'A256GCM'`. */
+  readonly enc?: JweEnc;
+  /**
+   * Inbound-decryption algorithm allowlists — block algorithm-substitution
+   * downgrade attacks. Default `[alg]` / `[enc]`. Set explicitly only when a
+   * client legitimately uses more than one algorithm.
+   */
+  readonly allowedAlgs?: readonly JweAlg[];
+  readonly allowedEncs?: readonly JweEnc[];
+  /**
+   * Fallback opt-in for routes that don't declare
+   * `extensions.encryption`. Return a directive (or `true` for the default
+   * mode) to encrypt, `false`/`undefined` to skip. The per-resource
+   * `extensions.encryption` ALWAYS wins when present. Use this to scope ALE
+   * to sensitive prefixes without touching every resource.
+   *
+   * @example confine ALE to `/payments` and `/accounts`
+   * ```ts
+   * routes: (req) => /^\/(payments|accounts)\b/.test(req.url)
+   * ```
+   */
+  readonly routes?: (request: FastifyRequest) => EncryptionDirective | boolean | undefined;
+  /** Decrypt inbound `application/jose` request bodies. Default `true`. */
+  readonly decryptRequests?: boolean;
+  /** Media type that signals an encrypted REQUEST body. Default `'application/jose'`. */
+  readonly contentType?: string;
+  /** Content-Type set on full-body JWE RESPONSES. Default `'application/jose'`. */
+  readonly responseContentType?: string;
+  /**
+   * Response header advertising that the body is encrypted, so generic
+   * client SDKs know to decrypt. Default `'x-encrypted'`; set `false` to omit.
+   */
+  readonly flagHeader?: string | false;
+}
+/** Request decorations added by the plugin. */
+declare module "fastify" {
+  interface FastifyRequest {
+    /** `true` when the inbound body was decrypted from a JWE by this plugin. */
+    requestDecrypted?: boolean;
+    /** `true` when the outbound body was encrypted by this plugin. */
+    responseEncrypted?: boolean;
+  }
+}
+//#endregion
+//#region src/encryption/encryptionPlugin.d.ts
+declare const encryptionPlugin: FastifyPluginAsync<EncryptionOptions>;
+declare const _default: FastifyPluginAsync<EncryptionOptions>;
+//#endregion
+//#region src/encryption/fieldCipher.d.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.
+ */
+/** Encrypt a UTF-8 string into the `arc.v1` field envelope. */
+declare function encryptField(plaintext: string, kid: string, key: unknown): string;
+/** Parsed envelope header — exposes `kid` for key resolution before decrypt. */
+interface ParsedFieldEnvelope {
+  readonly kid: string;
+  readonly iv: Buffer;
+  readonly ciphertext: Buffer;
+  readonly tag: Buffer;
+}
+/** Returns the parsed envelope, or `null` when the token isn't `arc.v1`. */
+declare function parseFieldEnvelope(token: string): ParsedFieldEnvelope | null;
+/** Decrypt a parsed `arc.v1` envelope with the resolved key. Throws on tamper. */
+declare function decryptField(envelope: ParsedFieldEnvelope, key: unknown): string;
+//#endregion
+//#region src/encryption/keyProvider.d.ts
+interface StaticKeyProviderOptions {
+  /**
+   * Active key used to ENCRYPT outbound responses. For `jwe` mode this is the
+   * recipient's PUBLIC key; for `fields` mode a 32-byte symmetric secret.
+   */
+  readonly encryptionKey: ActiveKey;
+  /**
+   * Keys used to DECRYPT inbound requests, indexed by `kid`. For `jwe` mode
+   * these are PRIVATE keys; for `fields` mode the same symmetric secrets.
+   *
+   * Defaults to `{ [encryptionKey.kid]: encryptionKey.key }` — correct for
+   * symmetric field mode where one key both encrypts and decrypts. For
+   * asymmetric JWE you MUST pass the private key(s) here; the public
+   * `encryptionKey` cannot decrypt. Keep 2–3 entries during a rotation so
+   * in-flight messages signed with the previous `kid` still decrypt.
+   */
+  readonly decryptionKeys?: Readonly<Record<string, KeyMaterial>>;
+}
+/**
+ * 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") },
+ * });
+ * ```
+ */
+declare function createStaticKeyProvider(options: StaticKeyProviderOptions): KeyProvider;
+//#endregion
+//#region src/encryption/index.d.ts
+declare module "../types/resource.js" {
+  interface ResourceExtensions {
+    /**
+     * Encrypt this resource's responses — full-body JWE or specific fields.
+     * Threaded to request time on
+     * `request.routeOptions.config.arcExtensions.encryption`.
+     */
+    encryption?: EncryptionDirective;
+  }
+}
+//#endregion
+export { type ActiveKey, type EncryptionDirective, type EncryptionMode, type EncryptionOptions, type JweAlg, type JweEnc, type KeyContext, type KeyMaterial, type KeyProvider, type ParsedFieldEnvelope, type StaticKeyProviderOptions, createStaticKeyProvider, decryptField, _default as default, encryptField, encryptionPlugin, parseFieldEnvelope };