@web-ts-toolkit/express-oidc-vault-memory-store 0.47.1 → 0.49.0

package/README.md

@@ -16,7 +16,7 @@ pnpm add @web-ts-toolkit/express-oidc-vault @web-ts-toolkit/express-oidc-vault-m
 
 ## Production Note
 
-This package stores authorization transactions, exchange codes, sessions, rotated-session aliases, and backchannel logout replay JTIs in process memory.
+This package stores authorization transactions, exchange codes, sessions, rotated-session aliases, backchannel logout replay JTIs, and DPoP proof reservations in process memory.
 
 Do not use it for multi-instance or production deployments. Use Redis or MongoDB provider packages for durable or horizontally scaled deployments.
 
@@ -59,7 +59,7 @@ const storeProvider = createMemoryOidcVaultStore({
 
 ## 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`.
+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`. Both ESM (`import`, `index.d.mts`) and CJS (`require`, `index.d.ts`) declaration conditions are shipped; consumer imports always use the package name.
 
 - `createMemoryOidcVaultStore(...)`
 - `type MemoryOidcVaultStoreOptions`
@@ -93,6 +93,7 @@ The store keeps these record kinds in separate in-process maps:
 - sessions, read and deleted by session, logical session, subject, or provider session identifiers
 - rotated-session aliases, used only so an old public session ID can revoke the current logical session
 - backchannel logout token JTIs, consumed once until their expiry time
+- DPoP proof reservations with their own bounded expiry heap/capacity
 
 `createAuthorizationTransaction`, `createExchangeCode`, and `createSession` are upserts; creating the same key again replaces the old value. A `createSession` replacement takes over the session ID with its own subject/logical/provider-session scope, and clears any stale rotation alias held under that ID so the reused ID cannot invoke an old logical-session meaning. Portable callers must still create sessions with a fresh unused ID and handle `OidcVaultStoreConflictError`: reusing a live ID replaces on memory/MongoDB but rejects on Redis. MongoDB also retains an alias row under a reused ID until expiry or lineage cleanup; only fresh-ID creation is portable.
 
@@ -111,3 +112,46 @@ Bulk methods return the number of live sessions removed, excluding expired recor
 ## Replay JTI Expiry
 
 Backchannel logout token JTI records are consumed only when `expiresAt` is a finite timestamp greater than the store clock at consume time. Expired, equal-to-current-time, `NaN`, and infinite expiries return `false` and are not stored.
+
+## Device-Binding Store Capabilities
+
+`createMemoryOidcVaultStore` returns the core `OidcVaultDeviceBindingStoreProvider`. Its six methods are callable directly from the inferred factory result:
+
+All shared types (`OidcVaultDeviceBindingStoreProvider`, `OidcVaultRecordBindingMatch`, guarded consume inputs, `ReserveDpopProofInput`, revocation context and capacity error) are **named root exports of `@web-ts-toolkit/express-oidc-vault`**. This package exports only its factory/options. Either vault `deviceBinding` or `fingerprintRecognition` requires all six capabilities; fingerprint-only flows do not reserve proofs. API middleware uses this store as its explicit replayStore. See the core's shipped README for the complete issuer/request-aware API and browser recipe.
+
+- `getAuthorizationTransaction(state)` / `getExchangeCode(code)`: detached live snapshots, without spending records; reads are not locks.
+- `consumeAuthorizationTransactionIfMatches({ state, match })` / `consumeExchangeCodeIfMatches({ code, expectedSessionId, match })`: synchronous expiry/complete-match/deletion before yielding; one winner for concurrent matching consumers.
+- `getSessionRevocationContext(sessionId)`: live handle or unexpired alias resolves its currently live lineage, returning only `logicalSessionId`, allowlisted `provider.issuer/clientId`, and optional `deviceBinding`. No upstream credentials, metadata or profile are returned.
+- `reserveDpopProof({ replayKey, expiresAt })`: process-object-shared atomic replay admission, described below.
+
+`match` requires both `{ deviceBinding, browserBindingHash }`; each is an exact value or **null meaning stored absence/undefined**. Null never ignores a field. Records are legacy (neither field), cookie-only (browser hash), or bound (hash + `{ type: 'dpop', jkt }`). Both hashes are canonical 43-character SHA-256 base64url. Null/malformed/extra binding fields and a key without a browser hash are invalid; writes reject, and corrupted stored data cannot yield credentials. Mismatch returns `null` without spending a live record; the honest caller may retry. Original legacy consumes refuse all guarded records, including cookie-only records, without consumption.
+
+Session rotation inherits omitted/undefined binding and accepts the same original key; it rejects null/malformed binding, a changed key, or adding a binding to an unbound source before mutation. Session IDs still follow the upsert/alias contracts above. A revocation alias never supplies historical or missing binding as proof of unboundness: all live lineage members must agree on binding/provider identity (malformed/inconsistent authority throws a fixed private diagnostic). Revocation context scans that lineage's candidates in the session map; it does not authenticate aliases through `getSession`.
+
+## Per-Request DPoP Replay And Capacity
+
+| Memory option          | Default    | Contract                                                                   |
+| ---------------------- | ---------- | -------------------------------------------------------------------------- |
+| `dpopReplayMaxEntries` | `100000`   | Positive safe integer, shared by this store object; no live eviction       |
+| `now`                  | `Date.now` | Epoch-millisecond deterministic test clock; proof/store windows must agree |
+
+Use one shared store object for every local protection-space instance. Independent memory objects/processes intentionally have independent replay state; use Redis/MongoDB for multi-instance protection. The store reserves opaque keys verbatim; shared orchestration supplies the namespace/key/JTI hash. It does not verify HTTP proofs or build namespaces itself.
+
+```ts
+import { OidcVaultDpopReplayCapacityError } from '@web-ts-toolkit/express-oidc-vault';
+import { createMemoryOidcVaultStore } from '@web-ts-toolkit/express-oidc-vault-memory-store';
+
+const replayStore = createMemoryOidcVaultStore({ dpopReplayMaxEntries: 100_000 });
+// Called only after a proof's signature, target, key and nonce are verified.
+const reserved = await replayStore.reserveDpopProof({
+  replayKey: 'opaque-protection-space-key-jti-digest',
+  expiresAt: Date.now() + 60_000,
+});
+void [reserved, OidcVaultDpopReplayCapacityError];
+```
+
+`dpopReplayMaxEntries` defaults to **100000**, and must be a positive safe integer. A duplicate returns `false` before capacity checks and never extends expiry. New reservations at capacity throw the core `OidcVaultDpopReplayCapacityError`. Live entries are never evicted. A future safe-integer expiry is required, with remaining TTL **<=360000 ms**; invalid/nonfinite/unsafe/fractional/expired (`<= now()`) or overlong windows return `false` without allocating. Expired keys may be admitted again.
+
+Replay uses a Map plus an **indexed min-heap with exactly one node per retained key**, with no unbounded stale-node accumulation or full-map snapshot rebuild. Each admission removes at most **64** expired heap nodes plus a targeted expired duplicate; insertion/removal costs O(log N). It never scans session or alias maps. Expired entries awaiting bounded cleanup may conservatively consume capacity; later new admissions reclaim them. Cleanup runs on traffic, not a timer, and the total retained replay state stays within the configured limit.
+
+DPoP reservations are **per request**, much higher-volume than logout JTIs. Size for unique proofs/second × proof-validity window plus headroom (approved defaults: at most 70 seconds retained). All instances in a protection space must use identical windows/namespaces and synchronized clocks. Never release a reservation after a later route failure; retries require a fresh proof. Capacity/provider errors must fail closed and map through orchestration to sanitized replay-unavailable, not proof acceptance. Heap bounds do not imply a fixed latency/throughput guarantee.

package/index.d.mts

@@ -1,6 +1,9 @@
-import { OidcVaultStoreProvider } from '@web-ts-toolkit/express-oidc-vault';
+import { OidcVaultDeviceBindingStoreProvider } from '@web-ts-toolkit/express-oidc-vault';
 
+/** Construction options for the named package-root memory-store factory. */
 interface MemoryOidcVaultStoreOptions {
+    /** Positive safe integer shared by this store object; default 100000. No live replay reservations are evicted. */
+    dpopReplayMaxEntries?: number;
     /**
      * Store clock in epoch milliseconds.
      *
@@ -16,8 +19,11 @@ interface MemoryOidcVaultStoreOptions {
  * Records are kept in memory, cloned on read/write, cleaned up opportunistically
  * during store operations, and lost when the Node.js process exits. Do not use
  * this provider when sessions must survive restarts or be shared by multiple
- * application instances.
+ * application instances. The returned stronger provider includes guarded
+ * exact/null consumes, token-free revocation context, and bounded DPoP replay.
+ * Replay is shared only by callers reusing this same object; the store does not
+ * verify HTTP proofs. Capacity defaults to 100000 and never evicts live entries.
  */
-declare function createMemoryOidcVaultStore(options?: MemoryOidcVaultStoreOptions): OidcVaultStoreProvider;
+declare function createMemoryOidcVaultStore(options?: MemoryOidcVaultStoreOptions): OidcVaultDeviceBindingStoreProvider;
 
 export { type MemoryOidcVaultStoreOptions, createMemoryOidcVaultStore };

package/index.d.ts

@@ -1,6 +1,9 @@
-import { OidcVaultStoreProvider } from '@web-ts-toolkit/express-oidc-vault';
+import { OidcVaultDeviceBindingStoreProvider } from '@web-ts-toolkit/express-oidc-vault';
 
+/** Construction options for the named package-root memory-store factory. */
 interface MemoryOidcVaultStoreOptions {
+    /** Positive safe integer shared by this store object; default 100000. No live replay reservations are evicted. */
+    dpopReplayMaxEntries?: number;
     /**
      * Store clock in epoch milliseconds.
      *
@@ -16,8 +19,11 @@ interface MemoryOidcVaultStoreOptions {
  * Records are kept in memory, cloned on read/write, cleaned up opportunistically
  * during store operations, and lost when the Node.js process exits. Do not use
  * this provider when sessions must survive restarts or be shared by multiple
- * application instances.
+ * application instances. The returned stronger provider includes guarded
+ * exact/null consumes, token-free revocation context, and bounded DPoP replay.
+ * Replay is shared only by callers reusing this same object; the store does not
+ * verify HTTP proofs. Capacity defaults to 100000 and never evicts live entries.
  */
-declare function createMemoryOidcVaultStore(options?: MemoryOidcVaultStoreOptions): OidcVaultStoreProvider;
+declare function createMemoryOidcVaultStore(options?: MemoryOidcVaultStoreOptions): OidcVaultDeviceBindingStoreProvider;
 
 export { type MemoryOidcVaultStoreOptions, createMemoryOidcVaultStore };

package/index.js

@@ -23,7 +23,122 @@ __export(index_exports, {
   createMemoryOidcVaultStore: () => createMemoryOidcVaultStore
 });
 module.exports = __toCommonJS(index_exports);
+var import_express_oidc_vault3 = require("@web-ts-toolkit/express-oidc-vault");
+
+// src/binding.ts
 var import_express_oidc_vault = require("@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 import_express_oidc_vault.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
+var import_express_oidc_vault2 = require("@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 import_express_oidc_vault2.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;
@@ -60,50 +175,88 @@ var MemoryOidcVaultStore = class {
     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.pruneMapBatch(this.authorizationTransactions, this.authorizationTransactionSweep, now);
-    this.authorizationTransactions.set(input.state, cloneRecord(input));
+    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.pruneMapBatch(this.authorizationTransactions, this.authorizationTransactionSweep, now);
-    const record = this.authorizationTransactions.get(state);
-    if (!record) {
-      return null;
-    }
-    this.authorizationTransactions.delete(state);
-    if (isExpiredRecord(record, 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(input.state);
     return cloneRecord(record);
   }
   async createExchangeCode(input) {
+    input = cloneRecord(input);
+    assertRecordBinding(input);
     const now = this.now();
     this.pruneMapBatch(this.exchangeCodes, this.exchangeCodeSweep, now);
-    this.exchangeCodes.set(input.code, cloneRecord(input));
+    this.exchangeCodes.set(input.code, input);
   }
   async consumeExchangeCode(code) {
     const now = this.now();
     this.pruneMapBatch(this.exchangeCodes, this.exchangeCodeSweep, now);
-    const record = this.exchangeCodes.get(code);
-    if (!record) {
+    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.pruneMapBatch(this.rotatedSessionAliases, this.rotatedSessionAliasSweep, timestamp);
     const session = {
-      ...cloneRecord(input),
+      ...input,
       logicalSessionId: input.logicalSessionId ?? input.sessionId,
       createdAt: input.createdAt ?? timestamp,
       updatedAt: input.updatedAt ?? timestamp
@@ -125,7 +278,37 @@ var MemoryOidcVaultStore = class {
       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();
@@ -135,17 +318,18 @@ var MemoryOidcVaultStore = class {
       this.removeAliasesForInactiveLogicalSession(sourceSession.logicalSessionId ?? sourceSession.sessionId, timestamp);
     }
     const liveSourceSession = this.sessions.get(input.sessionId);
-    if (!liveSourceSession) {
-      throw new import_express_oidc_vault.OidcVaultStoreConflictError("OIDC vault session no longer exists for rotation.");
+    if (!liveSourceSession || !hasValidSessionRecord(liveSourceSession, input.sessionId)) {
+      throw new import_express_oidc_vault3.OidcVaultStoreConflictError("OIDC vault session no longer exists for rotation.");
     }
     if (input.nextSession.sessionId === input.sessionId) {
-      throw new import_express_oidc_vault.OidcVaultStoreConflictError("OIDC vault session rotation target must use a different session ID.");
+      throw new import_express_oidc_vault3.OidcVaultStoreConflictError("OIDC vault session rotation target must use a different session ID.");
     }
     const existingTargetSession = this.sessions.get(input.nextSession.sessionId);
     if (existingTargetSession && !isExpiredRecord(existingTargetSession, timestamp)) {
-      throw new import_express_oidc_vault.OidcVaultStoreConflictError("OIDC vault session rotation target already exists.");
+      throw new import_express_oidc_vault3.OidcVaultStoreConflictError("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,

package/index.mjs

@@ -1,7 +1,122 @@
 // 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;
@@ -38,50 +153,88 @@ var MemoryOidcVaultStore = class {
     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.pruneMapBatch(this.authorizationTransactions, this.authorizationTransactionSweep, now);
-    this.authorizationTransactions.set(input.state, cloneRecord(input));
+    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.pruneMapBatch(this.authorizationTransactions, this.authorizationTransactionSweep, now);
-    const record = this.authorizationTransactions.get(state);
-    if (!record) {
+    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.pruneMapBatch(this.exchangeCodes, this.exchangeCodeSweep, now);
-    this.exchangeCodes.set(input.code, cloneRecord(input));
+    this.exchangeCodes.set(input.code, input);
   }
   async consumeExchangeCode(code) {
     const now = this.now();
     this.pruneMapBatch(this.exchangeCodes, this.exchangeCodeSweep, now);
-    const record = this.exchangeCodes.get(code);
-    if (!record) {
+    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.pruneMapBatch(this.rotatedSessionAliases, this.rotatedSessionAliasSweep, timestamp);
     const session = {
-      ...cloneRecord(input),
+      ...input,
       logicalSessionId: input.logicalSessionId ?? input.sessionId,
       createdAt: input.createdAt ?? timestamp,
       updatedAt: input.updatedAt ?? timestamp
@@ -103,7 +256,37 @@ var MemoryOidcVaultStore = class {
       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();
@@ -113,17 +296,18 @@ var MemoryOidcVaultStore = class {
       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)) {
-      throw new OidcVaultStoreConflictError("OIDC vault session rotation target already exists.");
+      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,

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.47.1",
+  "version": "0.49.0",
   "sideEffects": false,
   "keywords": [
     "express",
@@ -26,10 +26,10 @@
     }
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.12.0"
   },
   "dependencies": {
-    "@web-ts-toolkit/express-oidc-vault": "0.47.1"
+    "@web-ts-toolkit/express-oidc-vault": "0.49.0"
   },
   "files": [
     "**/*",