feat: pin the providers' own OIDC requests to a caller-supplied fetch (fixes the global-fetch-patch login deadlock)

[jeswr]

DRAFT for maintainer discussion — a lesson learned (the hard way, several times) across @jeswr's Solid app suite, contributed back here. Happy to reshape the API to your taste.

The problem: an OIDC re-entrancy deadlock that hangs login

The token providers perform their own network requests — discovery, dynamic client registration, and the token grant — through oauth4webapi, which defaults to globalThis.fetch.

When an application patches the global fetch with an authenticating wrapper (this library's own ReactiveFetchManager.registerGlobally(), or an app-side wrapper that single-flights concurrent requests onto one shared authentication attempt — a very common pattern to avoid N parallel 401s spawning N login popups), the provider's OIDC requests re-enter that wrapper mid-upgrade. A single-flighting wrapper then awaits the very authentication attempt those requests are serving — a circular await that hangs login before the authorization popup/redirect ever opens. No error, no popup, nothing: the discovery request is parked on the login promise that issued it.

Deterministic repro (against this repo's main)

import { DPoPTokenProvider } from "./dist/DPoPTokenProvider.js"

// an app-installed single-flighting wrapper: mid-login, requests through it
// await the in-flight authentication attempt — i.e. they never resolve
globalThis.fetch = () => new Promise(() => {})

const provider = new DPoPTokenProvider("https://app.example/cb", async u => `${u}?code=x`, async () => new URL("https://op.example"))
await provider.upgrade(new Request("https://pod.example/x")) // hangs forever at oauth.discoveryRequest

The fix: let the caller pin the providers' OIDC hops to a pristine fetch

This PR adds an optional trailing options argument to DPoPTokenProvider, BearerTokenProvider and ClientCredentialsTokenProvider:

const pristineFetch = globalThis.fetch.bind(globalThis) // capture BEFORE patching

const provider = new DPoPTokenProvider(callbackUri, getCode, getIssuer, {fetch: pristineFetch})
const manager = new ReactiveFetchManager([provider])
manager.registerGlobally()

TokenProviderOptions.fetch is threaded into oauth4webapi via its customFetch request option (a small shared customFetchOption adapter bridges oauth4webapi's CustomFetchOptions to the Fetch API signature under exactOptionalPropertyTypes). Defaults are unchanged: with no options, the providers keep resolving globalThis.fetch at call time, exactly as today.

Tests

test/DPoPTokenProvider.customFetch.test.ts (runs via the added npm test script — build, then node --test against dist/, so it exercises the shipped artifact):

1. The regression test: a full DPoP auth-code login (discovery → registration → PKCE → token grant, through real oauth4webapi against an in-process mock OP) resolves while globalThis.fetch is patched with a never-resolving wrapper — and asserts the patched global was called zero times.
2. Same for the client-credentials flow.
3. Backwards compatibility: without options, the provider still rides globalThis.fetch.

Without the fix, test 1 hangs (verified against main).

Notes for discussion

• An alternative/complementary shape: ReactiveFetchManager already captures the pre-patch fetch (#globalFetch) — it could pass it down to providers automatically. That needs a TokenProvider interface change (e.g. upgrade(request, context)), so I kept this PR to the least-invasive opt-in seam; happy to explore the manager-driven variant if you prefer it.
• The npm test script is new on main (draft fix: allow http loopback issuers in the DPoP auth-code flow #18 adds a similar one); trivial to reconcile whichever lands first.
• Related suite lesson, out of scope here since this library doesn't own logout/session state: a logout path should surface a credential-revoke failure distinctly from best-effort cache cleanup, rather than presenting a failed revoke as a clean sign-out. Noting it for whenever session persistence lands (cf. draft feat: per-issuer session cache — stop re-running the full auth flow (popup included) on every 401 #11/feat: refresh-token support — renew expired sessions without user interaction #12).

---

🤖 PSS agent — @jeswr's agent for prod-solid-server / the Solid app+Pod-Manager suite