layercache 1.3.0 → 1.3.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-BXWTKlI1.js';
-export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheDegradationOptions, n as CacheHealthCheckResult, o as CacheHitRateSnapshot, p as CacheInspectResult, q as CacheLayerLatency, r as CacheMGetEntry, s as CacheMSetEntry, t as CacheMetricsSnapshot, u as CacheMissError, v as CacheNamespace, w as CacheRateLimitOptions, x as CacheSnapshotEntry, y as CacheStackEvents, z as CacheStackOptions, A as CacheStatsSnapshot, B as CacheTtlPolicy, D as CacheTtlPolicyContext, E as CacheWarmEntry, F as CacheWarmOptions, G as CacheWarmProgress, H as CacheWriteBehindOptions, J as CacheWriteOptions, K as EvictionPolicy, L as LayerTtlMap, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-BXWTKlI1.js';
+import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-CUHTP9Bc.js';
+export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheDegradationOptions, n as CacheHealthCheckResult, o as CacheHitRateSnapshot, p as CacheInspectResult, q as CacheLayerLatency, r as CacheMGetEntry, s as CacheMSetEntry, t as CacheMetricsSnapshot, u as CacheMissError, v as CacheNamespace, w as CacheRateLimitOptions, x as CacheSnapshotEntry, y as CacheStackEvents, z as CacheStackOptions, A as CacheStatsSnapshot, B as CacheTtlPolicy, D as CacheTtlPolicyContext, E as CacheWarmEntry, F as CacheWarmOptions, G as CacheWarmProgress, H as CacheWriteBehindOptions, J as CacheWriteOptions, K as EvictionPolicy, L as LayerTtlMap, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-CUHTP9Bc.js';
 import Redis from 'ioredis';
 import 'node:events';
 
@@ -63,6 +63,11 @@ declare class RedisTagIndex implements CacheTagIndex {
 }
 
 interface CacheStatsHandlerOptions {
+    /**
+     * @deprecated Exposing cache stats without authentication is a security risk.
+     * Provide an `authorize` callback instead. This option will be removed in a
+     * future release.
+     */
     allowPublicAccess?: boolean;
     authorize?: (request: unknown) => boolean | Promise<boolean>;
     unauthorizedStatusCode?: number;
@@ -91,6 +96,11 @@ interface FastifyLikeReply {
 interface FastifyLayercachePluginOptions {
     exposeStatsRoute?: boolean;
     statsPath?: string;
+    /**
+     * @deprecated Exposing cache stats without authentication is a security risk.
+     * Provide an `authorizeStatsRoute` callback instead. This option will be
+     * removed in a future release.
+     */
     allowPublicStatsRoute?: boolean;
     authorizeStatsRoute?: (request: unknown) => boolean | Promise<boolean>;
     unauthorizedStatusCode?: number;
@@ -246,6 +256,8 @@ declare class RedisLayer implements CacheLayer {
     forEachKey(visitor: (key: string) => void | Promise<void>): Promise<void>;
     private scanKeys;
     private withPrefix;
+    private validateKey;
+    private displayKey;
     private deserializeOrDelete;
     private deleteCorruptedKey;
     private rewriteWithPrimarySerializer;
@@ -274,7 +286,8 @@ interface DiskLayerOptions {
     /**
      * Maximum number of cache files to store on disk. When exceeded, the oldest
      * entries (by file mtime) are evicted to keep the directory bounded.
-     * Defaults to unlimited.
+     * Defaults to 50 000. Set to `Infinity` to disable the limit (not recommended
+     * in production — unbounded growth will eventually exhaust disk space).
      */
     maxFiles?: number;
     /**
@@ -283,6 +296,19 @@ interface DiskLayerOptions {
      * Set to `false` to disable the limit.
      */
     maxEntryBytes?: number | false;
+    /**
+     * Encrypt cached data at rest using AES-256-GCM. Accepts a string or Buffer.
+     * The key material is hashed with SHA-256 to derive the actual cipher key.
+     * Encryption also provides authenticated integrity — a separate signingKey
+     * is unnecessary when encryption is enabled.
+     */
+    encryptionKey?: string | Buffer;
+    /**
+     * Sign cached data at rest using HMAC-SHA256 for integrity verification.
+     * Accepts a string or Buffer. Ignored when `encryptionKey` is also provided
+     * (AES-GCM already provides integrity).
+     */
+    signingKey?: string | Buffer;
 }
 /**
  * A file-system backed cache layer.
@@ -303,6 +329,7 @@ declare class DiskLayer implements CacheLayer {
     private readonly serializer;
     private readonly maxFiles;
     private readonly maxEntryBytes;
+    private readonly protection;
     private writeQueue;
     constructor(options: DiskLayerOptions);
     get<T>(key: string): Promise<T | null>;
@@ -429,9 +456,27 @@ declare class RedisSingleFlightCoordinator implements CacheSingleFlightCoordinat
     private runCommand;
 }
 
+interface StampedeGuardOptions {
+    /**
+     * Maximum number of concurrent in-flight keys. When exceeded, new `execute`
+     * calls for keys that are not already in-flight will throw immediately.
+     * Defaults to 10 000.
+     */
+    maxInFlight?: number;
+    /**
+     * Maximum milliseconds to wait for a single in-flight task before rejecting
+     * with a timeout error. When a timeout fires the entry is released so
+     * subsequent callers can retry. Defaults to no timeout.
+     */
+    entryTimeoutMs?: number;
+}
 declare class StampedeGuard {
     private readonly inFlight;
+    private readonly maxInFlight;
+    private readonly entryTimeoutMs;
+    constructor(options?: StampedeGuardOptions);
     execute<T>(key: string, task: () => Promise<T>): Promise<T>;
+    private withTimeout;
     private releaseEntry;
 }
 

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
@@ -1813,6 +1820,12 @@ var JsonSerializer = class {
 // src/stampede/StampedeGuard.ts
 var StampedeGuard = class {
   inFlight = /* @__PURE__ */ new Map();
+  maxInFlight;
+  entryTimeoutMs;
+  constructor(options = {}) {
+    this.maxInFlight = options.maxInFlight ?? 1e4;
+    this.entryTimeoutMs = options.entryTimeoutMs;
+  }
   async execute(key, task) {
     const existing = this.inFlight.get(key);
     if (existing) {
@@ -1823,8 +1836,15 @@ var StampedeGuard = class {
         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: Promise.resolve().then(task),
+      promise: guardedPromise,
       references: 1
     };
     this.inFlight.set(key, entry);
@@ -1834,6 +1854,27 @@ var StampedeGuard = class {
       this.releaseEntry(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);
@@ -1899,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(
@@ -1977,7 +2022,7 @@ var CacheStack = class extends EventEmitter {
   }
   layers;
   options;
-  stampedeGuard = new StampedeGuard();
+  stampedeGuard;
   metricsCollector = new MetricsCollector();
   instanceId = createInstanceId();
   startup;
@@ -2215,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;
           })
@@ -3267,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");
@@ -3309,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) {
@@ -3525,7 +3581,11 @@ var RedisLayer = class {
     return unwrapStoredValue(payload);
   }
   async getEntry(key) {
-    const payload = await this.runCommand(`get("${key}")`, () => 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;
     }
@@ -3535,6 +3595,9 @@ 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));
@@ -3557,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);
@@ -3571,33 +3637,43 @@ var RedisLayer = class {
     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.runCommand(`set("${key}")`, () => this.client.set(normalizedKey, payload, "EX", ttl));
+      await this.runCommand(
+        `set(${this.displayKey(key)})`,
+        () => this.client.set(normalizedKey, payload, "EX", ttl)
+      );
       return;
     }
-    await this.runCommand(`set("${key}")`, () => this.client.set(normalizedKey, payload));
+    await this.runCommand(`set(${this.displayKey(key)})`, () => this.client.set(normalizedKey, payload));
   }
   async delete(key) {
-    await this.runCommand(`delete("${key}")`, () => 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;
     }
+    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.runCommand(`has("${key}")`, () => 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.runCommand(`ttl("${key}")`, () => 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;
     }
@@ -3697,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 {
@@ -3720,23 +3813,30 @@ var RedisLayer = class {
   }
   async deleteCorruptedKey(key) {
     try {
-      await this.runCommand(`deleteCorrupted("${key}")`, () => 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.runCommand(`rewrite-ttl("${key}")`, () => 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.runCommand(
-        `rewrite-set("${key}")`,
+        `rewrite-set(${this.displayKey(key)})`,
         () => this.client.set(this.withPrefix(key), payload, "EX", ttl)
       );
       return;
     }
-    await this.runCommand(`rewrite-set("${key}")`, () => 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];
@@ -3864,9 +3964,131 @@ var RedisLayer = class {
 };
 
 // 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;
@@ -3876,6 +4098,7 @@ var DiskLayer = class {
   serializer;
   maxFiles;
   maxEntryBytes;
+  protection;
   writeQueue = Promise.resolve();
   constructor(options) {
     this.directory = this.resolveDirectory(options.directory);
@@ -3884,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));
@@ -3916,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);
@@ -4017,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) {
@@ -4031,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;
   }
@@ -4146,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.");
     }
@@ -4268,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(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "layercache",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Production-ready multi-layer caching for Node.js. Stack memory + Redis + disk behind one API with stampede prevention, tag invalidation, stale serving, and full observability.",
   "keywords": [
     "cache",