@getstrata/core 2.2.11 → 2.2.13

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @getstrata/core changelog
 
+## 2.2.13
+
+- Improve view rendering and better htmx support
+
+## 2.2.12
+
+- Require Bun >=1.4.3; align CI, generated/existing example runtime pins and Docker stages to 1.4.3, with bun-types >=1.4.3 behind the official @types/bun shim.
+
+Add identified field-encryption keyrings, reader-first email/MFA configuration, and explicit transactional maintenance rotation for ciphertext and lookup keys with durable checkpoints, RLS scopes, fresh retirement audits and backup/rollback guidance. Fix SQLite primary-key compilation for non-generated keys. Preserve legacy auth defaults; no automatic data migration.
+
 ## 2.2.11
 
 Add independently interruptible read-only SQLite and MySQL observations; extend bounded failed-job and outbox metrics to file-backed SQLite and URL-backed MySQL with schema/index guards, real-engine regressions and three-process consistency tests. Preserve Postgres RLS and business transaction behavior.

package/README.md

@@ -1,6 +1,6 @@
 # @getstrata/core
 
-Runtime library for [Strata](https://github.com/EyK-26/strata) apps: HTTP, auth, database, queue, mail, and security. Requires Bun (tested on 1.4.x).
+Runtime library for [Strata](https://github.com/EyK-26/strata) apps: HTTP, auth, database, queue, mail, and security. Requires Bun >=1.4.3 (tested on 1.4.3).
 
 Generate an app rather than wiring this by hand:
 

package/dist/core/crypto/fieldEncryption.d.ts

@@ -11,3 +11,32 @@ declare function protectEmail(email: string): {
 declare function revealEmail(storedEmail: string): string;
 declare function emailLookupForQuery(email: string): string;
 export { decryptField, emailLookupForQuery, encryptField, hashLookupValue, isFieldEncryptionEnabled, normalizeEmail, protectEmail, resolveEncryptionKey, revealEmail, };
+interface FieldEncryptionKeyringOptions {
+    /** Public stable identifiers; never reuse an ID for different key material. */
+    activeKeyId: string;
+    encryptionKeys: Readonly<Record<string, Uint8Array>>;
+    /** Explicitly retained key for unidentified enc:v1 records and historical backups. */
+    legacyV1Key?: Uint8Array;
+    /** Pinned independently of write-key rotation. Use the original key to preserve v1 email hashes. */
+    lookupKey: Uint8Array;
+}
+interface FieldEncryptionKeyring {
+    readonly activeKeyId: string;
+    encrypt(plaintext: string, purpose: string): string;
+    decrypt(ciphertext: string, purpose: string): string;
+    /** Input must already be normalized using the application's existing lookup contract. */
+    lookup(normalizedValue: string): string;
+}
+/** Opt-in primitives only. This does not activate auth rotation or migrate persisted rows. */
+declare function createFieldEncryptionKeyring(options: FieldEncryptionKeyringOptions): FieldEncryptionKeyring;
+export type { FieldEncryptionKeyring, FieldEncryptionKeyringOptions };
+export { createFieldEncryptionKeyring };
+interface ConfiguredFieldEncryption {
+    readonly keyring: FieldEncryptionKeyring;
+    readonly writeVersion: 1 | 2;
+    encrypt(plaintext: string, purpose: string): string;
+}
+/** Stateless resolution keeps separately bundled auth entrypoints on the same configuration. */
+declare function resolveFieldEncryptionKeyring(env?: Record<string, string | undefined>): ConfiguredFieldEncryption | null;
+export type { ConfiguredFieldEncryption };
+export { resolveFieldEncryptionKeyring };

package/dist/core/crypto/fieldEncryptionRotation.d.ts

@@ -0,0 +1,34 @@
+import { BaseRepository } from "../database/baseRepository";
+import type { Migration } from "../database/migrations/types";
+import { type DatabaseDriver } from "../database/schema";
+import { type FieldEncryptionKeyring } from "./fieldEncryption";
+declare function createFieldEncryptionRotationMigration(name: string, driver: DatabaseDriver, options?: {
+    rls?: boolean;
+}): Migration;
+interface FieldEncryptionRotationOptions<TEntity extends object, PK extends keyof TEntity & string> {
+    repository: BaseRepository<TEntity, PK>;
+    /** A distinct durable run identity per table, tenant/filter scope and audit pass. */
+    runId: string;
+    scopeId: string;
+    /** Required operator assertion: all application/worker/admin writers are stopped. Not an auth grant. */
+    maintenanceMode: true;
+    source: FieldEncryptionKeyring;
+    target: FieldEncryptionKeyring;
+    fields: readonly {
+        column: Exclude<keyof TEntity & string, PK>;
+        purpose: string;
+        lookupColumn?: Exclude<keyof TEntity & string, PK>;
+    }[];
+    mode?: "rotate" | "audit";
+    batchSize?: number;
+    signal?: AbortSignal;
+}
+interface FieldEncryptionRotationBatch {
+    processed: number;
+    changed: number;
+    completed: boolean;
+}
+/** One bounded transaction. Persisted cursors advance only with committed row writes. No RLS bypass. */
+declare function runFieldEncryptionRotationBatch<TEntity extends object, PK extends keyof TEntity & string>(options: FieldEncryptionRotationOptions<TEntity, PK>): Promise<FieldEncryptionRotationBatch>;
+export type { FieldEncryptionRotationBatch, FieldEncryptionRotationOptions };
+export { createFieldEncryptionRotationMigration, runFieldEncryptionRotationBatch };

package/dist/core/view/index.d.ts

@@ -1,8 +1,10 @@
-export type { LayoutDataResolver } from "./etaViewEngine";
+export type { LayoutDataResolver, RenderOptions } from "./etaViewEngine";
 export { DEFAULT_VIEWS_DIRECTORY, EtaViewEngine } from "./etaViewEngine";
 export { htmlResponse, isHtmxRequest, redirectResponse, rssResponse, textResponse, xmlResponse, } from "./htmlResponse";
 export type { ViewEngine } from "./viewEngine";
+export type { HtmxViewResponseOptions, ViewResponseOptions } from "./viewRenderer";
+export { CORE_VIEW_RENDERER_TOKEN, ViewRenderer } from "./viewRenderer";
 export type { WebErrorViewInput, WebErrorViewOptions } from "./webErrorView";
 export { configureWebErrorView, errorTemplateName, htmlErrorResponse, notFoundHtmlResponse, renderKernelErrorChrome, renderWebErrorHtml, } from "./webErrorView";
 export type { WebLayoutAuthUser, WebLayoutData, WebLayoutDataOptions, WebLayoutUserKey, } from "./webLayoutData";
-export { configureWebLayoutData, resolveWebLayoutData } from "./webLayoutData";
+export { configureWebLayoutData, createWebLayoutDataResolver, resolveWebLayoutData, } from "./webLayoutData";

package/dist/core/view/viewRenderer.d.ts

@@ -0,0 +1,24 @@
+import type { ViewEngine } from "./viewEngine";
+interface ViewResponseOptions {
+    layout?: string | false;
+    request?: Request;
+    status?: number;
+    statusText?: string;
+    headers?: ConstructorParameters<typeof Headers>[0];
+}
+interface HtmxViewResponseOptions extends ViewResponseOptions {
+    /** Optional fragment template; otherwise render the page template without its layout. */
+    fragment?: string;
+}
+/** App-owned renderer; request data stays in the engine's async resolver. */
+declare class ViewRenderer {
+    private readonly engine;
+    private readonly defaultLayout?;
+    constructor(engine: ViewEngine, defaultLayout?: string | false | undefined);
+    render(name: string, data?: Record<string, unknown>, options?: ViewResponseOptions): Promise<Response>;
+    /** Opt-in representation selection; auth/CSRF/tenancy remain the route's responsibility. */
+    renderHtmx(name: string, data?: Record<string, unknown>, options?: HtmxViewResponseOptions): Promise<Response>;
+}
+declare const CORE_VIEW_RENDERER_TOKEN: import("../contracts/container").ServiceToken<ViewRenderer>;
+export type { HtmxViewResponseOptions, ViewResponseOptions };
+export { CORE_VIEW_RENDERER_TOKEN, ViewRenderer };

package/dist/core/view/webLayoutData.d.ts

@@ -24,5 +24,7 @@ interface WebLayoutDataOptions {
 declare function configureWebLayoutData(options: WebLayoutDataOptions): void;
 declare function resetWebLayoutDataConfigForTests(): void;
 declare function resolveWebLayoutData(container: ServiceContainerLike, request?: Request, options?: WebLayoutDataOptions): Promise<Record<string, unknown>>;
+/** Isolated configuration for one app; does not read legacy global defaults. */
+declare function createWebLayoutDataResolver(container: ServiceContainerLike, options?: WebLayoutDataOptions): (request?: Request) => Promise<Record<string, unknown>>;
 export type { WebLayoutAuthUser, WebLayoutData, WebLayoutDataOptions, WebLayoutUserKey };
-export { configureWebLayoutData, resetWebLayoutDataConfigForTests, resolveWebLayoutData };
+export { configureWebLayoutData, createWebLayoutDataResolver, resetWebLayoutDataConfigForTests, resolveWebLayoutData, };

package/dist/entries/auth/basicAuthGuard.js

@@ -530,7 +530,7 @@ function isFieldEncryptionEnabled() {
   if (featureFlag === "true") {
     return true;
   }
-  return Boolean(resolveEncryptionKey());
+  return Boolean(resolveFieldEncryptionKeyring() || resolveEncryptionKey());
 }
 function encryptField(plaintext, key) {
   const iv = randomBytes(IV_LENGTH);
@@ -560,6 +560,13 @@ function normalizeEmail(email) {
 }
 function protectEmail(email) {
   const normalized = normalizeEmail(email);
+  const configured = resolveFieldEncryptionKeyring();
+  if (configured && isFieldEncryptionEnabled()) {
+    return {
+      storedEmail: configured.encrypt(normalized, "email"),
+      emailLookup: configured.keyring.lookup(normalized)
+    };
+  }
   const key = resolveEncryptionKey();
   if (!key || !isFieldEncryptionEnabled()) {
     return { storedEmail: normalized, emailLookup: normalized };
@@ -570,6 +577,11 @@ function protectEmail(email) {
   };
 }
 function revealEmail(storedEmail) {
+  const configured = resolveFieldEncryptionKeyring();
+  if (configured && storedEmail.startsWith("enc:"))
+    return configured.keyring.decrypt(storedEmail, "email");
+  if (storedEmail.startsWith("enc:") && !storedEmail.startsWith(ENCRYPTION_PREFIX))
+    throw new Error("Identified encrypted fields require KMS_ENCRYPTION_KEYRING.");
   const key = resolveEncryptionKey();
   if (!key || !storedEmail.startsWith(ENCRYPTION_PREFIX)) {
     return storedEmail;
@@ -578,15 +590,148 @@ function revealEmail(storedEmail) {
 }
 function emailLookupForQuery(email) {
   const normalized = normalizeEmail(email);
+  const configured = resolveFieldEncryptionKeyring();
+  if (configured && isFieldEncryptionEnabled())
+    return configured.keyring.lookup(normalized);
   const key = resolveEncryptionKey();
   if (!key || !isFieldEncryptionEnabled()) {
     return normalized;
   }
   return hashLookupValue(normalized, key);
 }
+function createFieldEncryptionKeyring(options) {
+  const identifier = /^[A-Za-z0-9_-]{1,64}$/;
+  const copyKey = (value) => {
+    if (!(value instanceof Uint8Array) || value.byteLength !== 32)
+      throw new TypeError("Field encryption keys must be 32 bytes.");
+    return Buffer.from(value);
+  };
+  const entries = Object.entries(options.encryptionKeys);
+  if (entries.length < 1 || entries.length > 32)
+    throw new TypeError("Field encryption keyrings require 1 to 32 keys.");
+  const keys = new Map;
+  for (const [id, key] of entries) {
+    if (!identifier.test(id))
+      throw new TypeError("Invalid field encryption key identifier.");
+    keys.set(id, copyKey(key));
+  }
+  const activeKeyId = options.activeKeyId;
+  const active = keys.get(activeKeyId);
+  if (!active)
+    throw new TypeError("Active field encryption key is not retained.");
+  const legacy = options.legacyV1Key === undefined ? undefined : copyKey(options.legacyV1Key);
+  const lookup = copyKey(options.lookupKey);
+  const associatedData = (id, purpose) => {
+    if (!identifier.test(purpose))
+      throw new TypeError("Invalid field encryption purpose.");
+    return Buffer.from(`strata:field:v2:${id}:${purpose}`, "utf8");
+  };
+  const decodePayload = (encoded) => {
+    const payload = Buffer.from(encoded, "base64");
+    if (payload.length < IV_LENGTH + TAG_LENGTH || payload.toString("base64") !== encoded)
+      throw new Error("Invalid encrypted field.");
+    return payload;
+  };
+  return Object.freeze({
+    activeKeyId,
+    encrypt(plaintext, purpose) {
+      const aad = associatedData(activeKeyId, purpose);
+      const iv = randomBytes(IV_LENGTH);
+      const cipher = createCipheriv("aes-256-gcm", active, iv, { authTagLength: TAG_LENGTH });
+      cipher.setAAD(aad);
+      const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+      const payload = Buffer.concat([iv, ciphertext, cipher.getAuthTag()]).toString("base64");
+      return `enc:v2:${activeKeyId}:${payload}`;
+    },
+    decrypt(value, purpose) {
+      associatedData(activeKeyId, purpose);
+      try {
+        if (value.startsWith(ENCRYPTION_PREFIX)) {
+          if (!legacy)
+            throw new Error("Missing legacy key");
+          decodePayload(value.slice(ENCRYPTION_PREFIX.length));
+          return decryptField(value, legacy);
+        }
+        const parts = value.split(":");
+        if (parts.length !== 4 || parts[0] !== "enc" || parts[1] !== "v2")
+          throw new Error("Invalid envelope");
+        const id = parts[2] ?? "";
+        const key = keys.get(id);
+        if (!key)
+          throw new Error("Missing retained key");
+        const payload = decodePayload(parts[3] ?? "");
+        const decipher = createDecipheriv("aes-256-gcm", key, payload.subarray(0, IV_LENGTH), {
+          authTagLength: TAG_LENGTH
+        });
+        decipher.setAAD(associatedData(id, purpose));
+        decipher.setAuthTag(payload.subarray(payload.length - TAG_LENGTH));
+        return Buffer.concat([
+          decipher.update(payload.subarray(IV_LENGTH, payload.length - TAG_LENGTH)),
+          decipher.final()
+        ]).toString("utf8");
+      } catch {
+        throw new Error("Unable to decrypt encrypted field.");
+      }
+    },
+    lookup(normalizedValue) {
+      return hashLookupValue(normalizedValue, lookup);
+    }
+  });
+}
+function resolveFieldEncryptionKeyring(env = process.env) {
+  const raw = env.KMS_ENCRYPTION_KEYRING;
+  if (raw === undefined)
+    return null;
+  try {
+    if (!raw.trim() || raw.length > 16384 || env.KMS_ENCRYPTION_KEY?.trim())
+      throw new Error("Invalid configuration");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      throw new Error("Invalid configuration");
+    const config = parsed;
+    if (Object.keys(config).some((key) => !["activeKeyId", "encryptionKeys", "legacyV1Key", "lookupKey", "writeVersion"].includes(key)))
+      throw new Error("Unknown option");
+    if (typeof config.activeKeyId !== "string" || config.writeVersion !== 1 && config.writeVersion !== 2 || !config.encryptionKeys || typeof config.encryptionKeys !== "object" || Array.isArray(config.encryptionKeys))
+      throw new Error("Invalid configuration");
+    const decodeKey = (value) => {
+      if (typeof value !== "string")
+        throw new Error("Invalid key");
+      if (/^[0-9a-f]{64}$/i.test(value))
+        return Buffer.from(value, "hex");
+      const decoded = Buffer.from(value, "base64");
+      if (decoded.length !== 32 || decoded.toString("base64") !== value)
+        throw new Error("Invalid key");
+      return decoded;
+    };
+    const keys = Object.fromEntries(Object.entries(config.encryptionKeys).map(([id, value]) => [id, decodeKey(value)]));
+    const legacy = config.legacyV1Key === undefined ? undefined : decodeKey(config.legacyV1Key);
+    const lookup = decodeKey(config.lookupKey);
+    if (config.writeVersion === 1 && !legacy || legacy && !legacy.equals(lookup))
+      throw new Error("Incompatible lookup key");
+    const keyring = createFieldEncryptionKeyring({
+      activeKeyId: config.activeKeyId,
+      encryptionKeys: keys,
+      legacyV1Key: legacy,
+      lookupKey: lookup
+    });
+    const writeVersion = config.writeVersion;
+    return Object.freeze({
+      keyring,
+      writeVersion,
+      encrypt(plaintext, purpose) {
+        return writeVersion === 1 && legacy ? encryptField(plaintext, legacy) : keyring.encrypt(plaintext, purpose);
+      }
+    });
+  } catch {
+    throw new Error("Invalid KMS_ENCRYPTION_KEYRING configuration.");
+  }
+}
 
 // ../../src/core/crypto/mfaSecret.ts
 function protectMfaSecret(secret) {
+  const configured = resolveFieldEncryptionKeyring();
+  if (configured)
+    return configured.encrypt(secret, "mfa");
   const key = resolveEncryptionKey();
   if (!key) {
     throw new Error("MFA secrets require KMS_ENCRYPTION_KEY.");
@@ -597,6 +742,14 @@ function revealMfaSecret(stored) {
   if (!stored) {
     return null;
   }
+  const configured = resolveFieldEncryptionKeyring();
+  if (configured) {
+    if (!stored.startsWith("enc:"))
+      throw new Error("MFA secrets must be encrypted.");
+    return configured.keyring.decrypt(stored, "mfa");
+  }
+  if (stored.startsWith("enc:") && !stored.startsWith("enc:v1:"))
+    throw new Error("Identified MFA secrets require KMS_ENCRYPTION_KEYRING.");
   if (!stored.startsWith("enc:v1:")) {
     if (isProductionEnv() || resolveEncryptionKey()) {
       throw new Error("MFA secrets must be encrypted.");

package/dist/entries/auth/passwordLogin.js

@@ -274,7 +274,7 @@ function isFieldEncryptionEnabled() {
   if (featureFlag === "true") {
     return true;
   }
-  return Boolean(resolveEncryptionKey());
+  return Boolean(resolveFieldEncryptionKeyring() || resolveEncryptionKey());
 }
 function encryptField(plaintext, key) {
   const iv = randomBytes(IV_LENGTH);
@@ -304,6 +304,13 @@ function normalizeEmail(email) {
 }
 function protectEmail(email) {
   const normalized = normalizeEmail(email);
+  const configured = resolveFieldEncryptionKeyring();
+  if (configured && isFieldEncryptionEnabled()) {
+    return {
+      storedEmail: configured.encrypt(normalized, "email"),
+      emailLookup: configured.keyring.lookup(normalized)
+    };
+  }
   const key = resolveEncryptionKey();
   if (!key || !isFieldEncryptionEnabled()) {
     return { storedEmail: normalized, emailLookup: normalized };
@@ -314,6 +321,11 @@ function protectEmail(email) {
   };
 }
 function revealEmail(storedEmail) {
+  const configured = resolveFieldEncryptionKeyring();
+  if (configured && storedEmail.startsWith("enc:"))
+    return configured.keyring.decrypt(storedEmail, "email");
+  if (storedEmail.startsWith("enc:") && !storedEmail.startsWith(ENCRYPTION_PREFIX))
+    throw new Error("Identified encrypted fields require KMS_ENCRYPTION_KEYRING.");
   const key = resolveEncryptionKey();
   if (!key || !storedEmail.startsWith(ENCRYPTION_PREFIX)) {
     return storedEmail;
@@ -322,15 +334,148 @@ function revealEmail(storedEmail) {
 }
 function emailLookupForQuery(email) {
   const normalized = normalizeEmail(email);
+  const configured = resolveFieldEncryptionKeyring();
+  if (configured && isFieldEncryptionEnabled())
+    return configured.keyring.lookup(normalized);
   const key = resolveEncryptionKey();
   if (!key || !isFieldEncryptionEnabled()) {
     return normalized;
   }
   return hashLookupValue(normalized, key);
 }
+function createFieldEncryptionKeyring(options) {
+  const identifier = /^[A-Za-z0-9_-]{1,64}$/;
+  const copyKey = (value) => {
+    if (!(value instanceof Uint8Array) || value.byteLength !== 32)
+      throw new TypeError("Field encryption keys must be 32 bytes.");
+    return Buffer.from(value);
+  };
+  const entries = Object.entries(options.encryptionKeys);
+  if (entries.length < 1 || entries.length > 32)
+    throw new TypeError("Field encryption keyrings require 1 to 32 keys.");
+  const keys = new Map;
+  for (const [id, key] of entries) {
+    if (!identifier.test(id))
+      throw new TypeError("Invalid field encryption key identifier.");
+    keys.set(id, copyKey(key));
+  }
+  const activeKeyId = options.activeKeyId;
+  const active = keys.get(activeKeyId);
+  if (!active)
+    throw new TypeError("Active field encryption key is not retained.");
+  const legacy = options.legacyV1Key === undefined ? undefined : copyKey(options.legacyV1Key);
+  const lookup = copyKey(options.lookupKey);
+  const associatedData = (id, purpose) => {
+    if (!identifier.test(purpose))
+      throw new TypeError("Invalid field encryption purpose.");
+    return Buffer.from(`strata:field:v2:${id}:${purpose}`, "utf8");
+  };
+  const decodePayload = (encoded) => {
+    const payload = Buffer.from(encoded, "base64");
+    if (payload.length < IV_LENGTH + TAG_LENGTH || payload.toString("base64") !== encoded)
+      throw new Error("Invalid encrypted field.");
+    return payload;
+  };
+  return Object.freeze({
+    activeKeyId,
+    encrypt(plaintext, purpose) {
+      const aad = associatedData(activeKeyId, purpose);
+      const iv = randomBytes(IV_LENGTH);
+      const cipher = createCipheriv("aes-256-gcm", active, iv, { authTagLength: TAG_LENGTH });
+      cipher.setAAD(aad);
+      const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+      const payload = Buffer.concat([iv, ciphertext, cipher.getAuthTag()]).toString("base64");
+      return `enc:v2:${activeKeyId}:${payload}`;
+    },
+    decrypt(value, purpose) {
+      associatedData(activeKeyId, purpose);
+      try {
+        if (value.startsWith(ENCRYPTION_PREFIX)) {
+          if (!legacy)
+            throw new Error("Missing legacy key");
+          decodePayload(value.slice(ENCRYPTION_PREFIX.length));
+          return decryptField(value, legacy);
+        }
+        const parts = value.split(":");
+        if (parts.length !== 4 || parts[0] !== "enc" || parts[1] !== "v2")
+          throw new Error("Invalid envelope");
+        const id = parts[2] ?? "";
+        const key = keys.get(id);
+        if (!key)
+          throw new Error("Missing retained key");
+        const payload = decodePayload(parts[3] ?? "");
+        const decipher = createDecipheriv("aes-256-gcm", key, payload.subarray(0, IV_LENGTH), {
+          authTagLength: TAG_LENGTH
+        });
+        decipher.setAAD(associatedData(id, purpose));
+        decipher.setAuthTag(payload.subarray(payload.length - TAG_LENGTH));
+        return Buffer.concat([
+          decipher.update(payload.subarray(IV_LENGTH, payload.length - TAG_LENGTH)),
+          decipher.final()
+        ]).toString("utf8");
+      } catch {
+        throw new Error("Unable to decrypt encrypted field.");
+      }
+    },
+    lookup(normalizedValue) {
+      return hashLookupValue(normalizedValue, lookup);
+    }
+  });
+}
+function resolveFieldEncryptionKeyring(env = process.env) {
+  const raw = env.KMS_ENCRYPTION_KEYRING;
+  if (raw === undefined)
+    return null;
+  try {
+    if (!raw.trim() || raw.length > 16384 || env.KMS_ENCRYPTION_KEY?.trim())
+      throw new Error("Invalid configuration");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      throw new Error("Invalid configuration");
+    const config = parsed;
+    if (Object.keys(config).some((key) => !["activeKeyId", "encryptionKeys", "legacyV1Key", "lookupKey", "writeVersion"].includes(key)))
+      throw new Error("Unknown option");
+    if (typeof config.activeKeyId !== "string" || config.writeVersion !== 1 && config.writeVersion !== 2 || !config.encryptionKeys || typeof config.encryptionKeys !== "object" || Array.isArray(config.encryptionKeys))
+      throw new Error("Invalid configuration");
+    const decodeKey = (value) => {
+      if (typeof value !== "string")
+        throw new Error("Invalid key");
+      if (/^[0-9a-f]{64}$/i.test(value))
+        return Buffer.from(value, "hex");
+      const decoded = Buffer.from(value, "base64");
+      if (decoded.length !== 32 || decoded.toString("base64") !== value)
+        throw new Error("Invalid key");
+      return decoded;
+    };
+    const keys = Object.fromEntries(Object.entries(config.encryptionKeys).map(([id, value]) => [id, decodeKey(value)]));
+    const legacy = config.legacyV1Key === undefined ? undefined : decodeKey(config.legacyV1Key);
+    const lookup = decodeKey(config.lookupKey);
+    if (config.writeVersion === 1 && !legacy || legacy && !legacy.equals(lookup))
+      throw new Error("Incompatible lookup key");
+    const keyring = createFieldEncryptionKeyring({
+      activeKeyId: config.activeKeyId,
+      encryptionKeys: keys,
+      legacyV1Key: legacy,
+      lookupKey: lookup
+    });
+    const writeVersion = config.writeVersion;
+    return Object.freeze({
+      keyring,
+      writeVersion,
+      encrypt(plaintext, purpose) {
+        return writeVersion === 1 && legacy ? encryptField(plaintext, legacy) : keyring.encrypt(plaintext, purpose);
+      }
+    });
+  } catch {
+    throw new Error("Invalid KMS_ENCRYPTION_KEYRING configuration.");
+  }
+}
 
 // ../../src/core/crypto/mfaSecret.ts
 function protectMfaSecret(secret) {
+  const configured = resolveFieldEncryptionKeyring();
+  if (configured)
+    return configured.encrypt(secret, "mfa");
   const key = resolveEncryptionKey();
   if (!key) {
     throw new Error("MFA secrets require KMS_ENCRYPTION_KEY.");
@@ -341,6 +486,14 @@ function revealMfaSecret(stored) {
   if (!stored) {
     return null;
   }
+  const configured = resolveFieldEncryptionKeyring();
+  if (configured) {
+    if (!stored.startsWith("enc:"))
+      throw new Error("MFA secrets must be encrypted.");
+    return configured.keyring.decrypt(stored, "mfa");
+  }
+  if (stored.startsWith("enc:") && !stored.startsWith("enc:v1:"))
+    throw new Error("Identified MFA secrets require KMS_ENCRYPTION_KEYRING.");
   if (!stored.startsWith("enc:v1:")) {
     if (isProductionEnv() || resolveEncryptionKey()) {
       throw new Error("MFA secrets must be encrypted.");