@katlux/providers 0.1.1-alpha.125 → 0.1.1-alpha.127

package/dist/index.cjs

@@ -18,6 +18,8 @@ function _interopNamespaceCompat(e) {
 
 const crypto__namespace = /*#__PURE__*/_interopNamespaceCompat(crypto$1);
 
+const DECRYPT_ERROR_SENTINEL = Symbol.for("katlux.decrypt_error");
+
 var EDataFilterOperator = /* @__PURE__ */ ((EDataFilterOperator2) => {
   EDataFilterOperator2["Equal"] = "==";
   EDataFilterOperator2["NotEqual"] = "!=";
@@ -672,13 +674,84 @@ function isAuthOrDecryptionError(err) {
   const msg = String(err.message || "").toLowerCase();
   return msg.includes("operationerror") || msg.includes("decrypt") || msg.includes("tag") || msg.includes("aad") || msg.includes("authenticated additional data") || msg.includes("authenticate data") || msg.includes("mac");
 }
+function canonicalizeJson(value, seen = /* @__PURE__ */ new Set()) {
+  if (value === void 0) {
+    return "";
+  }
+  if (value === null || typeof value === "boolean") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return "null";
+    if (Object.is(value, -0)) return "0";
+    return JSON.stringify(value);
+  }
+  if (typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "bigint") {
+    throw new TypeError("Do not know how to serialize a BigInt");
+  }
+  if (typeof value === "symbol" || typeof value === "function") {
+    return "";
+  }
+  if (typeof value === "object") {
+    if (typeof value.toJSON === "function") {
+      return canonicalizeJson(value.toJSON(), seen);
+    }
+    if (seen.has(value)) {
+      throw new TypeError("Converting circular structure to JSON");
+    }
+    seen.add(value);
+    try {
+      if (Array.isArray(value)) {
+        const items = value.map((item) => {
+          if (item === void 0 || typeof item === "function" || typeof item === "symbol") {
+            return "null";
+          }
+          const res = canonicalizeJson(item, seen);
+          return res === "" ? "null" : res;
+        });
+        return `[${items.join(",")}]`;
+      }
+      const keys = Object.keys(value).sort();
+      const entries = [];
+      for (const key of keys) {
+        const val = value[key];
+        if (val === void 0 || typeof val === "function" || typeof val === "symbol") {
+          continue;
+        }
+        const serialized = canonicalizeJson(val, seen);
+        if (serialized !== "") {
+          entries.push(`${JSON.stringify(key)}:${serialized}`);
+        }
+      }
+      return `{${entries.join(",")}}`;
+    } finally {
+      seen.delete(value);
+    }
+  }
+  return JSON.stringify(value);
+}
 
 class AEncryptionProvider {
   defaultKey;
-  constructor(key) {
+  keys;
+  activeKid;
+  allowedKids;
+  constructor(key, options) {
     if (key !== void 0) {
       this.defaultKey = key;
     }
+    if (options?.keys) {
+      this.keys = options.keys;
+    }
+    if (options?.activeKid) {
+      this.activeKid = options.activeKid;
+    }
+    if (options?.allowedKids) {
+      this.allowedKids = options.allowedKids;
+    }
   }
   /**
    * Sets or updates the default secret key, CryptoKey, or async key provider function.
@@ -692,6 +765,33 @@ class AEncryptionProvider {
   getDefaultKey() {
     return this.defaultKey;
   }
+  /**
+   * Configures a keyring dictionary of keys with an optional active key identifier.
+   */
+  setKeyring(keys, activeKid) {
+    this.keys = keys;
+    if (activeKid !== void 0) {
+      this.activeKid = activeKid;
+    }
+  }
+  /**
+   * Retrieves the currently configured keyring dictionary.
+   */
+  getKeyring() {
+    return this.keys;
+  }
+  /**
+   * Sets the active Key Identifier (kid) to use for outbound encryption.
+   */
+  setActiveKid(kid) {
+    this.activeKid = kid;
+  }
+  /**
+   * Retrieves the active Key Identifier (kid).
+   */
+  getActiveKid() {
+    return this.activeKid;
+  }
   /**
    * Pre-derives and caches the native CryptoKey for subsequent cryptographic operations.
    * Subclasses should override this with a dedicated, non-side-effecting implementation.
@@ -702,7 +802,7 @@ class AEncryptionProvider {
    * Resolves raw key from keyProvider callback or defaultKey.
    */
   async resolveRawKey(keyProvider) {
-    const target = keyProvider || this.defaultKey;
+    const target = keyProvider || (this.keys && this.activeKid ? this.keys[this.activeKid] : void 0) || this.defaultKey;
     if (!target) {
       throw new Error(
         `[${this.constructor.name}] No encryption key or keyProvider was supplied. Key cannot be empty or undefined. A valid key must be supplied from your authentication or secret management system.`
@@ -734,6 +834,9 @@ class AEncryptionProvider {
    */
   clearKeys() {
     this.defaultKey = void 0;
+    this.keys = void 0;
+    this.activeKid = void 0;
+    this.allowedKids = void 0;
   }
   /**
    * Alias for clearKeys() to conform with standard disposal patterns.
@@ -760,16 +863,26 @@ class AEncryptionProvider {
    */
   _resolveEffectiveAad(options, isDecrypt = false) {
     if (!options) return void 0;
-    if (options.bindRequestContextAad === false) return options.aad;
+    let rawAad = options.aad;
+    if (typeof rawAad === "function") {
+      rawAad = rawAad(void 0, "");
+    }
+    if (rawAad === void 0 && options.baseAad) {
+      rawAad = options.baseAad;
+    }
+    if (options.bindRequestContextAad === false) return rawAad;
     const hasReqContext = Boolean(options.url || options.method);
-    if (options.aad) {
+    if (rawAad) {
       if (options.bindRequestContextAad === true && hasReqContext) {
         const m = (options.method || "POST").toUpperCase();
         const u = options.url || "";
-        const baseAad = typeof options.aad === "string" ? options.aad : options.aad instanceof Uint8Array || options.aad instanceof ArrayBuffer ? textDecoder.decode(options.aad) : String(options.aad);
+        const baseAad = typeof rawAad === "string" ? rawAad : rawAad instanceof Uint8Array || rawAad instanceof ArrayBuffer ? textDecoder.decode(rawAad) : String(rawAad);
+        if (baseAad.includes(`|req:${m}:${u}`)) {
+          return baseAad;
+        }
         return `${baseAad}|req:${m}:${u}`;
       }
-      return options.aad;
+      return rawAad;
     }
     const shouldBindReq = isDecrypt ? hasReqContext : options.bindRequestContextAad === true && hasReqContext;
     if (shouldBindReq) {
@@ -780,27 +893,169 @@ class AEncryptionProvider {
     return void 0;
   }
   /**
-   * Helper to deterministically bind record ID and field name into the AAD
-   * to prevent ciphertext swapping between fields or records.
+   * Helper to deterministically bind record ID, contextual sibling fields (aadFields),
+   * dynamic AAD callbacks, and field name into the AAD to prevent ciphertext swapping
+   * between fields, records, or parent entities.
    */
   _bindFieldAad(data, field, options) {
     let baseAad = "";
+    if (options?.baseAad) {
+      baseAad = options.baseAad;
+    }
     if (options?.aad) {
-      if (typeof options.aad === "string") baseAad = options.aad;
-      else if (options.aad instanceof Uint8Array || options.aad instanceof ArrayBuffer) {
-        baseAad = textDecoder.decode(options.aad);
+      if (typeof options.aad === "function") {
+        const dynamicRes = options.aad(data, field);
+        if (typeof dynamicRes === "string") {
+          baseAad = baseAad ? `${baseAad}|${dynamicRes}` : dynamicRes;
+        } else if (dynamicRes instanceof Uint8Array || dynamicRes instanceof ArrayBuffer) {
+          const decoded = textDecoder.decode(dynamicRes);
+          baseAad = baseAad ? `${baseAad}|${decoded}` : decoded;
+        } else if (dynamicRes !== void 0 && dynamicRes !== null) {
+          const str = String(dynamicRes);
+          baseAad = baseAad ? `${baseAad}|${str}` : str;
+        }
+      } else if (typeof options.aad === "string") {
+        baseAad = baseAad ? `${baseAad}|${options.aad}` : options.aad;
+      } else if (options.aad instanceof Uint8Array || options.aad instanceof ArrayBuffer) {
+        const decoded = textDecoder.decode(options.aad);
+        baseAad = baseAad ? `${baseAad}|${decoded}` : decoded;
       } else {
-        baseAad = String(options.aad);
+        const str = String(options.aad);
+        baseAad = baseAad ? `${baseAad}|${str}` : str;
       }
     }
     const recordId = data && typeof data === "object" && (data.id !== void 0 || data._id !== void 0) ? String(data.id ?? data._id) : "";
     const recordPart = recordId ? `|record:${recordId}` : "";
+    let contextPart = "";
+    if (options?.aadFields && options.aadFields.length > 0 && data && typeof data === "object") {
+      const sortedFields = [...options.aadFields].sort();
+      const parts = [];
+      for (const f of sortedFields) {
+        const val = data[f];
+        let serializedVal = "";
+        if (val === null) {
+          serializedVal = "null";
+        } else if (val !== void 0) {
+          serializedVal = typeof val === "object" ? JSON.stringify(val) : String(val);
+        }
+        parts.push(`${f}=${serializedVal}`);
+      }
+      contextPart = `|ctx:${parts.join(",")}`;
+    }
     const reqPart = options?.bindRequestContextAad === true && (options?.url || options?.method) ? `|req:${(options.method || "POST").toUpperCase()}:${options.url || ""}` : "";
     return {
       ...options,
-      aad: `aad:${baseAad}${recordPart}${reqPart}|field:${field}`
+      bindRequestContextAad: false,
+      aad: `aad:${baseAad}${recordPart}${contextPart}${reqPart}|field:${field}`
     };
   }
+  /**
+   * Validates envelope metadata against algorithm whitelists and key identifiers (kid).
+   * In strict mode, allowedAlgorithms defaults to ['AES-GCM'].
+   */
+  _validateEnvelopeMetadata(payload, options) {
+    if (!payload || typeof payload !== "object") return void 0;
+    const allowedAlgorithms = options?.allowedAlgorithms ?? (options?.strict ? ["AES-GCM"] : void 0);
+    if (allowedAlgorithms && allowedAlgorithms.length > 0) {
+      const alg = payload.alg;
+      if (!alg || !allowedAlgorithms.includes(alg)) {
+        return new Error(`[AEncryptionProvider] Algorithm mismatch: algorithm '${alg || "unknown"}' is not in allowedAlgorithms.`);
+      }
+    }
+    const effectiveKeys = options?.keys || this.keys;
+    const effectiveAllowedKids = options?.allowedKids || this.allowedKids;
+    const allowedKids = effectiveAllowedKids ?? (effectiveKeys ? Object.keys(effectiveKeys) : void 0);
+    if (allowedKids && allowedKids.length > 0) {
+      if (payload.kid && !allowedKids.includes(payload.kid)) {
+        return new Error(`[AEncryptionProvider] Unauthorized key: kid '${payload.kid}' is not in allowedKids.`);
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Normalizes encryption options with active keyring parameters:
+   * If `keys` and `activeKid` are configured, selects `key = keys[activeKid]` and sets `kid = activeKid`.
+   */
+  _resolveOutboundKeyringOptions(options) {
+    const effectiveKeys = options?.keys || this.keys;
+    const effectiveActiveKid = options?.activeKid || (options?.kid ? options.kid : this.activeKid);
+    let effectiveKey = options?.key;
+    let effectiveKid = options?.kid || effectiveActiveKid;
+    if (effectiveKeys && effectiveActiveKid) {
+      if (effectiveKeys[effectiveActiveKid]) {
+        effectiveKey = options?.key || effectiveKeys[effectiveActiveKid];
+        effectiveKid = effectiveActiveKid;
+      } else if (!options?.key) {
+        throw new Error(`[${this.constructor.name}] Active kid '${effectiveActiveKid}' not found in keyring keys.`);
+      }
+    } else if (effectiveKeys && !effectiveKey) {
+      const kids = Object.keys(effectiveKeys);
+      if (kids.length > 0) {
+        effectiveKid = kids[0];
+        effectiveKey = effectiveKeys[kids[0]];
+      }
+    }
+    if (effectiveKeys || effectiveActiveKid || effectiveKey !== options?.key || effectiveKid !== options?.kid) {
+      return {
+        ...options,
+        ...effectiveKeys ? { keys: effectiveKeys } : {},
+        ...effectiveActiveKid ? { activeKid: effectiveActiveKid } : {},
+        ...effectiveKey !== void 0 ? { key: effectiveKey } : {},
+        ...effectiveKid !== void 0 ? { kid: effectiveKid } : {}
+      };
+    }
+    return options || {};
+  }
+  /**
+   * Resolves the appropriate decryption key for a specific payload envelope based on its `kid`
+   * and the configured keyring (`keys`, `activeKid`, or fallback `key`).
+   */
+  _resolveDecryptionKeyForEnvelope(payload, options) {
+    const effectiveKeys = options?.keys || this.keys;
+    const effectiveActiveKid = options?.activeKid || this.activeKid;
+    if (payload && typeof payload === "object" && payload.kid && effectiveKeys) {
+      if (effectiveKeys[payload.kid]) {
+        return effectiveKeys[payload.kid];
+      }
+    }
+    if (effectiveKeys && effectiveActiveKid && effectiveKeys[effectiveActiveKid]) {
+      return effectiveKeys[effectiveActiveKid];
+    }
+    return options?.key || this.defaultKey;
+  }
+  /**
+   * Handles a per-field or per-payload decryption error according to configured options:
+   * - Invokes onDecryptError callback if provided
+   * - Attaches error metadata (__decryptErrors) to the record object
+   * - Returns fallback cell placeholder ('[⚠ Decryption Error]') or rethrows
+   */
+  _handleDecryptError(err, record, field, value, index, options) {
+    if (record && typeof record === "object" && record !== value) {
+      record.__decryptErrors = {
+        ...record.__decryptErrors || {},
+        [field || "__payload"]: err
+      };
+    }
+    if (options?.onDecryptError === false || options?.onDecryptError === void 0) {
+      throw err;
+    }
+    if (typeof options.onDecryptError === "function") {
+      return options.onDecryptError({
+        record,
+        field,
+        value,
+        error: err,
+        index
+      });
+    }
+    if (typeof options.onDecryptError === "string") {
+      return options.onDecryptError;
+    }
+    if (options.onDecryptError === true) {
+      return "[\u26A0 Decryption Error]";
+    }
+    throw err;
+  }
   /**
    * Top-level polymorphic encryption method.
    * Automatically performs value-level encryption:
@@ -812,6 +1067,7 @@ class AEncryptionProvider {
   async encrypt(data, options) {
     if (data === void 0 || data === null) return data;
     if (this.isEncrypted(data)) return data;
+    options = this._resolveOutboundKeyringOptions(options);
     if (options?.valueEncryption === false && (!options.fields || options.fields.length === 0)) {
       return this.encryptValue(data, options);
     }
@@ -898,65 +1154,106 @@ class AEncryptionProvider {
   /**
    * Top-level polymorphic decryption method.
    * Automatically performs value-level decryption:
-   * - If payload is an encrypted envelope: decrypts directly via decryptValue.
-   * - If payload is an array of objects: decrypts each row.
-   * - If payload is an object: decrypts any encrypted value cells across fields.
-   */
-  /**
-   * Top-level polymorphic decryption method.
-   * Automatically performs value-level decryption:
-   * - If payload is an encrypted envelope: decrypts directly via decryptValue.
+   * - If payload is an encrypted envelope: validates metadata and decrypts directly via decryptValue.
    * - If payload is an array of objects: decrypts each row (batched with local memoization).
    * - If payload is an object: decrypts any encrypted value cells across fields.
+   * In strict mode:
+   * - Unencrypted plaintext in configured `fields` triggers a decryption error.
+   * - Envelopes are validated against `allowedAlgorithms` and `allowedKids`.
+   * - Errors are routed through `onDecryptError` or populated into `__decryptErrors`.
    */
   async decrypt(payload, options) {
     if (payload === void 0 || payload === null) return payload;
     if (this.isEncrypted(payload)) {
-      return this.decryptValue(payload, options);
+      const envelopeKey = this._resolveDecryptionKeyForEnvelope(payload, options);
+      const envelopeOptions = envelopeKey !== options?.key ? { ...options, key: envelopeKey } : options;
+      const metaErr = this._validateEnvelopeMetadata(payload, envelopeOptions);
+      if (metaErr) {
+        return this._handleDecryptError(metaErr, payload, "", payload, void 0, envelopeOptions);
+      }
+      try {
+        return await this.decryptValue(payload, envelopeOptions);
+      } catch (err) {
+        return this._handleDecryptError(err, payload, "", payload, void 0, envelopeOptions);
+      }
     }
     if (Array.isArray(payload)) {
       if (payload.length === 0) return payload;
       const localMemo = /* @__PURE__ */ new Map();
-      const decryptRow = async (item) => {
+      const decryptRow = async (item, rowIndex) => {
         if (!item) return item;
         if (this.isEncrypted(item)) {
+          const envelopeKey = this._resolveDecryptionKeyForEnvelope(item, options);
+          const envelopeOptions = envelopeKey !== options?.key ? { ...options, key: envelopeKey } : options;
+          const metaErr = this._validateEnvelopeMetadata(item, envelopeOptions);
+          if (metaErr) {
+            return this._handleDecryptError(metaErr, item, "", item, rowIndex, envelopeOptions);
+          }
           const ct = item.ciphertext;
           const iv = item.iv || "";
           const aadPart = options?.aad ? typeof options.aad === "string" ? options.aad : "" : "";
-          const memoKey = `${ct}:${iv}:${aadPart}`;
-          if (!localMemo.has(memoKey)) {
-            localMemo.set(memoKey, this.decryptValue(item, options));
+          const memoKey = `${ct}:${iv}:${aadPart}:${item.kid || ""}`;
+          try {
+            if (!localMemo.has(memoKey)) {
+              localMemo.set(memoKey, this.decryptValue(item, envelopeOptions));
+            }
+            return await localMemo.get(memoKey);
+          } catch (err) {
+            return this._handleDecryptError(err, item, "", item, rowIndex, envelopeOptions);
           }
-          return localMemo.get(memoKey);
         }
         if (typeof item === "object" && !ArrayBuffer.isView(item) && !(item instanceof ArrayBuffer)) {
           const targetKeys = options?.fields && options.fields.length > 0 ? options.fields.filter((f) => Object.prototype.hasOwnProperty.call(item, f)) : Object.keys(item);
           const keysToDecrypt = targetKeys.filter((key) => this.isEncrypted(item[key]));
-          if (keysToDecrypt.length === 0) {
+          const strictViolationKeys = options?.strict === true && options?.fields && options.fields.length > 0 ? targetKeys.filter((key) => item[key] !== void 0 && item[key] !== null && !this.isEncrypted(item[key])) : [];
+          if (keysToDecrypt.length === 0 && strictViolationKeys.length === 0) {
             return item;
           }
           const proto = Object.getPrototypeOf(item);
           const result = proto && proto !== Object.prototype ? Object.assign(Object.create(proto), item) : { ...item };
+          for (const key of strictViolationKeys) {
+            const err = new Error(`[AEncryptionProvider] Strict decryption violation: field '${key}' contains unencrypted plaintext.`);
+            const fallbackVal = this._handleDecryptError(err, result, key, item[key], rowIndex, options);
+            safeSetProperty(result, key, fallbackVal);
+          }
           await Promise.all(
             keysToDecrypt.map(async (key) => {
               const env = item[key];
-              const boundOptions = this._bindFieldAad(item, key, options);
-              const hasBoundAad = boundOptions.aad !== options?.aad;
+              const envelopeKey = this._resolveDecryptionKeyForEnvelope(env, options);
+              const baseOptions = envelopeKey !== options?.key ? { ...options, key: envelopeKey } : options;
+              const boundOptions = this._bindFieldAad(item, key, baseOptions);
+              const hasBoundAad = boundOptions.aad !== baseOptions?.aad;
+              const metaErr = this._validateEnvelopeMetadata(env, boundOptions);
+              if (metaErr) {
+                const fallbackVal = this._handleDecryptError(metaErr, result, key, env, rowIndex, boundOptions);
+                safeSetProperty(result, key, fallbackVal);
+                return;
+              }
               const ct = env.ciphertext;
               const iv = env.iv || "";
               const aadPart = boundOptions.aad ? typeof boundOptions.aad === "string" ? boundOptions.aad : "" : "";
-              const memoKey = `${ct}:${iv}:${aadPart}`;
-              if (!localMemo.has(memoKey)) {
-                const decryptPromise = this.decryptValue(env, boundOptions).catch((err) => {
-                  if (hasBoundAad && isAuthOrDecryptionError(err)) {
-                    return this.decryptValue(env, options);
-                  }
-                  throw err;
-                });
-                localMemo.set(memoKey, decryptPromise);
+              const memoKey = `${ct}:${iv}:${aadPart}:${env.kid || ""}`;
+              try {
+                if (!localMemo.has(memoKey)) {
+                  const decryptPromise = (async () => {
+                    try {
+                      return await this.decryptValue(env, boundOptions);
+                    } catch (err) {
+                      const canFallback = hasBoundAad && (!options?.aadFields || options.aadFields.length === 0) && typeof options?.aad !== "function";
+                      if (canFallback && isAuthOrDecryptionError(err)) {
+                        return await this.decryptValue(env, baseOptions);
+                      }
+                      throw err;
+                    }
+                  })();
+                  localMemo.set(memoKey, decryptPromise);
+                }
+                const decryptedVal = await localMemo.get(memoKey);
+                safeSetProperty(result, key, decryptedVal);
+              } catch (err) {
+                const fallbackVal = this._handleDecryptError(err, result, key, env, rowIndex, boundOptions);
+                safeSetProperty(result, key, fallbackVal);
               }
-              const decryptedVal = await localMemo.get(memoKey);
-              safeSetProperty(result, key, decryptedVal);
             })
           );
           return result;
@@ -964,14 +1261,14 @@ class AEncryptionProvider {
         return item;
       };
       if (payload.length <= 100) {
-        return Promise.all(payload.map(decryptRow));
+        return Promise.all(payload.map((item, index) => decryptRow(item, index)));
       }
       const batchSize = 1e3;
       const results = new Array(payload.length);
       for (let i = 0; i < payload.length; i += batchSize) {
         const end = Math.min(i + batchSize, payload.length);
         const chunk = payload.slice(i, end);
-        const chunkRes = await Promise.all(chunk.map(decryptRow));
+        const chunkRes = await Promise.all(chunk.map((item, localIdx) => decryptRow(item, i + localIdx)));
         for (let j = 0; j < chunkRes.length; j++) {
           results[i + j] = chunkRes[j];
         }
@@ -984,32 +1281,49 @@ class AEncryptionProvider {
     if (typeof payload === "object" && !ArrayBuffer.isView(payload) && !(payload instanceof ArrayBuffer)) {
       const targetKeys = options?.fields && options.fields.length > 0 ? options.fields.filter((f) => Object.prototype.hasOwnProperty.call(payload, f)) : Object.keys(payload);
       const keysToDecrypt = targetKeys.filter((key) => this.isEncrypted(payload[key]));
-      if (keysToDecrypt.length === 0) {
+      const strictViolationKeys = options?.strict === true && options?.fields && options.fields.length > 0 ? targetKeys.filter((key) => payload[key] !== void 0 && payload[key] !== null && !this.isEncrypted(payload[key])) : [];
+      if (keysToDecrypt.length === 0 && strictViolationKeys.length === 0) {
         return payload;
       }
       const proto = Object.getPrototypeOf(payload);
       const result = proto && proto !== Object.prototype ? Object.assign(Object.create(proto), payload) : { ...payload };
-      const entries = await Promise.all(
+      for (const key of strictViolationKeys) {
+        const err = new Error(`[AEncryptionProvider] Strict decryption violation: field '${key}' contains unencrypted plaintext.`);
+        const fallbackVal = this._handleDecryptError(err, result, key, payload[key], void 0, options);
+        safeSetProperty(result, key, fallbackVal);
+      }
+      await Promise.all(
         keysToDecrypt.map(async (key) => {
-          const boundOptions = this._bindFieldAad(payload, key, options);
-          const hasBoundAad = boundOptions.aad !== options?.aad;
+          const env = payload[key];
+          const envelopeKey = this._resolveDecryptionKeyForEnvelope(env, options);
+          const baseOptions = envelopeKey !== options?.key ? { ...options, key: envelopeKey } : options;
+          const boundOptions = this._bindFieldAad(payload, key, baseOptions);
+          const hasBoundAad = boundOptions.aad !== baseOptions?.aad;
+          const metaErr = this._validateEnvelopeMetadata(env, boundOptions);
+          if (metaErr) {
+            const fallbackVal = this._handleDecryptError(metaErr, result, key, env, void 0, boundOptions);
+            safeSetProperty(result, key, fallbackVal);
+            return;
+          }
           try {
-            return [key, await this.decryptValue(result[key], boundOptions)];
-          } catch (err) {
-            if (hasBoundAad && isAuthOrDecryptionError(err)) {
-              try {
-                return [key, await this.decryptValue(result[key], options)];
-              } catch (fallbackErr) {
-                throw fallbackErr;
+            let decryptedVal;
+            try {
+              decryptedVal = await this.decryptValue(env, boundOptions);
+            } catch (err) {
+              const canFallback = hasBoundAad && (!options?.aadFields || options.aadFields.length === 0) && typeof options?.aad !== "function";
+              if (canFallback && isAuthOrDecryptionError(err)) {
+                decryptedVal = await this.decryptValue(env, baseOptions);
+              } else {
+                throw err;
               }
             }
-            throw err;
+            safeSetProperty(result, key, decryptedVal);
+          } catch (err) {
+            const fallbackVal = this._handleDecryptError(err, result, key, env, void 0, boundOptions);
+            safeSetProperty(result, key, fallbackVal);
           }
         })
       );
-      for (const [key, decryptedVal] of entries) {
-        safeSetProperty(result, key, decryptedVal);
-      }
       return result;
     }
     return payload;
@@ -1442,6 +1756,46 @@ ${lines.join("\n")}
       `[CKeyManager] Unsupported user key algorithm for unwrapAccountKeyForUser: '${userPrivateKey.algorithm.name}'. Expected 'RSA-OAEP'.`
     );
   }
+  /**
+   * Atomically re-wraps an Account Data Encryption Key (ADEK) for a new recipient
+   * without exposing the raw extractable symmetric key to caller application code.
+   *
+   * @param wrappedKeyBase64 - The existing ADEK envelope wrapped with current user's public key
+   * @param myPrivateKey - Current user's RSA-OAEP private key
+   * @param recipientPublicKey - New recipient's RSA-OAEP public key
+   * @returns Base64-encoded wrapped key envelope for the recipient
+   */
+  static async rewrapAccountKeyForUser(wrappedKeyBase64, myPrivateKey, recipientPublicKey) {
+    const subtle = getSubtleCrypto();
+    if (!myPrivateKey || !myPrivateKey.algorithm || myPrivateKey.algorithm.name !== "RSA-OAEP" || !recipientPublicKey || !recipientPublicKey.algorithm || recipientPublicKey.algorithm.name !== "RSA-OAEP") {
+      throw new Error(`[CKeyManager] rewrapAccountKeyForUser requires RSA-OAEP keys.`);
+    }
+    if (myPrivateKey.type === "public" || recipientPublicKey.type === "private") {
+      throw new Error(
+        `[CKeyManager] rewrapAccountKeyForUser requires an RSA-OAEP private key for decryption and an RSA-OAEP public key for encryption.`
+      );
+    }
+    const wrappedBytes = CKeyManager.fromBase64(wrappedKeyBase64);
+    let rawKeyBuffer;
+    try {
+      rawKeyBuffer = await subtle.decrypt(
+        { name: "RSA-OAEP" },
+        myPrivateKey,
+        wrappedBytes
+      );
+      const rewrappedBuffer = await subtle.encrypt(
+        { name: "RSA-OAEP" },
+        recipientPublicKey,
+        rawKeyBuffer
+      );
+      return CKeyManager.toBase64(rewrappedBuffer);
+    } finally {
+      wrappedBytes.fill(0);
+      if (rawKeyBuffer) {
+        new Uint8Array(rawKeyBuffer).fill(0);
+      }
+    }
+  }
   // ── Key Derivation Functions (PBKDF2 & HKDF) ──────────────────────────────
   /**
    * Derives a symmetric AES-GCM CryptoKey from a passphrase using PBKDF2 or HKDF.
@@ -1545,6 +1899,299 @@ ${lines.join("\n")}
       ["encrypt", "decrypt"]
     );
   }
+  /**
+   * Derives two domain-separated, cryptographically isolated keys from a user password and salt:
+   * 1. `authKey`: For client authentication, SRP, or server challenge proofs.
+   * 2. `encryptionKey`: For AES-GCM local and field-level data encryption.
+   *
+   * Stage 1 (Password Stretching): PBKDF2-HMAC-SHA256 stretches low-entropy password into master secret.
+   * Stage 2 (Domain Expansion): HKDF-Expand derives subkeys using domain-separated context info tags.
+   * Immediate memory zeroization of intermediate master secret buffer is guaranteed.
+   *
+   * @param password - Master user password or passphrase
+   * @param salt - Salt (or omitted to generate a secure random 16-byte salt)
+   * @param options - PBKDF2 and HKDF configuration options
+   */
+  static async deriveAuthAndEncryptionKeys(password, salt, options = {}) {
+    if (!password || typeof password === "string" && password.trim().length === 0 || typeof password === "object" && "byteLength" in password && password.byteLength === 0) {
+      throw new Error("[CKeyManager] Password cannot be empty or undefined for key derivation.");
+    }
+    const subtle = getSubtleCrypto();
+    let saltBytes;
+    if (salt !== void 0) {
+      saltBytes = CKeyManager.resolveSalt(salt);
+    } else {
+      saltBytes = CKeyManager.randomBytes(16);
+    }
+    const saltBase64 = CKeyManager.toBase64(saltBytes);
+    const iterations = options.iterations || 31e4;
+    const hash = options.hash || "SHA-256";
+    const authKeyLength = options.authKeyLength || 256;
+    const encryptionKeyLength = options.encryptionKeyLength || 256;
+    const authAlgorithm = options.authAlgorithm || "HMAC";
+    const authInfo = resolveInfoBytes(options.authInfo, "katlux-auth-key-v1");
+    const encryptionInfo = resolveInfoBytes(options.encryptionInfo, "katlux-encryption-key-v1");
+    const extractable = options.extractable === true;
+    const rawPasswordBytes = typeof password === "string" ? textEncoder$1.encode(password) : password instanceof Uint8Array ? new Uint8Array(password.buffer, password.byteOffset, password.byteLength) : new Uint8Array(password);
+    let masterBits;
+    try {
+      const baseKey = await subtle.importKey(
+        "raw",
+        rawPasswordBytes,
+        "PBKDF2",
+        false,
+        ["deriveBits"]
+      );
+      const bitsLength = hash === "SHA-512" ? 512 : 256;
+      masterBits = await subtle.deriveBits(
+        {
+          name: "PBKDF2",
+          salt: saltBytes,
+          iterations,
+          hash
+        },
+        baseKey,
+        bitsLength
+      );
+      const hkdfKey = await subtle.importKey(
+        "raw",
+        masterBits,
+        "HKDF",
+        false,
+        ["deriveKey"]
+      );
+      const authDerivedAlgorithm = authAlgorithm === "AES-GCM" ? { name: "AES-GCM", length: authKeyLength } : { name: "HMAC", hash: { name: hash }, length: authKeyLength };
+      const authUsages = authAlgorithm === "AES-GCM" ? ["encrypt", "decrypt"] : ["sign", "verify"];
+      const authKey = await subtle.deriveKey(
+        {
+          name: "HKDF",
+          hash,
+          salt: new Uint8Array(0),
+          info: authInfo
+        },
+        hkdfKey,
+        authDerivedAlgorithm,
+        extractable,
+        authUsages
+      );
+      const encryptionKey = await subtle.deriveKey(
+        {
+          name: "HKDF",
+          hash,
+          salt: new Uint8Array(0),
+          info: encryptionInfo
+        },
+        hkdfKey,
+        { name: "AES-GCM", length: encryptionKeyLength },
+        extractable,
+        ["encrypt", "decrypt"]
+      );
+      return {
+        authKey,
+        encryptionKey,
+        salt: saltBase64
+      };
+    } finally {
+      if (typeof password === "string") {
+        rawPasswordBytes.fill(0);
+      }
+      if (masterBits) {
+        new Uint8Array(masterBits).fill(0);
+      }
+    }
+  }
+  // ── Digital Signatures, Fingerprints & Access Grants ─────────────────────
+  /**
+   * Generates an ECDSA P-256 signing key pair.
+   */
+  static async generateSigningKeyPair(curve = "P-256", extractable = true) {
+    const subtle = getSubtleCrypto();
+    const pair = await subtle.generateKey(
+      {
+        name: "ECDSA",
+        namedCurve: curve
+      },
+      extractable,
+      ["sign", "verify"]
+    );
+    return {
+      publicKey: pair.publicKey,
+      privateKey: pair.privateKey
+    };
+  }
+  /**
+   * Generates a deterministic SHA-256 fingerprint for a public key (SPKI or raw).
+   * Formatted as `SHA256:<base64url>`.
+   */
+  static async getKeyFingerprint(publicKey) {
+    const subtle = getSubtleCrypto();
+    let rawBytes;
+    if (typeof publicKey === "object" && publicKey !== null && "algorithm" in publicKey) {
+      const cryptoKey = publicKey;
+      rawBytes = await subtle.exportKey("spki", cryptoKey);
+    } else if (publicKey instanceof Uint8Array) {
+      rawBytes = publicKey;
+    } else if (publicKey instanceof ArrayBuffer) {
+      rawBytes = publicKey;
+    } else if (typeof publicKey === "string") {
+      const trimmed = publicKey.trim();
+      if (trimmed.startsWith("-----BEGIN")) {
+        const b642 = trimmed.replace(/-----[^-]+-----/g, "").replace(/\s+/g, "");
+        rawBytes = CKeyManager.fromBase64(b642);
+      } else {
+        try {
+          rawBytes = CKeyManager.fromBase64(trimmed);
+        } catch {
+          rawBytes = textEncoder$1.encode(trimmed);
+        }
+      }
+    } else {
+      throw new Error(
+        "[CKeyManager] Invalid key input for getKeyFingerprint: expected CryptoKey, Uint8Array, ArrayBuffer, or string."
+      );
+    }
+    const hashBuffer = await subtle.digest("SHA-256", rawBytes);
+    const b64 = CKeyManager.toBase64(hashBuffer);
+    const b64url = b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    return `SHA256:${b64url}`;
+  }
+  /**
+   * Signs arbitrary data or JSON objects using an ECDSA P-256 private key.
+   * Objects are automatically serialized via canonicalizeJson() before hashing.
+   */
+  static async sign(data, privateKey) {
+    const subtle = getSubtleCrypto();
+    if (!privateKey || !privateKey.algorithm || privateKey.algorithm.name !== "ECDSA") {
+      throw new Error("[CKeyManager] sign requires an ECDSA private key.");
+    }
+    let dataBytes;
+    if (data instanceof Uint8Array) {
+      dataBytes = data;
+    } else if (ArrayBuffer.isView(data)) {
+      dataBytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    } else if (data instanceof ArrayBuffer) {
+      dataBytes = new Uint8Array(data);
+    } else if (typeof data === "string") {
+      dataBytes = textEncoder$1.encode(data);
+    } else {
+      const canonical = canonicalizeJson(data);
+      dataBytes = textEncoder$1.encode(canonical);
+    }
+    const namedCurve = privateKey.algorithm.namedCurve || "P-256";
+    const hashName = namedCurve === "P-384" ? "SHA-384" : namedCurve === "P-521" ? "SHA-512" : "SHA-256";
+    const signatureBuffer = await subtle.sign(
+      {
+        name: "ECDSA",
+        hash: { name: hashName }
+      },
+      privateKey,
+      dataBytes
+    );
+    return CKeyManager.toBase64(signatureBuffer);
+  }
+  /**
+   * Verifies an ECDSA P-256 signature against original data or JSON object.
+   */
+  static async verify(data, signature, publicKey) {
+    const subtle = getSubtleCrypto();
+    if (!publicKey || !publicKey.algorithm || publicKey.algorithm.name !== "ECDSA") {
+      throw new Error("[CKeyManager] verify requires an ECDSA public key.");
+    }
+    if (typeof signature !== "string" || !signature.trim()) {
+      return false;
+    }
+    try {
+      const signatureBytes = CKeyManager.fromBase64(signature);
+      let dataBytes;
+      if (data instanceof Uint8Array) {
+        dataBytes = data;
+      } else if (ArrayBuffer.isView(data)) {
+        dataBytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+      } else if (data instanceof ArrayBuffer) {
+        dataBytes = new Uint8Array(data);
+      } else if (typeof data === "string") {
+        dataBytes = textEncoder$1.encode(data);
+      } else {
+        const canonical = canonicalizeJson(data);
+        dataBytes = textEncoder$1.encode(canonical);
+      }
+      const namedCurve = publicKey.algorithm.namedCurve || "P-256";
+      const hashName = namedCurve === "P-384" ? "SHA-384" : namedCurve === "P-521" ? "SHA-512" : "SHA-256";
+      return await subtle.verify(
+        {
+          name: "ECDSA",
+          hash: { name: hashName }
+        },
+        publicKey,
+        signatureBytes,
+        dataBytes
+      );
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Signs a structured access grant, embedding signature and granter key fingerprint.
+   */
+  static async signGrant(grant, granterPrivateKey, granterPublicKey) {
+    if (!grant || typeof grant !== "object") {
+      throw new Error("[CKeyManager] signGrant requires a valid grant object.");
+    }
+    let fingerprint;
+    if (granterPublicKey) {
+      fingerprint = await CKeyManager.getKeyFingerprint(granterPublicKey);
+    } else {
+      const subtle = getSubtleCrypto();
+      try {
+        const jwk = await subtle.exportKey("jwk", granterPrivateKey);
+        const pubJwk = {
+          kty: jwk.kty,
+          crv: jwk.crv,
+          x: jwk.x,
+          y: jwk.y,
+          ext: true,
+          key_ops: ["verify"]
+        };
+        const pubKey = await subtle.importKey(
+          "jwk",
+          pubJwk,
+          { name: "ECDSA", namedCurve: jwk.crv || "P-256" },
+          true,
+          ["verify"]
+        );
+        fingerprint = await CKeyManager.getKeyFingerprint(pubKey);
+      } catch {
+        throw new Error(
+          "[CKeyManager] signGrant requires granterPublicKey when granterPrivateKey is non-extractable."
+        );
+      }
+    }
+    const signature = await CKeyManager.sign(grant, granterPrivateKey);
+    return {
+      grant: { ...grant },
+      signature,
+      fingerprint
+    };
+  }
+  /**
+   * Verifies the authenticity and integrity of a signed access grant against granter public key.
+   */
+  static async verifyGrant(signedGrant, granterPublicKey, options) {
+    if (!signedGrant || !signedGrant.grant || !signedGrant.signature || !signedGrant.fingerprint || !granterPublicKey) {
+      return false;
+    }
+    const expectedFingerprint = await CKeyManager.getKeyFingerprint(granterPublicKey);
+    if (signedGrant.fingerprint !== expectedFingerprint) {
+      return false;
+    }
+    if (options?.checkExpiry && signedGrant.grant.expiresAt !== void 0) {
+      const now = options.now ?? Date.now();
+      if (now > signedGrant.grant.expiresAt) {
+        return false;
+      }
+    }
+    return await CKeyManager.verify(signedGrant.grant, signedGrant.signature, granterPublicKey);
+  }
 }
 
 class CWebCryptoEncryptionProvider extends AEncryptionProvider {
@@ -1558,6 +2205,7 @@ class CWebCryptoEncryptionProvider extends AEncryptionProvider {
   _cachedKeyId;
   _configuredKid;
   _decryptSaltCache = /* @__PURE__ */ new Map();
+  _keyringCache = /* @__PURE__ */ new Map();
   setDefaultKey(key) {
     super.setDefaultKey(key);
     this._cachedKey = void 0;
@@ -1567,6 +2215,7 @@ class CWebCryptoEncryptionProvider extends AEncryptionProvider {
     this._cachedHash = void 0;
     this._cachedKeyId = void 0;
     this._decryptSaltCache.clear();
+    this._keyringCache.clear();
   }
   clearKeys() {
     super.clearKeys();
@@ -1577,9 +2226,10 @@ class CWebCryptoEncryptionProvider extends AEncryptionProvider {
     this._cachedHash = void 0;
     this._cachedKeyId = void 0;
     this._decryptSaltCache.clear();
+    this._keyringCache.clear();
   }
   constructor(key, options) {
-    super(key);
+    super(key, options);
     if (options) {
       if (options.kid || options.keyId) {
         this._configuredKid = options.kid || options.keyId;
@@ -1629,14 +2279,21 @@ class CWebCryptoEncryptionProvider extends AEncryptionProvider {
   }
   async _resolveCryptoKeyInternal(keyProvider, kdfOverride, saltOverride, options, iterationsOverride) {
     const rawKey = await this.resolveRawKey(keyProvider);
+    const currentKeyId = getSafeKeyIdentifier(rawKey);
     if (typeof rawKey !== "string" && rawKey.algorithm) {
-      if (!keyProvider) {
+      const res2 = { cryptoKey: rawKey, kdf: "direct" };
+      this._keyringCache.set(currentKeyId, res2);
+      if (!keyProvider || keyProvider === this.defaultKey) {
         this._cachedKey = rawKey;
         this._cachedKdf = "direct";
       }
-      return { cryptoKey: rawKey, kdf: "direct" };
+      return res2;
     }
     if (rawKey instanceof Uint8Array || rawKey instanceof ArrayBuffer) {
+      const cached = this._keyringCache.get(currentKeyId);
+      if (cached) {
+        return cached;
+      }
       if (!keyProvider && this._cachedKey && this._cachedKdf === "raw") {
         return { cryptoKey: this._cachedKey, kdf: "raw" };
       }
@@ -1653,11 +2310,13 @@ class CWebCryptoEncryptionProvider extends AEncryptionProvider {
         false,
         ["encrypt", "decrypt"]
       );
-      if (!keyProvider) {
+      const res2 = { cryptoKey: cryptoKey2, kdf: "raw" };
+      this._keyringCache.set(currentKeyId, res2);
+      if (!keyProvider || keyProvider === this.defaultKey) {
         this._cachedKey = cryptoKey2;
         this._cachedKdf = "raw";
       }
-      return { cryptoKey: cryptoKey2, kdf: "raw" };
+      return res2;
     }
     const passphrase = rawKey;
     const kdf = (kdfOverride || options?.kdf || this._defaultKdf || "pbkdf2").toLowerCase();
@@ -1667,12 +2326,21 @@ class CWebCryptoEncryptionProvider extends AEncryptionProvider {
     const matchesHash = !targetHash || this._cachedHash !== void 0 && targetHash.toLowerCase() === this._cachedHash.toLowerCase();
     const matchesKdf = this._cachedKdf !== void 0 && kdf === this._cachedKdf.toLowerCase();
     const matchesSalt = !saltOverride || this._cachedSalt !== void 0 && saltOverride === this._cachedSalt;
-    const currentKeyId = getSafeKeyIdentifier(rawKey);
     if (this._cachedKey && matchesSalt && !options?.kdfSalt && matchesKdf && matchesIter && matchesHash) {
       if (this._cachedKeyId === currentKeyId) {
         return { cryptoKey: this._cachedKey, salt: this._cachedSalt, kdf: this._cachedKdf, iter: this._cachedIter };
       }
     }
+    if (!saltOverride && !options?.kdfSalt) {
+      const cached = this._keyringCache.get(currentKeyId);
+      if (cached) {
+        const cMatchesKdf = !cached.kdf || cached.kdf.toLowerCase() === kdf;
+        const cMatchesIter = !targetIter || cached.iter === targetIter;
+        if (cMatchesKdf && cMatchesIter) {
+          return cached;
+        }
+      }
+    }
     if (kdf === "pbkdf2") {
       const salt = saltOverride || options?.kdfSalt || this._kdfOptions?.salt;
       const rawIterations = iterationsOverride || options?.kdfIterations || this._kdfOptions?.iterations || 31e4;
@@ -1684,15 +2352,19 @@ class CWebCryptoEncryptionProvider extends AEncryptionProvider {
         iterations,
         hash
       });
+      const res2 = { cryptoKey: derived.key, salt: derived.salt, kdf: "PBKDF2", iter: iterations };
       if (!saltOverride && !options?.kdfSalt) {
-        this._cachedKey = derived.key;
-        this._cachedSalt = derived.salt;
-        this._cachedKdf = "PBKDF2";
-        this._cachedIter = iterations;
-        this._cachedHash = hash;
-        this._cachedKeyId = currentKeyId;
+        this._keyringCache.set(currentKeyId, res2);
+        if (!keyProvider || keyProvider === this.defaultKey) {
+          this._cachedKey = derived.key;
+          this._cachedSalt = derived.salt;
+          this._cachedKdf = "PBKDF2";
+          this._cachedIter = iterations;
+          this._cachedHash = hash;
+          this._cachedKeyId = currentKeyId;
+        }
       }
-      return { cryptoKey: derived.key, salt: derived.salt, kdf: "PBKDF2", iter: iterations };
+      return res2;
     }
     if (kdf === "hkdf") {
       if (typeof rawKey === "string") {
@@ -1709,14 +2381,18 @@ class CWebCryptoEncryptionProvider extends AEncryptionProvider {
         hash,
         info
       });
+      const res2 = { cryptoKey: derived.key, salt: derived.salt, kdf: "HKDF" };
       if (!saltOverride && !options?.kdfSalt) {
-        this._cachedKey = derived.key;
-        this._cachedSalt = derived.salt;
-        this._cachedKdf = "HKDF";
-        this._cachedHash = hash;
-        this._cachedKeyId = currentKeyId;
+        this._keyringCache.set(currentKeyId, res2);
+        if (!keyProvider || keyProvider === this.defaultKey) {
+          this._cachedKey = derived.key;
+          this._cachedSalt = derived.salt;
+          this._cachedKdf = "HKDF";
+          this._cachedHash = hash;
+          this._cachedKeyId = currentKeyId;
+        }
       }
-      return { cryptoKey: derived.key, salt: derived.salt, kdf: "HKDF" };
+      return res2;
     }
     if (kdf === "none") {
       if (saltOverride) {
@@ -1748,11 +2424,13 @@ class CWebCryptoEncryptionProvider extends AEncryptionProvider {
     } finally {
       new Uint8Array(keyHash).fill(0);
     }
-    if (!keyProvider) {
+    const res = { cryptoKey, kdf: "none" };
+    this._keyringCache.set(currentKeyId, res);
+    if (!keyProvider || keyProvider === this.defaultKey) {
       this._cachedKey = cryptoKey;
       this._cachedKdf = "none";
     }
-    return { cryptoKey, kdf: "none" };
+    return res;
   }
   static isEncrypted(payload) {
     if (!payload || typeof payload !== "object") return false;
@@ -1762,6 +2440,29 @@ class CWebCryptoEncryptionProvider extends AEncryptionProvider {
     return CWebCryptoEncryptionProvider.isEncrypted(payload);
   }
   async warmupKey(options) {
+    const effectiveKeys = options?.keys || this.keys;
+    if (effectiveKeys && Object.keys(effectiveKeys).length > 0) {
+      const promises = Object.entries(effectiveKeys).map(async ([kid, keyProv]) => {
+        const res2 = await this.resolveCryptoKey(keyProv, void 0, void 0, { ...options, key: keyProv, kid });
+        const rawKey = await this.resolveRawKey(keyProv);
+        const keyId = getSafeKeyIdentifier(rawKey);
+        this._keyringCache.set(keyId, res2);
+        this._keyringCache.set(`kid:${kid}`, res2);
+        return { kid, res: res2 };
+      });
+      const results = await Promise.all(promises);
+      const effectiveActiveKid = options?.activeKid || this.activeKid;
+      const primary = effectiveActiveKid && results.find((r) => r.kid === effectiveActiveKid)?.res || results[0]?.res;
+      if (primary) {
+        this._cachedKey = primary.cryptoKey;
+        this._cachedSalt = primary.salt;
+        this._cachedKdf = primary.kdf;
+        this._cachedIter = primary.iter;
+        this._cachedHash = options?.kdfHash || this._kdfOptions?.hash || "SHA-256";
+        this._cachedKeyId = getKeyIdentifier(options?.key, this.defaultKey);
+      }
+      return;
+    }
     const res = await this.resolveCryptoKey(options?.key, void 0, void 0, options);
     this._cachedKey = res.cryptoKey;
     this._cachedSalt = res.salt;
@@ -1804,7 +2505,7 @@ class CWebCryptoEncryptionProvider extends AEncryptionProvider {
       cryptoKey,
       textEncoder$1.encode(jsonString)
     );
-    const kid = options?.kid || options?.keyId || this._configuredKid;
+    const kid = options?.kid || options?.keyId || this.activeKid || this._configuredKid;
     return {
       __encrypted: true,
       ciphertext: CKeyManager.toBase64(ciphertextBuffer),
@@ -3127,12 +3828,26 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
   _cachedHash;
   _cachedKeyId;
   _configuredKid;
+  _keyringCache = /* @__PURE__ */ new Map();
+  isKeyRetained(key) {
+    if (key === this._cachedKey) return true;
+    for (const entry of this._keyringCache.values()) {
+      if (entry.key === key) return true;
+    }
+    return false;
+  }
   setDefaultKey(key) {
     super.setDefaultKey(key);
     if (this._cachedKey) {
       this._cachedKey.fill(0);
       this._cachedKey = void 0;
     }
+    for (const entry of this._keyringCache.values()) {
+      if (entry.key !== this._cachedKey) {
+        entry.key.fill(0);
+      }
+    }
+    this._keyringCache.clear();
     this._cachedSalt = void 0;
     this._cachedKdf = void 0;
     this._cachedIter = void 0;
@@ -3145,6 +3860,12 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
       this._cachedKey.fill(0);
       this._cachedKey = void 0;
     }
+    for (const entry of this._keyringCache.values()) {
+      if (entry.key !== this._cachedKey) {
+        entry.key.fill(0);
+      }
+    }
+    this._keyringCache.clear();
     this._cachedSalt = void 0;
     this._cachedKdf = void 0;
     this._cachedIter = void 0;
@@ -3152,6 +3873,29 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
     this._cachedKeyId = void 0;
   }
   async warmupKey(options) {
+    const effectiveKeys = options?.keys || this.keys;
+    if (effectiveKeys && Object.keys(effectiveKeys).length > 0) {
+      const promises = Object.entries(effectiveKeys).map(async ([kid, keyProv]) => {
+        const res2 = await this.deriveKeyAsync(keyProv, void 0, void 0, { ...options, key: keyProv, kid });
+        const raw = await this.resolveRawKeyAsync(keyProv);
+        const keyId = getSafeKeyIdentifier(raw);
+        this._keyringCache.set(keyId, res2);
+        this._keyringCache.set(`kid:${kid}`, res2);
+        return { kid, res: res2 };
+      });
+      const results = await Promise.all(promises);
+      const effectiveActiveKid = options?.activeKid || this.activeKid;
+      const primary = effectiveActiveKid && results.find((r) => r.kid === effectiveActiveKid)?.res || results[0]?.res;
+      if (primary) {
+        this._cachedKey = primary.key;
+        this._cachedSalt = primary.salt;
+        this._cachedKdf = primary.kdf;
+        this._cachedIter = primary.iter;
+        this._cachedHash = options?.kdfHash || this._kdfOptions?.hash || "SHA-256";
+        this._cachedKeyId = getSafeKeyIdentifier(await this.resolveRawKeyAsync(options?.key));
+      }
+      return;
+    }
     const res = await this.deriveKeyAsync(options?.key, void 0, void 0, options);
     if (!options?.key) {
       this._cachedKey = res.key;
@@ -3166,6 +3910,30 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
    * Synchronously pre-derives and caches the encryption key for subsequent synchronous operations.
    */
   warmupKeySync(options) {
+    const effectiveKeys = options?.keys || this.keys;
+    if (effectiveKeys && Object.keys(effectiveKeys).length > 0) {
+      const entries = Object.entries(effectiveKeys);
+      const results = [];
+      for (const [kid, keyProv] of entries) {
+        const res2 = this.deriveKeySync(keyProv, void 0, void 0, { ...options, key: keyProv, kid });
+        const raw = this.resolveRawKeySync(keyProv);
+        const keyId = getSafeKeyIdentifier(raw);
+        this._keyringCache.set(keyId, res2);
+        this._keyringCache.set(`kid:${kid}`, res2);
+        results.push({ kid, res: res2 });
+      }
+      const effectiveActiveKid = options?.activeKid || this.activeKid;
+      const primary = effectiveActiveKid && results.find((r) => r.kid === effectiveActiveKid)?.res || results[0]?.res;
+      if (primary) {
+        this._cachedKey = primary.key;
+        this._cachedSalt = primary.salt;
+        this._cachedKdf = primary.kdf;
+        this._cachedIter = primary.iter;
+        this._cachedHash = options?.kdfHash || this._kdfOptions?.hash || "SHA-256";
+        this._cachedKeyId = getSafeKeyIdentifier(this.resolveRawKeySync(options?.key));
+      }
+      return;
+    }
     const res = this.deriveKeySync(options?.key, void 0, void 0, options);
     if (!options?.key) {
       this._cachedKey = res.key;
@@ -3184,7 +3952,7 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
     return Buffer.from(infoRaw);
   }
   constructor(key, options) {
-    super(key);
+    super(key, options);
     if (options) {
       if (options.kid || options.keyId) {
         this._configuredKid = options.kid || options.keyId;
@@ -3202,7 +3970,7 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
     }
   }
   resolveRawKeySync(keyProvider) {
-    const target = keyProvider || this.defaultKey;
+    const target = keyProvider || (this.activeKid && this.keys ? this.keys[this.activeKid] : void 0) || this.defaultKey;
     if (!target) {
       throw new Error("[CNodeCryptoEncryptionProvider] No encryption key or keyProvider was supplied.");
     }
@@ -3232,7 +4000,7 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
     return rawKey;
   }
   async resolveRawKeyAsync(keyProvider) {
-    const target = keyProvider || this.defaultKey;
+    const target = keyProvider || (this.activeKid && this.keys ? this.keys[this.activeKid] : void 0) || this.defaultKey;
     if (!target) {
       throw new Error("[CNodeCryptoEncryptionProvider] No encryption key or keyProvider was supplied.");
     }
@@ -3263,15 +4031,16 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
     const currentKeyId = getSafeKeyIdentifier(raw);
     if (Buffer.isBuffer(raw)) {
       if (raw.length === 32) {
-        if (!keyProvider) {
-          if (!this._cachedKey || this._cachedKeyId !== currentKeyId) {
-            this._cachedKey = Buffer.from(raw);
-            this._cachedKdf = "raw";
-            this._cachedKeyId = currentKeyId;
-          }
-          return { key: this._cachedKey, kdf: "raw" };
+        const cached = this._keyringCache.get(currentKeyId);
+        if (cached) return cached;
+        const res2 = { key: Buffer.from(raw), kdf: "raw" };
+        this._keyringCache.set(currentKeyId, res2);
+        if (!keyProvider || keyProvider === this.defaultKey) {
+          this._cachedKey = res2.key;
+          this._cachedKdf = "raw";
+          this._cachedKeyId = currentKeyId;
         }
-        return { key: Buffer.from(raw), kdf: "raw" };
+        return res2;
       }
       throw new Error(
         `[CNodeCryptoEncryptionProvider] AES-GCM-256 requires a 32-byte key. Received a Buffer of ${raw.length} bytes. Provide exactly 32 bytes or a string passphrase.`
@@ -3290,6 +4059,16 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
         return { key: this._cachedKey, salt: this._cachedSalt, kdf: this._cachedKdf, iter: this._cachedIter };
       }
     }
+    if (!saltOverride && !options?.kdfSalt) {
+      const cached = this._keyringCache.get(currentKeyId);
+      if (cached) {
+        const cMatchesKdf = !cached.kdf || cached.kdf.toLowerCase() === kdf;
+        const cMatchesIter = !targetIter || cached.iter === targetIter;
+        if (cMatchesKdf && cMatchesIter) {
+          return cached;
+        }
+      }
+    }
     if (kdf === "pbkdf2") {
       const s = saltOverride || options?.kdfSalt || this._kdfOptions?.salt;
       const saltBytes = CKeyManager.resolveSalt(s);
@@ -3298,20 +4077,24 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
       const iterations = Math.min(Math.max(rawIter, 1e3), 6e5);
       const hash = (options?.kdfHash || this._kdfOptions?.hash || "SHA-256").toLowerCase().replace("-", "");
       const key2 = crypto__namespace.pbkdf2Sync(passphrase, saltBuf, iterations, 32, hash);
-      if (!keyProvider && !saltOverride && !options?.kdfSalt) {
-        this._cachedKey = key2;
-        this._cachedSalt = saltBuf.toString("base64");
-        this._cachedKdf = "PBKDF2";
-        this._cachedIter = iterations;
-        this._cachedHash = options?.kdfHash || this._kdfOptions?.hash || "SHA-256";
-        this._cachedKeyId = currentKeyId;
-      }
-      return {
+      const res2 = {
         key: key2,
         salt: saltBuf.toString("base64"),
         kdf: "PBKDF2",
         iter: iterations
       };
+      if (!saltOverride && !options?.kdfSalt) {
+        this._keyringCache.set(currentKeyId, res2);
+        if (!keyProvider || keyProvider === this.defaultKey) {
+          this._cachedKey = key2;
+          this._cachedSalt = saltBuf.toString("base64");
+          this._cachedKdf = "PBKDF2";
+          this._cachedIter = iterations;
+          this._cachedHash = options?.kdfHash || this._kdfOptions?.hash || "SHA-256";
+          this._cachedKeyId = currentKeyId;
+        }
+      }
+      return res2;
     }
     if (kdf === "hkdf") {
       if (typeof raw === "string") {
@@ -3325,49 +4108,56 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
       const hash = (options?.kdfHash || this._kdfOptions?.hash || "SHA-256").toLowerCase().replace("-", "");
       const info = this.resolveInfoBuffer(options?.info || this._kdfOptions?.info);
       const key2 = Buffer.from(crypto__namespace.hkdfSync(hash, passphrase, saltBuf, info, 32));
-      if (!keyProvider && !saltOverride && !options?.kdfSalt) {
-        this._cachedKey = key2;
-        this._cachedSalt = saltBuf.toString("base64");
-        this._cachedKdf = "HKDF";
-        this._cachedHash = options?.kdfHash || this._kdfOptions?.hash || "SHA-256";
-        this._cachedKeyId = currentKeyId;
-      }
-      return {
+      const res2 = {
         key: key2,
         salt: saltBuf.toString("base64"),
         kdf: "HKDF"
       };
+      if (!saltOverride && !options?.kdfSalt) {
+        this._keyringCache.set(currentKeyId, res2);
+        if (!keyProvider || keyProvider === this.defaultKey) {
+          this._cachedKey = key2;
+          this._cachedSalt = saltBuf.toString("base64");
+          this._cachedKdf = "HKDF";
+          this._cachedHash = options?.kdfHash || this._kdfOptions?.hash || "SHA-256";
+          this._cachedKeyId = currentKeyId;
+        }
+      }
+      return res2;
     }
     if (kdf === "none") {
       console.warn(
         "[CNodeCryptoEncryptionProvider] WARNING: Decrypting a legacy envelope with no KDF (raw SHA-256 key derivation). This is cryptographically weak. Migrate to pbkdf2 or hkdf."
       );
     }
-    if (!keyProvider && this._cachedKey && this._cachedKdf === "none" && this._cachedKeyId === currentKeyId) {
+    if ((!keyProvider || keyProvider === this.defaultKey) && this._cachedKey && this._cachedKdf === "none" && this._cachedKeyId === currentKeyId) {
       return { key: this._cachedKey, kdf: "none" };
     }
     const key = crypto__namespace.createHash("sha256").update(passphrase, "utf8").digest();
-    if (!keyProvider) {
+    const res = { key, kdf: "none" };
+    this._keyringCache.set(currentKeyId, res);
+    if (!keyProvider || keyProvider === this.defaultKey) {
       this._cachedKey = key;
       this._cachedKdf = "none";
       this._cachedKeyId = currentKeyId;
     }
-    return { key, kdf: "none" };
+    return res;
   }
   async deriveKeyAsync(keyProvider, kdfOverride, saltOverride, options, iterationsOverride) {
     const raw = await this.resolveRawKeyAsync(keyProvider);
     const currentKeyId = getSafeKeyIdentifier(raw);
     if (Buffer.isBuffer(raw)) {
       if (raw.length === 32) {
-        if (!keyProvider) {
-          if (!this._cachedKey || this._cachedKeyId !== currentKeyId) {
-            this._cachedKey = Buffer.from(raw);
-            this._cachedKdf = "raw";
-            this._cachedKeyId = currentKeyId;
-          }
-          return { key: this._cachedKey, kdf: "raw" };
+        const cached = this._keyringCache.get(currentKeyId);
+        if (cached) return cached;
+        const res2 = { key: Buffer.from(raw), kdf: "raw" };
+        this._keyringCache.set(currentKeyId, res2);
+        if (!keyProvider || keyProvider === this.defaultKey) {
+          this._cachedKey = res2.key;
+          this._cachedKdf = "raw";
+          this._cachedKeyId = currentKeyId;
         }
-        return { key: Buffer.from(raw), kdf: "raw" };
+        return res2;
       }
       throw new Error(
         `[CNodeCryptoEncryptionProvider] AES-GCM-256 requires a 32-byte key. Received a Buffer of ${raw.length} bytes. Provide exactly 32 bytes or a string passphrase.`
@@ -3386,6 +4176,16 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
         return { key: this._cachedKey, salt: this._cachedSalt, kdf: this._cachedKdf, iter: this._cachedIter };
       }
     }
+    if (!saltOverride && !options?.kdfSalt) {
+      const cached = this._keyringCache.get(currentKeyId);
+      if (cached) {
+        const cMatchesKdf = !cached.kdf || cached.kdf.toLowerCase() === kdf;
+        const cMatchesIter = !targetIter || cached.iter === targetIter;
+        if (cMatchesKdf && cMatchesIter) {
+          return cached;
+        }
+      }
+    }
     if (kdf === "pbkdf2") {
       const s = saltOverride || options?.kdfSalt || this._kdfOptions?.salt;
       const saltBytes = CKeyManager.resolveSalt(s);
@@ -3399,20 +4199,24 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
           else resolve(derived);
         });
       });
-      if (!keyProvider && !saltOverride && !options?.kdfSalt) {
-        this._cachedKey = key2;
-        this._cachedSalt = saltBuf.toString("base64");
-        this._cachedKdf = "PBKDF2";
-        this._cachedIter = iterations;
-        this._cachedHash = options?.kdfHash || this._kdfOptions?.hash || "SHA-256";
-        this._cachedKeyId = currentKeyId;
-      }
-      return {
+      const res2 = {
         key: key2,
         salt: saltBuf.toString("base64"),
         kdf: "PBKDF2",
         iter: iterations
       };
+      if (!saltOverride && !options?.kdfSalt) {
+        this._keyringCache.set(currentKeyId, res2);
+        if (!keyProvider || keyProvider === this.defaultKey) {
+          this._cachedKey = key2;
+          this._cachedSalt = saltBuf.toString("base64");
+          this._cachedKdf = "PBKDF2";
+          this._cachedIter = iterations;
+          this._cachedHash = options?.kdfHash || this._kdfOptions?.hash || "SHA-256";
+          this._cachedKeyId = currentKeyId;
+        }
+      }
+      return res2;
     }
     if (kdf === "hkdf") {
       if (typeof raw === "string") {
@@ -3431,34 +4235,40 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
           else resolve(Buffer.from(derived));
         });
       });
-      if (!keyProvider && !saltOverride && !options?.kdfSalt) {
-        this._cachedKey = key2;
-        this._cachedSalt = saltBuf.toString("base64");
-        this._cachedKdf = "HKDF";
-        this._cachedHash = options?.kdfHash || this._kdfOptions?.hash || "SHA-256";
-        this._cachedKeyId = currentKeyId;
-      }
-      return {
+      const res2 = {
         key: key2,
         salt: saltBuf.toString("base64"),
         kdf: "HKDF"
       };
+      if (!saltOverride && !options?.kdfSalt) {
+        this._keyringCache.set(currentKeyId, res2);
+        if (!keyProvider || keyProvider === this.defaultKey) {
+          this._cachedKey = key2;
+          this._cachedSalt = saltBuf.toString("base64");
+          this._cachedKdf = "HKDF";
+          this._cachedHash = options?.kdfHash || this._kdfOptions?.hash || "SHA-256";
+          this._cachedKeyId = currentKeyId;
+        }
+      }
+      return res2;
     }
     if (kdf === "none") {
       console.warn(
         "[CNodeCryptoEncryptionProvider] WARNING: Decrypting a legacy envelope with no KDF (raw SHA-256 key derivation). This is cryptographically weak. Migrate to pbkdf2 or hkdf."
       );
     }
-    if (!keyProvider && this._cachedKey && this._cachedKdf === "none" && this._cachedKeyId === currentKeyId) {
+    if ((!keyProvider || keyProvider === this.defaultKey) && this._cachedKey && this._cachedKdf === "none" && this._cachedKeyId === currentKeyId) {
       return { key: this._cachedKey, kdf: "none" };
     }
     const key = crypto__namespace.createHash("sha256").update(passphrase, "utf8").digest();
-    if (!keyProvider) {
+    const res = { key, kdf: "none" };
+    this._keyringCache.set(currentKeyId, res);
+    if (!keyProvider || keyProvider === this.defaultKey) {
       this._cachedKey = key;
       this._cachedKdf = "none";
       this._cachedKeyId = currentKeyId;
     }
-    return { key, kdf: "none" };
+    return res;
   }
   static isEncrypted(payload) {
     if (!payload || typeof payload !== "object") return false;
@@ -3498,7 +4308,7 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
       ]);
       const authTag = cipher.getAuthTag();
       const combinedCiphertext = Buffer.concat([encryptedBuffer, authTag]);
-      const kid = options?.kid || options?.keyId || this._configuredKid;
+      const kid = options?.kid || options?.keyId || this.activeKid || this._configuredKid;
       return {
         __encrypted: true,
         ciphertext: combinedCiphertext.toString("base64"),
@@ -3511,7 +4321,7 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
         ...hasAad ? { aad: true } : {}
       };
     } finally {
-      if (key !== this._cachedKey) {
+      if (!this.isKeyRetained(key)) {
         key.fill(0);
       }
     }
@@ -3600,7 +4410,7 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
       if (err instanceof SyntaxError) throw err;
       throw new Error(`[CNodeCryptoEncryptionProvider] Decryption failed: ${err?.message || "Authentication tag mismatch or corrupted ciphertext"}`);
     } finally {
-      if (key !== this._cachedKey) {
+      if (!this.isKeyRetained(key)) {
         key.fill(0);
       }
     }
@@ -3609,6 +4419,7 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
   encryptSync(data, options) {
     if (data === void 0 || data === null) return data;
     if (this.isEncrypted(data)) return data;
+    options = this._resolveOutboundKeyringOptions(options);
     if (Array.isArray(data)) {
       if (options?.fields && options.fields.length > 0 || options?.valueEncryption === true) {
         return data.map((item) => this.encryptSync(item, options));
@@ -3644,7 +4455,12 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
   decryptSync(payload, options) {
     if (payload === void 0 || payload === null) return payload;
     if (this.isEncrypted(payload)) {
-      return this.decryptValueSync(payload, options);
+      const metaErr = this._validateEnvelopeMetadata(payload, options);
+      if (metaErr) {
+        return this._handleDecryptError(metaErr, payload, "", payload, void 0, options);
+      }
+      const envelopeKey = this._resolveDecryptionKeyForEnvelope(payload, options);
+      return this.decryptValueSync(payload, { ...options, key: envelopeKey });
     }
     if (Array.isArray(payload)) {
       return payload.map((item) => this.decryptSync(item, options));
@@ -3658,28 +4474,35 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
         for (const key of targetKeys) {
           if (this.isEncrypted(result[key])) {
             const fieldPayload = result[key];
+            const metaErr = this._validateEnvelopeMetadata(fieldPayload, options);
+            if (metaErr) {
+              return this._handleDecryptError(metaErr, result, key, fieldPayload, void 0, options);
+            }
+            const envelopeKey = this._resolveDecryptionKeyForEnvelope(fieldPayload, options);
             const salt = fieldPayload.salt || "__no_salt__";
-            let derivedKey = keyCache.get(salt);
+            const memoKey = `${salt}:${fieldPayload.kid || ""}`;
+            let derivedKey = keyCache.get(memoKey);
             if (!derivedKey) {
               const kdfFromEnvelope = fieldPayload.kdf ? fieldPayload.kdf.toLowerCase() : "none";
               const derived = this.deriveKeySync(
-                options?.key,
+                envelopeKey,
                 kdfFromEnvelope,
                 fieldPayload.salt,
                 options,
                 fieldPayload.iter
               );
               derivedKey = derived.key;
-              keyCache.set(salt, derivedKey);
+              keyCache.set(memoKey, derivedKey);
             }
-            const boundOptions = this._bindFieldAad(payload, key, options);
+            const boundOptions = this._bindFieldAad(payload, key, { ...options, key: envelopeKey });
             const hasBoundAad = boundOptions.aad !== options?.aad;
             try {
               safeSetProperty(result, key, this.decryptCiphertextWithKey(fieldPayload, derivedKey, boundOptions));
             } catch (err) {
-              if (hasBoundAad && isAuthOrDecryptionError(err)) {
+              const canFallback = hasBoundAad && (!options?.aadFields || options.aadFields.length === 0) && typeof options?.aad !== "function";
+              if (canFallback && isAuthOrDecryptionError(err)) {
                 try {
-                  safeSetProperty(result, key, this.decryptCiphertextWithKey(fieldPayload, derivedKey, options));
+                  safeSetProperty(result, key, this.decryptCiphertextWithKey(fieldPayload, derivedKey, { ...options, key: envelopeKey }));
                 } catch (fallbackErr) {
                   throw fallbackErr;
                 }
@@ -3693,7 +4516,7 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
         return mutated ? result : payload;
       } finally {
         for (const k of keyCache.values()) {
-          if (k !== this._cachedKey) {
+          if (!this.isKeyRetained(k)) {
             k.fill(0);
           }
         }
@@ -3741,7 +4564,7 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
       ]);
       const authTag = cipher.getAuthTag();
       const combined = Buffer.concat([ciphertext, authTag]);
-      const kid = options?.kid || options?.keyId || this._configuredKid;
+      const kid = options?.kid || options?.keyId || this.activeKid || this._configuredKid;
       return {
         __encrypted: true,
         ciphertext: combined.toString("base64"),
@@ -3754,7 +4577,7 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
         ...hasAad ? { aad: true } : {}
       };
     } finally {
-      if (key !== this._cachedKey) {
+      if (!this.isKeyRetained(key)) {
         key.fill(0);
       }
     }
@@ -3778,7 +4601,7 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
       if (err instanceof SyntaxError) throw err;
       throw new Error(`[CNodeCryptoEncryptionProvider] Decryption failed: ${err?.message || "Authentication tag mismatch or corrupted ciphertext"}`);
     } finally {
-      if (key !== this._cachedKey) {
+      if (!this.isKeyRetained(key)) {
         key.fill(0);
       }
     }
@@ -3786,7 +4609,12 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
   async decrypt(payload, options) {
     if (payload === void 0 || payload === null) return payload;
     if (this.isEncrypted(payload)) {
-      return this.decryptValue(payload, options);
+      const metaErr = this._validateEnvelopeMetadata(payload, options);
+      if (metaErr) {
+        return this._handleDecryptError(metaErr, payload, "", payload, void 0, options);
+      }
+      const envelopeKey = this._resolveDecryptionKeyForEnvelope(payload, options);
+      return this.decryptValue(payload, { ...options, key: envelopeKey });
     }
     if (Array.isArray(payload)) {
       return Promise.all(payload.map((item) => this.decrypt(item, options)));
@@ -3800,28 +4628,35 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
         for (const key of targetKeys) {
           if (this.isEncrypted(result[key])) {
             const fieldPayload = result[key];
+            const metaErr = this._validateEnvelopeMetadata(fieldPayload, options);
+            if (metaErr) {
+              return this._handleDecryptError(metaErr, result, key, fieldPayload, void 0, options);
+            }
+            const envelopeKey = this._resolveDecryptionKeyForEnvelope(fieldPayload, options);
             const salt = fieldPayload.salt || "__no_salt__";
-            let derivedKey = keyCache.get(salt);
+            const memoKey = `${salt}:${fieldPayload.kid || ""}`;
+            let derivedKey = keyCache.get(memoKey);
             if (!derivedKey) {
               const kdfFromEnvelope = fieldPayload.kdf ? fieldPayload.kdf.toLowerCase() : "none";
               const derived = await this.deriveKeyAsync(
-                options?.key,
+                envelopeKey,
                 kdfFromEnvelope,
                 fieldPayload.salt ? CKeyManager.fromBase64(fieldPayload.salt) : void 0,
                 options,
                 fieldPayload.iter
               );
               derivedKey = derived.key;
-              keyCache.set(salt, derivedKey);
+              keyCache.set(memoKey, derivedKey);
             }
-            const boundOptions = this._bindFieldAad(payload, key, options);
+            const boundOptions = this._bindFieldAad(payload, key, { ...options, key: envelopeKey });
             const hasBoundAad = boundOptions.aad !== options?.aad;
             try {
               safeSetProperty(result, key, this.decryptCiphertextWithKey(fieldPayload, derivedKey, boundOptions));
             } catch (err) {
-              if (hasBoundAad && isAuthOrDecryptionError(err)) {
+              const canFallback = hasBoundAad && (!options?.aadFields || options.aadFields.length === 0) && typeof options?.aad !== "function";
+              if (canFallback && isAuthOrDecryptionError(err)) {
                 try {
-                  safeSetProperty(result, key, this.decryptCiphertextWithKey(fieldPayload, derivedKey, options));
+                  safeSetProperty(result, key, this.decryptCiphertextWithKey(fieldPayload, derivedKey, { ...options, key: envelopeKey }));
                 } catch (fallbackErr) {
                   throw fallbackErr;
                 }
@@ -3835,7 +4670,7 @@ class CNodeCryptoEncryptionProvider extends AEncryptionProvider {
         return mutated ? result : payload;
       } finally {
         for (const k of keyCache.values()) {
-          if (k !== this._cachedKey) {
+          if (!this.isKeyRetained(k)) {
             k.fill(0);
           }
         }
@@ -3866,7 +4701,11 @@ function createEncryptionProvider(options = {}) {
       kdfIterations: options.kdfIterations,
       kdfHash: options.kdfHash,
       kdfSalt: options.kdfSalt,
-      info: options.info
+      info: options.info,
+      kid: options.kid || options.keyId,
+      keys: options.keys,
+      activeKid: options.activeKid,
+      allowedKids: options.allowedKids
     });
   }
   if (alg === "AES-CBC") {
@@ -3903,7 +4742,11 @@ function createEncryptionProvider(options = {}) {
       kdfIterations: options.kdfIterations,
       kdfHash: options.kdfHash,
       kdfSalt: options.kdfSalt,
-      info: options.info
+      info: options.info,
+      kid: options.kid || options.keyId,
+      keys: options.keys,
+      activeKid: options.activeKid,
+      allowedKids: options.allowedKids
     });
   }
   throw new Error(
@@ -3966,7 +4809,19 @@ function isDataEncrypted(provider, data) {
 function buildEncryptionContext(encryption, url, _defaultIdKey) {
   return {
     url,
+    aad: encryption?.aad,
+    aadFields: encryption?.aadFields,
+    baseAad: encryption?.baseAad,
+    bindRequestContextAad: encryption?.bindRequestContextAad,
+    strict: encryption?.strict,
+    allowedAlgorithms: encryption?.allowedAlgorithms,
+    allowedKids: encryption?.allowedKids,
+    onDecryptError: encryption?.onDecryptError,
     key: encryption?.key,
+    kid: encryption?.kid,
+    keyId: encryption?.keyId,
+    keys: encryption?.keys,
+    activeKid: encryption?.activeKid,
     valueEncryption: encryption?.valueEncryption,
     fields: encryption?.fields,
     publicKey: encryption?.publicKey,
@@ -3997,7 +4852,7 @@ async function decryptPageRows(rows, encryption, apiUrl, idKey) {
     }
     return isDataEncrypted(cipherProvider, row);
   });
-  if (!hasEncryptedRows) {
+  if (!hasEncryptedRows && !encryption?.strict) {
     return { rows, decrypted: false };
   }
   const ctx = buildEncryptionContext(encryption, apiUrl);
@@ -6704,8 +7559,18 @@ class RequestProvider {
       method,
       isServer,
       aad: encOptions.aad,
+      aadFields: encOptions.aadFields,
+      baseAad: encOptions.baseAad,
       bindRequestContextAad: encOptions.bindRequestContextAad,
+      strict: encOptions.strict,
+      allowedAlgorithms: encOptions.allowedAlgorithms,
+      allowedKids: encOptions.allowedKids,
+      onDecryptError: encOptions.onDecryptError,
       key: encOptions.key,
+      kid: encOptions.kid,
+      keyId: encOptions.keyId,
+      keys: encOptions.keys,
+      activeKid: encOptions.activeKid,
       valueEncryption: encOptions.valueEncryption,
       fields: encOptions.fields,
       publicKey: encOptions.publicKey,
@@ -10244,6 +11109,7 @@ exports.CTreeServerDataProvider = CTreeServerDataProvider;
 exports.CWebCryptoAESCBCProvider = CWebCryptoAESCBCProvider;
 exports.CWebCryptoEncryptionProvider = CWebCryptoEncryptionProvider;
 exports.CacheProviderFactory = CacheProviderFactory;
+exports.DECRYPT_ERROR_SENTINEL = DECRYPT_ERROR_SENTINEL;
 exports.DefaultHydrationAdapter = DefaultHydrationAdapter;
 exports.ECacheStrategy = ECacheStrategy;
 exports.EDataFilterOperator = EDataFilterOperator;
@@ -10256,6 +11122,7 @@ exports.RequestQueue = RequestQueue;
 exports.SENSITIVE_HEADER_KEYS = SENSITIVE_HEADER_KEYS;
 exports.applyOperator = applyOperator;
 exports.buildEncryptionContext = buildEncryptionContext;
+exports.canonicalizeJson = canonicalizeJson;
 exports.clearCachedCipherProvider = clearCachedCipherProvider;
 exports.clearSSRData = clearSSRData;
 exports.compareAnd = compareAnd;