@web-ts-toolkit/express-oidc-vault-mongodb-store 0.42.2 → 0.47.1

package/README.md

@@ -64,7 +64,10 @@ app.use(
 const server = app.listen(3000);
 
 process.once('SIGTERM', async () => {
-  server.close();
+  await new Promise<void>((resolve, reject) => {
+    server.close((error) => (error ? reject(error) : resolve()));
+  });
+  // Also settle any store work started outside HTTP requests before closing.
   await mongo.close();
 });
 ```
@@ -92,21 +95,47 @@ const storeProvider = createMongoOidcVaultStore({
 });
 ```
 
-## Notes
+## Startup And Client Ownership
 
 - use MongoDB when your team already standardizes on Mongo and you want the auth vault data in the same operational platform
 - the provider uses separate collections for authorization transactions, exchange codes, sessions, backchannel logout token JTIs, and rotated-session aliases
-- TTL indexes are created on expiring records; authorization transactions, exchange codes, backchannel logout token JTIs, and rotated-session aliases are also checked for expiration during relevant reads or consumes so behavior does not depend only on Mongo's background TTL monitor timing
-- session rotation requires MongoDB transactions; use a replica set or sharded deployment because standalone servers fail closed instead of using non-atomic multi-write rotation
+- TTL indexes are created on expiring records; sessions, authorization transactions, exchange codes, backchannel logout token JTIs, and rotated-session aliases are also checked for expiration during relevant reads or consumes (`expiresAt <= now()` is expired), so behavior does not depend only on Mongo's background TTL monitor timing
+- session rotation and inactive-lineage alias cleanup require MongoDB transactions; use a replica set or sharded deployment because standalone servers fail readiness instead of using non-atomic multi-write fallbacks
 - startup readiness creates required indexes and verifies transaction-capable topology; connect the MongoDB client, create the store, await `storeProvider.ready()`, then accept traffic
 - session deletion by subject or provider session ID uses compound scoped indexes on the identity field plus `provider.issuer` and `provider.clientId`; these replace single-field identity indexes because the leading key still supports identity-only deletes while scoped logout deletes avoid scanning every repeated identity across tenants
 - the application owns MongoDB client shutdown; this package does not close the client
-- rotation requires a distinct unused target session ID; missing-source, same-ID, and existing-target rotation conflicts throw `OidcVaultStoreConflictError` without changing source or target records
-- rotated-session aliases are retained only long enough to bridge in-flight refresh/logout requests; sessions without explicit expiry use a finite 5 minute alias retention window by default, configurable with `rotatedSessionAliasRetentionMs`
-- deleting by current session ID, stale rotated ID, logical session ID, subject, or provider session ID removes aliases for the affected logical sessions
-- `createAuthorizationTransaction`, `createExchangeCode`, and `createSession` are upserts; metadata should be JSON-compatible for portability across store providers
+
+Drain HTTP requests and any other in-flight store operations before closing the caller-owned `MongoClient`. The store has no shutdown method or background cleanup timer. Its explicit transaction sessions are ended in `finally` on success and failure; MongoDB's TTL monitor belongs to the server. Shared state and durability depend on your deployment, replication and backup configuration.
+
+## Rotation Aliases And Lifetime
+
+- rotation requires a distinct unused target session ID; missing-source, same-ID, existing-target, changed-source, and expired-source rotation conflicts throw `OidcVaultStoreConflictError` without changing source or target records (the source document is re-read inside the transaction and must still match the generation seen before the transaction, including liveness, so a same-ID replacement committed after the rotation's source read aborts instead of being consumed)
+- an expired target document still present before TTL cleanup can conflict; use fresh target IDs for portable rotation
+- each alias takes its immediate successor's `expiresAt`, not the source's; later rotations never extend it. With `A -> B (expiresAt=T1) -> C (expiresAt=T2)`, A stops revoking at T1 even if T2 is later or absent. B uses C's deadline. `getSession(A)` returns `null`: aliases are only revocation handles
+- without successor `expiresAt`, MongoDB uses `now() + rotatedSessionAliasRetentionMs` (default five minutes, finite positive duration). Memory/Redis instead have no alias time limit and can accumulate aliases for a long-lived lineage. Finite session expiry is the portable policy; core refresh preserves it
+- omitting the next logical ID preserves the source lineage. With `A/L1 -> B/L1 -> C/L2`, the new B alias revokes L2; earlier A keeps L1 and its original deadline, never C. MongoDB does not eagerly retire L1 aliases merely because rotation/upsert moves its last member elsewhere (memory does); they can remain until expiry or explicit lineage cleanup. Use distinct logical IDs for unrelated login families rather than relying on retained handles disappearing on reuse
+- after an alias expires, use the live ID or logical/subject/provider-session deletion, not that stale handle
+
+## Deletion, Counts And Concurrency
+
+- deleting a live public ID removes that record; deleting an unexpired alias revokes its logical lineage. Logical deletion and aliases have no issuer/client filter. Subject/provider-session object inputs match each supplied `issuer` and `clientId`; string inputs omit both filters and match across providers
+- deleting by current session ID, subject, or provider session ID preserves unexpired aliases while any live member of the logical session survives, including another issuer/client scope; a stale rotated ID still revokes its logical lineage
+- after session deletion commits, alias cleanup checks live membership and removes inactive-lineage aliases in a snapshot transaction. Concurrently inserted rotation aliases are outside that snapshot; updating an existing alias conflicts and retries cleanup, including identical lineage/expiry reuse (an internal alias revision makes every rotation a write). Cleanup sessions are closed on success and failure. This is not a global logout snapshot: later arrivals can survive, and cleanup failure can reject after sessions were already deleted
+- compatibility: scoped/direct deletion no longer discards the surviving lineage's revocation handles. Alias deadlines and the create-ID-reuse variation below are unchanged. Cleanup still materializes affected logical IDs and surviving members; very large `$in` batches remain a scale-dependent limit
+
+Subject/provider-session deletion repeats find/delete/cleanup passes until a find observes no matches. It can catch a rotation or matching arrival on a later pass, but arrivals after the final query can survive; continuously arriving matches can prolong the call without a fixed pass bound. Logical deletion uses one `deleteMany` followed by alias cleanup. Counts sum MongoDB `deletedCount` for primary session documents, possibly including expired documents awaiting TTL cleanup; alias removal is never counted. Memory excludes expired sessions, and Redis counts primary deletions from its cursor traversal. Counts are not a global remaining-session census or a cross-provider live-user metric. An error can follow partial/committed deletion. Vault deletion does not revoke outstanding stateless access tokens or call upstream logout.
+
+## Creation And Data Ownership
+
+- `createAuthorizationTransaction`, `createExchangeCode`, and `createSession` are upserts; a `createSession` replacement takes over the session ID with its own subject/logical/provider-session scope
+- unlike memory/Redis, a `createSession` replacement does not clear a stale rotation alias row held under the reused ID; that row can remain until expiry or lineage cleanup. After removing the replacement, another delete of that ID can invoke its former lineage. Portable callers must create sessions with a fresh unused ID and handle `OidcVaultStoreConflictError` (reusing a live ID replaces here but rejects on Redis; concurrent reuse also races rotation source checks)
+- portable data consists of strings, finite numbers, booleans, null, arrays, and plain objects; exclude cycles, custom prototypes/serializers, functions, symbols, and undefined properties. This applies to nested provider/user/metadata fields, not just top-level metadata
+- portable plain-object/array inputs are snapshotted at invocation, before readiness or other asynchronous work; later caller mutation cannot change session/transaction data, rotation retries, JTI identity, or deletion scope. Returned session containers are independent from caller input, including nested provider/user/metadata arrays
+- compatibility: ownership snapshots do not JSON-round-trip values or flatten BSON wrappers. MongoDB's native serialization still applies outside the portable subset (including Dates, BSON values, undefined properties and custom `toBSON` hooks); opaque non-plain objects are not recursively copied and have no portable mutation-isolation guarantee
 - backchannel logout token JTI records are consumed only when `expiresAt` is finite and greater than the store clock at consume time
 
+Authorization transactions and exchange codes are atomically consumed once by state/code, returning `null` when absent or expired. JTI reservations return `false` for duplicate, past, exact-boundary, NaN, or infinite expiries. Core passes an opaque issuer/client/JTI-namespaced key; the store uses it verbatim. Session creation defaults omitted logical ID to session ID and omitted timestamps to the store clock.
+
 ## Security And Operations
 
 Session records contain refresh tokens, ID tokens, access tokens, and related bearer-equivalent secrets. Treat the MongoDB database and every backup, log, trace, metric label, and export path that can expose these records as sensitive auth infrastructure.
@@ -120,6 +149,8 @@ Recommended controls:
 - define an explicit data-retention policy for sessions, aliases, authorization transactions, exchange codes, and consumed logout JTIs
 - close the caller-owned `MongoClient` from application shutdown code; this package never closes it
 
+The store does not emit record/error logs or sanitize arbitrary MongoDB/client exceptions for application logging. Use fixed operation names and allowlisted diagnostic categories; do not log whole errors, connection URLs, session IDs, state/PKCE values, exchange codes or token-valued labels. A private error observer is not an automatic redaction boundary.
+
 This package does not implement application-level field encryption or client-side field-level encryption. Add those controls at your MongoDB/client configuration layer if your deployment requires them.
 
 ## Scoped Deletion Indexes
@@ -136,6 +167,8 @@ The package intentionally creates one compound index per public scoped identity
 
 ## Main Exports
 
+Use named imports from the package root; there is no default export or public subpath API. Use Node.js `>=22.12.0` for the core dependency's CJS/ESM runtime support. TypeScript apps also need `@types/node` and `@types/express`.
+
 - `createMongoOidcVaultStore(...)`
 - `type OidcVaultMongoStoreProvider`
 - `type MongoOidcVaultStoreOptions`

package/index.js

@@ -27,6 +27,7 @@ module.exports = __toCommonJS(index_exports);
 
 // src/store.ts
 var import_express_oidc_vault = require("@web-ts-toolkit/express-oidc-vault");
+var import_node_util = require("util");
 
 // src/documents.ts
 var sessionToDocument = (session) => ({
@@ -175,10 +176,30 @@ var ensureStoreIndexes = async (collections) => {
 };
 
 // src/store.ts
-var toSubjectDeleteInput = (input) => typeof input === "string" ? { subject: input } : input;
-var toProviderSessionDeleteInput = (input) => typeof input === "string" ? { providerSessionId: input } : input;
-var toLogicalSessionDeleteInput = (input) => typeof input === "string" ? { logicalSessionId: input } : input;
+var snapshotInput = (input, seen = /* @__PURE__ */ new WeakMap()) => {
+  if (input === null || typeof input !== "object") return input;
+  const prototype = Object.getPrototypeOf(input);
+  if (!Array.isArray(input) && prototype !== Object.prototype && prototype !== null) return input;
+  if (seen.has(input)) return seen.get(input);
+  const copy = Array.isArray(input) ? new Array(input.length) : Object.create(prototype);
+  seen.set(input, copy);
+  for (const key of Reflect.ownKeys(input)) {
+    if (Object.prototype.propertyIsEnumerable.call(input, key)) {
+      Object.defineProperty(copy, key, {
+        value: snapshotInput(Reflect.get(input, key), seen),
+        enumerable: true,
+        configurable: true,
+        writable: true
+      });
+    }
+  }
+  return copy;
+};
+var toSubjectDeleteInput = (input) => typeof input === "string" ? { subject: input } : { ...input };
+var toProviderSessionDeleteInput = (input) => typeof input === "string" ? { providerSessionId: input } : { ...input };
+var toLogicalSessionDeleteInput = (input) => typeof input === "string" ? { logicalSessionId: input } : { ...input };
 var isDuplicateKeyError = (error) => typeof error === "object" && error !== null && "code" in error && error.code === 11e3;
+var isSameSessionDocumentGeneration = (current, expected) => current._id === expected._id && (current.logicalSessionId ?? current._id) === (expected.logicalSessionId ?? expected._id) && current.subject === expected.subject && current.providerSessionId === expected.providerSessionId && (0, import_node_util.isDeepStrictEqual)(current.provider, expected.provider) && current.refreshToken === expected.refreshToken && current.idToken === expected.idToken && current.accessToken === expected.accessToken && current.scope === expected.scope && (current.expiresAt?.getTime() ?? null) === (expected.expiresAt?.getTime() ?? null) && current.createdAt === expected.createdAt && current.updatedAt === expected.updatedAt && (0, import_node_util.isDeepStrictEqual)(current.user, expected.user) && (0, import_node_util.isDeepStrictEqual)(current.metadata, expected.metadata);
 var MongoOidcVaultStore = class {
   constructor(options) {
     const collectionNames = resolveCollectionNames(options);
@@ -207,6 +228,7 @@ var MongoOidcVaultStore = class {
     await this.waitUntilReady();
   }
   async createAuthorizationTransaction(input) {
+    input = snapshotInput({ ...input });
     await this.waitUntilReady();
     await this.authorizationTransactions.replaceOne({ _id: input.state }, authorizationTransactionToDocument(input), {
       upsert: true
@@ -221,6 +243,7 @@ var MongoOidcVaultStore = class {
     return authorizationDocumentToRecord(record);
   }
   async createExchangeCode(input) {
+    input = { ...input };
     await this.waitUntilReady();
     await this.exchangeCodes.replaceOne({ _id: input.code }, exchangeCodeToDocument(input), { upsert: true });
   }
@@ -233,6 +256,7 @@ var MongoOidcVaultStore = class {
     return exchangeDocumentToRecord(record);
   }
   async createSession(input) {
+    input = snapshotInput({ ...input });
     await this.waitUntilReady();
     const timestamp = this.now();
     const session = {
@@ -253,6 +277,7 @@ var MongoOidcVaultStore = class {
     return documentToSession(session);
   }
   async rotateSession(input) {
+    input = { sessionId: input.sessionId, nextSession: snapshotInput({ ...input.nextSession }) };
     await this.waitUntilReady();
     if (input.nextSession.sessionId === input.sessionId) {
       throw new import_express_oidc_vault.OidcVaultStoreConflictError("OIDC vault session rotation target must use a different session ID.");
@@ -273,7 +298,7 @@ var MongoOidcVaultStore = class {
       const logicalSessionId = session.logicalSessionId ?? session._id;
       const result = await this.sessions.deleteOne({ _id: sessionId });
       if (result.deletedCount === 1) {
-        await this.deleteRotatedSessionAliasesByLogicalSessionId(logicalSessionId);
+        await this.deleteAliasesForInactiveLogicalSessions([logicalSessionId]);
         return;
       }
       const alias2 = await this.rotatedSessionAliases.findOne({ _id: sessionId });
@@ -288,13 +313,14 @@ var MongoOidcVaultStore = class {
     }
   }
   async deleteSessionsByLogicalSessionId(input) {
-    await this.waitUntilReady();
     const resolved = toLogicalSessionDeleteInput(input);
+    await this.waitUntilReady();
     const result = await this.sessions.deleteMany({ logicalSessionId: resolved.logicalSessionId });
-    await this.deleteRotatedSessionAliasesByLogicalSessionId(resolved.logicalSessionId);
+    await this.deleteAliasesForInactiveLogicalSessions([resolved.logicalSessionId]);
     return result.deletedCount;
   }
   async consumeBackchannelLogoutTokenJti(input) {
+    input = { ...input };
     await this.waitUntilReady();
     const now = this.now();
     if (!Number.isFinite(input.expiresAt) || input.expiresAt <= now) {
@@ -327,8 +353,8 @@ var MongoOidcVaultStore = class {
     }
   }
   async deleteSessionsBySubject(input) {
-    await this.waitUntilReady();
     const resolved = toSubjectDeleteInput(input);
+    await this.waitUntilReady();
     const filter = { subject: resolved.subject };
     if (resolved.issuer !== void 0) {
       filter["provider.issuer"] = resolved.issuer;
@@ -340,8 +366,8 @@ var MongoOidcVaultStore = class {
     return result.deletedCount;
   }
   async deleteSessionsByProviderSessionId(input) {
-    await this.waitUntilReady();
     const resolved = toProviderSessionDeleteInput(input);
+    await this.waitUntilReady();
     const filter = { providerSessionId: resolved.providerSessionId };
     if (resolved.issuer !== void 0) {
       filter["provider.issuer"] = resolved.issuer;
@@ -371,10 +397,18 @@ var MongoOidcVaultStore = class {
     }
   }
   async rotateSessionWithTransaction(input) {
+    const { previous, nextSession } = await this.normalizeRotatedSession(input);
+    const expectedSource = sessionToDocument(previous);
     const session = this.db.client.startSession();
-    const nextSession = await this.normalizeRotatedSession(input);
     try {
       await session.withTransaction(async () => {
+        const current = await this.sessions.findOne({ _id: input.sessionId }, { session });
+        if (!current || isExpired(current, this.now())) {
+          throw new import_express_oidc_vault.OidcVaultStoreConflictError("OIDC vault session no longer exists for rotation.");
+        }
+        if (!isSameSessionDocumentGeneration(current, expectedSource)) {
+          throw new import_express_oidc_vault.OidcVaultStoreConflictError("OIDC vault session changed before rotation could commit.");
+        }
         await this.sessions.insertOne(sessionToDocument(nextSession), { session });
         const deleteResult = await this.sessions.deleteOne({ _id: input.sessionId }, { session });
         if (deleteResult.deletedCount !== 1) {
@@ -397,7 +431,10 @@ var MongoOidcVaultStore = class {
         $set: {
           logicalSessionId,
           expiresAt: this.getRotatedSessionAliasExpiresAt(nextSession, now)
-        }
+        },
+        // A no-op alias update would not conflict with an older cleanup
+        // snapshot. Every rotation must write, even with identical values.
+        $inc: { revision: 1 }
       },
       { upsert: true, session }
     );
@@ -408,8 +445,11 @@ var MongoOidcVaultStore = class {
       throw new import_express_oidc_vault.OidcVaultStoreConflictError("OIDC vault session no longer exists for rotation.");
     }
     return {
-      ...input.nextSession,
-      logicalSessionId: input.nextSession.logicalSessionId ?? previous.logicalSessionId ?? input.sessionId
+      previous,
+      nextSession: {
+        ...input.nextSession,
+        logicalSessionId: input.nextSession.logicalSessionId ?? previous.logicalSessionId ?? input.sessionId
+      }
     };
   }
   async deleteSessionsAndAliasesByFilter(filter) {
@@ -425,7 +465,7 @@ var MongoOidcVaultStore = class {
       }
       const result = await this.sessions.deleteMany(filter);
       deletedCount += result.deletedCount;
-      await this.rotatedSessionAliases.deleteMany({ logicalSessionId: { $in: logicalSessionIds } });
+      await this.deleteAliasesForInactiveLogicalSessions(logicalSessionIds);
     }
   }
   getRotatedSessionAliasExpiresAt(nextSession, now) {
@@ -433,8 +473,36 @@ var MongoOidcVaultStore = class {
       typeof nextSession.expiresAt === "number" ? nextSession.expiresAt : now + this.rotatedSessionAliasRetentionMs
     );
   }
-  async deleteRotatedSessionAliasesByLogicalSessionId(logicalSessionId) {
-    await this.rotatedSessionAliases.deleteMany({ logicalSessionId });
+  async deleteAliasesForInactiveLogicalSessions(logicalSessionIds) {
+    const session = this.db.client.startSession();
+    try {
+      await session.withTransaction(
+        async () => {
+          const live = await this.sessions.find(
+            {
+              $and: [
+                {
+                  $or: [
+                    { logicalSessionId: { $in: logicalSessionIds } },
+                    { logicalSessionId: { $exists: false }, _id: { $in: logicalSessionIds } }
+                  ]
+                },
+                { $nor: [{ expiresAt: { $lte: new Date(this.now()) } }] }
+              ]
+            },
+            { session, projection: { _id: 1, logicalSessionId: 1 } }
+          ).toArray();
+          const survivingIds = new Set(live.map((record) => record.logicalSessionId ?? record._id));
+          const inactiveIds = logicalSessionIds.filter((id) => !survivingIds.has(id));
+          if (inactiveIds.length > 0) {
+            await this.rotatedSessionAliases.deleteMany({ logicalSessionId: { $in: inactiveIds } }, { session });
+          }
+        },
+        { readConcern: { level: "snapshot" } }
+      );
+    } finally {
+      await session.endSession();
+    }
   }
   async isExpiredAndCleanup(collection, record) {
     if (!isExpired(record, this.now())) {

package/index.mjs

@@ -2,6 +2,7 @@
 import {
   OidcVaultStoreConflictError
 } from "@web-ts-toolkit/express-oidc-vault";
+import { isDeepStrictEqual } from "util";
 
 // src/documents.ts
 var sessionToDocument = (session) => ({
@@ -150,10 +151,30 @@ var ensureStoreIndexes = async (collections) => {
 };
 
 // src/store.ts
-var toSubjectDeleteInput = (input) => typeof input === "string" ? { subject: input } : input;
-var toProviderSessionDeleteInput = (input) => typeof input === "string" ? { providerSessionId: input } : input;
-var toLogicalSessionDeleteInput = (input) => typeof input === "string" ? { logicalSessionId: input } : input;
+var snapshotInput = (input, seen = /* @__PURE__ */ new WeakMap()) => {
+  if (input === null || typeof input !== "object") return input;
+  const prototype = Object.getPrototypeOf(input);
+  if (!Array.isArray(input) && prototype !== Object.prototype && prototype !== null) return input;
+  if (seen.has(input)) return seen.get(input);
+  const copy = Array.isArray(input) ? new Array(input.length) : Object.create(prototype);
+  seen.set(input, copy);
+  for (const key of Reflect.ownKeys(input)) {
+    if (Object.prototype.propertyIsEnumerable.call(input, key)) {
+      Object.defineProperty(copy, key, {
+        value: snapshotInput(Reflect.get(input, key), seen),
+        enumerable: true,
+        configurable: true,
+        writable: true
+      });
+    }
+  }
+  return copy;
+};
+var toSubjectDeleteInput = (input) => typeof input === "string" ? { subject: input } : { ...input };
+var toProviderSessionDeleteInput = (input) => typeof input === "string" ? { providerSessionId: input } : { ...input };
+var toLogicalSessionDeleteInput = (input) => typeof input === "string" ? { logicalSessionId: input } : { ...input };
 var isDuplicateKeyError = (error) => typeof error === "object" && error !== null && "code" in error && error.code === 11e3;
+var isSameSessionDocumentGeneration = (current, expected) => current._id === expected._id && (current.logicalSessionId ?? current._id) === (expected.logicalSessionId ?? expected._id) && current.subject === expected.subject && current.providerSessionId === expected.providerSessionId && isDeepStrictEqual(current.provider, expected.provider) && current.refreshToken === expected.refreshToken && current.idToken === expected.idToken && current.accessToken === expected.accessToken && current.scope === expected.scope && (current.expiresAt?.getTime() ?? null) === (expected.expiresAt?.getTime() ?? null) && current.createdAt === expected.createdAt && current.updatedAt === expected.updatedAt && isDeepStrictEqual(current.user, expected.user) && isDeepStrictEqual(current.metadata, expected.metadata);
 var MongoOidcVaultStore = class {
   constructor(options) {
     const collectionNames = resolveCollectionNames(options);
@@ -182,6 +203,7 @@ var MongoOidcVaultStore = class {
     await this.waitUntilReady();
   }
   async createAuthorizationTransaction(input) {
+    input = snapshotInput({ ...input });
     await this.waitUntilReady();
     await this.authorizationTransactions.replaceOne({ _id: input.state }, authorizationTransactionToDocument(input), {
       upsert: true
@@ -196,6 +218,7 @@ var MongoOidcVaultStore = class {
     return authorizationDocumentToRecord(record);
   }
   async createExchangeCode(input) {
+    input = { ...input };
     await this.waitUntilReady();
     await this.exchangeCodes.replaceOne({ _id: input.code }, exchangeCodeToDocument(input), { upsert: true });
   }
@@ -208,6 +231,7 @@ var MongoOidcVaultStore = class {
     return exchangeDocumentToRecord(record);
   }
   async createSession(input) {
+    input = snapshotInput({ ...input });
     await this.waitUntilReady();
     const timestamp = this.now();
     const session = {
@@ -228,6 +252,7 @@ var MongoOidcVaultStore = class {
     return documentToSession(session);
   }
   async rotateSession(input) {
+    input = { sessionId: input.sessionId, nextSession: snapshotInput({ ...input.nextSession }) };
     await this.waitUntilReady();
     if (input.nextSession.sessionId === input.sessionId) {
       throw new OidcVaultStoreConflictError("OIDC vault session rotation target must use a different session ID.");
@@ -248,7 +273,7 @@ var MongoOidcVaultStore = class {
       const logicalSessionId = session.logicalSessionId ?? session._id;
       const result = await this.sessions.deleteOne({ _id: sessionId });
       if (result.deletedCount === 1) {
-        await this.deleteRotatedSessionAliasesByLogicalSessionId(logicalSessionId);
+        await this.deleteAliasesForInactiveLogicalSessions([logicalSessionId]);
         return;
       }
       const alias2 = await this.rotatedSessionAliases.findOne({ _id: sessionId });
@@ -263,13 +288,14 @@ var MongoOidcVaultStore = class {
     }
   }
   async deleteSessionsByLogicalSessionId(input) {
-    await this.waitUntilReady();
     const resolved = toLogicalSessionDeleteInput(input);
+    await this.waitUntilReady();
     const result = await this.sessions.deleteMany({ logicalSessionId: resolved.logicalSessionId });
-    await this.deleteRotatedSessionAliasesByLogicalSessionId(resolved.logicalSessionId);
+    await this.deleteAliasesForInactiveLogicalSessions([resolved.logicalSessionId]);
     return result.deletedCount;
   }
   async consumeBackchannelLogoutTokenJti(input) {
+    input = { ...input };
     await this.waitUntilReady();
     const now = this.now();
     if (!Number.isFinite(input.expiresAt) || input.expiresAt <= now) {
@@ -302,8 +328,8 @@ var MongoOidcVaultStore = class {
     }
   }
   async deleteSessionsBySubject(input) {
-    await this.waitUntilReady();
     const resolved = toSubjectDeleteInput(input);
+    await this.waitUntilReady();
     const filter = { subject: resolved.subject };
     if (resolved.issuer !== void 0) {
       filter["provider.issuer"] = resolved.issuer;
@@ -315,8 +341,8 @@ var MongoOidcVaultStore = class {
     return result.deletedCount;
   }
   async deleteSessionsByProviderSessionId(input) {
-    await this.waitUntilReady();
     const resolved = toProviderSessionDeleteInput(input);
+    await this.waitUntilReady();
     const filter = { providerSessionId: resolved.providerSessionId };
     if (resolved.issuer !== void 0) {
       filter["provider.issuer"] = resolved.issuer;
@@ -346,10 +372,18 @@ var MongoOidcVaultStore = class {
     }
   }
   async rotateSessionWithTransaction(input) {
+    const { previous, nextSession } = await this.normalizeRotatedSession(input);
+    const expectedSource = sessionToDocument(previous);
     const session = this.db.client.startSession();
-    const nextSession = await this.normalizeRotatedSession(input);
     try {
       await session.withTransaction(async () => {
+        const current = await this.sessions.findOne({ _id: input.sessionId }, { session });
+        if (!current || isExpired(current, this.now())) {
+          throw new OidcVaultStoreConflictError("OIDC vault session no longer exists for rotation.");
+        }
+        if (!isSameSessionDocumentGeneration(current, expectedSource)) {
+          throw new OidcVaultStoreConflictError("OIDC vault session changed before rotation could commit.");
+        }
         await this.sessions.insertOne(sessionToDocument(nextSession), { session });
         const deleteResult = await this.sessions.deleteOne({ _id: input.sessionId }, { session });
         if (deleteResult.deletedCount !== 1) {
@@ -372,7 +406,10 @@ var MongoOidcVaultStore = class {
         $set: {
           logicalSessionId,
           expiresAt: this.getRotatedSessionAliasExpiresAt(nextSession, now)
-        }
+        },
+        // A no-op alias update would not conflict with an older cleanup
+        // snapshot. Every rotation must write, even with identical values.
+        $inc: { revision: 1 }
       },
       { upsert: true, session }
     );
@@ -383,8 +420,11 @@ var MongoOidcVaultStore = class {
       throw new OidcVaultStoreConflictError("OIDC vault session no longer exists for rotation.");
     }
     return {
-      ...input.nextSession,
-      logicalSessionId: input.nextSession.logicalSessionId ?? previous.logicalSessionId ?? input.sessionId
+      previous,
+      nextSession: {
+        ...input.nextSession,
+        logicalSessionId: input.nextSession.logicalSessionId ?? previous.logicalSessionId ?? input.sessionId
+      }
     };
   }
   async deleteSessionsAndAliasesByFilter(filter) {
@@ -400,7 +440,7 @@ var MongoOidcVaultStore = class {
       }
       const result = await this.sessions.deleteMany(filter);
       deletedCount += result.deletedCount;
-      await this.rotatedSessionAliases.deleteMany({ logicalSessionId: { $in: logicalSessionIds } });
+      await this.deleteAliasesForInactiveLogicalSessions(logicalSessionIds);
     }
   }
   getRotatedSessionAliasExpiresAt(nextSession, now) {
@@ -408,8 +448,36 @@ var MongoOidcVaultStore = class {
       typeof nextSession.expiresAt === "number" ? nextSession.expiresAt : now + this.rotatedSessionAliasRetentionMs
     );
   }
-  async deleteRotatedSessionAliasesByLogicalSessionId(logicalSessionId) {
-    await this.rotatedSessionAliases.deleteMany({ logicalSessionId });
+  async deleteAliasesForInactiveLogicalSessions(logicalSessionIds) {
+    const session = this.db.client.startSession();
+    try {
+      await session.withTransaction(
+        async () => {
+          const live = await this.sessions.find(
+            {
+              $and: [
+                {
+                  $or: [
+                    { logicalSessionId: { $in: logicalSessionIds } },
+                    { logicalSessionId: { $exists: false }, _id: { $in: logicalSessionIds } }
+                  ]
+                },
+                { $nor: [{ expiresAt: { $lte: new Date(this.now()) } }] }
+              ]
+            },
+            { session, projection: { _id: 1, logicalSessionId: 1 } }
+          ).toArray();
+          const survivingIds = new Set(live.map((record) => record.logicalSessionId ?? record._id));
+          const inactiveIds = logicalSessionIds.filter((id) => !survivingIds.has(id));
+          if (inactiveIds.length > 0) {
+            await this.rotatedSessionAliases.deleteMany({ logicalSessionId: { $in: inactiveIds } }, { session });
+          }
+        },
+        { readConcern: { level: "snapshot" } }
+      );
+    } finally {
+      await session.endSession();
+    }
   }
   async isExpiredAndCleanup(collection, record) {
     if (!isExpired(record, this.now())) {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/express-oidc-vault-mongodb-store",
   "description": "MongoDB store provider for @web-ts-toolkit/express-oidc-vault",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/express-oidc-vault-mongodb-store",
-  "version": "0.42.2",
+  "version": "0.47.1",
   "sideEffects": false,
   "keywords": [
     "express",
@@ -25,7 +25,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@web-ts-toolkit/express-oidc-vault": "0.42.2",
+    "@web-ts-toolkit/express-oidc-vault": "0.47.1",
     "mongodb": "^6.20.0"
   },
   "files": [