@blamejs/blamejs-shop 0.5.5 → 0.5.6

package/lib/vendor/blamejs/lib/auth/lockout.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
 "use strict";
 /**
  * b.auth.lockout — per-key failed-attempt tracking with exponential
@@ -90,6 +92,11 @@ var observability = lazyRequire(function () { return require("../observability")
 
 var _err = LockoutError.factory;
 
+// Default duration for an operator-forced lock() (ATO kill-switch / incident
+// response) when neither untilMs nor durationMs is supplied — long enough to
+// require an explicit admin unlock() during an active incident.
+var DEFAULT_ADMIN_LOCK_MS = C.TIME.hours(24);
+
 var DEFAULTS = Object.freeze({
   maxAttempts:     5,
   windowMs:        C.TIME.minutes(15),
@@ -161,10 +168,11 @@ function create(opts) {
 
   if (!opts.cache || typeof opts.cache !== "object" ||
       typeof opts.cache.get !== "function" ||
-      typeof opts.cache.set !== "function" ||
-      typeof opts.cache.del !== "function") {
+      typeof opts.cache.del !== "function" ||
+      typeof opts.cache.update !== "function") {
     throw _err("BAD_OPT", "auth.lockout.create: opts.cache must be a b.cache " +
-               "instance (or shape with get/set/del). Pass b.cache.create({...}).");
+               "instance (or shape with get/del/update — the failure counter needs " +
+               "an atomic update). Pass b.cache.create({...}).");
   }
   _requireString("namespace", opts.namespace);
 
@@ -172,7 +180,11 @@ function create(opts) {
   _requirePositiveInt("maxAttempts", maxAttempts);
 
   var windowMs = opts.windowMs !== undefined ? opts.windowMs : DEFAULTS.windowMs;
-  _requireNonNegFinite("windowMs", windowMs);
+  // windowMs must be POSITIVE: a 0 window makes every failure "decay" on the
+  // next request (the `now - lastFailureAt > windowMs` reset fires for any
+  // elapsed time) so the counter never reaches maxAttempts, AND the cache TTL
+  // of 0 makes the state non-persistent — together silently disabling lockout.
+  _requirePositiveInt("windowMs", windowMs);
 
   var lockoutDurations = opts.lockoutDurations !== undefined
                             ? opts.lockoutDurations : DEFAULTS.lockoutDurations;
@@ -232,13 +244,6 @@ function create(opts) {
     }
   }
 
-  async function _writeState(key, state, ttlMs) {
-    try {
-      await cache.set(_scopedKey(key), state, { ttlMs: ttlMs });
-    } catch (_e) {
-      _signalCacheError("set");
-    }
-  }
 
   async function _deleteState(key) {
     try {
@@ -248,6 +253,49 @@ function create(opts) {
     }
   }
 
+  // Atomically clear the lockout state under a compare-and-set, so a clear
+  // (recordSuccess / unlock) cannot race a concurrent recordFailure that just
+  // engaged a lock — a read-then-del would erase that fresh lock. onState is
+  // invoked with the pre-clear state inside the CAS mutator (it may re-run on a
+  // retry; the last invocation reflects the committed state) to capture audit
+  // detail. On a backend that can't do an atomic update at runtime it falls
+  // back to read-then-del (a lost clear leaves a lock in place — fail-safe).
+  // preserveIf(state) → true to KEEP the state (abort the clear) rather than
+  // delete it. recordSuccess passes a predicate that preserves an active forced
+  // (admin / ATO kill-switch) lock, so a successful login by someone who still
+  // holds the compromised password cannot clear it — only an explicit unlock()
+  // releases a forced lock.
+  async function _atomicClear(key, onState, preserveIf) {
+    try {
+      await cache.update(_scopedKey(key), function (state) {
+        state = state || null;
+        onState(state);
+        if (!state) return { abort: true };
+        if (preserveIf && preserveIf(state)) return { abort: true };
+        return { delete: true };
+      }, { ttlMs: windowMs });
+    } catch (e) {
+      if (e && e.code === "UNSUPPORTED") {
+        var st = await _readState(key);
+        onState(st);
+        if (st && !(preserveIf && preserveIf(st))) await _deleteState(key);
+        return;
+      }
+      _signalCacheError("update");
+      // Best-effort fallback so a transient cache error doesn't leave the
+      // counter un-cleared on the happy path.
+      var st2 = await _readState(key);
+      onState(st2);
+      if (st2 && !(preserveIf && preserveIf(st2))) await _deleteState(key);
+    }
+  }
+
+  // An active forced/admin lock (set by lock()) must survive recordSuccess.
+  function _isActiveForcedLock(state) {
+    return !!(state && state.forced === true &&
+              typeof state.lockedUntil === "number" && state.lockedUntil > clock());
+  }
+
   function _verdictFromState(state, now) {
     if (!state) return { locked: false, attempts: 0 };
     if (state.lockedUntil && state.lockedUntil > now) {
@@ -262,126 +310,143 @@ function create(opts) {
 
   // ---- Public surface ----
 
-  // Per-key serialization of the failure counter (read→increment→write on an
-  // async store): concurrent recordFailure calls for the same key would lose
-  // updates, letting parallel failures stay under the lockout threshold. A
-  // per-key promise chain applies them sequentially in-process.
-  var _recordChains = new Map();
-  function recordFailure(key, callOpts) {
-    var prev = _recordChains.get(key) || Promise.resolve();
-    var run = prev.then(function () { return _doRecordFailure(key, callOpts); },
-                        function () { return _doRecordFailure(key, callOpts); });
-    var tail = run.then(function () {}, function () {});
-    _recordChains.set(key, tail);
-    tail.then(function () { if (_recordChains.get(key) === tail) _recordChains.delete(key); });
-    return run;
-  }
-
-  async function _doRecordFailure(key, callOpts) {
+  // The failure counter is a read-modify-write on a shared cache. A plain
+  // get -> increment -> set is not atomic, so concurrent recordFailure calls
+  // across nodes lose increments and a brute-force attacker spread across nodes
+  // stays under the lockout threshold. cache.update runs the whole decision
+  // under a compare-and-set (with retry on the cluster backend), so every
+  // failure is counted. The mutator is PURE (it may re-run on a CAS retry): it
+  // computes the next state, records the outcome for the post-commit audit /
+  // observability emits below, and captures any error it raises so a
+  // configuration fault surfaces instead of being read as a cache failure.
+  async function recordFailure(key, callOpts) {
     _requireKey(key);
     callOpts = callOpts || {};
     var now = clock();
-    var state = await _readState(key);
+    var outcome = null;
+    var mutatorErr = null;
+    try {
+      await cache.update(_scopedKey(key), function (state) {
+        try {
+          state = state || null;
+          // Currently locked: the lockout itself counts — don't accumulate during
+          // the cooldown. Abort (no write); the verdict comes from the read state.
+          if (state && state.lockedUntil && state.lockedUntil > now) {
+            outcome = { kind: "during-lock", attempts: state.attempts || 0,
+              lockNumber: state.lockNumber || 0, lockedUntil: state.lockedUntil };
+            return { abort: true };
+          }
+          // Window decay: failures older than windowMs reset the counter.
+          // Lock-number persists so an attacker who sleeps off a lockout doesn't
+          // get a fresh ladder rung.
+          if (state && state.lastFailureAt && (now - state.lastFailureAt) > windowMs) {
+            state = { attempts: 0, lockNumber: state.lockNumber || 0,
+              firstFailureAt: null, lastFailureAt: null, lockedUntil: null };
+          }
+          var attempts = (state && state.attempts) || 0;
+          var lockNumber = (state && state.lockNumber) || 0;
+          attempts += 1;
+          var lockedUntil = null, newLock = false;
+          if (attempts >= maxAttempts) {
+            lockNumber += 1;
+            lockedUntil = now + _resolveDuration(lockoutDurations, lockNumber);
+            newLock = true;
+            attempts = 0;  // counter resets — the lockout window IS the punishment
+          }
+          var newState = {
+            attempts:       attempts,
+            lockNumber:     lockNumber,
+            firstFailureAt: (state && state.firstFailureAt) || now,
+            lastFailureAt:  now,
+            lockedUntil:    lockedUntil,
+          };
+          outcome = { kind: "recorded", attempts: attempts, lockNumber: lockNumber,
+            lockedUntil: lockedUntil, newLock: newLock };
+          // Keep the state only as long as it is meaningful: a non-locked counter
+          // expires after the decay window (so check()/attempts() read clean once
+          // it has elapsed), and a lock persists until lockedUntil plus a window
+          // so the lockNumber survives the cooldown — for the operator's actual
+          // configured duration, however long. A DURATION (the cache resolves it
+          // against its own clock) so an injectable lockout clock never desyncs
+          // the cache's expiry.
+          return { value: newState, ttlMs: lockedUntil ? (lockedUntil - now + windowMs) : windowMs };
+        } catch (me) {
+          mutatorErr = me;
+          throw me;
+        }
+      }, { ttlMs: windowMs });
+    } catch (e) {
+      // A configuration fault raised by the mutator (e.g. a lockoutDurations
+      // function returning an invalid value) must surface — not be swallowed as
+      // a backend failure and silently disable the lockout.
+      if (mutatorErr) throw mutatorErr;
+      // A backend that can't actually commit an atomic update (a get/set-only
+      // backend throws UNSUPPORTED at call time) must surface LOUD — failing
+      // open here would silently disable lockout. Any other cache error keeps
+      // the documented fail-OPEN posture (allow the attempt, signal it).
+      if (e && e.code === "UNSUPPORTED") {
+        throw _err("CACHE_NO_ATOMIC_UPDATE",
+          "auth.lockout: the cache backend does not support atomic update() — the " +
+          "failure counter cannot be enforced across nodes on a get/set-only backend; " +
+          "use a cache whose backend implements update (the memory or cluster backend).");
+      }
+      _signalCacheError("update");
+      return { locked: false, attempts: 0 };
+    }
 
-    // If currently locked, the lockout itself counts — don't accumulate
-    // additional attempts during the cooldown. The caller saw locked=true
-    // from check() OR from a prior failure; this branch handles a caller
-    // that calls recordFailure() on a locked account anyway (e.g. they
-    // skipped check()).
-    if (state && state.lockedUntil && state.lockedUntil > now) {
+    if (outcome.kind === "during-lock") {
       _emitObs("auth.lockout.failure_during_lock", { namespace: namespace });
       if (auditFailures) {
         _emitAudit("auth.lockout.failure", key, "denied",
-          { duringLock: true, attempts: state.attempts || 0,
-            lockNumber: state.lockNumber || 0,
-            lockedUntil: state.lockedUntil,
-            reason: callOpts.reason || null },
+          { duringLock: true, attempts: outcome.attempts, lockNumber: outcome.lockNumber,
+            lockedUntil: outcome.lockedUntil, reason: callOpts.reason || null },
           callOpts.req);
       }
-      return {
-        locked:      true,
-        attempts:    state.attempts || 0,
-        lockedUntil: state.lockedUntil,
-      };
-    }
-
-    // Window decay: failures older than windowMs reset the counter.
-    // Lock-number persists across decay windows so an attacker who
-    // sleeps off a lockout doesn't get a fresh ladder rung.
-    if (state && state.lastFailureAt && (now - state.lastFailureAt) > windowMs) {
-      state = {
-        attempts:       0,
-        lockNumber:     state.lockNumber || 0,
-        firstFailureAt: null,
-        lastFailureAt:  null,
-        lockedUntil:    null,
-      };
-    }
-
-    var attempts   = (state && state.attempts) || 0;
-    var lockNumber = (state && state.lockNumber) || 0;
-    attempts += 1;
-
-    var lockedUntil = null;
-    var newLock = false;
-    if (attempts >= maxAttempts) {
-      lockNumber += 1;
-      var dur = _resolveDuration(lockoutDurations, lockNumber);
-      lockedUntil = now + dur;
-      newLock = true;
-      attempts = 0;  // counter resets — the lockout window IS the punishment
+      return { locked: true, attempts: outcome.attempts, lockedUntil: outcome.lockedUntil };
     }
 
-    var newState = {
-      attempts:       attempts,
-      lockNumber:     lockNumber,
-      firstFailureAt: (state && state.firstFailureAt) || now,
-      lastFailureAt:  now,
-      lockedUntil:    lockedUntil,
-    };
-
-    // TTL: keep the state alive long enough that a follower-up failure
-    // after the window/lockout expires still finds the lockNumber. The
-    // longer of (windowMs after last failure) or (lockedUntil + windowMs).
-    var ttlMs = lockedUntil ? (lockedUntil - now + windowMs) : windowMs;
-    await _writeState(key, newState, ttlMs);
-
     _emitObs("auth.lockout.failure", { namespace: namespace });
     if (auditFailures) {
       _emitAudit("auth.lockout.failure", key, "failure",
-        { attempts: newState.attempts, lockNumber: lockNumber,
+        { attempts: outcome.attempts, lockNumber: outcome.lockNumber,
           reason: callOpts.reason || null },
         callOpts.req);
     }
 
-    if (newLock) {
+    if (outcome.newLock) {
       _emitObs("auth.lockout.engaged", {
         namespace:  namespace,
-        lockNumber: String(lockNumber),
+        lockNumber: String(outcome.lockNumber),
       });
       if (auditEngaged) {
         _emitAudit("auth.lockout.engaged", key, "denied",
-          { lockNumber: lockNumber, lockedUntil: lockedUntil,
-            durationMs: lockedUntil - now,
+          { lockNumber: outcome.lockNumber, lockedUntil: outcome.lockedUntil,
+            durationMs: outcome.lockedUntil - now,
             reason: callOpts.reason || null },
           callOpts.req);
       }
-      return { locked: true, attempts: 0, lockedUntil: lockedUntil };
+      return { locked: true, attempts: 0, lockedUntil: outcome.lockedUntil };
     }
 
-    return { locked: false, attempts: attempts };
+    return { locked: false, attempts: outcome.attempts };
   }
 
   async function recordSuccess(key, callOpts) {
     _requireKey(key);
     callOpts = callOpts || {};
-    var state = await _readState(key);
-    var hadCounter = !!(state && (state.attempts > 0 || state.lockedUntil));
-    if (state) await _deleteState(key);
+    var hadCounter = false;
+    var clearedAttempts = 0;
+    // Preserve an active forced (admin / ATO) lock: a successful credential
+    // verification must not release a kill-switch lock — the password may still
+    // be the compromised one. A forced lock yields only to unlock().
+    await _atomicClear(key, function (state) {
+      hadCounter = !!(state && (state.attempts > 0 || state.lockedUntil));
+      clearedAttempts = (state && state.attempts) || 0;
+    }, _isActiveForcedLock);
     _emitObs("auth.lockout.success", { namespace: namespace });
     if (auditSuccess) {
       _emitAudit("auth.lockout.success", key, "success",
-        { attemptsCleared: (state && state.attempts) || 0,
+        { attemptsCleared: clearedAttempts,
           hadCounter:      hadCounter },
         callOpts.req);
     }
@@ -396,26 +461,93 @@ function create(opts) {
   async function unlock(key, callOpts) {
     _requireKey(key);
     callOpts = callOpts || {};
-    var state = await _readState(key);
     var now = clock();
-    var hadLock = !!(state && (
-      (state.lockedUntil && state.lockedUntil > now) ||
-      (state.attempts || 0) > 0
-    ));
-    if (state) await _deleteState(key);
+    var hadLock = false;
+    var prior = { attempts: 0, lockedUntil: null, lockNumber: 0 };
+    await _atomicClear(key, function (state) {
+      hadLock = !!(state && (
+        (state.lockedUntil && state.lockedUntil > now) ||
+        (state.attempts || 0) > 0
+      ));
+      prior = {
+        attempts:    (state && state.attempts) || 0,
+        lockedUntil: (state && state.lockedUntil) || null,
+        lockNumber:  (state && state.lockNumber) || 0,
+      };
+    });
     _emitObs("auth.lockout.unlock", { namespace: namespace });
     if (auditUnlock) {
       _emitAudit("auth.lockout.unlock", key, "success",
         { hadLock:           hadLock,
-          priorAttempts:    (state && state.attempts) || 0,
-          priorLockedUntil: (state && state.lockedUntil) || null,
-          priorLockNumber:  (state && state.lockNumber) || 0,
+          priorAttempts:    prior.attempts,
+          priorLockedUntil: prior.lockedUntil,
+          priorLockNumber:  prior.lockNumber,
           reason:           callOpts.reason || null },
         callOpts.req);
     }
     return hadLock;
   }
 
+  // Force an account into lockout immediately — the operator action behind an
+  // ATO kill-switch / incident response, independent of the failure counter.
+  // Sets lockedUntil to `untilMs` (absolute) or now+`durationMs`, defaulting to
+  // a long admin lock; bumps lockNumber so a subsequent failure ladders from
+  // here. Uses the same compare-and-set as recordFailure (atomic, retried). An
+  // admin lock that cannot be committed THROWS (the caller — e.g. the kill-
+  // switch — must know it did not lock), rather than the hot-path fail-open.
+  async function lock(key, callOpts) {
+    _requireKey(key);
+    callOpts = callOpts || {};
+    var now = clock();
+    var lockedUntil;
+    if (typeof callOpts.untilMs === "number" && isFinite(callOpts.untilMs)) {
+      lockedUntil = callOpts.untilMs;
+    } else if (typeof callOpts.durationMs === "number" && isFinite(callOpts.durationMs) && callOpts.durationMs > 0) {
+      lockedUntil = now + callOpts.durationMs;
+    } else {
+      lockedUntil = now + DEFAULT_ADMIN_LOCK_MS;
+    }
+    if (lockedUntil <= now) {
+      throw _err("BAD_OPT", "lock: resolved lockedUntil is not in the future " +
+        "(untilMs/durationMs) — use unlock() to clear a lock");
+    }
+    var ttl = lockedUntil - now + windowMs;
+    var lockNumber = 0;
+    try {
+      await cache.update(_scopedKey(key), function (state) {
+        lockNumber = ((state && state.lockNumber) || 0) + 1;
+        return {
+          value: {
+            attempts:       0,
+            lockNumber:     lockNumber,
+            firstFailureAt: (state && state.firstFailureAt) || now,
+            lastFailureAt:  now,
+            lockedUntil:    lockedUntil,
+            // Marks this as an operator-forced lock so recordSuccess won't clear
+            // it — it is released only by an explicit unlock().
+            forced:         true,
+          },
+          ttlMs: ttl,
+        };
+      }, { ttlMs: ttl });
+    } catch (e) {
+      if (e && e.code === "UNSUPPORTED") {
+        throw _err("CACHE_NO_ATOMIC_UPDATE",
+          "auth.lockout: the cache backend does not support atomic update() — " +
+          "lock() cannot enforce the lockout across nodes on a get/set-only backend.");
+      }
+      throw e;
+    }
+    _emitObs("auth.lockout.engaged", { namespace: namespace, lockNumber: String(lockNumber) });
+    if (auditEngaged) {
+      _emitAudit("auth.lockout.engaged", key, "denied",
+        { lockNumber: lockNumber, lockedUntil: lockedUntil, durationMs: lockedUntil - now,
+          forced: true, reason: callOpts.reason || null },
+        callOpts.req);
+    }
+    return { locked: true, lockedUntil: lockedUntil, lockNumber: lockNumber };
+  }
+
   async function attempts(key) {
     _requireKey(key);
     var state = await _readState(key);
@@ -432,6 +564,7 @@ function create(opts) {
     recordFailure: recordFailure,
     recordSuccess: recordSuccess,
     check:         check,
+    lock:          lock,
     unlock:        unlock,
     attempts:      attempts,
     close:         close,

package/lib/vendor/blamejs/lib/auth/oauth.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
 "use strict";
 /**
  * oauth — OAuth 2 / OIDC client.
@@ -107,6 +109,7 @@
 var nodeCrypto = require("node:crypto");
 var cache = require("../cache");
 var C = require("../constants");
+var numericBounds = require("../numeric-bounds");
 var safeAsync = require("../safe-async");
 var bCrypto = require("../crypto");
 var { generateBytes, timingSafeEqual: cryptoTimingSafeEqual } = bCrypto;
@@ -886,6 +889,11 @@ async function verifyClientAttestation(attestationJwt, popJwt, vopts) {
       "client-attestation: missing 'cnf.jwk' confirmation key (RFC 7800)");
   }
   var nowSec  = Math.floor(Date.now() / C.TIME.seconds(1));
+  // A present skew/maxAge must be a non-negative finite integer; a bare typeof
+  // check lets Infinity/NaN through, and `exp + Infinity < now` (or NaN) is
+  // always false — disabling the attestation/PoP expiry gates.
+  numericBounds.requireNonNegativeFiniteIntIfPresent(vopts.clockSkewSec,
+    "verifyClientAttestation: opts.clockSkewSec", OAuthError, "auth-oauth/bad-clock-skew");
   var skewSec = typeof vopts.clockSkewSec === "number" ? vopts.clockSkewSec : (C.TIME.minutes(1) / C.TIME.seconds(1));
   if (typeof ap.exp !== "number" || ap.exp + skewSec < nowSec) {
     throw new OAuthError("auth-oauth/attestation-expired",
@@ -918,6 +926,8 @@ async function verifyClientAttestation(attestationJwt, popJwt, vopts) {
   if (typeof pp.iat !== "number") {
     throw new OAuthError("auth-oauth/attestation-pop-no-iat", "client-attestation-pop: missing 'iat'");
   }
+  numericBounds.requireNonNegativeFiniteIntIfPresent(vopts.maxPopAgeSec,
+    "verifyClientAttestation: opts.maxPopAgeSec", OAuthError, "auth-oauth/bad-pop-max-age");
   var maxAge = typeof vopts.maxPopAgeSec === "number" ? vopts.maxPopAgeSec : DEFAULT_POP_MAX_AGE_SEC;
   if (pp.iat - skewSec > nowSec) {
     throw new OAuthError("auth-oauth/attestation-pop-iat-future", "client-attestation-pop: iat in the future");
@@ -951,7 +961,11 @@ async function verifyClientAttestation(attestationJwt, popJwt, vopts) {
       throw new OAuthError("auth-oauth/attestation-pop-seen-callback-failed",
         "client-attestation-pop: seenJti() callback threw: " + ((e && e.message) || String(e)));
     }
-    if (unseen === false) {
+    // Fail closed on ANY non-truthy result. The contract is "returns truthy
+    // when UNSEEN"; an operator store fronting Redis EXISTS / SISMEMBER or a
+    // SQL COUNT returns 0 (falsy, not `false`) on a replay, so an
+    // `=== false` comparison would miss it and accept the replayed PoP.
+    if (!unseen) {
       throw new OAuthError("auth-oauth/attestation-pop-replay",
         "client-attestation-pop: jti already seen (replay refused, draft §12.1)");
     }
@@ -972,6 +986,47 @@ function _constantTimeStrEq(a, b) {
   return cryptoTimingSafeEqual(a, b);
 }
 
+// Framework-managed authorization-request parameters. Operator-supplied
+// extraParams may not carry any of these — the builder generates them and
+// RETURNS the security-critical ones (state, PKCE verifier/challenge) to the
+// caller, so an extraParams override would silently diverge the returned
+// values from what the URL/PAR body actually carries (a broken CSRF / PKCE
+// binding). Covers redirect target, client identity, requested response,
+// scope, state, nonce, PKCE challenge, response mode, RAR details, and the
+// JAR request container.
+var RESERVED_AUTHZ_PARAMS = {
+  "response_type":         1,
+  "client_id":             1,
+  "redirect_uri":          1,
+  "scope":                 1,
+  "state":                 1,
+  "nonce":                 1,
+  "code_challenge":        1,
+  "code_challenge_method": 1,
+  "response_mode":         1,
+  "authorization_details": 1,
+  "request":               1,
+  "request_uri":           1,
+};
+
+// Refuse operator-supplied extraParams keys that collide with a framework-
+// managed parameter. extraParams is operator-controlled, so a collision is a
+// config-time bug (a library merge / copy-paste) — refuse it loudly rather
+// than let it shadow a value the framework generated and returned. Fail
+// closed; shared by authorizationUrl, pushAuthorizationRequest, and
+// endSessionUrl so every URL/PAR builder guards the same way.
+function _assertNoReservedExtraParams(extraParams, reserved, errCode, ctx) {
+  if (!extraParams || typeof extraParams !== "object") return;
+  var ek = Object.keys(extraParams);
+  for (var i = 0; i < ek.length; i++) {
+    if (Object.prototype.hasOwnProperty.call(reserved, ek[i])) {
+      throw new OAuthError(errCode,
+        ctx + ": extraParams key '" + ek[i] + "' collides with a " +
+        "framework-managed parameter — pass it through the named option instead");
+    }
+  }
+}
+
 // ---- core ----
 
 function create(opts) {
@@ -992,6 +1047,12 @@ function create(opts) {
       "requires PKCE for all clients. Remove the opt or upgrade the IdP.");
   }
   var pkce = true;
+  // A present clockSkewMs must be a non-negative finite integer; Infinity/NaN
+  // would disable verifyIdToken's exp gate (`exp + Infinity < now` is always
+  // false → an expired ID token verifies). Reject a malformed skew at config
+  // time so the operator catches it.
+  numericBounds.requireNonNegativeFiniteIntIfPresent(opts.clockSkewMs,
+    "oauth.create: opts.clockSkewMs", OAuthError, "auth-oauth/bad-clock-skew");
   var clockSkewMs  = typeof opts.clockSkewMs === "number" ? opts.clockSkewMs : DEFAULT_CLOCK_SKEW_MS;
   var discoveryCacheMs = typeof opts.discoveryCacheMs === "number"
                            ? opts.discoveryCacheMs : DEFAULT_DISCOVERY_CACHE_MS;
@@ -1245,7 +1306,14 @@ function create(opts) {
       params.set("authorization_details", JSON.stringify(requestedAuthzDetails));
     }
     // Operator-supplied additional params (audience, resource, etc.).
+    // Refuse keys that collide with a framework-managed parameter so an
+    // operator typo / library-merge can't shadow the redirect_uri / state /
+    // code_challenge the builder generated and returned — which would
+    // silently diverge the returned {state, verifier} from the URL and
+    // break the CSRF / PKCE binding.
     if (uopts.extraParams && typeof uopts.extraParams === "object") {
+      _assertNoReservedExtraParams(uopts.extraParams, RESERVED_AUTHZ_PARAMS,
+        "auth-oauth/reserved-extra-param", "authorizationUrl");
       var ek = Object.keys(uopts.extraParams);
       for (var i = 0; i < ek.length; i++) params.set(ek[i], String(uopts.extraParams[ek[i]]));
     }
@@ -1357,23 +1425,30 @@ function create(opts) {
         throw new OAuthError("auth-oauth/seen-callback-failed",
           "refreshAccessToken: checkAndInsert() callback threw: " + ((e && e.message) || String(e)));
       }
-      // Spec contract: inserted===true → first sighting (OK);
-      // inserted===false → replay. v0.9.3 had this inverted, which
-      // broke every first refresh attempt for operators reusing an
-      // existing b.nonceStore-style backend.
-      alreadySeen = inserted === false;
+      // Spec contract: a TRUTHY result → first sighting (the value was
+      // inserted, OK); a FALSY result → replay. v0.9.3 had this inverted,
+      // which broke every first refresh attempt for operators reusing an
+      // existing b.nonceStore-style backend. Test truthiness, not an
+      // `=== false` literal: a store fronting Redis SETNX / SQL INSERT
+      // returns 0 (falsy, not `false`) when the row already existed, so
+      // an exact-literal compare would miss the replay and fail OPEN.
+      alreadySeen = !inserted;
     } else if (typeof ropts.seen === "function") {
       // Legacy non-atomic path. Documented as a check-then-act race;
       // operators sharing a single-writer store (Redis SETNX, DB
       // INSERT ON CONFLICT) MUST migrate to checkAndInsert. Stays
       // here for backwards-compat with existing operator code.
+      // Legacy contract: truthy → the token was presented before (replay).
+      // The value is used by truthiness at the gate below, so a store
+      // returning 1 from Redis EXISTS / a SQL COUNT is honored as "seen"
+      // instead of being missed by an `=== true` literal compare.
       try { alreadySeen = await ropts.seen(refreshToken); }
       catch (e) {
         throw new OAuthError("auth-oauth/seen-callback-failed",
           "refreshAccessToken: seen() callback threw: " + ((e && e.message) || String(e)));
       }
     }
-    if (alreadySeen === true) {
+    if (alreadySeen) {
       throw new OAuthError("auth-oauth/refresh-token-replay",
         "refreshAccessToken: refresh token has been presented before — refused " +
         "(OAuth 2.1 §6.1 / RFC 9700 §4.13 one-time-use defense). The operator MUST " +
@@ -1996,15 +2071,10 @@ function create(opts) {
         "ui_locales":                 1,
         "client_id":                  1,
       };
+      _assertNoReservedExtraParams(uopts.extraParams, RESERVED_END_SESSION_PARAMS,
+        "auth-oauth/end-session-reserved-extra-param", "endSessionUrl");
       var ek = Object.keys(uopts.extraParams);
-      for (var i = 0; i < ek.length; i++) {
-        if (RESERVED_END_SESSION_PARAMS[ek[i]]) {
-          throw new OAuthError("auth-oauth/end-session-reserved-extra-param",
-            "endSessionUrl: extraParams key '" + ek[i] + "' collides with a first-class " +
-            "RP-Init Logout parameter — pass it through the named field instead");
-        }
-        params.set(ek[i], String(uopts.extraParams[ek[i]]));
-      }
+      for (var i = 0; i < ek.length; i++) params.set(ek[i], String(uopts.extraParams[ek[i]]));
     }
     var qs = params.toString();
     if (qs.length === 0) return endpoint;
@@ -2092,6 +2162,11 @@ function create(opts) {
         : JSON.stringify(requestedAuthzDetails);   // form param — JSON string
     }
     if (uopts.extraParams && typeof uopts.extraParams === "object") {
+      // Same reserved-key guard as authorizationUrl — a PAR request pushes
+      // the identical security-critical parameter set, so extraParams may
+      // not shadow redirect_uri / state / code_challenge here either.
+      _assertNoReservedExtraParams(uopts.extraParams, RESERVED_AUTHZ_PARAMS,
+        "auth-oauth/reserved-extra-param", "pushAuthorizationRequest");
       var ek = Object.keys(uopts.extraParams);
       for (var i = 0; i < ek.length; i++) authzParams[ek[i]] = String(uopts.extraParams[ek[i]]);
     }
@@ -2338,7 +2413,10 @@ function create(opts) {
           "verifyBackchannelLogoutToken: atomicReplayStore.checkAndInsert threw: " +
           ((e && e.message) || String(e)));
       }
-      if (inserted === false) {
+      // Fail closed on ANY non-truthy result. A store fronting SETNX / an
+      // ON-CONFLICT INSERT returns 0 (falsy, not `false`) on a duplicate,
+      // so an `=== false` compare would miss the replay.
+      if (!inserted) {
         throw new OAuthError("auth-oauth/logout-token-replay",
           "verifyBackchannelLogoutToken: jti '" + claims.jti +
           "' already seen — replay refused (atomic)");
@@ -2354,7 +2432,10 @@ function create(opts) {
         throw new OAuthError("auth-oauth/seen-callback-failed",
           "verifyBackchannelLogoutToken: seen() callback threw: " + ((e && e.message) || String(e)));
       }
-      if (first === false) {
+      // Fail closed on ANY non-truthy result — `seen()` returns truthy the
+      // first time it sees the (jti, iss) pair; a store returning 0 for a
+      // duplicate must still refuse, which an `=== false` compare would miss.
+      if (!first) {
         throw new OAuthError("auth-oauth/logout-token-replay",
           "verifyBackchannelLogoutToken: jti already seen — replay refused");
       }