@web-ts-toolkit/oidc-vault-dpop-client 0.53.0 → 0.55.0

package/README.md

@@ -179,17 +179,80 @@ fresh proof. Web Locks coordinate tabs of one frontend origin, storage
 partition, and vault scope — they are not a backend refresh lease, so other
 frontends, devices, or processes can still race upstream refresh families.
 
+## Provider logout navigation
+
+With server `logoutNavigation` enabled, call **`logoutAndNavigate(): Promise<void>`**
+from a user action. It confirms local logout, clears old frontend auth and invokes
+the synchronous `navigate(url)` adapter (default `location.assign`) inside lifecycle
+authority. `logout()` remains local-only. No return-URL/prepare API is needed.
+
+```ts
+import {
+  createOidcVaultDpopSession,
+  type OidcVaultLogoutNavigationInput,
+  type OidcVaultLogoutNavigationResult,
+} from '@web-ts-toolkit/oidc-vault-dpop-client';
+
+const session = createOidcVaultDpopSession({
+  backendOrigin: 'https://api.example.com',
+  basePath: '/auth/oidc',
+  sessionTransport: 'body', // Or the matching cookie mount and 'cookie'.
+});
+export const signOutThroughProvider = (): Promise<void> => session.logoutAndNavigate();
+// Pure wire types are also bundled at the client root; no backend install needed.
+export type NavigationRequest = OidcVaultLogoutNavigationInput;
+export type NavigationResponse = OidcVaultLogoutNavigationResult;
+```
+
+The existing persistent key plus body handle or **active matching cookie metadata**
+suffices after reload, with an absent or expired memory JWT. It does not refresh,
+create a replacement key, send fingerprint/Authorization/`ath`, or put API tokens
+in query strings. POST uses the same finite HTTP bounds and nonce cache, including
+learned success nonces: at most one recognized challenge retry with a fresh proof/JTI.
+Body credentials are `omit` with `{ sessionId }`; cookie credentials are `include`
+with `{}` under the scope Web Lock. Strict server Origin/Referer checks apply in
+both transports; allow the frontend via `trustedOrigins` and expose `DPoP-Nonce` in CORS.
+
+The client accepts only the exact absolute pinned backend continuation path,
+bare or followed by one literal `?ticket=lnt_<43 canonical base64url characters>`.
+No upstream URL/hint enters initiation JSON. A confirmed `loggedOut: true` clears
+token, handle, pending login, nonces and peer adoption, and invalidates cookie
+metadata/notifies peers even if the URL is invalid; that case rejects with fixed
+nonterminal **`INVALID_LOGOUT_NAVIGATION_RESPONSE`** and never navigates. Unconfirmed,
+malformed, oversized, timed-out or lost responses leave the server commit uncertain,
+retain the existing failure policy and never automatically retry or navigate.
+Cleanup/adapter failure rejects after memory clear, without credential restoration.
+
+Concurrent clicks share the **same pending Promise** through FIFO, nonce retry,
+cleanup and one adapter invocation. An earlier refresh publishes rotation first;
+a later refresh cannot resurrect credentials. Refresh does not split that click
+batch. Later login/exchange/local logout/clear/resetKey/dispose immediately withdraws
+navigation intent, including a login still queued for the FIFO/lock. A started
+POST may finish old-state cleanup before that login, but rejects as superseded
+instead of navigating. No completed ticket URL is cached; another click after
+cleanup requires login. Cancellation cannot undo server commit or navigation
+already handed to the browser.
+
+The server revokes locally before optional provider work. Missing endpoints,
+discovery/ticket failures and missing/spent/expired tickets select its fixed
+configured fallback. Tickets default to 60 seconds (server range 1–120 seconds),
+are single-use, and retain only the final upstream hint URL server-side until
+consume/expiry/cleanup. Navigation/history/proxy logs and the IdP request still
+expose their respective URLs; avoid logging them. After upstream handoff, provider
+availability/termination/return is not guaranteed. Stateless JWTs remain valid
+until expiry unless the application adds revocation.
+
 ## Lifecycle concurrency and cleanup
 
 Use one session instance per tab and vault mount. In **both transports**,
-`login`, `exchange`, `refresh`, and `logout` run in invocation order. A logout
+`login`, `exchange`, `refresh`, `logout`, and `logoutAndNavigate` run in invocation order. A logout
 queued behind refresh uses the rotated handle/cookie. Cookie operations also
 hold the scope's Web Lock across their HTTP work and credential publication.
 Body queues belong to the instance; they do not coordinate other instances or
 copied tab handles.
 
 Concurrent `refresh()` callers receive the **same Promise** until a call to
-`login`, `exchange`, `logout`, `clear`, or `resetKey` starts a new batch. The first caller's
+`login`, `exchange`, `logout`, `logoutAndNavigate`, `clear`, or `resetKey` starts a new batch. The first caller's
 `rejectedToken` applies to that batch. A refresh invoked after a queued logout
 waits behind it instead of joining the earlier refresh. Read-only `getKey()`
 checks can run alongside the queue and one another; only their still-current
@@ -208,12 +271,13 @@ newer auth state is published. A new `login()` intent additionally supersedes
 older peer callbacks immediately, including while that login is waiting in the
 lifecycle queue or for the cookie Web Lock.
 
-| Method       | Effect                                                                                                                                                                                                                                                                                                                                                                  |
-| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `logout()`   | Ordered server logout, then frontend cleanup. Revokes vault refresh state.                                                                                                                                                                                                                                                                                              |
-| `clear()`    | Immediately drops this context's memory token, vault nonces, body handle and pending-login marker, and aborts its in-flight vault HTTP. Keeps the persistent key. In cookie mode, its Promise waits for the Web Lock, inactive-generation write and peer notification. It does not call the backend or remove the HttpOnly cookie.                                      |
-| `resetKey()` | Explicit local key recovery. Immediately invalidates the same local work/auth as `clear`, then atomically deletes **this scope's key and cookie-session metadata**. Cookie mode uses the shared Web Lock and notifies affected peers. Repeating on absent records is harmless. Creates no key and makes no backend request; await it, then invoke `login()` explicitly. |
-| `dispose()`  | Immediately closes this context, drops its memory token/vault nonces, aborts owned vault HTTP, settles peer waits, removes listeners/timers and closes its channel. Keeps the previously persisted key, handle, pending-login marker and committed cookie metadata so a replacement context can bootstrap normally. Later calls reject.                                 |
+| Method                | Effect                                                                                                                                                                                                                                                                                                                                                                  |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `logout()`            | Ordered server logout, then frontend cleanup. Revokes vault refresh state.                                                                                                                                                                                                                                                                                              |
+| `logoutAndNavigate()` | Ordered proof-authorized server logout, confirmed cleanup, then provider/fallback navigation; coalesced clicks and withdrawable navigation intent. Requires server opt-in.                                                                                                                                                                                              |
+| `clear()`             | Immediately drops this context's memory token, vault nonces, body handle and pending-login marker, and aborts its in-flight vault HTTP. Keeps the persistent key. In cookie mode, its Promise waits for the Web Lock, inactive-generation write and peer notification. It does not call the backend or remove the HttpOnly cookie.                                      |
+| `resetKey()`          | Explicit local key recovery. Immediately invalidates the same local work/auth as `clear`, then atomically deletes **this scope's key and cookie-session metadata**. Cookie mode uses the shared Web Lock and notifies affected peers. Repeating on absent records is harmless. Creates no key and makes no backend request; await it, then invoke `login()` explicitly. |
+| `dispose()`           | Immediately closes this context, drops its memory token/vault nonces, aborts owned vault HTTP, settles peer waits, removes listeners/timers and closes its channel. Keeps the previously persisted key, handle, pending-login marker and committed cookie metadata so a replacement context can bootstrap normally. Later calls reject.                                 |
 
 Clear/reset/dispose invalidate pending cookie-version and session-owned key
 transactions as well as memory publication. After clear or reset, unsolicited peer messages cannot restore this
@@ -247,7 +311,7 @@ partition/scope.
 
 ## HTTP bounds and cancellation
 
-All vault `login`/`exchange`/`refresh`/`logout` attempts use these session options:
+All vault `login`/`exchange`/`refresh`/`logout`/`logoutAndNavigate` attempts use these session options:
 
 | Option             | Default                     | Valid values / scope                                                                                                                 |
 | ------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
@@ -343,6 +407,9 @@ Backend options that must agree with this client (authoritative wire contract:
 - `deviceBinding.mode: 'required'` for bound flows, with a shared nonce secret
   when nonces are enabled (`nonce: { secret, lifetimeSeconds }`, ≥32 random
   bytes shared by instances of that protection space).
+- `logoutNavigation: { fallbackRedirectUri }` enables provider navigation logout;
+  configure/register `postLogoutRedirectUri` for provider return. Built-in stores
+  supply ticket capabilities; custom stores need both optional ticket methods.
 - The API's `replayNamespace` must equal the `replayNamespace` configured in
   `fetchWithDpop` `apis` entries.
 
@@ -576,11 +643,12 @@ error or automatically start login for a non-terminal failure.
 
 `credentials` is owned by the helpers; callers must not set it.
 
-| Operation            | Body transport                           | Cookie transport                                                   |
-| -------------------- | ---------------------------------------- | ------------------------------------------------------------------ |
-| `login` / `exchange` | `include` (temporary transaction cookie) | `include` (temporary transaction cookie)                           |
-| `refresh` / `logout` | `omit` + `{ sessionId }` JSON body       | `include` + `{}` JSON body (no `sessionId`)                        |
-| `fetchWithDpop` API  | `omit` default                           | `omit` default (`include` only for an explicitly cookie-using API) |
+| Operation                | Body transport                           | Cookie transport                                                   |
+| ------------------------ | ---------------------------------------- | ------------------------------------------------------------------ |
+| `login` / `exchange`     | `include` (temporary transaction cookie) | `include` (temporary transaction cookie)                           |
+| `refresh` / `logout`     | `omit` + `{ sessionId }` JSON body       | `include` + `{}` JSON body (no `sessionId`)                        |
+| `logoutAndNavigate` POST | `omit` + `{ sessionId }` JSON body       | `include` + `{}` JSON body (no `sessionId`)                        |
+| `fetchWithDpop` API      | `omit` default                           | `omit` default (`include` only for an explicitly cookie-using API) |
 
 Cookie JSON always omits `sessionId`. Every request uses `redirect: 'error'`
 and `cache: 'no-store'`. Vault POSTs present no access token; API calls send
@@ -768,7 +836,7 @@ singleton, and no client router — the callback is the same page reading
 ## API reference
 
 - `createOidcVaultDpopSession(options)` → `OidcVaultDpopSession`
-  (`login`/`exchange`/`refresh`/`logout`/`getAccessToken`/`getKey`/`clear`/`resetKey`/`dispose`).
+  (`login`/`exchange`/`refresh`/`logout`/`logoutAndNavigate`/`getAccessToken`/`getKey`/`clear`/`resetKey`/`dispose`).
   Options: `backendOrigin`, `basePath` (default `/auth/oidc`),
   `sessionTransport` (`'body'` default | `'cookie'`), optional `fingerprint`,
   `requestTimeoutMs` (default 15,000 ms), `maxResponseBytes` (default 1 MiB),
@@ -785,9 +853,17 @@ pathPrefix?, credentials? }`; longest normalized segment-prefix match wins.
   `DeviceFingerprintSignalSource`, `FingerprintJsAgent`. Wire DTOs stay
   single-sourced from the pure `@web-ts-toolkit/express-oidc-vault/wire` entry
   at build time; no backend import survives in client declarations/JavaScript.
+- Pure root DTOs: `OidcVaultLogoutNavigationInput`, `OidcVaultLogoutNavigationResult`.
 
 ## Upgrade notes
 
+Provider logout is additive: enable the paired server's `logoutNavigation` and
+replace custom logout proof/fetch/redirect handling with `session.logoutAndNavigate()`.
+Keep `logout()` for local-only behavior. Add `logoutAndNavigate` to typed session
+mocks. `navigate` now handles both login and logout URLs synchronously; do not
+defer its actual navigation beyond the call, where lifecycle authority no longer
+protects it. Existing persistent keys and the database schema are retained.
+
 | Area                         | Consumer action / delivered contract                                                                                                                                                                                                                                                                                                                                                                   |
 | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Node and types               | Use **Node >=22.12.0** for CJS `require(esm)`. Browser declarations now need only DOM/ES libs; remove compensating Express/Node ambient types if your app has no other use for them. Backend root type imports and `req.auth` remain available.                                                                                                                                                        |

package/index.d.mts

@@ -85,6 +85,37 @@ interface OidcVaultUserProfile {
     preferredUsername?: string;
     [key: string]: unknown;
 }
+/** Successful local logout; stateless application JWTs require separate revocation or expiry. */
+interface OidcVaultLogoutResult {
+    /**
+     * Successful logout commits revocation before upstream work and clears the
+     * session cookie under cookie transport. Built-in live handles and unexpired
+     * aliases authenticate the surviving lineage's provider/original binding;
+     * wrong identity, missing/wrong/stale/replayed proof, or disabled acceptance
+     * of a bound lineage fails without deleting or clearing. No currently live
+     * target is idempotent success without deletion or proof reservation. Aliases
+     * grant revocation only, not refresh authentication or upstream redirects.
+     * Old custom bearer stores without revocation context retain legacy alias
+     * deletion behavior. Stateless application access tokens are not invalidated.
+     * Local-only logout (`redirect` unset or `false`) never contacts the provider.
+     * Redirected logout (`redirect: true`)
+     * treats the upstream end-session redirect as best-effort: when provider
+     * discovery fails or no `endSessionEndpoint` is available, the route still
+     * returns this local success. Discovery errors reach `onError` without
+     * undoing revocation or skipping the live session's `onLogout` notification.
+     */
+    loggedOut: true;
+}
+/** JSON-only POST <basePath>/logout/navigation. Proof belongs in DPoP, with no access token or ath. */
+interface OidcVaultLogoutNavigationInput {
+    /** Required nonempty handle in body transport; ignored in cookie transport, which selects only the configured cookie. */
+    sessionId?: string;
+}
+/** Confirmed local logout, not an IdP delivery receipt. Never contains an upstream token-bearing URL. */
+interface OidcVaultLogoutNavigationResult extends OidcVaultLogoutResult {
+    /** Absolute pinned backend continuation URL, bare or with one opaque one-use ticket. Navigate at top level; do not fetch the provider redirect. */
+    navigationUrl: string;
+}
 /** Vault handle transport; independent of DPoP mode. Default: body. */
 type OidcVaultSessionTransport = 'body' | 'cookie';
 
@@ -157,8 +188,8 @@ interface OidcVaultDpopSessionOptions {
     maxResponseBytes?: number;
     /** Default global fetch. Injected responses must expose a standard streaming body. */
     fetch?: typeof globalThis.fetch;
-    /** Login redirect after authoritative initiation; default location.assign. */
-    navigate?: (authorizationUrl: string) => void;
+    /** Synchronous login/logout navigation inside lifecycle authority; default location.assign. */
+    navigate?: (url: string) => void;
     /** Epoch-millisecond clock; default Date.now. Credential deadline arithmetic must remain safe. */
     now?: () => number;
 }
@@ -181,6 +212,14 @@ interface OidcVaultDpopSession {
     }): Promise<DpopAccessToken>;
     /** FIFO: an earlier refresh publishes its rotated handle before logout uses it. Revokes server refresh state. */
     logout(): Promise<void>;
+    /**
+     * Proof-authorized local logout followed by top-level provider/fallback navigation.
+     * Requires server logoutNavigation opt-in and the existing key/handle or active
+     * cookie metadata, not a live access JWT. Concurrent clicks share one Promise.
+     * Later login/exchange/logout/clear/resetKey/dispose withdraw navigation intent.
+     * Invalid navigation URLs still clear confirmed logout state, then reject.
+     */
+    logoutAndNavigate(): Promise<void>;
     /** Memory snapshot only; may already be expired, including a valid expiresIn: 0 response. */
     getAccessToken(): DpopAccessToken | undefined;
     /**
@@ -367,4 +406,4 @@ declare class OidcVaultDpopClientError extends Error {
     constructor(code: string, message: string, requiresLogin?: boolean, status?: number);
 }
 
-export { type DeviceFingerprint, type DeviceFingerprintOptions, type DeviceFingerprintSignalSource, type DpopAccessToken, type DpopApi, type DpopFetchContext, type DpopFetchOptions, type DpopKey, type DpopKeyScope, DpopNonceCache, type DpopProofInput, type FingerprintJsAgent, OidcVaultDpopClientError, type OidcVaultDpopSession, type OidcVaultDpopSessionOptions, createDeviceFingerprint, createDpopProof, createOidcVaultDpopSession, fetchWithDpop, fingerprintJsSignalSource, getOrCreateDpopKey };
+export { type DeviceFingerprint, type DeviceFingerprintOptions, type DeviceFingerprintSignalSource, type DpopAccessToken, type DpopApi, type DpopFetchContext, type DpopFetchOptions, type DpopKey, type DpopKeyScope, DpopNonceCache, type DpopProofInput, type FingerprintJsAgent, OidcVaultDpopClientError, type OidcVaultDpopSession, type OidcVaultDpopSessionOptions, type OidcVaultLogoutNavigationInput, type OidcVaultLogoutNavigationResult, createDeviceFingerprint, createDpopProof, createOidcVaultDpopSession, fetchWithDpop, fingerprintJsSignalSource, getOrCreateDpopKey };

package/index.d.ts

@@ -85,6 +85,37 @@ interface OidcVaultUserProfile {
     preferredUsername?: string;
     [key: string]: unknown;
 }
+/** Successful local logout; stateless application JWTs require separate revocation or expiry. */
+interface OidcVaultLogoutResult {
+    /**
+     * Successful logout commits revocation before upstream work and clears the
+     * session cookie under cookie transport. Built-in live handles and unexpired
+     * aliases authenticate the surviving lineage's provider/original binding;
+     * wrong identity, missing/wrong/stale/replayed proof, or disabled acceptance
+     * of a bound lineage fails without deleting or clearing. No currently live
+     * target is idempotent success without deletion or proof reservation. Aliases
+     * grant revocation only, not refresh authentication or upstream redirects.
+     * Old custom bearer stores without revocation context retain legacy alias
+     * deletion behavior. Stateless application access tokens are not invalidated.
+     * Local-only logout (`redirect` unset or `false`) never contacts the provider.
+     * Redirected logout (`redirect: true`)
+     * treats the upstream end-session redirect as best-effort: when provider
+     * discovery fails or no `endSessionEndpoint` is available, the route still
+     * returns this local success. Discovery errors reach `onError` without
+     * undoing revocation or skipping the live session's `onLogout` notification.
+     */
+    loggedOut: true;
+}
+/** JSON-only POST <basePath>/logout/navigation. Proof belongs in DPoP, with no access token or ath. */
+interface OidcVaultLogoutNavigationInput {
+    /** Required nonempty handle in body transport; ignored in cookie transport, which selects only the configured cookie. */
+    sessionId?: string;
+}
+/** Confirmed local logout, not an IdP delivery receipt. Never contains an upstream token-bearing URL. */
+interface OidcVaultLogoutNavigationResult extends OidcVaultLogoutResult {
+    /** Absolute pinned backend continuation URL, bare or with one opaque one-use ticket. Navigate at top level; do not fetch the provider redirect. */
+    navigationUrl: string;
+}
 /** Vault handle transport; independent of DPoP mode. Default: body. */
 type OidcVaultSessionTransport = 'body' | 'cookie';
 
@@ -157,8 +188,8 @@ interface OidcVaultDpopSessionOptions {
     maxResponseBytes?: number;
     /** Default global fetch. Injected responses must expose a standard streaming body. */
     fetch?: typeof globalThis.fetch;
-    /** Login redirect after authoritative initiation; default location.assign. */
-    navigate?: (authorizationUrl: string) => void;
+    /** Synchronous login/logout navigation inside lifecycle authority; default location.assign. */
+    navigate?: (url: string) => void;
     /** Epoch-millisecond clock; default Date.now. Credential deadline arithmetic must remain safe. */
     now?: () => number;
 }
@@ -181,6 +212,14 @@ interface OidcVaultDpopSession {
     }): Promise<DpopAccessToken>;
     /** FIFO: an earlier refresh publishes its rotated handle before logout uses it. Revokes server refresh state. */
     logout(): Promise<void>;
+    /**
+     * Proof-authorized local logout followed by top-level provider/fallback navigation.
+     * Requires server logoutNavigation opt-in and the existing key/handle or active
+     * cookie metadata, not a live access JWT. Concurrent clicks share one Promise.
+     * Later login/exchange/logout/clear/resetKey/dispose withdraw navigation intent.
+     * Invalid navigation URLs still clear confirmed logout state, then reject.
+     */
+    logoutAndNavigate(): Promise<void>;
     /** Memory snapshot only; may already be expired, including a valid expiresIn: 0 response. */
     getAccessToken(): DpopAccessToken | undefined;
     /**
@@ -367,4 +406,4 @@ declare class OidcVaultDpopClientError extends Error {
     constructor(code: string, message: string, requiresLogin?: boolean, status?: number);
 }
 
-export { type DeviceFingerprint, type DeviceFingerprintOptions, type DeviceFingerprintSignalSource, type DpopAccessToken, type DpopApi, type DpopFetchContext, type DpopFetchOptions, type DpopKey, type DpopKeyScope, DpopNonceCache, type DpopProofInput, type FingerprintJsAgent, OidcVaultDpopClientError, type OidcVaultDpopSession, type OidcVaultDpopSessionOptions, createDeviceFingerprint, createDpopProof, createOidcVaultDpopSession, fetchWithDpop, fingerprintJsSignalSource, getOrCreateDpopKey };
+export { type DeviceFingerprint, type DeviceFingerprintOptions, type DeviceFingerprintSignalSource, type DpopAccessToken, type DpopApi, type DpopFetchContext, type DpopFetchOptions, type DpopKey, type DpopKeyScope, DpopNonceCache, type DpopProofInput, type FingerprintJsAgent, OidcVaultDpopClientError, type OidcVaultDpopSession, type OidcVaultDpopSessionOptions, type OidcVaultLogoutNavigationInput, type OidcVaultLogoutNavigationResult, createDeviceFingerprint, createDpopProof, createOidcVaultDpopSession, fetchWithDpop, fingerprintJsSignalSource, getOrCreateDpopKey };

package/index.js

@@ -690,11 +690,17 @@ var createOidcVaultDpopSession = (options) => {
   const cookieBindings = /* @__PURE__ */ new WeakMap();
   let refreshPromise;
   let resetPromise;
+  let navigationPromise;
+  let navigationIntent = 0;
   const lifecycle = createSessionLifecycle();
   let publication = 0;
   let loginIntent = 0;
   let acceptPeerTokens = true;
   const peerWaiters = /* @__PURE__ */ new Set();
+  const withdrawNavigation = () => {
+    navigationIntent++;
+    navigationPromise = void 0;
+  };
   const readStorage = (key) => {
     try {
       const value = sessionStorage.getItem(key);
@@ -732,6 +738,7 @@ var createOidcVaultDpopSession = (options) => {
   };
   const invalidateLocal = (clearPendingLogin = true) => {
     const authority = lifecycle.invalidate();
+    withdrawNavigation();
     refreshPromise = void 0;
     resetPromise = void 0;
     clearLocal(clearPendingLogin);
@@ -811,7 +818,7 @@ var createOidcVaultDpopSession = (options) => {
     let nonceRetried = false;
     for (; ; ) {
       authority.assertCurrent();
-      const recognition = route === "logout" ? {} : await fingerprint?.headers() ?? {};
+      const recognition = route === "logout" || route === "logout/navigation" ? {} : await fingerprint?.headers() ?? {};
       const currentKey = await existingKey(authority, jkt);
       authority.assertCurrent();
       const proof = await createDpopProof(currentKey, {
@@ -1055,6 +1062,7 @@ var createOidcVaultDpopSession = (options) => {
     sessionTransport,
     async login(returnTo) {
       const authority = lifecycle.capture();
+      withdrawNavigation();
       loginIntent++;
       refreshPromise = void 0;
       resetPromise = void 0;
@@ -1100,6 +1108,7 @@ var createOidcVaultDpopSession = (options) => {
     },
     async exchange(code) {
       const authority = lifecycle.capture();
+      withdrawNavigation();
       refreshPromise = void 0;
       resetPromise = void 0;
       return operation(authority, async () => {
@@ -1166,6 +1175,7 @@ var createOidcVaultDpopSession = (options) => {
     },
     async logout() {
       const authority = lifecycle.capture();
+      withdrawNavigation();
       refreshPromise = void 0;
       resetPromise = void 0;
       await operation(authority, async () => {
@@ -1182,6 +1192,56 @@ var createOidcVaultDpopSession = (options) => {
         await invalidateCookie(authority, key.jkt);
       });
     },
+    logoutAndNavigate() {
+      const authority = lifecycle.capture();
+      if (navigationPromise) return navigationPromise;
+      const intent = navigationIntent;
+      const navigation = lifecycle.capture(() => navigationIntent === intent);
+      refreshPromise = void 0;
+      resetPromise = void 0;
+      const pending = operation(authority, async () => {
+        navigation.assertCurrent();
+        const key = await authenticatedKey(authority);
+        authority.assertCurrent();
+        if (channel) {
+          const version = await readCookieSessionVersion(scope.id);
+          authority.assertCurrent();
+          if (!version?.active || version.jkt !== key.jkt) throw loginRequired();
+          cookieBindings.set(authority, { ...version });
+        }
+        const handle = sessionTransport === "body" ? readStorage(storageKey) : void 0;
+        if (sessionTransport === "body" && (!handle?.sessionId || handle.jkt !== key.jkt)) throw loginRequired();
+        const { value } = await post(
+          authority,
+          "logout/navigation",
+          handle ? { sessionId: handle.sessionId } : {},
+          key
+        );
+        authority.assertCurrent();
+        const invalidResponse = () => new OidcVaultDpopClientError(
+          "INVALID_LOGOUT_NAVIGATION_RESPONSE",
+          "The logout navigation response is invalid."
+        );
+        if (typeof value !== "object" || value === null || !("loggedOut" in value) || value.loggedOut !== true)
+          throw invalidResponse();
+        clearLocal();
+        await invalidateCookie(authority, key.jkt);
+        authority.assertCurrent();
+        navigation.assertCurrent();
+        const bare = `${scope.backendOrigin}${scope.basePath === "/" ? "" : scope.basePath}/logout/navigation`;
+        const url = "navigationUrl" in value ? value.navigationUrl : void 0;
+        if (typeof url !== "string" || url !== bare && (url.length !== bare.length + "?ticket=".length + 47 || !url.startsWith(`${bare}?ticket=`) || !/^lnt_[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/.test(url.slice(`${bare}?ticket=`.length))))
+          throw invalidResponse();
+        navigation.assertCurrent();
+        navigate(url);
+      });
+      navigationPromise = pending;
+      void pending.finally(() => {
+        if (navigationPromise === pending) navigationPromise = void 0;
+      }).catch(() => {
+      });
+      return pending;
+    },
     getAccessToken: () => token,
     async getKey() {
       const authority = stateAuthority();
@@ -1236,6 +1296,7 @@ var createOidcVaultDpopSession = (options) => {
     },
     dispose() {
       lifecycle.dispose();
+      withdrawNavigation();
       publication++;
       refreshPromise = void 0;
       resetPromise = void 0;

package/index.mjs

@@ -658,11 +658,17 @@ var createOidcVaultDpopSession = (options) => {
   const cookieBindings = /* @__PURE__ */ new WeakMap();
   let refreshPromise;
   let resetPromise;
+  let navigationPromise;
+  let navigationIntent = 0;
   const lifecycle = createSessionLifecycle();
   let publication = 0;
   let loginIntent = 0;
   let acceptPeerTokens = true;
   const peerWaiters = /* @__PURE__ */ new Set();
+  const withdrawNavigation = () => {
+    navigationIntent++;
+    navigationPromise = void 0;
+  };
   const readStorage = (key) => {
     try {
       const value = sessionStorage.getItem(key);
@@ -700,6 +706,7 @@ var createOidcVaultDpopSession = (options) => {
   };
   const invalidateLocal = (clearPendingLogin = true) => {
     const authority = lifecycle.invalidate();
+    withdrawNavigation();
     refreshPromise = void 0;
     resetPromise = void 0;
     clearLocal(clearPendingLogin);
@@ -779,7 +786,7 @@ var createOidcVaultDpopSession = (options) => {
     let nonceRetried = false;
     for (; ; ) {
       authority.assertCurrent();
-      const recognition = route === "logout" ? {} : await fingerprint?.headers() ?? {};
+      const recognition = route === "logout" || route === "logout/navigation" ? {} : await fingerprint?.headers() ?? {};
       const currentKey = await existingKey(authority, jkt);
       authority.assertCurrent();
       const proof = await createDpopProof(currentKey, {
@@ -1023,6 +1030,7 @@ var createOidcVaultDpopSession = (options) => {
     sessionTransport,
     async login(returnTo) {
       const authority = lifecycle.capture();
+      withdrawNavigation();
       loginIntent++;
       refreshPromise = void 0;
       resetPromise = void 0;
@@ -1068,6 +1076,7 @@ var createOidcVaultDpopSession = (options) => {
     },
     async exchange(code) {
       const authority = lifecycle.capture();
+      withdrawNavigation();
       refreshPromise = void 0;
       resetPromise = void 0;
       return operation(authority, async () => {
@@ -1134,6 +1143,7 @@ var createOidcVaultDpopSession = (options) => {
     },
     async logout() {
       const authority = lifecycle.capture();
+      withdrawNavigation();
       refreshPromise = void 0;
       resetPromise = void 0;
       await operation(authority, async () => {
@@ -1150,6 +1160,56 @@ var createOidcVaultDpopSession = (options) => {
         await invalidateCookie(authority, key.jkt);
       });
     },
+    logoutAndNavigate() {
+      const authority = lifecycle.capture();
+      if (navigationPromise) return navigationPromise;
+      const intent = navigationIntent;
+      const navigation = lifecycle.capture(() => navigationIntent === intent);
+      refreshPromise = void 0;
+      resetPromise = void 0;
+      const pending = operation(authority, async () => {
+        navigation.assertCurrent();
+        const key = await authenticatedKey(authority);
+        authority.assertCurrent();
+        if (channel) {
+          const version = await readCookieSessionVersion(scope.id);
+          authority.assertCurrent();
+          if (!version?.active || version.jkt !== key.jkt) throw loginRequired();
+          cookieBindings.set(authority, { ...version });
+        }
+        const handle = sessionTransport === "body" ? readStorage(storageKey) : void 0;
+        if (sessionTransport === "body" && (!handle?.sessionId || handle.jkt !== key.jkt)) throw loginRequired();
+        const { value } = await post(
+          authority,
+          "logout/navigation",
+          handle ? { sessionId: handle.sessionId } : {},
+          key
+        );
+        authority.assertCurrent();
+        const invalidResponse = () => new OidcVaultDpopClientError(
+          "INVALID_LOGOUT_NAVIGATION_RESPONSE",
+          "The logout navigation response is invalid."
+        );
+        if (typeof value !== "object" || value === null || !("loggedOut" in value) || value.loggedOut !== true)
+          throw invalidResponse();
+        clearLocal();
+        await invalidateCookie(authority, key.jkt);
+        authority.assertCurrent();
+        navigation.assertCurrent();
+        const bare = `${scope.backendOrigin}${scope.basePath === "/" ? "" : scope.basePath}/logout/navigation`;
+        const url = "navigationUrl" in value ? value.navigationUrl : void 0;
+        if (typeof url !== "string" || url !== bare && (url.length !== bare.length + "?ticket=".length + 47 || !url.startsWith(`${bare}?ticket=`) || !/^lnt_[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/.test(url.slice(`${bare}?ticket=`.length))))
+          throw invalidResponse();
+        navigation.assertCurrent();
+        navigate(url);
+      });
+      navigationPromise = pending;
+      void pending.finally(() => {
+        if (navigationPromise === pending) navigationPromise = void 0;
+      }).catch(() => {
+      });
+      return pending;
+    },
     getAccessToken: () => token,
     async getKey() {
       const authority = stateAuthority();
@@ -1204,6 +1264,7 @@ var createOidcVaultDpopSession = (options) => {
     },
     dispose() {
       lifecycle.dispose();
+      withdrawNavigation();
       publication++;
       refreshPromise = void 0;
       resetPromise = void 0;

package/llms.txt

@@ -14,6 +14,7 @@ createDeviceFingerprint, fingerprintJsSignalSource, OidcVaultDpopClientError.
 Full root type list and member contracts: README API reference + index.d.mts.
 Both declaration conditions are DOM-only (types:[], skipLibCheck:false).
 Wire DTOs come from express-oidc-vault/wire at build time and are bundled here.
+Root DTOs: OidcVaultLogoutNavigationInput, OidcVaultLogoutNavigationResult (DOM-only).
 
 Session: createOidcVaultDpopSession({backendOrigin,basePath,sessionTransport})
 defaults to /auth/oidc + body. login -> exchange(code) -> API/refresh -> logout.
@@ -36,6 +37,19 @@ server revocation; reset leaves old sessions/JWTs until revocation/expiry.
 DPOP_OPERATION_SUPERSEDED / DPOP_SESSION_DISPOSED are non-terminal; stale work
 cannot publish/navigate/clear newer auth. See README's cleanup/recovery tables.
 
+Provider logout: server logoutNavigation opt-in + session.logoutAndNavigate():Promise<void>.
+Existing key/handle or active matching cookie metadata; absent/expired JWT works,
+no refresh/fingerprint/Authorization/ath. Same HTTP bounds/nonce cache, one fresh-proof retry.
+Exact pinned backend bare or canonical ticket URL only; no API token in GET/IdP URL in JSON.
+Confirmed loggedOut:true clears old state even on INVALID_LOGOUT_NAVIGATION_RESPONSE.
+Unconfirmed/lost responses retain uncertainty, no navigation or automatic mutation retry.
+Clicks share one Promise/adapter call; FIFO preserves rotation. Login/exchange/local logout/
+clear/reset/dispose withdraw old navigation intent immediately, including queued login.
+Synchronous navigate adapter handles login AND logout inside authority; do not defer handoff.
+Single-use ticket (default60s, 1..120s) -> provider or fixed fallback; replay falls back.
+Hint URL retained server-side until consume/expiry/cleanup; navigation URLs remain log/history
+exposures. After IdP handoff its availability/return is not guaranteed. logout() stays local.
+
 HTTP: requestTimeoutMs=15000 ms per vault headers/body/JSON attempt;
 maxResponseBytes=1048576 streamed bytes. Bounds exclude queue/storage/key/hooks/
 other locks. Timeout/size errors retain auth. API/proof signal stops only this

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/oidc-vault-dpop-client",
   "description": "DPoP browser client for @web-ts-toolkit/express-oidc-vault with body+cookie transports",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/oidc-vault-dpop-client",
-  "version": "0.53.0",
+  "version": "0.55.0",
   "sideEffects": false,
   "keywords": [
     "oidc",