feat: add CryptoAdapter interface to allow custom encryption/decryption strategies for session data

Author: mingchuno

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Types:** `MongoStore` and option hooks are strongly typed to avoid `any` leaks.
 - **Fixed:** `store.clear()` now uses `deleteMany({})` instead of `collection.drop()`, preserving TTL indexes and treating `NamespaceNotFound` as success so clears are idempotent.
 - **Fixed:** Decryption failures in `get()` now short-circuit after the first callback, preventing double-callback regressions when the crypto secret is wrong.
+- **Added:** Pluggable `cryptoAdapter` interface with helpers `createWebCryptoAdapter` (AES-GCM via Web Crypto API) and `createKrupteinAdapter`; legacy `crypto` options are auto-wrapped and mutually exclusive with `cryptoAdapter` to avoid ambiguity.
 - **Added:** Optional `timestamps` flag to record `createdAt`/`updatedAt` on session documents for auditing while keeping the default schema unchanged.
 
 ## [5.1.0] - 2023-10-14

README.md

@@ -251,17 +251,33 @@ by doing this, setting `touchAfter: 24 * 3600` you are saying to the session be
 
 ## Transparent encryption/decryption of session data
 
-When working with sensitive session data it is [recommended](https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Session_Management_Cheat_Sheet.md) to use encryption
+When working with sensitive session data it is [recommended](https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Session_Management_Cheat_Sheet.md) to use encryption.  
+Use the new `cryptoAdapter` option to plug in your encryption strategy. The preferred helper uses the Web Crypto API (AES-GCM):
+
+```ts
+import MongoStore, { createWebCryptoAdapter } from 'connect-mongo'
 
-```js
 const store = MongoStore.create({
   mongoUrl: 'mongodb://localhost/test-app',
-  crypto: {
-    secret: 'squirrel'
-  }
+  cryptoAdapter: createWebCryptoAdapter({
+    secret: process.env.SESSION_SECRET!,
+  }),
 })
 ```
 
+If you need the legacy [kruptein](https://www.npmjs.com/package/kruptein) behavior, wrap it explicitly:
+
+```ts
+import { createKrupteinAdapter } from 'connect-mongo'
+
+const store = MongoStore.create({
+  mongoUrl: 'mongodb://localhost/test-app',
+  cryptoAdapter: createKrupteinAdapter({ secret: 'squirrel' }),
+})
+```
+
+The legacy `crypto` option still works for backwards compatibility; it is automatically wrapped into a kruptein-based adapter. Supplying both `crypto` and `cryptoAdapter` throws an error so it is clear which path is used.
+
 ## Options
 
 ### Connection-related options (required)
@@ -291,11 +307,14 @@ One of the following options should be provided. If more than one option are pro
 |`unserialize`||Custom hook for unserializing sessions from MongoDB. This can be used in scenarios where you need to support different types of serializations (e.g., objects and JSON strings) or need to modify the session before using it in your app.|
 |`writeOperationOptions`||Options object to pass to every MongoDB write operation call that supports it (e.g. `update`, `remove`). Useful for adjusting the write concern. Only exception: If `autoRemove` is set to `'interval'`, the write concern from the `writeOperationOptions` object will get overwritten.|
 |`transformId`||Transform original `sessionId` in whatever you want to use as storage key.|
+|`cryptoAdapter`||Preferred hook for encrypting/decrypting session payloads. Accepts any object with async `encrypt`/`decrypt` functions; helpers `createWebCryptoAdapter` (AES-GCM via Web Crypto API) and `createKrupteinAdapter` are provided.|
 |`crypto`||Crypto related options. See below.|
 
 If you enable `timestamps`, each session document will include `createdAt` (first insert) and `updatedAt` (every subsequent `set`/`touch`) fields. These fields are informational only and do not change TTL behavior.
 
-### Crypto-related options
+### Crypto-related options (legacy)
+
+Prefer `cryptoAdapter` for new integrations. The legacy `crypto` options are wrapped internally into a kruptein adapter to preserve backwards compatibility:
 
 |Option|Default|Description|
 |------|:-----:|-----------|

ava.config.mjs

@@ -2,7 +2,7 @@ export default {
   files: [
     'src/**/*.{test,spec}.ts'
   ],
-  failFast: true,
+  failFast: false,
   typescript: {
     // map TS paths -> compiled JS paths
     rewritePaths: {

docs/PLANS.md

@@ -6,6 +6,8 @@
   - Align session TTL math with express-session: prefer `cookie.maxAge`, then `cookie.expires`, then `ttl` in both `set()` and `touch()` so rolling sessions retain their intended lifetime.
   - Avoid closing user-supplied MongoClient instances in `close()`; only shut down clients created by the store and always clear timers.
   - [done 2025-11-25] Add optional createdAt/updatedAt timestamps on session documents, disabled by default.
+  - [started 2025-11-30] Add CryptoAdapter interface for pluggable encryption (wrap legacy crypto option, prefer Web Crypto helper, document usage, add tests).
+  - [done 2025-11-30] Rewrite decrypt failure callback test for cryptoAdapter (agent).
 
 - Tooling & CI
   - Rework integration helpers: replace the broken `check-cli`/`diff-integration-tests`, document a safe reset workflow, and migrate `test:integration` to mongodb-memory-server.

package.json

@@ -136,10 +136,10 @@
     "all": true,
     "skipFull": false,
     "check-coverage": true,
-    "branches": 75,
-    "functions": 70,
-    "lines": 80,
-    "statements": 80
+    "branches": 85,
+    "functions": 85,
+    "lines": 85,
+    "statements": 85
   },
   "lint-staged": {
     "**/*.{ts,js}": [

src/index.ts

@@ -1,4 +1,11 @@
 import MongoStore from './lib/MongoStore.js'
+export {
+  createKrupteinAdapter,
+  createWebCryptoAdapter,
+  type CryptoAdapter,
+  type CryptoOptions,
+  type WebCryptoAdapterOptions,
+} from './lib/cryptoAdapters.js'
 
 export default MongoStore
 export { MongoStore }

src/lib/MongoStore.spec.ts

@@ -2,7 +2,11 @@ import test from 'ava'
 import { SessionData } from 'express-session'
 import { MongoClient } from 'mongodb'
 
-import MongoStore from './MongoStore.js'
+import MongoStore, {
+  createWebCryptoAdapter,
+  createKrupteinAdapter,
+  type CryptoAdapter,
+} from './MongoStore.js'
 import {
   createStoreHelper,
   makeData,
@@ -296,15 +300,26 @@ test.serial('clear preserves TTL index and is idempotent', async (t) => {
 })
 
 test.serial('decrypt failure only calls callback once', async (t) => {
-  ;({ store, storePromise } = createStoreHelper({
-    crypto: {
-      secret: 'right-secret',
+  let secret = 'right-secret'
+  const adapter: CryptoAdapter = {
+    async encrypt(plaintext) {
+      return `${secret}:${plaintext}`
     },
-  }))
+    async decrypt(ciphertext) {
+      const prefix = `${secret}:`
+      if (!ciphertext.startsWith(prefix)) {
+        throw new Error('bad secret')
+      }
+      return ciphertext.slice(prefix.length)
+    },
+  }
+
+  ;({ store, storePromise } = createStoreHelper({ cryptoAdapter: adapter }))
   const sid = 'decrypt-failure'
   await storePromise.set(sid, makeData())
+
   // Tamper with the secret so decryption fails
-  ;(store as any).options.crypto.secret = 'wrong-secret'
+  secret = 'wrong-secret'
 
   await new Promise<void>((resolve) => {
     let calls = 0
@@ -388,10 +403,10 @@ test.serial(
   }
 )
 
-test.serial('test destory event', async (t) => {
+test.serial('test destroy event', async (t) => {
   ;({ store, storePromise } = createStoreHelper())
   const orgSession = makeData()
-  const sid = 'test-destory-event'
+  const sid = 'test-destroy-event'
 
   const waitForDestroy = new Promise<void>((resolve, reject) => {
     store.once('destroy', (sessionId: string) => {
@@ -618,6 +633,206 @@ test.serial(
   }
 )
 
+test.serial('cryptoAdapter conflicts with legacy crypto option', (t) => {
+  const adapter: CryptoAdapter = {
+    encrypt: async (payload) => payload,
+    decrypt: async (payload) => payload,
+  }
+  t.throws(
+    () =>
+      MongoStore.create({
+        mongoUrl: 'mongodb://root:example@127.0.0.1:27017',
+        crypto: { secret: 'secret' },
+        cryptoAdapter: adapter,
+      }),
+    { message: /legacy crypto option or cryptoAdapter/ }
+  )
+})
+
+test.serial('custom cryptoAdapter roundtrips session data', async (t) => {
+  const adapter: CryptoAdapter = {
+    encrypt: async (payload) => `enc:${payload}`,
+    decrypt: async (payload) => payload.replace(/^enc:/, ''),
+  }
+  ;({ store, storePromise } = createStoreHelper({
+    cryptoAdapter: adapter,
+    collectionName: 'custom-adapter',
+  }))
+  const sid = 'adapter-roundtrip'
+  const original = makeData()
+  await storePromise.set(sid, original)
+  const session = await storePromise.get(sid)
+  t.deepEqual(session, JSON.parse(JSON.stringify(original)))
+})
+
+test.serial(
+  'kruptein adapter helper merges defaults and works with only secret',
+  async (t) => {
+    ;({ store, storePromise } = createStoreHelper({
+      cryptoAdapter: createKrupteinAdapter({ secret: 'secret' }),
+      collectionName: 'kruptein-adapter',
+    }))
+    const sid = 'kruptein-adapter'
+    const original = makeData()
+    await storePromise.set(sid, original)
+    const session = await storePromise.get(sid)
+    t.deepEqual(session, JSON.parse(JSON.stringify(original)))
+  }
+)
+
+test.serial('web crypto adapter encrypts and decrypts sessions', async (t) => {
+  const adapter = createWebCryptoAdapter({ secret: 'sup3r-secr3t' })
+  ;({ store, storePromise } = createStoreHelper({
+    cryptoAdapter: adapter,
+    collectionName: 'webcrypto-adapter',
+  }))
+  const sid = 'webcrypto-session'
+  const original = makeData()
+  await storePromise.set(sid, original)
+  const session = await storePromise.get(sid)
+  t.deepEqual(session, JSON.parse(JSON.stringify(original)))
+})
+
+test.serial('web crypto adapter supports base64url encoding', async (t) => {
+  const adapter = createWebCryptoAdapter({
+    secret: 'sup3r-secr3t',
+    encoding: 'base64url',
+  })
+  ;({ store, storePromise } = createStoreHelper({
+    cryptoAdapter: adapter,
+    collectionName: 'webcrypto-base64url',
+  }))
+  const sid = 'webcrypto-base64url'
+  const original = makeData()
+  await storePromise.set(sid, original)
+  const session = await storePromise.get(sid)
+  t.deepEqual(session, JSON.parse(JSON.stringify(original)))
+})
+
+test.serial('web crypto adapter supports hex encoding', async (t) => {
+  const adapter = createWebCryptoAdapter({
+    secret: 'sup3r-secr3t',
+    encoding: 'hex',
+  })
+  ;({ store, storePromise } = createStoreHelper({
+    cryptoAdapter: adapter,
+    collectionName: 'webcrypto-hex',
+  }))
+  const sid = 'webcrypto-hex'
+  const original = makeData()
+  await storePromise.set(sid, original)
+  const session = await storePromise.get(sid)
+  t.deepEqual(session, JSON.parse(JSON.stringify(original)))
+})
+
+test.serial(
+  'web crypto adapter derives key with PBKDF2 salt/iterations overrides',
+  async (t) => {
+    const adapter = createWebCryptoAdapter({
+      secret: 'sup3r-secr3t',
+      encoding: 'base64url',
+      salt: 'custom-salt',
+      iterations: 100_000,
+    })
+    ;({ store, storePromise } = createStoreHelper({
+      cryptoAdapter: adapter,
+      collectionName: 'webcrypto-pbkdf2',
+    }))
+    const sid = 'webcrypto-pbkdf2'
+    const original = makeData()
+    await storePromise.set(sid, original)
+    const session = await storePromise.get(sid)
+    t.deepEqual(session, JSON.parse(JSON.stringify(original)))
+  }
+)
+
+test.serial('web crypto adapter supports AES-CBC algorithm', async (t) => {
+  const adapter = createWebCryptoAdapter({
+    secret: 'sup3r-secr3t',
+    algorithm: 'AES-CBC',
+    ivLength: 16,
+  })
+  ;({ store, storePromise } = createStoreHelper({
+    cryptoAdapter: adapter,
+    collectionName: 'webcrypto-aes-cbc',
+  }))
+  const sid = 'webcrypto-aes-cbc'
+  const original = makeData()
+  await storePromise.set(sid, original)
+  const session = await storePromise.get(sid)
+  t.deepEqual(session, JSON.parse(JSON.stringify(original)))
+})
+
+test.serial(
+  'cryptoAdapter works with default stringify (string payload)',
+  async (t) => {
+    const adapter: CryptoAdapter = {
+      encrypt: async (payload) => `enc:${payload}`,
+      decrypt: async (payload) => payload.replace(/^enc:/, ''),
+    }
+    ;({ store, storePromise } = createStoreHelper({
+      cryptoAdapter: adapter,
+      collectionName: 'crypto-default-stringify',
+    }))
+    const sid = 'crypto-default-stringify'
+    const original = makeData()
+    await storePromise.set(sid, original)
+    const session = await storePromise.get(sid)
+    t.deepEqual(session, JSON.parse(JSON.stringify(original)))
+  }
+)
+
+test.serial(
+  'cryptoAdapter works with stringify=false (raw object path)',
+  async (t) => {
+    const adapter: CryptoAdapter = {
+      encrypt: async (payload) => `enc:${payload}`,
+      decrypt: async (payload) => payload.replace(/^enc:/, ''),
+    }
+    ;({ store, storePromise } = createStoreHelper({
+      cryptoAdapter: adapter,
+      stringify: false,
+      collectionName: 'crypto-stringify-false',
+    }))
+    const sid = 'crypto-stringify-false'
+    const original = makeDataNoCookie()
+    // @ts-ignore
+    await storePromise.set(sid, original)
+    const session = await storePromise.get(sid)
+    t.deepEqual(session, original)
+  }
+)
+
+test.serial(
+  'cryptoAdapter works with custom serialize/unserialize functions',
+  async (t) => {
+    const adapter: CryptoAdapter = {
+      encrypt: async (payload) => `enc:${payload}`,
+      decrypt: async (payload) => payload.replace(/^enc:/, ''),
+    }
+    const serialize = (session: SessionData) => ({
+      ...session,
+      marker: true,
+    })
+    const unserialize = (payload: unknown) => {
+      const { marker, ...rest } = payload as Record<string, unknown>
+      return rest as SessionData
+    }
+
+    ;({ store, storePromise } = createStoreHelper({
+      cryptoAdapter: adapter,
+      serialize,
+      unserialize,
+      collectionName: 'crypto-custom-serialize',
+    }))
+    const sid = 'crypto-custom-serialize'
+    const original = makeData()
+    await storePromise.set(sid, original)
+    const session = await storePromise.get(sid)
+    t.deepEqual(session, JSON.parse(JSON.stringify(original)))
+  }
+)
+
 test.serial('basic operation flow with crypto', async (t) => {
   ;({ store, storePromise } = createStoreHelper({
     crypto: { secret: 'secret' },