feat: add optional session timestamps for auditing

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:** 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

@@ -285,13 +285,16 @@ One of the following options should be provided. If more than one option are pro
 |`autoRemove`|`'native'`|Behavior for removing expired sessions. Possible values: `'native'`, `'interval'` and `'disabled'`.|
 |`autoRemoveInterval`|`10`|Interval (in minutes) used when `autoRemove` option is set to `interval`.|
 |`touchAfter`|`0`|Interval (in seconds) between session updates.|
+|`timestamps`|`false`|When `true`, stores `createdAt` (on insert) and `updatedAt` (on every write/touch) fields on each session document for auditing. Disabled by default to preserve existing schemas.|
 |`stringify`|`true`|If `true`, connect-mongo will serialize sessions using `JSON.stringify` before setting them, and deserialize them with `JSON.parse` when getting them. This is useful if you are using types that MongoDB doesn't support.|
 |`serialize`||Custom hook for serializing sessions to MongoDB. This is helpful if you need to modify the session before writing it out.|
 |`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.|
 |`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
 
 |Option|Default|Description|

docs/PLANS.md

@@ -5,6 +5,7 @@
 - Runtime & API Quality
   - 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.
 
 - 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.