@udibo/oauth2 0.6.0 → 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;

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. */

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

package/esm/server/authorization-server.js

@@ -29,6 +29,7 @@ import { DeviceAuthorizationGrant } from "./grants/device-authorization.js";
 import { ResourceServer, } from "./resource-server.js";
 import { defaultSubjectOf, signJwt, verifyJwt, } from "./signing-keys.js";
 import { validateCodeChallenge } from "../utils/pkce.js";
+import { assertMaxBodyBytes, DEFAULT_MAX_BODY_BYTES, readBoundedBody, } from "../utils/_body.js";
 const ENDPOINTS = {
     authorization: {
         option: "authorizationEndpoint",
@@ -186,6 +187,7 @@ export class AuthorizationServer extends ResourceServer {
     signingKeys;
     #endSession;
     #isPublicSuffix;
+    #maxBodyBytes;
     #subjectOf;
     #userClaims;
     #introspectionClaims;
@@ -197,6 +199,7 @@ export class AuthorizationServer extends ResourceServer {
      *
      * @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) {
         super({
@@ -227,6 +230,8 @@ export class AuthorizationServer extends ResourceServer {
                 "plain OAuth2.");
         }
         this.#isPublicSuffix = options.isPublicSuffix;
+        this.#maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+        assertMaxBodyBytes(this.#maxBodyBytes, "maxBodyBytes");
         this.#subjectOf = options.subjectOf ?? defaultSubjectOf;
         this.#userClaims = options.userClaims;
         this.#introspectionClaims = options.introspectionClaims;
@@ -343,6 +348,18 @@ export class AuthorizationServer extends ResourceServer {
         }
         return grant;
     }
+    async #readBody(request, options = {}) {
+        const bytes = await readBoundedBody(request, this.#maxBodyBytes, options)
+            .catch((cause) => {
+            throw new InvalidRequestError("request body could not be read", {
+                cause,
+            });
+        });
+        if (!bytes) {
+            throw new InvalidRequestError(413, `request body exceeds ${this.#maxBodyBytes} bytes`);
+        }
+        return bytes;
+    }
     async #beginClientAuthenticatedRequest(request, options = {}) {
         if (request.method !== "POST") {
             throw new InvalidRequestError("method must be POST");
@@ -351,10 +368,13 @@ export class AuthorizationServer extends ResourceServer {
         if (!contentType?.includes("application/x-www-form-urlencoded")) {
             throw new InvalidRequestError("content-type header must be application/x-www-form-urlencoded");
         }
-        const context = await this.authorizationContext(request);
-        const body = await request.clone().formData().catch(() => {
+        const bytes = await this.#readBody(request, { keepReadable: true });
+        const body = await new Response(bytes, {
+            headers: { "content-type": contentType },
+        }).formData().catch(() => {
             throw new InvalidRequestError("body must be application/x-www-form-urlencoded");
         });
+        const context = await this.authorizationContext(request);
         const grant = options.grantFromBody?.(body);
         const client = grant
             ? await grant.getAuthenticatedClient(request, body)
@@ -372,7 +392,9 @@ export class AuthorizationServer extends ResourceServer {
      * `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.
      */
     async handleTokenRequest(request) {
         try {
@@ -523,7 +545,9 @@ export class AuthorizationServer extends ResourceServer {
      * 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
@@ -572,7 +596,7 @@ export class AuthorizationServer extends ResourceServer {
     async #endSessionParameters(request) {
         const url = new URL(request.url);
         const params = request.method === "POST"
-            ? new URLSearchParams(await request.text())
+            ? new URLSearchParams(new TextDecoder().decode(await this.#readBody(request)))
             : url.searchParams;
         const idTokenHint = params.get("id_token_hint");
         const hint = idTokenHint ? await this.#readIdTokenHint(idTokenHint) : null;

package/esm/testing/contract/auth-request-storage.d.ts

@@ -22,6 +22,20 @@
  * });
  * ```
  *
+ * @example Verify a store shared between users, whose `clear()` removes only expired records
+ * ```ts
+ * import { runAuthRequestStorageContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { AuthRequestStorage } from "@udibo/oauth2/client";
+ *
+ * declare function freshSharedAuthRequestStorage(): Promise<AuthRequestStorage>;
+ *
+ * runAuthRequestStorageContractTests({
+ *   describeName: "SharedAuthRequestStorage satisfies AuthRequestStorage contract",
+ *   makeStore: freshSharedAuthRequestStorage,
+ *   clear: "scoped",
+ * });
+ * ```
+ *
  * @module
  */
 import type { AuthRequestStorage } from "../../client/storage.js";
@@ -41,6 +55,18 @@ export interface AuthRequestStorageContractOptions {
      * that meant to implement it and does not fails loudly.
      */
     take?: boolean;
+    /**
+     * What the store's {@link AuthRequestStorage.clear} removes. Defaults to
+     * `"all"`: every record, as a store private to one browser or session
+     * does. Pass `"scoped"` for a store shared between users whose `clear()`
+     * deliberately removes less — only expired records, say — because a
+     * `DirectClient` clears it on every sign-out, and removing everything would
+     * cancel other users' sign-ins still in progress. The suite then drops the
+     * clear-everything case and instead requires that `clear()` leaves every
+     * record still inside its lifetime readable and redeemable, and removes a
+     * record created at the epoch (`createdAt: 0`), which is past any lifetime.
+     */
+    clear?: "all" | "scoped";
     /**
      * Overrides the name passed to the outer `describe` block. Defaults to
      * `"AuthRequestStorage contract"`.

package/esm/testing/contract/auth-request-storage.js

@@ -22,6 +22,20 @@
  * });
  * ```
  *
+ * @example Verify a store shared between users, whose `clear()` removes only expired records
+ * ```ts
+ * import { runAuthRequestStorageContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { AuthRequestStorage } from "@udibo/oauth2/client";
+ *
+ * declare function freshSharedAuthRequestStorage(): Promise<AuthRequestStorage>;
+ *
+ * runAuthRequestStorageContractTests({
+ *   describeName: "SharedAuthRequestStorage satisfies AuthRequestStorage contract",
+ *   makeStore: freshSharedAuthRequestStorage,
+ *   clear: "scoped",
+ * });
+ * ```
+ *
  * @module
  */
 import { assert, assertEquals, assertStrictEquals } from "../../deps/jsr.io/@std/assert/1.0.19/mod.js";
@@ -47,6 +61,7 @@ function record(overrides = {}) {
  */
 export function runAuthRequestStorageContractTests(options) {
     const expectTake = options.take ?? true;
+    const clearScope = options.clear ?? "all";
     describe(options.describeName ?? "AuthRequestStorage contract", () => {
         let store;
         beforeEach(async () => {
@@ -74,13 +89,35 @@ export function runAuthRequestStorageContractTests(options) {
                 assertStrictEquals(await store.get("state-1"), null);
                 assert(await store.get("state-2") !== null, "delete must remove only the named state");
             });
-            it("clears every record", async () => {
-                await store.set("state-1", record());
-                await store.set("state-2", record());
-                await store.clear();
-                assertStrictEquals(await store.get("state-1"), null);
-                assertStrictEquals(await store.get("state-2"), null);
-            });
+            if (clearScope === "all") {
+                it("clears every record", async () => {
+                    await store.set("state-1", record());
+                    await store.set("state-2", record());
+                    await store.clear();
+                    assertStrictEquals(await store.get("state-1"), null);
+                    assertStrictEquals(await store.get("state-2"), null);
+                });
+            }
+            else {
+                it('leaves every in-progress record in place (clear: "scoped")', async () => {
+                    const first = record({ codeVerifier: "verifier-1" });
+                    const second = record({ codeVerifier: "verifier-2" });
+                    await store.set("state-1", first);
+                    await store.set("state-2", second);
+                    await store.clear();
+                    const message = "clear() on a shared store must not cancel another user's sign-in " +
+                        "that is still in progress";
+                    assertEquals(await store.get("state-2"), second, message);
+                    assertEquals(expectTake
+                        ? await store.take("state-1")
+                        : await store.get("state-1"), first, message);
+                });
+                it('removes a record past any lifetime (clear: "scoped")', async () => {
+                    await store.set("expired", record({ createdAt: 0 }));
+                    await store.clear();
+                    assertStrictEquals(await store.get("expired"), null, "a scoped clear() must still remove expired records");
+                });
+            }
         });
         if (expectTake) {
             describe("take", () => {

package/esm/utils/_body.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Internal bounded request-body reader for the endpoints that parse a body
+ * before they have authenticated the caller.
+ *
+ * @module
+ */
+/**
+ * The default cap on those bodies: 64 KiB. The largest legitimate field is a
+ * JWT (`id_token_hint`, `logout_token`, an introspected access token), and a
+ * token that also travels in an `Authorization` header already has to fit
+ * the 8–16 KiB header limits common to servers and proxies.
+ */
+export declare const DEFAULT_MAX_BODY_BYTES: number;
+/**
+ * Throws a `RangeError` naming `option` unless `maxBodyBytes` is a positive
+ * safe integer.
+ */
+export declare function assertMaxBodyBytes(maxBodyBytes: number, option: string): void;
+/**
+ * Reads `request`'s body, counting bytes as they arrive, and returns `null`
+ * once it exceeds `maxBytes` — cancelling the stream rather than draining it.
+ * A `Content-Length` over the cap is refused without reading; one under it is
+ * not trusted. Consumes the body unless `keepReadable` is set, which reads a
+ * clone and leaves the original readable (a refusal cancels both). Rejects if
+ * the stream errors or was already read.
+ */
+export declare function readBoundedBody(request: Request, maxBytes: number, options?: {
+    keepReadable?: boolean;
+}): Promise<Uint8Array<ArrayBuffer> | null>;

package/esm/utils/_body.js

@@ -0,0 +1,66 @@
+/**
+ * Internal bounded request-body reader for the endpoints that parse a body
+ * before they have authenticated the caller.
+ *
+ * @module
+ */
+/**
+ * The default cap on those bodies: 64 KiB. The largest legitimate field is a
+ * JWT (`id_token_hint`, `logout_token`, an introspected access token), and a
+ * token that also travels in an `Authorization` header already has to fit
+ * the 8–16 KiB header limits common to servers and proxies.
+ */
+export const DEFAULT_MAX_BODY_BYTES = 64 * 1024;
+/**
+ * Throws a `RangeError` naming `option` unless `maxBodyBytes` is a positive
+ * safe integer.
+ */
+export function assertMaxBodyBytes(maxBodyBytes, option) {
+    if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes < 1) {
+        throw new RangeError(`${option} must be a positive integer, got ${maxBodyBytes}`);
+    }
+}
+/**
+ * Reads `request`'s body, counting bytes as they arrive, and returns `null`
+ * once it exceeds `maxBytes` — cancelling the stream rather than draining it.
+ * A `Content-Length` over the cap is refused without reading; one under it is
+ * not trusted. Consumes the body unless `keepReadable` is set, which reads a
+ * clone and leaves the original readable (a refusal cancels both). Rejects if
+ * the stream errors or was already read.
+ */
+export async function readBoundedBody(request, maxBytes, options = {}) {
+    if (!request.body)
+        return new Uint8Array();
+    if (Number(request.headers.get("content-length")) > maxBytes) {
+        request.body.cancel().catch(() => { });
+        return null;
+    }
+    const body = options.keepReadable ? request.clone().body : request.body;
+    const bytes = await readUpTo(body, maxBytes);
+    if (!bytes && options.keepReadable)
+        request.body.cancel().catch(() => { });
+    return bytes;
+}
+async function readUpTo(body, maxBytes) {
+    const reader = body.getReader();
+    const chunks = [];
+    let length = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        length += value.byteLength;
+        if (length > maxBytes) {
+            reader.cancel().catch(() => { });
+            return null;
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udibo/oauth2",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A flexible OAuth2 toolkit: framework-agnostic authorization & resource servers, a typed client, Hono adapters (including a backend-for-frontend), and React bindings.",
   "repository": {
     "type": "git",