@nodellmcache/encryption 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @nodellmcache/encryption
+
+## 1.0.0
+
+### Minor Changes
+
+- Initial release of `@nodellmcache/encryption`: an `EncryptedAdapter` that wraps any `StorageAdapter` and encrypts cached values at rest with AES-256-GCM (authenticated; tampering is detected) using pure `node:crypto`. A fresh random IV is used per write; keys/timestamps/metadata stay in the clear (cache keys are already hashed). Includes `generateKey()` and `deriveKey(passphrase, salt)` helpers; accepts a 32-byte Buffer, hex, or base64 key. Wrong key or tampered data throws `CacheAdapterError`.
+
+### Patch Changes
+
+- Updated dependencies [a2633d8]
+  - @nodellmcache/core@1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NodeLLMCache contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @nodellmcache/encryption
+
+Encrypting storage adapter wrapper for [NodeLLMCache](https://github.com/mdmax007/node-llm-cache). Wraps any `StorageAdapter` and encrypts cached **values** at rest with AES-256-GCM (authenticated, so tampering is detected). Pure `node:crypto`, no native bindings.
+
+## Install
+
+```bash
+npm install @nodellmcache/encryption @nodellmcache/core
+```
+
+## Quick start
+
+```ts
+import { PromptCache } from '@nodellmcache/prompt-cache'
+import { EncryptedAdapter, generateKey } from '@nodellmcache/encryption'
+import { RedisAdapter } from '@nodellmcache/redis'
+
+const key = generateKey() // 32 bytes; persist this securely (env/secret manager)
+
+const adapter = new EncryptedAdapter({
+  adapter: new RedisAdapter({ host: 'localhost', port: 6379 }),
+  key,
+})
+
+const cache = new PromptCache({ adapter })
+```
+
+Derive a key from a passphrase instead:
+
+```ts
+import { deriveKey } from '@nodellmcache/encryption'
+const key = deriveKey(process.env.CACHE_PASSPHRASE!, process.env.CACHE_SALT!)
+```
+
+## What is and isn't encrypted
+
+- **Encrypted**: the cached value (serialized, then AES-256-GCM with a fresh random IV per write).
+- **In the clear**: the cache key, timestamps, and metadata (sizes, cache type, model). Cache keys are already SHA-256 hashed by `KeyBuilder`, so no plaintext prompt content is exposed either way.
+
+## Notes
+
+- The key must be 32 bytes. Pass a `Buffer`, a 64-char hex string, or base64. `generateKey()` makes one; `deriveKey(passphrase, salt)` derives one via scrypt.
+- Decryption with the wrong key, or against tampered data, throws `CacheAdapterError` (the GCM auth tag fails).
+- It is a `StorageAdapter`, so it composes with anything, including `@nodellmcache/tiered`.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,142 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  EncryptedAdapter: () => EncryptedAdapter,
+  KEY_BYTES: () => KEY_BYTES,
+  deriveKey: () => deriveKey,
+  generateKey: () => generateKey,
+  normalizeKey: () => normalizeKey
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/EncryptedAdapter.ts
+var import_node_crypto2 = require("crypto");
+var import_core2 = require("@nodellmcache/core");
+
+// src/keys.ts
+var import_node_crypto = require("crypto");
+var import_core = require("@nodellmcache/core");
+var KEY_BYTES = 32;
+function generateKey() {
+  return (0, import_node_crypto.randomBytes)(KEY_BYTES);
+}
+function deriveKey(passphrase, salt) {
+  return (0, import_node_crypto.scryptSync)(passphrase, salt, KEY_BYTES);
+}
+function normalizeKey(key) {
+  let buf;
+  if (Buffer.isBuffer(key)) {
+    buf = key;
+  } else if (/^[0-9a-fA-F]{64}$/.test(key)) {
+    buf = Buffer.from(key, "hex");
+  } else {
+    buf = Buffer.from(key, "base64");
+  }
+  if (buf.length !== KEY_BYTES) {
+    throw new import_core.ValidationError(
+      `Encryption key must be ${KEY_BYTES} bytes (got ${buf.length}). Use generateKey() or deriveKey(passphrase, salt).`
+    );
+  }
+  return buf;
+}
+
+// src/EncryptedAdapter.ts
+var ALGO = "aes-256-gcm";
+var IV_BYTES = 12;
+var EncryptedAdapter = class {
+  inner;
+  key;
+  serializer;
+  constructor(options) {
+    this.inner = options.adapter;
+    this.key = normalizeKey(options.key);
+    this.serializer = options.serializer ?? new import_core2.JsonSerializer();
+  }
+  async get(key) {
+    const stored = await this.inner.get(key);
+    if (!stored) return null;
+    const value = this.decrypt(stored.value);
+    return {
+      key: stored.key,
+      value,
+      createdAt: stored.createdAt,
+      expiresAt: stored.expiresAt,
+      metadata: stored.metadata
+    };
+  }
+  async set(key, entry, ttl) {
+    const stored = {
+      key: entry.key,
+      value: this.encrypt(entry.value),
+      createdAt: entry.createdAt,
+      expiresAt: entry.expiresAt,
+      metadata: entry.metadata
+    };
+    await this.inner.set(key, stored, ttl);
+  }
+  async delete(key) {
+    await this.inner.delete(key);
+  }
+  async clear() {
+    await this.inner.clear();
+  }
+  async has(key) {
+    return this.inner.has(key);
+  }
+  async stats() {
+    return this.inner.stats();
+  }
+  // --- crypto --------------------------------------------------------------
+  encrypt(value) {
+    const iv = (0, import_node_crypto2.randomBytes)(IV_BYTES);
+    const cipher = (0, import_node_crypto2.createCipheriv)(ALGO, this.key, iv);
+    const plaintext = this.serializer.serialize(value);
+    const data = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return { v: 1, iv: iv.toString("base64"), tag: tag.toString("base64"), data: data.toString("base64") };
+  }
+  decrypt(blob) {
+    try {
+      const decipher = (0, import_node_crypto2.createDecipheriv)(ALGO, this.key, Buffer.from(blob.iv, "base64"));
+      decipher.setAuthTag(Buffer.from(blob.tag, "base64"));
+      const plaintext = Buffer.concat([
+        decipher.update(Buffer.from(blob.data, "base64")),
+        decipher.final()
+      ]);
+      return this.serializer.deserialize(plaintext);
+    } catch (cause) {
+      throw new import_core2.CacheAdapterError(
+        "Failed to decrypt cache entry (wrong key or tampered data)",
+        { cause }
+      );
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EncryptedAdapter,
+  KEY_BYTES,
+  deriveKey,
+  generateKey,
+  normalizeKey
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/EncryptedAdapter.ts","../src/keys.ts"],"sourcesContent":["export {\n  EncryptedAdapter,\n  type EncryptedAdapterOptions,\n  type EncryptedBlob,\n} from './EncryptedAdapter.js'\nexport { generateKey, deriveKey, normalizeKey, KEY_BYTES } from './keys.js'\n","import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'\nimport { CacheAdapterError, JsonSerializer } from '@nodellmcache/core'\nimport type { AdapterStats, CacheEntry, Serializer, StorageAdapter } from '@nodellmcache/core'\nimport { normalizeKey } from './keys.js'\n\nconst ALGO = 'aes-256-gcm'\nconst IV_BYTES = 12\n\n/** The encrypted envelope stored in place of a value. */\nexport interface EncryptedBlob {\n  v: 1\n  iv: string\n  tag: string\n  data: string\n}\n\nexport interface EncryptedAdapterOptions {\n  /** Inner adapter that stores the encrypted envelopes (memory, Redis, ...). */\n  adapter: StorageAdapter<EncryptedBlob>\n  /** 32-byte key: a Buffer, 64-char hex, or base64. See `generateKey`/`deriveKey`. */\n  key: Buffer | string\n  /** Serializer used to turn values into bytes before encryption. Defaults to JSON. */\n  serializer?: Serializer\n}\n\n/**\n * Wraps any {@link StorageAdapter} and encrypts cached **values** at rest with\n * AES-256-GCM (authenticated, so tampering is detected). Keys, timestamps, and\n * metadata are stored in the clear — only the value is encrypted, and cache keys\n * are already hashed by `KeyBuilder`, so no plaintext prompt content is exposed.\n *\n * Pure `node:crypto`, no native bindings.\n */\nexport class EncryptedAdapter<T = unknown> implements StorageAdapter<T> {\n  private readonly inner: StorageAdapter<EncryptedBlob>\n  private readonly key: Buffer\n  private readonly serializer: Serializer\n\n  constructor(options: EncryptedAdapterOptions) {\n    this.inner = options.adapter\n    this.key = normalizeKey(options.key)\n    this.serializer = options.serializer ?? new JsonSerializer()\n  }\n\n  async get(key: string): Promise<CacheEntry<T> | null> {\n    const stored = await this.inner.get(key)\n    if (!stored) return null\n    const value = this.decrypt(stored.value)\n    return {\n      key: stored.key,\n      value,\n      createdAt: stored.createdAt,\n      expiresAt: stored.expiresAt,\n      metadata: stored.metadata,\n    }\n  }\n\n  async set(key: string, entry: CacheEntry<T>, ttl?: number): Promise<void> {\n    const stored: CacheEntry<EncryptedBlob> = {\n      key: entry.key,\n      value: this.encrypt(entry.value),\n      createdAt: entry.createdAt,\n      expiresAt: entry.expiresAt,\n      metadata: entry.metadata,\n    }\n    await this.inner.set(key, stored, ttl)\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.inner.delete(key)\n  }\n\n  async clear(): Promise<void> {\n    await this.inner.clear()\n  }\n\n  async has(key: string): Promise<boolean> {\n    return this.inner.has(key)\n  }\n\n  async stats(): Promise<AdapterStats> {\n    return this.inner.stats()\n  }\n\n  // --- crypto --------------------------------------------------------------\n\n  private encrypt(value: T): EncryptedBlob {\n    const iv = randomBytes(IV_BYTES)\n    const cipher = createCipheriv(ALGO, this.key, iv)\n    const plaintext = this.serializer.serialize(value)\n    const data = Buffer.concat([cipher.update(plaintext), cipher.final()])\n    const tag = cipher.getAuthTag()\n    return { v: 1, iv: iv.toString('base64'), tag: tag.toString('base64'), data: data.toString('base64') }\n  }\n\n  private decrypt(blob: EncryptedBlob): T {\n    try {\n      const decipher = createDecipheriv(ALGO, this.key, Buffer.from(blob.iv, 'base64'))\n      decipher.setAuthTag(Buffer.from(blob.tag, 'base64'))\n      const plaintext = Buffer.concat([\n        decipher.update(Buffer.from(blob.data, 'base64')),\n        decipher.final(),\n      ])\n      return this.serializer.deserialize<T>(plaintext)\n    } catch (cause) {\n      throw new CacheAdapterError(\n        'Failed to decrypt cache entry (wrong key or tampered data)',\n        { cause },\n      )\n    }\n  }\n}\n","import { randomBytes, scryptSync } from 'node:crypto'\nimport { ValidationError } from '@nodellmcache/core'\n\n/** AES-256 needs a 32-byte key. */\nexport const KEY_BYTES = 32\n\n/** Generates a fresh random 32-byte AES-256 key. Persist it somewhere safe. */\nexport function generateKey(): Buffer {\n  return randomBytes(KEY_BYTES)\n}\n\n/**\n * Derives a 32-byte key from a passphrase and salt using scrypt. Use a stable,\n * unique salt per deployment (store it alongside your config, not the data).\n */\nexport function deriveKey(passphrase: string, salt: string | Buffer): Buffer {\n  return scryptSync(passphrase, salt, KEY_BYTES)\n}\n\n/**\n * Normalizes a key option into a 32-byte Buffer. Accepts a Buffer, a 64-char hex\n * string, or a 44-char base64 string.\n */\nexport function normalizeKey(key: Buffer | string): Buffer {\n  let buf: Buffer\n  if (Buffer.isBuffer(key)) {\n    buf = key\n  } else if (/^[0-9a-fA-F]{64}$/.test(key)) {\n    buf = Buffer.from(key, 'hex')\n  } else {\n    buf = Buffer.from(key, 'base64')\n  }\n  if (buf.length !== KEY_BYTES) {\n    throw new ValidationError(\n      `Encryption key must be ${KEY_BYTES} bytes (got ${buf.length}). ` +\n        'Use generateKey() or deriveKey(passphrase, salt).',\n    )\n  }\n  return buf\n}\n"],"mappings":"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","names":["import_node_crypto","import_core"]}

package/dist/index.d.cts

@@ -0,0 +1,56 @@
+import { StorageAdapter, Serializer, CacheEntry, AdapterStats } from '@nodellmcache/core';
+
+/** The encrypted envelope stored in place of a value. */
+interface EncryptedBlob {
+    v: 1;
+    iv: string;
+    tag: string;
+    data: string;
+}
+interface EncryptedAdapterOptions {
+    /** Inner adapter that stores the encrypted envelopes (memory, Redis, ...). */
+    adapter: StorageAdapter<EncryptedBlob>;
+    /** 32-byte key: a Buffer, 64-char hex, or base64. See `generateKey`/`deriveKey`. */
+    key: Buffer | string;
+    /** Serializer used to turn values into bytes before encryption. Defaults to JSON. */
+    serializer?: Serializer;
+}
+/**
+ * Wraps any {@link StorageAdapter} and encrypts cached **values** at rest with
+ * AES-256-GCM (authenticated, so tampering is detected). Keys, timestamps, and
+ * metadata are stored in the clear — only the value is encrypted, and cache keys
+ * are already hashed by `KeyBuilder`, so no plaintext prompt content is exposed.
+ *
+ * Pure `node:crypto`, no native bindings.
+ */
+declare class EncryptedAdapter<T = unknown> implements StorageAdapter<T> {
+    private readonly inner;
+    private readonly key;
+    private readonly serializer;
+    constructor(options: EncryptedAdapterOptions);
+    get(key: string): Promise<CacheEntry<T> | null>;
+    set(key: string, entry: CacheEntry<T>, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    stats(): Promise<AdapterStats>;
+    private encrypt;
+    private decrypt;
+}
+
+/** AES-256 needs a 32-byte key. */
+declare const KEY_BYTES = 32;
+/** Generates a fresh random 32-byte AES-256 key. Persist it somewhere safe. */
+declare function generateKey(): Buffer;
+/**
+ * Derives a 32-byte key from a passphrase and salt using scrypt. Use a stable,
+ * unique salt per deployment (store it alongside your config, not the data).
+ */
+declare function deriveKey(passphrase: string, salt: string | Buffer): Buffer;
+/**
+ * Normalizes a key option into a 32-byte Buffer. Accepts a Buffer, a 64-char hex
+ * string, or a 44-char base64 string.
+ */
+declare function normalizeKey(key: Buffer | string): Buffer;
+
+export { EncryptedAdapter, type EncryptedAdapterOptions, type EncryptedBlob, KEY_BYTES, deriveKey, generateKey, normalizeKey };

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { StorageAdapter, Serializer, CacheEntry, AdapterStats } from '@nodellmcache/core';
+
+/** The encrypted envelope stored in place of a value. */
+interface EncryptedBlob {
+    v: 1;
+    iv: string;
+    tag: string;
+    data: string;
+}
+interface EncryptedAdapterOptions {
+    /** Inner adapter that stores the encrypted envelopes (memory, Redis, ...). */
+    adapter: StorageAdapter<EncryptedBlob>;
+    /** 32-byte key: a Buffer, 64-char hex, or base64. See `generateKey`/`deriveKey`. */
+    key: Buffer | string;
+    /** Serializer used to turn values into bytes before encryption. Defaults to JSON. */
+    serializer?: Serializer;
+}
+/**
+ * Wraps any {@link StorageAdapter} and encrypts cached **values** at rest with
+ * AES-256-GCM (authenticated, so tampering is detected). Keys, timestamps, and
+ * metadata are stored in the clear — only the value is encrypted, and cache keys
+ * are already hashed by `KeyBuilder`, so no plaintext prompt content is exposed.
+ *
+ * Pure `node:crypto`, no native bindings.
+ */
+declare class EncryptedAdapter<T = unknown> implements StorageAdapter<T> {
+    private readonly inner;
+    private readonly key;
+    private readonly serializer;
+    constructor(options: EncryptedAdapterOptions);
+    get(key: string): Promise<CacheEntry<T> | null>;
+    set(key: string, entry: CacheEntry<T>, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    stats(): Promise<AdapterStats>;
+    private encrypt;
+    private decrypt;
+}
+
+/** AES-256 needs a 32-byte key. */
+declare const KEY_BYTES = 32;
+/** Generates a fresh random 32-byte AES-256 key. Persist it somewhere safe. */
+declare function generateKey(): Buffer;
+/**
+ * Derives a 32-byte key from a passphrase and salt using scrypt. Use a stable,
+ * unique salt per deployment (store it alongside your config, not the data).
+ */
+declare function deriveKey(passphrase: string, salt: string | Buffer): Buffer;
+/**
+ * Normalizes a key option into a 32-byte Buffer. Accepts a Buffer, a 64-char hex
+ * string, or a 44-char base64 string.
+ */
+declare function normalizeKey(key: Buffer | string): Buffer;
+
+export { EncryptedAdapter, type EncryptedAdapterOptions, type EncryptedBlob, KEY_BYTES, deriveKey, generateKey, normalizeKey };

package/dist/index.mjs

@@ -0,0 +1,111 @@
+// src/EncryptedAdapter.ts
+import { createCipheriv, createDecipheriv, randomBytes as randomBytes2 } from "crypto";
+import { CacheAdapterError, JsonSerializer } from "@nodellmcache/core";
+
+// src/keys.ts
+import { randomBytes, scryptSync } from "crypto";
+import { ValidationError } from "@nodellmcache/core";
+var KEY_BYTES = 32;
+function generateKey() {
+  return randomBytes(KEY_BYTES);
+}
+function deriveKey(passphrase, salt) {
+  return scryptSync(passphrase, salt, KEY_BYTES);
+}
+function normalizeKey(key) {
+  let buf;
+  if (Buffer.isBuffer(key)) {
+    buf = key;
+  } else if (/^[0-9a-fA-F]{64}$/.test(key)) {
+    buf = Buffer.from(key, "hex");
+  } else {
+    buf = Buffer.from(key, "base64");
+  }
+  if (buf.length !== KEY_BYTES) {
+    throw new ValidationError(
+      `Encryption key must be ${KEY_BYTES} bytes (got ${buf.length}). Use generateKey() or deriveKey(passphrase, salt).`
+    );
+  }
+  return buf;
+}
+
+// src/EncryptedAdapter.ts
+var ALGO = "aes-256-gcm";
+var IV_BYTES = 12;
+var EncryptedAdapter = class {
+  inner;
+  key;
+  serializer;
+  constructor(options) {
+    this.inner = options.adapter;
+    this.key = normalizeKey(options.key);
+    this.serializer = options.serializer ?? new JsonSerializer();
+  }
+  async get(key) {
+    const stored = await this.inner.get(key);
+    if (!stored) return null;
+    const value = this.decrypt(stored.value);
+    return {
+      key: stored.key,
+      value,
+      createdAt: stored.createdAt,
+      expiresAt: stored.expiresAt,
+      metadata: stored.metadata
+    };
+  }
+  async set(key, entry, ttl) {
+    const stored = {
+      key: entry.key,
+      value: this.encrypt(entry.value),
+      createdAt: entry.createdAt,
+      expiresAt: entry.expiresAt,
+      metadata: entry.metadata
+    };
+    await this.inner.set(key, stored, ttl);
+  }
+  async delete(key) {
+    await this.inner.delete(key);
+  }
+  async clear() {
+    await this.inner.clear();
+  }
+  async has(key) {
+    return this.inner.has(key);
+  }
+  async stats() {
+    return this.inner.stats();
+  }
+  // --- crypto --------------------------------------------------------------
+  encrypt(value) {
+    const iv = randomBytes2(IV_BYTES);
+    const cipher = createCipheriv(ALGO, this.key, iv);
+    const plaintext = this.serializer.serialize(value);
+    const data = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return { v: 1, iv: iv.toString("base64"), tag: tag.toString("base64"), data: data.toString("base64") };
+  }
+  decrypt(blob) {
+    try {
+      const decipher = createDecipheriv(ALGO, this.key, Buffer.from(blob.iv, "base64"));
+      decipher.setAuthTag(Buffer.from(blob.tag, "base64"));
+      const plaintext = Buffer.concat([
+        decipher.update(Buffer.from(blob.data, "base64")),
+        decipher.final()
+      ]);
+      return this.serializer.deserialize(plaintext);
+    } catch (cause) {
+      throw new CacheAdapterError(
+        "Failed to decrypt cache entry (wrong key or tampered data)",
+        { cause }
+      );
+    }
+  }
+};
+export {
+  EncryptedAdapter,
+  KEY_BYTES,
+  deriveKey,
+  generateKey,
+  normalizeKey
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/EncryptedAdapter.ts","../src/keys.ts"],"sourcesContent":["import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'\nimport { CacheAdapterError, JsonSerializer } from '@nodellmcache/core'\nimport type { AdapterStats, CacheEntry, Serializer, StorageAdapter } from '@nodellmcache/core'\nimport { normalizeKey } from './keys.js'\n\nconst ALGO = 'aes-256-gcm'\nconst IV_BYTES = 12\n\n/** The encrypted envelope stored in place of a value. */\nexport interface EncryptedBlob {\n  v: 1\n  iv: string\n  tag: string\n  data: string\n}\n\nexport interface EncryptedAdapterOptions {\n  /** Inner adapter that stores the encrypted envelopes (memory, Redis, ...). */\n  adapter: StorageAdapter<EncryptedBlob>\n  /** 32-byte key: a Buffer, 64-char hex, or base64. See `generateKey`/`deriveKey`. */\n  key: Buffer | string\n  /** Serializer used to turn values into bytes before encryption. Defaults to JSON. */\n  serializer?: Serializer\n}\n\n/**\n * Wraps any {@link StorageAdapter} and encrypts cached **values** at rest with\n * AES-256-GCM (authenticated, so tampering is detected). Keys, timestamps, and\n * metadata are stored in the clear — only the value is encrypted, and cache keys\n * are already hashed by `KeyBuilder`, so no plaintext prompt content is exposed.\n *\n * Pure `node:crypto`, no native bindings.\n */\nexport class EncryptedAdapter<T = unknown> implements StorageAdapter<T> {\n  private readonly inner: StorageAdapter<EncryptedBlob>\n  private readonly key: Buffer\n  private readonly serializer: Serializer\n\n  constructor(options: EncryptedAdapterOptions) {\n    this.inner = options.adapter\n    this.key = normalizeKey(options.key)\n    this.serializer = options.serializer ?? new JsonSerializer()\n  }\n\n  async get(key: string): Promise<CacheEntry<T> | null> {\n    const stored = await this.inner.get(key)\n    if (!stored) return null\n    const value = this.decrypt(stored.value)\n    return {\n      key: stored.key,\n      value,\n      createdAt: stored.createdAt,\n      expiresAt: stored.expiresAt,\n      metadata: stored.metadata,\n    }\n  }\n\n  async set(key: string, entry: CacheEntry<T>, ttl?: number): Promise<void> {\n    const stored: CacheEntry<EncryptedBlob> = {\n      key: entry.key,\n      value: this.encrypt(entry.value),\n      createdAt: entry.createdAt,\n      expiresAt: entry.expiresAt,\n      metadata: entry.metadata,\n    }\n    await this.inner.set(key, stored, ttl)\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.inner.delete(key)\n  }\n\n  async clear(): Promise<void> {\n    await this.inner.clear()\n  }\n\n  async has(key: string): Promise<boolean> {\n    return this.inner.has(key)\n  }\n\n  async stats(): Promise<AdapterStats> {\n    return this.inner.stats()\n  }\n\n  // --- crypto --------------------------------------------------------------\n\n  private encrypt(value: T): EncryptedBlob {\n    const iv = randomBytes(IV_BYTES)\n    const cipher = createCipheriv(ALGO, this.key, iv)\n    const plaintext = this.serializer.serialize(value)\n    const data = Buffer.concat([cipher.update(plaintext), cipher.final()])\n    const tag = cipher.getAuthTag()\n    return { v: 1, iv: iv.toString('base64'), tag: tag.toString('base64'), data: data.toString('base64') }\n  }\n\n  private decrypt(blob: EncryptedBlob): T {\n    try {\n      const decipher = createDecipheriv(ALGO, this.key, Buffer.from(blob.iv, 'base64'))\n      decipher.setAuthTag(Buffer.from(blob.tag, 'base64'))\n      const plaintext = Buffer.concat([\n        decipher.update(Buffer.from(blob.data, 'base64')),\n        decipher.final(),\n      ])\n      return this.serializer.deserialize<T>(plaintext)\n    } catch (cause) {\n      throw new CacheAdapterError(\n        'Failed to decrypt cache entry (wrong key or tampered data)',\n        { cause },\n      )\n    }\n  }\n}\n","import { randomBytes, scryptSync } from 'node:crypto'\nimport { ValidationError } from '@nodellmcache/core'\n\n/** AES-256 needs a 32-byte key. */\nexport const KEY_BYTES = 32\n\n/** Generates a fresh random 32-byte AES-256 key. Persist it somewhere safe. */\nexport function generateKey(): Buffer {\n  return randomBytes(KEY_BYTES)\n}\n\n/**\n * Derives a 32-byte key from a passphrase and salt using scrypt. Use a stable,\n * unique salt per deployment (store it alongside your config, not the data).\n */\nexport function deriveKey(passphrase: string, salt: string | Buffer): Buffer {\n  return scryptSync(passphrase, salt, KEY_BYTES)\n}\n\n/**\n * Normalizes a key option into a 32-byte Buffer. Accepts a Buffer, a 64-char hex\n * string, or a 44-char base64 string.\n */\nexport function normalizeKey(key: Buffer | string): Buffer {\n  let buf: Buffer\n  if (Buffer.isBuffer(key)) {\n    buf = key\n  } else if (/^[0-9a-fA-F]{64}$/.test(key)) {\n    buf = Buffer.from(key, 'hex')\n  } else {\n    buf = Buffer.from(key, 'base64')\n  }\n  if (buf.length !== KEY_BYTES) {\n    throw new ValidationError(\n      `Encryption key must be ${KEY_BYTES} bytes (got ${buf.length}). ` +\n        'Use generateKey() or deriveKey(passphrase, salt).',\n    )\n  }\n  return buf\n}\n"],"mappings":"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","names":["randomBytes","randomBytes"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@nodellmcache/encryption",
+  "version": "1.0.0",
+  "description": "AES-256-GCM encrypting storage adapter wrapper for NodeLLMCache",
+  "keywords": [
+    "llm",
+    "cache",
+    "encryption",
+    "aes",
+    "gcm",
+    "security",
+    "nodejs"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdmax007/node-llm-cache.git",
+    "directory": "packages/encryption"
+  },
+  "homepage": "https://github.com/mdmax007/node-llm-cache/tree/main/packages/encryption#readme",
+  "bugs": "https://github.com/mdmax007/node-llm-cache/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "@nodellmcache/core": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "@nodellmcache/core": "1.0.0",
+    "@nodellmcache/memory": "1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo \"no lint configured\""
+  }
+}