@getstrata/core 2.2.10 → 2.2.12

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @getstrata/core changelog
 
+## 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.
+
 ## 2.2.10
 
 - Add bounded OpenTelemetry SDK health observations and selected native transaction-acquisition histograms through explicit metrics options.

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/database/baseRepository.d.ts

@@ -17,6 +17,11 @@ interface DatabaseConnection {
     }): Promise<DatabaseConnection & {
         release(): void | Promise<void>;
     }>;
+    /** Optional independent, interruptible read-only observation; no business transaction or pool slot. */
+    observeReadOnly?<T>(operation: (connection: DatabaseConnection) => Promise<T>, options: {
+        signal: AbortSignal;
+        timeoutMs: number;
+    }): Promise<T>;
     /** SQLite closes synchronously; pooled drivers return a promise. */
     close?(): void | Promise<void>;
 }

package/dist/core/database/isolatedReadOnlyObservation.d.ts

@@ -0,0 +1,15 @@
+import type { DatabaseConnection } from "./baseRepository";
+interface ReadOnlyObservationOptions {
+    signal: AbortSignal;
+    timeoutMs: number;
+}
+declare function observeIsolatedReadOnly<T>(profile: {
+    driver: "sqlite";
+    filename: string;
+} | {
+    driver: "mysql";
+    url: string;
+    module: string;
+}, operation: (connection: DatabaseConnection) => Promise<T>, options: ReadOnlyObservationOptions): Promise<T>;
+export type { ReadOnlyObservationOptions };
+export { observeIsolatedReadOnly };

package/dist/core/database/mysqlConnection.d.ts

@@ -1,4 +1,6 @@
+import type { DatabaseConnection } from "./baseRepository.ts";
 import { type ActiveDatabaseHandle } from "./connectionContext.ts";
+import { type ReadOnlyObservationOptions } from "./isolatedReadOnlyObservation.ts";
 type MysqlExecutable = {
     execute: (sql: string, params?: unknown[]) => Promise<[unknown, unknown]>;
     query?: (sql: string) => Promise<[unknown, unknown]>;
@@ -19,6 +21,7 @@ type MysqlPoolConnection = MysqlExecutable & {
 type MysqlConnection = ActiveDatabaseHandle & {
     begin<T>(callback: (transaction: ActiveDatabaseHandle) => Promise<T>): Promise<T>;
     close(): Promise<void>;
+    observeReadOnly<T>(operation: (connection: DatabaseConnection) => Promise<T>, options: ReadOnlyObservationOptions): Promise<T>;
 };
 declare function resetMysqlLoaderForTests(importer?: () => Promise<unknown>): void;
 declare function createMysqlConnectionFromPool(pool: MysqlExecutable): MysqlConnection;

package/dist/core/database/readOnlyCollector.d.ts

@@ -0,0 +1,7 @@
+interface ReadOnlyCollector<T> {
+    collect(): Promise<T>;
+    close(): Promise<void>;
+}
+/** Internal shared observation lifecycle. No bypass, payload or tenant enumeration. */
+declare function createReadOnlyCollector<T>(name: string, timeoutMs: number, collect: (remaining: () => number) => Promise<T>): ReadOnlyCollector<T>;
+export { createReadOnlyCollector };

package/dist/core/database/sqliteConnection.d.ts

@@ -1,6 +1,9 @@
+import type { DatabaseConnection } from "./baseRepository.ts";
 import { type ActiveDatabaseHandle } from "./connectionContext.ts";
+import { type ReadOnlyObservationOptions } from "./isolatedReadOnlyObservation.ts";
 type SqliteConnection = ActiveDatabaseHandle & {
     begin<T>(callback: (transaction: ActiveDatabaseHandle) => Promise<T>): Promise<T>;
+    observeReadOnly<T>(operation: (connection: DatabaseConnection) => Promise<T>, options: ReadOnlyObservationOptions): Promise<T>;
     close(): void;
 };
 declare function createSqliteConnection(filename: string): SqliteConnection;

package/dist/core/events/outbox/metrics.d.ts

@@ -19,7 +19,7 @@ interface OutboxMetricsCollector {
 }
 declare const snapshotQuery: string;
 /** Explicit platform observation, using the same transaction-local RLS bypass as coordination.
- * Initially Postgres-only: other engines fail rather than receiving a false empty snapshot.
+ * Postgres uses scoped bypass; official SQLite/MySQL adapters use isolated read-only snapshots.
  */
 declare function createOutboxMetricsCollector(options?: OutboxMetricsOptions): OutboxMetricsCollector;
 declare function renderOutboxMetrics(snapshot: OutboxMetricsSnapshot): string;

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.");