@web-ts-toolkit/express-oidc-vault 0.43.0 → 0.47.1

package/index.mjs

@@ -5,6 +5,7 @@ import express from "express";
 // src/config.ts
 var DEFAULT_OIDC_SCOPES = "openid email profile";
 var MANUAL_CONFIG_REQUIREMENTS = ["issuer", "authorizationEndpoint", "tokenEndpoint", "jwksUri"];
+var MANUAL_CONFIG_SELECTORS = ["authorizationEndpoint", "tokenEndpoint", "jwksUri", "userInfoEndpoint", "endSessionEndpoint"];
 var normalizeOptionalString = (value) => {
   const trimmed = value?.trim();
   return trimmed ? trimmed : void 0;
@@ -24,19 +25,38 @@ var normalizeHttpUrl = (value, optionName) => {
   }
   return url.toString();
 };
+var normalizeIssuerIdentifier = (value, optionName) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`${optionName} must be an absolute HTTP(S) URL.`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:" || url.origin === "null") {
+    throw new Error(`${optionName} must use http or https.`);
+  }
+  if (url.username !== "" || url.password !== "") {
+    throw new Error(`${optionName} must not include userinfo.`);
+  }
+  if (url.search !== "" || url.hash !== "") {
+    throw new Error(`${optionName} must not include query or fragment.`);
+  }
+  return value;
+};
 var withOptionalValue = (target, key, value) => {
   if (value !== void 0) {
     target[key] = value;
   }
 };
 function resolveOidcVaultConfig(config = {}) {
-  const issuer = normalizeHttpUrl(normalizeOptionalString(config.issuer), "config.issuer");
+  const issuer = normalizeIssuerIdentifier(normalizeOptionalString(config.issuer), "config.issuer");
   const clientId = normalizeOptionalString(config.clientId);
   const clientSecret = normalizeOptionalString(config.clientSecret);
   const scopes = normalizeOptionalString(config.scopes) ?? DEFAULT_OIDC_SCOPES;
-  const hasManualEndpoints = MANUAL_CONFIG_REQUIREMENTS.some(
-    (key) => key !== "issuer" && normalizeOptionalString(config[key])
-  );
+  const hasManualEndpoints = MANUAL_CONFIG_SELECTORS.some((key) => normalizeOptionalString(config[key]));
   if (!clientId) {
     throw new Error("OIDC clientId is required.");
   }
@@ -196,37 +216,11 @@ var getRequiredFiniteNonNegativeInteger = (value, message, code, status = 502) =
 // src/cookies.ts
 var getSessionTransport = (options) => options.sessionTransport ?? "body";
 var usesCookieTransport = (options) => getSessionTransport(options) === "cookie";
-var parseCookieHeader = (headerValue) => {
-  if (!headerValue) {
-    return {};
-  }
-  return headerValue.split(";").reduce((cookies, part) => {
-    const separatorIndex = part.indexOf("=");
-    if (separatorIndex === -1) {
-      return cookies;
-    }
-    const name = part.slice(0, separatorIndex).trim();
-    const value = part.slice(separatorIndex + 1).trim();
-    if (!name) {
-      return cookies;
-    }
-    try {
-      cookies[name] = decodeURIComponent(value);
-    } catch {
-      throw new OidcVaultHttpError(
-        400,
-        "OIDC_VAULT_MALFORMED_SESSION_COOKIE",
-        "OIDC vault session cookie is malformed."
-      );
-    }
-    return cookies;
-  }, {});
-};
 var resolveCookieOptions = (options) => {
   const cookieOptions = options.cookie ?? {};
   const deploymentMode = cookieOptions.deploymentMode ?? "same-origin";
   const sameSite = cookieOptions.sameSite ?? (deploymentMode === "cross-site" ? "none" : "lax");
-  const secure = cookieOptions.secure ?? (sameSite === "none" || deploymentMode === "cross-site");
+  const secure = cookieOptions.secure ?? (sameSite === "none" || deploymentMode === "cross-site" || isHttpsBackendOrigin(options));
   return {
     name: cookieOptions.name ?? DEFAULT_SESSION_COOKIE_NAME,
     sameSite,
@@ -236,12 +230,24 @@ var resolveCookieOptions = (options) => {
     httpOnly: cookieOptions.httpOnly ?? true
   };
 };
+var isEffectivelySecureCookie = (cookieOptions) => cookieOptions.secure || cookieOptions.sameSite === "none";
+var isHttpsBackendOrigin = (options) => {
+  try {
+    const raw = options.backendOrigin;
+    if (typeof raw !== "string") {
+      return false;
+    }
+    return new URL(raw.trim()).protocol === "https:";
+  } catch {
+    return false;
+  }
+};
 var COOKIE_NAME_PATTERN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
 var COOKIE_DOMAIN_PATTERN = /^\.?[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$/;
 var hasUnsafeCookieValueCharacters = (value) => {
   for (let index = 0; index < value.length; index += 1) {
     const code = value.charCodeAt(index);
-    if (code <= 31 || code === 127 || value[index] === ";") {
+    if (code < 32 || code > 126 || value[index] === ";") {
       return true;
     }
   }
@@ -264,6 +270,22 @@ var validateCookieOptions = (options) => {
   if (!cookieOptions.httpOnly) {
     throw new Error("cookie.httpOnly must be true for cookie session transport.");
   }
+  const effectiveSecure = isEffectivelySecureCookie(cookieOptions);
+  if (cookieOptions.name.startsWith("__Host-")) {
+    if (!effectiveSecure) {
+      throw new Error("cookie.name with the __Host- prefix must be Secure.");
+    }
+    if (cookieOptions.domain !== void 0) {
+      throw new Error("cookie.name with the __Host- prefix must not set cookie.domain.");
+    }
+    if (cookieOptions.path !== "/") {
+      throw new Error('cookie.name with the __Host- prefix must use cookie.path "/".');
+    }
+  } else if (cookieOptions.name.startsWith("__Secure-")) {
+    if (!effectiveSecure) {
+      throw new Error("cookie.name with the __Secure- prefix must be Secure.");
+    }
+  }
 };
 var usesCrossSiteCookieTransport = (options) => usesCookieTransport(options) && resolveCookieOptions(options).sameSite === "none";
 var serializeCookie = (name, value, options, overrides) => {
@@ -301,8 +323,62 @@ var clearSessionCookie = (res, options) => {
   );
 };
 var getSessionIdFromCookie = (req, options) => {
-  const cookies = parseCookieHeader(req.headers.cookie);
-  return cookies[resolveCookieOptions(options).name];
+  const raw = parseSelectedCookieValue(req.headers.cookie, resolveCookieOptions(options).name);
+  if (raw === void 0) {
+    return void 0;
+  }
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    throw new OidcVaultHttpError(400, "OIDC_VAULT_MALFORMED_SESSION_COOKIE", "OIDC vault session cookie is malformed.");
+  }
+};
+var parseSelectedCookieValue = (headerValue, selectedName) => {
+  if (!headerValue) {
+    return void 0;
+  }
+  const segments = headerValue.split(";");
+  for (const segment of segments) {
+    const separatorIndex = segment.indexOf("=");
+    if (separatorIndex === -1) {
+      continue;
+    }
+    const name = segment.slice(0, separatorIndex).trim();
+    if (!name || name !== selectedName) {
+      continue;
+    }
+    return segment.slice(separatorIndex + 1).trim();
+  }
+  return void 0;
+};
+
+// src/lifetime-policy.ts
+var MAX_EPOCH_MS = 864e13;
+var isUsableEpochMs = (value) => typeof value === "number" && Number.isSafeInteger(value) && Math.abs(value) <= MAX_EPOCH_MS;
+var computeExpiresAt = (now, ttlMs, name) => {
+  if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) {
+    throw new Error(`${name} must be a positive safe integer in milliseconds.`);
+  }
+  const expiresAt = now + ttlMs;
+  if (!isUsableEpochMs(now) || !isUsableEpochMs(expiresAt) || expiresAt <= now) {
+    throw new Error(`${name} must produce a usable epoch-millisecond expiry after now.`);
+  }
+  return expiresAt;
+};
+var validateLifetimeOptions = (options, now) => {
+  computeExpiresAt(
+    now,
+    options.authorizationTransactionTtlMs === void 0 ? DEFAULT_AUTHORIZATION_TRANSACTION_TTL_MS : options.authorizationTransactionTtlMs,
+    "authorizationTransactionTtlMs"
+  );
+  computeExpiresAt(
+    now,
+    options.exchangeCodeTtlMs === void 0 ? DEFAULT_EXCHANGE_CODE_TTL_MS : options.exchangeCodeTtlMs,
+    "exchangeCodeTtlMs"
+  );
+  if (options.sessionTtlMs !== void 0) {
+    computeExpiresAt(now, options.sessionTtlMs, "sessionTtlMs");
+  }
 };
 
 // src/utils.ts
@@ -401,18 +477,36 @@ var assertTrustedOrigin = (req, options, trustedOrigins, action) => {
 };
 
 // src/provider-client.ts
-import { createRemoteJWKSet } from "jose";
+import { createRemoteJWKSet, customFetch } from "jose";
 var DEFAULT_PROVIDER_REQUEST_TIMEOUT_MS = 5e3;
 var DEFAULT_DISCOVERY_CACHE_TTL_MS = 10 * 6e4;
 var DEFAULT_DISCOVERY_CACHE_CAPACITY = 32;
 var DEFAULT_JWKS_CACHE_CAPACITY = 32;
 var DEFAULT_PROVIDER_ERROR_BODY_LIMIT = 1024;
 var DEFAULT_PROVIDER_JSON_BODY_LIMIT = 1024 * 1024;
+var DEFAULT_JWKS_BODY_LIMIT = 1024 * 1024;
+var DEFAULT_JWKS_MAX_KEYS = 100;
 var discoveryCache = /* @__PURE__ */ new Map();
 var jwksCache = /* @__PURE__ */ new Map();
-var normalizeIssuerForDiscoveryComparison = (issuer) => issuer.replace(/\/+$/g, "");
 var assertDiscoveredIssuerMatchesConfig = (configuredIssuer, discoveredIssuer) => {
-  if (normalizeIssuerForDiscoveryComparison(configuredIssuer) !== normalizeIssuerForDiscoveryComparison(discoveredIssuer)) {
+  let discoveredUrl;
+  try {
+    discoveredUrl = new URL(discoveredIssuer);
+  } catch {
+    throw new OidcVaultHttpError(
+      502,
+      "OIDC_VAULT_DISCOVERY_INVALID",
+      "OIDC discovery response issuer must be an absolute HTTP(S) URL."
+    );
+  }
+  if (discoveredUrl.protocol !== "https:" && discoveredUrl.protocol !== "http:" || discoveredUrl.origin === "null" || discoveredUrl.username !== "" || discoveredUrl.password !== "" || discoveredUrl.search !== "" || discoveredUrl.hash !== "") {
+    throw new OidcVaultHttpError(
+      502,
+      "OIDC_VAULT_DISCOVERY_INVALID",
+      "OIDC discovery response issuer must be an http(s) URL without userinfo, query, or fragment."
+    );
+  }
+  if (configuredIssuer !== discoveredIssuer) {
     throw new OidcVaultHttpError(
       502,
       "OIDC_VAULT_DISCOVERY_INVALID",
@@ -440,6 +534,20 @@ var validateDiscoveredHttpUrl = (value, fieldName) => {
   }
   return url.toString();
 };
+var validateOptionalDiscoveredHttpUrl = (value, fieldName) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  return validateDiscoveredHttpUrl(
+    getRequiredString(
+      value,
+      `OIDC discovery response ${fieldName} must be a non-empty string when present.`,
+      "OIDC_VAULT_DISCOVERY_INVALID",
+      502
+    ),
+    fieldName
+  );
+};
 var buildWellKnownUrl = (issuer) => {
   const normalizedIssuer = issuer.endsWith("/") ? issuer : `${issuer}/`;
   return new URL(".well-known/openid-configuration", normalizedIssuer);
@@ -464,42 +572,91 @@ var evictOldestEntry = (cache, capacity) => {
     cache.delete(oldestKey);
   }
 };
+var isAbortError = (error) => error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
+var createProviderTimeoutError = (errorCode) => new OidcVaultHttpError(502, errorCode, "OIDC provider request timed out.");
+var createProviderTransportError = (errorCode, cause) => {
+  const error = new OidcVaultHttpError(502, errorCode, "OIDC provider request failed.");
+  Object.defineProperty(error, "cause", { value: cause, configurable: true, writable: true });
+  return error;
+};
+var cancelBestEffort = (cancel) => {
+  try {
+    void cancel()?.catch(() => {
+    });
+  } catch {
+  }
+};
 var fetchProvider = async (input, init, errorCode, options) => {
+  const timeoutMs = getProviderRequestTimeoutMs(options);
   const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), getProviderRequestTimeoutMs(options));
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  const done = () => clearTimeout(timeout);
   try {
-    return await fetch(input, {
+    const response = await fetch(input, {
       ...init,
       redirect: "manual",
       signal: controller.signal
     });
+    return { response, signal: controller.signal, done };
   } catch (error) {
-    if (error instanceof Error && error.name === "AbortError") {
-      throw new OidcVaultHttpError(502, errorCode, "OIDC provider request timed out.");
+    done();
+    if (controller.signal.aborted || isAbortError(error)) {
+      throw createProviderTimeoutError(errorCode);
     }
-    throw error;
-  } finally {
-    clearTimeout(timeout);
+    throw createProviderTransportError(errorCode, error);
   }
 };
+var throwBoundedReadTimeout = (errorCode, timeoutAsTimeoutError) => {
+  if (timeoutAsTimeoutError) {
+    const timeoutError = new Error("JSON Web Key Set request timed out.");
+    timeoutError.name = "TimeoutError";
+    throw timeoutError;
+  }
+  throw createProviderTimeoutError(errorCode);
+};
 var readBoundedResponseText = async (response, limit, errorCode, options = {}) => {
   if (!response.body) {
     return "";
   }
   const reader = response.body.getReader();
   const decoder = new TextDecoder();
+  const { signal } = options;
   let size = 0;
   let text = "";
+  let onAbort;
+  let abortPromise;
+  if (signal) {
+    if (signal.aborted) {
+      cancelBestEffort(() => reader.cancel());
+      reader.releaseLock();
+      throwBoundedReadTimeout(errorCode, options.timeoutAsTimeoutError === true);
+    }
+    abortPromise = new Promise((_resolve, reject) => {
+      onAbort = () => {
+        reject(Object.assign(new Error("aborted"), { name: "AbortError" }));
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    });
+    abortPromise.catch(() => {
+    });
+  }
   try {
     for (; ; ) {
-      const result = await reader.read();
+      let result;
+      try {
+        result = abortPromise === void 0 ? await reader.read() : await Promise.race([reader.read(), abortPromise]);
+      } catch (error) {
+        if (signal?.aborted === true || isAbortError(error)) {
+          throwBoundedReadTimeout(errorCode, options.timeoutAsTimeoutError === true);
+        }
+        throw createProviderTransportError(options.transportErrorCode ?? errorCode, error);
+      }
       if (result.done) {
         break;
       }
       size += result.value.byteLength;
       if (size > limit) {
-        await reader.cancel();
-        if (options.truncate) {
+        if (options.truncate === true) {
           return `${text.slice(0, limit)}...`;
         }
         throw new OidcVaultHttpError(502, errorCode, "OIDC provider response is too large.");
@@ -507,123 +664,219 @@ var readBoundedResponseText = async (response, limit, errorCode, options = {}) =
       text += decoder.decode(result.value, { stream: true });
     }
   } finally {
+    if (signal !== void 0 && onAbort !== void 0) {
+      signal.removeEventListener("abort", onAbort);
+    }
+    cancelBestEffort(() => reader.cancel());
     reader.releaseLock();
   }
   return `${text}${decoder.decode()}`;
 };
+var createBoundedJwksFetch = (timeoutMs) => {
+  void timeoutMs;
+  return async (url, { headers, method, redirect, signal }) => {
+    let response;
+    try {
+      response = await fetch(url, { method, headers, redirect, signal });
+    } catch (error) {
+      if (signal.aborted || isAbortError(error)) {
+        const timeoutError = new Error("JSON Web Key Set request timed out.");
+        timeoutError.name = "TimeoutError";
+        throw timeoutError;
+      }
+      throw createProviderTransportError("OIDC_VAULT_JWKS_FAILED", error);
+    }
+    if (response.status !== 200) {
+      cancelBestEffort(() => response.body?.cancel());
+      return response;
+    }
+    const text = await readBoundedResponseText(response, DEFAULT_JWKS_BODY_LIMIT, "OIDC_VAULT_JWKS_FAILED", {
+      signal,
+      timeoutAsTimeoutError: true
+    });
+    try {
+      const parsed = JSON.parse(text);
+      if (Array.isArray(parsed.keys) && parsed.keys.length > DEFAULT_JWKS_MAX_KEYS) {
+        throw new OidcVaultHttpError(502, "OIDC_VAULT_JWKS_FAILED", "JSON Web Key Set contains too many keys.");
+      }
+    } catch (error) {
+      if (error instanceof OidcVaultHttpError) {
+        throw error;
+      }
+    }
+    return new Response(text, {
+      status: 200,
+      headers: { "content-type": "application/json" }
+    });
+  };
+};
 var resolveJwks = (jwksUri, options = {}) => {
-  let jwks = jwksCache.get(jwksUri);
+  const timeoutMs = getProviderRequestTimeoutMs(options);
+  const cacheKey = `${jwksUri}\0${timeoutMs}`;
+  let jwks = jwksCache.get(cacheKey);
   if (!jwks) {
     jwks = createRemoteJWKSet(new URL(jwksUri), {
-      timeoutDuration: getProviderRequestTimeoutMs(options),
-      cacheMaxAge: DEFAULT_DISCOVERY_CACHE_TTL_MS
+      timeoutDuration: timeoutMs,
+      cacheMaxAge: DEFAULT_DISCOVERY_CACHE_TTL_MS,
+      [customFetch]: createBoundedJwksFetch(timeoutMs)
     });
-    jwksCache.set(jwksUri, jwks);
+    jwksCache.set(cacheKey, jwks);
     evictOldestEntry(jwksCache, DEFAULT_JWKS_CACHE_CAPACITY);
   }
   return jwks;
 };
 var formEncodeClientCredential = (value) => new URLSearchParams([[value, ""]]).toString().slice(0, -1);
 var toBasicAuthorization = (clientId, clientSecret) => `Basic ${Buffer.from(`${formEncodeClientCredential(clientId)}:${formEncodeClientCredential(clientSecret)}`).toString("base64")}`;
-var readJsonResponse = async (response, errorCode, invalidJsonMessage = "OIDC provider returned invalid JSON.") => {
-  const text = await readBoundedResponseText(response, DEFAULT_PROVIDER_JSON_BODY_LIMIT, errorCode);
+var isProviderJsonObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var readJsonResponse = async (response, errorCode, invalidJsonMessage = "OIDC provider returned invalid JSON.", readOptions = {}) => {
+  const text = await readBoundedResponseText(response, DEFAULT_PROVIDER_JSON_BODY_LIMIT, errorCode, {
+    signal: readOptions.signal,
+    transportErrorCode: readOptions.transportErrorCode
+  });
   if (!text) {
     return {};
   }
+  let parsed;
   try {
-    return JSON.parse(text);
+    parsed = JSON.parse(text);
   } catch {
-    throw new OidcVaultHttpError(
-      response.ok ? 502 : response.status,
-      errorCode,
-      invalidJsonMessage,
-      invalidJsonMessage
-    );
+    throw new OidcVaultHttpError(502, errorCode, invalidJsonMessage, invalidJsonMessage);
+  }
+  if (!isProviderJsonObject(parsed)) {
+    throw new OidcVaultHttpError(502, errorCode, invalidJsonMessage, invalidJsonMessage);
+  }
+  return parsed;
+};
+var drainProviderErrorBody = async (response, signal, errorCode) => {
+  try {
+    await readBoundedResponseText(response, DEFAULT_PROVIDER_JSON_BODY_LIMIT, errorCode, { signal });
+  } catch (error) {
+    if (error instanceof OidcVaultHttpError) {
+      throw error;
+    }
+    throw error;
   }
 };
 async function discoverIssuerMetadata(issuer, options) {
+  const callerTimeoutMs = getProviderRequestTimeoutMs(options);
+  const policyKey = `${issuer}\0${callerTimeoutMs}`;
   const now = Date.now();
-  const cached = discoveryCache.get(issuer);
-  let discoveryPromise = cached && cached.expiresAt > now ? cached.promise : void 0;
-  if (cached && !discoveryPromise) {
-    discoveryCache.delete(issuer);
-  }
-  if (!discoveryPromise) {
+  const policyCached = discoveryCache.get(policyKey);
+  let discoveryPromise = policyCached !== void 0 && policyCached.expiresAt > now ? policyCached.promise : void 0;
+  if (policyCached !== void 0 && discoveryPromise === void 0) {
+    discoveryCache.delete(policyKey);
+  }
+  if (discoveryPromise === void 0) {
+    const sharedCached = discoveryCache.get(issuer);
+    const sharedPromise = sharedCached !== void 0 && sharedCached.expiresAt > now ? sharedCached.promise : void 0;
+    if (sharedCached !== void 0 && sharedPromise === void 0) {
+      discoveryCache.delete(issuer);
+    }
+    if (sharedPromise !== void 0) {
+      return sharedPromise;
+    }
     discoveryPromise = (async () => {
       const discoveryUrl = buildWellKnownUrl(issuer);
-      const response = await fetchProvider(discoveryUrl, void 0, "OIDC_VAULT_DISCOVERY_FAILED", options);
-      if (!response.ok) {
-        const errorText = await readBoundedResponseText(
+      const { response, signal, done } = await fetchProvider(
+        discoveryUrl,
+        void 0,
+        "OIDC_VAULT_DISCOVERY_FAILED",
+        options
+      );
+      try {
+        if (!response.ok) {
+          const errorText = await readBoundedResponseText(
+            response,
+            DEFAULT_PROVIDER_ERROR_BODY_LIMIT,
+            "OIDC_VAULT_DISCOVERY_FAILED",
+            {
+              truncate: true,
+              signal
+            }
+          );
+          throw new OidcVaultHttpError(
+            502,
+            "OIDC_VAULT_DISCOVERY_FAILED",
+            errorText || `OIDC discovery failed with status ${response.status}.`,
+            "OIDC discovery failed."
+          );
+        }
+        const discovered = await readJsonResponse(
           response,
-          DEFAULT_PROVIDER_ERROR_BODY_LIMIT,
-          "OIDC_VAULT_DISCOVERY_FAILED",
-          {
-            truncate: true
-          }
+          "OIDC_VAULT_DISCOVERY_INVALID",
+          "OIDC discovery response is malformed JSON.",
+          { signal, transportErrorCode: "OIDC_VAULT_DISCOVERY_FAILED" }
         );
-        throw new OidcVaultHttpError(
-          502,
-          "OIDC_VAULT_DISCOVERY_FAILED",
-          errorText || `OIDC discovery failed with status ${response.status}.`,
-          "OIDC discovery failed."
+        const authorizationEndpoint = validateDiscoveredHttpUrl(
+          getRequiredString(
+            discovered.authorization_endpoint,
+            "OIDC discovery response is missing authorization_endpoint.",
+            "OIDC_VAULT_DISCOVERY_INVALID",
+            502
+          ),
+          "authorization_endpoint"
         );
-      }
-      const discovered = await readJsonResponse(
-        response,
-        "OIDC_VAULT_DISCOVERY_INVALID",
-        "OIDC discovery response is malformed JSON."
-      );
-      const authorizationEndpoint = validateDiscoveredHttpUrl(
-        getRequiredString(
-          discovered.authorization_endpoint,
-          "OIDC discovery response is missing authorization_endpoint.",
-          "OIDC_VAULT_DISCOVERY_INVALID",
-          502
-        ),
-        "authorization_endpoint"
-      );
-      const tokenEndpoint = validateDiscoveredHttpUrl(
-        getRequiredString(
-          discovered.token_endpoint,
-          "OIDC discovery response is missing token_endpoint.",
-          "OIDC_VAULT_DISCOVERY_INVALID",
-          502
-        ),
-        "token_endpoint"
-      );
-      const jwksUri = validateDiscoveredHttpUrl(
-        getRequiredString(
-          discovered.jwks_uri,
-          "OIDC discovery response is missing jwks_uri.",
+        const tokenEndpoint = validateDiscoveredHttpUrl(
+          getRequiredString(
+            discovered.token_endpoint,
+            "OIDC discovery response is missing token_endpoint.",
+            "OIDC_VAULT_DISCOVERY_INVALID",
+            502
+          ),
+          "token_endpoint"
+        );
+        const jwksUri = validateDiscoveredHttpUrl(
+          getRequiredString(
+            discovered.jwks_uri,
+            "OIDC discovery response is missing jwks_uri.",
+            "OIDC_VAULT_DISCOVERY_INVALID",
+            502
+          ),
+          "jwks_uri"
+        );
+        const discoveredIssuer = getRequiredString(
+          discovered.issuer,
+          "OIDC discovery response is missing issuer.",
           "OIDC_VAULT_DISCOVERY_INVALID",
           502
-        ),
-        "jwks_uri"
-      );
-      const discoveredIssuer = getRequiredString(
-        discovered.issuer,
-        "OIDC discovery response is missing issuer.",
-        "OIDC_VAULT_DISCOVERY_INVALID",
-        502
-      );
-      assertDiscoveredIssuerMatchesConfig(issuer, discoveredIssuer);
-      return {
-        issuer: discoveredIssuer,
-        authorizationEndpoint,
-        tokenEndpoint,
-        jwksUri,
-        userInfoEndpoint: typeof discovered.userinfo_endpoint === "string" ? validateDiscoveredHttpUrl(discovered.userinfo_endpoint, "userinfo_endpoint") : void 0,
-        endSessionEndpoint: typeof discovered.end_session_endpoint === "string" ? validateDiscoveredHttpUrl(discovered.end_session_endpoint, "end_session_endpoint") : void 0
-      };
+        );
+        assertDiscoveredIssuerMatchesConfig(issuer, discoveredIssuer);
+        return {
+          issuer: discoveredIssuer,
+          authorizationEndpoint,
+          tokenEndpoint,
+          jwksUri,
+          userInfoEndpoint: validateOptionalDiscoveredHttpUrl(discovered.userinfo_endpoint, "userinfo_endpoint"),
+          endSessionEndpoint: validateOptionalDiscoveredHttpUrl(
+            discovered.end_session_endpoint,
+            "end_session_endpoint"
+          )
+        };
+      } finally {
+        done();
+        cancelBestEffort(() => response.body?.cancel());
+      }
     })();
-    discoveryCache.set(issuer, {
+    discoveryPromise.then(
+      () => {
+        const fetchedAt = Date.now();
+        discoveryCache.set(issuer, {
+          expiresAt: fetchedAt + DEFAULT_DISCOVERY_CACHE_TTL_MS,
+          promise: discoveryPromise
+        });
+        evictOldestEntry(discoveryCache, DEFAULT_DISCOVERY_CACHE_CAPACITY);
+      },
+      () => {
+      }
+    );
+    discoveryCache.set(policyKey, {
       expiresAt: now + DEFAULT_DISCOVERY_CACHE_TTL_MS,
       promise: discoveryPromise
     });
     evictOldestEntry(discoveryCache, DEFAULT_DISCOVERY_CACHE_CAPACITY);
     discoveryPromise.catch(() => {
-      if (discoveryCache.get(issuer)?.promise === discoveryPromise) {
-        discoveryCache.delete(issuer);
+      if (discoveryCache.get(policyKey)?.promise === discoveryPromise) {
+        discoveryCache.delete(policyKey);
       }
     });
   }
@@ -674,7 +927,7 @@ async function requestToken(metadata, params, options = {}) {
   if (metadata.clientSecret) {
     headers.authorization = toBasicAuthorization(clientId, metadata.clientSecret);
   }
-  const response = await fetchProvider(
+  const { response, signal, done } = await fetchProvider(
     metadata.tokenEndpoint,
     {
       method: "POST",
@@ -684,17 +937,33 @@ async function requestToken(metadata, params, options = {}) {
     "OIDC_VAULT_TOKEN_REQUEST_FAILED",
     options
   );
-  const json = await readJsonResponse(response, "OIDC_VAULT_TOKEN_REQUEST_FAILED");
-  if (!response.ok) {
+  try {
+    if (!response.ok) {
+      await drainProviderErrorBody(response, signal, "OIDC_VAULT_TOKEN_REQUEST_FAILED");
+      throw new OidcVaultHttpError(
+        502,
+        "OIDC_VAULT_TOKEN_REQUEST_FAILED",
+        "OIDC token request failed.",
+        "OIDC token request failed."
+      );
+    }
+    const json = await readJsonResponse(response, "OIDC_VAULT_TOKEN_REQUEST_FAILED", void 0, { signal });
+    return json;
+  } finally {
+    done();
+    cancelBestEffort(() => response.body?.cancel());
+  }
+}
+var assertPresentTokenStringField = (tokenResponse, field) => {
+  const value = tokenResponse[field];
+  if (value !== void 0 && (typeof value !== "string" || value.length === 0)) {
     throw new OidcVaultHttpError(
       502,
-      "OIDC_VAULT_TOKEN_REQUEST_FAILED",
-      typeof json.error_description === "string" ? json.error_description : `OIDC token request failed with status ${response.status}.`,
-      "OIDC token request failed."
+      "OIDC_VAULT_INVALID_TOKEN_RESPONSE",
+      `OIDC token response ${field} must be a non-empty string when present.`
     );
   }
-  return json;
-}
+};
 function validateTokenResponse(tokenResponse) {
   if (typeof tokenResponse.token_type !== "string" || tokenResponse.token_type.toLowerCase() !== "bearer") {
     throw new OidcVaultHttpError(
@@ -710,12 +979,38 @@ function validateTokenResponse(tokenResponse) {
       "OIDC_VAULT_INVALID_TOKEN_RESPONSE"
     );
   }
+  assertPresentTokenStringField(tokenResponse, "access_token");
+  assertPresentTokenStringField(tokenResponse, "id_token");
+  assertPresentTokenStringField(tokenResponse, "refresh_token");
+  if (tokenResponse.scope !== void 0 && typeof tokenResponse.scope !== "string") {
+    throw new OidcVaultHttpError(
+      502,
+      "OIDC_VAULT_INVALID_TOKEN_RESPONSE",
+      "OIDC token response scope must be a string when present."
+    );
+  }
+}
+function validateCallbackTokenResponse(tokenResponse) {
+  validateTokenResponse(tokenResponse);
+  if (typeof tokenResponse.id_token !== "string" || tokenResponse.id_token.length === 0) {
+    throw new OidcVaultHttpError(502, "OIDC_VAULT_MISSING_ID_TOKEN", "OIDC token response is missing id_token.");
+  }
+  if (typeof tokenResponse.refresh_token !== "string" || tokenResponse.refresh_token.length === 0) {
+    throw new OidcVaultHttpError(
+      502,
+      "OIDC_VAULT_MISSING_REFRESH_TOKEN",
+      "OIDC token response is missing refresh_token."
+    );
+  }
+}
+function validateRefreshTokenResponse(tokenResponse) {
+  validateTokenResponse(tokenResponse);
 }
 async function fetchUserInfo(metadata, accessToken, options = {}) {
   if (!metadata.userInfoEndpoint) {
     return {};
   }
-  const response = await fetchProvider(
+  const { response, signal, done } = await fetchProvider(
     metadata.userInfoEndpoint,
     {
       headers: {
@@ -725,16 +1020,22 @@ async function fetchUserInfo(metadata, accessToken, options = {}) {
     "OIDC_VAULT_USERINFO_FAILED",
     options
   );
-  const json = await readJsonResponse(response, "OIDC_VAULT_USERINFO_FAILED");
-  if (!response.ok) {
-    throw new OidcVaultHttpError(
-      502,
-      "OIDC_VAULT_USERINFO_FAILED",
-      `OIDC userinfo request failed with status ${response.status}.`,
-      "OIDC userinfo request failed."
-    );
+  try {
+    if (!response.ok) {
+      await drainProviderErrorBody(response, signal, "OIDC_VAULT_USERINFO_FAILED");
+      throw new OidcVaultHttpError(
+        502,
+        "OIDC_VAULT_USERINFO_FAILED",
+        "OIDC userinfo request failed.",
+        "OIDC userinfo request failed."
+      );
+    }
+    const json = await readJsonResponse(response, "OIDC_VAULT_USERINFO_FAILED", void 0, { signal });
+    return json;
+  } finally {
+    done();
+    cancelBestEffort(() => response.body?.cancel());
   }
-  return json;
 }
 
 // src/token-validation.ts
@@ -764,6 +1065,9 @@ var defaultJwtClaimsMapper = (claims) => {
   };
 };
 var assertUserInfoSubject = (userInfo, subject) => {
+  if (typeof userInfo !== "object" || userInfo === null || Array.isArray(userInfo)) {
+    throw new OidcVaultHttpError(502, "OIDC_VAULT_INVALID_USERINFO", "OIDC userinfo response is invalid.");
+  }
   if (!isString(userInfo.sub)) {
     throw new OidcVaultHttpError(502, "OIDC_VAULT_INVALID_USERINFO", "OIDC userinfo response is missing sub.");
   }
@@ -776,6 +1080,12 @@ var mergeUserProfile = (sub, idTokenClaims, userInfo) => ({
   ...userInfo ?? {},
   sub
 });
+var composeRefreshedUserProfile = (sub, currentUser, freshIdClaims, freshUserInfo) => {
+  if (freshIdClaims === void 0) {
+    return mergeUserProfile(sub, { ...currentUser ?? { sub } }, freshUserInfo);
+  }
+  return mergeUserProfile(sub, { ...freshIdClaims }, freshUserInfo);
+};
 async function verifyIdToken(metadata, idToken, nonce, options = {}) {
   if (!metadata.jwksUri) {
     throw new OidcVaultHttpError(500, "OIDC_VAULT_MISSING_JWKS_URI", "OIDC jwksUri is required to validate id_token.");
@@ -916,10 +1226,17 @@ var extractBearerToken = (authorizationHeader) => {
 var setBearerChallengeHeader = (res) => {
   res.setHeader("WWW-Authenticate", "Bearer");
 };
+var notifyBearerMiddlewareError = async (options, context) => {
+  try {
+    await options.onError?.(context);
+  } catch {
+  }
+};
 function createOidcVaultAccessTokenMiddleware(options) {
   return async (req, res, next) => {
+    let token;
     try {
-      const token = extractBearerToken(req.get("authorization"));
+      token = extractBearerToken(req.get("authorization"));
       const validationResult = await options.validator.validate(token);
       const auth = {
         token,
@@ -927,9 +1244,38 @@ function createOidcVaultAccessTokenMiddleware(options) {
       };
       const authenticatedRequest = req;
       authenticatedRequest.auth = auth;
-      await options.onAuthContext?.({ req: authenticatedRequest, res, auth });
+      try {
+        await options.onAuthContext?.({ req: authenticatedRequest, res, auth });
+      } catch (hookError) {
+        delete authenticatedRequest.auth;
+        await notifyBearerMiddlewareError(options, { error: hookError, req, res, token, auth });
+        if (res.headersSent) {
+          next(hookError);
+          return;
+        }
+        if (hookError instanceof OidcVaultHttpError) {
+          if (hookError.status === 401) {
+            setBearerChallengeHeader(res);
+          }
+          res.status(hookError.status).json({
+            code: hookError.code,
+            message: hookError.clientMessage
+          });
+          return;
+        }
+        res.status(500).json({
+          code: "OIDC_VAULT_AUTH_CONTEXT_FAILED",
+          message: "Auth context hook failed."
+        });
+        return;
+      }
       next();
     } catch (error) {
+      await notifyBearerMiddlewareError(options, { error, req, res, ...token ? { token } : {} });
+      if (res.headersSent) {
+        next(error);
+        return;
+      }
       if (error instanceof OidcVaultHttpError) {
         setBearerChallengeHeader(res);
         res.status(error.status).json({
@@ -955,28 +1301,43 @@ function normalizeOidcVaultBasePath(value) {
   return `/${value.replace(/^\/+|\/+$/g, "")}`;
 }
 var getNow = (options) => (options.now ?? Date.now)();
+var CREDENTIAL_RESPONSE_CACHE_CONTROL = "no-store";
+var applyCredentialResponseCachePolicy = (res) => {
+  res.setHeader("Cache-Control", CREDENTIAL_RESPONSE_CACHE_CONTROL);
+};
 var createOpaqueId = (prefix) => `${prefix}_${randomBytes(16).toString("base64url")}`;
 var createPkceVerifier = () => randomBytes(32).toString("base64url");
 var createPkceChallenge = (verifier) => createHash("sha256").update(verifier).digest("base64url");
 var getCallbackUri = (backendOrigin, basePath) => `${backendOrigin}${basePath}${OIDC_VAULT_ROUTE_PATHS.callback}`;
 var validateOidcVaultOptions = (options) => {
+  validateLifetimeOptions(options, getNow(options));
   const backendOrigin = resolveBackendOrigin(options);
   const frontendRedirectUri = resolveFrontendRedirectUri(options);
   validatePostLogoutRedirectUri(options);
   validateCookieOptions(options);
-  const config = resolveOidcVaultConfig(options.config);
+  const config = resolveOidcVaultConfig(options.config ? { ...options.config } : void 0);
   const configuredTrustedOrigins = resolveTrustedOrigins(options);
   if (usesCrossSiteCookieTransport(options) && configuredTrustedOrigins.size === 0) {
     throw new Error("trustedOrigins is required when using cross-site cookie transport.");
   }
   const trustedOrigins = new Set(configuredTrustedOrigins);
   trustedOrigins.add(backendOrigin);
-  if (frontendRedirectUri) {
-    options.frontendRedirectUri = frontendRedirectUri;
-  }
-  return { backendOrigin, config, trustedOrigins };
+  const resolvedOptions = {
+    ...options,
+    ...frontendRedirectUri !== void 0 ? { frontendRedirectUri } : {},
+    ...options.trustedOrigins ? { trustedOrigins: [...options.trustedOrigins] } : {},
+    ...options.cookie ? { cookie: { ...options.cookie } } : {},
+    ...options.config ? { config: { ...options.config } } : {}
+  };
+  return { backendOrigin, config, trustedOrigins, resolvedOptions };
 };
 var isStoreConflictError = (error) => error instanceof OidcVaultStoreConflictError || typeof error === "object" && error !== null && "name" in error && error.name === "OidcVaultStoreConflictError";
+var assertSessionIdentity = (session, config) => {
+  const provider = session.provider;
+  if (provider?.issuer !== void 0 && provider.issuer !== config.issuer || provider?.clientId !== void 0 && provider.clientId !== config.clientId) {
+    throw new OidcVaultHttpError(401, "OIDC_VAULT_INVALID_SESSION", "Session is missing or expired.");
+  }
+};
 var getSessionIdFromRequest = (req, options, action) => {
   if (usesCookieTransport(options)) {
     const cookieSessionId = getSessionIdFromCookie(req, options);
@@ -999,7 +1360,9 @@ var getSessionIdFromRequest = (req, options, action) => {
 var createExchangeResponse = (options, session, issuedToken) => ({
   sessionId: usesCookieTransport(options) ? void 0 : session.sessionId,
   user: session.user,
-  ...issuedToken
+  accessToken: issuedToken.accessToken,
+  expiresIn: issuedToken.expiresIn,
+  tokenType: issuedToken.tokenType
 });
 var appendQueryParam = (url, name, value) => {
   if (value) {
@@ -1032,6 +1395,10 @@ var getLogoutTokenFromRequest = (req) => {
     "OIDC_VAULT_MISSING_LOGOUT_TOKEN"
   );
 };
+var buildBackchannelLogoutReplayKey = (input) => {
+  const encode = (value) => Buffer.from(value, "utf8").toString("base64url");
+  return `v2:${encode(input.issuer ?? "")}:${encode(input.clientId ?? "")}:${encode(input.jti)}`;
+};
 var createHookContext = (route, req, res, session, metadata) => ({ route, req, res, session, metadata });
 var resolveReturnTo = (req, options) => {
   const rawReturnTo = req.query.returnTo;
@@ -1071,7 +1438,21 @@ var withIssuedToken = async (req, res, options, session) => {
   if (!options.tokenIssuer) {
     return {};
   }
-  return options.tokenIssuer.issue({ req, res, session });
+  const result = await options.tokenIssuer.issue({ req, res, session });
+  if (typeof result !== "object" || result === null || Array.isArray(result)) {
+    throw new TypeError("tokenIssuer.issue must return a token result object.");
+  }
+  const { accessToken, expiresIn, tokenType } = result;
+  if (typeof accessToken !== "string" || accessToken.length === 0) {
+    throw new TypeError("tokenIssuer.issue accessToken must be a nonempty string.");
+  }
+  if (typeof expiresIn !== "number" || !Number.isSafeInteger(expiresIn) || expiresIn < 0) {
+    throw new TypeError("tokenIssuer.issue expiresIn must be a finite nonnegative safe integer.");
+  }
+  if (tokenType !== void 0 && tokenType !== "Bearer") {
+    throw new TypeError("tokenIssuer.issue tokenType must be Bearer when provided.");
+  }
+  return { accessToken, expiresIn, ...tokenType === void 0 ? {} : { tokenType } };
 };
 var resolveFrontendRedirectUri2 = (transaction, options) => {
   const redirectUri = transaction.returnTo ?? options.frontendRedirectUri;
@@ -1119,6 +1500,7 @@ async function handleRouteError(route, req, res, next, options, error) {
     next(error);
     return;
   }
+  applyCredentialResponseCachePolicy(res);
   const payload = toErrorPayload(error);
   res.status(payload.status).json({
     code: payload.code,
@@ -1140,6 +1522,7 @@ function createBodyParserErrorHandler() {
       next(error);
       return;
     }
+    applyCredentialResponseCachePolicy(res);
     const payload = toBodyParserErrorPayload(error);
     res.status(payload.status).json({
       code: payload.code,
@@ -1159,7 +1542,11 @@ var createLoginHandler = (options, config, backendOrigin, basePath) => createAsy
     codeChallenge: createPkceChallenge(pkceVerifier),
     returnTo: resolveReturnTo(req, options),
     createdAt: now,
-    expiresAt: now + (options.authorizationTransactionTtlMs ?? DEFAULT_AUTHORIZATION_TRANSACTION_TTL_MS)
+    expiresAt: computeExpiresAt(
+      now,
+      options.authorizationTransactionTtlMs ?? DEFAULT_AUTHORIZATION_TRANSACTION_TTL_MS,
+      "authorizationTransactionTtlMs"
+    )
   };
   await options.storeProvider.createAuthorizationTransaction(transaction);
   const authorizationUrl = buildAuthorizationUrl(metadata, transaction, getCallbackUri(backendOrigin, basePath));
@@ -1183,6 +1570,7 @@ var createCallbackHandler = (options, config, backendOrigin, basePath) => create
   if (!transaction) {
     throw new OidcVaultHttpError(400, "OIDC_VAULT_INVALID_STATE", "OIDC state is invalid or expired.");
   }
+  const frontendDestination = resolveFrontendRedirectUri2(transaction, options);
   const metadata = await resolveProviderMetadata(config, options);
   const tokenResponse = await requestToken(
     metadata,
@@ -1194,17 +1582,7 @@ var createCallbackHandler = (options, config, backendOrigin, basePath) => create
     },
     options
   );
-  validateTokenResponse(tokenResponse);
-  if (!isString(tokenResponse.id_token)) {
-    throw new OidcVaultHttpError(502, "OIDC_VAULT_MISSING_ID_TOKEN", "OIDC token response is missing id_token.");
-  }
-  if (!isString(tokenResponse.refresh_token)) {
-    throw new OidcVaultHttpError(
-      502,
-      "OIDC_VAULT_MISSING_REFRESH_TOKEN",
-      "OIDC token response is missing refresh_token."
-    );
-  }
+  validateCallbackTokenResponse(tokenResponse);
   await callHook("callback", options.hooks?.onCallbackTokens, req, res, void 0, {
     hasAccessToken: Boolean(tokenResponse.access_token),
     hasRefreshToken: true,
@@ -1213,13 +1591,19 @@ var createCallbackHandler = (options, config, backendOrigin, basePath) => create
   const claims = await verifyIdToken(metadata, tokenResponse.id_token, transaction.nonce, options);
   const subject = getRequiredString(claims.sub, "OIDC id_token is missing sub.", "OIDC_VAULT_INVALID_ID_TOKEN", 502);
   const userInfo = shouldFetchUserInfo(options, metadata) && isString(tokenResponse.access_token) ? await fetchUserInfo(metadata, tokenResponse.access_token, options) : void 0;
-  if (userInfo) {
+  if (userInfo !== void 0) {
     assertUserInfoSubject(userInfo, subject);
   }
-  if (userInfo) {
+  if (userInfo !== void 0) {
     await callHook("callback", options.hooks?.onUserInfo, req, res, void 0, { subject });
   }
   const now = getNow(options);
+  const sessionExpiresAt = options.sessionTtlMs === void 0 ? void 0 : computeExpiresAt(now, options.sessionTtlMs, "sessionTtlMs");
+  const exchangeExpiresAt = computeExpiresAt(
+    now,
+    options.exchangeCodeTtlMs ?? DEFAULT_EXCHANGE_CODE_TTL_MS,
+    "exchangeCodeTtlMs"
+  );
   const sessionId = createOpaqueId("sess");
   const session = {
     sessionId,
@@ -1236,12 +1620,16 @@ var createCallbackHandler = (options, config, backendOrigin, basePath) => create
     scope: typeof tokenResponse.scope === "string" ? tokenResponse.scope : metadata.scopes,
     createdAt: now,
     updatedAt: now,
+    ...sessionExpiresAt === void 0 ? {} : { expiresAt: sessionExpiresAt },
     user: mergeUserProfile(subject, claims, userInfo),
     metadata: {
       tokenType: tokenResponse.token_type
     }
   };
   await callHook("callback", options.hooks?.onBeforeSessionCreate, req, res, session, { subject });
+  if (sessionExpiresAt !== void 0) {
+    session.expiresAt = isUsableEpochMs(session.expiresAt) ? Math.min(session.expiresAt, sessionExpiresAt) : sessionExpiresAt;
+  }
   const createdSession = await options.storeProvider.createSession(session);
   const exchangeCode = createOpaqueId("code");
   try {
@@ -1250,7 +1638,7 @@ var createCallbackHandler = (options, config, backendOrigin, basePath) => create
       sessionId: createdSession.sessionId,
       returnTo: transaction.returnTo,
       createdAt: now,
-      expiresAt: now + (options.exchangeCodeTtlMs ?? DEFAULT_EXCHANGE_CODE_TTL_MS)
+      expiresAt: exchangeExpiresAt
     });
   } catch (error) {
     await options.storeProvider.deleteSessionsByLogicalSessionId({
@@ -1261,9 +1649,9 @@ var createCallbackHandler = (options, config, backendOrigin, basePath) => create
   await callPostCommitHook("callback", options, options.hooks?.onSessionCreated, req, res, createdSession, {
     subject
   });
-  res.redirect(302, appendCodeToRedirectUri(resolveFrontendRedirectUri2(transaction, options), exchangeCode));
+  res.redirect(302, appendCodeToRedirectUri(frontendDestination, exchangeCode));
 });
-var createExchangeHandler = (options) => createAsyncHandler("exchange", options, async (req, res) => {
+var createExchangeHandler = (options, config) => createAsyncHandler("exchange", options, async (req, res) => {
   const body = getBody(req);
   const code = getRequiredString(body.code, "Exchange request is missing code.", "OIDC_VAULT_MISSING_EXCHANGE_CODE");
   const exchangeRecord = await options.storeProvider.consumeExchangeCode(code);
@@ -1274,6 +1662,7 @@ var createExchangeHandler = (options) => createAsyncHandler("exchange", options,
   if (!session) {
     throw new OidcVaultHttpError(401, "OIDC_VAULT_INVALID_SESSION", "Session is missing or expired.");
   }
+  assertSessionIdentity(session, config);
   let issuedToken;
   try {
     issuedToken = await withIssuedToken(req, res, options, session);
@@ -1302,6 +1691,7 @@ var createRefreshHandler = (options, config, trustedOrigins) => createAsyncHandl
     }
     throw new OidcVaultHttpError(401, "OIDC_VAULT_INVALID_SESSION", "Session is missing or expired.");
   }
+  assertSessionIdentity(currentSession, config);
   const metadata = await resolveProviderMetadata(config, options);
   const tokenResponse = await requestToken(
     metadata,
@@ -1311,16 +1701,16 @@ var createRefreshHandler = (options, config, trustedOrigins) => createAsyncHandl
     },
     options
   );
-  validateTokenResponse(tokenResponse);
+  validateRefreshTokenResponse(tokenResponse);
   const newIdToken = isString(tokenResponse.id_token) ? tokenResponse.id_token : void 0;
   const idToken = newIdToken ?? currentSession.idToken;
-  const claims = newIdToken ? await verifyIdToken(metadata, newIdToken, void 0, options) : currentSession.user ?? { sub: currentSession.subject };
-  const subject = newIdToken ? getRequiredString(claims.sub, "OIDC id_token is missing sub.", "OIDC_VAULT_INVALID_ID_TOKEN", 502) : currentSession.subject;
+  const freshClaims = newIdToken ? await verifyIdToken(metadata, newIdToken, void 0, options) : void 0;
+  const subject = freshClaims ? getRequiredString(freshClaims.sub, "OIDC id_token is missing sub.", "OIDC_VAULT_INVALID_ID_TOKEN", 502) : currentSession.subject;
   if (newIdToken && subject !== currentSession.subject) {
     throw new OidcVaultHttpError(502, "OIDC_VAULT_INVALID_ID_TOKEN", "OIDC refreshed id_token sub changed.");
   }
   const userInfo = shouldFetchUserInfo(options, metadata) && isString(tokenResponse.access_token) ? await fetchUserInfo(metadata, tokenResponse.access_token, options) : void 0;
-  if (userInfo) {
+  if (userInfo !== void 0) {
     assertUserInfoSubject(userInfo, subject);
   }
   const now = getNow(options);
@@ -1330,14 +1720,14 @@ var createRefreshHandler = (options, config, trustedOrigins) => createAsyncHandl
     sessionId: createOpaqueId("sess"),
     logicalSessionId,
     subject,
-    providerSessionId: typeof claims.sid === "string" ? claims.sid : currentSession.providerSessionId,
+    providerSessionId: freshClaims && typeof freshClaims.sid === "string" ? freshClaims.sid : currentSession.providerSessionId,
     refreshToken: isString(tokenResponse.refresh_token) ? tokenResponse.refresh_token : currentSession.refreshToken,
     idToken,
     accessToken: isString(tokenResponse.access_token) ? tokenResponse.access_token : currentSession.accessToken,
     scope: typeof tokenResponse.scope === "string" ? tokenResponse.scope : currentSession.scope,
     expiresAt: currentSession.expiresAt,
     updatedAt: now,
-    user: mergeUserProfile(subject, claims, userInfo ?? currentSession.user)
+    user: composeRefreshedUserProfile(subject, currentSession.user, freshClaims, userInfo)
   };
   let rotatedSession;
   try {
@@ -1389,6 +1779,7 @@ var createLogoutHandler = (options, config, trustedOrigins) => createAsyncHandle
     res.status(200).json({ loggedOut: true });
     return;
   }
+  assertSessionIdentity(session, config);
   await callHook("logout", options.hooks?.onBeforeLogout, req, res, session, void 0);
   await options.storeProvider.deleteSessionsByLogicalSessionId({
     logicalSessionId: session.logicalSessionId ?? session.sessionId
@@ -1396,8 +1787,24 @@ var createLogoutHandler = (options, config, trustedOrigins) => createAsyncHandle
   if (usesCookieTransport(options)) {
     clearSessionCookie(res, options);
   }
-  const metadata = await resolveProviderMetadata(config, options);
-  const upstreamLogoutUrl = metadata.endSessionEndpoint ? buildLogoutUrl(metadata.endSessionEndpoint, session.idToken, options.postLogoutRedirectUri) : void 0;
+  if (!redirect) {
+    await callPostCommitHook("logout", options, options.hooks?.onLogout, req, res, session);
+    res.status(200).json({ loggedOut: true });
+    return;
+  }
+  let upstreamLogoutUrl;
+  try {
+    const metadata = await resolveProviderMetadata(config, options);
+    upstreamLogoutUrl = metadata.endSessionEndpoint ? buildLogoutUrl(metadata.endSessionEndpoint, session.idToken, options.postLogoutRedirectUri) : void 0;
+  } catch (error) {
+    try {
+      await options.hooks?.onError?.({
+        ...createHookContext("logout", req, res, session),
+        error
+      });
+    } catch {
+    }
+  }
   await callPostCommitHook("logout", options, options.hooks?.onLogout, req, res, session);
   if (redirect && upstreamLogoutUrl) {
     res.redirect(302, upstreamLogoutUrl);
@@ -1411,26 +1818,40 @@ var createBackchannelLogoutHandler = (options, config) => createAsyncHandler("ba
   const metadata = await resolveProviderMetadata(config, options);
   const logoutToken = getLogoutTokenFromRequest(req);
   const claims = await verifyBackchannelLogoutToken(metadata, logoutToken, options);
+  const replayKey = buildBackchannelLogoutReplayKey({
+    issuer: metadata.issuer,
+    clientId: metadata.clientId,
+    jti: claims.jti
+  });
   const firstUse = await options.storeProvider.consumeBackchannelLogoutTokenJti({
-    jti: claims.jti,
+    jti: replayKey,
     expiresAt: claims.exp * 1e3
   });
-  if (!firstUse) {
-    res.status(200).json({
-      loggedOut: true,
-      revokedSessions: 0
-    });
-    return;
-  }
-  const revokedSessions = isString(claims.sid) ? await options.storeProvider.deleteSessionsByProviderSessionId({
+  const revokeMatchingSessions = () => isString(claims.sid) ? options.storeProvider.deleteSessionsByProviderSessionId({
     providerSessionId: claims.sid,
     issuer: metadata.issuer,
     clientId: metadata.clientId
-  }) : await options.storeProvider.deleteSessionsBySubject({
+  }) : options.storeProvider.deleteSessionsBySubject({
     subject: String(claims.sub),
     issuer: metadata.issuer,
     clientId: metadata.clientId
   });
+  if (!firstUse) {
+    const catchUpRevokedSessions = await revokeMatchingSessions();
+    if (catchUpRevokedSessions > 0) {
+      await callPostCommitHook("backchannel-logout", options, options.hooks?.onLogout, req, res, void 0, {
+        providerSessionId: claims.sid,
+        subject: claims.sub,
+        revokedSessions: catchUpRevokedSessions
+      });
+    }
+    res.status(200).json({
+      loggedOut: true,
+      revokedSessions: catchUpRevokedSessions
+    });
+    return;
+  }
+  const revokedSessions = await revokeMatchingSessions();
   await callPostCommitHook("backchannel-logout", options, options.hooks?.onLogout, req, res, void 0, {
     providerSessionId: claims.sid,
     subject: claims.sub,
@@ -1444,17 +1865,21 @@ var createBackchannelLogoutHandler = (options, config) => createAsyncHandler("ba
 function registerRoutes(router, options, config, trustedOrigins, backendOrigin, basePath) {
   router.get(OIDC_VAULT_ROUTE_PATHS.login, createLoginHandler(options, config, backendOrigin, basePath));
   router.get(OIDC_VAULT_ROUTE_PATHS.callback, createCallbackHandler(options, config, backendOrigin, basePath));
-  router.post(OIDC_VAULT_ROUTE_PATHS.exchange, createExchangeHandler(options));
+  router.post(OIDC_VAULT_ROUTE_PATHS.exchange, createExchangeHandler(options, config));
   router.post(OIDC_VAULT_ROUTE_PATHS.refresh, createRefreshHandler(options, config, trustedOrigins));
   router.post(OIDC_VAULT_ROUTE_PATHS.logout, createLogoutHandler(options, config, trustedOrigins));
   router.post(OIDC_VAULT_ROUTE_PATHS["backchannel-logout"], createBackchannelLogoutHandler(options, config));
 }
 function createOidcVaultMiddleware(options) {
-  const { backendOrigin, config, trustedOrigins } = validateOidcVaultOptions(options);
+  const { backendOrigin, config, trustedOrigins, resolvedOptions } = validateOidcVaultOptions(options);
   const rootRouter = express.Router();
   const baseRouter = express.Router();
-  const basePath = normalizeOidcVaultBasePath(options.basePath);
-  const requestBodyLimit = options.requestBodyLimit ?? DEFAULT_OIDC_VAULT_REQUEST_BODY_LIMIT;
+  const basePath = normalizeOidcVaultBasePath(resolvedOptions.basePath);
+  const requestBodyLimit = resolvedOptions.requestBodyLimit ?? DEFAULT_OIDC_VAULT_REQUEST_BODY_LIMIT;
+  baseRouter.use((_req, res, next) => {
+    applyCredentialResponseCachePolicy(res);
+    next();
+  });
   baseRouter.use(express.json({ limit: requestBodyLimit }));
   baseRouter.use(
     express.urlencoded({
@@ -1464,7 +1889,7 @@ function createOidcVaultMiddleware(options) {
     })
   );
   baseRouter.use(createBodyParserErrorHandler());
-  registerRoutes(baseRouter, options, config, trustedOrigins, backendOrigin, basePath);
+  registerRoutes(baseRouter, resolvedOptions, config, trustedOrigins, backendOrigin, basePath);
   rootRouter.use(basePath, baseRouter);
   return rootRouter;
 }