@web-ts-toolkit/express-oidc-vault-memory-store 0.43.0 → 0.48.0

package/index.mjs

@@ -1,10 +1,133 @@
 // src/index.ts
 import {
-  OidcVaultStoreConflictError
+  OidcVaultStoreConflictError as OidcVaultStoreConflictError2
 } from "@web-ts-toolkit/express-oidc-vault";
+
+// src/binding.ts
+import { OidcVaultStoreConflictError } from "@web-ts-toolkit/express-oidc-vault";
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+var isHash = (value) => typeof value === "string" && value.length === 43 && /^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/.test(value);
+var isBinding = (value) => isRecord(value) && Object.keys(value).length === 2 && Object.hasOwn(value, "type") && Object.hasOwn(value, "jkt") && value.type === "dpop" && isHash(value.jkt);
+var hasValidBinding = (record) => record.deviceBinding === void 0 || isBinding(record.deviceBinding);
+var hasValidRecordBinding = (record) => hasValidBinding(record) && (record.browserBindingHash === void 0 || isHash(record.browserBindingHash)) && (record.deviceBinding === void 0 || record.browserBindingHash !== void 0);
+var assertRecordBinding = (record) => {
+  if (!hasValidRecordBinding(record))
+    throw new TypeError("OIDC vault store record has invalid device/browser binding.");
+};
+var assertSessionBinding = (record) => {
+  if (!hasValidBinding(record)) throw new TypeError("OIDC vault store session has invalid device binding.");
+};
+var isBindingMatch = (match) => isRecord(match) && Object.hasOwn(match, "deviceBinding") && Object.hasOwn(match, "browserBindingHash") && (match.deviceBinding === null || isBinding(match.deviceBinding)) && (match.browserBindingHash === null || isHash(match.browserBindingHash));
+var matchesRecordBinding = (record, match) => (match.deviceBinding === null ? record.deviceBinding === void 0 : record.deviceBinding?.type === match.deviceBinding.type && record.deviceBinding.jkt === match.deviceBinding.jkt) && (match.browserBindingHash === null ? record.browserBindingHash === void 0 : record.browserBindingHash === match.browserBindingHash);
+var inheritSessionBinding = (source, next) => {
+  assertSessionBinding(source);
+  assertSessionBinding(next);
+  if (next.deviceBinding !== void 0 && next.deviceBinding.jkt !== source.deviceBinding?.jkt) {
+    throw new OidcVaultStoreConflictError("OIDC vault session rotation cannot change or add device binding.");
+  }
+  if (source.deviceBinding !== void 0) next.deviceBinding = { type: "dpop", jkt: source.deviceBinding.jkt };
+};
+var sessionRevocationContext = (session) => {
+  assertSessionBinding(session);
+  if (typeof session.sessionId !== "string" || typeof session.subject !== "string" || session.logicalSessionId !== void 0 && typeof session.logicalSessionId !== "string") {
+    throw new Error("OIDC vault store lineage has malformed session authority.");
+  }
+  const provider = session.provider;
+  if (provider !== void 0 && (!isRecord(provider) || provider.issuer !== void 0 && typeof provider.issuer !== "string" || provider.clientId !== void 0 && typeof provider.clientId !== "string")) {
+    throw new Error("OIDC vault store lineage has malformed provider identity.");
+  }
+  return {
+    logicalSessionId: session.logicalSessionId ?? session.sessionId,
+    ...provider === void 0 ? {} : {
+      provider: {
+        ...typeof provider.issuer === "string" ? { issuer: provider.issuer } : {},
+        ...typeof provider.clientId === "string" ? { clientId: provider.clientId } : {}
+      }
+    },
+    ...session.deviceBinding === void 0 ? {} : { deviceBinding: { ...session.deviceBinding } }
+  };
+};
+var hasValidSessionRecord = (session, sessionId) => session.sessionId === sessionId && typeof session.subject === "string" && (session.logicalSessionId === void 0 || typeof session.logicalSessionId === "string") && typeof session.refreshToken === "string" && typeof session.idToken === "string" && (session.expiresAt === void 0 || Number.isFinite(session.expiresAt)) && hasValidBinding(session);
+var assertSameLineageAuthority = (source, member) => {
+  assertSessionBinding(member);
+  const authority = sessionRevocationContext(member);
+  if (source.deviceBinding?.jkt !== authority.deviceBinding?.jkt || source.subject !== member.subject || source.provider?.issuer !== authority.provider?.issuer || source.provider?.clientId !== authority.provider?.clientId) {
+    throw new Error("OIDC vault store lineage has inconsistent device binding or provider identity.");
+  }
+};
+
+// src/dpop-replay.ts
+import { OidcVaultDpopReplayCapacityError } from "@web-ts-toolkit/express-oidc-vault";
+var DpopReplayReservations = class {
+  constructor(maxEntries) {
+    this.maxEntries = maxEntries;
+    this.reservations = /* @__PURE__ */ new Map();
+    this.expiryHeap = [];
+  }
+  reserve({ replayKey, expiresAt }, now) {
+    if (!Number.isFinite(now)) throw new Error("OIDC vault DPoP replay store clock is invalid.");
+    if (typeof replayKey !== "string" || !Number.isSafeInteger(expiresAt) || expiresAt <= now || expiresAt - now > 36e4) {
+      return false;
+    }
+    const existing = this.reservations.get(replayKey);
+    if (existing && existing.expiresAt > now) return false;
+    if (existing) this.remove(existing.index);
+    for (let cleaned = 0; cleaned < 64 && this.expiryHeap[0]?.expiresAt <= now; cleaned += 1) this.remove(0);
+    if (this.reservations.size >= this.maxEntries) throw new OidcVaultDpopReplayCapacityError();
+    const reservation = { replayKey, expiresAt, index: this.expiryHeap.length };
+    this.reservations.set(replayKey, reservation);
+    this.expiryHeap.push(reservation);
+    this.moveUp(reservation.index);
+    return true;
+  }
+  remove(index) {
+    const removed = this.expiryHeap[index];
+    const last = this.expiryHeap.pop();
+    this.reservations.delete(removed.replayKey);
+    if (index === this.expiryHeap.length) return;
+    this.expiryHeap[index] = last;
+    last.index = index;
+    this.moveUp(index);
+    this.moveDown(last.index);
+  }
+  swap(left, right) {
+    [this.expiryHeap[left], this.expiryHeap[right]] = [this.expiryHeap[right], this.expiryHeap[left]];
+    this.expiryHeap[left].index = left;
+    this.expiryHeap[right].index = right;
+  }
+  moveUp(index) {
+    while (index > 0) {
+      const parent = Math.floor((index - 1) / 2);
+      if (this.expiryHeap[parent].expiresAt <= this.expiryHeap[index].expiresAt) break;
+      this.swap(parent, index);
+      index = parent;
+    }
+  }
+  moveDown(index) {
+    for (; ; ) {
+      const left = index * 2 + 1;
+      if (left >= this.expiryHeap.length) return;
+      const right = left + 1;
+      const child = right < this.expiryHeap.length && this.expiryHeap[right].expiresAt < this.expiryHeap[left].expiresAt ? right : left;
+      if (this.expiryHeap[index].expiresAt <= this.expiryHeap[child].expiresAt) return;
+      this.swap(index, child);
+      index = child;
+    }
+  }
+};
+
+// src/index.ts
 var cloneRecord = (value) => structuredClone(value);
 var isExpiredRecord = (value, now) => typeof value.expiresAt === "number" && value.expiresAt <= now;
 var EXPIRY_SWEEP_BATCH_SIZE = 64;
+var createMapSweepState = () => ({ keys: [], position: 0 });
+var createMemoryStoreSweepWork = () => ({
+  inspectedKeys: 0,
+  staleSnapshotSlots: 0,
+  snapshotRebuilds: 0,
+  aliasSessionVisits: 0,
+  aliasEntryVisits: 0
+});
 var matchesProviderScope = (session, input) => {
   if (input.issuer !== void 0 && session.provider?.issuer !== input.issuer) {
     return false;
@@ -24,68 +147,105 @@ var MemoryOidcVaultStore = class {
     this.sessions = /* @__PURE__ */ new Map();
     this.rotatedSessionAliases = /* @__PURE__ */ new Map();
     this.backchannelLogoutTokenJtis = /* @__PURE__ */ new Map();
+    this.authorizationTransactionSweep = createMapSweepState();
+    this.exchangeCodeSweep = createMapSweepState();
+    this.sessionSweep = createMapSweepState();
+    this.rotatedSessionAliasSweep = createMapSweepState();
+    this.backchannelLogoutTokenJtiSweep = createMapSweepState();
+    this.sweepWork = createMemoryStoreSweepWork();
+    const maxEntries = options.dpopReplayMaxEntries === void 0 ? 1e5 : options.dpopReplayMaxEntries;
+    if (!Number.isSafeInteger(maxEntries) || maxEntries <= 0) {
+      throw new TypeError("OIDC vault DPoP replay maximum entries must be a positive safe integer.");
+    }
+    this.dpopProofs = new DpopReplayReservations(maxEntries);
     this.now = options.now ?? (() => Date.now());
   }
   async createAuthorizationTransaction(input) {
+    input = cloneRecord(input);
+    assertRecordBinding(input);
     const now = this.now();
-    this.authorizationTransactionSweepCursor = this.pruneMapBatch(
-      this.authorizationTransactions,
-      now,
-      this.authorizationTransactionSweepCursor
-    );
-    this.authorizationTransactions.set(input.state, cloneRecord(input));
+    this.pruneMapBatch(this.authorizationTransactions, this.authorizationTransactionSweep, now);
+    this.authorizationTransactions.set(input.state, input);
   }
   async consumeAuthorizationTransaction(state) {
+    return this.consumeAuthorizationTransactionIfMatches({
+      state,
+      match: { deviceBinding: null, browserBindingHash: null }
+    });
+  }
+  async getAuthorizationTransaction(state) {
+    const record = this.readOneTimeRecord(this.authorizationTransactions, state, this.now());
+    return record && record.state === state && typeof record.nonce === "string" && typeof record.pkceVerifier === "string" && typeof record.codeChallenge === "string" ? cloneRecord(record) : null;
+  }
+  async consumeAuthorizationTransactionIfMatches(input) {
+    input = cloneRecord(input);
+    if (!isBindingMatch(input.match)) return null;
     const now = this.now();
-    this.authorizationTransactionSweepCursor = this.pruneMapBatch(
-      this.authorizationTransactions,
-      now,
-      this.authorizationTransactionSweepCursor
-    );
-    const record = this.authorizationTransactions.get(state);
-    if (!record) {
+    this.pruneMapBatch(this.authorizationTransactions, this.authorizationTransactionSweep, now);
+    const record = this.readOneTimeRecord(this.authorizationTransactions, input.state, now);
+    if (!record || record.state !== input.state || typeof record.nonce !== "string" || typeof record.pkceVerifier !== "string" || typeof record.codeChallenge !== "string" || !matchesRecordBinding(record, input.match))
       return null;
-    }
-    this.authorizationTransactions.delete(state);
-    if (isExpiredRecord(record, now)) {
-      return null;
-    }
+    this.authorizationTransactions.delete(input.state);
     return cloneRecord(record);
   }
   async createExchangeCode(input) {
+    input = cloneRecord(input);
+    assertRecordBinding(input);
     const now = this.now();
-    this.exchangeCodeSweepCursor = this.pruneMapBatch(this.exchangeCodes, now, this.exchangeCodeSweepCursor);
-    this.exchangeCodes.set(input.code, cloneRecord(input));
+    this.pruneMapBatch(this.exchangeCodes, this.exchangeCodeSweep, now);
+    this.exchangeCodes.set(input.code, input);
   }
   async consumeExchangeCode(code) {
     const now = this.now();
-    this.exchangeCodeSweepCursor = this.pruneMapBatch(this.exchangeCodes, now, this.exchangeCodeSweepCursor);
-    const record = this.exchangeCodes.get(code);
-    if (!record) {
+    this.pruneMapBatch(this.exchangeCodes, this.exchangeCodeSweep, now);
+    return this.consumeExchangeRecord(code, { deviceBinding: null, browserBindingHash: null }, now);
+  }
+  async getExchangeCode(code) {
+    const record = this.readOneTimeRecord(this.exchangeCodes, code, this.now());
+    return record && record.code === code && typeof record.sessionId === "string" ? cloneRecord(record) : null;
+  }
+  async consumeExchangeCodeIfMatches(input) {
+    input = cloneRecord(input);
+    if (!isBindingMatch(input.match) || typeof input.expectedSessionId !== "string") return null;
+    const now = this.now();
+    this.pruneMapBatch(this.exchangeCodes, this.exchangeCodeSweep, now);
+    return this.consumeExchangeRecord(input.code, input.match, now, input.expectedSessionId);
+  }
+  consumeExchangeRecord(code, match, now, expectedSessionId) {
+    const record = this.readOneTimeRecord(this.exchangeCodes, code, now);
+    if (!record || record.code !== code || typeof record.sessionId !== "string" || expectedSessionId !== void 0 && record.sessionId !== expectedSessionId || !matchesRecordBinding(record, match))
       return null;
-    }
     this.exchangeCodes.delete(code);
-    if (isExpiredRecord(record, now)) {
+    return cloneRecord(record);
+  }
+  readOneTimeRecord(map, id, now) {
+    const record = map.get(id);
+    if (!record) return null;
+    if (!Number.isFinite(record.createdAt) || !Number.isFinite(record.expiresAt) || isExpiredRecord(record, now) || !hasValidRecordBinding(record)) {
+      map.delete(id);
       return null;
     }
-    return cloneRecord(record);
+    return record;
   }
   async createSession(input) {
+    input = cloneRecord(input);
+    assertSessionBinding(input);
     const timestamp = this.now();
     this.pruneSessionsBatch(timestamp);
-    this.rotatedSessionAliasSweepCursor = this.pruneMapBatch(
-      this.rotatedSessionAliases,
-      timestamp,
-      this.rotatedSessionAliasSweepCursor
-    );
+    this.pruneMapBatch(this.rotatedSessionAliases, this.rotatedSessionAliasSweep, timestamp);
     const session = {
-      ...cloneRecord(input),
+      ...input,
       logicalSessionId: input.logicalSessionId ?? input.sessionId,
       createdAt: input.createdAt ?? timestamp,
       updatedAt: input.updatedAt ?? timestamp
     };
+    const previousSession = this.sessions.get(session.sessionId);
+    const previousLogicalSessionId = previousSession?.logicalSessionId ?? previousSession?.sessionId;
     this.sessions.set(session.sessionId, session);
     this.rotatedSessionAliases.delete(session.sessionId);
+    if (previousLogicalSessionId !== void 0 && previousLogicalSessionId !== session.logicalSessionId) {
+      this.removeAliasesForInactiveLogicalSession(previousLogicalSessionId, timestamp);
+    }
     return cloneRecord(session);
   }
   async getSession(sessionId) {
@@ -93,63 +253,97 @@ var MemoryOidcVaultStore = class {
     const session = this.sessions.get(sessionId);
     if (session && isExpiredRecord(session, now)) {
       this.sessions.delete(sessionId);
-      this.removeAliasesForInactiveLogicalSession(session.logicalSessionId ?? session.sessionId);
+      this.removeAliasesForInactiveLogicalSession(session.logicalSessionId ?? session.sessionId, now);
       return null;
     }
-    return session ? cloneRecord(session) : null;
+    return session && hasValidSessionRecord(session, sessionId) ? cloneRecord(session) : null;
+  }
+  async getSessionRevocationContext(sessionId) {
+    const now = this.now();
+    const live = this.sessions.get(sessionId);
+    const alias = this.rotatedSessionAliases.get(sessionId);
+    if (live && !isExpiredRecord(live, now)) {
+      if (live.sessionId !== sessionId) throw new Error("OIDC vault store has malformed revocation authority.");
+      sessionRevocationContext(live);
+    }
+    if ((!live || isExpiredRecord(live, now)) && alias && (typeof alias.logicalSessionId !== "string" || alias.expiresAt !== void 0 && !Number.isFinite(alias.expiresAt))) {
+      throw new Error("OIDC vault store has malformed revocation alias.");
+    }
+    const logicalSessionId = live && !isExpiredRecord(live, now) ? live.logicalSessionId ?? live.sessionId : alias && !isExpiredRecord(alias, now) ? alias.logicalSessionId : void 0;
+    if (logicalSessionId === void 0) return null;
+    if (typeof logicalSessionId !== "string") throw new Error("OIDC vault store has malformed revocation authority.");
+    let source;
+    for (const member of this.sessions.values()) {
+      if ((member.logicalSessionId ?? member.sessionId) !== logicalSessionId || isExpiredRecord(member, now)) continue;
+      if (member.sessionId === void 0 || typeof member.subject !== "string" || member.expiresAt !== void 0 && !Number.isFinite(member.expiresAt)) {
+        throw new Error("OIDC vault store lineage has malformed session authority.");
+      }
+      sessionRevocationContext(member);
+      if (source) assertSameLineageAuthority(source, member);
+      else source = member;
+    }
+    return source ? sessionRevocationContext(source) : null;
+  }
+  async reserveDpopProof(input) {
+    input = { replayKey: input.replayKey, expiresAt: input.expiresAt };
+    return this.dpopProofs.reserve(input, this.now());
   }
   async rotateSession(input) {
     const timestamp = this.now();
     const sourceSession = this.sessions.get(input.sessionId);
     if (sourceSession && isExpiredRecord(sourceSession, timestamp)) {
       this.sessions.delete(input.sessionId);
-      this.removeAliasesForInactiveLogicalSession(sourceSession.logicalSessionId ?? sourceSession.sessionId);
+      this.removeAliasesForInactiveLogicalSession(sourceSession.logicalSessionId ?? sourceSession.sessionId, timestamp);
     }
     const liveSourceSession = this.sessions.get(input.sessionId);
-    if (!liveSourceSession) {
-      throw new OidcVaultStoreConflictError("OIDC vault session no longer exists for rotation.");
+    if (!liveSourceSession || !hasValidSessionRecord(liveSourceSession, input.sessionId)) {
+      throw new OidcVaultStoreConflictError2("OIDC vault session no longer exists for rotation.");
     }
     if (input.nextSession.sessionId === input.sessionId) {
-      throw new OidcVaultStoreConflictError("OIDC vault session rotation target must use a different session ID.");
+      throw new OidcVaultStoreConflictError2("OIDC vault session rotation target must use a different session ID.");
     }
     const existingTargetSession = this.sessions.get(input.nextSession.sessionId);
-    if (existingTargetSession && isExpiredRecord(existingTargetSession, timestamp)) {
-      this.sessions.delete(input.nextSession.sessionId);
-      this.removeAliasesForInactiveLogicalSession(
-        existingTargetSession.logicalSessionId ?? existingTargetSession.sessionId
-      );
-    } else if (existingTargetSession) {
-      throw new OidcVaultStoreConflictError("OIDC vault session rotation target already exists.");
+    if (existingTargetSession && !isExpiredRecord(existingTargetSession, timestamp)) {
+      throw new OidcVaultStoreConflictError2("OIDC vault session rotation target already exists.");
     }
     const nextSession = cloneRecord(input.nextSession);
+    inheritSessionBinding(liveSourceSession, nextSession);
     const session = {
       ...nextSession,
       logicalSessionId: nextSession.logicalSessionId ?? liveSourceSession.logicalSessionId ?? liveSourceSession.sessionId,
       createdAt: nextSession.createdAt ?? timestamp,
       updatedAt: nextSession.updatedAt ?? timestamp
     };
+    if (existingTargetSession) {
+      this.sessions.delete(session.sessionId);
+      this.removeAliasesForInactiveLogicalSession(
+        existingTargetSession.logicalSessionId ?? existingTargetSession.sessionId,
+        timestamp
+      );
+    }
+    const previousLogicalSessionId = liveSourceSession.logicalSessionId ?? liveSourceSession.sessionId;
     this.sessions.delete(input.sessionId);
     this.sessions.set(session.sessionId, session);
+    this.rotatedSessionAliases.delete(session.sessionId);
     this.rotatedSessionAliases.set(input.sessionId, {
       logicalSessionId: session.logicalSessionId ?? session.sessionId,
       expiresAt: session.expiresAt
     });
+    if (previousLogicalSessionId !== session.logicalSessionId) {
+      this.removeAliasesForInactiveLogicalSession(previousLogicalSessionId, timestamp);
+    }
     return cloneRecord(session);
   }
   async deleteSession(sessionId) {
     const now = this.now();
     this.pruneSessionsBatch(now);
-    this.rotatedSessionAliasSweepCursor = this.pruneMapBatch(
-      this.rotatedSessionAliases,
-      now,
-      this.rotatedSessionAliasSweepCursor
-    );
+    this.pruneMapBatch(this.rotatedSessionAliases, this.rotatedSessionAliasSweep, now);
     const session = this.sessions.get(sessionId);
     if (session) {
       const logicalSessionId = session.logicalSessionId ?? session.sessionId;
       this.sessions.delete(sessionId);
       this.rotatedSessionAliases.delete(sessionId);
-      this.removeAliasesForInactiveLogicalSession(logicalSessionId);
+      this.removeAliasesForInactiveLogicalSession(logicalSessionId, now);
       return;
     }
     const alias = this.rotatedSessionAliases.get(sessionId);
@@ -178,17 +372,13 @@ var MemoryOidcVaultStore = class {
         deleted += 1;
       }
     }
-    this.removeAliasesForInactiveLogicalSessions(expiredLogicalSessionIds);
+    this.removeAliasesForInactiveLogicalSessions(expiredLogicalSessionIds, now);
     this.removeAliasesForLogicalSession(resolved.logicalSessionId);
     return deleted;
   }
   async consumeBackchannelLogoutTokenJti(input) {
     const now = this.now();
-    this.backchannelLogoutTokenJtiSweepCursor = this.pruneMapBatch(
-      this.backchannelLogoutTokenJtis,
-      now,
-      this.backchannelLogoutTokenJtiSweepCursor
-    );
+    this.pruneMapBatch(this.backchannelLogoutTokenJtis, this.backchannelLogoutTokenJtiSweep, now);
     if (!Number.isFinite(input.expiresAt) || input.expiresAt <= now) {
       return false;
     }
@@ -217,8 +407,8 @@ var MemoryOidcVaultStore = class {
         deleted += 1;
       }
     }
-    this.removeAliasesForInactiveLogicalSessions(expiredLogicalSessionIds);
-    this.removeAliasesForInactiveLogicalSessions(logicalSessionIds);
+    this.removeAliasesForInactiveLogicalSessions(expiredLogicalSessionIds, now);
+    this.removeAliasesForInactiveLogicalSessions(logicalSessionIds, now);
     return deleted;
   }
   async deleteSessionsByProviderSessionId(input) {
@@ -239,83 +429,118 @@ var MemoryOidcVaultStore = class {
         deleted += 1;
       }
     }
-    this.removeAliasesForInactiveLogicalSessions(expiredLogicalSessionIds);
-    this.removeAliasesForInactiveLogicalSessions(logicalSessionIds);
+    this.removeAliasesForInactiveLogicalSessions(expiredLogicalSessionIds, now);
+    this.removeAliasesForInactiveLogicalSessions(logicalSessionIds, now);
     return deleted;
   }
-  pruneMapBatch(map, now, cursor) {
-    let inspected = 0;
-    let nextCursor;
-    for (const [key, value] of this.entriesAfterCursor(map, cursor)) {
+  pruneMapBatch(map, sweep, now) {
+    if (map.size === 0) {
+      sweep.keys = [];
+      sweep.position = 0;
+      return;
+    }
+    if (sweep.position >= sweep.keys.length) {
+      this.rebuildSweepSnapshot(map, sweep);
+    }
+    let visited = 0;
+    while (visited < EXPIRY_SWEEP_BATCH_SIZE) {
+      if (sweep.position >= sweep.keys.length) {
+        if (map.size <= sweep.keys.length) {
+          break;
+        }
+        this.rebuildSweepSnapshot(map, sweep);
+      }
+      const key = sweep.keys[sweep.position];
+      sweep.position += 1;
+      visited += 1;
+      const value = map.get(key);
+      if (value === void 0) {
+        this.sweepWork.staleSnapshotSlots += 1;
+        continue;
+      }
+      this.sweepWork.inspectedKeys += 1;
       if (isExpiredRecord(value, now)) {
         map.delete(key);
       }
-      inspected += 1;
-      nextCursor = key;
-      if (inspected >= EXPIRY_SWEEP_BATCH_SIZE) {
-        return nextCursor;
-      }
     }
-    return void 0;
   }
-  pruneSessionsBatch(now) {
-    const expiredLogicalSessionIds = /* @__PURE__ */ new Set();
-    let inspected = 0;
-    for (const [sessionId, session] of this.entriesAfterCursor(this.sessions, this.sessionSweepCursor)) {
-      if (isExpiredRecord(session, now)) {
-        expiredLogicalSessionIds.add(session.logicalSessionId ?? session.sessionId);
-        this.sessions.delete(sessionId);
-      }
-      inspected += 1;
-      this.sessionSweepCursor = sessionId;
-      if (inspected >= EXPIRY_SWEEP_BATCH_SIZE) {
-        this.removeAliasesForInactiveLogicalSessions(expiredLogicalSessionIds);
-        return;
-      }
-    }
-    this.sessionSweepCursor = void 0;
-    this.removeAliasesForInactiveLogicalSessions(expiredLogicalSessionIds);
+  rebuildSweepSnapshot(map, sweep) {
+    sweep.keys = Array.from(map.keys());
+    sweep.position = 0;
+    this.sweepWork.snapshotRebuilds += 1;
   }
-  *entriesAfterCursor(map, cursor) {
-    if (!cursor || !map.has(cursor)) {
-      yield* map.entries();
+  pruneSessionsBatch(now) {
+    const sweep = this.sessionSweep;
+    if (this.sessions.size === 0) {
+      sweep.keys = [];
+      sweep.position = 0;
       return;
     }
-    let foundCursor = false;
-    for (const entry of map.entries()) {
-      if (!foundCursor) {
-        foundCursor = entry[0] === cursor;
+    if (sweep.position >= sweep.keys.length) {
+      this.rebuildSweepSnapshot(this.sessions, sweep);
+    }
+    const expiredLogicalSessionIds = /* @__PURE__ */ new Set();
+    let visited = 0;
+    while (visited < EXPIRY_SWEEP_BATCH_SIZE) {
+      if (sweep.position >= sweep.keys.length) {
+        if (this.sessions.size <= sweep.keys.length) {
+          break;
+        }
+        this.rebuildSweepSnapshot(this.sessions, sweep);
+      }
+      const sessionId = sweep.keys[sweep.position];
+      sweep.position += 1;
+      visited += 1;
+      const session = this.sessions.get(sessionId);
+      if (session === void 0) {
+        this.sweepWork.staleSnapshotSlots += 1;
         continue;
       }
-      yield entry;
-    }
-    for (const entry of map.entries()) {
-      if (entry[0] === cursor) {
-        return;
+      this.sweepWork.inspectedKeys += 1;
+      if (isExpiredRecord(session, now)) {
+        expiredLogicalSessionIds.add(session.logicalSessionId ?? session.sessionId);
+        this.sessions.delete(sessionId);
       }
-      yield entry;
     }
+    this.removeAliasesForInactiveLogicalSessions(expiredLogicalSessionIds, now);
   }
-  removeAliasesForInactiveLogicalSessions(logicalSessionIds) {
+  removeAliasesForInactiveLogicalSessions(logicalSessionIds, now) {
     for (const logicalSessionId of logicalSessionIds) {
-      this.removeAliasesForInactiveLogicalSession(logicalSessionId);
+      this.removeAliasesForInactiveLogicalSession(logicalSessionId, now);
     }
   }
-  removeAliasesForInactiveLogicalSession(logicalSessionId) {
-    if (!this.hasLiveSessionForLogicalSession(logicalSessionId)) {
+  removeAliasesForInactiveLogicalSession(logicalSessionId, now) {
+    if (!this.hasLiveSessionForLogicalSession(logicalSessionId, now)) {
       this.removeAliasesForLogicalSession(logicalSessionId);
     }
   }
-  hasLiveSessionForLogicalSession(logicalSessionId) {
+  /**
+   * Residual cost note (SVH-04): liveness is a full scan of `sessions`
+   * (early-out on the first live member), so per retired logical lineage the
+   * cleanup work is proportional to retained sessions, not to the 64-entry sweep
+   * batch. Visits are counted in `sweepWork.aliasSessionVisits` so this
+   * nested cost stays measurable and is never implied to be constant-time.
+   */
+  hasLiveSessionForLogicalSession(logicalSessionId, now) {
     for (const session of this.sessions.values()) {
-      if ((session.logicalSessionId ?? session.sessionId) === logicalSessionId) {
+      this.sweepWork.aliasSessionVisits += 1;
+      if ((session.logicalSessionId ?? session.sessionId) === logicalSessionId && !isExpiredRecord(session, now)) {
         return true;
       }
     }
     return false;
   }
+  /**
+   * Residual cost note (SVH-04): alias removal scans every
+   * `rotatedSessionAliases` entry for the lineage, so per expired lineage the
+   * work is proportional to live aliases. Visits are counted in
+   * `sweepWork.aliasEntryVisits`. Bounding this further would need a
+   * lineage-to-alias index; that was deferred as unjustified complexity for
+   * the measured workloads (see README sweep-bounds note).
+   */
   removeAliasesForLogicalSession(logicalSessionId) {
     for (const [sessionId, alias] of this.rotatedSessionAliases.entries()) {
+      this.sweepWork.aliasEntryVisits += 1;
       if (alias.logicalSessionId === logicalSessionId) {
         this.rotatedSessionAliases.delete(sessionId);
       }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/express-oidc-vault-memory-store",
   "description": "In-memory store provider for @web-ts-toolkit/express-oidc-vault",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/express-oidc-vault-memory-store",
-  "version": "0.43.0",
+  "version": "0.48.0",
   "sideEffects": false,
   "keywords": [
     "express",
@@ -26,10 +26,10 @@
     }
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.12.0"
   },
   "dependencies": {
-    "@web-ts-toolkit/express-oidc-vault": "0.43.0"
+    "@web-ts-toolkit/express-oidc-vault": "0.48.0"
   },
   "files": [
     "**/*",