@web-ts-toolkit/express-oidc-vault 0.53.0 → 0.54.0

package/index.mjs

@@ -1,5 +1,5 @@
 // src/index.ts
-import { createHash as createHash6, randomBytes as randomBytes3 } from "crypto";
+import { createHash as createHash8, randomBytes as randomBytes4 } from "crypto";
 import express from "express";
 
 // src/errors.ts
@@ -97,6 +97,7 @@ var OIDC_VAULT_ROUTE_PATHS = {
   exchange: "/exchange",
   refresh: "/refresh",
   logout: "/logout",
+  "logout-navigation": "/logout/navigation",
   "backchannel-logout": "/backchannel-logout"
 };
 
@@ -570,10 +571,11 @@ var invalidProof = (diagnostic, cause) => {
   if (cause !== void 0) Object.defineProperty(error, "cause", { value: cause, configurable: true });
   return error;
 };
-var extractDpopProof = (header) => {
+var extractDpopProof = (header, diagnostic) => {
   if (header.count === 0) return void 0;
   const { value } = header;
   if (header.count !== 1 || typeof value !== "string" || value.length === 0 || value.length > DPOP_PROOF_MAX_BYTES || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(value)) {
+    diagnostic?.emit("presentation", "rejected", "malformed-proof");
     throw invalidProof("DPoP header must contain one bounded compact signed proof.");
   }
   return value;
@@ -651,58 +653,105 @@ var publicJwk = (value, alg) => {
   return value;
 };
 var verifyDpopProof = async (input) => {
-  const { proof, method, targetUrl, proofOptions, expectedJkt, accessToken } = input;
+  const { proof, method, targetUrl, proofOptions, expectedJkt, accessToken, diagnostic } = input;
   const algorithms = [...proofOptions.algorithms];
   const { ignoreTargetFailure } = proofOptions;
-  extractDpopProof({ count: 1, value: proof });
-  const [encodedHeader, encodedPayload, encodedSignature] = proof.split(".");
-  const header = parseObject(decodeBase64url2(encodedHeader, DPOP_PROTECTED_HEADER_MAX_BYTES));
-  decodeBase64url2(encodedPayload, DPOP_PROOF_MAX_BYTES);
-  const signature = decodeBase64url2(encodedSignature, 512);
-  const { alg } = header;
-  if (header.typ !== "dpop+jwt" || !isDpopAlgorithm(alg) || !algorithms.includes(alg) || ["crit", "b64", "jku", "x5u", "x5c", "x5t", "x5t#S256"].some((key) => Object.hasOwn(header, key))) {
-    throw invalidProof("DPoP protected header has an unsupported type, algorithm or key/critical extension.");
-  }
-  const jwk = publicJwk(header.jwk, alg);
-  const signatureBytes = alg === "ES256" ? 64 : decodeBase64url2(jwk.n, 512).length;
-  if (signature.length !== signatureBytes)
-    throw invalidProof("DPoP signature length does not match the allowed key profile.");
-  let payload;
-  try {
-    const key = await importJWK(jwk, alg);
-    ({ payload } = await compactVerify(proof, key, { algorithms }));
-  } catch (cause) {
-    throw invalidProof("DPoP public-key import or signature verification failed.", cause);
-  }
-  const claims = parseObject(payload);
-  const { htm, htu, iat, jti, nonce, ath } = claims;
-  if (typeof iat !== "number" || !Number.isSafeInteger(iat) || iat < 0 || typeof jti !== "string" || jti.length < 1 || jti.length > 128 || /[^\x20-\x7e]/.test(jti)) {
-    throw invalidProof("DPoP signed iat/JTI must be nonnegative integer time and bounded printable ASCII.");
-  }
+  let stage = "header";
+  let reason = "malformed-proof";
   try {
-    const expectedTarget = typeof targetUrl === "function" ? targetUrl() : targetUrl;
-    if (htm !== method || typeof method !== "string" || method.length === 0 || normalizeDpopProofTarget(htu) !== expectedTarget) {
-      throw invalidProof("DPoP signed method or normalized public target does not match this request.");
+    extractDpopProof({ count: 1, value: proof }, diagnostic);
+    const [encodedHeader, encodedPayload, encodedSignature] = proof.split(".");
+    const header = parseObject(decodeBase64url2(encodedHeader, DPOP_PROTECTED_HEADER_MAX_BYTES));
+    decodeBase64url2(encodedPayload, DPOP_PROOF_MAX_BYTES);
+    const signature = decodeBase64url2(encodedSignature, 512);
+    const { alg } = header;
+    reason = "unsupported-header";
+    if (header.typ !== "dpop+jwt" || !isDpopAlgorithm(alg) || !algorithms.includes(alg) || ["crit", "b64", "jku", "x5u", "x5c", "x5t", "x5t#S256"].some((key) => Object.hasOwn(header, key))) {
+      throw invalidProof("DPoP protected header has an unsupported type, algorithm or key/critical extension.");
+    }
+    diagnostic?.emit("header", "accepted", "check-passed");
+    stage = "key";
+    reason = "invalid-key";
+    const jwk = publicJwk(header.jwk, alg);
+    stage = "signature";
+    reason = "invalid-signature";
+    const signatureBytes = alg === "ES256" ? 64 : decodeBase64url2(jwk.n, 512).length;
+    if (signature.length !== signatureBytes)
+      throw invalidProof("DPoP signature length does not match the allowed key profile.");
+    let payload;
+    try {
+      stage = "key";
+      reason = "invalid-key";
+      const key = await importJWK(jwk, alg);
+      diagnostic?.emit("key", "accepted", "check-passed");
+      stage = "signature";
+      reason = "invalid-signature";
+      ({ payload } = await compactVerify(proof, key, { algorithms }));
+    } catch (cause) {
+      throw invalidProof("DPoP public-key import or signature verification failed.", cause);
+    }
+    diagnostic?.mark({ signature: "verified" });
+    diagnostic?.emit("signature", "accepted", "check-passed");
+    stage = "claims";
+    reason = "invalid-claims";
+    const claims = parseObject(payload);
+    const { htm, htu, iat, jti, nonce, ath } = claims;
+    if (typeof iat !== "number" || !Number.isSafeInteger(iat) || iat < 0 || typeof jti !== "string" || jti.length < 1 || jti.length > 128 || /[^\x20-\x7e]/.test(jti)) {
+      throw invalidProof("DPoP signed iat/JTI must be nonnegative integer time and bounded printable ASCII.");
+    }
+    diagnostic?.signedTime(iat);
+    diagnostic?.emit("claims", "accepted", "check-passed");
+    stage = "target";
+    reason = "target-mismatch";
+    try {
+      const expectedTarget = typeof targetUrl === "function" ? targetUrl() : targetUrl;
+      if (htm !== method || typeof method !== "string" || method.length === 0 || normalizeDpopProofTarget(htu) !== expectedTarget) {
+        throw invalidProof("DPoP signed method or normalized public target does not match this request.");
+      }
+      diagnostic?.mark({ target: "matched" });
+      diagnostic?.emit("target", "accepted", "check-passed");
+    } catch (error) {
+      if (ignoreTargetFailure) {
+        diagnostic?.mark({ target: "ignored" });
+        diagnostic?.emit("target", "ignored", reason);
+      }
+      handleDpopCheckFailure(ignoreTargetFailure, "target", error);
+    }
+    stage = "nonce";
+    reason = "invalid-nonce";
+    if (typeof nonce === "string" && (nonce.length > DPOP_NONCE_MAX_BYTES || Buffer.byteLength(nonce, "utf8") > DPOP_NONCE_MAX_BYTES)) {
+      throw invalidProof("DPoP signed nonce exceeds its byte bound.");
     }
+    stage = "token-hash";
+    reason = "token-hash-mismatch";
+    if (accessToken !== void 0 && (typeof accessToken !== "string" || !/^[\x21-\x7e]+$/.test(accessToken) || !isCanonicalDpopJkt(ath) || ath !== createHash2("sha256").update(accessToken, "ascii").digest("base64url"))) {
+      throw invalidProof("DPoP signed access-token hash does not match the presented API token.");
+    }
+    diagnostic?.mark({ tokenHash: accessToken === void 0 ? "not-applicable" : "matched" });
+    if (accessToken !== void 0) diagnostic?.emit("token-hash", "accepted", "check-passed");
+    stage = "binding";
+    reason = "key-mismatch";
+    const jkt = await calculateJwkThumbprint(jwk, "sha256");
+    if (expectedJkt !== void 0 && (!isCanonicalDpopJkt(expectedJkt) || jkt !== expectedJkt)) {
+      throw invalidProof("DPoP verified public key does not match the original credential confirmation.");
+    }
+    diagnostic?.mark({ credentialBinding: expectedJkt === void 0 ? "not-applicable" : "matched" });
+    if (expectedJkt !== void 0) diagnostic?.emit("binding", "accepted", "check-passed");
+    return Object.freeze({
+      binding: Object.freeze({ type: "dpop", jkt, alg }),
+      iat,
+      jti,
+      ...nonce === void 0 ? {} : { nonce }
+    });
   } catch (error) {
-    handleDpopCheckFailure(ignoreTargetFailure, "target", error);
-  }
-  if (typeof nonce === "string" && (nonce.length > DPOP_NONCE_MAX_BYTES || Buffer.byteLength(nonce, "utf8") > DPOP_NONCE_MAX_BYTES)) {
-    throw invalidProof("DPoP signed nonce exceeds its byte bound.");
-  }
-  if (accessToken !== void 0 && (typeof accessToken !== "string" || !/^[\x21-\x7e]+$/.test(accessToken) || !isCanonicalDpopJkt(ath) || ath !== createHash2("sha256").update(accessToken, "ascii").digest("base64url"))) {
-    throw invalidProof("DPoP signed access-token hash does not match the presented API token.");
-  }
-  const jkt = await calculateJwkThumbprint(jwk, "sha256");
-  if (expectedJkt !== void 0 && (!isCanonicalDpopJkt(expectedJkt) || jkt !== expectedJkt)) {
-    throw invalidProof("DPoP verified public key does not match the original credential confirmation.");
+    if (stage === "signature") diagnostic?.mark({ signature: "failed" });
+    else if (stage === "target") diagnostic?.mark({ target: "failed" });
+    else if (stage === "token-hash") diagnostic?.mark({ tokenHash: "failed" });
+    else if (stage === "binding") diagnostic?.mark({ credentialBinding: "failed" });
+    else if (stage === "nonce") diagnostic?.mark({ nonce: "failed" });
+    diagnostic?.emit(stage, "rejected", reason);
+    throw error;
   }
-  return Object.freeze({
-    binding: Object.freeze({ type: "dpop", jkt, alg }),
-    iat,
-    jti,
-    ...nonce === void 0 ? {} : { nonce }
-  });
 };
 
 // src/fingerprint-recognition.ts
@@ -765,11 +814,11 @@ var snapshotFingerprintRecognition = (metadata) => {
   const value = metadata?.[FINGERPRINT_RECOGNITION_METADATA_KEY];
   if (value === void 0) return void 0;
   if (!isPlainRecord2(value)) throw new TypeError("Stored fingerprint recognition metadata is invalid.");
-  const { version, hash } = value;
-  if (Object.keys(value).length !== 2 || !Object.hasOwn(value, "version") || !Object.hasOwn(value, "hash") || version !== 1 || !isCanonicalDpopJkt(hash)) {
+  const { version, hash: hash2 } = value;
+  if (Object.keys(value).length !== 2 || !Object.hasOwn(value, "version") || !Object.hasOwn(value, "hash") || version !== 1 || !isCanonicalDpopJkt(hash2)) {
     throw new TypeError("Stored fingerprint recognition metadata is invalid.");
   }
-  return Object.freeze({ version, hash });
+  return Object.freeze({ version, hash: hash2 });
 };
 var fingerprintRecognitionMatches = (actual, original) => actual?.hash === original?.hash;
 var assertFingerprintRecognition = (policy, original, supplied) => {
@@ -1105,6 +1154,249 @@ function resolveOidcVaultConfigFromEnv(env = process.env) {
   });
 }
 
+// src/diagnostics.ts
+import { createHash as createHash5 } from "crypto";
+var createDiagnosticDispatcher = (observer) => {
+  let pending = 0;
+  let invoking = false;
+  return (event) => {
+    if (!observer || invoking || pending >= 32) return;
+    invoking = true;
+    try {
+      const result = observer(event);
+      if (result !== void 0) {
+        pending++;
+        const release = () => {
+          pending--;
+        };
+        void Promise.resolve(result).then(release, release);
+      }
+    } catch {
+    } finally {
+      invoking = false;
+    }
+  };
+};
+var reference = (purpose, value) => typeof value === "string" && value.length > 0 && value.length <= 1024 ? createHash5("sha256").update(`${purpose}\0${value}`, "utf8").digest("base64url") : void 0;
+var diagnosticCorrelation = (association, subject, sessionId) => {
+  const subjectRef = reference("subject", subject);
+  const sessionRef = reference("session", sessionId);
+  return Object.freeze({ association, ...subjectRef ? { subjectRef } : {}, ...sessionRef ? { sessionRef } : {} });
+};
+var DpopDiagnostic = class {
+  constructor(operation, dispatch) {
+    this.operation = operation;
+    this.dispatch = dispatch;
+    this.verification = {
+      signature: "unchecked",
+      target: "unchecked",
+      tokenHash: "unchecked",
+      credentialBinding: "unchecked",
+      freshness: "unchecked",
+      nonce: "unchecked",
+      replay: "unchecked"
+    };
+    this.terminal = false;
+  }
+  associate(correlation) {
+    this.correlation = correlation;
+  }
+  mark(update) {
+    this.verification = { ...this.verification, ...update };
+  }
+  signedTime(iatSeconds) {
+    this.timing = Object.freeze({ provenance: "signature-verified", iatSeconds });
+  }
+  checkTime(checkedAtMs, clock) {
+    if (!this.timing) return;
+    const issuedAt = this.timing.iatSeconds * 1e3;
+    const age = checkedAtMs - issuedAt;
+    this.timing = Object.freeze({
+      ...this.timing,
+      clock,
+      checkedAtMs,
+      ...Number.isSafeInteger(issuedAt) && Number.isSafeInteger(age) ? { observedAgeMs: age } : {}
+    });
+  }
+  emit(stage, outcome, reason) {
+    if (this.terminal) return;
+    if (outcome === "rejected" || outcome === "challenged" || stage === "proof" || stage === "presentation" && outcome === "ignored")
+      this.terminal = true;
+    this.dispatch(
+      Object.freeze({
+        operation: this.operation,
+        stage,
+        outcome,
+        reason,
+        verification: Object.freeze({ ...this.verification }),
+        ...this.timing ? { timing: this.timing } : {},
+        ...this.correlation ? { correlation: this.correlation } : {}
+      })
+    );
+  }
+  accept() {
+    if (this.correlation && this.hasAuthenticatedProof()) {
+      this.correlation = Object.freeze({ ...this.correlation, association: "authenticated" });
+    }
+    this.emit("proof", "accepted", "proof-accepted");
+  }
+  /** Policy acceptance with an ignored security check is not strict identity evidence. */
+  hasAuthenticatedProof() {
+    const v = this.verification;
+    return v.signature === "verified" && v.target === "matched" && v.credentialBinding === "matched" && (v.tokenHash === "matched" || v.tokenHash === "not-applicable") && v.freshness === "passed" && (v.nonce === "passed" || v.nonce === "disabled") && v.replay === "reserved";
+  }
+};
+var diagnosticPreflightReason = (code) => {
+  switch (code) {
+    case "OIDC_VAULT_DPOP_REQUIRED":
+      return "proof-required";
+    case "OIDC_VAULT_DEVICE_BINDING_REQUIRED":
+      return "binding-required";
+    case "OIDC_VAULT_INVALID_SESSION":
+      return "session-mismatch";
+    case "OIDC_VAULT_INVALID_EXCHANGE_CODE":
+      return "session-unavailable";
+    case "OIDC_VAULT_INVALID_ORIGIN":
+    case "OIDC_VAULT_UNTRUSTED_ORIGIN":
+      return "origin-rejected";
+    case "OIDC_VAULT_INVALID_BROWSER_BINDING":
+      return "browser-binding-rejected";
+    case "OIDC_VAULT_FINGERPRINT_REAUTH_REQUIRED":
+      return "recognition-rejected";
+    default:
+      return "preflight-failed";
+  }
+};
+var createDpopDiagnosticFactory = (observer) => {
+  const dispatch = createDiagnosticDispatcher(observer);
+  return (operation) => new DpopDiagnostic(operation, dispatch);
+};
+
+// src/logout-navigation.ts
+import { createHash as createHash6, randomBytes as randomBytes3 } from "crypto";
+import { isIP as isIP2 } from "net";
+
+// src/types.ts
+var OidcVaultStoreConflictError = class extends Error {
+  constructor(message = "OIDC vault store operation conflicted with concurrent state changes.") {
+    super(message);
+    this.name = "OidcVaultStoreConflictError";
+  }
+};
+var OidcVaultDpopReplayCapacityError = class extends Error {
+  constructor(message = "OIDC vault DPoP replay store capacity is exhausted.") {
+    super(message);
+    this.name = "OidcVaultDpopReplayCapacityError";
+  }
+};
+var OidcVaultLogoutNavigationCapacityError = class extends Error {
+  constructor(message = "OIDC vault logout navigation ticket store capacity is exhausted.") {
+    super(message);
+    this.name = "OidcVaultLogoutNavigationCapacityError";
+  }
+};
+
+// src/logout-navigation.ts
+var UNSAFE_URL = /[\s\\\u0000-\u001f\u007f-\u009f]/u;
+var TICKET = /^lnt_[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/;
+var hash = (value) => createHash6("sha256").update(value, "utf8").digest("base64url");
+var plainRecord = (value) => typeof value === "object" && value !== null && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+var destination = (value, name, maxBytes, secure) => {
+  const invalid = () => new TypeError(`${name} must be a bounded absolute HTTP(S) URL without unsafe characters, userinfo or fragment.`);
+  if (typeof value !== "string" || !/^https?:\/\//i.test(value) || /^https?:\/\/[^/?#]*@/i.test(value) || UNSAFE_URL.test(value) || value.includes("#") || Buffer.byteLength(value, "utf8") > maxBytes)
+    throw invalid();
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw invalid();
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "[::1]" || isIP2(url.hostname) === 4 && url.hostname.startsWith("127.");
+  if (url.protocol !== "https:" && url.protocol !== "http:" || secure && url.protocol === "http:" && !loopback || url.username || url.password || url.hash || Buffer.byteLength(url.href, "utf8") > maxBytes)
+    throw invalid();
+  return url;
+};
+var resolveLogoutNavigationOptions = (value, input) => {
+  if (value === void 0) return void 0;
+  if (!plainRecord(value)) throw new TypeError("logoutNavigation must be a plain options object.");
+  if (!input.deviceBindingConfigured) throw new TypeError("logoutNavigation requires deviceBinding.");
+  for (const name of ["createLogoutNavigationTicket", "consumeLogoutNavigationTicket"]) {
+    if (typeof input.store[name] !== "function")
+      throw new TypeError(`logoutNavigation requires storeProvider.${name}.`);
+  }
+  const { fallbackRedirectUri, ticketTtlMs = 6e4, namespace = "default" } = value;
+  if (!Number.isInteger(ticketTtlMs) || ticketTtlMs < 1e3 || ticketTtlMs > 12e4)
+    throw new TypeError("logoutNavigation.ticketTtlMs must be an integer from 1000 through 120000.");
+  computeExpiresAt(input.now, ticketTtlMs, "logoutNavigation.ticketTtlMs");
+  if (typeof namespace !== "string" || !/^[\x21-\x7e]{1,128}$/.test(namespace))
+    throw new TypeError("logoutNavigation.namespace must be a static printable ASCII label of 1 through 128 bytes.");
+  const path = `${input.basePath}${OIDC_VAULT_ROUTE_PATHS["logout-navigation"]}`;
+  const fallback = destination(fallbackRedirectUri, "logoutNavigation.fallbackRedirectUri", 2048, true);
+  if (fallback.origin !== input.backendOrigin && (input.frontendRedirectUri === void 0 || fallback.origin !== new URL(input.frontendRedirectUri).origin) || // Express's default mount/route matching is case-insensitive and accepts
+  // a trailing slash. Those aliases are continuation loops as well.
+  fallback.origin === input.backendOrigin && fallback.pathname.replace(/\/$/, "").toLowerCase() === path.toLowerCase())
+    throw new TypeError(
+      "logoutNavigation.fallbackRedirectUri must stay on the backend/frontend origin and cannot loop to logout navigation."
+    );
+  const postLogout = input.postLogoutRedirectUri === void 0 ? void 0 : destination(input.postLogoutRedirectUri, "logoutNavigation.postLogoutRedirectUri", 2048, true).href;
+  return Object.freeze({
+    fallbackRedirectUri: fallback.href,
+    ticketTtlMs,
+    namespace: "logout-navigation:v1:" + hash(
+      JSON.stringify([
+        "oidc-vault-logout-navigation",
+        1,
+        input.backendOrigin,
+        input.basePath,
+        input.config.issuer,
+        input.config.clientId,
+        namespace,
+        fallback.href,
+        postLogout ?? null
+      ])
+    ),
+    navigationUrl: `${input.backendOrigin}${path}`,
+    ...postLogout === void 0 ? {} : { postLogoutRedirectUri: postLogout }
+  });
+};
+var validateUpstreamLogoutUrl = (value) => destination(value, "Logout navigation upstream destination", 16384, false).href;
+var persistLogoutNavigation = async (policy, store, upstreamLogoutUrl, now) => {
+  const expiresAt = computeExpiresAt(now, policy.ticketTtlMs, "logoutNavigation.ticketTtlMs");
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const ticket = `lnt_${randomBytes3(32).toString("base64url")}`;
+    try {
+      await store.createLogoutNavigationTicket({
+        namespace: policy.namespace,
+        ticketHash: hash(ticket),
+        upstreamLogoutUrl,
+        createdAt: now,
+        expiresAt
+      });
+      return `${policy.navigationUrl}?ticket=${ticket}`;
+    } catch (error) {
+      const conflict = error instanceof OidcVaultStoreConflictError || typeof error === "object" && error !== null && "name" in error && error.name === "OidcVaultStoreConflictError";
+      if (!conflict || attempt === 2) throw error;
+    }
+  }
+  throw new Error("Logout navigation ticket attempts exhausted.");
+};
+var navigationTicketHash = (originalUrl) => {
+  const index = originalUrl.indexOf("?");
+  if (index < 0) return void 0;
+  const query = originalUrl.slice(index + 1);
+  if (!query.startsWith("ticket=")) return void 0;
+  const ticket = query.slice("ticket=".length);
+  return TICKET.test(ticket) ? hash(ticket) : void 0;
+};
+var consumedLogoutDestination = (value, namespace, ticketHash, now) => {
+  if (!plainRecord(value) || Object.keys(value).length !== 5)
+    throw new TypeError("Logout navigation consume returned an invalid record.");
+  const { namespace: returnedNamespace, ticketHash: returnedHash, upstreamLogoutUrl, createdAt, expiresAt } = value;
+  if (returnedNamespace !== namespace || returnedHash !== ticketHash || !isUsableEpochMs(now) || !isUsableEpochMs(createdAt) || !isUsableEpochMs(expiresAt) || expiresAt - createdAt < 1e3 || expiresAt - createdAt > 12e4 || expiresAt <= now || expiresAt - now > 12e4)
+    throw new TypeError("Logout navigation consume returned invalid identity or lifetime.");
+  return validateUpstreamLogoutUrl(upstreamLogoutUrl);
+};
+
 // src/utils.ts
 var isRecord = (value) => typeof value === "object" && value !== null;
 var isString = (value) => typeof value === "string" && value.length > 0;
@@ -1189,8 +1481,8 @@ var getRequestSourceOrigin = (req) => {
 var assertTrustedOrigin = (req, options, trustedOrigins, action) => {
   captureTrustedOriginGuard(req, options, trustedOrigins, action)();
 };
-var captureTrustedOriginGuard = (req, options, trustedOrigins, action) => {
-  const guarded = action === "login" || action === "exchange";
+var captureTrustedOriginGuard = (req, options, trustedOrigins, action, strict = false) => {
+  const guarded = strict || action === "login" || action === "exchange";
   if (!guarded && !usesCookieTransport(options)) {
     return () => {
     };
@@ -1958,6 +2250,28 @@ var createExchangeResponse = (options, session, issuedToken) => ({
   expiresIn: issuedToken.expiresIn,
   tokenType: issuedToken.tokenType
 });
+var notifyTokenOutcomes = (operation, session, issuedToken, notify, diagnostic) => {
+  const deviceBound = session.deviceBinding !== void 0;
+  const correlation = diagnosticCorrelation(
+    deviceBound && !diagnostic?.hasAuthenticatedProof() ? "candidate-session" : "authenticated",
+    session.subject,
+    session.logicalSessionId ?? session.sessionId
+  );
+  const tokenIssued = issuedToken.accessToken !== void 0;
+  if (tokenIssued)
+    notify(
+      Object.freeze({
+        kind: "token-issued",
+        operation,
+        correlation,
+        deviceBound,
+        expiresIn: issuedToken.expiresIn,
+        ...issuedToken.tokenType === void 0 ? {} : { tokenType: issuedToken.tokenType }
+      })
+    );
+  if (operation === "exchange")
+    notify(Object.freeze({ kind: "exchange-succeeded", operation, correlation, deviceBound, tokenIssued }));
+};
 var assertIssuedBoundJwt = (accessToken, jkt) => {
   if (!isCompactSignedJwt(accessToken)) {
     throw new TypeError("tokenIssuer.issue accessToken must be a compact signed JWT for bound issuance.");
@@ -1984,13 +2298,14 @@ var assertIssuedBoundJwt = (accessToken, jkt) => {
     throw new TypeError("tokenIssuer.issue accessToken exp must be a nonnegative safe integer with safe milliseconds.");
   }
 };
-var withIssuedToken = async (req, res, options, session, verifiedBinding) => {
+var withIssuedToken = async (req, res, options, session, operation, verifiedBinding) => {
   const binding = resolveVerifiedDeviceBinding(options.deviceBinding, session.deviceBinding, verifiedBinding);
   if (!options.tokenIssuer) return {};
   const logicalSessionId = session.logicalSessionId ?? session.sessionId;
   try {
     const issuerSession = withSessionDeviceBinding(copyVaultSession(session, true), binding);
     const result = await options.tokenIssuer.issue({
+      operation,
       req,
       res,
       session: issuerSession,
@@ -2029,7 +2344,32 @@ var withIssuedToken = async (req, res, options, session, verifiedBinding) => {
 };
 
 // src/token-validation.ts
-import { jwtVerify } from "jose";
+import { errors as joseErrors, jwtVerify } from "jose";
+
+// src/access-token-errors.ts
+var OidcVaultInvalidAccessTokenError = class extends OidcVaultHttpError {
+  constructor(message = "Access token rejected.") {
+    super(401, "OIDC_VAULT_INVALID_ACCESS_TOKEN", message, "Access token validation failed.");
+    this.name = "OidcVaultInvalidAccessTokenError";
+  }
+};
+var OidcVaultAuthDeniedError = class extends OidcVaultHttpError {
+  constructor(message = "Authentication denied.", status = 403) {
+    if (status !== 401 && status !== 403) throw new TypeError("Auth denial status must be 401 or 403.");
+    super(status, "OIDC_VAULT_AUTH_DENIED", message);
+    this.name = "OidcVaultAuthDeniedError";
+  }
+};
+var credentialOutcomes = /* @__PURE__ */ new WeakMap();
+var markAccessTokenRejected = (error) => {
+  if (typeof error === "object" && error !== null) credentialOutcomes.set(error, true);
+};
+var markAccessTokenValidationFailure = (error) => {
+  if (typeof error === "object" && error !== null) credentialOutcomes.set(error, false);
+};
+var isAccessTokenRejected = (error) => typeof error === "object" && error !== null && (credentialOutcomes.get(error) ?? error instanceof OidcVaultInvalidAccessTokenError);
+
+// src/token-validation.ts
 var BACKCHANNEL_LOGOUT_EVENT_CLAIM = "http://schemas.openid.net/event/backchannel-logout";
 var validateBackchannelLogoutTokenTyp = (typ) => {
   if (typ !== void 0 && (typeof typ !== "string" || typ.toLowerCase() !== "logout+jwt")) {
@@ -2188,20 +2528,36 @@ function createOidcVaultJwtAccessTokenValidator(options) {
   const audience = Array.isArray(configuredAudience) ? [...configuredAudience] : configuredAudience;
   const algorithms = configuredAlgorithms === void 0 ? void 0 : [...configuredAlgorithms];
   const validateJwt = async (token) => {
-    const result = await jwtVerify(token, key, { issuer, audience, algorithms });
-    const claims = result.payload;
-    const confirmation = snapshotVerifiedJwtConfirmation(claims);
-    if (confirmation !== null) {
-      if (!isCompactSignedJwt(token)) {
-        throw invalidAccessToken("Bound JWT must use canonical compact signed encoding.");
+    const result = await jwtVerify(token, key, { issuer, audience, algorithms }).catch((error) => {
+      if (error instanceof joseErrors.JWTExpired || error instanceof joseErrors.JWTClaimValidationFailed || error instanceof joseErrors.JWTInvalid || error instanceof joseErrors.JWSInvalid || error instanceof joseErrors.JWSSignatureVerificationFailed || error instanceof joseErrors.JOSEAlgNotAllowed) {
+        markAccessTokenRejected(error);
       }
-      if (readJwtExpirationMs(claims.exp) === void 0) {
-        throw invalidAccessToken("Bound JWT exp must be a nonnegative safe integer with safe milliseconds.");
+      throw error;
+    });
+    const claims = result.payload;
+    let confirmation;
+    try {
+      confirmation = snapshotVerifiedJwtConfirmation(claims);
+      if (confirmation !== null) {
+        if (!isCompactSignedJwt(token)) {
+          throw invalidAccessToken("Bound JWT must use canonical compact signed encoding.");
+        }
+        if (readJwtExpirationMs(claims.exp) === void 0) {
+          throw invalidAccessToken("Bound JWT exp must be a nonnegative safe integer with safe milliseconds.");
+        }
       }
+      if (!mapClaims) return { ...defaultJwtClaimsMapper(claims), confirmation };
+    } catch (error) {
+      markAccessTokenRejected(error);
+      throw error;
+    }
+    try {
+      const { subject, sessionId, scope, claims: mappedClaims } = mapClaims(claims);
+      return { subject, sessionId, scope, claims: mappedClaims, confirmation };
+    } catch (error) {
+      markAccessTokenValidationFailure(error);
+      throw error;
     }
-    const mapped = mapClaims ? mapClaims(claims) : defaultJwtClaimsMapper(claims);
-    const { subject, sessionId, scope, claims: mappedClaims } = mapped;
-    return { subject, sessionId, scope, claims: mappedClaims, confirmation };
   };
   return Object.freeze({
     async validate(token) {
@@ -2216,22 +2572,8 @@ function createOidcVaultJwtAccessTokenValidator(options) {
   });
 }
 
-// src/types.ts
-var OidcVaultStoreConflictError = class extends Error {
-  constructor(message = "OIDC vault store operation conflicted with concurrent state changes.") {
-    super(message);
-    this.name = "OidcVaultStoreConflictError";
-  }
-};
-var OidcVaultDpopReplayCapacityError = class extends Error {
-  constructor(message = "OIDC vault DPoP replay store capacity is exhausted.") {
-    super(message);
-    this.name = "OidcVaultDpopReplayCapacityError";
-  }
-};
-
 // src/dpop-replay.ts
-import { createHash as createHash5 } from "crypto";
+import { createHash as createHash7 } from "crypto";
 var isPrintableIdentifier = (value) => typeof value === "string" && /^[\x20-\x7e]{1,128}$/.test(value);
 var normalizeNamespaceBasePath = (origin, value) => {
   if (value !== void 0 && typeof value !== "string")
@@ -2269,7 +2611,7 @@ var createDpopReplayKey = (effectiveNamespace, jkt, jti) => {
   if (!isCanonicalDpopJkt(jkt) || !isPrintableIdentifier(jti)) {
     throw new TypeError("DPoP replay key requires a canonical thumbprint and a bounded printable JTI.");
   }
-  return `dpop:v1:${createHash5("sha256").update(JSON.stringify([effectiveNamespace, jkt, jti]), "utf8").digest("base64url")}`;
+  return `dpop:v1:${createHash7("sha256").update(JSON.stringify([effectiveNamespace, jkt, jti]), "utf8").digest("base64url")}`;
 };
 var getDpopReplayExpiresAt = (input) => {
   const { iat, now, proofMaxAgeSeconds: age, clockSkewSeconds: skew } = input;
@@ -2308,47 +2650,85 @@ var createDpopReplayPolicy = (options) => {
   });
   return Object.freeze({
     effectiveNamespace,
-    async verifyAndReserve(verifyBeforeReplay) {
+    async verifyAndReserve(verifyBeforeReplay, diagnostic) {
       const verified = await verifyBeforeReplay();
       if (typeof verified !== "object" || verified === null || Array.isArray(verified)) {
+        diagnostic?.emit("claims", "rejected", "invalid-claims");
         throw invalidProof2("DPoP verifier did not return a proof verification result.");
       }
       const { binding: verifiedBinding, iat, jti, nonce } = verified;
       if (typeof verifiedBinding !== "object" || verifiedBinding === null || Array.isArray(verifiedBinding)) {
+        diagnostic?.emit("binding", "rejected", "invalid-key");
         throw invalidProof2("DPoP verifier did not return a verified key binding.");
       }
       const { type, jkt, alg } = verifiedBinding;
       if (type !== "dpop" || !isCanonicalDpopJkt(jkt) || !isDpopAlgorithm(alg) || !policy.algorithms.includes(alg) || !isPrintableIdentifier(jti) || typeof iat !== "number" || !Number.isSafeInteger(iat) || iat < 0) {
+        diagnostic?.emit("claims", "rejected", "invalid-claims");
         throw invalidProof2("DPoP verified key/algorithm or signed iat/JTI shape is invalid.");
       }
       const binding = Object.freeze({ type, jkt, alg });
       let checkedNow;
+      let clockSource = configuredNow ? "configured" : "system";
       try {
         checkedNow = now();
         if (!Number.isSafeInteger(checkedNow) || checkedNow < 0) throw new TypeError("DPoP replay clock is invalid.");
       } catch (error) {
+        diagnostic?.mark({ freshness: policy.ignoreFreshnessFailure ? "ignored" : "failed" });
+        diagnostic?.emit("freshness", policy.ignoreFreshnessFailure ? "ignored" : "rejected", "clock-unavailable");
         handleDpopCheckFailure(policy.ignoreFreshnessFailure, "freshness", replayUnavailable(error));
         checkedNow = Date.now();
-        if (!Number.isSafeInteger(checkedNow) || checkedNow < 0)
+        if (!Number.isSafeInteger(checkedNow) || checkedNow < 0) {
+          diagnostic?.mark({ freshness: "failed" });
+          diagnostic?.emit("freshness", "rejected", "clock-unavailable");
           throw replayUnavailable(new TypeError("DPoP fallback clock is invalid."));
+        }
+        clockSource = "fallback";
       }
+      diagnostic?.checkTime(checkedNow, clockSource);
       let expiresAt = getDpopReplayExpiresAt({ ...policy, iat, now: checkedNow });
       if (expiresAt === null) {
+        diagnostic?.mark({ freshness: policy.ignoreFreshnessFailure ? "ignored" : "failed" });
+        diagnostic?.emit(
+          "freshness",
+          policy.ignoreFreshnessFailure ? "ignored" : "rejected",
+          !Number.isSafeInteger(iat * 1e3) || !Number.isSafeInteger((iat + policy.proofMaxAgeSeconds + policy.clockSkewSeconds) * 1e3) ? "invalid-time" : iat * 1e3 - checkedNow > policy.clockSkewSeconds * 1e3 ? "proof-in-future" : "proof-too-old"
+        );
         handleDpopCheckFailure(
           policy.ignoreFreshnessFailure,
           "freshness",
           invalidProof2("DPoP signed iat is outside the bounded replay window.")
         );
         expiresAt = checkedNow + (policy.proofMaxAgeSeconds + policy.clockSkewSeconds) * 1e3;
+      } else {
+        diagnostic?.mark({ freshness: clockSource === "fallback" ? "ignored" : "passed" });
+        diagnostic?.emit("freshness", "accepted", "check-passed");
       }
       if (noncePolicy) {
         if (!noncePolicy.verify(nonce, jkt, checkedNow)) {
-          return Object.freeze({ type: "nonce-challenge", nonce: noncePolicy.issue(jkt, checkedNow) });
+          let challengeNonce;
+          try {
+            challengeNonce = noncePolicy.issue(jkt, checkedNow);
+          } catch (error) {
+            diagnostic?.mark({ nonce: "failed" });
+            diagnostic?.emit("nonce", "rejected", "nonce-unavailable");
+            throw error;
+          }
+          diagnostic?.mark({ nonce: "challenged" });
+          diagnostic?.emit("nonce", "challenged", nonce === void 0 ? "nonce-required" : "nonce-invalid");
+          return Object.freeze({ type: "nonce-challenge", nonce: challengeNonce });
         }
+        diagnostic?.mark({ nonce: "passed" });
+        diagnostic?.emit("nonce", "accepted", "check-passed");
       } else if (nonce !== void 0 && (typeof nonce !== "string" || nonce.length > DPOP_NONCE_MAX_BYTES || Buffer.byteLength(nonce, "utf8") > DPOP_NONCE_MAX_BYTES)) {
+        diagnostic?.mark({ nonce: "failed" });
+        diagnostic?.emit("nonce", "rejected", "invalid-nonce");
         throw invalidProof2("DPoP signed nonce claim exceeds its string/byte bound.");
+      } else {
+        diagnostic?.mark({ nonce: "disabled" });
+        diagnostic?.emit("nonce", "ignored", "nonce-disabled");
       }
       let reservationError;
+      let unavailable = false;
       try {
         const reserved = await replayStore.reserveDpopProof({
           replayKey: createDpopReplayKey(effectiveNamespace, jkt, jti),
@@ -2359,8 +2739,21 @@ var createDpopReplayPolicy = (options) => {
         if (!reserved) reservationError = invalidProof2("DPoP replay reservation was duplicate or no longer live.");
       } catch (error) {
         reservationError = replayUnavailable(error);
+        unavailable = true;
       }
-      if (reservationError) handleDpopCheckFailure(policy.ignoreReplayFailure, "replay", reservationError);
+      if (reservationError) {
+        diagnostic?.mark({ replay: policy.ignoreReplayFailure ? "ignored" : "failed" });
+        diagnostic?.emit(
+          "replay",
+          policy.ignoreReplayFailure ? "ignored" : "rejected",
+          unavailable ? "replay-unavailable" : "replay-detected"
+        );
+        handleDpopCheckFailure(policy.ignoreReplayFailure, "replay", reservationError);
+      } else {
+        diagnostic?.mark({ replay: "reserved" });
+        diagnostic?.emit("replay", "accepted", "check-passed");
+      }
+      diagnostic?.accept();
       return Object.freeze({ type: "accepted", binding, expiresAt });
     }
   });
@@ -2399,7 +2792,8 @@ var toDpopNonceChallengeResponse = (result, endpoint, algorithms) => {
 };
 
 // src/vault-route-proof.ts
-var captureVaultRouteProof = (req) => Object.freeze({
+var captureVaultRouteProof = (req, diagnostic) => Object.freeze({
+  diagnostic,
   header: readDpopRawHeader(req, "dpop"),
   method: req.method,
   originalUrl: req.originalUrl
@@ -2423,14 +2817,17 @@ var createVaultRouteProofVerifier = (options, config, backendOrigin, basePath) =
     now: options.now
   });
   const admit = async (request, proof, expectedJkt) => {
+    const { diagnostic } = request;
     const result = await replay.verifyAndReserve(
       () => verifyDpopProof({
         proof,
         method: request.method,
         targetUrl: () => targetFor(request.originalUrl),
         proofOptions: policy,
-        expectedJkt
-      })
+        expectedJkt,
+        diagnostic
+      }),
+      diagnostic
     );
     if (result.type === "nonce-challenge") {
       throw new VaultDpopNonceChallengeError(toDpopNonceChallengeResponse(result, "vault-post", policy.algorithms));
@@ -2439,9 +2836,10 @@ var createVaultRouteProofVerifier = (options, config, backendOrigin, basePath) =
   };
   return Object.freeze({
     async initiate(request) {
-      const proof = extractDpopProof(request.header);
+      const proof = extractDpopProof(request.header, request.diagnostic);
       if (proof === void 0) {
         assertDeviceBindingPolicy(policy, void 0);
+        request.diagnostic?.emit("presentation", "ignored", "proof-absent");
         return void 0;
       }
       return admit(request, proof);
@@ -2449,9 +2847,11 @@ var createVaultRouteProofVerifier = (options, config, backendOrigin, basePath) =
     async verify(request, originalBinding) {
       const binding = snapshotDpopBinding(originalBinding);
       assertDeviceBindingPolicy(policy, binding);
-      const proof = extractDpopProof(request.header);
+      const proof = extractDpopProof(request.header, request.diagnostic);
       const verified = proof === void 0 ? void 0 : await admit(request, proof, binding?.jkt);
-      return resolveVerifiedDeviceBinding(policy, binding, verified);
+      const resolved = resolveVerifiedDeviceBinding(policy, binding, verified);
+      if (proof === void 0) request.diagnostic?.emit("presentation", "ignored", "proof-absent");
+      return resolved;
     }
   });
 };
@@ -2469,7 +2869,7 @@ var extractBearerToken = (authorizationHeader) => {
     throw new OidcVaultHttpError(401, "OIDC_VAULT_MISSING_BEARER_TOKEN", "Missing bearer token.");
   }
   const [scheme, token, extra] = authorizationHeader.trim().split(/\s+/);
-  if (scheme?.toLowerCase() !== "bearer" || !token || extra) {
+  if (scheme?.toLowerCase() !== "bearer" || !token || extra || !/^[\x21-\x7e]+$/.test(token) || token.includes(",")) {
     throw new OidcVaultHttpError(
       401,
       "OIDC_VAULT_INVALID_AUTHORIZATION_HEADER",
@@ -2496,8 +2896,40 @@ var mappedFields = (result) => {
     throw invalidAccessToken("Access token validator result is missing subject.");
   return { subject, sessionId, scope, claims };
 };
+var evidence = /* @__PURE__ */ new WeakMap();
+var authFields = ["subject", "sessionId", "scope", "claims", "token", "confirmation", "deviceBinding"];
+var credentialRejectionCodes = /* @__PURE__ */ new Set([
+  "OIDC_VAULT_MISSING_BEARER_TOKEN",
+  "OIDC_VAULT_MISSING_ACCESS_TOKEN",
+  "OIDC_VAULT_INVALID_AUTHORIZATION_HEADER",
+  "OIDC_VAULT_INVALID_ACCESS_TOKEN",
+  "OIDC_VAULT_DPOP_REQUIRED",
+  "OIDC_VAULT_DEVICE_BINDING_REQUIRED",
+  "OIDC_VAULT_INVALID_DPOP_PROOF"
+]);
+var clearChallenge = (res) => {
+  res.removeHeader("WWW-Authenticate");
+  res.removeHeader("DPoP-Nonce");
+  res.setHeader("Cache-Control", "no-store");
+};
+var sendError = (res, response) => {
+  clearChallenge(res);
+  for (const [name, value] of Object.entries(response.headers)) res.setHeader(name, value);
+  res.status(response.status).json(response.body);
+};
 function createOidcVaultAccessTokenMiddleware(options) {
-  const { validator, deviceBinding: configuredBinding, onAuthContext, onError } = options;
+  return createOidcVaultAuthenticator(options).authenticate;
+}
+function createOidcVaultAuthenticator(options) {
+  const { validator, deviceBinding: configuredBinding, onAuthContext, onError, onDpopDiagnostic } = options;
+  const createDiagnostic = createDpopDiagnosticFactory(onDpopDiagnostic);
+  const { authentication = "required", invalidCredentials = "reject" } = options;
+  if (authentication !== "required" && authentication !== "optional")
+    throw new TypeError("authentication must be required or optional.");
+  if (invalidCredentials !== "reject" && invalidCredentials !== "anonymous")
+    throw new TypeError("invalidCredentials must be reject or anonymous.");
+  if (invalidCredentials === "anonymous" && authentication !== "optional")
+    throw new TypeError("Anonymous invalid credentials require optional authentication.");
   const policy = resolveDeviceBindingOptions(configuredBinding);
   const validate = validator.validate.bind(validator);
   const requestAware = policy ? validator.validateWithRequest : void 0;
@@ -2529,56 +2961,134 @@ function createOidcVaultAccessTokenMiddleware(options) {
   const algs = algorithms.join(" ");
   const dpopChallenge = (error) => `DPoP${error ? ` error="${error}",` : ""} algs="${algs}"`;
   const proofChallenge = dpopChallenge("invalid_dpop_proof");
-  return async (req, res, next) => {
+  const owner = Object.freeze({});
+  const prepareError = (error, scheme, nonceResponse, hookFailure = false) => {
+    const response = nonceResponse ?? (error instanceof OidcVaultHttpError ? toDpopReplayErrorResponse(error, algorithms) : {
+      status: hookFailure ? 500 : 401,
+      body: hookFailure ? { code: "OIDC_VAULT_AUTH_CONTEXT_FAILED", message: "Auth context hook failed." } : { code: "OIDC_VAULT_INVALID_ACCESS_TOKEN", message: "Access token validation failed." },
+      headers: { "Cache-Control": "no-store" }
+    });
+    const headers = { ...response.headers };
+    if (response.status === 401 && headers["WWW-Authenticate"] === void 0) {
+      const code = response.body.code;
+      const challenge2 = code === "OIDC_VAULT_DPOP_REQUIRED" || code === "OIDC_VAULT_INVALID_DPOP_PROOF" ? proofChallenge : !policy ? "Bearer" : code === "OIDC_VAULT_MISSING_ACCESS_TOKEN" || code === "OIDC_VAULT_AUTHENTICATION_REQUIRED" ? policy.mode === "required" ? dpopChallenge() : `Bearer, ${dpopChallenge()}` : scheme === "DPoP" || !scheme && policy.mode === "required" ? dpopChallenge("invalid_token") : 'Bearer error="invalid_token"';
+      headers["WWW-Authenticate"] = challenge2;
+    }
+    return Object.freeze({
+      status: response.status,
+      body: Object.freeze({ ...response.body }),
+      headers: Object.freeze(headers)
+    });
+  };
+  const reentryError = () => new OidcVaultHttpError(500, "OIDC_VAULT_AUTHENTICATION_REENTRY", "Authentication is already running or completed.");
+  const rejectGuard = async (req, res, next) => {
+    const state = evidence.get(req);
+    const error = state?.status === "pending" ? reentryError() : new OidcVaultHttpError(401, "OIDC_VAULT_AUTHENTICATION_REQUIRED", "Authentication is required.");
+    if (state) state.status = "failed";
+    else evidence.set(req, { owner, res, status: "failed" });
+    delete req.auth;
+    const response = prepareError(error);
+    await notifyMiddlewareError(onError, { error, req, res });
+    delete req.auth;
+    if (res.headersSent) next(error);
+    else sendError(res, response);
+  };
+  const guard = (bound) => async (req, res, next) => {
+    const state = evidence.get(req);
+    const current = Object.getOwnPropertyDescriptor(req, "auth");
+    const intact = state?.auth && state.snapshot && current && "value" in current && current.value === state.auth && authFields.every((key) => {
+      const field = Object.getOwnPropertyDescriptor(state.auth, key);
+      return Object.hasOwn(state.snapshot, key) ? field && "value" in field && field.value === state.snapshot[key] : field === void 0;
+    });
+    if (state?.status !== "authenticated" || state.owner !== owner || state.res !== res || !intact) {
+      await rejectGuard(req, res, next);
+      return;
+    }
+    if (bound && !state.snapshot.deviceBinding) {
+      const error = new OidcVaultHttpError(
+        401,
+        "OIDC_VAULT_DEVICE_BINDING_REQUIRED",
+        "A device-bound login is required."
+      );
+      state.status = "failed";
+      delete req.auth;
+      const response = prepareError(error);
+      await notifyMiddlewareError(onError, { error, req, res });
+      delete req.auth;
+      if (res.headersSent) next(error);
+      else sendError(res, response);
+      return;
+    }
+    if (!res.headersSent) res.setHeader("Cache-Control", "no-store");
+    next();
+  };
+  const authenticate = async (req, res, next) => {
+    if (evidence.has(req)) {
+      const state2 = evidence.get(req);
+      state2.status = "failed";
+      delete req.auth;
+      const error = reentryError();
+      const response = prepareError(error);
+      await notifyMiddlewareError(onError, { error, req, res });
+      delete req.auth;
+      if (res.headersSent) next(error);
+      else sendError(res, response);
+      return;
+    }
+    const state = { owner, res, status: "pending" };
+    const diagnostic = createDiagnostic("api");
+    evidence.set(req, state);
     let token;
     let scheme;
     let nonceResponse;
+    let stage = "credential";
     const authenticatedRequest = req;
     delete authenticatedRequest.auth;
     if (!res.headersSent) res.setHeader("Cache-Control", "no-store");
-    const prepareError = (error, hookFailure = false) => {
-      const response = nonceResponse ?? (error instanceof OidcVaultHttpError ? toDpopReplayErrorResponse(error, algorithms) : {
-        status: hookFailure ? 500 : 401,
-        body: hookFailure ? { code: "OIDC_VAULT_AUTH_CONTEXT_FAILED", message: "Auth context hook failed." } : { code: "OIDC_VAULT_INVALID_ACCESS_TOKEN", message: "Access token validation failed." },
-        headers: { "Cache-Control": "no-store" }
-      });
-      const headers = { ...response.headers };
-      if (response.status === 401 && headers["WWW-Authenticate"] === void 0) {
-        const code = response.body.code;
-        const challenge2 = code === "OIDC_VAULT_DPOP_REQUIRED" || code === "OIDC_VAULT_INVALID_DPOP_PROOF" ? proofChallenge : !policy ? "Bearer" : code === "OIDC_VAULT_MISSING_ACCESS_TOKEN" ? policy.mode === "required" ? dpopChallenge() : `Bearer, ${dpopChallenge()}` : scheme === "DPoP" || !scheme && policy.mode === "required" ? dpopChallenge("invalid_token") : 'Bearer error="invalid_token"';
-        headers["WWW-Authenticate"] = challenge2;
-      }
-      return Object.freeze({
-        status: response.status,
-        body: Object.freeze({ ...response.body }),
-        headers: Object.freeze(headers)
-      });
-    };
-    const sendError = (response) => {
-      res.removeHeader("WWW-Authenticate");
-      res.removeHeader("DPoP-Nonce");
-      for (const [name, value] of Object.entries(response.headers)) res.setHeader(name, value);
-      res.status(response.status).json(response.body);
+    const stillPending = () => {
+      if (state.status === "pending") return true;
+      delete authenticatedRequest.auth;
+      return false;
     };
     try {
+      const authorization = readDpopRawHeader(req, "authorization");
+      const proofHeader = readDpopRawHeader(req, "dpop");
+      if (authentication === "optional" && authorization.count === 0 && proofHeader.count === 0) {
+        diagnostic.emit("presentation", "ignored", policy ? "proof-absent" : "policy-disabled");
+        state.status = "missing";
+        clearChallenge(res);
+        next();
+        return;
+      }
       let result;
       let confirmation;
       let deviceBinding;
       if (!policy) {
+        if (authorization.count > 1 || authorization.count === 1 && !authorization.value?.trim())
+          throw new OidcVaultHttpError(
+            401,
+            "OIDC_VAULT_INVALID_AUTHORIZATION_HEADER",
+            "Authorization header must use the Bearer scheme."
+          );
         token = extractBearerToken(req.get("authorization"));
         scheme = "Bearer";
+        stage = "validator";
         result = await validate(token);
+        if (!stillPending()) return;
         delete authenticatedRequest.auth;
+        stage = "result";
         const reported = result?.confirmation;
         confirmation = reported === void 0 ? void 0 : snapshotAccessTokenConfirmation(reported);
         result = mappedFields(result);
+        diagnostic.associate(diagnosticCorrelation("verified-token", result.subject, result.sessionId));
         delete authenticatedRequest.auth;
+        stage = "proof";
         if (confirmation)
           throw new OidcVaultHttpError(401, "OIDC_VAULT_DPOP_REQUIRED", "DPoP authentication is required.");
+        diagnostic.emit("presentation", "ignored", "policy-disabled");
       } else {
-        const authorization = readDpopRawHeader(req, "authorization");
         scheme = schemeOf(authorization.value);
-        if (authorization.count === 0 || authorization.count === 1 && !authorization.value?.trim()) {
+        if (authorization.count === 0) {
           throw new OidcVaultHttpError(401, "OIDC_VAULT_MISSING_ACCESS_TOKEN", "Missing access token.");
         }
         const credential = authorization.value?.trim().split(/\s+/);
@@ -2590,13 +3100,17 @@ function createOidcVaultAccessTokenMiddleware(options) {
           );
         }
         token = credential[1];
-        const proofHeader = readDpopRawHeader(req, "dpop");
         const { method, originalUrl } = req;
+        stage = "validator";
         result = await validateWithRequest(Object.freeze({ token, scheme, req }));
+        if (!stillPending()) return;
         delete authenticatedRequest.auth;
+        stage = "result";
         confirmation = snapshotAccessTokenConfirmation(result?.confirmation);
         result = mappedFields(result);
+        diagnostic.associate(diagnosticCorrelation("verified-token", result.subject, result.sessionId));
         delete authenticatedRequest.auth;
+        stage = "proof";
         if (confirmation && scheme !== "DPoP")
           throw new OidcVaultHttpError(401, "OIDC_VAULT_DPOP_REQUIRED", "DPoP authentication is required.");
         if (!confirmation && scheme === "DPoP")
@@ -2604,7 +3118,7 @@ function createOidcVaultAccessTokenMiddleware(options) {
         if (!confirmation && policy.mode === "required") {
           throw new OidcVaultHttpError(401, "OIDC_VAULT_DEVICE_BINDING_REQUIRED", "A device-bound login is required.");
         }
-        const proof = extractDpopProof(proofHeader);
+        const proof = extractDpopProof(proofHeader, diagnostic);
         if (!proof && confirmation)
           throw new OidcVaultHttpError(401, "OIDC_VAULT_DPOP_REQUIRED", "DPoP authentication is required.");
         if (proof) {
@@ -2615,15 +3129,18 @@ function createOidcVaultAccessTokenMiddleware(options) {
               targetUrl: () => targetFor(originalUrl),
               proofOptions: policy,
               accessToken: token,
-              expectedJkt: confirmation?.jkt
-            })
+              expectedJkt: confirmation?.jkt,
+              diagnostic
+            }),
+            diagnostic
           );
+          if (!stillPending()) return;
           if (admission.type === "nonce-challenge") {
             nonceResponse = toDpopNonceChallengeResponse(admission, "api", policy.algorithms);
             throw new OidcVaultHttpError(401, "OIDC_VAULT_USE_DPOP_NONCE", "A fresh DPoP nonce is required.");
           }
           if (confirmation) deviceBinding = admission.binding;
-        }
+        } else diagnostic.emit("presentation", "ignored", "proof-absent");
       }
       const authenticatedToken = token;
       const auth = {
@@ -2647,9 +3164,12 @@ function createOidcVaultAccessTokenMiddleware(options) {
       authenticatedRequest.auth = auth;
       try {
         await onAuthContext?.({ req: authenticatedRequest, res, auth });
+        if (!stillPending()) return;
         authenticatedRequest.auth = restoreAuth();
       } catch (hookError) {
-        const response = prepareError(hookError, true);
+        if (!stillPending()) return;
+        state.status = "failed";
+        const response = prepareError(hookError, scheme, void 0, true);
         delete authenticatedRequest.auth;
         let errorAuth;
         try {
@@ -2668,13 +3188,25 @@ function createOidcVaultAccessTokenMiddleware(options) {
           next(hookError);
           return;
         }
-        sendError(response);
+        sendError(res, response);
         return;
       }
+      state.auth = authenticatedRequest.auth;
+      state.snapshot = { ...authenticatedRequest.auth };
+      state.status = "authenticated";
       if (!res.headersSent) res.setHeader("Cache-Control", "no-store");
       next();
     } catch (error) {
-      const response = prepareError(error);
+      if (!stillPending()) return;
+      diagnostic.emit(
+        "preflight",
+        "rejected",
+        stage === "proof" ? diagnosticPreflightReason(error instanceof OidcVaultHttpError ? error.code : void 0) : "credential-rejected"
+      );
+      const response = prepareError(error, scheme, nonceResponse);
+      const rejected = stage === "validator" ? isAccessTokenRejected(error) : (stage === "credential" || stage === "proof") && error instanceof OidcVaultHttpError && credentialRejectionCodes.has(error.code);
+      const anonymous = authentication === "optional" && invalidCredentials === "anonymous" && rejected && !nonceResponse;
+      state.status = anonymous ? "invalid" : nonceResponse ? "challenged" : "failed";
       delete authenticatedRequest.auth;
       await notifyMiddlewareError(onError, { error, req, res, ...token ? { token } : {} });
       delete authenticatedRequest.auth;
@@ -2682,9 +3214,139 @@ function createOidcVaultAccessTokenMiddleware(options) {
         next(error);
         return;
       }
-      sendError(response);
+      if (anonymous && state.status === "invalid") {
+        clearChallenge(res);
+        res.status(200);
+        next();
+      } else sendError(res, response);
     }
   };
+  return Object.freeze({ authenticate, requireAuth: guard(false), requireDeviceBinding: guard(true) });
+}
+
+// src/jwt-token-issuer.ts
+import { createPrivateKey, createSecretKey, KeyObject } from "crypto";
+import { types } from "util";
+import { SignJWT } from "jose";
+var ALGORITHMS = /* @__PURE__ */ new Set([
+  "HS256",
+  "HS384",
+  "HS512",
+  "RS256",
+  "RS384",
+  "RS512",
+  "PS256",
+  "PS384",
+  "PS512",
+  "ES256",
+  "ES384",
+  "ES512",
+  "EdDSA"
+]);
+var RESERVED = ["iss", "aud", "iat", "exp", "sub", "cnf"];
+var CURVES = { ES256: "prime256v1", ES384: "secp384r1", ES512: "secp521r1" };
+var requireString = (value, name) => {
+  if (typeof value !== "string" || value.trim().length === 0) throw new TypeError(`${name} must be a nonblank string.`);
+  return value;
+};
+var signingKey = (configured, algorithm) => {
+  const symmetric = algorithm.startsWith("HS");
+  let key;
+  let cryptoKey;
+  if (configured instanceof Uint8Array) {
+    key = createSecretKey(Uint8Array.from(configured));
+  } else if (configured instanceof KeyObject) {
+    key = configured;
+  } else if (types.isCryptoKey(configured)) {
+    cryptoKey = configured;
+    const expectedName = symmetric ? "HMAC" : algorithm.startsWith("RS") ? "RSASSA-PKCS1-v1_5" : algorithm.startsWith("PS") ? "RSA-PSS" : algorithm.startsWith("ES") ? "ECDSA" : "Ed25519";
+    const parameters = configured.algorithm;
+    if (!configured.usages.includes("sign") || parameters.name !== expectedName || (symmetric || algorithm.startsWith("RS") || algorithm.startsWith("PS")) && parameters.hash?.name !== `SHA-${algorithm.slice(2)}`)
+      throw new TypeError("JWT signing CryptoKey algorithm/hash/usages must match the signing algorithm.");
+    key = KeyObject.from(configured);
+  } else {
+    if (!isRecord(configured)) throw new TypeError("JWT signing key must be a JOSE key.");
+    const jwk = { ...configured, ...configured.key_ops ? { key_ops: [...configured.key_ops] } : {} };
+    if (jwk.alg !== void 0 && jwk.alg !== algorithm || jwk.use !== void 0 && jwk.use !== "sig" || jwk.key_ops !== void 0 && (!Array.isArray(jwk.key_ops) || !jwk.key_ops.includes("sign")))
+      throw new TypeError("JWT signing JWK alg/use/key_ops must permit the signing algorithm.");
+    if (jwk.kty === "oct") {
+      if (typeof jwk.k !== "string" || !/^[A-Za-z0-9_-]+$/.test(jwk.k) || Buffer.from(jwk.k, "base64url").toString("base64url") !== jwk.k)
+        throw new TypeError("JWT signing JWK k must be canonical base64url secret bytes.");
+      key = createSecretKey(Buffer.from(jwk.k, "base64url"));
+    } else {
+      key = createPrivateKey({ key: jwk, format: "jwk" });
+    }
+  }
+  const bits = Number(algorithm.slice(2));
+  const curve = CURVES[algorithm];
+  const compatible = symmetric ? key.type === "secret" && key.symmetricKeySize * 8 >= bits : key.type === "private" && (curve ? key.asymmetricKeyType === "ec" && key.asymmetricKeyDetails?.namedCurve === curve : algorithm === "EdDSA" ? key.asymmetricKeyType === "ed25519" : key.asymmetricKeyType === "rsa" && (key.asymmetricKeyDetails?.modulusLength ?? 0) >= 2048);
+  if (!compatible) throw new TypeError("JWT signing key type/size/curve must match the signing algorithm.");
+  return cryptoKey ?? key;
+};
+var tokenTimes = (now, lifetimeSeconds) => {
+  const milliseconds = now();
+  const lifetimeMs = lifetimeSeconds * 1e3;
+  const iat = Math.floor(milliseconds / 1e3);
+  const exp = iat + lifetimeSeconds;
+  if (!Number.isSafeInteger(milliseconds) || milliseconds < 0 || !Number.isSafeInteger(lifetimeMs) || !Number.isSafeInteger(milliseconds + lifetimeMs) || !Number.isSafeInteger(exp) || !Number.isSafeInteger(exp * 1e3))
+    throw new TypeError("JWT clock/lifetime must produce safe nonnegative integer milliseconds and expiry.");
+  return { iat, exp };
+};
+function assertApplicationClaims(claims) {
+  if (!isRecord(claims) || Array.isArray(claims)) throw new TypeError("JWT mapClaims must return a claims object.");
+  for (const field of RESERVED) {
+    if (field in claims) throw new TypeError(`JWT mapClaims must not supply reserved claim ${field}.`);
+  }
+}
+function createOidcVaultJwtAccessTokenIssuer(options) {
+  const {
+    algorithm,
+    issuer: configuredIssuer,
+    audience: configuredAudience,
+    lifetimeSeconds = 300,
+    now = Date.now,
+    mapSubject,
+    mapClaims
+  } = options;
+  if (!ALGORITHMS.has(algorithm)) throw new TypeError("JWT signing algorithm is unsupported.");
+  const issuer = requireString(configuredIssuer, "JWT issuer");
+  const audience = Array.isArray(configuredAudience) ? [...configuredAudience] : configuredAudience;
+  if (Array.isArray(audience)) {
+    if (audience.length === 0) throw new TypeError("JWT audience must not be empty.");
+    for (const value of audience) requireString(value, "JWT audience");
+  } else requireString(audience, "JWT audience");
+  if (!Number.isSafeInteger(lifetimeSeconds) || lifetimeSeconds < 0)
+    throw new TypeError("JWT lifetimeSeconds must be a nonnegative safe integer.");
+  if (typeof now !== "function" || mapSubject !== void 0 && typeof mapSubject !== "function" || mapClaims !== void 0 && typeof mapClaims !== "function")
+    throw new TypeError("JWT clock and mappers must be functions.");
+  const key = signingKey(options.key, algorithm);
+  tokenTimes(now, lifetimeSeconds);
+  return Object.freeze({
+    async issue(input) {
+      const { deviceBinding, session } = input;
+      const { subject: defaultSubject, scope } = session;
+      if (scope !== void 0 && typeof scope !== "string") throw new TypeError("JWT session scope must be a string.");
+      if (deviceBinding !== void 0 && deviceBinding.type !== "dpop")
+        throw new TypeError("JWT deviceBinding must be verified DPoP context.");
+      const cnf = deviceBinding === void 0 ? void 0 : snapshotJkt({ jkt: deviceBinding.jkt }, (message) => new TypeError(message));
+      const subject = requireString(mapSubject ? await mapSubject(input) : defaultSubject, "JWT subject");
+      const mapped = mapClaims ? await mapClaims(input) : {};
+      assertApplicationClaims(mapped);
+      const claims = JSON.parse(JSON.stringify({ ...scope === void 0 ? {} : { scope }, ...mapped }));
+      assertApplicationClaims(claims);
+      const { iat, exp } = tokenTimes(now, lifetimeSeconds);
+      const accessToken = await new SignJWT({
+        ...claims,
+        iss: issuer,
+        aud: audience,
+        sub: subject,
+        iat,
+        exp,
+        ...cnf === void 0 ? {} : { cnf }
+      }).setProtectedHeader({ alg: algorithm, typ: "JWT" }).sign(key);
+      return { accessToken, expiresIn: lifetimeSeconds, tokenType: cnf === void 0 ? "Bearer" : "DPoP" };
+    }
+  });
 }
 
 // src/index.ts
@@ -2699,24 +3361,30 @@ var CREDENTIAL_RESPONSE_CACHE_CONTROL = "no-store";
 var applyCredentialResponseCachePolicy = (res) => {
   res.setHeader("Cache-Control", CREDENTIAL_RESPONSE_CACHE_CONTROL);
 };
-var createOpaqueId = (prefix) => `${prefix}_${randomBytes3(16).toString("base64url")}`;
-var createPkceVerifier = () => randomBytes3(32).toString("base64url");
-var createPkceChallenge = (verifier) => createHash6("sha256").update(verifier).digest("base64url");
+var createOpaqueId = (prefix) => `${prefix}_${randomBytes4(16).toString("base64url")}`;
+var createPkceVerifier = () => randomBytes4(32).toString("base64url");
+var createPkceChallenge = (verifier) => createHash8("sha256").update(verifier).digest("base64url");
 var getCallbackUri = (backendOrigin, basePath) => `${backendOrigin}${basePath}${OIDC_VAULT_ROUTE_PATHS.callback}`;
 var validateOidcVaultOptions = (options) => {
   const {
     deviceBinding: configuredDeviceBinding,
     fingerprintRecognition: configuredFingerprintRecognition,
     transactionCookie: configuredTransactionCookie,
+    logoutNavigation: configuredLogoutNavigation,
     ...otherOptions
   } = options;
   const cookie = otherOptions.cookie ? { ...otherOptions.cookie } : void 0;
   const cookieOptions = { ...otherOptions, cookie };
-  validateLifetimeOptions(options, getNow(options));
+  const now = getNow(options);
+  validateLifetimeOptions(options, now);
   const deviceBinding = resolveDeviceBindingOptions(configuredDeviceBinding);
   const fingerprintRecognition = resolveFingerprintRecognitionOptions(configuredFingerprintRecognition);
   const backendOrigin = deviceBinding === void 0 ? resolveBackendOrigin(options) : resolveDeviceBindingOrigin(options.backendOrigin);
-  if (deviceBinding !== void 0) assertDeviceBindingStoreCapabilities(options.storeProvider);
+  if (deviceBinding !== void 0)
+    assertDeviceBindingStoreCapabilities(
+      options.storeProvider,
+      configuredLogoutNavigation === void 0 ? "deviceBinding" : "logoutNavigation"
+    );
   if (fingerprintRecognition !== void 0)
     assertDeviceBindingStoreCapabilities(options.storeProvider, "fingerprintRecognition");
   const frontendRedirectUri = resolveFrontendRedirectUri(options);
@@ -2732,6 +3400,16 @@ var validateOidcVaultOptions = (options) => {
     backendOrigin
   );
   const config = resolveOidcVaultConfig(options.config ? { ...options.config } : void 0);
+  const logoutNavigation = resolveLogoutNavigationOptions(configuredLogoutNavigation, {
+    backendOrigin,
+    basePath: normalizeOidcVaultBasePath(otherOptions.basePath),
+    config,
+    frontendRedirectUri,
+    postLogoutRedirectUri: otherOptions.postLogoutRedirectUri,
+    deviceBindingConfigured: deviceBinding !== void 0,
+    store: otherOptions.storeProvider,
+    now
+  });
   const configuredTrustedOrigins = resolveTrustedOrigins(options);
   if (usesCrossSiteCookieTransport(cookieOptions) && configuredTrustedOrigins.size === 0) {
     throw new Error("trustedOrigins is required when using cross-site cookie transport.");
@@ -2743,6 +3421,8 @@ var validateOidcVaultOptions = (options) => {
     deviceBinding,
     fingerprintRecognition,
     transactionCookie,
+    logoutNavigation,
+    ...logoutNavigation === void 0 ? {} : { postLogoutRedirectUri: logoutNavigation.postLogoutRedirectUri },
     ...frontendRedirectUri !== void 0 ? { frontendRedirectUri } : {},
     ...options.trustedOrigins ? { trustedOrigins: [...options.trustedOrigins] } : {},
     ...cookie === void 0 ? {} : { cookie },
@@ -2890,10 +3570,18 @@ async function handleRouteError(route, req, res, next, options, error) {
   sendVaultRoutePolicyResponse(res, response);
 }
 function createAsyncHandler(route, options, handler) {
+  const createDiagnostic = createDpopDiagnosticFactory(options.onDpopDiagnostic);
+  const notify = createDiagnosticDispatcher(options.onTokenOutcome);
   return async (req, res, next) => {
+    const diagnostic = req.method === "POST" && route !== "callback" && route !== "backchannel-logout" ? createDiagnostic(route) : void 0;
     try {
-      await handler(req, res, next);
+      await handler(req, res, next, diagnostic, notify);
     } catch (error) {
+      diagnostic?.emit(
+        "preflight",
+        "rejected",
+        diagnosticPreflightReason(error instanceof OidcVaultHttpError ? error.code : void 0)
+      );
       await handleRouteError(route, req, res, next, options, error);
     }
   };
@@ -2939,8 +3627,8 @@ var createLoginHandler = (options, config, backendOrigin, basePath) => createAsy
   });
   res.redirect(302, authorizationUrl);
 });
-var createLoginInitiationHandler = (options, config, trustedOrigins, backendOrigin, basePath, proofVerifier) => createAsyncHandler("login", options, async (req, res) => {
-  const capturedProof = captureVaultRouteProof(req);
+var createLoginInitiationHandler = (options, config, trustedOrigins, backendOrigin, basePath, proofVerifier) => createAsyncHandler("login", options, async (req, res, _next, diagnostic) => {
+  const capturedProof = captureVaultRouteProof(req, diagnostic);
   const fingerprintRecognition = captureFingerprintRecognition(req, options.fingerprintRecognition);
   assertLoginInitiationRequest(req, options, trustedOrigins);
   const body = getBody(req);
@@ -2949,6 +3637,7 @@ var createLoginInitiationHandler = (options, config, trustedOrigins, backendOrig
   }
   const returnTo = resolveLoginReturnTo(body.returnTo, options);
   if (proofVerifier === void 0 && capturedProof.header.count !== 0) {
+    diagnostic?.emit("presentation", "rejected", "policy-disabled");
     throw new OidcVaultHttpError(
       401,
       "OIDC_VAULT_INVALID_DPOP_PROOF",
@@ -2957,6 +3646,7 @@ var createLoginInitiationHandler = (options, config, trustedOrigins, backendOrig
     );
   }
   const verifiedBinding = await proofVerifier?.initiate(capturedProof);
+  if (proofVerifier === void 0) diagnostic?.emit("presentation", "ignored", "policy-disabled");
   const binding = snapshotDpopBinding(verifiedBinding);
   const metadata = await resolveProviderMetadata(config, options);
   await callHook("login", options.hooks?.onLoginStart, req, res, void 0, { provider: { ...metadata } });
@@ -3174,8 +3864,8 @@ var copySessionApplicationFields = (session) => {
   }
   return result;
 };
-var createExchangeHandler = (options, config, trustedOrigins, proofVerifier) => createAsyncHandler("exchange", options, async (req, res) => {
-  const capturedProof = proofVerifier === void 0 ? void 0 : captureVaultRouteProof(req);
+var createExchangeHandler = (options, config, trustedOrigins, proofVerifier) => createAsyncHandler("exchange", options, async (req, res, _next, diagnostic, notify) => {
+  const capturedProof = proofVerifier === void 0 ? void 0 : captureVaultRouteProof(req, diagnostic);
   const capturedRecognition = captureFingerprintRecognition(req, options.fingerprintRecognition);
   const assertExchangeOrigin = captureTrustedOriginGuard(req, options, trustedOrigins, "exchange");
   const cookieHeader = req.headers.cookie;
@@ -3187,14 +3877,24 @@ var createExchangeHandler = (options, config, trustedOrigins, proofVerifier) =>
     throw new TypeError("Device-bound exchange requires guarded store reads and atomic consumption.");
   }
   const rawCode = canPreflight ? await store.getExchangeCode(code) : await store.consumeExchangeCode(code);
-  if (!rawCode) throw invalidExchangeCode();
+  if (!rawCode) {
+    diagnostic?.emit("preflight", "rejected", "session-unavailable");
+    throw invalidExchangeCode();
+  }
   const record = snapshotVaultExchangeCode(rawCode, code, getNow(options));
+  diagnostic?.associate(diagnosticCorrelation("candidate-session", void 0, record.sessionId));
   const guarded = record.browserBindingHash !== void 0;
   if (guarded) assertExchangeOrigin();
   assertDeviceBindingPolicy(options.deviceBinding, record.deviceBinding);
   const rawSession = await store.getSession(record.sessionId);
-  if (!rawSession) throw invalidVaultSession();
+  if (!rawSession) {
+    diagnostic?.emit("preflight", "rejected", "session-unavailable");
+    throw invalidVaultSession();
+  }
   const session = snapshotVaultSession(rawSession, record.sessionId, getNow(options));
+  diagnostic?.associate(
+    diagnosticCorrelation("candidate-session", session.subject, session.logicalSessionId ?? session.sessionId)
+  );
   assertDeviceBindingPolicy(options.deviceBinding, session.deviceBinding);
   assertVaultExchangeSessionBinding(record, session);
   const protectedExchange = proofVerifier !== void 0 || options.fingerprintRecognition !== void 0 || guarded;
@@ -3206,6 +3906,7 @@ var createExchangeHandler = (options, config, trustedOrigins, proofVerifier) =>
   const recognition = options.fingerprintRecognition === void 0 ? void 0 : snapshotFingerprintRecognition(session.metadata);
   assertFingerprintRecognition(options.fingerprintRecognition, recognition, capturedRecognition);
   const verifiedBinding = proofVerifier === void 0 ? void 0 : await proofVerifier.verify(capturedProof, session.deviceBinding);
+  if (proofVerifier === void 0) diagnostic?.emit("presentation", "ignored", "policy-disabled");
   if (canPreflight) {
     const consumed = protectedExchange ? await store.consumeExchangeCodeIfMatches({
       code,
@@ -3226,34 +3927,45 @@ var createExchangeHandler = (options, config, trustedOrigins, proofVerifier) =>
   }
   assertVaultSessionIdentity(session, config);
   try {
-    const issuedToken = await withIssuedToken(req, res, options, session, verifiedBinding);
+    const issuedToken = await withIssuedToken(req, res, options, session, "exchange", verifiedBinding);
     if (usesCookieTransport(options)) setSessionCookie(res, options, session.sessionId);
     if (cookieSecret !== void 0) clearTransactionCookie(res, options.transactionCookie);
     applyCredentialResponseCachePolicy(res);
-    res.status(200).json(createExchangeResponse(options, session, issuedToken));
+    const response = createExchangeResponse(options, session, issuedToken);
+    notifyTokenOutcomes("exchange", session, issuedToken, notify, diagnostic);
+    res.status(200).json(response);
   } catch (error) {
     if (cookieSecret !== void 0) clearTransactionCookie(res, options.transactionCookie);
     throw error;
   }
 });
-var createRefreshHandler = (options, config, trustedOrigins, proofVerifier) => createAsyncHandler("refresh", options, async (req, res) => {
+var createRefreshHandler = (options, config, trustedOrigins, proofVerifier) => createAsyncHandler("refresh", options, async (req, res, _next, diagnostic, notify) => {
   const capturedRecognition = captureFingerprintRecognition(req, options.fingerprintRecognition);
   assertTrustedOrigin(req, options, trustedOrigins, "refresh");
-  const capturedProof = proofVerifier === void 0 ? void 0 : captureVaultRouteProof(req);
+  const capturedProof = proofVerifier === void 0 ? void 0 : captureVaultRouteProof(req, diagnostic);
   const sessionId = getSessionIdFromRequest(req, options, "refresh");
   const currentRecord = await options.storeProvider.getSession(sessionId);
   if (!currentRecord) {
+    diagnostic?.emit("preflight", "rejected", "session-unavailable");
     if (usesCookieTransport(options)) {
       clearSessionCookie(res, options);
     }
     throw new OidcVaultHttpError(401, "OIDC_VAULT_INVALID_SESSION", "Session is missing or expired.");
   }
   const currentSession = snapshotVaultSession(currentRecord, sessionId, getNow(options));
+  diagnostic?.associate(
+    diagnosticCorrelation(
+      "candidate-session",
+      currentSession.subject,
+      currentSession.logicalSessionId ?? currentSession.sessionId
+    )
+  );
   assertVaultSessionIdentity(currentSession, config);
   assertDeviceBindingPolicy(options.deviceBinding, currentSession.deviceBinding);
   const recognition = options.fingerprintRecognition === void 0 ? void 0 : snapshotFingerprintRecognition(currentSession.metadata);
   assertFingerprintRecognition(options.fingerprintRecognition, recognition, capturedRecognition);
   const verifiedBinding = proofVerifier === void 0 ? void 0 : await proofVerifier.verify(capturedProof, currentSession.deviceBinding);
+  if (proofVerifier === void 0) diagnostic?.emit("presentation", "ignored", "policy-disabled");
   const metadata = await resolveProviderMetadata(config, options);
   if (proofVerifier !== void 0 || options.fingerprintRecognition !== void 0) {
     const latest = await options.storeProvider.getSession(sessionId);
@@ -3327,7 +4039,7 @@ var createRefreshHandler = (options, config, trustedOrigins, proofVerifier) => c
     throw error;
   }
   const rotatedSession = expectedSession;
-  const issuedToken = await withIssuedToken(req, res, options, rotatedSession, verifiedBinding);
+  const issuedToken = await withIssuedToken(req, res, options, rotatedSession, "refresh", verifiedBinding);
   await callPostCommitHook(
     "refresh",
     options,
@@ -3344,14 +4056,21 @@ var createRefreshHandler = (options, config, trustedOrigins, proofVerifier) => c
   }
   const response = createExchangeResponse(options, rotatedSession, issuedToken);
   applyCredentialResponseCachePolicy(res);
+  notifyTokenOutcomes("refresh", rotatedSession, issuedToken, notify, diagnostic);
   res.status(200).json(response);
 });
-var createLogoutHandler = (options, config, trustedOrigins, proofVerifier) => createAsyncHandler("logout", options, async (req, res) => {
-  assertTrustedOrigin(req, options, trustedOrigins, "logout");
-  const capturedProof = proofVerifier === void 0 ? void 0 : captureVaultRouteProof(req);
-  const body = getBody(req);
+var notifyLogoutError = async (options, req, res, error, session) => {
+  try {
+    await options.hooks?.onError?.({
+      ...createHookContext("logout", req, res, session === void 0 ? void 0 : copyVaultSession(session)),
+      error
+    });
+  } catch {
+  }
+};
+var performLogout = async (options, config, proofVerifier, req, res, diagnostic, redirect, navigation) => {
+  const capturedProof = proofVerifier === void 0 ? void 0 : captureVaultRouteProof(req, diagnostic);
   const sessionId = getSessionIdFromRequest(req, options, "logout");
-  const redirect = body.redirect === true;
   const store = options.storeProvider;
   const hasContext = typeof store.getSessionRevocationContext === "function";
   if (proofVerifier !== void 0 && !hasContext) {
@@ -3361,18 +4080,29 @@ var createLogoutHandler = (options, config, trustedOrigins, proofVerifier) => cr
   const context = rawContext ? snapshotVaultRevocationContext(rawContext) : void 0;
   const rawSession = await store.getSession(sessionId);
   const session = rawSession ? snapshotVaultSession(rawSession, sessionId, getNow(options)) : void 0;
+  if (session || context)
+    diagnostic?.associate(
+      diagnosticCorrelation(
+        "candidate-session",
+        session?.subject,
+        context?.logicalSessionId ?? session?.logicalSessionId ?? session?.sessionId
+      )
+    );
   const finishLocalLogout = () => {
+    diagnostic?.emit(
+      "presentation",
+      "ignored",
+      options.deviceBinding === void 0 ? "policy-disabled" : "target-absent"
+    );
     if (usesCookieTransport(options)) clearSessionCookie(res, options);
-    applyCredentialResponseCachePolicy(res);
-    res.status(200).json({ loggedOut: true });
+    return {};
   };
   if (hasContext && context === void 0) {
     if (session !== void 0) {
       assertDeviceBindingPolicy(options.deviceBinding, session.deviceBinding);
       throw invalidVaultSession();
     }
-    finishLocalLogout();
-    return;
+    return finishLocalLogout();
   }
   const authority = context ?? (session === void 0 ? void 0 : snapshotVaultRevocationContext({
     logicalSessionId: session.logicalSessionId ?? session.sessionId,
@@ -3381,11 +4111,12 @@ var createLogoutHandler = (options, config, trustedOrigins, proofVerifier) => cr
   }));
   if (authority === void 0) {
     await store.deleteSession(sessionId);
-    finishLocalLogout();
-    return;
+    return finishLocalLogout();
   }
   assertVaultSessionIdentity(authority, config);
   assertDeviceBindingPolicy(options.deviceBinding, authority.deviceBinding);
+  if (navigation !== void 0 && authority.deviceBinding === void 0)
+    throw new OidcVaultHttpError(401, "OIDC_VAULT_DEVICE_BINDING_REQUIRED", "A device-bound login is required.");
   if (session !== void 0)
     assertVaultRevocationContextMatches(
       snapshotVaultRevocationContext({
@@ -3396,54 +4127,95 @@ var createLogoutHandler = (options, config, trustedOrigins, proofVerifier) => cr
       authority
     );
   if (proofVerifier !== void 0) await proofVerifier.verify(capturedProof, authority.deviceBinding);
+  else diagnostic?.emit("presentation", "ignored", "policy-disabled");
   if (hasContext) {
     const latest = await store.getSessionRevocationContext(sessionId);
     if (!latest) {
-      finishLocalLogout();
-      return;
+      return finishLocalLogout();
     }
     assertVaultRevocationContextMatches(snapshotVaultRevocationContext(latest), authority);
   }
   if (session !== void 0)
     await callHook("logout", options.hooks?.onBeforeLogout, req, res, copyVaultSession(session));
   await store.deleteSessionsByLogicalSessionId({ logicalSessionId: authority.logicalSessionId });
-  if (usesCookieTransport(options)) {
-    clearSessionCookie(res, options);
+  try {
+    if (usesCookieTransport(options)) clearSessionCookie(res, options);
+    if (session === void 0 || !redirect && navigation === void 0) return {};
+    if (navigation !== void 0 && !isString(session.idToken)) return {};
+    try {
+      const metadata = await resolveProviderMetadata(config, options);
+      if (!metadata.endSessionEndpoint) return {};
+      const endpoint = navigation === void 0 ? metadata.endSessionEndpoint : validateUpstreamLogoutUrl(metadata.endSessionEndpoint);
+      const builtUrl = buildLogoutUrl(endpoint, session.idToken, options.postLogoutRedirectUri);
+      if (navigation === void 0) return { upstreamLogoutUrl: builtUrl };
+      const upstreamLogoutUrl = validateUpstreamLogoutUrl(builtUrl);
+      const navigationUrl = await persistLogoutNavigation(navigation, store, upstreamLogoutUrl, getNow(options));
+      return { navigationUrl };
+    } catch (error) {
+      await notifyLogoutError(options, req, res, error, session);
+      return {};
+    }
+  } finally {
+    if (session !== void 0)
+      await callPostCommitHook("logout", options, options.hooks?.onLogout, req, res, copyVaultSession(session));
   }
-  if (session === void 0) {
-    applyCredentialResponseCachePolicy(res);
-    res.status(200).json({ loggedOut: true });
+};
+var createLogoutHandler = (options, config, trustedOrigins, proofVerifier, navigation) => createAsyncHandler("logout", options, async (req, res, _next, diagnostic) => {
+  if (navigation === void 0) assertTrustedOrigin(req, options, trustedOrigins, "logout");
+  else {
+    assertLogoutNavigationRequest(req, options, trustedOrigins);
+    const body = req.body;
+    if (typeof body !== "object" || body === null || Array.isArray(body) || Object.keys(body).some((key) => key !== "sessionId") || Object.hasOwn(body, "sessionId") && typeof body.sessionId !== "string")
+      throw new OidcVaultHttpError(
+        400,
+        "OIDC_VAULT_INVALID_REQUEST_BODY",
+        "Logout navigation request body is invalid."
+      );
+  }
+  const redirect = navigation === void 0 && getBody(req).redirect === true;
+  const result = await performLogout(options, config, proofVerifier, req, res, diagnostic, redirect, navigation);
+  applyCredentialResponseCachePolicy(res);
+  if (navigation !== void 0) {
+    res.status(200).json({
+      loggedOut: true,
+      navigationUrl: result.navigationUrl ?? navigation.navigationUrl
+    });
     return;
   }
-  if (!redirect) {
-    await callPostCommitHook("logout", options, options.hooks?.onLogout, req, res, copyVaultSession(session));
-    applyCredentialResponseCachePolicy(res);
-    res.status(200).json({ loggedOut: true });
+  if (result.upstreamLogoutUrl) {
+    res.redirect(302, result.upstreamLogoutUrl);
     return;
   }
-  let upstreamLogoutUrl;
-  try {
-    const metadata = await resolveProviderMetadata(config, options);
-    upstreamLogoutUrl = metadata.endSessionEndpoint ? buildLogoutUrl(metadata.endSessionEndpoint, session.idToken, options.postLogoutRedirectUri) : void 0;
-  } catch (error) {
+  res.status(200).json({ loggedOut: true });
+});
+var assertLogoutNavigationRequest = (req, options, trustedOrigins) => {
+  captureTrustedOriginGuard(req, options, trustedOrigins, "logout", true)();
+  if (!req.is("application/json"))
+    throw new OidcVaultHttpError(
+      415,
+      "OIDC_VAULT_UNSUPPORTED_REQUEST_BODY_TYPE",
+      "Logout navigation requires a JSON request body."
+    );
+};
+var createLogoutNavigationGetHandler = (options) => async (req, res) => {
+  const policy = options.logoutNavigation;
+  let location = policy.fallbackRedirectUri;
+  const ticketHash = navigationTicketHash(req.originalUrl);
+  if (ticketHash !== void 0) {
     try {
-      await options.hooks?.onError?.({
-        ...createHookContext("logout", req, res, copyVaultSession(session)),
-        error
+      const record = await options.storeProvider.consumeLogoutNavigationTicket({
+        namespace: policy.namespace,
+        ticketHash
       });
-    } catch {
+      if (record !== null)
+        location = consumedLogoutDestination(record, policy.namespace, ticketHash, getNow(options));
+    } catch (error) {
+      await notifyLogoutError(options, req, res, error);
     }
   }
-  await callPostCommitHook("logout", options, options.hooks?.onLogout, req, res, copyVaultSession(session));
-  applyCredentialResponseCachePolicy(res);
-  if (redirect && upstreamLogoutUrl) {
-    res.redirect(302, upstreamLogoutUrl);
-    return;
-  }
-  res.status(200).json({
-    loggedOut: true
-  });
-});
+  res.status(302).setHeader("Location", location);
+  res.end();
+};
 var createBackchannelLogoutHandler = (options, config) => createAsyncHandler("backchannel-logout", options, async (req, res) => {
   const metadata = await resolveProviderMetadata(config, options);
   const logoutToken = getLogoutTokenFromRequest(req);
@@ -3505,6 +4277,10 @@ function registerRoutes(router, options, config, trustedOrigins, backendOrigin,
   router.post(OIDC_VAULT_ROUTE_PATHS.exchange, createExchangeHandler(options, config, trustedOrigins, proofVerifier));
   router.post(OIDC_VAULT_ROUTE_PATHS.refresh, createRefreshHandler(options, config, trustedOrigins, proofVerifier));
   router.post(OIDC_VAULT_ROUTE_PATHS.logout, createLogoutHandler(options, config, trustedOrigins, proofVerifier));
+  if (options.logoutNavigation !== void 0) {
+    const path = OIDC_VAULT_ROUTE_PATHS["logout-navigation"];
+    router.post(path, createLogoutHandler(options, config, trustedOrigins, proofVerifier, options.logoutNavigation));
+  }
   router.post(OIDC_VAULT_ROUTE_PATHS["backchannel-logout"], createBackchannelLogoutHandler(options, config));
 }
 function createOidcVaultMiddleware(options) {
@@ -3517,6 +4293,26 @@ function createOidcVaultMiddleware(options) {
     applyCredentialResponseCachePolicy(res);
     next();
   });
+  if (resolvedOptions.logoutNavigation !== void 0) {
+    const path = OIDC_VAULT_ROUTE_PATHS["logout-navigation"];
+    baseRouter.all(path, (_req, res, next) => {
+      res.setHeader("Referrer-Policy", "no-referrer");
+      next();
+    });
+    baseRouter.head(path, (_req, res) => {
+      res.setHeader("Allow", "GET, POST");
+      res.status(405).end();
+    });
+    baseRouter.get(path, createLogoutNavigationGetHandler(resolvedOptions));
+    baseRouter.post(
+      path,
+      createAsyncHandler("logout", resolvedOptions, async (req, _res, next) => {
+        assertLogoutNavigationRequest(req, resolvedOptions, trustedOrigins);
+        next();
+      })
+    );
+    baseRouter.post(path, express.json({ limit: requestBodyLimit, strict: false }));
+  }
   if (resolvedOptions.deviceBinding !== void 0 || resolvedOptions.fingerprintRecognition !== void 0) {
     baseRouter.post(
       OIDC_VAULT_ROUTE_PATHS.login,
@@ -3547,9 +4343,14 @@ export {
   DEFAULT_OIDC_VAULT_REQUEST_BODY_LIMIT,
   OIDC_VAULT_ROUTE_PATHS,
   OIDC_VAULT_URL_ENCODED_PARAMETER_LIMIT,
+  OidcVaultAuthDeniedError,
   OidcVaultDpopReplayCapacityError,
+  OidcVaultInvalidAccessTokenError,
+  OidcVaultLogoutNavigationCapacityError,
   OidcVaultStoreConflictError,
   createOidcVaultAccessTokenMiddleware,
+  createOidcVaultAuthenticator,
+  createOidcVaultJwtAccessTokenIssuer,
   createOidcVaultJwtAccessTokenValidator,
   createOidcVaultMiddleware,
   normalizeOidcVaultBasePath,