@web-ts-toolkit/express-oidc-vault-mongodb-store 0.31.5 → 0.33.0

package/README.md

@@ -20,6 +20,11 @@ await client.connect();
 const storeProvider = createMongoOidcVaultStore({
   db: client.db('app-auth'),
 });
+
+await storeProvider.ready();
+
+// Later, during application shutdown:
+await client.close();
 ```
 
 ## Express Wiring Example
@@ -35,9 +40,16 @@ const mongo = new MongoClient(process.env.MONGODB_URI!);
 
 await mongo.connect();
 
+const storeProvider = createMongoOidcVaultStore({
+  db: mongo.db('app-auth'),
+});
+
+await storeProvider.ready();
+
 app.use(
   createOidcVaultMiddleware({
     basePath: '/auth/oidc',
+    backendOrigin: 'https://api.example.com',
     config: {
       issuer: process.env.OIDC_ISSUER,
       clientId: process.env.OIDC_CLIENT_ID,
@@ -45,21 +57,86 @@ app.use(
     },
     frontendRedirectUri: 'https://frontend.example.com/callback',
     postLogoutRedirectUri: 'https://frontend.example.com/logged-out',
-    storeProvider: createMongoOidcVaultStore({
-      db: mongo.db('app-auth'),
-    }),
+    storeProvider,
   }),
 );
+
+const server = app.listen(3000);
+
+process.once('SIGTERM', async () => {
+  server.close();
+  await mongo.close();
+});
+```
+
+## Collection Names
+
+The provider uses five separate MongoDB collections by default:
+
+- `oidc_vault_authorization_transactions`: authorization transaction state, nonce, PKCE verifier, and metadata
+- `oidc_vault_exchange_codes`: short-lived frontend exchange codes
+- `oidc_vault_sessions`: sessions, user data, and bearer-equivalent token material
+- `oidc_vault_backchannel_logout_token_jtis`: consumed backchannel logout token JTIs
+- `oidc_vault_rotated_session_aliases`: stale rotated session IDs mapped to active logical sessions
+
+Override collection names when your deployment needs explicit naming:
+
+```ts
+const storeProvider = createMongoOidcVaultStore({
+  db: mongo.db('app-auth'),
+  authorizationTransactionsCollectionName: 'auth_oidc_transactions',
+  exchangeCodesCollectionName: 'auth_oidc_exchange_codes',
+  sessionsCollectionName: 'auth_oidc_sessions',
+  backchannelLogoutTokenJtisCollectionName: 'auth_oidc_backchannel_logout_jtis',
+  rotatedSessionAliasesCollectionName: 'auth_oidc_rotated_session_aliases',
+});
 ```
 
 ## Notes
 
 - 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, and sessions
-- TTL indexes are created on `expiresAt`, and the provider also checks expiration on reads so behavior does not depend on Mongo's background TTL monitor timing
-- session rotation uses MongoDB transactions when connected to a replica set or sharded deployment, and falls back to conflict-safe rollback behavior on standalone servers
+- 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
+- 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
+- backchannel logout token JTI records are consumed only when `expiresAt` is finite and greater than the store clock at consume time
+
+## 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.
+
+Recommended controls:
+
+- require TLS for MongoDB connections and for any network path carrying session data
+- grant the application least-privilege roles scoped to the configured database and collections
+- enable encryption at rest for the database and backups
+- restrict observability tooling so token fields and whole session documents are not logged, indexed, sampled, or exported
+- 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
+
+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
+
+The sessions collection creates these deletion indexes:
+
+- `subject_scope_idx`: `{ subject: 1, 'provider.issuer': 1, 'provider.clientId': 1 }`
+- `provider_session_scope_idx`: `{ providerSessionId: 1, 'provider.issuer': 1, 'provider.clientId': 1 }`
+- `logical_session_idx`: `{ logicalSessionId: 1 }`
+
+Representative query-plan evidence used a dataset with 2 repeated identities, 10 issuers, 10 clients, and 10 duplicate sessions per issuer/client scope. With only single-field `subject` or `providerSessionId` indexes, scoped delete lookups examined all 1,000 matching identity documents. With the compound indexes above, `subject/providerSessionId + issuer`, `subject/providerSessionId + clientId`, and `subject/providerSessionId + issuer + clientId` examined 100, 100, and 10 documents respectively, matching the scoped result set size in that dataset.
+
+The package intentionally creates one compound index per public scoped identity delete path rather than one index per optional-filter permutation. The leading identity key still supports identity-only deletes with the same result-set-sized scan as the previous single-field indexes, while issuer/client scoped deletes avoid broad scans in multi-tenant collections. The residual assumption is that very large deployments should keep subject/provider-session identifiers reasonably distributed within each issuer/client scope; otherwise the scoped result set itself is large and deletion cost is expected to scale with the number of sessions being revoked.
 
 ## Main Exports
 
 - `createMongoOidcVaultStore(...)`
+- `type OidcVaultMongoStoreProvider`
 - `type MongoOidcVaultStoreOptions`
+- `DEFAULT_ROTATED_SESSION_ALIAS_RETENTION_MS`

package/index.d.mts

@@ -1,13 +1,66 @@
-import { OidcVaultStoreProvider } from '@web-ts-toolkit/express-oidc-vault';
 import { Db } from 'mongodb';
+import { OidcVaultStoreProvider } from '@web-ts-toolkit/express-oidc-vault';
 
+/**
+ * Options for `createMongoOidcVaultStore`.
+ *
+ * Pass a `Db` from an already-connected caller-owned `MongoClient`. The store
+ * validates collection names, creates indexes, and verifies transaction support
+ * from `ready()`, so applications should await readiness before accepting
+ * traffic. Session rotation requires MongoDB transactions; standalone servers
+ * fail closed instead of using non-atomic multi-write fallback behavior.
+ */
 interface MongoOidcVaultStoreOptions {
+    /** MongoDB database handle. The caller owns the underlying client lifecycle. */
     db: Db;
+    /** Collection for authorization transactions, keyed by OIDC `state`. */
     authorizationTransactionsCollectionName?: string;
+    /** Collection for short-lived frontend exchange codes. */
     exchangeCodesCollectionName?: string;
+    /** Collection for OIDC vault sessions and bearer-equivalent token material. */
     sessionsCollectionName?: string;
+    /** Collection for consumed backchannel logout token JTIs. */
+    backchannelLogoutTokenJtisCollectionName?: string;
+    /** Collection mapping rotated stale session IDs to active logical sessions. */
+    rotatedSessionAliasesCollectionName?: string;
+    /**
+     * Finite alias retention for sessions without explicit expiry, in
+     * milliseconds. Defaults to `DEFAULT_ROTATED_SESSION_ALIAS_RETENTION_MS`.
+     */
+    rotatedSessionAliasRetentionMs?: number;
+    /** Test-only clock override used for deterministic expiry and retention tests. */
     now?: () => number;
 }
-declare function createMongoOidcVaultStore(options: MongoOidcVaultStoreOptions): OidcVaultStoreProvider;
+/**
+ * MongoDB-backed OIDC vault store provider.
+ *
+ * Create the store after connecting the MongoDB client, then await `ready()`
+ * before accepting traffic. The application owns the MongoDB client lifecycle,
+ * including shutdown.
+ */
+interface OidcVaultMongoStoreProvider extends OidcVaultStoreProvider {
+    /**
+     * Waits for startup validation to complete.
+     *
+     * Readiness validates collection names, creates required indexes, and verifies
+     * the MongoDB deployment supports transactions required by session rotation.
+     * If readiness fails, every store operation rejects with the same error.
+     */
+    ready(): Promise<void>;
+}
+declare const DEFAULT_ROTATED_SESSION_ALIAS_RETENTION_MS: number;
+
+/**
+ * Creates a MongoDB-backed store provider.
+ *
+ * Use the named root import:
+ * `import { createMongoOidcVaultStore } from '@web-ts-toolkit/express-oidc-vault-mongodb-store'`.
+ * Pass a `Db` from an already-connected caller-owned `MongoClient`, await
+ * `store.ready()` before accepting traffic, and close the client from your own
+ * shutdown path. Readiness validates all configured collection names, creates
+ * required indexes for the five store collections, and verifies that the
+ * MongoDB deployment supports transactions required by session rotation.
+ */
+declare function createMongoOidcVaultStore(options: MongoOidcVaultStoreOptions): OidcVaultMongoStoreProvider;
 
-export { type MongoOidcVaultStoreOptions, createMongoOidcVaultStore };
+export { DEFAULT_ROTATED_SESSION_ALIAS_RETENTION_MS, type MongoOidcVaultStoreOptions, type OidcVaultMongoStoreProvider, createMongoOidcVaultStore };

package/index.d.ts

@@ -1,13 +1,66 @@
-import { OidcVaultStoreProvider } from '@web-ts-toolkit/express-oidc-vault';
 import { Db } from 'mongodb';
+import { OidcVaultStoreProvider } from '@web-ts-toolkit/express-oidc-vault';
 
+/**
+ * Options for `createMongoOidcVaultStore`.
+ *
+ * Pass a `Db` from an already-connected caller-owned `MongoClient`. The store
+ * validates collection names, creates indexes, and verifies transaction support
+ * from `ready()`, so applications should await readiness before accepting
+ * traffic. Session rotation requires MongoDB transactions; standalone servers
+ * fail closed instead of using non-atomic multi-write fallback behavior.
+ */
 interface MongoOidcVaultStoreOptions {
+    /** MongoDB database handle. The caller owns the underlying client lifecycle. */
     db: Db;
+    /** Collection for authorization transactions, keyed by OIDC `state`. */
     authorizationTransactionsCollectionName?: string;
+    /** Collection for short-lived frontend exchange codes. */
     exchangeCodesCollectionName?: string;
+    /** Collection for OIDC vault sessions and bearer-equivalent token material. */
     sessionsCollectionName?: string;
+    /** Collection for consumed backchannel logout token JTIs. */
+    backchannelLogoutTokenJtisCollectionName?: string;
+    /** Collection mapping rotated stale session IDs to active logical sessions. */
+    rotatedSessionAliasesCollectionName?: string;
+    /**
+     * Finite alias retention for sessions without explicit expiry, in
+     * milliseconds. Defaults to `DEFAULT_ROTATED_SESSION_ALIAS_RETENTION_MS`.
+     */
+    rotatedSessionAliasRetentionMs?: number;
+    /** Test-only clock override used for deterministic expiry and retention tests. */
     now?: () => number;
 }
-declare function createMongoOidcVaultStore(options: MongoOidcVaultStoreOptions): OidcVaultStoreProvider;
+/**
+ * MongoDB-backed OIDC vault store provider.
+ *
+ * Create the store after connecting the MongoDB client, then await `ready()`
+ * before accepting traffic. The application owns the MongoDB client lifecycle,
+ * including shutdown.
+ */
+interface OidcVaultMongoStoreProvider extends OidcVaultStoreProvider {
+    /**
+     * Waits for startup validation to complete.
+     *
+     * Readiness validates collection names, creates required indexes, and verifies
+     * the MongoDB deployment supports transactions required by session rotation.
+     * If readiness fails, every store operation rejects with the same error.
+     */
+    ready(): Promise<void>;
+}
+declare const DEFAULT_ROTATED_SESSION_ALIAS_RETENTION_MS: number;
+
+/**
+ * Creates a MongoDB-backed store provider.
+ *
+ * Use the named root import:
+ * `import { createMongoOidcVaultStore } from '@web-ts-toolkit/express-oidc-vault-mongodb-store'`.
+ * Pass a `Db` from an already-connected caller-owned `MongoClient`, await
+ * `store.ready()` before accepting traffic, and close the client from your own
+ * shutdown path. Readiness validates all configured collection names, creates
+ * required indexes for the five store collections, and verifies that the
+ * MongoDB deployment supports transactions required by session rotation.
+ */
+declare function createMongoOidcVaultStore(options: MongoOidcVaultStoreOptions): OidcVaultMongoStoreProvider;
 
-export { type MongoOidcVaultStoreOptions, createMongoOidcVaultStore };
+export { DEFAULT_ROTATED_SESSION_ALIAS_RETENTION_MS, type MongoOidcVaultStoreOptions, type OidcVaultMongoStoreProvider, createMongoOidcVaultStore };

package/index.js

@@ -20,17 +20,18 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DEFAULT_ROTATED_SESSION_ALIAS_RETENTION_MS: () => DEFAULT_ROTATED_SESSION_ALIAS_RETENTION_MS,
   createMongoOidcVaultStore: () => createMongoOidcVaultStore
 });
 module.exports = __toCommonJS(index_exports);
+
+// src/store.ts
 var import_express_oidc_vault = require("@web-ts-toolkit/express-oidc-vault");
-var DEFAULT_COLLECTION_NAMES = {
-  authorizationTransactions: "oidc_vault_authorization_transactions",
-  exchangeCodes: "oidc_vault_exchange_codes",
-  sessions: "oidc_vault_sessions"
-};
+
+// src/documents.ts
 var sessionToDocument = (session) => ({
   _id: session.sessionId,
+  logicalSessionId: session.logicalSessionId ?? session.sessionId,
   subject: session.subject,
   providerSessionId: session.providerSessionId,
   provider: session.provider,
@@ -46,6 +47,7 @@ var sessionToDocument = (session) => ({
 });
 var documentToSession = (session) => ({
   sessionId: session._id,
+  logicalSessionId: session.logicalSessionId ?? session._id,
   subject: session.subject,
   providerSessionId: session.providerSessionId,
   provider: session.provider,
@@ -87,56 +89,155 @@ var exchangeDocumentToRecord = (record) => ({
   expiresAt: record.expiresAt.getTime()
 });
 var isExpired = (record, now) => record.expiresAt instanceof Date && record.expiresAt.getTime() <= now;
+
+// src/options.ts
+var DEFAULT_ROTATED_SESSION_ALIAS_RETENTION_MS = 5 * 60 * 1e3;
+var DEFAULT_COLLECTION_NAMES = {
+  authorizationTransactions: "oidc_vault_authorization_transactions",
+  exchangeCodes: "oidc_vault_exchange_codes",
+  sessions: "oidc_vault_sessions",
+  backchannelLogoutTokenJtis: "oidc_vault_backchannel_logout_token_jtis",
+  rotatedSessionAliases: "oidc_vault_rotated_session_aliases"
+};
+var validateCollectionName = (role, name) => {
+  if (name.length === 0) {
+    throw new TypeError(`OIDC vault MongoDB ${role} collection name must not be empty.`);
+  }
+  if (name.includes("\0")) {
+    throw new TypeError(`OIDC vault MongoDB ${role} collection name must not contain null bytes.`);
+  }
+  if (name.startsWith("system.")) {
+    throw new TypeError(`OIDC vault MongoDB ${role} collection name must not use the reserved system namespace.`);
+  }
+  if (name.includes("$")) {
+    throw new TypeError(`OIDC vault MongoDB ${role} collection name must not contain '$'.`);
+  }
+};
+var resolveCollectionNames = (options) => {
+  const collectionNames = {
+    authorizationTransactions: options.authorizationTransactionsCollectionName ?? DEFAULT_COLLECTION_NAMES.authorizationTransactions,
+    exchangeCodes: options.exchangeCodesCollectionName ?? DEFAULT_COLLECTION_NAMES.exchangeCodes,
+    sessions: options.sessionsCollectionName ?? DEFAULT_COLLECTION_NAMES.sessions,
+    backchannelLogoutTokenJtis: options.backchannelLogoutTokenJtisCollectionName ?? DEFAULT_COLLECTION_NAMES.backchannelLogoutTokenJtis,
+    rotatedSessionAliases: options.rotatedSessionAliasesCollectionName ?? DEFAULT_COLLECTION_NAMES.rotatedSessionAliases
+  };
+  for (const [role, name] of Object.entries(collectionNames)) {
+    validateCollectionName(role, name);
+  }
+  const seen = /* @__PURE__ */ new Map();
+  for (const [role, name] of Object.entries(collectionNames)) {
+    const existingRole = seen.get(name);
+    if (existingRole !== void 0) {
+      throw new TypeError(
+        `OIDC vault MongoDB ${role} collection name must be distinct from ${existingRole}; shared collections are not supported.`
+      );
+    }
+    seen.set(name, role);
+  }
+  return collectionNames;
+};
+
+// src/topology.ts
+var isTransactionCapableHelloResponse = (value) => typeof value.setName === "string" || value.msg === "isdbgrid";
+var assertTransactionSupport = async (db) => {
+  const hello = await db.admin().command({ hello: 1 });
+  if (!isTransactionCapableHelloResponse(hello)) {
+    throw new Error(
+      "OIDC vault MongoDB session rotation requires a transaction-capable MongoDB deployment. Use a replica set or sharded cluster."
+    );
+  }
+};
+var createTtlIndex = async (collection) => collection.createIndex(
+  { expiresAt: 1 },
+  {
+    expireAfterSeconds: 0,
+    name: "expiresAt_ttl"
+  }
+);
+var ensureStoreIndexes = async (collections) => {
+  await Promise.all([
+    createTtlIndex(collections.authorizationTransactions),
+    createTtlIndex(collections.exchangeCodes),
+    createTtlIndex(collections.sessions),
+    createTtlIndex(collections.backchannelLogoutTokenJtis),
+    createTtlIndex(collections.rotatedSessionAliases),
+    collections.rotatedSessionAliases.createIndex({ logicalSessionId: 1 }, { name: "logical_session_idx" }),
+    collections.sessions.createIndex(
+      { subject: 1, "provider.issuer": 1, "provider.clientId": 1 },
+      { name: "subject_scope_idx" }
+    ),
+    collections.sessions.createIndex(
+      { providerSessionId: 1, "provider.issuer": 1, "provider.clientId": 1 },
+      { name: "provider_session_scope_idx" }
+    ),
+    collections.sessions.createIndex({ logicalSessionId: 1 }, { name: "logical_session_idx" })
+  ]);
+};
+
+// src/store.ts
 var toSubjectDeleteInput = (input) => typeof input === "string" ? { subject: input } : input;
 var toProviderSessionDeleteInput = (input) => typeof input === "string" ? { providerSessionId: input } : input;
-var isTransactionCapableHelloResponse = (value) => typeof value.setName === "string" || value.msg === "isdbgrid";
+var toLogicalSessionDeleteInput = (input) => typeof input === "string" ? { logicalSessionId: input } : input;
+var isDuplicateKeyError = (error) => typeof error === "object" && error !== null && "code" in error && error.code === 11e3;
 var MongoOidcVaultStore = class {
   constructor(options) {
+    const collectionNames = resolveCollectionNames(options);
     this.db = options.db;
     this.authorizationTransactions = options.db.collection(
-      options.authorizationTransactionsCollectionName ?? DEFAULT_COLLECTION_NAMES.authorizationTransactions
+      collectionNames.authorizationTransactions
     );
-    this.exchangeCodes = options.db.collection(
-      options.exchangeCodesCollectionName ?? DEFAULT_COLLECTION_NAMES.exchangeCodes
+    this.exchangeCodes = options.db.collection(collectionNames.exchangeCodes);
+    this.sessions = options.db.collection(collectionNames.sessions);
+    this.backchannelLogoutTokenJtis = options.db.collection(
+      collectionNames.backchannelLogoutTokenJtis
     );
-    this.sessions = options.db.collection(
-      options.sessionsCollectionName ?? DEFAULT_COLLECTION_NAMES.sessions
+    this.rotatedSessionAliases = options.db.collection(
+      collectionNames.rotatedSessionAliases
     );
+    this.rotatedSessionAliasRetentionMs = options.rotatedSessionAliasRetentionMs ?? DEFAULT_ROTATED_SESSION_ALIAS_RETENTION_MS;
+    if (!Number.isFinite(this.rotatedSessionAliasRetentionMs) || this.rotatedSessionAliasRetentionMs <= 0) {
+      throw new TypeError("OIDC vault rotated session alias retention must be a finite positive duration.");
+    }
     this.now = options.now ?? (() => Date.now());
-    this.ready = this.ensureIndexes();
-    this.supportsTransactions = this.detectTransactionSupport();
+    this.initialization = this.initialize().then(void 0, (error) => {
+      this.initializationError = error;
+    });
+  }
+  async ready() {
+    await this.waitUntilReady();
   }
   async createAuthorizationTransaction(input) {
-    await this.ready;
+    await this.waitUntilReady();
     await this.authorizationTransactions.replaceOne({ _id: input.state }, authorizationTransactionToDocument(input), {
       upsert: true
     });
   }
   async consumeAuthorizationTransaction(state) {
-    await this.ready;
+    await this.waitUntilReady();
     const record = await this.authorizationTransactions.findOneAndDelete({ _id: state });
-    if (!record || await this.isExpiredAndCleanup(this.authorizationTransactions, record)) {
+    if (!record || isExpired(record, this.now())) {
       return null;
     }
     return authorizationDocumentToRecord(record);
   }
   async createExchangeCode(input) {
-    await this.ready;
+    await this.waitUntilReady();
     await this.exchangeCodes.replaceOne({ _id: input.code }, exchangeCodeToDocument(input), { upsert: true });
   }
   async consumeExchangeCode(code) {
-    await this.ready;
+    await this.waitUntilReady();
     const record = await this.exchangeCodes.findOneAndDelete({ _id: code });
-    if (!record || await this.isExpiredAndCleanup(this.exchangeCodes, record)) {
+    if (!record || isExpired(record, this.now())) {
       return null;
     }
     return exchangeDocumentToRecord(record);
   }
   async createSession(input) {
-    await this.ready;
+    await this.waitUntilReady();
     const timestamp = this.now();
     const session = {
       ...input,
+      logicalSessionId: input.logicalSessionId ?? input.sessionId,
       createdAt: input.createdAt ?? timestamp,
       updatedAt: input.updatedAt ?? timestamp
     };
@@ -144,7 +245,7 @@ var MongoOidcVaultStore = class {
     return session;
   }
   async getSession(sessionId) {
-    await this.ready;
+    await this.waitUntilReady();
     const session = await this.sessions.findOne({ _id: sessionId });
     if (!session || await this.isExpiredAndCleanup(this.sessions, session)) {
       return null;
@@ -152,42 +253,81 @@ var MongoOidcVaultStore = class {
     return documentToSession(session);
   }
   async rotateSession(input) {
-    await this.ready;
-    if (await this.supportsTransactions) {
-      return this.rotateSessionWithTransaction(input);
+    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.");
+    }
+    try {
+      return await this.rotateSessionWithTransaction(input);
+    } catch (error) {
+      if (isDuplicateKeyError(error)) {
+        throw new import_express_oidc_vault.OidcVaultStoreConflictError("OIDC vault session rotation target already exists.");
+      }
+      throw error;
     }
-    return this.rotateSessionWithoutTransaction(input);
   }
-  async rotateSessionWithoutTransaction(input) {
-    await this.sessions.insertOne(sessionToDocument(input.nextSession));
-    const deleteResult = await this.sessions.deleteOne({ _id: input.sessionId });
-    if (deleteResult.deletedCount !== 1) {
-      await this.sessions.deleteOne({ _id: input.nextSession.sessionId });
-      throw new import_express_oidc_vault.OidcVaultStoreConflictError("OIDC vault session no longer exists for rotation.");
+  async deleteSession(sessionId) {
+    await this.waitUntilReady();
+    const session = await this.sessions.findOne({ _id: sessionId });
+    if (session) {
+      const logicalSessionId = session.logicalSessionId ?? session._id;
+      const result = await this.sessions.deleteOne({ _id: sessionId });
+      if (result.deletedCount === 1) {
+        await this.deleteRotatedSessionAliasesByLogicalSessionId(logicalSessionId);
+        return;
+      }
+      const alias2 = await this.rotatedSessionAliases.findOne({ _id: sessionId });
+      if (alias2 && !isExpired(alias2, this.now())) {
+        await this.deleteSessionsByLogicalSessionId(alias2.logicalSessionId);
+      }
+      return;
+    }
+    const alias = await this.rotatedSessionAliases.findOne({ _id: sessionId });
+    if (alias && !isExpired(alias, this.now())) {
+      await this.deleteSessionsByLogicalSessionId(alias.logicalSessionId);
     }
-    return input.nextSession;
   }
-  async rotateSessionWithTransaction(input) {
-    const session = this.db.client.startSession();
+  async deleteSessionsByLogicalSessionId(input) {
+    await this.waitUntilReady();
+    const resolved = toLogicalSessionDeleteInput(input);
+    const result = await this.sessions.deleteMany({ logicalSessionId: resolved.logicalSessionId });
+    await this.deleteRotatedSessionAliasesByLogicalSessionId(resolved.logicalSessionId);
+    return result.deletedCount;
+  }
+  async consumeBackchannelLogoutTokenJti(input) {
+    await this.waitUntilReady();
+    const now = this.now();
+    if (!Number.isFinite(input.expiresAt) || input.expiresAt <= now) {
+      return false;
+    }
+    const replacedExpired = await this.backchannelLogoutTokenJtis.findOneAndUpdate(
+      {
+        _id: input.jti,
+        expiresAt: { $lte: new Date(now) }
+      },
+      {
+        $set: { expiresAt: new Date(input.expiresAt) }
+      },
+      { returnDocument: "after" }
+    );
+    if (replacedExpired) {
+      return true;
+    }
     try {
-      await session.withTransaction(async () => {
-        await this.sessions.insertOne(sessionToDocument(input.nextSession), { session });
-        const deleteResult = await this.sessions.deleteOne({ _id: input.sessionId }, { session });
-        if (deleteResult.deletedCount !== 1) {
-          throw new import_express_oidc_vault.OidcVaultStoreConflictError("OIDC vault session no longer exists for rotation.");
-        }
+      await this.backchannelLogoutTokenJtis.insertOne({
+        _id: input.jti,
+        expiresAt: new Date(input.expiresAt)
       });
-      return input.nextSession;
-    } finally {
-      await session.endSession();
+      return true;
+    } catch (error) {
+      if (isDuplicateKeyError(error)) {
+        return false;
+      }
+      throw error;
     }
   }
-  async deleteSession(sessionId) {
-    await this.ready;
-    await this.sessions.deleteOne({ _id: sessionId });
-  }
   async deleteSessionsBySubject(input) {
-    await this.ready;
+    await this.waitUntilReady();
     const resolved = toSubjectDeleteInput(input);
     const filter = { subject: resolved.subject };
     if (resolved.issuer !== void 0) {
@@ -196,11 +336,11 @@ var MongoOidcVaultStore = class {
     if (resolved.clientId !== void 0) {
       filter["provider.clientId"] = resolved.clientId;
     }
-    const result = await this.sessions.deleteMany(filter);
+    const result = await this.deleteSessionsAndAliasesByFilter(filter);
     return result.deletedCount;
   }
   async deleteSessionsByProviderSessionId(input) {
-    await this.ready;
+    await this.waitUntilReady();
     const resolved = toProviderSessionDeleteInput(input);
     const filter = { providerSessionId: resolved.providerSessionId };
     if (resolved.issuer !== void 0) {
@@ -209,47 +349,108 @@ var MongoOidcVaultStore = class {
     if (resolved.clientId !== void 0) {
       filter["provider.clientId"] = resolved.clientId;
     }
-    const result = await this.sessions.deleteMany(filter);
+    const result = await this.deleteSessionsAndAliasesByFilter(filter);
     return result.deletedCount;
   }
-  async ensureIndexes() {
+  async initialize() {
     await Promise.all([
-      this.createTtlIndex(this.authorizationTransactions),
-      this.createTtlIndex(this.exchangeCodes),
-      this.createTtlIndex(this.sessions),
-      this.sessions.createIndex({ subject: 1 }, { name: "subject_idx" }),
-      this.sessions.createIndex({ providerSessionId: 1 }, { name: "provider_session_idx" })
+      ensureStoreIndexes({
+        authorizationTransactions: this.authorizationTransactions,
+        exchangeCodes: this.exchangeCodes,
+        sessions: this.sessions,
+        backchannelLogoutTokenJtis: this.backchannelLogoutTokenJtis,
+        rotatedSessionAliases: this.rotatedSessionAliases
+      }),
+      assertTransactionSupport(this.db)
     ]);
   }
-  async detectTransactionSupport() {
+  async waitUntilReady() {
+    await this.initialization;
+    if (this.initializationError !== void 0) {
+      throw this.initializationError;
+    }
+  }
+  async rotateSessionWithTransaction(input) {
+    const session = this.db.client.startSession();
+    const nextSession = await this.normalizeRotatedSession(input);
     try {
-      const hello = await this.db.admin().command({ hello: 1 });
-      return isTransactionCapableHelloResponse(hello);
-    } catch {
-      return false;
+      await session.withTransaction(async () => {
+        await this.sessions.insertOne(sessionToDocument(nextSession), { session });
+        const deleteResult = await this.sessions.deleteOne({ _id: input.sessionId }, { session });
+        if (deleteResult.deletedCount !== 1) {
+          throw new import_express_oidc_vault.OidcVaultStoreConflictError("OIDC vault session no longer exists for rotation.");
+        }
+        await this.createRotatedSessionAlias(input.sessionId, nextSession, session);
+      });
+      return nextSession;
+    } finally {
+      await session.endSession();
     }
   }
-  async createTtlIndex(collection) {
-    return collection.createIndex(
-      { expiresAt: 1 },
+  async createRotatedSessionAlias(previousSessionId, nextSession, session) {
+    const logicalSessionId = nextSession.logicalSessionId ?? nextSession.sessionId;
+    const now = this.now();
+    await this.rotatedSessionAliases.deleteMany({ logicalSessionId, expiresAt: { $lte: new Date(now) } }, { session });
+    await this.rotatedSessionAliases.updateOne(
+      { _id: previousSessionId },
       {
-        expireAfterSeconds: 0,
-        name: "expiresAt_ttl"
+        $set: {
+          logicalSessionId,
+          expiresAt: this.getRotatedSessionAliasExpiresAt(nextSession, now)
+        }
+      },
+      { upsert: true, session }
+    );
+  }
+  async normalizeRotatedSession(input) {
+    const previous = await this.getSession(input.sessionId);
+    if (!previous) {
+      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
+    };
+  }
+  async deleteSessionsAndAliasesByFilter(filter) {
+    let deletedCount = 0;
+    for (; ; ) {
+      const sessions = await this.sessions.find(filter).project({
+        _id: 1,
+        logicalSessionId: 1
+      }).toArray();
+      const logicalSessionIds = [...new Set(sessions.map((session) => session.logicalSessionId ?? session._id))];
+      if (logicalSessionIds.length === 0) {
+        return { deletedCount };
       }
+      const result = await this.sessions.deleteMany(filter);
+      deletedCount += result.deletedCount;
+      await this.rotatedSessionAliases.deleteMany({ logicalSessionId: { $in: logicalSessionIds } });
+    }
+  }
+  getRotatedSessionAliasExpiresAt(nextSession, now) {
+    return new Date(
+      typeof nextSession.expiresAt === "number" ? nextSession.expiresAt : now + this.rotatedSessionAliasRetentionMs
     );
   }
+  async deleteRotatedSessionAliasesByLogicalSessionId(logicalSessionId) {
+    await this.rotatedSessionAliases.deleteMany({ logicalSessionId });
+  }
   async isExpiredAndCleanup(collection, record) {
     if (!isExpired(record, this.now())) {
       return false;
     }
-    await collection.deleteOne({ _id: record._id });
+    await collection.deleteOne({ _id: record._id, expiresAt: record.expiresAt });
     return true;
   }
 };
+
+// src/index.ts
 function createMongoOidcVaultStore(options) {
   return new MongoOidcVaultStore(options);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_ROTATED_SESSION_ALIAS_RETENTION_MS,
   createMongoOidcVaultStore
 });

package/index.mjs

@@ -1,14 +1,12 @@
-// src/index.ts
+// src/store.ts
 import {
   OidcVaultStoreConflictError
 } from "@web-ts-toolkit/express-oidc-vault";
-var DEFAULT_COLLECTION_NAMES = {
-  authorizationTransactions: "oidc_vault_authorization_transactions",
-  exchangeCodes: "oidc_vault_exchange_codes",
-  sessions: "oidc_vault_sessions"
-};
+
+// src/documents.ts
 var sessionToDocument = (session) => ({
   _id: session.sessionId,
+  logicalSessionId: session.logicalSessionId ?? session.sessionId,
   subject: session.subject,
   providerSessionId: session.providerSessionId,
   provider: session.provider,
@@ -24,6 +22,7 @@ var sessionToDocument = (session) => ({
 });
 var documentToSession = (session) => ({
   sessionId: session._id,
+  logicalSessionId: session.logicalSessionId ?? session._id,
   subject: session.subject,
   providerSessionId: session.providerSessionId,
   provider: session.provider,
@@ -65,56 +64,155 @@ var exchangeDocumentToRecord = (record) => ({
   expiresAt: record.expiresAt.getTime()
 });
 var isExpired = (record, now) => record.expiresAt instanceof Date && record.expiresAt.getTime() <= now;
+
+// src/options.ts
+var DEFAULT_ROTATED_SESSION_ALIAS_RETENTION_MS = 5 * 60 * 1e3;
+var DEFAULT_COLLECTION_NAMES = {
+  authorizationTransactions: "oidc_vault_authorization_transactions",
+  exchangeCodes: "oidc_vault_exchange_codes",
+  sessions: "oidc_vault_sessions",
+  backchannelLogoutTokenJtis: "oidc_vault_backchannel_logout_token_jtis",
+  rotatedSessionAliases: "oidc_vault_rotated_session_aliases"
+};
+var validateCollectionName = (role, name) => {
+  if (name.length === 0) {
+    throw new TypeError(`OIDC vault MongoDB ${role} collection name must not be empty.`);
+  }
+  if (name.includes("\0")) {
+    throw new TypeError(`OIDC vault MongoDB ${role} collection name must not contain null bytes.`);
+  }
+  if (name.startsWith("system.")) {
+    throw new TypeError(`OIDC vault MongoDB ${role} collection name must not use the reserved system namespace.`);
+  }
+  if (name.includes("$")) {
+    throw new TypeError(`OIDC vault MongoDB ${role} collection name must not contain '$'.`);
+  }
+};
+var resolveCollectionNames = (options) => {
+  const collectionNames = {
+    authorizationTransactions: options.authorizationTransactionsCollectionName ?? DEFAULT_COLLECTION_NAMES.authorizationTransactions,
+    exchangeCodes: options.exchangeCodesCollectionName ?? DEFAULT_COLLECTION_NAMES.exchangeCodes,
+    sessions: options.sessionsCollectionName ?? DEFAULT_COLLECTION_NAMES.sessions,
+    backchannelLogoutTokenJtis: options.backchannelLogoutTokenJtisCollectionName ?? DEFAULT_COLLECTION_NAMES.backchannelLogoutTokenJtis,
+    rotatedSessionAliases: options.rotatedSessionAliasesCollectionName ?? DEFAULT_COLLECTION_NAMES.rotatedSessionAliases
+  };
+  for (const [role, name] of Object.entries(collectionNames)) {
+    validateCollectionName(role, name);
+  }
+  const seen = /* @__PURE__ */ new Map();
+  for (const [role, name] of Object.entries(collectionNames)) {
+    const existingRole = seen.get(name);
+    if (existingRole !== void 0) {
+      throw new TypeError(
+        `OIDC vault MongoDB ${role} collection name must be distinct from ${existingRole}; shared collections are not supported.`
+      );
+    }
+    seen.set(name, role);
+  }
+  return collectionNames;
+};
+
+// src/topology.ts
+var isTransactionCapableHelloResponse = (value) => typeof value.setName === "string" || value.msg === "isdbgrid";
+var assertTransactionSupport = async (db) => {
+  const hello = await db.admin().command({ hello: 1 });
+  if (!isTransactionCapableHelloResponse(hello)) {
+    throw new Error(
+      "OIDC vault MongoDB session rotation requires a transaction-capable MongoDB deployment. Use a replica set or sharded cluster."
+    );
+  }
+};
+var createTtlIndex = async (collection) => collection.createIndex(
+  { expiresAt: 1 },
+  {
+    expireAfterSeconds: 0,
+    name: "expiresAt_ttl"
+  }
+);
+var ensureStoreIndexes = async (collections) => {
+  await Promise.all([
+    createTtlIndex(collections.authorizationTransactions),
+    createTtlIndex(collections.exchangeCodes),
+    createTtlIndex(collections.sessions),
+    createTtlIndex(collections.backchannelLogoutTokenJtis),
+    createTtlIndex(collections.rotatedSessionAliases),
+    collections.rotatedSessionAliases.createIndex({ logicalSessionId: 1 }, { name: "logical_session_idx" }),
+    collections.sessions.createIndex(
+      { subject: 1, "provider.issuer": 1, "provider.clientId": 1 },
+      { name: "subject_scope_idx" }
+    ),
+    collections.sessions.createIndex(
+      { providerSessionId: 1, "provider.issuer": 1, "provider.clientId": 1 },
+      { name: "provider_session_scope_idx" }
+    ),
+    collections.sessions.createIndex({ logicalSessionId: 1 }, { name: "logical_session_idx" })
+  ]);
+};
+
+// src/store.ts
 var toSubjectDeleteInput = (input) => typeof input === "string" ? { subject: input } : input;
 var toProviderSessionDeleteInput = (input) => typeof input === "string" ? { providerSessionId: input } : input;
-var isTransactionCapableHelloResponse = (value) => typeof value.setName === "string" || value.msg === "isdbgrid";
+var toLogicalSessionDeleteInput = (input) => typeof input === "string" ? { logicalSessionId: input } : input;
+var isDuplicateKeyError = (error) => typeof error === "object" && error !== null && "code" in error && error.code === 11e3;
 var MongoOidcVaultStore = class {
   constructor(options) {
+    const collectionNames = resolveCollectionNames(options);
     this.db = options.db;
     this.authorizationTransactions = options.db.collection(
-      options.authorizationTransactionsCollectionName ?? DEFAULT_COLLECTION_NAMES.authorizationTransactions
+      collectionNames.authorizationTransactions
     );
-    this.exchangeCodes = options.db.collection(
-      options.exchangeCodesCollectionName ?? DEFAULT_COLLECTION_NAMES.exchangeCodes
+    this.exchangeCodes = options.db.collection(collectionNames.exchangeCodes);
+    this.sessions = options.db.collection(collectionNames.sessions);
+    this.backchannelLogoutTokenJtis = options.db.collection(
+      collectionNames.backchannelLogoutTokenJtis
     );
-    this.sessions = options.db.collection(
-      options.sessionsCollectionName ?? DEFAULT_COLLECTION_NAMES.sessions
+    this.rotatedSessionAliases = options.db.collection(
+      collectionNames.rotatedSessionAliases
     );
+    this.rotatedSessionAliasRetentionMs = options.rotatedSessionAliasRetentionMs ?? DEFAULT_ROTATED_SESSION_ALIAS_RETENTION_MS;
+    if (!Number.isFinite(this.rotatedSessionAliasRetentionMs) || this.rotatedSessionAliasRetentionMs <= 0) {
+      throw new TypeError("OIDC vault rotated session alias retention must be a finite positive duration.");
+    }
     this.now = options.now ?? (() => Date.now());
-    this.ready = this.ensureIndexes();
-    this.supportsTransactions = this.detectTransactionSupport();
+    this.initialization = this.initialize().then(void 0, (error) => {
+      this.initializationError = error;
+    });
+  }
+  async ready() {
+    await this.waitUntilReady();
   }
   async createAuthorizationTransaction(input) {
-    await this.ready;
+    await this.waitUntilReady();
     await this.authorizationTransactions.replaceOne({ _id: input.state }, authorizationTransactionToDocument(input), {
       upsert: true
     });
   }
   async consumeAuthorizationTransaction(state) {
-    await this.ready;
+    await this.waitUntilReady();
     const record = await this.authorizationTransactions.findOneAndDelete({ _id: state });
-    if (!record || await this.isExpiredAndCleanup(this.authorizationTransactions, record)) {
+    if (!record || isExpired(record, this.now())) {
       return null;
     }
     return authorizationDocumentToRecord(record);
   }
   async createExchangeCode(input) {
-    await this.ready;
+    await this.waitUntilReady();
     await this.exchangeCodes.replaceOne({ _id: input.code }, exchangeCodeToDocument(input), { upsert: true });
   }
   async consumeExchangeCode(code) {
-    await this.ready;
+    await this.waitUntilReady();
     const record = await this.exchangeCodes.findOneAndDelete({ _id: code });
-    if (!record || await this.isExpiredAndCleanup(this.exchangeCodes, record)) {
+    if (!record || isExpired(record, this.now())) {
       return null;
     }
     return exchangeDocumentToRecord(record);
   }
   async createSession(input) {
-    await this.ready;
+    await this.waitUntilReady();
     const timestamp = this.now();
     const session = {
       ...input,
+      logicalSessionId: input.logicalSessionId ?? input.sessionId,
       createdAt: input.createdAt ?? timestamp,
       updatedAt: input.updatedAt ?? timestamp
     };
@@ -122,7 +220,7 @@ var MongoOidcVaultStore = class {
     return session;
   }
   async getSession(sessionId) {
-    await this.ready;
+    await this.waitUntilReady();
     const session = await this.sessions.findOne({ _id: sessionId });
     if (!session || await this.isExpiredAndCleanup(this.sessions, session)) {
       return null;
@@ -130,42 +228,81 @@ var MongoOidcVaultStore = class {
     return documentToSession(session);
   }
   async rotateSession(input) {
-    await this.ready;
-    if (await this.supportsTransactions) {
-      return this.rotateSessionWithTransaction(input);
+    await this.waitUntilReady();
+    if (input.nextSession.sessionId === input.sessionId) {
+      throw new OidcVaultStoreConflictError("OIDC vault session rotation target must use a different session ID.");
+    }
+    try {
+      return await this.rotateSessionWithTransaction(input);
+    } catch (error) {
+      if (isDuplicateKeyError(error)) {
+        throw new OidcVaultStoreConflictError("OIDC vault session rotation target already exists.");
+      }
+      throw error;
     }
-    return this.rotateSessionWithoutTransaction(input);
   }
-  async rotateSessionWithoutTransaction(input) {
-    await this.sessions.insertOne(sessionToDocument(input.nextSession));
-    const deleteResult = await this.sessions.deleteOne({ _id: input.sessionId });
-    if (deleteResult.deletedCount !== 1) {
-      await this.sessions.deleteOne({ _id: input.nextSession.sessionId });
-      throw new OidcVaultStoreConflictError("OIDC vault session no longer exists for rotation.");
+  async deleteSession(sessionId) {
+    await this.waitUntilReady();
+    const session = await this.sessions.findOne({ _id: sessionId });
+    if (session) {
+      const logicalSessionId = session.logicalSessionId ?? session._id;
+      const result = await this.sessions.deleteOne({ _id: sessionId });
+      if (result.deletedCount === 1) {
+        await this.deleteRotatedSessionAliasesByLogicalSessionId(logicalSessionId);
+        return;
+      }
+      const alias2 = await this.rotatedSessionAliases.findOne({ _id: sessionId });
+      if (alias2 && !isExpired(alias2, this.now())) {
+        await this.deleteSessionsByLogicalSessionId(alias2.logicalSessionId);
+      }
+      return;
+    }
+    const alias = await this.rotatedSessionAliases.findOne({ _id: sessionId });
+    if (alias && !isExpired(alias, this.now())) {
+      await this.deleteSessionsByLogicalSessionId(alias.logicalSessionId);
     }
-    return input.nextSession;
   }
-  async rotateSessionWithTransaction(input) {
-    const session = this.db.client.startSession();
+  async deleteSessionsByLogicalSessionId(input) {
+    await this.waitUntilReady();
+    const resolved = toLogicalSessionDeleteInput(input);
+    const result = await this.sessions.deleteMany({ logicalSessionId: resolved.logicalSessionId });
+    await this.deleteRotatedSessionAliasesByLogicalSessionId(resolved.logicalSessionId);
+    return result.deletedCount;
+  }
+  async consumeBackchannelLogoutTokenJti(input) {
+    await this.waitUntilReady();
+    const now = this.now();
+    if (!Number.isFinite(input.expiresAt) || input.expiresAt <= now) {
+      return false;
+    }
+    const replacedExpired = await this.backchannelLogoutTokenJtis.findOneAndUpdate(
+      {
+        _id: input.jti,
+        expiresAt: { $lte: new Date(now) }
+      },
+      {
+        $set: { expiresAt: new Date(input.expiresAt) }
+      },
+      { returnDocument: "after" }
+    );
+    if (replacedExpired) {
+      return true;
+    }
     try {
-      await session.withTransaction(async () => {
-        await this.sessions.insertOne(sessionToDocument(input.nextSession), { session });
-        const deleteResult = await this.sessions.deleteOne({ _id: input.sessionId }, { session });
-        if (deleteResult.deletedCount !== 1) {
-          throw new OidcVaultStoreConflictError("OIDC vault session no longer exists for rotation.");
-        }
+      await this.backchannelLogoutTokenJtis.insertOne({
+        _id: input.jti,
+        expiresAt: new Date(input.expiresAt)
       });
-      return input.nextSession;
-    } finally {
-      await session.endSession();
+      return true;
+    } catch (error) {
+      if (isDuplicateKeyError(error)) {
+        return false;
+      }
+      throw error;
     }
   }
-  async deleteSession(sessionId) {
-    await this.ready;
-    await this.sessions.deleteOne({ _id: sessionId });
-  }
   async deleteSessionsBySubject(input) {
-    await this.ready;
+    await this.waitUntilReady();
     const resolved = toSubjectDeleteInput(input);
     const filter = { subject: resolved.subject };
     if (resolved.issuer !== void 0) {
@@ -174,11 +311,11 @@ var MongoOidcVaultStore = class {
     if (resolved.clientId !== void 0) {
       filter["provider.clientId"] = resolved.clientId;
     }
-    const result = await this.sessions.deleteMany(filter);
+    const result = await this.deleteSessionsAndAliasesByFilter(filter);
     return result.deletedCount;
   }
   async deleteSessionsByProviderSessionId(input) {
-    await this.ready;
+    await this.waitUntilReady();
     const resolved = toProviderSessionDeleteInput(input);
     const filter = { providerSessionId: resolved.providerSessionId };
     if (resolved.issuer !== void 0) {
@@ -187,46 +324,107 @@ var MongoOidcVaultStore = class {
     if (resolved.clientId !== void 0) {
       filter["provider.clientId"] = resolved.clientId;
     }
-    const result = await this.sessions.deleteMany(filter);
+    const result = await this.deleteSessionsAndAliasesByFilter(filter);
     return result.deletedCount;
   }
-  async ensureIndexes() {
+  async initialize() {
     await Promise.all([
-      this.createTtlIndex(this.authorizationTransactions),
-      this.createTtlIndex(this.exchangeCodes),
-      this.createTtlIndex(this.sessions),
-      this.sessions.createIndex({ subject: 1 }, { name: "subject_idx" }),
-      this.sessions.createIndex({ providerSessionId: 1 }, { name: "provider_session_idx" })
+      ensureStoreIndexes({
+        authorizationTransactions: this.authorizationTransactions,
+        exchangeCodes: this.exchangeCodes,
+        sessions: this.sessions,
+        backchannelLogoutTokenJtis: this.backchannelLogoutTokenJtis,
+        rotatedSessionAliases: this.rotatedSessionAliases
+      }),
+      assertTransactionSupport(this.db)
     ]);
   }
-  async detectTransactionSupport() {
+  async waitUntilReady() {
+    await this.initialization;
+    if (this.initializationError !== void 0) {
+      throw this.initializationError;
+    }
+  }
+  async rotateSessionWithTransaction(input) {
+    const session = this.db.client.startSession();
+    const nextSession = await this.normalizeRotatedSession(input);
     try {
-      const hello = await this.db.admin().command({ hello: 1 });
-      return isTransactionCapableHelloResponse(hello);
-    } catch {
-      return false;
+      await session.withTransaction(async () => {
+        await this.sessions.insertOne(sessionToDocument(nextSession), { session });
+        const deleteResult = await this.sessions.deleteOne({ _id: input.sessionId }, { session });
+        if (deleteResult.deletedCount !== 1) {
+          throw new OidcVaultStoreConflictError("OIDC vault session no longer exists for rotation.");
+        }
+        await this.createRotatedSessionAlias(input.sessionId, nextSession, session);
+      });
+      return nextSession;
+    } finally {
+      await session.endSession();
     }
   }
-  async createTtlIndex(collection) {
-    return collection.createIndex(
-      { expiresAt: 1 },
+  async createRotatedSessionAlias(previousSessionId, nextSession, session) {
+    const logicalSessionId = nextSession.logicalSessionId ?? nextSession.sessionId;
+    const now = this.now();
+    await this.rotatedSessionAliases.deleteMany({ logicalSessionId, expiresAt: { $lte: new Date(now) } }, { session });
+    await this.rotatedSessionAliases.updateOne(
+      { _id: previousSessionId },
       {
-        expireAfterSeconds: 0,
-        name: "expiresAt_ttl"
+        $set: {
+          logicalSessionId,
+          expiresAt: this.getRotatedSessionAliasExpiresAt(nextSession, now)
+        }
+      },
+      { upsert: true, session }
+    );
+  }
+  async normalizeRotatedSession(input) {
+    const previous = await this.getSession(input.sessionId);
+    if (!previous) {
+      throw new OidcVaultStoreConflictError("OIDC vault session no longer exists for rotation.");
+    }
+    return {
+      ...input.nextSession,
+      logicalSessionId: input.nextSession.logicalSessionId ?? previous.logicalSessionId ?? input.sessionId
+    };
+  }
+  async deleteSessionsAndAliasesByFilter(filter) {
+    let deletedCount = 0;
+    for (; ; ) {
+      const sessions = await this.sessions.find(filter).project({
+        _id: 1,
+        logicalSessionId: 1
+      }).toArray();
+      const logicalSessionIds = [...new Set(sessions.map((session) => session.logicalSessionId ?? session._id))];
+      if (logicalSessionIds.length === 0) {
+        return { deletedCount };
       }
+      const result = await this.sessions.deleteMany(filter);
+      deletedCount += result.deletedCount;
+      await this.rotatedSessionAliases.deleteMany({ logicalSessionId: { $in: logicalSessionIds } });
+    }
+  }
+  getRotatedSessionAliasExpiresAt(nextSession, now) {
+    return new Date(
+      typeof nextSession.expiresAt === "number" ? nextSession.expiresAt : now + this.rotatedSessionAliasRetentionMs
     );
   }
+  async deleteRotatedSessionAliasesByLogicalSessionId(logicalSessionId) {
+    await this.rotatedSessionAliases.deleteMany({ logicalSessionId });
+  }
   async isExpiredAndCleanup(collection, record) {
     if (!isExpired(record, this.now())) {
       return false;
     }
-    await collection.deleteOne({ _id: record._id });
+    await collection.deleteOne({ _id: record._id, expiresAt: record.expiresAt });
     return true;
   }
 };
+
+// src/index.ts
 function createMongoOidcVaultStore(options) {
   return new MongoOidcVaultStore(options);
 }
 export {
+  DEFAULT_ROTATED_SESSION_ALIAS_RETENTION_MS,
   createMongoOidcVaultStore
 };

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.31.5",
+  "version": "0.33.0",
   "sideEffects": false,
   "keywords": [
     "express",
@@ -22,10 +22,10 @@
     }
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "dependencies": {
-    "@web-ts-toolkit/express-oidc-vault": "0.31.5",
+    "@web-ts-toolkit/express-oidc-vault": "0.33.0",
     "mongodb": "^6.20.0"
   },
   "files": [