@udibo/oauth2 0.5.1 → 0.7.0

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

@@ -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
@@ -717,7 +736,9 @@ export declare 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(): 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 " +
@@ -775,7 +781,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 +793,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 +833,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;
@@ -48,6 +51,8 @@ export declare function sendGuarded(fetchImpl: typeof fetch, url: string, init:
  * @param res The response from {@link sendGuarded}.
  * @param what The endpoint's name, for error messages.
  * @returns The parsed JSON object.
+ * @throws {TemporarilyUnavailableError} on a `2xx` whose body stops arriving
+ * within the size cap — the deadline fires or the connection drops mid-body.
  * @throws {OAuth2Error} on a non-OK status, an oversized body, a body that is
  * not valid JSON, or JSON that is not an object.
  */

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();
@@ -81,6 +84,8 @@ export async function sendGuarded(fetchImpl, url, init, what, options = {}) {
  * @param res The response from {@link sendGuarded}.
  * @param what The endpoint's name, for error messages.
  * @returns The parsed JSON object.
+ * @throws {TemporarilyUnavailableError} on a `2xx` whose body stops arriving
+ * within the size cap — the deadline fires or the connection drops mid-body.
  * @throws {OAuth2Error} on a non-OK status, an oversized body, a body that is
  * not valid JSON, or JSON that is not an object.
  */
@@ -92,6 +97,10 @@ export async function receiveJson(res, what) {
         throw new ServerError(`the ${what} response exceeded ${MAX_RESPONSE_BYTES} bytes — refusing ` +
             `to parse a response this large`);
     }
+    if (body.interrupted) {
+        throw new TemporarilyUnavailableError(`the ${what} response body did not arrive in full ` +
+            `(${describeError(body.interrupted.cause)})`, { cause: body.interrupted.cause });
+    }
     let parsed;
     try {
         parsed = JSON.parse(body.text);
@@ -184,8 +193,8 @@ async function readBounded(res) {
             size += value.byteLength;
         }
     }
-    catch {
-        return { text: decode(chunks, size), truncated: true };
+    catch (cause) {
+        return { text: decode(chunks, size), truncated, interrupted: { cause } };
     }
     finally {
         await reader.cancel().catch(() => { });

package/esm/client/check.d.ts

@@ -96,9 +96,10 @@ export interface CheckPermissionsResult {
  * deleted after the signature, so catch it on that path rather than reading a
  * throw as a bug in your own setup. A redirect, or a `2xx` whose body is not a
  * JSON object or exceeds the response-size cap, also throws
- * {@linkcode ServerError}, and a request whose response headers do not
- * arrive before the deadline throws {@linkcode TemporarilyUnavailableError}.
- * The body's shape is not validated beyond being a JSON object.
+ * {@linkcode ServerError}. A response that does not arrive in full before the
+ * deadline — whether its headers or its body stall — or whose connection
+ * drops mid-body throws {@linkcode TemporarilyUnavailableError}. The body's
+ * shape is not validated beyond being a JSON object.
  *
  * @example
  * ```ts

package/esm/client/check.js

@@ -50,9 +50,10 @@ const CHECK_ENDPOINT = "check endpoint";
  * deleted after the signature, so catch it on that path rather than reading a
  * throw as a bug in your own setup. A redirect, or a `2xx` whose body is not a
  * JSON object or exceeds the response-size cap, also throws
- * {@linkcode ServerError}, and a request whose response headers do not
- * arrive before the deadline throws {@linkcode TemporarilyUnavailableError}.
- * The body's shape is not validated beyond being a JSON object.
+ * {@linkcode ServerError}. A response that does not arrive in full before the
+ * deadline — whether its headers or its body stall — or whose connection
+ * drops mid-body throws {@linkcode TemporarilyUnavailableError}. The body's
+ * shape is not validated beyond being a JSON object.
  *
  * @example
  * ```ts
@@ -73,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

@@ -89,12 +89,20 @@ export interface AuthRequestStorage {
      * before the token call but lets concurrent callers that both read it
      * before either deletes it redeem it twice. Implement it with the backing
      * store's own atomic primitive (`GETDEL`, `DELETE … RETURNING`) whenever
-     * the store is shared between processes or requests.
+     * the store is shared between processes or requests, and check it with
+     * `runAuthRequestStorageContractTests` from `@udibo/oauth2/testing/contract`.
      */
     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. */

package/esm/server/authorization-server.d.ts

@@ -248,6 +248,26 @@ export interface AuthorizationServerOptions<Client extends ClientInterface, User
      * bundle.
      */
     isPublicSuffix?: IsPublicSuffix;
+    /**
+     * The largest request body, in bytes, the server reads at the token,
+     * revocation, introspection, device authorization and end-session
+     * endpoints. Each reads its form body before it has authenticated the
+     * caller, so the cap bounds what an anonymous request can make the server
+     * 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 `413` and `invalid_request` before the request's
+     * context is resolved or any client is authenticated.
+     *
+     * The default fits every body these endpoints legitimately receive: the
+     * largest field is a JWT (`id_token_hint`, or a token presented for
+     * introspection or revocation), a few KiB even with a large claim set.
+     * Raise it only if your clients send larger ones.
+     *
+     * @default 65536
+     * @throws {RangeError} From the constructor when it is not a positive
+     *   integer.
+     */
+    maxBodyBytes?: number;
 }
 /**
  * Function to authenticate the user during authorization.
@@ -407,6 +427,7 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      *
      * @throws {Error} If any grant's map key does not equal its `grantType`.
      * @throws {Error} If `requireOidc` is set without `signingKeys`.
+     * @throws {RangeError} If `maxBodyBytes` is not a positive integer.
      */
     constructor(options: AuthorizationServerOptions<Client, User, S>);
     /**
@@ -453,7 +474,9 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * `application/x-www-form-urlencoded`, or no `grant_type` — is a 400
      * `invalid_request`. A `grant_type` with no registered grant is
      * `unsupported_grant_type`, checked before client authentication; a client
-     * not registered for the grant is `unauthorized_client`.
+     * not registered for the grant is `unauthorized_client`. A body over
+     * {@linkcode AuthorizationServerOptions.maxBodyBytes} is a 413
+     * `invalid_request`, refused before the request context is resolved.
      */
     handleTokenRequest(request: Request): Promise<Response>;
     /**
@@ -522,7 +545,9 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * when sent, names the client ahead of the hint's audience, and when both
      * are sent `client_id` must be one of the hint's audiences — a mismatch is
      * a 400 `invalid_request` (OIDC RP-Initiated Logout 1.0 §2). `state` rides
-     * along only to a URI that passed authorization.
+     * along only to a URI that passed authorization. A POST body over
+     * {@linkcode AuthorizationServerOptions.maxBodyBytes} is a 413
+     * `invalid_request`, refused before `endSession` runs.
      *
      * Wire the app's session teardown through the `endSession` **constructor
      * option**; this method answers 404 without it, and the discovery document