layercache 1.2.9 → 1.3.1

package/dist/index.js

@@ -457,15 +457,14 @@ function createInstanceId() {
   if (globalThis.crypto?.randomUUID) {
     return globalThis.crypto.randomUUID();
   }
-  const bytes = new Uint8Array(16);
   if (globalThis.crypto?.getRandomValues) {
+    const bytes = new Uint8Array(16);
     globalThis.crypto.getRandomValues(bytes);
-  } else {
-    for (let i = 0; i < bytes.length; i += 1) {
-      bytes[i] = Math.floor(Math.random() * 256);
-    }
+    return `layercache-${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
   }
-  return `layercache-${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+  throw new Error(
+    "layercache requires a cryptographic random source. Neither crypto.randomUUID nor crypto.getRandomValues is available in this runtime."
+  );
 }
 
 // src/internal/CacheStackGeneration.ts
@@ -1286,7 +1285,8 @@ var CircuitBreakerManager = class {
     }
     const remainingMs = state.openUntil - now;
     const remainingSecs = Math.ceil(remainingMs / 1e3);
-    throw new Error(`Circuit breaker is open for key "${key}" (resets in ${remainingSecs}s).`);
+    const displayKey = key.length > 64 ? `${key.slice(0, 64)}...` : key;
+    throw new Error(`Circuit breaker is open for key "${displayKey}" (resets in ${remainingSecs}s).`);
   }
   recordFailure(key, options) {
     if (!options) {
@@ -1802,7 +1802,14 @@ var JsonSerializer = class {
   }
   deserialize(payload) {
     const normalized = Buffer.isBuffer(payload) ? payload.toString("utf8") : payload;
-    return sanitizeStructuredData(JSON.parse(normalized), {
+    let parsed;
+    try {
+      parsed = JSON.parse(normalized);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`JsonSerializer: failed to parse JSON payload: ${message}`);
+    }
+    return sanitizeStructuredData(parsed, {
       label: "JSON payload",
       maxDepth: 200,
       maxNodes: 1e4
@@ -1811,29 +1818,69 @@ var JsonSerializer = class {
 };
 
 // src/stampede/StampedeGuard.ts
-import { Mutex as Mutex2 } from "async-mutex";
 var StampedeGuard = class {
-  mutexes = /* @__PURE__ */ new Map();
+  inFlight = /* @__PURE__ */ new Map();
+  maxInFlight;
+  entryTimeoutMs;
+  constructor(options = {}) {
+    this.maxInFlight = options.maxInFlight ?? 1e4;
+    this.entryTimeoutMs = options.entryTimeoutMs;
+  }
   async execute(key, task) {
-    const entry = this.getMutexEntry(key);
+    const existing = this.inFlight.get(key);
+    if (existing) {
+      existing.references += 1;
+      try {
+        return await existing.promise;
+      } finally {
+        this.releaseEntry(key, existing);
+      }
+    }
+    if (this.inFlight.size >= this.maxInFlight) {
+      throw new Error(
+        `StampedeGuard: in-flight limit of ${this.maxInFlight} exceeded. Rejecting new key to prevent memory exhaustion.`
+      );
+    }
+    const taskPromise = Promise.resolve().then(task);
+    const guardedPromise = this.entryTimeoutMs ? this.withTimeout(key, taskPromise, this.entryTimeoutMs) : taskPromise;
+    const entry = {
+      promise: guardedPromise,
+      references: 1
+    };
+    this.inFlight.set(key, entry);
     try {
-      return await entry.mutex.runExclusive(task);
+      return await entry.promise;
     } finally {
-      entry.references -= 1;
-      const current = this.mutexes.get(key);
-      if (current === entry && entry.references === 0 && !entry.mutex.isLocked()) {
-        this.mutexes.delete(key);
-      }
+      this.releaseEntry(key, entry);
     }
   }
-  getMutexEntry(key) {
-    let entry = this.mutexes.get(key);
-    if (!entry) {
-      entry = { mutex: new Mutex2(), references: 0 };
-      this.mutexes.set(key, entry);
+  withTimeout(key, promise, timeoutMs) {
+    return new Promise((resolve2, reject) => {
+      const timer = setTimeout(() => {
+        reject(
+          new Error(
+            `StampedeGuard: task for key "${key.slice(0, 64)}${key.length > 64 ? "..." : ""}" timed out after ${timeoutMs}ms.`
+          )
+        );
+      }, timeoutMs);
+      promise.then(
+        (value) => {
+          clearTimeout(timer);
+          resolve2(value);
+        },
+        (error) => {
+          clearTimeout(timer);
+          reject(error);
+        }
+      );
+    });
+  }
+  releaseEntry(key, entry) {
+    entry.references -= 1;
+    const current = this.inFlight.get(key);
+    if (current === entry && entry.references === 0) {
+      this.inFlight.delete(key);
     }
-    entry.references += 1;
-    return entry;
   }
 };
 
@@ -1893,6 +1940,10 @@ var CacheStack = class extends EventEmitter {
     const maxProfileEntries = options.maxProfileEntries ?? DEFAULT_MAX_PROFILE_ENTRIES;
     this.ttlResolver = new TtlResolver({ maxProfileEntries });
     this.circuitBreakerManager = new CircuitBreakerManager({ maxEntries: maxProfileEntries });
+    this.stampedeGuard = new StampedeGuard({
+      maxInFlight: options.stampedeMaxInFlight,
+      entryTimeoutMs: options.stampedeEntryTimeoutMs
+    });
     this.currentGeneration = options.generation;
     if (options.publishSetInvalidation !== void 0) {
       console.warn(
@@ -1971,7 +2022,7 @@ var CacheStack = class extends EventEmitter {
   }
   layers;
   options;
-  stampedeGuard = new StampedeGuard();
+  stampedeGuard;
   metricsCollector = new MetricsCollector();
   instanceId = createInstanceId();
   startup;
@@ -2048,7 +2099,7 @@ var CacheStack = class extends EventEmitter {
     if (!fetcher) {
       return null;
     }
-    return this.fetchWithGuards(normalizedKey, fetcher, options);
+    return this.fetchWithGuards(normalizedKey, fetcher, options, void 0, void 0, true);
   }
   /**
    * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
@@ -2209,7 +2260,8 @@ var CacheStack = class extends EventEmitter {
               return promise;
             }
             if (existing.fetch !== entry.fetch || existing.optionsSignature !== optionsSignature) {
-              throw new Error(`mget received conflicting entries for key "${entry.key}".`);
+              const displayKey = entry.key.length > 64 ? `${entry.key.slice(0, 64)}...` : entry.key;
+              throw new Error(`mget received conflicting entries for key "${displayKey}".`);
             }
             return existing.promise;
           })
@@ -2539,12 +2591,15 @@ var CacheStack = class extends EventEmitter {
       await this.handleInvalidationMessage(message);
     });
   }
-  async fetchWithGuards(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
+  async fetchWithGuards(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, initialMissConfirmed = false) {
     const fetchTask = async () => {
-      const secondHit = await this.readFromLayers(key, options, "fresh-only");
-      if (secondHit.found) {
-        this.metricsCollector.increment("hits");
-        return secondHit.value;
+      const shouldRecheckFreshLayers = !(initialMissConfirmed && this.options.singleFlightCoordinator);
+      if (shouldRecheckFreshLayers) {
+        const secondHit = await this.readFromLayers(key, options, "fresh-only");
+        if (secondHit.found) {
+          this.metricsCollector.increment("hits");
+          return secondHit.value;
+        }
       }
       return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch);
     };
@@ -2552,12 +2607,22 @@ var CacheStack = class extends EventEmitter {
       if (!this.options.singleFlightCoordinator) {
         return fetchTask();
       }
-      return this.options.singleFlightCoordinator.execute(
-        key,
-        this.resolveSingleFlightOptions(),
-        fetchTask,
-        () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch)
-      );
+      try {
+        return await this.options.singleFlightCoordinator.execute(
+          key,
+          this.resolveSingleFlightOptions(),
+          fetchTask,
+          () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch)
+        );
+      } catch (error) {
+        if (!this.isGracefulDegradationEnabled()) {
+          throw error;
+        }
+        this.metricsCollector.increment("degradedOperations");
+        this.logger.warn?.("single-flight-coordinator-degraded", { key, error: this.formatError(error) });
+        this.emitError("single-flight", { key, degraded: true, error: this.formatError(error) });
+        return fetchTask();
+      }
     };
     if (this.options.stampedePrevention === false) {
       return singleFlightTask();
@@ -3248,6 +3313,11 @@ var RedisInvalidationBus = class {
 
 // src/http/createCacheStatsHandler.ts
 function createCacheStatsHandler(cache, options = {}) {
+  if (options.allowPublicAccess === true) {
+    console.warn(
+      "[layercache] WARNING: Stats endpoint is publicly accessible without authentication. Set allowPublicAccess: false (or provide an authorize callback) before deploying to production."
+    );
+  }
   return async (request, response) => {
     response.setHeader?.("content-type", "application/json; charset=utf-8");
     response.setHeader?.("cache-control", "no-store");
@@ -3290,6 +3360,11 @@ function createCachedMethodDecorator(options) {
 
 // src/integrations/fastify.ts
 function createFastifyLayercachePlugin(cache, options = {}) {
+  if (options.exposeStatsRoute === true && options.allowPublicStatsRoute === true) {
+    console.warn(
+      "[layercache] WARNING: Cache stats route is publicly accessible without authentication. Set allowPublicStatsRoute: false (or provide an authorizeStatsRoute callback) before deploying to production."
+    );
+  }
   return async (fastify) => {
     fastify.decorate("cache", cache);
     if (options.exposeStatsRoute === true && fastify.get) {
@@ -3485,6 +3560,7 @@ var RedisLayer = class {
   compression;
   compressionThreshold;
   decompressionMaxBytes;
+  commandTimeoutMs;
   disconnectOnDispose;
   constructor(options) {
     this.client = options.client;
@@ -3497,6 +3573,7 @@ var RedisLayer = class {
     this.compression = options.compression;
     this.compressionThreshold = options.compressionThreshold ?? 1024;
     this.decompressionMaxBytes = options.decompressionMaxBytes ?? 64 * 1024 * 1024;
+    this.commandTimeoutMs = this.normalizeCommandTimeoutMs(options.commandTimeoutMs);
     this.disconnectOnDispose = options.disconnectOnDispose ?? false;
   }
   async get(key) {
@@ -3504,7 +3581,11 @@ var RedisLayer = class {
     return unwrapStoredValue(payload);
   }
   async getEntry(key) {
-    const payload = await this.client.getBuffer(this.withPrefix(key));
+    this.validateKey(key);
+    const payload = await this.runCommand(
+      `get(${this.displayKey(key)})`,
+      () => this.client.getBuffer(this.withPrefix(key))
+    );
     if (payload === null) {
       return null;
     }
@@ -3514,11 +3595,14 @@ var RedisLayer = class {
     if (keys.length === 0) {
       return [];
     }
+    for (const key of keys) {
+      this.validateKey(key);
+    }
     const pipeline = this.client.pipeline();
     for (const key of keys) {
       pipeline.getBuffer(this.withPrefix(key));
     }
-    const results = await pipeline.exec();
+    const results = await this.runCommand(`mget(${keys.length})`, () => pipeline.exec());
     if (results === null) {
       return keys.map(() => null);
     }
@@ -3536,6 +3620,9 @@ var RedisLayer = class {
     if (entries.length === 0) {
       return;
     }
+    for (const entry of entries) {
+      this.validateKey(entry.key);
+    }
     const pipeline = this.client.pipeline();
     for (const entry of entries) {
       const serialized = this.primarySerializer().serialize(entry.value);
@@ -3547,33 +3634,46 @@ var RedisLayer = class {
         pipeline.set(normalizedKey, payload);
       }
     }
-    await pipeline.exec();
+    await this.runCommand(`mset(${entries.length})`, () => pipeline.exec());
   }
   async set(key, value, ttl = this.defaultTtl) {
+    this.validateKey(key);
     const serialized = this.primarySerializer().serialize(value);
     const payload = await this.encodePayload(serialized);
     const normalizedKey = this.withPrefix(key);
     if (ttl && ttl > 0) {
-      await this.client.set(normalizedKey, payload, "EX", ttl);
+      await this.runCommand(
+        `set(${this.displayKey(key)})`,
+        () => this.client.set(normalizedKey, payload, "EX", ttl)
+      );
       return;
     }
-    await this.client.set(normalizedKey, payload);
+    await this.runCommand(`set(${this.displayKey(key)})`, () => this.client.set(normalizedKey, payload));
   }
   async delete(key) {
-    await this.client.del(this.withPrefix(key));
+    this.validateKey(key);
+    await this.runCommand(`delete(${this.displayKey(key)})`, () => this.client.del(this.withPrefix(key)));
   }
   async deleteMany(keys) {
     if (keys.length === 0) {
       return;
     }
-    await this.client.del(...keys.map((key) => this.withPrefix(key)));
+    for (const key of keys) {
+      this.validateKey(key);
+    }
+    await this.runCommand(
+      `deleteMany(${keys.length})`,
+      () => this.client.del(...keys.map((key) => this.withPrefix(key)))
+    );
   }
   async has(key) {
-    const exists = await this.client.exists(this.withPrefix(key));
+    this.validateKey(key);
+    const exists = await this.runCommand(`has(${this.displayKey(key)})`, () => this.client.exists(this.withPrefix(key)));
     return exists > 0;
   }
   async ttl(key) {
-    const remaining = await this.client.ttl(this.withPrefix(key));
+    this.validateKey(key);
+    const remaining = await this.runCommand(`ttl(${this.displayKey(key)})`, () => this.client.ttl(this.withPrefix(key)));
     if (remaining < 0) {
       return null;
     }
@@ -3581,13 +3681,16 @@ var RedisLayer = class {
   }
   async size() {
     if (!this.prefix) {
-      return this.client.dbsize();
+      return this.runCommand("dbsize()", () => this.client.dbsize());
     }
     const pattern = `${this.prefix}*`;
     let cursor = "0";
     let count = 0;
     do {
-      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
+      const [nextCursor, keys] = await this.runCommand(
+        `scan("${pattern}")`,
+        () => this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount)
+      );
       cursor = nextCursor;
       count += keys.length;
     } while (cursor !== "0");
@@ -3595,7 +3698,7 @@ var RedisLayer = class {
   }
   async ping() {
     try {
-      return await this.client.ping() === "PONG";
+      return await this.runCommand("ping()", () => this.client.ping()) === "PONG";
     } catch {
       return false;
     }
@@ -3618,14 +3721,17 @@ var RedisLayer = class {
     const pattern = `${this.prefix}*`;
     let cursor = "0";
     do {
-      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
+      const [nextCursor, keys] = await this.runCommand(
+        `scan("${pattern}")`,
+        () => this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount)
+      );
       cursor = nextCursor;
       if (keys.length === 0) {
         continue;
       }
       for (let i = 0; i < keys.length; i += BATCH_DELETE_SIZE) {
         const batch = keys.slice(i, i + BATCH_DELETE_SIZE);
-        await this.client.del(...batch);
+        await this.runCommand(`clear-del(${batch.length})`, () => this.client.del(...batch));
       }
     } while (cursor !== "0");
   }
@@ -3641,7 +3747,10 @@ var RedisLayer = class {
     const pattern = `${this.prefix}*`;
     let cursor = "0";
     do {
-      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
+      const [nextCursor, keys] = await this.runCommand(
+        `scan("${pattern}")`,
+        () => this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount)
+      );
       cursor = nextCursor;
       for (const key of keys) {
         await visitor(this.prefix ? key.slice(this.prefix.length) : key);
@@ -3652,7 +3761,10 @@ var RedisLayer = class {
     const matches = [];
     let cursor = "0";
     do {
-      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
+      const [nextCursor, keys] = await this.runCommand(
+        `scan("${pattern}")`,
+        () => this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount)
+      );
       cursor = nextCursor;
       matches.push(...keys);
     } while (cursor !== "0");
@@ -3661,6 +3773,23 @@ var RedisLayer = class {
   withPrefix(key) {
     return `${this.prefix}${key}`;
   }
+  validateKey(key) {
+    if (key.length === 0) {
+      throw new Error("RedisLayer: key must not be empty.");
+    }
+    if (key.length > 1024) {
+      throw new Error(`RedisLayer: key length must be at most 1 024 characters (got ${key.length}).`);
+    }
+    if (/[\u0000-\u001F\u007F]/.test(key)) {
+      throw new Error("RedisLayer: key contains unsupported control characters.");
+    }
+    if (/[\uD800-\uDFFF]/.test(key)) {
+      throw new Error("RedisLayer: key contains unsupported surrogate code points.");
+    }
+  }
+  displayKey(key) {
+    return key.length > 64 ? `${key.slice(0, 64)}...` : key;
+  }
   async deserializeOrDelete(key, payload) {
     let decodedPayload;
     try {
@@ -3684,20 +3813,30 @@ var RedisLayer = class {
   }
   async deleteCorruptedKey(key) {
     try {
-      await this.client.del(this.withPrefix(key));
+      await this.runCommand(`deleteCorrupted(${this.displayKey(key)})`, () => this.client.del(this.withPrefix(key)));
     } catch (deleteError) {
-      console.warn(`[layercache] RedisLayer: failed to delete corrupted key "${key}"`, deleteError);
+      const displayKey = key.length > 64 ? `${key.slice(0, 64)}...` : key;
+      console.warn(`[layercache] RedisLayer: failed to delete corrupted key "${displayKey}"`, deleteError);
     }
   }
   async rewriteWithPrimarySerializer(key, value) {
     const serialized = this.primarySerializer().serialize(value);
     const payload = await this.encodePayload(serialized);
-    const ttl = await this.client.ttl(this.withPrefix(key));
+    const ttl = await this.runCommand(
+      `rewrite-ttl(${this.displayKey(key)})`,
+      () => this.client.ttl(this.withPrefix(key))
+    );
     if (ttl > 0) {
-      await this.client.set(this.withPrefix(key), payload, "EX", ttl);
+      await this.runCommand(
+        `rewrite-set(${this.displayKey(key)})`,
+        () => this.client.set(this.withPrefix(key), payload, "EX", ttl)
+      );
       return;
     }
-    await this.client.set(this.withPrefix(key), payload);
+    await this.runCommand(
+      `rewrite-set(${this.displayKey(key)})`,
+      () => this.client.set(this.withPrefix(key), payload)
+    );
   }
   primarySerializer() {
     const serializer = this.serializers[0];
@@ -3793,12 +3932,163 @@ var RedisLayer = class {
       source.pipe(decompressor);
     });
   }
+  normalizeCommandTimeoutMs(value) {
+    if (value === void 0) {
+      return void 0;
+    }
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new Error("RedisLayer.commandTimeoutMs must be a positive number.");
+    }
+    return value;
+  }
+  async runCommand(operation, command) {
+    const promise = command();
+    if (!this.commandTimeoutMs) {
+      return promise;
+    }
+    let timer;
+    return Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          reject(new Error(`RedisLayer command ${operation} timed out after ${this.commandTimeoutMs}ms.`));
+        }, this.commandTimeoutMs);
+        timer.unref?.();
+      })
+    ]).finally(() => {
+      if (timer) {
+        clearTimeout(timer);
+      }
+    });
+  }
 };
 
 // src/layers/DiskLayer.ts
-import { createHash, randomBytes as randomBytes2 } from "crypto";
+import { createHash as createHash2, randomBytes as randomBytes3 } from "crypto";
 import { promises as fs2 } from "fs";
 import { join, resolve } from "path";
+
+// src/internal/PayloadProtection.ts
+import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes as randomBytes2, timingSafeEqual } from "crypto";
+var MAGIC_ENCRYPTED = Buffer.from("LCP1:");
+var MAGIC_SIGNED = Buffer.from("LCS1:");
+var ALGORITHM = "aes-256-gcm";
+var IV_LENGTH = 12;
+var AUTH_TAG_LENGTH = 16;
+var HMAC_LENGTH = 32;
+var PayloadProtection = class {
+  encryptionKey;
+  signingKey;
+  constructor(options) {
+    if (options.encryptionKey) {
+      const raw = Buffer.isBuffer(options.encryptionKey) ? options.encryptionKey : Buffer.from(options.encryptionKey, "utf8");
+      this.encryptionKey = createHash("sha256").update(raw).digest();
+    }
+    if (options.signingKey && !options.encryptionKey) {
+      const raw = Buffer.isBuffer(options.signingKey) ? options.signingKey : Buffer.from(options.signingKey, "utf8");
+      this.signingKey = createHash("sha256").update(raw).digest();
+    }
+  }
+  /** Returns `true` when any protection (encryption or signing) is configured. */
+  get isEnabled() {
+    return this.encryptionKey !== void 0 || this.signingKey !== void 0;
+  }
+  /**
+   * Applies the configured protection (encryption or signing) to a payload.
+   * Returns the input unchanged when no protection is configured.
+   */
+  protect(payload) {
+    if (this.encryptionKey) {
+      return this.encrypt(payload, this.encryptionKey);
+    }
+    if (this.signingKey) {
+      return this.sign(payload, this.signingKey);
+    }
+    return payload;
+  }
+  /**
+   * Removes the protection layer from a payload.
+   *
+   * - Protected payloads are decrypted/verified using the configured keys.
+   * - Legacy unprotected payloads pass through unchanged when **no** protection
+   *   is configured.
+   * - If protection **is** configured but the payload is not protected, the
+   *   payload is treated as a legacy entry. Callers can handle this case by
+   *   checking `isEnabled` separately.
+   */
+  unprotect(payload) {
+    if (this.startsWith(payload, MAGIC_ENCRYPTED)) {
+      if (!this.encryptionKey) {
+        throw new PayloadProtectionError("Encrypted payload but no encryptionKey configured.");
+      }
+      return this.decrypt(payload, this.encryptionKey);
+    }
+    if (this.startsWith(payload, MAGIC_SIGNED)) {
+      if (!this.signingKey) {
+        throw new PayloadProtectionError("Signed payload but no signingKey configured.");
+      }
+      return this.verify(payload, this.signingKey);
+    }
+    return payload;
+  }
+  // ── Encryption (AES-256-GCM) ──────────────────────────────────────────
+  encrypt(plaintext, key) {
+    const iv = randomBytes2(IV_LENGTH);
+    const cipher = createCipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+    const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    return Buffer.concat([MAGIC_ENCRYPTED, iv, authTag, encrypted]);
+  }
+  decrypt(payload, key) {
+    const headerEnd = MAGIC_ENCRYPTED.length;
+    const iv = payload.subarray(headerEnd, headerEnd + IV_LENGTH);
+    const authTag = payload.subarray(headerEnd + IV_LENGTH, headerEnd + IV_LENGTH + AUTH_TAG_LENGTH);
+    const ciphertext = payload.subarray(headerEnd + IV_LENGTH + AUTH_TAG_LENGTH);
+    try {
+      const decipher = createDecipheriv(ALGORITHM, key, iv, {
+        authTagLength: AUTH_TAG_LENGTH
+      });
+      decipher.setAuthTag(authTag);
+      return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    } catch {
+      throw new PayloadProtectionError(
+        "Decryption failed. The data may have been tampered with or the encryptionKey is incorrect."
+      );
+    }
+  }
+  // ── Signing (HMAC-SHA256) ─────────────────────────────────────────────
+  sign(payload, key) {
+    const hmac = createHmac("sha256", key).update(payload).digest();
+    return Buffer.concat([MAGIC_SIGNED, hmac, payload]);
+  }
+  verify(payload, key) {
+    const headerEnd = MAGIC_SIGNED.length;
+    const receivedHmac = payload.subarray(headerEnd, headerEnd + HMAC_LENGTH);
+    const data = payload.subarray(headerEnd + HMAC_LENGTH);
+    const expectedHmac = createHmac("sha256", key).update(data).digest();
+    if (receivedHmac.length !== HMAC_LENGTH || !timingSafeEqual(receivedHmac, expectedHmac)) {
+      throw new PayloadProtectionError(
+        "HMAC verification failed. The data may have been tampered with or the signingKey is incorrect."
+      );
+    }
+    return data;
+  }
+  // ── Helpers ────────────────────────────────────────────────────────────
+  startsWith(buffer, prefix) {
+    if (buffer.length < prefix.length) {
+      return false;
+    }
+    return buffer.subarray(0, prefix.length).equals(prefix);
+  }
+};
+var PayloadProtectionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PayloadProtectionError";
+  }
+};
+
+// src/layers/DiskLayer.ts
 var FILE_SCAN_CONCURRENCY = 32;
 var DiskLayer = class {
   name;
@@ -3808,6 +4098,7 @@ var DiskLayer = class {
   serializer;
   maxFiles;
   maxEntryBytes;
+  protection;
   writeQueue = Promise.resolve();
   constructor(options) {
     this.directory = this.resolveDirectory(options.directory);
@@ -3816,6 +4107,10 @@ var DiskLayer = class {
     this.serializer = options.serializer ?? new JsonSerializer();
     this.maxFiles = this.normalizeMaxFiles(options.maxFiles);
     this.maxEntryBytes = this.normalizeMaxEntryBytes(options.maxEntryBytes);
+    this.protection = new PayloadProtection({
+      encryptionKey: options.encryptionKey,
+      signingKey: options.signingKey
+    });
   }
   async get(key) {
     return unwrapStoredValue(await this.getEntry(key));
@@ -3848,10 +4143,12 @@ var DiskLayer = class {
         expiresAt: ttl && ttl > 0 ? Date.now() + ttl * 1e3 : null
       };
       const payload = this.serializer.serialize(entry);
+      const raw = Buffer.isBuffer(payload) ? payload : Buffer.from(payload, "utf8");
+      const protectedPayload = this.protection.protect(raw);
       const targetPath = this.keyToPath(key);
-      const tempPath = `${targetPath}.${process.pid}.${Date.now()}.${randomBytes2(8).toString("hex")}.tmp`;
+      const tempPath = `${targetPath}.${process.pid}.${Date.now()}.${randomBytes3(8).toString("hex")}.tmp`;
       try {
-        await fs2.writeFile(tempPath, payload);
+        await fs2.writeFile(tempPath, protectedPayload);
         await fs2.rename(tempPath, targetPath);
       } catch (error) {
         await this.safeDelete(tempPath);
@@ -3949,7 +4246,7 @@ var DiskLayer = class {
   async dispose() {
   }
   keyToPath(key) {
-    const hash = createHash("sha256").update(key).digest("hex");
+    const hash = createHash2("sha256").update(key).digest("hex");
     return join(this.directory, `${hash}.lc`);
   }
   resolveDirectory(directory) {
@@ -3963,10 +4260,13 @@ var DiskLayer = class {
   }
   normalizeMaxFiles(maxFiles) {
     if (maxFiles === void 0) {
+      return 5e4;
+    }
+    if (maxFiles === Number.POSITIVE_INFINITY) {
       return void 0;
     }
     if (!Number.isInteger(maxFiles) || maxFiles <= 0) {
-      throw new Error("DiskLayer.maxFiles must be a positive integer.");
+      throw new Error("DiskLayer.maxFiles must be a positive integer or Infinity.");
     }
     return maxFiles;
   }
@@ -4078,7 +4378,8 @@ var DiskLayer = class {
     );
   }
   deserializeEntry(raw) {
-    const entry = this.serializer.deserialize(raw);
+    const unprotected = this.protection.unprotect(raw);
+    const entry = this.serializer.deserialize(unprotected);
     if (!isDiskEntry(entry)) {
       throw new Error("Invalid disk cache entry.");
     }
@@ -4200,7 +4501,10 @@ var MemcachedLayer = class {
   validateKey(key) {
     const fullKey = this.withPrefix(key);
     if (Buffer.byteLength(fullKey, "utf8") > 250) {
-      throw new Error(`MemcachedLayer: key exceeds 250-byte Memcached limit: "${fullKey.slice(0, 60)}..."`);
+      const displayKey = fullKey.slice(0, 64);
+      throw new Error(
+        `MemcachedLayer: key exceeds 250-byte Memcached limit: "${displayKey}${fullKey.length > 64 ? "..." : ""}"`
+      );
     }
     if (/[\s\x00-\x1f\x7f]/.test(fullKey)) {
       throw new Error(
@@ -4243,14 +4547,19 @@ return 0
 var RedisSingleFlightCoordinator = class {
   client;
   prefix;
+  commandTimeoutMs;
   constructor(options) {
     this.client = options.client;
     this.prefix = options.prefix ?? "layercache:singleflight";
+    this.commandTimeoutMs = this.normalizeCommandTimeoutMs(options.commandTimeoutMs);
   }
   async execute(key, options, worker, waiter) {
     const lockKey = `${this.prefix}:${encodeURIComponent(key)}`;
     const token = randomUUID();
-    const acquired = await this.client.set(lockKey, token, "PX", options.leaseMs, "NX");
+    const acquired = await this.runCommand(
+      `acquire("${key}")`,
+      () => this.client.set(lockKey, token, "PX", options.leaseMs, "NX")
+    );
     if (acquired === "OK") {
       const renewTimer = this.startLeaseRenewal(lockKey, token, options);
       try {
@@ -4259,7 +4568,7 @@ var RedisSingleFlightCoordinator = class {
         if (renewTimer) {
           clearInterval(renewTimer);
         }
-        await this.client.eval(RELEASE_SCRIPT, 1, lockKey, token);
+        await this.runCommand(`release("${key}")`, () => this.client.eval(RELEASE_SCRIPT, 1, lockKey, token));
       }
     }
     return waiter();
@@ -4270,11 +4579,45 @@ var RedisSingleFlightCoordinator = class {
       return void 0;
     }
     const timer = setInterval(() => {
-      void this.client.eval(RENEW_SCRIPT, 1, lockKey, token, String(options.leaseMs)).catch(() => void 0);
+      void this.runCommand(
+        `renew("${lockKey}")`,
+        () => this.client.eval(RENEW_SCRIPT, 1, lockKey, token, String(options.leaseMs))
+      ).catch(() => void 0);
     }, renewIntervalMs);
     timer.unref?.();
     return timer;
   }
+  normalizeCommandTimeoutMs(value) {
+    if (value === void 0) {
+      return void 0;
+    }
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new Error("RedisSingleFlightCoordinator.commandTimeoutMs must be a positive number.");
+    }
+    return value;
+  }
+  async runCommand(operation, command) {
+    const promise = command();
+    if (!this.commandTimeoutMs) {
+      return promise;
+    }
+    let timer;
+    return Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          reject(
+            new Error(`RedisSingleFlightCoordinator command ${operation} timed out after ${this.commandTimeoutMs}ms.`)
+          );
+        }, this.commandTimeoutMs);
+        timer.unref?.();
+      })
+    ]).finally(() => {
+      if (timer) {
+        clearTimeout(timer);
+      }
+    });
+  }
 };
 
 // src/metrics/PrometheusExporter.ts