@udibo/oauth2 0.6.0 → 0.8.0

package/esm/_dnt.polyfills.d.ts

@@ -15,3 +15,17 @@ declare global {
     }
 }
 export {};
+declare global {
+    interface PromiseConstructor {
+        /**
+         * Creates a Promise that can be resolved or rejected using provided functions.
+         * @returns An object containing `promise` promise object, `resolve` and `reject` functions.
+         */
+        withResolvers<T>(): {
+            promise: Promise<T>;
+            resolve: (value: T | PromiseLike<T>) => void;
+            reject: (reason?: any) => void;
+        };
+    }
+}
+export {};

package/esm/_dnt.polyfills.js

@@ -12,4 +12,15 @@ if (!Object.hasOwn) {
         writable: true,
     });
 }
+// https://github.com/tc39/proposal-promise-with-resolvers/blob/3a78801e073e99217dbeb2c43ba7212f3bdc8b83/polyfills.js#L1C1-L9C2
+if (Promise.withResolvers === undefined) {
+    Promise.withResolvers = () => {
+        const out = {};
+        out.promise = new Promise((resolve_, reject_) => {
+            out.resolve = resolve_;
+            out.reject = reject_;
+        });
+        return out;
+    };
+}
 export {};

package/esm/adapters/hono/bff/bff.d.ts

@@ -49,7 +49,7 @@
  */
 import { Hono } from "hono";
 import type { Context, Handler, MiddlewareHandler } from "hono";
-import type { DirectClient, TokenBundle, UserInfoClaims } from "../../../client/mod.js";
+import type { DirectClient, SessionState, TokenBundle, UserInfoClaims } from "../../../client/mod.js";
 import type { ClientInterface } from "../../../models/client.js";
 import type { AbstractScope, BasicScope } from "../../../models/scope.js";
 import type { HonoAuthorizationServer } from "../authorization-server.js";
@@ -260,6 +260,23 @@ export interface HonoBffBackchannelOptions {
      * `{ sub, sid }` to log out. Throw or return `null` to reject the request.
      */
     verifyLogoutToken: (logoutToken: string) => Promise<BackchannelLogoutSubject | null> | BackchannelLogoutSubject | null;
+    /**
+     * The largest request body, in bytes, the receiver reads. The body is read
+     * before the `logout_token` is verified, so the cap bounds what an
+     * anonymous caller can make the BFF buffer. Bytes are counted as they
+     * arrive, so a chunked body or a `Content-Length` that understates the body
+     * cannot get past it. A larger body is refused with `400 invalid_request` —
+     * the status OIDC Back-Channel Logout 1.0 §2.8 requires for a failed
+     * request — without calling
+     * {@linkcode HonoBffBackchannelOptions.verifyLogoutToken}.
+     *
+     * The default is far above a `logout_token`, a JWT of a few KiB. When an
+     * earlier middleware has already read the body, the receiver uses Hono's
+     * parsed copy and the cap does not apply; bound the body in that middleware.
+     *
+     * @default 65536
+     */
+    maxBodyBytes?: number;
 }
 /**
  * Why `/auth/callback` could not complete a sign-in. Passed to
@@ -609,7 +626,9 @@ export declare class HonoBff {
      * {@linkcode HonoBffPaths.basePath}, when the session cookie would die
      * before the session behind it (see
      * {@linkcode HonoBffOptions.sessionMaxAgeMs}), when `sessionMaxAgeMs` or a
-     * numeric `cookie.maxAge` is not positive or exceeds 400 days, or when
+     * numeric `cookie.maxAge` is not positive or exceeds 400 days, when
+     * {@linkcode HonoBffBackchannelOptions.maxBodyBytes} is not a positive
+     * integer (a `RangeError`), or when
      * {@linkcode HonoBffOptions.extraParams} or
      * {@linkcode HonoBffOptions.forwardedParams} names a reserved authorize
      * parameter, gives one a name that is empty or not equal to its trimmed
@@ -712,12 +731,56 @@ export declare class HonoBff {
      * `logoutUrl` when signed in. Never returns tokens.
      */
     sessionHandler(): Handler;
+    /**
+     * Who is signed in on this request, for a server that renders pages: the
+     * answer `GET /auth/session` gives the browser, read without a round trip to
+     * it. Seed the React provider's `initialState` with it so a signed-in page
+     * renders signed in on the first paint.
+     *
+     * A session counts exactly when the probe would count it. In `sessionMode:
+     * "own"`, a session older than `sessionMaxAgeMs` is destroyed and its cookie
+     * cleared on this response, just as the probe does. Shared mode leaves
+     * lifetime enforcement to the application and its session store.
+     * It never returns a token, and it does
+     * not refresh one: `sessionExpiresIn` is `0` once the access token has
+     * expired, and the next `attachToken` or `protect` refreshes it when the
+     * session holds a refresh token.
+     *
+     * It skips the CSRF header check, because the answer goes to your server,
+     * not to a page that could read it cross-site. Call it only on the server.
+     * It sets no caching policy. A response built from its answer is one
+     * person's, so send it with a private or `no-store` `Cache-Control`.
+     *
+     * @param c The request's Hono context. The session cookie is read from it.
+     * @returns The same fields as `BffClient.getSession()`. Signed out,
+     * `user`, `sessionExpiresIn` and `logoutUrl` are all `null`.
+     *
+     * @example Seed the React provider from a server-rendered page
+     * ```ts
+     * import { Hono } from "hono";
+     * import type { SessionState } from "@udibo/oauth2/client";
+     * import type { HonoBff } from "@udibo/oauth2/hono/bff";
+     *
+     * declare const bff: HonoBff;
+     * declare function renderPage(initialState: SessionState): string;
+     *
+     * const app = new Hono();
+     * app.route("/auth", bff.routes());
+     * app.get("/", async (c) => {
+     *   c.header("Cache-Control", "private, no-store");
+     *   return c.html(renderPage(await bff.readSession(c)));
+     * });
+     * ```
+     */
+    readSession(c: Context): Promise<SessionState>;
     /**
      * OIDC Back-Channel Logout receiver. A server-to-server `POST` from the OP
      * carrying a signed `logout_token`; the configured verifier validates it (and
      * returns the subject / OP session id), then the matching server-side
      * session(s) are destroyed. Responds `200` on success and `400` on a
-     * missing/invalid token, with `Cache-Control: no-store`, per the spec.
+     * missing/invalid token or a body over
+     * {@linkcode HonoBffBackchannelOptions.maxBodyBytes}, with
+     * `Cache-Control: no-store`, per the spec.
      */
     backchannelHandler(): Handler;
     /**

package/esm/adapters/hono/bff/bff.js

@@ -49,6 +49,7 @@
  */
 import { Hono } from "hono";
 import { deleteCookie, getCookie, setCookie } from "hono/cookie";
+import { assertMaxBodyBytes, DEFAULT_MAX_BODY_BYTES, readBoundedBody, } from "../../../utils/_body.js";
 import { InvalidRequestError, InvalidTokenError, isOAuth2Error, TemporarilyUnavailableError, } from "../../../errors.js";
 import { timingSafeMatchIndex } from "../../../utils/_timing-safe.js";
 import { sha256Hash } from "../../../server/utils/hash.js";
@@ -303,7 +304,9 @@ export class HonoBff {
      * {@linkcode HonoBffPaths.basePath}, when the session cookie would die
      * before the session behind it (see
      * {@linkcode HonoBffOptions.sessionMaxAgeMs}), when `sessionMaxAgeMs` or a
-     * numeric `cookie.maxAge` is not positive or exceeds 400 days, or when
+     * numeric `cookie.maxAge` is not positive or exceeds 400 days, when
+     * {@linkcode HonoBffBackchannelOptions.maxBodyBytes} is not a positive
+     * integer (a `RangeError`), or when
      * {@linkcode HonoBffOptions.extraParams} or
      * {@linkcode HonoBffOptions.forwardedParams} names a reserved authorize
      * parameter, gives one a name that is empty or not equal to its trimmed
@@ -363,6 +366,9 @@ export class HonoBff {
                 }
             }
         }
+        if (options.backchannelLogout?.maxBodyBytes !== undefined) {
+            assertMaxBodyBytes(options.backchannelLogout.maxBodyBytes, "backchannelLogout.maxBodyBytes");
+        }
         if (options.backchannelLogout && !supportsBackchannelLogout(this.#store)) {
             throw new Error("backchannelLogout requires a SessionStore that implements " +
                 "destroyByLogout() (a stateful store). The stateless " +
@@ -758,16 +764,74 @@ export class HonoBff {
             if (!data) {
                 return c.json({ isAuthenticated: false, user: null });
             }
-            const expiresAt = data.tokens.accessTokenExpiresAt;
-            const sessionExpiresIn = expiresAt !== undefined
+            return c.json(this.#signedInState(data));
+        };
+    }
+    /**
+     * Who is signed in on this request, for a server that renders pages: the
+     * answer `GET /auth/session` gives the browser, read without a round trip to
+     * it. Seed the React provider's `initialState` with it so a signed-in page
+     * renders signed in on the first paint.
+     *
+     * A session counts exactly when the probe would count it. In `sessionMode:
+     * "own"`, a session older than `sessionMaxAgeMs` is destroyed and its cookie
+     * cleared on this response, just as the probe does. Shared mode leaves
+     * lifetime enforcement to the application and its session store.
+     * It never returns a token, and it does
+     * not refresh one: `sessionExpiresIn` is `0` once the access token has
+     * expired, and the next `attachToken` or `protect` refreshes it when the
+     * session holds a refresh token.
+     *
+     * It skips the CSRF header check, because the answer goes to your server,
+     * not to a page that could read it cross-site. Call it only on the server.
+     * It sets no caching policy. A response built from its answer is one
+     * person's, so send it with a private or `no-store` `Cache-Control`.
+     *
+     * @param c The request's Hono context. The session cookie is read from it.
+     * @returns The same fields as `BffClient.getSession()`. Signed out,
+     * `user`, `sessionExpiresIn` and `logoutUrl` are all `null`.
+     *
+     * @example Seed the React provider from a server-rendered page
+     * ```ts
+     * import { Hono } from "hono";
+     * import type { SessionState } from "@udibo/oauth2/client";
+     * import type { HonoBff } from "@udibo/oauth2/hono/bff";
+     *
+     * declare const bff: HonoBff;
+     * declare function renderPage(initialState: SessionState): string;
+     *
+     * const app = new Hono();
+     * app.route("/auth", bff.routes());
+     * app.get("/", async (c) => {
+     *   c.header("Cache-Control", "private, no-store");
+     *   return c.html(renderPage(await bff.readSession(c)));
+     * });
+     * ```
+     */
+    async readSession(c) {
+        const cookieValue = getCookie(c, this.#cookieName);
+        const data = cookieValue
+            ? await this.#readLiveSession(c, cookieValue)
+            : null;
+        if (!data) {
+            return {
+                isAuthenticated: false,
+                user: null,
+                sessionExpiresIn: null,
+                logoutUrl: null,
+            };
+        }
+        return this.#signedInState(data);
+    }
+    #signedInState(data) {
+        const expiresAt = data.tokens.accessTokenExpiresAt;
+        return {
+            isAuthenticated: true,
+            user: data.user ?? null,
+            sessionExpiresIn: expiresAt !== undefined
                 ? Math.max(0, Math.round((expiresAt - Date.now()) / 1000))
-                : null;
-            return c.json({
-                isAuthenticated: true,
-                user: data.user ?? null,
-                sessionExpiresIn,
-                logoutUrl: this.#paths.logout,
-            });
+                : null,
+            logoutUrl: this.#paths.logout,
         };
     }
     /**
@@ -775,7 +839,9 @@ export class HonoBff {
      * carrying a signed `logout_token`; the configured verifier validates it (and
      * returns the subject / OP session id), then the matching server-side
      * session(s) are destroyed. Responds `200` on success and `400` on a
-     * missing/invalid token, with `Cache-Control: no-store`, per the spec.
+     * missing/invalid token or a body over
+     * {@linkcode HonoBffBackchannelOptions.maxBodyBytes}, with
+     * `Cache-Control: no-store`, per the spec.
      */
     backchannelHandler() {
         return async (c) => {
@@ -785,7 +851,16 @@ export class HonoBff {
                 return c.json({ error: "not_supported" }, 400);
             let logoutToken;
             try {
-                logoutToken = (await c.req.formData()).get("logout_token")?.toString();
+                const form = c.req.raw.bodyUsed
+                    ? await c.req.formData()
+                    : await this.#readBackchannelForm(c, opts);
+                if (!form) {
+                    return c.json({
+                        error: "invalid_request",
+                        error_description: "request body is too large",
+                    }, 400);
+                }
+                logoutToken = form.get("logout_token")?.toString();
             }
             catch {
                 logoutToken = undefined;
@@ -816,6 +891,14 @@ export class HonoBff {
             return c.body(null, 200);
         };
     }
+    async #readBackchannelForm(c, opts) {
+        const bytes = await readBoundedBody(c.req.raw, opts.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES);
+        if (!bytes)
+            return null;
+        return await new Response(bytes, {
+            headers: { "content-type": c.req.header("content-type") ?? "" },
+        }).formData();
+    }
     async #resolveSessionEntry(c) {
         const cookieValue = getCookie(c, this.#cookieName);
         if (!cookieValue)

package/esm/client/_http.d.ts

@@ -32,8 +32,11 @@ export type RedirectPolicy = "refuse" | "follow";
  * @param what The endpoint's name, for error messages.
  * @param options `redirect` policy and `timeoutMs` deadline.
  * @returns The response, which may still be a non-OK status.
- * @throws {ServerError} when the request cannot be made, times out, or (under
- * `"refuse"`) answers with a redirect.
+ * @throws {TemporarilyUnavailableError} when the request cannot be made or its
+ * response headers do not arrive before the deadline; `cause` is the
+ * transport failure.
+ * @throws {ServerError} when (under `"refuse"`) the endpoint answers with a
+ * redirect.
  */
 export declare function sendGuarded(fetchImpl: typeof fetch, url: string, init: RequestInit, what: Endpoint, options?: {
     redirect?: RedirectPolicy;

package/esm/client/_http.js

@@ -47,8 +47,11 @@ const ERROR_CLASS_BY_CODE = {
  * @param what The endpoint's name, for error messages.
  * @param options `redirect` policy and `timeoutMs` deadline.
  * @returns The response, which may still be a non-OK status.
- * @throws {ServerError} when the request cannot be made, times out, or (under
- * `"refuse"`) answers with a redirect.
+ * @throws {TemporarilyUnavailableError} when the request cannot be made or its
+ * response headers do not arrive before the deadline; `cause` is the
+ * transport failure.
+ * @throws {ServerError} when (under `"refuse"`) the endpoint answers with a
+ * redirect.
  */
 export async function sendGuarded(fetchImpl, url, init, what, options = {}) {
     const redirect = options.redirect ?? "refuse";
@@ -62,7 +65,7 @@ export async function sendGuarded(fetchImpl, url, init, what, options = {}) {
         });
     }
     catch (error) {
-        throw new ServerError(`could not reach the ${what} (${describeError(error)})`, { cause: error });
+        throw new TemporarilyUnavailableError(`could not reach the ${what} (${describeError(error)})`, { cause: error });
     }
     if (redirect === "refuse" && res.status >= 300 && res.status < 400) {
         await res.body?.cancel();

package/esm/client/check.js

@@ -74,38 +74,17 @@ const CHECK_ENDPOINT = "check endpoint";
  * ```
  */
 export async function checkPermissions(options) {
-    const fetchImpl = options.fetch ?? fetch;
-    const reportUnreachable = async (input, init) => {
-        try {
-            return await fetchImpl(input, init);
-        }
-        catch (cause) {
-            throw new TemporarilyUnavailableError("check endpoint unreachable", {
-                cause,
-            });
-        }
-    };
-    let response;
-    try {
-        response = await sendGuarded(reportUnreachable, options.endpoint, {
-            method: "POST",
-            headers: {
-                authorization: `Bearer ${options.accessToken}`,
-                "content-type": "application/json",
-            },
-            body: JSON.stringify({
-                permissions: options.permissions,
-                ...(options.resource ? { resource: options.resource } : {}),
-            }),
-        }, CHECK_ENDPOINT);
-    }
-    catch (error) {
-        if (error instanceof Error &&
-            error.cause instanceof TemporarilyUnavailableError) {
-            throw error.cause;
-        }
-        throw error;
-    }
+    const response = await sendGuarded(options.fetch ?? fetch, options.endpoint, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${options.accessToken}`,
+            "content-type": "application/json",
+        },
+        body: JSON.stringify({
+            permissions: options.permissions,
+            ...(options.resource ? { resource: options.resource } : {}),
+        }),
+    }, CHECK_ENDPOINT);
     if (response.status >= 500) {
         await response.body?.cancel();
         throw new TemporarilyUnavailableError(`check endpoint answered ${response.status}`);

package/esm/client/direct-client.d.ts

@@ -290,9 +290,13 @@ export declare class DirectClient extends OAuth2ClientBase {
      * @returns The server's metadata document.
      * @throws {Error} when the client was configured with explicit `endpoints`
      * rather than an `issuer` — there is nothing to discover.
+     * @throws {TemporarilyUnavailableError} the last attempt's error when both
+     * well-known paths fail because the server cannot be reached or its
+     * response does not arrive in full before the deadline; `cause` is the
+     * transport failure.
      * @throws {OAuth2Error} the last attempt's error when both well-known paths
-     * fail: the server is unreachable, answers non-OK or with something other
-     * than a JSON object, or reports an `issuer` other than the configured one.
+     * fail otherwise: the server answers non-OK or with something other than a
+     * JSON object, or reports an `issuer` other than the configured one.
      *
      * @example
      * ```ts
@@ -377,6 +381,9 @@ export declare class DirectClient extends OAuth2ClientBase {
      *
      * @param input The callback URL, its query string, or the parsed params.
      * @returns The persisted tokens and the `returnTo` recorded at login.
+     * @throws {TemporarilyUnavailableError} when the token endpoint cannot be
+     * reached or its response does not arrive in full before the deadline;
+     * `cause` is the transport failure.
      * @throws {OAuth2Error} when the callback carries `?error=…`, or the token
      * exchange fails.
      * @throws {TypeError} when `code` or `state` is missing.
@@ -422,6 +429,9 @@ export declare class DirectClient extends OAuth2ClientBase {
      * `returnTo`, plus the raw response.
      * @throws {InvalidGrantError} when `state` is unknown or older than
      * `authRequestTtlMs`.
+     * @throws {TemporarilyUnavailableError} when the token endpoint cannot be
+     * reached or its response does not arrive in full before the deadline;
+     * `cause` is the transport failure.
      */
     exchangeAuthorizationCode(code: string, state: string, options?: ExchangeOptions): Promise<ExchangeResult>;
     /**
@@ -440,6 +450,9 @@ export declare class DirectClient extends OAuth2ClientBase {
      *
      * @param refreshToken The refresh token to redeem.
      * @returns The new tokens, the rotated refresh token, and the raw response.
+     * @throws {TemporarilyUnavailableError} when the token endpoint cannot be
+     * reached or its response does not arrive in full before the deadline;
+     * `cause` is the transport failure.
      * @throws {OAuth2Error} when the token endpoint rejects the grant.
      */
     exchangeRefreshToken(refreshToken: string): Promise<ExchangeResult>;
@@ -451,6 +464,9 @@ export declare class DirectClient extends OAuth2ClientBase {
      * @returns The persisted token bundle.
      * @throws {Error} when the client has no `clientSecret` — RFC 6749 §4.4
      * restricts this grant to confidential clients.
+     * @throws {TemporarilyUnavailableError} when the token endpoint cannot be
+     * reached or its response does not arrive in full before the deadline;
+     * `cause` is the transport failure.
      * @throws {OAuth2Error} when the token endpoint rejects the grant.
      *
      * @example
@@ -491,6 +507,11 @@ export declare class DirectClient extends OAuth2ClientBase {
      * one is dead.
      * @throws {Error} whatever the configured `RefreshTokenStorage` threw when
      * the read itself failed.
+     * @throws {TemporarilyUnavailableError} when the token endpoint cannot be
+     * reached or its response does not arrive in full before the deadline;
+     * `cause` is the transport failure.
+     * @throws {OAuth2Error} when the token endpoint rejects the refresh for
+     * another reason.
      */
     refresh(): Promise<string>;
     /**
@@ -502,6 +523,9 @@ export declare class DirectClient extends OAuth2ClientBase {
      * @returns The server's device authorization response.
      * @throws {Error} when no device authorization endpoint is configured or
      * discoverable.
+     * @throws {TemporarilyUnavailableError} when the device authorization
+     * endpoint cannot be reached or its response does not arrive in full before
+     * the deadline; `cause` is the transport failure.
      * @throws {OAuth2Error} when the server rejects the request.
      *
      * @example
@@ -534,6 +558,9 @@ export declare class DirectClient extends OAuth2ClientBase {
      * @throws {InvalidGrantError} when `expiresAt` passes before approval. A
      * server that reports the code expired first throws `ExpiredTokenError`
      * instead.
+     * @throws {TemporarilyUnavailableError} when the token endpoint cannot be
+     * reached or its response does not arrive in full before the deadline;
+     * `cause` is the transport failure. Polling stops on it.
      * @throws {OAuth2Error} on any other terminal error from the server.
      */
     pollDeviceToken(deviceCode: string, options?: PollDeviceTokenOptions): Promise<TokenBundle>;
@@ -547,6 +574,9 @@ export declare class DirectClient extends OAuth2ClientBase {
      * @returns The introspection response; check `active`.
      * @throws {Error} when the client has no `clientSecret` — RFC 7662 requires
      * an authenticated caller.
+     * @throws {TemporarilyUnavailableError} when the introspection endpoint
+     * cannot be reached or its response does not arrive in full before the
+     * deadline; `cause` is the transport failure.
      * @throws {OAuth2Error} when the endpoint rejects the request.
      */
     introspect(token: string, options?: {
@@ -560,6 +590,9 @@ export declare class DirectClient extends OAuth2ClientBase {
      * @param options `tokenTypeHint` tells the server which kind to look up
      * first.
      * @throws {Error} when no revocation endpoint is configured or discoverable.
+     * @throws {TemporarilyUnavailableError} when the revocation endpoint cannot
+     * be reached or its response does not arrive in full before the deadline;
+     * `cause` is the transport failure.
      * @throws {OAuth2Error} when the endpoint rejects the request.
      */
     revoke(token: string, options?: {
@@ -573,6 +606,9 @@ export declare class DirectClient extends OAuth2ClientBase {
      * @throws {Error} when no userinfo endpoint is configured or discoverable.
      * @throws {InvalidGrantError} when no usable token is stored and there is no
      * refresh token to mint one.
+     * @throws {TemporarilyUnavailableError} when the token or userinfo endpoint
+     * cannot be reached or its response does not arrive in full before the
+     * deadline; `cause` is the transport failure.
      * @throws {OAuth2Error} when the refresh or the userinfo endpoint fails.
      */
     getUserInfo(): Promise<UserInfoClaims>;
@@ -721,6 +757,9 @@ export declare class DirectClient extends OAuth2ClientBase {
      * than 30 seconds left, otherwise a freshly refreshed one.
      * @throws {InvalidGrantError} when a refresh is needed and no refresh token
      * is stored, or the stored one is dead.
+     * @throws {TemporarilyUnavailableError} when the token endpoint cannot be
+     * reached or its response does not arrive in full before the deadline;
+     * `cause` is the transport failure.
      * @throws {OAuth2Error} when a needed refresh fails for another reason.
      */
     getAccessToken(): Promise<string>;

package/esm/client/direct-client.js

@@ -159,9 +159,13 @@ export class DirectClient extends OAuth2ClientBase {
      * @returns The server's metadata document.
      * @throws {Error} when the client was configured with explicit `endpoints`
      * rather than an `issuer` — there is nothing to discover.
+     * @throws {TemporarilyUnavailableError} the last attempt's error when both
+     * well-known paths fail because the server cannot be reached or its
+     * response does not arrive in full before the deadline; `cause` is the
+     * transport failure.
      * @throws {OAuth2Error} the last attempt's error when both well-known paths
-     * fail: the server is unreachable, answers non-OK or with something other
-     * than a JSON object, or reports an `issuer` other than the configured one.
+     * fail otherwise: the server answers non-OK or with something other than a
+     * JSON object, or reports an `issuer` other than the configured one.
      *
      * @example
      * ```ts
@@ -368,6 +372,9 @@ export class DirectClient extends OAuth2ClientBase {
      *
      * @param input The callback URL, its query string, or the parsed params.
      * @returns The persisted tokens and the `returnTo` recorded at login.
+     * @throws {TemporarilyUnavailableError} when the token endpoint cannot be
+     * reached or its response does not arrive in full before the deadline;
+     * `cause` is the transport failure.
      * @throws {OAuth2Error} when the callback carries `?error=…`, or the token
      * exchange fails.
      * @throws {TypeError} when `code` or `state` is missing.
@@ -451,6 +458,9 @@ export class DirectClient extends OAuth2ClientBase {
      * `returnTo`, plus the raw response.
      * @throws {InvalidGrantError} when `state` is unknown or older than
      * `authRequestTtlMs`.
+     * @throws {TemporarilyUnavailableError} when the token endpoint cannot be
+     * reached or its response does not arrive in full before the deadline;
+     * `cause` is the transport failure.
      */
     async exchangeAuthorizationCode(code, state, options = {}) {
         const authRequestStorage = options.authRequestStorage ??
@@ -494,6 +504,9 @@ export class DirectClient extends OAuth2ClientBase {
      *
      * @param refreshToken The refresh token to redeem.
      * @returns The new tokens, the rotated refresh token, and the raw response.
+     * @throws {TemporarilyUnavailableError} when the token endpoint cannot be
+     * reached or its response does not arrive in full before the deadline;
+     * `cause` is the transport failure.
      * @throws {OAuth2Error} when the token endpoint rejects the grant.
      */
     async exchangeRefreshToken(refreshToken) {
@@ -515,6 +528,9 @@ export class DirectClient extends OAuth2ClientBase {
      * @returns The persisted token bundle.
      * @throws {Error} when the client has no `clientSecret` — RFC 6749 §4.4
      * restricts this grant to confidential clients.
+     * @throws {TemporarilyUnavailableError} when the token endpoint cannot be
+     * reached or its response does not arrive in full before the deadline;
+     * `cause` is the transport failure.
      * @throws {OAuth2Error} when the token endpoint rejects the grant.
      *
      * @example
@@ -566,6 +582,11 @@ export class DirectClient extends OAuth2ClientBase {
      * one is dead.
      * @throws {Error} whatever the configured `RefreshTokenStorage` threw when
      * the read itself failed.
+     * @throws {TemporarilyUnavailableError} when the token endpoint cannot be
+     * reached or its response does not arrive in full before the deadline;
+     * `cause` is the transport failure.
+     * @throws {OAuth2Error} when the token endpoint rejects the refresh for
+     * another reason.
      */
     refresh() {
         return this.#sharedRefresh(true);
@@ -642,6 +663,9 @@ export class DirectClient extends OAuth2ClientBase {
      * @returns The server's device authorization response.
      * @throws {Error} when no device authorization endpoint is configured or
      * discoverable.
+     * @throws {TemporarilyUnavailableError} when the device authorization
+     * endpoint cannot be reached or its response does not arrive in full before
+     * the deadline; `cause` is the transport failure.
      * @throws {OAuth2Error} when the server rejects the request.
      *
      * @example
@@ -687,6 +711,9 @@ export class DirectClient extends OAuth2ClientBase {
      * @throws {InvalidGrantError} when `expiresAt` passes before approval. A
      * server that reports the code expired first throws `ExpiredTokenError`
      * instead.
+     * @throws {TemporarilyUnavailableError} when the token endpoint cannot be
+     * reached or its response does not arrive in full before the deadline;
+     * `cause` is the transport failure. Polling stops on it.
      * @throws {OAuth2Error} on any other terminal error from the server.
      */
     async pollDeviceToken(deviceCode, options = {}) {
@@ -734,6 +761,9 @@ export class DirectClient extends OAuth2ClientBase {
      * @returns The introspection response; check `active`.
      * @throws {Error} when the client has no `clientSecret` — RFC 7662 requires
      * an authenticated caller.
+     * @throws {TemporarilyUnavailableError} when the introspection endpoint
+     * cannot be reached or its response does not arrive in full before the
+     * deadline; `cause` is the transport failure.
      * @throws {OAuth2Error} when the endpoint rejects the request.
      */
     async introspect(token, options = {}) {
@@ -760,6 +790,9 @@ export class DirectClient extends OAuth2ClientBase {
      * @param options `tokenTypeHint` tells the server which kind to look up
      * first.
      * @throws {Error} when no revocation endpoint is configured or discoverable.
+     * @throws {TemporarilyUnavailableError} when the revocation endpoint cannot
+     * be reached or its response does not arrive in full before the deadline;
+     * `cause` is the transport failure.
      * @throws {OAuth2Error} when the endpoint rejects the request.
      */
     async revoke(token, options = {}) {
@@ -785,6 +818,9 @@ export class DirectClient extends OAuth2ClientBase {
      * @throws {Error} when no userinfo endpoint is configured or discoverable.
      * @throws {InvalidGrantError} when no usable token is stored and there is no
      * refresh token to mint one.
+     * @throws {TemporarilyUnavailableError} when the token or userinfo endpoint
+     * cannot be reached or its response does not arrive in full before the
+     * deadline; `cause` is the transport failure.
      * @throws {OAuth2Error} when the refresh or the userinfo endpoint fails.
      */
     async getUserInfo() {
@@ -1053,6 +1089,9 @@ export class DirectClient extends OAuth2ClientBase {
      * than 30 seconds left, otherwise a freshly refreshed one.
      * @throws {InvalidGrantError} when a refresh is needed and no refresh token
      * is stored, or the stored one is dead.
+     * @throws {TemporarilyUnavailableError} when the token endpoint cannot be
+     * reached or its response does not arrive in full before the deadline;
+     * `cause` is the transport failure.
      * @throws {OAuth2Error} when a needed refresh fails for another reason.
      */
     async getAccessToken() {

package/esm/client/storage.d.ts

@@ -95,7 +95,14 @@ export interface AuthRequestStorage {
     take?(state: string): Promise<AuthRequestRecord | null> | AuthRequestRecord | null;
     /** Removes one entry — a claimed or stale one. */
     delete(state: string): Promise<void> | void;
-    /** Removes every entry. Called when the client clears its session. */
+    /**
+     * Removes every entry. `DirectClient` calls it whenever it clears its
+     * session — on sign-out, and when a refresh finds the grant dead. A store
+     * shared between users may scope it instead, removing only expired records,
+     * so that one user's sign-out does not cancel another user's sign-in still
+     * in progress; register such a store with the contract suite's
+     * `clear: "scoped"`.
+     */
     clear(): Promise<void> | void;
 }
 /** Default in-memory {@link TokenStorage}. Data is lost when the process exits. */