npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@web-ts-toolkit/oidc-vault-dpop-client

v0.74.0

Published

Browser vault sessions and scoped fetch with default DPoP or explicit Bearer, body+cookie transports

Readme

@web-ts-toolkit/oidc-vault-dpop-client

Browser-only client for @web-ts-toolkit/express-oidc-vault vault flows, with body and cookie session transports. DPoP is on by default (omitted dpop or dpop: true): persistent non-extractable P-256 keys, per-attempt proofs and bounded nonce/refresh retries. Explicit dpop: false selects keyless Bearer for the whole session, never automatic fallback. Both modes use app-local credentials, not IdP access, ID or refresh tokens. Bearer token theft permits replay; it does not provide DPoP's sender constraint.

The package ships at an es2022 bundle target for modern evergreen browsers (Chrome 94+, Edge 94+, Firefox 93+, Safari 16+, declared via browserslist). It touches browser globals (crypto.subtle, indexedDB, sessionStorage, and — cookie transport only — navigator.locks plus BroadcastChannel) lazily behind runtime feature asserts, never at module import time. There is no express, no node:*, and no default export.

Guide: Quickstart · Explicit Bearer · Auto-refresh · Observation · Lifecycle/cleanup · HTTP bounds · Recovery · Gateway scopes · Upgrade notes

Installation

pnpm add @web-ts-toolkit/oidc-vault-dpop-client

jose and idb are runtime dependencies of this package, not peers: the single install above is enough. Do not install them separately unless your own code imports them directly.

Requirements: DPoP needs secure-context Web Crypto, IndexedDB CryptoKey persistence and sessionStorage. Body Bearer needs secure-context Web Crypto digest/UUID support and sessionStorage, not IndexedDB or CryptoKey. Cookie Bearer still needs IndexedDB for non-credential metadata, plus Web Locks and BroadcastChannel (also required for cookie DPoP). Keyless does not mean storage-free. Feature checks run when creating/using a session, so importing the module is safe before browser startup. Keep one lazy session per tab/vault mount.

Node tooling/runtime imports require Node >=22.12.0: the CJS entry synchronously requires ESM-only jose, using Node's default require(esm) support. Node 22.0–22.11 cannot load it without an experimental flag. Node importability does not supply the browser storage needed to create a session.

Strict DOM-only TypeScript consumers can use types: [] and skipLibCheck: false with Bundler or NodeNext resolution. ESM resolves index.d.mts, CJS resolves index.d.ts; both are self-contained, without Node types, Express augmentation, or a backend package dependency. In workspace/npm source-tree packs these files live under dist/; release packaging flattens them and rewrites the export map. Always import by package name.

Canonical imports

Named root imports only; no default export, no deep dist/* or src/* imports.

import {
  createDeviceFingerprint,
  createDpopProof,
  createOidcVaultDpopSession,
  fetchWithDpop,
  fingerprintJsSignalSource,
  getOrCreateDpopKey,
  OidcVaultDpopClientError,
} from '@web-ts-toolkit/oidc-vault-dpop-client';
import type {
  DpopAccessToken,
  DpopApi,
  DpopFetchContext,
  DpopFetchOptions,
  DpopKey,
  OidcVaultDpopSession,
  BearerAccessToken,
  BearerApi,
  BearerFetchContext,
  OidcVaultAccessToken,
  OidcVaultBearerSession,
  OidcVaultBearerSessionOptions,
  OidcVaultSession,
  OidcVaultSessionOptions,
  OidcVaultFetchContext,
} from '@web-ts-toolkit/oidc-vault-dpop-client';

export const sessionApi = { createOidcVaultDpopSession, fetchWithDpop };
export type { DpopAccessToken, DpopKey, OidcVaultDpopSession, BearerAccessToken, OidcVaultSession };

DpopNonceCache and the DeviceFingerprint family are also exported from the root for typed consumption. Non-public coordination helpers (withDpopDatabase, resolveDpopScope, cookie-version bookkeeping) stay internal on purpose: scope to one backendOrigin + basePath per session and let the session own key/proof/nonce coordination.

Quickstart: body transport

One vault mount, one session. basePath must equal the backend's exact public mount (the core default is /auth/oidc; the example app mounts /auth/oidc/body and /auth/oidc/cookie side by side — pick the one you call).

import {
  createOidcVaultDpopSession,
  fetchWithDpop,
  OidcVaultDpopClientError,
} from '@web-ts-toolkit/oidc-vault-dpop-client';

const backendOrigin = 'https://api.example.com';
const session = createOidcVaultDpopSession({
  backendOrigin,
  basePath: '/auth/oidc/body',
  sessionTransport: 'body',
});

// A login button calls this; login creates/persists the key BEFORE POST and navigation.
export async function signIn(): Promise<void> {
  await session.login('/callback?transport=body');
}

// On /callback or application bootstrap:
export async function bootstrap(): Promise<'ready' | 'sign-in'> {
  try {
    const url = new URL(location.href);
    const code = url.searchParams.get('code');
    if (code !== null) {
      url.searchParams.delete('code');
      history.replaceState(null, '', url.href);
      await session.exchange(code);
    } else {
      await session.refresh(); // Existing persistent key only; no Authorization/ath.
    }
    return 'ready';
  } catch (error) {
    if (error instanceof OidcVaultDpopClientError && error.requiresLogin) return 'sign-in';
    throw error; // Keep recovery state on transient/proof/nonce failures.
  }
}

export async function getProfile(): Promise<unknown> {
  const response = await fetchWithDpop(
    { session, apis: [{ origin: backendOrigin, replayNamespace: 'my-app-api' }] },
    `${backendOrigin}/api/profile`,
  );
  if (!response.ok) throw new Error('Protected API request failed.');
  return response.json();
}

export async function signOut(): Promise<void> {
  await session.logout();
}

Lifecycle is login → exchange(code) → getAccessToken()/fetchWithDpop → refresh → logout. Vault POSTs carry no Authorization and no ath, so local JWT expiry never blocks refresh. All vault and API credential responses are Cache-Control: no-store; body handles are tab-local (see Storage).

On a new tab with no usable login, bootstrap returns 'sign-in'; show the sign-in action. On success it has accepted the response contract, including valid zero-lifetime credentials (bound profile). Render a recoverable error for other failures rather than clearing auth or automatically repeating mutations. A corrupt persisted key needs the explicit reset-then-login action.

Quickstart: cookie transport

Same session shape, sessionTransport: 'cookie', and the matching cookie mount. Cookie mode additionally requires Web Locks and BroadcastChannel at runtime; unsupported browsers fail explicitly via DPOP_TAB_COORDINATION_UNSUPPORTED.

import { createOidcVaultDpopSession } from '@web-ts-toolkit/oidc-vault-dpop-client';

export const session = createOidcVaultDpopSession({
  backendOrigin: 'https://api.example.com',
  basePath: '/auth/oidc/cookie',
  sessionTransport: 'cookie',
});

export async function signIn(): Promise<void> {
  await session.login('/callback?transport=cookie');
}

Apply the callback/bootstrap, API and logout flow above to this session. Cookie refresh uses one same-origin Web Lock per vault scope plus BroadcastChannel winner-token delivery: a tab adopts a live peer token for up to 180ms, otherwise it performs its own serialized refresh with the current browser cookie. Peer adoption still validates payload, key binding, expiry, generation, and current recognition. Each API call and retry signs its own 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.

Explicit Bearer mode

Use only with a supported backend/API pairing. The names stay createOidcVaultDpopSession and fetchWithDpop; there is no rename or alias. The immutable selection is snapshotted at construction; nonboolean runtime values reject. Changing options later, a response or an authentication challenge cannot change mode. Switching requires a fresh login, not refreshing an existing bound session as Bearer. Close/reload old DPoP-only tabs first when replacing a shared cookie session (see Storage).

import {
  createOidcVaultDpopSession,
  fetchWithDpop,
  OidcVaultDpopClientError,
  type BearerAccessToken,
  type OidcVaultBearerSessionOptions,
} from '@web-ts-toolkit/oidc-vault-dpop-client';

const backendOrigin = 'https://api.example.com';
let view: BearerAccessToken | undefined; // Optional memory-only mirror.
const options: OidcVaultBearerSessionOptions = {
  backendOrigin,
  basePath: '/auth/oidc/body',
  sessionTransport: 'body', // Or 'cookie' with the matching cookie mount.
  dpop: false,
  autoRefresh: { refreshBeforeExpiryMs: 60_000 }, // Optional; default is off.
  onCredentialsChanged(credentials) {
    view = credentials; // Inferred BearerAccessToken | undefined; no jkt.
  },
  onAutoRefreshError(error) {
    // Report paused scheduling; never automatically retry an uncertain rotation.
    console.error(error instanceof OidcVaultDpopClientError ? error.code : 'refresh-paused');
  },
};
const session = createOidcVaultDpopSession(options);
export const readView = () => view;
export const signIn = (): Promise<void> => session.login('/callback');

// Explicit callback/reload bootstrap, not performed by construction or autoRefresh.
export async function bootstrap(): Promise<'ready' | 'sign-in'> {
  try {
    const url = new URL(location.href);
    const code = url.searchParams.get('code');
    if (code !== null) {
      url.searchParams.delete('code');
      history.replaceState(null, '', url.href);
      await session.exchange(code);
    } else await session.refresh();
    return 'ready';
  } catch (error) {
    if (error instanceof OidcVaultDpopClientError && error.requiresLogin) return 'sign-in';
    throw error;
  }
}

export const refresh = (): Promise<BearerAccessToken> => session.refresh();
export const loadProfile = (): Promise<Response> =>
  fetchWithDpop({ session, apis: [{ origin: backendOrigin, pathPrefix: '/api' }] }, `${backendOrigin}/api/profile`); // Authorization: Bearer <app-local token>; no proof/nonce/key work.
export const signOut = (): Promise<void> => session.logout();

An inline literal dpop: false infers the same Bearer observer/session types; existing OidcVaultDpopSessionOptions stays DPoP-only. For a runtime boolean, use the union options and narrow credentials by tokenType, sessions by dpop:

import {
  createOidcVaultDpopSession,
  fetchWithDpop,
  type OidcVaultAccessToken,
  type OidcVaultSessionOptions,
  type OidcVaultFetchContext,
} from '@web-ts-toolkit/oidc-vault-dpop-client';

export function configureSession(dpopEnabled: boolean) {
  let view: OidcVaultAccessToken | undefined;
  const options: OidcVaultSessionOptions = {
    backendOrigin: 'https://api.example.com',
    dpop: dpopEnabled,
    autoRefresh: { refreshBeforeExpiryMs: 60_000 },
    onCredentialsChanged(credentials) {
      view = credentials;
      if (credentials?.tokenType === 'DPoP') credentials.jkt satisfies string;
      // Bearer has no jkt; never invent one or persist the token.
    },
    onAutoRefreshError: () => {
      /* Show explicit recovery UI. */
    },
  };
  const session = createOidcVaultDpopSession(options);
  // Runtime-mode contexts still need DPoP-compatible namespaces.
  const context: OidcVaultFetchContext = {
    session,
    apis: [{ origin: options.backendOrigin, replayNamespace: 'app-api' }],
  };
  return {
    session,
    readView: () => view,
    loadProfile: () => fetchWithDpop(context, `${options.backendOrigin}/api/profile`),
  };
}

Only definitely-Bearer BearerApi/BearerFetchContext may omit replayNamespace; a supplied namespace is validated but unused. Runtime-mode contexts require namespaces until narrowed to !session.dpop. Bearer's interface has no getKey, resetKey or logoutAndNavigate. Runtime probes reject fixed nonterminal DPOP_OPERATION_UNSUPPORTED before storage/key/network/navigation or lifecycle side effects. Ordinary logout() works even after app-token expiry. There is no unbound provider-navigation logout.

Bearer uses the same FIFO, observers and default-off scheduler, HTTP bounds, scope/header restrictions, CSRF/transaction-cookie protection and credentials matrix. It never sends a DPoP proof, reads nonce headers or uses a nonce cache. An API must independently authenticate/authorize unbound credentials; choosing Bearer at the vault does not turn off an API's required-binding policy.

Provider logout navigation

DPoP only. 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.

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.

Observing credentials

Prefer session.getAccessToken() as the single token source. When an application needs an in-memory mirror or reactive view, observe committed changes independently of refresh scheduling:

import { createOidcVaultDpopSession, type DpopAccessToken } from '@web-ts-toolkit/oidc-vault-dpop-client';

let applicationCredential: DpopAccessToken | undefined;
export const session = createOidcVaultDpopSession({
  backendOrigin: 'https://api.example.com',
  onCredentialsChanged: (credentials) => {
    applicationCredential = credentials; // undefined means cleared; do not persist.
  },
});
export const readApplicationCredential = () => applicationCredential;

This covers exchange, manual/API refresh, validated cookie-peer adoption, and local/peer/terminal clearing. Delivery is asynchronous, coalesced latest state, not an event log: superseded intermediate values and duplicate peer messages do not produce events. The callback runs outside this instance's mutation/lock ownership; it is never awaited, and throws/returned rejected promises are contained. Reentrant session calls are allowed but retain their normal lifecycle semantics. Disposal suppresses pending token delivery and emits a final undefined only when a token was previously observed; there are no later notifications. No callback runs merely because the session was constructed. Callback failures do not undo credential rotation or clear auth. Tokens remain memory-only.

Opt-in proactive refresh

Auto-refresh is off by default (autoRefresh omitted or false). An options object enables it after a successful explicit exchange() or refresh(); creating a session does not bootstrap, generate a key, refresh a stored handle, or navigate.

import { createOidcVaultDpopSession, OidcVaultDpopClientError } from '@web-ts-toolkit/oidc-vault-dpop-client';

let recovery: 'none' | 'sign-in' | 'refresh-paused' = 'none';
export const session = createOidcVaultDpopSession({
  backendOrigin: 'https://api.example.com',
  autoRefresh: { refreshBeforeExpiryMs: 60_000 },
  onAutoRefreshError: (error) => {
    recovery = error instanceof OidcVaultDpopClientError && error.requiresLogin ? 'sign-in' : 'refresh-paused';
    // Show recovery UI. Never automatically log in or retry an uncertain rotation.
  },
});
export const readRecovery = () => recovery;
// Bootstrap/callback still explicitly calls session.refresh()/exchange(code).

| Option | Enabled default | Meaning / valid milliseconds | | ----------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | refreshBeforeExpiryMs | 60,000 | Lead before effective expiresAt, not a periodic interval. Integer 0..2,147,483,647. When acquisition time is known, capped to half the initial remaining lifetime. | | maxRefreshIntervalMs | unset | Explicit keep-alive deadline since successful acquisition. Integer 1,000..2,147,483,647; no implicit keep-alive policy. |

The earlier deadline wins, with a one-second minimum scheduled cadence. A one-hour token with a 60-second lead refreshes around minute 59. A 60-second token caps that lead to 30 seconds; extremely short credentials can expire before the cadence floor. Zero/nonlive results pause with non-terminal DPOP_ACCESS_TOKEN_EXPIRED (or BEARER_ACCESS_TOKEN_EXPIRED in Bearer mode) while retaining rotated handles. Repeated short results never start a tight loop.

A one-hour app token can outlive a 30-minute provider idle timeout. Applications that explicitly accept keep-alive can instead choose, for example:

import type { OidcVaultDpopAutoRefreshOptions } from '@web-ts-toolkit/oidc-vault-dpop-client';

export const keepAlivePolicy: OidcVaultDpopAutoRefreshOptions = {
  refreshBeforeExpiryMs: 60_000,
  maxRefreshIntervalMs: 20 * 60_000, // Explicit application policy, not the default.
};

Either scheduling policy may keep an idle upstream session active, depending on token lifetimes and provider settings. Neither measures user activity or replaces application idle logout, nor extends provider/vault absolute session expiry. Timers run in hidden tabs when the browser allows, but cannot guarantee refresh during throttling, BFCache/device sleep or browser shutdown. Visible visibilitychange and pageshow recheck one deadline, never catch up missed ticks. Always retain a Sign in again action.

Scheduled work uses the same refresh FIFO/single-flight and cookie Web Lock. A deadline is rechecked after admission and peer adoption, avoiding redundant rotation when a newer winner already satisfies the policy. Cookie metadata adds an optional generation-bound acquisition-clock hint (refreshedAt), never a token or handle. Peer receipt/rebroadcast does not reset the deadline. Missing, malformed or future hints from old records make an enabled maximum interval due rather than pretending the provider saw fresh activity. Existing keys/schema remain usable. Coordination is still same frontend origin/storage partition/scope, not a backend lease; lost peer delivery may require a later serialized refresh. Body sessions remain tab-local and never share handles.

Login/exchange/logout/navigation-logout intent withdraws pending scheduled work; clear/reset/terminal invalidation stop it and disposal removes its timer/listeners. An already-started refresh may publish its rotation before an ordered logout uses it, but cannot rearm behind that logout. No scheduled callback navigates or replays a protected API mutation.

Failures pause scheduling and report once through onAutoRefreshError(error); terminal errors retain normal cleanup, others retain recovery state. The callback is never awaited and throws/rejected promises are contained. Resume/online events and unsolicited peer tokens do not unpause failure; successful explicit local exchange/refresh rearms. An old failure cannot pause a newer admitted winner. There is no blanket retry/backoff: a lost response or timeout may already have rotated credentials. Manual operations still reject their own promises; the background callback is not a replacement for their error handling. Failed manual refresh also pauses existing scheduling silently, so a later timer cannot become an implicit retry of that possibly committed mutation. Superseded work without an admitted newer winner pauses silently; follow the current explicit session flow rather than retrying an obsolete credential in a timer loop.

Lifecycle concurrency and cleanup

Use one session instance per tab and vault mount. In both transports, 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.

The key/reset/navigation-logout details below apply only to DPoP. Bearer shares the common lifecycle methods, and cookie cleanup is mode/generation-guarded so an old context cannot invalidate another mode's replacement generation.

Concurrent refresh() callers receive the same Promise until a call to 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 failure cleanup enters the mutation queue. They neither start refresh nor erase a pending login merely because exchange has not finished.

Every asynchronous session operation keeps its entry-time authority. clear, resetKey, a terminal auth failure, and dispose supersede older work, including queued operations. Stale results cannot publish tokens/handles, change cookie generation metadata, clear a newer login, or navigate. A stale call rejects with DPOP_OPERATION_SUPERSEDED, or DPOP_SESSION_DISPOSED after disposal; both have requiresLogin: false. Follow the current session flow rather than clearing auth or starting another login in response to these errors. Key reads and background peer callbacks also lose authority when a 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. | | 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 context; an explicit successful exchange/refresh must reestablish auth. Peer waits end within 180ms, or immediately on local invalidation/disposal, and a late peer lookup cannot publish after that wait has ended. Same-origin tabs still reuse the current generation's live winner token; key-loss, expiry and recognition checks remain mandatory. Reset notifications are advisory: peers check that both scoped records are still absent and that their local key/generation matches the deletion. A delayed notification or old-binding failure cannot clear a replacement login, including a fresh key created before cookie metadata is written. Concurrent resets share their pending removal until another lifecycle mutation intervenes; repeating after completion also succeeds when both records are already absent.

Clear/token/reset messages are advisory until their shared key/generation state is checked. A failed peer recognition or coordination lookup leaves local auth and pending login intact. An admitted token's key-validation failure still invalidates a matching current local credential; explicit credential operations continue to report genuine key/storage and terminal session errors.

Limits: already-started storage/crypto and noncooperative custom transport work may still finish, but superseded results cannot publish. Vault HTTP waits are bounded as described below; storage, recognition hooks, and time waiting for other Web Lock owners are outside that HTTP deadline. Cleanup cannot undo a server mutation or a browser-applied Set-Cookie. Await clear() or resetKey() before disposing when its persistence work must finish. Lifecycle cleanup also does not cancel caller-owned API requests or revoke already-issued stateless JWTs. Coordination remains limited to one frontend origin/storage partition/scope.

HTTP bounds and cancellation

All vault login/exchange/refresh/logout/logoutAndNavigate attempts use these session options:

| Option | Default | Valid values / scope | | ------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | requestTimeoutMs | 15,000 milliseconds | Integer from 1 through 2,147,483,647. One deadline from fetch invocation through response headers, full body read, and JSON parsing. | | maxResponseBytes | 1,048,576 bytes (1 MiB) | Positive safe integer. Counts bytes actually read from the fetch body stream on every HTTP status, after browser HTTP decompression. |

Invalid options throw TypeError at session construction; zero and infinity do not disable the bounds. Content-Length is not trusted to measure the body: missing, understated, overstated, or malformed values do not change the byte count. UTF-8 characters count by their bytes, not JavaScript string length. Custom fetch implementations must expose a standard streaming Response.body.

import { createOidcVaultDpopSession, fetchWithDpop } from '@web-ts-toolkit/oidc-vault-dpop-client';
import type { OidcVaultDpopSessionOptions } from '@web-ts-toolkit/oidc-vault-dpop-client';

const options: OidcVaultDpopSessionOptions = {
  backendOrigin: 'https://api.example.com',
  requestTimeoutMs: 15_000,
  maxResponseBytes: 1_048_576,
};
const session = createOidcVaultDpopSession(options);

// Supply the caller's AbortController.signal (for example, on page teardown).
export async function loadProfile(signal: AbortSignal): Promise<unknown> {
  const response = await fetchWithDpop(
    { session, apis: [{ origin: options.backendOrigin, replayNamespace: 'my-app-api' }] },
    `${options.backendOrigin}/api/profile`,
    { signal },
  );
  return response.json();
}

The HTTP deadline excludes the lifecycle queue, key/proof/recognition work and credential publication. An allowed nonce retry gets its own deadline, with the existing two-attempt vault budget. A trickling body cannot reset it. Deadline or byte overflow rejects with fixed DPOP_REQUEST_TIMEOUT or DPOP_RESPONSE_TOO_LARGE, both requiresLogin: false. These failures do not themselves clear auth, and release refresh/FIFO/Web Lock ownership for a later explicit operation. Malformed JSON still follows the existing route response-contract error handling.

Clear/reset/invalidation/disposal abort the session-owned request and stop waiting even if an injected fetch or stream ignores AbortSignal. Cancellation and reader cleanup are best effort: their failure or noncompletion cannot delay settlement or replace its primary outcome. Late responses are discarded and late rejections are observed. Timers cannot run in suspended tabs or preempt synchronous JavaScript; elapsed time is also checked after decoding/parsing before accepting a result.

For fetchWithDpop, a pre-aborted signal starts no refresh, key lookup, proof or network work. Later cancellation rejects with signal.reason promptly, including while waiting for shared refresh/key work. It cancels only this caller's wait; another waiter's shared refresh continues and may publish its result. Proof work checks cancellation before signing, including after the access-token digest; already-started Web Crypto may finish. Standalone createDpopProof also accepts DpopProofInput.signal. API requests receive the caller signal; the returned response/body belongs to the caller. The vault timeout/byte options do not bound API bodies. Cleanup of a discarded API challenge response cannot stall its permitted retry or replace its outcome.

Uncertain commit / retry: no timeout, cancellation, byte-limit, or network failure automatically retries a mutation. The server may already have consumed an exchange code, rotated a refresh handle, or completed logout, and the browser may already have applied Set-Cookie. Aborting does not roll that back. An explicit retry is not evidence that the first attempt failed; a lost body-mode rotation can make the retained old handle unusable and require fresh login. Use the operation's server-side recovery/idempotency contract when deciding what to do next.

Backend pairing

Configure the vault mount this client calls. backendOrigin must be the exact public origin (scheme + host + port); basePath must match the public mount. Unreserved path escapes, dot segments and trailing slashes normalize; the key scope, proof htu and request URL all derive from that path. Use 127.0.0.1 consistently in loopback development: localhost is a different origin and a different key scope.

Backend options that must agree with this client (authoritative wire contract: express-oidc-vault README):

  • basePath: the same mount (e.g. /auth/oidc/body with sessionTransport: 'body', /auth/oidc/cookie with 'cookie').
  • trustedOrigins: list every browser source origin allowed to POST login/guarded exchange (both transports) and cookie-authenticated refresh/logout. Required for cross-site session cookie transport.
  • transactionCookie.sameSite: keep the default lax for same-site deployments. HTTPS cross-site SPAs need explicit transactionCookie: { sameSite: 'none' }, plus matching session-cookie deployment policy, credentialed CORS, and a browser policy that permits third-party cookies.
  • 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 DPoP API's replayNamespace must equal the replayNamespace configured in fetchWithDpop apis entries.

| Vault binding policy | Client pairing | | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | required | Omitted/true DPoP. Explicit Bearer is rejected; never downgrade. | | optional | Primary dual-mode target: guarded POST login accepts DPoP or explicit unbound Bearer. Original binding survives refresh. | | Disabled + fingerprintRecognition configured | Existing guarded POST login can support Bearer. Recognition is optional enrollment/change detection, not PoP. | | Disabled without recognition | Unsupported by this client: no guarded POST-login route. No legacy GET-login fallback; backend expansion is deferred. |

In all cases, configure a local tokenIssuer with the selected credential profile. APIs independently need unbound acceptance (e.g. optional API binding with request-aware verification, or an appropriate unbound-only validator). Required API binding rejects Bearer even when optional vault binding issued it. No server binding option re-enrolls or downgrades an existing session. Login/exchange retain their temporary browser-binding cookie; cookie refresh/logout retain strict Origin/Referer checks and trusted-origin/CORS requirements in both modes.

Bound credential response

Exchange/refresh must return exact tokenType: 'DPoP' and a compact signed JWT: three nonempty canonical unpadded base64url segments, a nonempty signing alg other than none, and no b64: false payload. Its cnf must be exactly { jkt }, with the canonical RFC 7638 SHA-256 thumbprint of the persistent browser key (43 base64url characters, including canonical final bits). Additional confirmation fields/methods are rejected.

JWT exp is mandatory: a nonnegative safe integer in epoch seconds, with safe exp * 1000 milliseconds. Response expiresIn is nonnegative safe-integer seconds; its millisecond conversion and addition to the current nonnegative safe-integer epoch-millisecond clock must also be safe. Invalid or overflowing values are rejected even when a shorter deadline could otherwise hide them. The effective DpopAccessToken.expiresAt is the earlier of the response deadline and JWT expiry. These are response-contract decode checks, not JWT authentication: each API must independently verify the JWT signature/expiry/issuer/audience and the original-key request proof.

expiresIn: 0 remains valid so a rotated body handle can be retained. The returned credential may already be expired; getAccessToken() is a snapshot, not a guarantee of a live token. fetchWithDpop checks the deadline per attempt and after asynchronous proof work. A nonlive refresh result stops with DPOP_ACCESS_TOKEN_EXPIRED (requiresLogin: false), preserves session handles, and starts no additional refresh loop; a later explicit refresh may recover. Cookie peer adoption clamps the envelope deadline to JWT expiry and requires the final result to be strictly in the future. Cookie responses and peer tokens must contain no sessionId property.

Invalid direct responses produce INVALID_BOUND_CREDENTIAL_RESPONSE; invalid or expired peer tokens are ignored. The paired server enforces the same bound JWT profile before claim mapping in both validator methods after JOSE verification. Generic unbound JWTs retain optional-expiry compatibility, and unbound issuers can still return opaque tokens in explicit Bearer mode.

Bearer credential response

Direct exchange/refresh accepts exact tokenType: 'Bearer' or omission/undefined, normalizing omission only in explicit Bearer mode. DPoP, lowercase and other values reject. Peers must already carry exact normalized Bearer. Tokens must be nonempty visible ASCII without whitespace, controls or commas. Opaque tokens are supported; exactly three dot-separated segments are reserved for compact signed JWTs. Malformed candidates are not reinterpreted as opaque: canonical nonempty unpadded base64url, a nonempty signing alg other than none, no b64: false, and no present cnf claim (even null) are required. Optional JWT exp must be safe, nonnegative integer epoch seconds and clamps the deadline when present.

expiresIn, clock conversions/addition, user copying and body/cookie handle rules retain the bound profile's safe arithmetic. Zero lifetime retains a rotated handle but supplies no live API/peer token; nonlive use stops with nonterminal BEARER_ACCESS_TOKEN_EXPIRED, never a refresh loop. Cookie responses/peers have no sessionId, and Bearer peer envelopes have no jkt. Invalid direct responses are terminal INVALID_BEARER_CREDENTIAL_RESPONSE; invalid peers are advisory/ignored. This is contract decoding, not authentication. Each API must verify the token (JWT signature/claims or appropriate opaque validation) independently.

CORS

The backend must answer credentialed cross-origin browser calls:

| Setting | Value | | --------------- | ------------------------------------------------------------------------------- | | Origin | Echo the exact trusted frontend origin (never *) | | credentials | true | | Allowed headers | Content-Type, Authorization, DPoP, and the configured fingerprint header | | Exposed headers | DPoP-Nonce, WWW-Authenticate (the client reads nonce challenges from these) |

Vault Origin/Referer checks run independently of CORS. Cookie-authenticated refresh/logout require an Origin (or valid Referer) matching backendOrigin or trustedOrigins in every SameSite mode.

Nonce retry rule

This section's nonce behavior is DPoP only; Bearer ignores nonces entirely.

When nonces are enabled, a missing/expired nonce returns fixed OIDC_VAULT_USE_DPOP_NONCE: HTTP 400 at vault POSTs (login/exchange/refresh/logout), HTTP 401 with DPoP error="use_dpop_nonce" at protected APIs.

  • Vault POSTs allow one nonce retry when that code arrives on HTTP 400 or 401 with a valid DPoP-Nonce. A second nonce challenge throws DPOP_NONCE_RETRY_EXHAUSTED, requiresLogin: false, with its HTTP status. Existing auth/pending-login state is retained for explicit recovery; starting a new login() still performs its documented frontend reset. A first challenge with no usable nonce returns the fixed non-terminal OIDC_VAULT_USE_DPOP_NONCE error without a retry.
  • API calls allow one nonce retry only when their retry policy permits it (see Retry policy). Only an HTTP-401 DPoP error="invalid_token" challenge allows session.refresh() and a further attempt, at most once per invocation. An initial refresh for absent/expired credentials uses that same refresh budget. There are at most three API HTTP attempts: the original plus one nonce retry and one refresh retry. The final API response, including a repeated challenge, is returned to the caller.

Each permitted attempt mints a fresh proof/jti/signature with the current iat and API-only ath; vault proofs never carry ath. Replayed bodies keep their original snapshot. Generic 401s, proof errors, 403s, 503s, and network failures do not trigger API refresh or extra attempts.

Learning is independent of retry permission. Both helpers remember a valid nonce from the selected trusted response, including success and final error responses. An unsafe POST still makes exactly one attempt and returns its challenge; the next explicit invocation can send the learned nonce. Learning from a header never authorizes resubmission of the current mutation.

Nonce cache and challenge parsing

DpopNonceCache holds at most 64 (protection space, key thumbprint) tuples per instance. A successful remember renews that tuple's write order; insertion at capacity evicts the oldest remembered tuple. Reads do not promote entries, and rejected values neither replace an entry nor change eviction order. Vault mounts and API (origin, replayNamespace) spaces remain separate. API calls share a default cache through their session, even when a new context wrapper is passed each time; a supplied nonces cache uses the same limits and isolation.

Accepted nonce headers contain one opaque value of 1–512 visible ASCII characters, excluding whitespace, double quotes, backslashes, and commas. The client never trims, splits, unquotes, or decodes the exposed header value. Comma-containing values, including Fetch-coalesced duplicate fields (even identical ones), are rejected without overwriting a usable nonce. This is the OAuth nonce-character syntax restricted to an unambiguous single header value. There is no client-invented TTL: nonce expiry is determined by the server's next challenge, not by interpreting its private nonce format. Cache eviction can likewise require a new challenge.

The API WWW-Authenticate parser accepts auth-parameters in any order, token or quoted values, and other authentication schemes in the same field. Only one unambiguous active-scheme challenge can trigger recovery. Bearer errors never recover DPoP, or vice versa; quoted descriptions never supply an error. Duplicate parameter names (case-insensitive), multiple selected-scheme challenges, malformed/empty list members, or a field longer than 8,192 characters cause no refresh/retry. A valid nonce header can still be learned independently of that decision. Vault status/nonce fields are captured before body reads, so an injected response cannot change the recovery decision while its body is awaited.

Storage

| What | Where | Lifetime / scope | | ----------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | App-local access token (DPoP JWT or Bearer JWT/opaque) | Memory only (getAccessToken()), never persisted | Until expiresAt; closing every tab discards all tokens | | Body handle { sessionId, jkt } | sessionStorage, tab-local | Scoped key oidc-vault-dpop:handle:<scope>; do not copy across tabs | | Pending-login jkt marker | sessionStorage, survives the IdP navigation | Cleared at exchange; missing marker means fresh login required | | Bearer body handle / pending marker (mode: 'bearer', no jkt) | Separate sessionStorage keys | oidc-vault-bearer:handle:<scope> / oidc-vault-bearer:pending:<scope>; no migration of DPoP markers | | Cookie handle | Backend HttpOnly session cookie, never browser-readable | Backend session TTL (example: 8h absolute); no vault sid in the JWT payload | | DPoP private CryptoKey (non-extractable) + public JWK | IndexedDB object stores | Scope [frontendOrigin, backendOrigin, normalizedBasePath]; atomic first-key-wins across tabs | | Cookie coordination mode union + { generation, active, refreshedAt? } | IndexedDB, non-credential metadata only | DPoP has real jkt; Bearer has mode: 'bearer', no jkt; transient BroadcastChannel peer wait ≤180ms |

sessionStorage tab-local body handles must not be shared between tabs, and opener-cloned sessionStorage is not a shared-refresh strategy. No tokens or handles enter localStorage or IndexedDB. Crypto runs outside the readwrite transaction; export of the private key always fails by construction.

The historical database name oidc-vault-dpop-example-v1 and version-1 schema are retained so installed keys survive upgrades. Use resetKey() for scoped recovery rather than deleting the entire origin's database.

Cookie modes share one metadata row and the same historical cookie Web Lock, not separate per-mode locks. Admission checks mode, generation, expiry and current recognition, then rechecks metadata; only DPoP reads/verifies a key. Reload needs active same-mode metadata, never a blind refresh to discover cookie binding. Missing-mode historical metadata/messages mean DPoP only; unknown/corrupt modes are unusable. No key migration, fabricated thumbprint or Bearer key-store read occurs.

Fresh login can replace a cookie mode under that lock. Updated opposite-mode contexts invalidate checked old local state, never adopt the other mode's token or clear its successor metadata. Unmodified older tabs cannot understand this contract: their clear/reset/logout may damage a replacement session. Concurrent mixed-version/mixed-mode use of one backend cookie authority is unsupported. Upgrade/close/reload old tabs before switching and log in afresh. Independent concurrent modes need genuinely distinct backend cookie authorities. Coordination is limited to one frontend origin/storage partition/scope; issued stateless JWTs are not instantly revoked by mode replacement, clear or logout.

Key loss and errors

In DPoP mode, key loss or key change clears frontend auth and requires a fresh login — DPOP_KEY_LOST (requiresLogin: true). Only fresh login() may create a missing key; exchange/refresh/API/logout read the existing key and compare its binding (cnf.jkt decode check plus key-equality check). There is no Bearer fallback and no ephemeral-key fallback. Storage/crypto failures stop the operation; error handling never silently deletes or creates a key.

Explicit recovery from a corrupt key

An existing but unusable record (for example, a mismatched private/public pair) also fails validation during login(). Retrying login or calling clear() cannot repair it: clear deliberately keeps the key. Offer an explicit recovery action that calls resetKey() and awaits it before starting login:

import { createOidcVaultDpopSession } from '@web-ts-toolkit/oidc-vault-dpop-client';

const session = createOidcVaultDpopSession({
  backendOrigin: 'https://api.example.com',
  basePath: '/auth/oidc/body',
  sessionTransport: 'body',
});

// A user-invoked recovery button when the persisted browser key is unusable.
export async function recoverBrowserKey(): Promise<void> {
  await session.resetKey();
  await session.login('/callback?transport=body');
  // The redirect callback calls session.exchange(code), as in the quickstart.
}

Reset bypasses key validation and removes both scoped IndexedDB records in one guarded transaction. It leaves other vault mounts/backend origins and their installed keys/metadata intact. The next explicit login persists a fresh non-extractable key using the same atomic first-key-wins path across tabs. IndexedDB still has to be available; reset does not repair denied/unavailable browser storage. Recovery is never automatic on API, refresh, logout, proof, nonce, timeout, or recognition errors.

Reset is local-only recovery. Other sessions using the removed key need a fresh login; cookie peers are notified under the shared lock, and body tabs detect the lost/changed key on their next credential operation. The HttpOnly cookie is not removed, old server sessions remain until explicit revocation or expiry, and issued stateless JWTs are not revoked. If the key is still usable and server sign-out is wanted, call logout() before resetting it. An already-started API request, browser-applied cookie, server mutation, or previously obtained CryptoKey reference cannot be undone by local deletion. API requests remain caller-owned; use their AbortSignal for local cancellation.

Error classification

Package-generated OidcVaultDpopClientErrors carry a stable code, a fixed message (never keys, credentials, fingerprints, or URLs), requiresLogin, and an optional HTTP status. Treat requiresLogin === true as "route to sign-in"; enrolled recognition changes surface as OIDC_VAULT_FINGERPRINT_REAUTH_REQUIRED (clear auth, start fresh POST login, no automatic re-enrollment).

Vault JSON errors use an explicit code allowlist rather than treating every HTTP 401 as logout. These terminal server codes clear local auth and pending login, invalidate cookie coordination metadata, and require sign-in:

| Code | Meaning | | ---------------------------------------- | ------------------------------------------------------------------------- | | OIDC_VAULT_INVALID_SESSION | Session is missing, expired, or no longer usable. | | OIDC_VAULT_REFRESH_REJECTED | The current upstream refresh grant was confirmed rejected; sign in again. | | OIDC_VAULT_MISSING_SESSION_ID | The body handle or session cookie is missing (HTTP 400). | | OIDC_VAULT_MALFORMED_SESSION_COOKIE | The session cookie is malformed (HTTP 400). | | OIDC_VAULT_INVALID_EXCHANGE_CODE | The exchange code is invalid/expired (HTTP 400); begin a fresh login. | | OIDC_VAULT_INVALID_BROWSER_BINDING | The login transaction's browser-cookie binding failed. | | OIDC_VAULT_DEVICE_BINDING_REQUIRED | The session needs a device-bound login. | | OIDC_VAULT_FINGERPRINT_REAUTH_REQUIRED | Enrolled recognition changed or is absent. |

Proof/nonce errors (OIDC_VAULT_INVALID_DPOP_PROOF, OIDC_VAULT_DPOP_REQUIRED, OIDC_VAULT_USE_DPOP_NONCE) are non-terminal, even on HTTP 401. Replay-store unavailability, generic upstream/provider failures, and request/configuration failures also retain auth. An invalid recognition input (OIDC_VAULT_INVALID_FINGERPRINT) is non-terminal; it differs from a confirmed enrollment mismatch. Non-terminal does not promise that a retry will succeed or authorize one automatically; use the operation's recovery contract.

OIDC_VAULT_REFRESH_REJECTED is the narrow provider exception: a bounded valid OAuth invalid_grant rejection during refresh, not proof that time expiry caused it. Newer cookie generations or local publication/login intent supersede an old rejection with non-terminal DPOP_OPERATION_SUPERSEDED; failed advisory lookup retains auth. The server adds no cookie clear/lineage deletion for this error. Older servers still return generic OIDC_VAULT_TOKEN_REQUEST_FAILED; older clients sanitize the unknown new code as non-terminal. Keep explicit sign-in recovery and do not reinterpret every provider failure as logout.

Unknown codes, including object-prototype names, become fixed OIDC_REQUEST_FAILED / The OIDC request failed., requiresLogin: false; server codes/messages are never copied into that fallback. The HTTP status is retained. Local key loss, binding/token-type violations and invalid bound/Bearer credential responses remain terminal. API HTTP failures are still caller-owned Responses, with automatic recovery limited to the challenge rules above.

Construction can also throw TypeError for invalid options; caller abort rejects with signal.reason. Do not assume every thrown value is a package error or automatically start login for a non-terminal failure.

Credentials matrix

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) | | logoutAndNavigate POST (DPoP only) | 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 Authorization: DPoP <JWT> plus a fresh same-key proof with ath, or only Authorization: Bearer <app-local token> for an explicitly Bearer session.

Multiple services behind a gateway

Use DpopApi.pathPrefix to select each service's credential policy and backend replayNamespace on one public origin. Pass the full public URL, including the service path; pathPrefix selects the scope without adding or stripping a mount. Bootstrap the session with login/exchange or refresh as above.

import { createOidcVaultDpopSession, fetchWithDpop } from '@web-ts-toolkit/oidc-vault-dpop-client';
import type { DpopApi, DpopFetchContext } from '@web-ts-toolkit/oidc-vault-dpop-client';

const origin = 'https://gateway.example.com';
const session = createOidcVaultDpopSession({
  backendOrigin: origin,
  basePath: '/auth/oidc/body',
  sessionTransport: 'body',
});
const apis: readonly DpopApi[] = [
  { origin, pathPrefix: '/orders', replayNamespace: 'orders-api' },
  // This billing service also uses an application cookie.
  { origin, pathPrefix: '/billing', replayNamespace: 'billing-api', credentials: 'include' },
];
const gateway: DpopFetchContext = { session, apis };

export function loadOrders(): Promise<Response> {
  return fetchWithDpop(gateway, `${origin}/orders?limit=20`);
}

export function loadInvoices(): Promise<Response> {
  return fetchWithDpop(gateway, `${origin}/billing/invoices`);
}

Selection is case-sensitive at normalized path-segment boundaries: /orders matches /orders, /orders/, and /orders/42, but neither /orders-evil nor /orders%2Fevil. The longest matching prefix wins, regardless of array order. For example, /orders/admin takes precedence over /orders; /orders/admin-evil still uses /orders. Trailing prefix slashes are removed, so /orders/ and /orders define the same scope.

Omission and root are origin-wide. Leaving out pathPrefix preserves the existing whole-origin behavior. Explicit /, or a prefix that normalizes to /, also permits credentials on every path at that origin. A root entry is a fallback for paths outside more-specific entries. Without such a fallback, an unmatched path fails before access-token lookup, refresh, key lookup, signing, or network work.

Matching, the outbound pathname, and proof htu use the same normalization: unreserved percent escapes (A–Z, a–z, digits, -._~) decode, remaining escape hex digits uppercase, and dot segments collapse. Thus /ord%65rs is sent as /orders, and /orders/%2e%2e/billing can only use the billing scope (or an origin-wide fallback). Reserved escapes stay encoded: %2F, %5C, %3F, and %23 never become separators, a new authority, query, or fragment. Double-encoded escapes are not decoded again. Query order, duplicate query parameters, escaping, and fragment data are retained in the URL passed to fetch. HTTP omits the fragment; the proof omits both query and fragment. The same uppercase method is used for the proof and every outbound attempt.

Every invocation validates all entries, including nonmatching ones, before auth work. An origin must contain only scheme/host/port and an optional root slash, with HTTPS except for loopback development. A prefix must be an absolute path without a URL/// authority-like prefix, query, fragment, whitespace, backslash, control character, or malformed escape. replayNamespace must be 1–128 printable ASCII characters; credentials accepts only omit (default) or include. Duplicate normalized (origin, pathPrefix) scopes are rejected even if their policies are identical: this includes omission versus /, trailing slashes, equivalent unreserved escapes, and equivalent dot segments. Targets must already be absolute HTTP(S) URLs; configuring a prefix never makes a relative, userinfo-bearing, or malformed target usable.

The same scopes/normalization apply to BearerApi; only definitely-Bearer APIs may omit replayNamespace. If supplied it has the same validation, but is unused.

The target and selected origin/path/namespace/credentials are snapshotted before asynchronous auth work. All attempts and nonce learning for that invocation keep that snapshot, including across refresh/key waits. Caller configuration changes apply to later invocations. Nonces retain the existing ['api', normalizedOrigin, replayNamespace] + signing-key-thumbprint tuple: the two services above use independent nonce spaces, while paths deliberately using the same origin/namespace share a nonce space. Path selection leaves the nonce/refresh retry budgets and single-attempt mutation policy below intact.

| Failure | Fixed client code (requiresLogin: false) | | ---------------------------------------------------- | ------------------------------------------ | | No matching origin/path scope | DPOP_API_OUT_OF_SCOPE | | Invalid policy fields or duplicate normalized scopes | INVALID_DPOP_API_CONFIG | | Malformed URL, origin syntax, or prefix | INVALID_DPOP_TARGET | | Configured non-loopback HTTP origin | INSECURE_DPOP_ORIGIN |

Retry policy (fetchWithDpop)

Scoped fetch for the configured API origin/path subtrees: it owns Authorization/DPoP (caller-set auth headers throw DPOP_AUTH_HEADER_OVERRIDE), mints a fresh proof per DPoP attempt, and accepts only exact origin matches with a matching pathPrefix and valid mode-specific policy.

| Method | Default attempts | Opt-in | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | GET / HEAD / OPTIONS | Retry once on nonce challenge, refresh once on invalid_token | retry: 'never' disables retries | | Mutations (POST / PUT / DELETE / …) | Single attempt; a nonce challenge on an unsafe mutation is returned to the caller without implicit resubmission | retry: 'idempotent' only when the authorized operation owns a server-enforced idempotency contract |

In Bearer mode, only an unambiguous HTTP-401 Bearer invalid_token challenge permits response-driven refresh, and only when this retry policy permits replay. At most two API attempts and one shared refresh budget (including initial absent/expired-token acquisition); no nonce retry/learning. Generic 401, DPoP errors, insufficient scope, malformed/ambiguous/oversized challenges, 403/5xx and network failures authorize no extra attempt. The final API response is returned to the caller. retry: 'never' and unsafe mutation defaults remain single-attempt.

Retry-enabled bodies must be replayable: strings, URLSearchParams, Blob, FormData, ArrayBuffer, and views are snapshotted; streams throw `DPOP_BODY_NOT_REPLAYA