@udibo/oauth2 0.19.0 → 0.21.0

package/dist/cli/idp/server.js

@@ -23,6 +23,7 @@ import { PasswordGrant } from "../../server/grants/password.js";
 import { RefreshTokenGrant } from "../../server/grants/refresh-token.js";
 import { StaticSigningKeyProvider, } from "../../server/signing-keys.js";
 import { generateCodeChallenge, generateCodeVerifier, generateState, } from "../../utils/pkce.js";
+import { DEFAULT_MAX_BODY_BYTES, readBoundedBody } from "../../utils/_body.js";
 import { timingSafeEqualString } from "../../utils/crypto.js";
 import { safeReturnTo } from "../../utils/url.js";
 import { MemoryAuthorizationCodeService, MemoryClientService, MemoryTokenService, MemoryUserService, } from "../../testing/services.js";
@@ -218,8 +219,22 @@ function handleConsentFor(state, request) {
         }));
     };
 }
+class BodyTooLargeError extends Error {
+}
+async function readBody(request) {
+    const bytes = await readBoundedBody(request, DEFAULT_MAX_BODY_BYTES);
+    if (!bytes) {
+        throw new BodyTooLargeError(`request body exceeds ${DEFAULT_MAX_BODY_BYTES} bytes`);
+    }
+    return bytes;
+}
+async function readFormBody(request) {
+    return await new Response(await readBody(request), {
+        headers: { "content-type": request.headers.get("content-type") ?? "" },
+    }).formData();
+}
 async function handleLoginSubmission(state, config, request) {
-    const form = await request.formData();
+    const form = await readFormBody(request);
     const returnTo = safeReturnTo(formValue(form, "return_to"));
     const quickSignIn = formValue(form, "as");
     let user;
@@ -252,7 +267,7 @@ async function handleConsentSubmission(state, request) {
     const user = await currentUser(state, request);
     if (!user)
         return redirect("/login");
-    const form = await request.formData();
+    const form = await readFormBody(request);
     const returnTo = safeReturnTo(formValue(form, "return_to"));
     const target = new URL(returnTo, request.url);
     const clientId = target.searchParams.get("client_id");
@@ -294,7 +309,7 @@ function handleLogout(state, config, request) {
     });
 }
 async function readJsonBody(request) {
-    const text = await request.text();
+    const text = new TextDecoder().decode(await readBody(request));
     if (text.trim().length === 0)
         return {};
     const parsed = JSON.parse(text);
@@ -522,7 +537,7 @@ export async function startDevIdentityProvider(options) {
             }
         }
         catch (error) {
-            return jsonError(400, error instanceof Error ? error.message : String(error));
+            return jsonError(error instanceof BodyTooLargeError ? 413 : 400, error instanceof Error ? error.message : String(error));
         }
     };
     const server = serveNode({

package/dist/identity/external/_shared.d.ts

@@ -24,10 +24,25 @@ export declare const ID_TOKEN_EXPIRY_LEEWAY_SECONDS = 120;
  * OAuth2 error carries a description the provider wrote.
  */
 export declare function describeError(error: unknown): string;
+/**
+ * Response bytes a connector reads from a provider endpoint — token, profile,
+ * UserInfo, or key set — before refusing the response.
+ */
+export declare const MAX_PROVIDER_RESPONSE_BYTES: number;
+/**
+ * Reads `res`'s body as text, stopping and cancelling it past
+ * {@link MAX_PROVIDER_RESPONSE_BYTES}. `source` names the endpoint in the
+ * error message, e.g. `"the Acme profile endpoint"`.
+ *
+ * @throws {ExternalAuthError} `provider_error` when the body is larger than
+ *   the cap or stops arriving.
+ */
+export declare function readProviderText(res: Response, provider: string, source: string): Promise<string>;
 /**
  * Reads a failed response's body into a bounded, single-line `": <text>"`
- * suffix to append to an error message, or `""` when the body is empty or
- * unreadable. Consumes the body, so the caller must not read it again.
+ * suffix to append to an error message, or `""` when the body is empty,
+ * unreadable, or larger than {@link MAX_PROVIDER_RESPONSE_BYTES}. Consumes
+ * the body, so the caller must not read it again.
  */
 export declare function readErrorBody(res: Response): Promise<string>;
 /**

package/dist/identity/external/_shared.js

@@ -9,6 +9,7 @@
  * @module
  */
 import { isOAuth2Error } from "../../errors.js";
+import { readBoundedBody } from "../../utils/_body.js";
 import { timingSafeEqualString } from "../../utils/crypto.js";
 import { PROVIDER_TEXT_MAX_LENGTH, sanitizeProviderText, } from "../../utils/text.js";
 import { ExternalAuthError } from "./errors.js";
@@ -36,14 +37,45 @@ export function describeError(error) {
     }
     return sanitizeProviderText(error instanceof Error ? error.message : String(error));
 }
+/**
+ * Response bytes a connector reads from a provider endpoint — token, profile,
+ * UserInfo, or key set — before refusing the response.
+ */
+export const MAX_PROVIDER_RESPONSE_BYTES = 64 * 1024;
+/**
+ * Reads `res`'s body as text, stopping and cancelling it past
+ * {@link MAX_PROVIDER_RESPONSE_BYTES}. `source` names the endpoint in the
+ * error message, e.g. `"the Acme profile endpoint"`.
+ *
+ * @throws {ExternalAuthError} `provider_error` when the body is larger than
+ *   the cap or stops arriving.
+ */
+export async function readProviderText(res, provider, source) {
+    let bytes;
+    try {
+        bytes = await readBoundedBody(res, MAX_PROVIDER_RESPONSE_BYTES);
+    }
+    catch (error) {
+        throw new ExternalAuthError(provider, "provider_error", `${source} response could not be read (${describeError(error)}).`, { cause: error });
+    }
+    if (!bytes) {
+        throw new ExternalAuthError(provider, "provider_error", `${source} response exceeded ${MAX_PROVIDER_RESPONSE_BYTES} bytes — ` +
+            `refusing to parse a response this large.`);
+    }
+    return new TextDecoder().decode(bytes);
+}
 /**
  * Reads a failed response's body into a bounded, single-line `": <text>"`
- * suffix to append to an error message, or `""` when the body is empty or
- * unreadable. Consumes the body, so the caller must not read it again.
+ * suffix to append to an error message, or `""` when the body is empty,
+ * unreadable, or larger than {@link MAX_PROVIDER_RESPONSE_BYTES}. Consumes
+ * the body, so the caller must not read it again.
  */
 export async function readErrorBody(res) {
     try {
-        const snippet = sanitizeProviderText(await res.text());
+        const bytes = await readBoundedBody(res, MAX_PROVIDER_RESPONSE_BYTES);
+        if (!bytes)
+            return "";
+        const snippet = sanitizeProviderText(new TextDecoder().decode(bytes));
         return snippet ? `: ${snippet}` : "";
     }
     catch {

package/dist/identity/external/_token-exchange.js

@@ -9,10 +9,10 @@
  * @module
  */
 import { packageDeadlineSignal } from "../../utils/_default-fetch.js";
-import { describeError, sanitizeProviderText } from "./_shared.js";
+import { describeError, MAX_PROVIDER_RESPONSE_BYTES, sanitizeProviderText, } from "./_shared.js";
 import { ExternalAuthError } from "./errors.js";
 /** Response bytes accepted from a token endpoint before the exchange is refused. */
-export const MAX_TOKEN_RESPONSE_BYTES = 64 * 1024;
+export const MAX_TOKEN_RESPONSE_BYTES = MAX_PROVIDER_RESPONSE_BYTES;
 /** Wall-clock budget for the exchange, covering the connect and the body read. */
 export const TOKEN_EXCHANGE_TIMEOUT_MS = 10_000;
 /**

package/dist/identity/external/apple.js

@@ -18,7 +18,7 @@
 import { toArrayBuffer } from "../../utils/_buffer.js";
 import { base64urlDecode } from "../../utils/crypto.js";
 import { defaultFetch } from "../../utils/_default-fetch.js";
-import { assertIdTokenClaims, describeError } from "./_shared.js";
+import { assertIdTokenClaims, describeError, readProviderText, } from "./_shared.js";
 import { runTokenExchange } from "./_token-exchange.js";
 import { createAppleClientSecretFactory, } from "./apple-client-secret.js";
 import { ExternalAuthError } from "./errors.js";
@@ -110,9 +110,10 @@ export function appleProvider(options) {
             await res.body?.cancel();
             throw new ExternalAuthError(id, "provider_error", `Apple's JWKS endpoint responded with HTTP ${res.status}.`);
         }
+        const text = await readProviderText(res, id, "Apple's JWKS endpoint");
         let doc;
         try {
-            doc = (await res.json());
+            doc = JSON.parse(text);
         }
         catch (error) {
             throw new ExternalAuthError(id, "provider_error", `Apple's JWKS endpoint returned invalid JSON (${describeError(error)}).`, { cause: error });

package/dist/identity/external/github.js

@@ -5,7 +5,7 @@
  * @module
  */
 import { defaultFetch } from "../../utils/_default-fetch.js";
-import { describeError } from "./_shared.js";
+import { describeError, readProviderText } from "./_shared.js";
 import { runTokenExchange } from "./_token-exchange.js";
 import { ExternalAuthError } from "./errors.js";
 const GITHUB_AUTHORIZE_URL = "https://github.com/login/oauth/authorize";
@@ -74,8 +74,9 @@ export function githubProvider(options) {
             await res.body?.cancel();
             return null;
         }
+        const text = await readProviderText(res, id, url);
         try {
-            return await res.json();
+            return JSON.parse(text);
         }
         catch (error) {
             throw new ExternalAuthError(id, "provider_error", `${url} returned a response that was not valid JSON ` +

package/dist/identity/external/oauth2.js

@@ -9,7 +9,7 @@
  */
 import { defaultFetch } from "../../utils/_default-fetch.js";
 import { generateCodeChallenge } from "../../utils/pkce.js";
-import { describeError, readErrorBody } from "./_shared.js";
+import { describeError, readErrorBody, readProviderText } from "./_shared.js";
 import { runTokenExchange } from "./_token-exchange.js";
 import { ExternalAuthError } from "./errors.js";
 /**
@@ -85,8 +85,9 @@ export function oauth2Provider(options) {
                 `access token was issued but lacks profile access — ensure the ` +
                 `identity scope is requested.`);
         }
+        const text = await readProviderText(res, id, `the ${options.displayName} profile endpoint`);
         try {
-            return (await res.json());
+            return JSON.parse(text);
         }
         catch (error) {
             throw new ExternalAuthError(id, "provider_error", `the ${options.displayName} profile endpoint returned a response ` +

package/dist/identity/external/oidc.js

@@ -9,7 +9,7 @@ import { MemoryAuthRequestStorage } from "../../client/storage.js";
 import { isOAuth2Error } from "../../errors.js";
 import { defaultFetch } from "../../utils/_default-fetch.js";
 import { generateCodeChallenge } from "../../utils/pkce.js";
-import { assertIdTokenClaims, describeError, stripTrailingSlash, } from "./_shared.js";
+import { assertIdTokenClaims, describeError, readProviderText, stripTrailingSlash, } from "./_shared.js";
 import { ExternalAuthError } from "./errors.js";
 /**
  * Creates a connector for any spec-compliant OpenID Connect provider.
@@ -153,7 +153,7 @@ export function oidcProvider(options) {
                 await res.body?.cancel();
                 return null;
             }
-            const info = (await res.json());
+            const info = JSON.parse(await readProviderText(res, id, "the UserInfo endpoint"));
             return info.sub === idTokenSub ? info : null;
         }
         catch {

package/dist/identity/hibp.d.ts

@@ -32,6 +32,14 @@ export interface BreachedPasswordOptions {
     failOpen?: boolean;
     /** Abort the range request after this many ms. Defaults to 3000. */
     timeoutMs?: number;
+    /**
+     * Largest range response, in bytes, the check reads. Defaults to 1048576
+     * (1 MiB), about ten times a padded range. The read counts bytes as they
+     * arrive and cancels the response at the cap, whether or not it has a
+     * `Content-Length`; a larger response counts as the range API being
+     * unavailable, so `failOpen` decides the outcome.
+     */
+    maxResponseBytes?: number;
     /** Fetch implementation — inject for tests. Defaults to `globalThis.fetch`. */
     fetch?: typeof fetch;
     /** Range API base URL. Defaults to `https://api.pwnedpasswords.com/range/`. */
@@ -56,6 +64,8 @@ export declare function sha1Hex(input: string): Promise<string>;
  * Build a {@link PasswordPolicy} validator that rejects passwords found in the
  * HIBP breach corpus.
  *
+ * @throws {RangeError} If `maxResponseBytes` is not a positive integer.
+ *
  * @example
  * ```ts
  * const policy: PasswordPolicy = {

package/dist/identity/hibp.js

@@ -17,10 +17,12 @@
  *
  * @module
  */
+import { assertMaxBodyBytes, readBoundedBody } from "../utils/_body.js";
 import { encodeHex } from "../utils/_encoding.js";
 import { defaultFetch, packageDeadlineSignal, } from "../utils/_default-fetch.js";
 import { dispatchIdentityEvent } from "./events.js";
 const DEFAULT_BASE_URL = "https://api.pwnedpasswords.com/range/";
+const DEFAULT_MAX_RESPONSE_BYTES = 1024 * 1024;
 const VALIDATOR_NAME = "breached_password";
 const BREACHED_MESSAGE = "This password has appeared in a data breach; choose a different one.";
 const UNAVAILABLE_MESSAGE = "The password couldn't be checked against known breaches; try again.";
@@ -33,6 +35,8 @@ export async function sha1Hex(input) {
  * Build a {@link PasswordPolicy} validator that rejects passwords found in the
  * HIBP breach corpus.
  *
+ * @throws {RangeError} If `maxResponseBytes` is not a positive integer.
+ *
  * @example
  * ```ts
  * const policy: PasswordPolicy = {
@@ -45,6 +49,8 @@ export function breachedPasswordValidator(options = {}) {
     const threshold = options.threshold ?? 1;
     const failOpen = options.failOpen ?? true;
     const timeoutMs = options.timeoutMs ?? 3000;
+    const maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    assertMaxBodyBytes(maxResponseBytes, "maxResponseBytes");
     const fetchImpl = options.fetch ?? defaultFetch;
     const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
     const onEvent = options.onEvent;
@@ -61,7 +67,11 @@ export function breachedPasswordValidator(options = {}) {
                 await response.body?.cancel();
                 throw new Error(`range API responded ${response.status}`);
             }
-            const body = await response.text();
+            const bytes = await readBoundedBody(response, maxResponseBytes);
+            if (!bytes) {
+                throw new Error(`range API response exceeded ${maxResponseBytes} bytes`);
+            }
+            const body = new TextDecoder().decode(bytes);
             for (const line of body.split("\n")) {
                 const [lineSuffix, countText] = line.trim().split(":");
                 if (lineSuffix === suffix && Number(countText) >= threshold) {

package/dist/server/_challenge.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Character-set rules for `WWW-Authenticate` challenge parameters (RFC 7235
+ * §2.2, RFC 9110 §5.6.4, RFC 6750 §3).
+ *
+ * @module
+ */
+/** Throws `TypeError` unless `realm` is printable ASCII (U+0020–U+007E), the only text every HTTP stack carries in a header unaltered. */
+export declare function assertRealm(realm: string): void;
+/** The `realm` parameter as a quoted-string; `realm` must already satisfy {@linkcode assertRealm}. */
+export declare function quoteRealm(realm: string): string;
+/**
+ * Maps text into the RFC 6750 §3 `error_description` set
+ * (`%x20-21 / %x23-5B / %x5D-7E`): control characters are dropped, `"`
+ * becomes `'`, and every other code point outside the set becomes `?`.
+ */
+export declare function toChallengeDescription(text: string): string;
+/** `scope` with its space-separated tokens rejoined by single spaces, or `undefined` unless every token is an RFC 6750 §3 scope-token. */
+export declare function toChallengeScope(scope: string): string | undefined;

package/dist/server/_challenge.js

@@ -0,0 +1,41 @@
+/**
+ * Character-set rules for `WWW-Authenticate` challenge parameters (RFC 7235
+ * §2.2, RFC 9110 §5.6.4, RFC 6750 §3).
+ *
+ * @module
+ */
+import { NQCHAR } from "../models/scope.js";
+const PRINTABLE_ASCII = /^[\x20-\x7e]*$/;
+// oxlint-disable-next-line no-control-regex
+const CONTROL_CHARACTERS = /[\x00-\x1f\x7f]/g;
+const OUTSIDE_DESCRIPTION_SET = /[^\x20\x21\x23-\x5b\x5d-\x7e]/gu;
+const SCOPE_TOKEN_ONLY = new RegExp(`^${NQCHAR.source}+$`);
+/** Throws `TypeError` unless `realm` is printable ASCII (U+0020–U+007E), the only text every HTTP stack carries in a header unaltered. */
+export function assertRealm(realm) {
+    if (typeof realm !== "string" || !PRINTABLE_ASCII.test(realm)) {
+        throw new TypeError(`realm must contain only printable ASCII characters (U+0020 to U+007E), got ${JSON.stringify(realm)}`);
+    }
+}
+/** The `realm` parameter as a quoted-string; `realm` must already satisfy {@linkcode assertRealm}. */
+export function quoteRealm(realm) {
+    return `"${realm.replace(/["\\]/g, "\\$&")}"`;
+}
+/**
+ * Maps text into the RFC 6750 §3 `error_description` set
+ * (`%x20-21 / %x23-5B / %x5D-7E`): control characters are dropped, `"`
+ * becomes `'`, and every other code point outside the set becomes `?`.
+ */
+export function toChallengeDescription(text) {
+    return text
+        .replace(CONTROL_CHARACTERS, "")
+        .replaceAll('"', "'")
+        .replace(OUTSIDE_DESCRIPTION_SET, "?");
+}
+/** `scope` with its space-separated tokens rejoined by single spaces, or `undefined` unless every token is an RFC 6750 §3 scope-token. */
+export function toChallengeScope(scope) {
+    const tokens = scope.split(" ").filter((token) => token !== "");
+    return tokens.length > 0 &&
+        tokens.every((token) => SCOPE_TOKEN_ONLY.test(token))
+        ? tokens.join(" ")
+        : undefined;
+}

package/dist/server/_response-json.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Not part of the public API. The bounded JSON read the token readers apply
+ * to the responses of the authorization server they call.
+ *
+ * @module
+ */
+/**
+ * Parses `response`'s body as JSON, reading at most `maxBytes`. `label`
+ * names the response in error messages.
+ *
+ * @throws {ServerError} When the body exceeds `maxBytes` (the read stops and
+ *   the body is cancelled) or is not JSON.
+ * @throws {TemporarilyUnavailableError} When the body stops arriving before it
+ *   is complete: the deadline fired or the connection dropped mid-body.
+ */
+export declare function readResponseJson(response: Response, maxBytes: number, label: string): Promise<unknown>;

package/dist/server/_response-json.js

@@ -0,0 +1,35 @@
+/**
+ * Not part of the public API. The bounded JSON read the token readers apply
+ * to the responses of the authorization server they call.
+ *
+ * @module
+ */
+import { ServerError, TemporarilyUnavailableError } from "../errors.js";
+import { readBoundedBody } from "../utils/_body.js";
+/**
+ * Parses `response`'s body as JSON, reading at most `maxBytes`. `label`
+ * names the response in error messages.
+ *
+ * @throws {ServerError} When the body exceeds `maxBytes` (the read stops and
+ *   the body is cancelled) or is not JSON.
+ * @throws {TemporarilyUnavailableError} When the body stops arriving before it
+ *   is complete: the deadline fired or the connection dropped mid-body.
+ */
+export async function readResponseJson(response, maxBytes, label) {
+    let bytes;
+    try {
+        bytes = await readBoundedBody(response, maxBytes);
+    }
+    catch (cause) {
+        throw new TemporarilyUnavailableError(`${label} request failed`, { cause });
+    }
+    if (!bytes) {
+        throw new ServerError(`${label} response exceeded ${maxBytes} bytes`);
+    }
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch (cause) {
+        throw new ServerError(`${label} response was not JSON`, { cause });
+    }
+}

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

@@ -446,6 +446,8 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * @throws {Error} If `requireOidc` is set without `signingKeys`.
      * @throws {RangeError} If `maxBodyBytes` or `maxTokenBodyBytes` is not a
      *   positive integer.
+     * @throws {TypeError} If `realm` contains a character outside printable
+     *   ASCII.
      */
     constructor(options: AuthorizationServerOptions<Client, User, S>);
     /**

package/dist/server/authorization-server.js

@@ -29,6 +29,7 @@ import { ResourceServer, } from "./resource-server.js";
 import { defaultSubjectOf, signJwt, verifyJwt, } from "./signing-keys.js";
 import { validateCodeChallenge } from "../utils/pkce.js";
 import { oauth2ErrorResponse } from "./_error-response.js";
+import { quoteRealm } from "./_challenge.js";
 import { assertMaxBodyBytes, DEFAULT_MAX_BODY_BYTES, readBoundedBody, } from "../utils/_body.js";
 const ENDPOINTS = {
     authorization: {
@@ -200,6 +201,8 @@ export class AuthorizationServer extends ResourceServer {
      * @throws {Error} If `requireOidc` is set without `signingKeys`.
      * @throws {RangeError} If `maxBodyBytes` or `maxTokenBodyBytes` is not a
      *   positive integer.
+     * @throws {TypeError} If `realm` contains a character outside printable
+     *   ASCII.
      */
     constructor(options) {
         super({
@@ -336,7 +339,7 @@ export class AuthorizationServer extends ResourceServer {
         return (error) => {
             this.addCacheHeaders(error);
             if (error.status === 401 && request.headers.get("authorization")) {
-                error.headers.set("WWW-Authenticate", `Basic realm="${this.realm}"`);
+                error.headers.set("WWW-Authenticate", `Basic realm=${quoteRealm(this.realm)}`);
             }
         };
     }

package/dist/server/introspection-token-reader.d.ts

@@ -67,6 +67,13 @@ export interface IntrospectionTokenReaderOptions<Client extends ClientInterface,
      * {@linkcode fetch} that doesn't honour `AbortSignal`.
      */
     fetchTimeoutMs?: number;
+    /**
+     * Largest introspection response, in bytes, the reader accepts. Defaults to
+     * 65536 (64 KiB). The read counts bytes as they arrive and cancels the
+     * response at the cap, whether or not it has a `Content-Length`; a larger
+     * response throws {@linkcode ServerError}.
+     */
+    maxResponseBytes?: number;
     /**
      * `fetch` implementation used to call the introspection endpoint. Defaults
      * to the global `fetch`. Inject it to route through a custom client (mTLS,
@@ -127,10 +134,14 @@ export declare class IntrospectionTokenReader<Client extends ClientInterface, Us
     private getClient;
     private getUser?;
     private fetchTimeoutMs;
+    private maxResponseBytes;
     private customFetch?;
     /**
-     * `Scope` defaults to {@linkcode BasicScope}, `fetchTimeoutMs` to 5000, and
-     * `fetch` to the global `fetch` when omitted from `options`.
+     * `Scope` defaults to {@linkcode BasicScope}, `fetchTimeoutMs` to 5000,
+     * `maxResponseBytes` to 65536, and `fetch` to the global `fetch` when
+     * omitted from `options`.
+     *
+     * @throws {RangeError} If `maxResponseBytes` is not a positive integer.
      */
     constructor(options: IntrospectionTokenReaderOptions<Client, User, S>);
     /**
@@ -149,9 +160,10 @@ export declare class IntrospectionTokenReader<Client extends ClientInterface, Us
      *   a genuinely invalid token (which is `undefined` → `invalid_token`), not
      *   collapsed into it.
      * @throws {ServerError} If the endpoint returns any other non-2xx status
-     *   (e.g. the reader's own introspection credentials are rejected) or a body
-     *   that is not JSON — a misconfiguration, not a verdict on the caller's
-     *   token.
+     *   (e.g. the reader's own introspection credentials are rejected), a body
+     *   that is not JSON, or one larger than
+     *   {@linkcode IntrospectionTokenReaderOptions.maxResponseBytes} — a
+     *   misconfiguration, not a verdict on the caller's token.
      *
      * An active response is only accepted when its `token_type` names a bearer
      * token. RFC 7662 answers for refresh tokens too, and a refresh token's

package/dist/server/introspection-token-reader.js

@@ -12,6 +12,8 @@
 import { ServerError, TemporarilyUnavailableError } from "../errors.js";
 import { BasicScope } from "../models/scope.js";
 import { encodeBasicAuth } from "../utils/basic-auth.js";
+import { assertMaxBodyBytes, DEFAULT_MAX_RESPONSE_BYTES, } from "../utils/_body.js";
+import { readResponseJson } from "./_response-json.js";
 import { defaultFetch, packageDeadlineSignal, } from "../utils/_default-fetch.js";
 /**
  * Validates tokens by calling an OAuth2 introspection endpoint (RFC 7662).
@@ -62,10 +64,14 @@ export class IntrospectionTokenReader {
     getClient;
     getUser;
     fetchTimeoutMs;
+    maxResponseBytes;
     customFetch;
     /**
-     * `Scope` defaults to {@linkcode BasicScope}, `fetchTimeoutMs` to 5000, and
-     * `fetch` to the global `fetch` when omitted from `options`.
+     * `Scope` defaults to {@linkcode BasicScope}, `fetchTimeoutMs` to 5000,
+     * `maxResponseBytes` to 65536, and `fetch` to the global `fetch` when
+     * omitted from `options`.
+     *
+     * @throws {RangeError} If `maxResponseBytes` is not a positive integer.
      */
     constructor(options) {
         this.introspectionEndpoint = options.introspectionEndpoint;
@@ -76,6 +82,9 @@ export class IntrospectionTokenReader {
         this.getClient = options.getClient;
         this.getUser = options.getUser;
         this.fetchTimeoutMs = options.fetchTimeoutMs ?? 5_000;
+        this.maxResponseBytes =
+            options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+        assertMaxBodyBytes(this.maxResponseBytes, "maxResponseBytes");
         this.customFetch = options.fetch;
     }
     /**
@@ -94,9 +103,10 @@ export class IntrospectionTokenReader {
      *   a genuinely invalid token (which is `undefined` → `invalid_token`), not
      *   collapsed into it.
      * @throws {ServerError} If the endpoint returns any other non-2xx status
-     *   (e.g. the reader's own introspection credentials are rejected) or a body
-     *   that is not JSON — a misconfiguration, not a verdict on the caller's
-     *   token.
+     *   (e.g. the reader's own introspection credentials are rejected), a body
+     *   that is not JSON, or one larger than
+     *   {@linkcode IntrospectionTokenReaderOptions.maxResponseBytes} — a
+     *   misconfiguration, not a verdict on the caller's token.
      *
      * An active response is only accepted when its `token_type` names a bearer
      * token. RFC 7662 answers for refresh tokens too, and a refresh token's
@@ -153,16 +163,7 @@ export class IntrospectionTokenReader {
                     ? new TemporarilyUnavailableError(`token introspection failed (HTTP ${response.status})`)
                     : new ServerError(`token introspection failed (HTTP ${response.status})`);
             }
-            try {
-                return (await response.json());
-            }
-            catch (cause) {
-                throw controller.signal.aborted
-                    ? new TemporarilyUnavailableError("token introspection request failed", { cause })
-                    : new ServerError("token introspection response was not JSON", {
-                        cause,
-                    });
-            }
+            return (await readResponseJson(response, this.maxResponseBytes, "token introspection"));
         }
         finally {
             clearTimeout(deadline);

package/dist/server/jwks-token-reader.d.ts

@@ -146,6 +146,14 @@ export interface JwksTokenReaderOptions<Client extends ClientInterface, User, S
      * {@linkcode fetch} that doesn't honour `AbortSignal`.
      */
     fetchTimeoutMs?: number;
+    /**
+     * Largest discovery document or JWKS, in bytes, the reader accepts.
+     * Defaults to 262144 (256 KiB). The read counts bytes as they arrive and
+     * cancels the response at the cap, whether or not it has a
+     * `Content-Length`; a larger response fails the refresh with a
+     * {@linkcode ServerError}, as a malformed one does.
+     */
+    maxResponseBytes?: number;
     /** Optional scope constructor for parsing scope strings. Defaults to BasicScope. */
     Scope?: ScopeConstructor<S>;
     /**
@@ -233,14 +241,15 @@ export declare class JwksTokenReader<Client extends ClientInterface, User, S ext
      * Defaults: every Web Crypto asymmetric algorithm accepted, `at+jwt`
      * required as `typ`, `client_id` as the required client-id claim, 30
      * seconds of clock skew, a 10-minute cache with a 30-second minimum
-     * between fetches, a 5-second request deadline, {@linkcode BasicScope},
-     * and the global `fetch`.
+     * between fetches, a 5-second request deadline, a 256 KiB response cap,
+     * {@linkcode BasicScope}, and the global `fetch`.
      *
      * @throws {TypeError} If `issuer` is not an absolute URL, `audience` is
      *   empty, or `algorithms` names an algorithm this package cannot verify
      *   (a silently ignored entry would read as a policy that isn't enforced).
      * @throws {RangeError} If `clockSkewSeconds` is negative, non-finite, or
-     *   overflows when converted to milliseconds.
+     *   overflows when converted to milliseconds, or `maxResponseBytes` is not
+     *   a positive integer.
      */
     constructor(options: JwksTokenReaderOptions<Client, User, S>);
     /**
@@ -263,8 +272,10 @@ export declare class JwksTokenReader<Client extends ClientInterface, User, S ext
      *   invalid token, not collapsed into it. Once keys are cached, a failed
      *   refresh is absorbed and the cached keys keep serving.
      * @throws {ServerError} If, with no keys cached, the JWKS endpoint returns
-     *   a 4xx or a body that is not a JWKS, or discovery reports no `jwks_uri`
-     *   — a misconfiguration, not a verdict on the caller's token.
+     *   a 4xx or a body that is not a JWKS, either document exceeds
+     *   {@linkcode JwksTokenReaderOptions.maxResponseBytes}, or discovery
+     *   reports no `jwks_uri` — a misconfiguration, not a verdict on the
+     *   caller's token.
      */
     getToken(accessToken: string): Promise<Token<Client, User, S> | undefined>;
 }

package/dist/server/jwks-token-reader.js

@@ -14,10 +14,12 @@
  */
 import { ServerError, TemporarilyUnavailableError } from "../errors.js";
 import { BasicScope } from "../models/scope.js";
+import { assertMaxBodyBytes, DEFAULT_MAX_KEY_SET_BYTES, } from "../utils/_body.js";
 import { toArrayBuffer } from "../utils/_buffer.js";
 import { base64urlDecode } from "../utils/crypto.js";
 import { defaultFetch, packageDeadlineSignal, } from "../utils/_default-fetch.js";
 import { assertClockSkewSeconds } from "./_clock-skew.js";
+import { readResponseJson } from "./_response-json.js";
 const ALGORITHMS = {
     ES256: {
         kty: "EC",
@@ -210,6 +212,7 @@ export class JwksTokenReader {
     #cacheMaxAgeMs;
     #minFetchIntervalMs;
     #fetchTimeoutMs;
+    #maxResponseBytes;
     #metadataUrls;
     #Scope;
     #getClient;
@@ -224,14 +227,15 @@ export class JwksTokenReader {
      * Defaults: every Web Crypto asymmetric algorithm accepted, `at+jwt`
      * required as `typ`, `client_id` as the required client-id claim, 30
      * seconds of clock skew, a 10-minute cache with a 30-second minimum
-     * between fetches, a 5-second request deadline, {@linkcode BasicScope},
-     * and the global `fetch`.
+     * between fetches, a 5-second request deadline, a 256 KiB response cap,
+     * {@linkcode BasicScope}, and the global `fetch`.
      *
      * @throws {TypeError} If `issuer` is not an absolute URL, `audience` is
      *   empty, or `algorithms` names an algorithm this package cannot verify
      *   (a silently ignored entry would read as a policy that isn't enforced).
      * @throws {RangeError} If `clockSkewSeconds` is negative, non-finite, or
-     *   overflows when converted to milliseconds.
+     *   overflows when converted to milliseconds, or `maxResponseBytes` is not
+     *   a positive integer.
      */
     constructor(options) {
         this.#issuer = options.issuer;
@@ -255,6 +259,9 @@ export class JwksTokenReader {
         this.#cacheMaxAgeMs = options.cacheMaxAgeMs ?? 600_000;
         this.#minFetchIntervalMs = options.minFetchIntervalMs ?? 30_000;
         this.#fetchTimeoutMs = options.fetchTimeoutMs ?? 5_000;
+        this.#maxResponseBytes =
+            options.maxResponseBytes ?? DEFAULT_MAX_KEY_SET_BYTES;
+        assertMaxBodyBytes(this.#maxResponseBytes, "maxResponseBytes");
         this.#Scope =
             options.Scope ?? BasicScope;
         this.#getClient = options.getClient;
@@ -282,8 +289,10 @@ export class JwksTokenReader {
      *   invalid token, not collapsed into it. Once keys are cached, a failed
      *   refresh is absorbed and the cached keys keep serving.
      * @throws {ServerError} If, with no keys cached, the JWKS endpoint returns
-     *   a 4xx or a body that is not a JWKS, or discovery reports no `jwks_uri`
-     *   — a misconfiguration, not a verdict on the caller's token.
+     *   a 4xx or a body that is not a JWKS, either document exceeds
+     *   {@linkcode JwksTokenReaderOptions.maxResponseBytes}, or discovery
+     *   reports no `jwks_uri` — a misconfiguration, not a verdict on the
+     *   caller's token.
      */
     async getToken(accessToken) {
         const parsed = parseJws(accessToken);
@@ -499,12 +508,7 @@ export class JwksTokenReader {
                     ? new TemporarilyUnavailableError(`${label} request failed (HTTP ${response.status})`)
                     : new ServerError(`${label} request failed (HTTP ${response.status})`);
             }
-            try {
-                return await response.json();
-            }
-            catch (cause) {
-                throw new ServerError(`${label} response was not JSON`, { cause });
-            }
+            return await readResponseJson(response, this.#maxResponseBytes, label);
         }
         finally {
             clearTimeout(deadline);

package/dist/server/resource-server.d.ts

@@ -37,7 +37,14 @@ export interface ResourceServerOptions<Client extends ClientInterface, User, S e
     resolve: (request: Request) => ResourceServerContext<Client, User, S> | Promise<ResourceServerContext<Client, User, S>>;
     /** Scope constructor used to parse and compare scopes. Defaults to {@linkcode BasicScope}. */
     Scope?: ScopeConstructor<S>;
-    /** Protection space named in `WWW-Authenticate` challenges. Defaults to `"Service"`. */
+    /**
+     * Protection space named in `WWW-Authenticate` challenges. Defaults to
+     * `"Service"`. Must be printable ASCII (U+0020 to U+007E); a product name
+     * with other characters needs an ASCII form here.
+     *
+     * @throws {TypeError} From the constructor when it contains any other
+     *   character.
+     */
     realm?: string;
     /**
      * Leeway in seconds applied to the access token's expiry, to absorb clock
@@ -170,14 +177,22 @@ export declare class ResourceServer<Client extends ClientInterface, User, S exte
     #private;
     /** Scope constructor used to parse and compare scopes. */
     Scope: ScopeConstructor<S>;
-    /** Protection space named in `WWW-Authenticate` challenges. */
-    realm: string;
     /** Body format of protected-resource refusals: OAuth2 or RFC 9457 problem details. See {@linkcode ResourceServerOptions.errorFormat}. */
     errorFormat: "oauth2" | "problem-details";
     /** When true, handler boundaries rethrow {@linkcode OAuth2Error} instead of returning a response. */
     throwOnError: boolean;
     /** Resolves the per-request {@link ResourceServerContext}. */
     protected resolveContext: (request: Request) => ResourceServerContext<Client, User, S> | Promise<ResourceServerContext<Client, User, S>>;
+    /** Protection space named in `WWW-Authenticate` challenges. */
+    get realm(): string;
+    /**
+     * Sets the protection space, preserving the previous value if validation
+     * fails.
+     *
+     * @throws {TypeError} If the value contains a character outside printable
+     *   ASCII (U+0020 to U+007E).
+     */
+    set realm(value: string);
     /**
      * Leeway in seconds applied to the access token's expiry. Defaults to `0`.
      * May be reassigned to any non-negative finite number with a finite
@@ -197,6 +212,8 @@ export declare class ResourceServer<Client extends ClientInterface, User, S exte
      * @throws {RangeError} If `clockSkewSeconds` is negative, non-finite, or
      *   overflows when converted to milliseconds, or if `maxTokenBodyBytes` is
      *   not a positive integer.
+     * @throws {TypeError} If `realm` contains a character outside printable
+     *   ASCII.
      */
     constructor(options: ResourceServerOptions<Client, User, S>);
     /**
@@ -217,6 +234,14 @@ export declare class ResourceServer<Client extends ClientInterface, User, S exte
      * {@linkcode InsufficientScopeError} is the one that tells it "your token is
      * fine, it just lacks scope" rather than sending it off to refresh.
      *
+     * The result is always printable ASCII, so it never makes `Headers` throw.
+     * `error_description` is the same text the oauth2 response body uses (the
+     * `error_description` extension, else the error's exposed message, so an
+     * unexposed message stays out of both), narrowed to the RFC 6750 character
+     * set: control characters are dropped, `"` becomes `'`, and any other
+     * character outside the set becomes `?`. `scope` is omitted entirely when
+     * any of its tokens falls outside the RFC 6750 set.
+     *
      * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3
      */
     buildWwwAuthenticate(error?: OAuth2Error, requiredScope?: string): string;

package/dist/server/resource-server.js

@@ -11,6 +11,7 @@ import { AccessDeniedError, InsufficientPermissionsError, InsufficientScopeError
 import { authorizationFromClaims, } from "../models/authorization.js";
 import { copyErrorHeaders, oauth2ErrorResponse } from "./_error-response.js";
 import { assertClockSkewSeconds } from "./_clock-skew.js";
+import { assertRealm, quoteRealm, toChallengeDescription, toChallengeScope, } from "./_challenge.js";
 import { assertMaxBodyBytes, DEFAULT_MAX_TOKEN_BODY_BYTES, peekBoundedBody, } from "../utils/_body.js";
 /** Bearer token regex pattern. */
 export const BEARER_TOKEN = /^ *(?:[Bb][Ee][Aa][Rr][Ee][Rr]) +([\w-.~+/]+=*) *$/;
@@ -73,8 +74,6 @@ const CHALLENGE_ERROR_CODES = new Set([
 export class ResourceServer {
     /** Scope constructor used to parse and compare scopes. */
     Scope;
-    /** Protection space named in `WWW-Authenticate` challenges. */
-    realm;
     /** Body format of protected-resource refusals: OAuth2 or RFC 9457 problem details. See {@linkcode ResourceServerOptions.errorFormat}. */
     errorFormat;
     /** When true, handler boundaries rethrow {@linkcode OAuth2Error} instead of returning a response. */
@@ -83,6 +82,22 @@ export class ResourceServer {
     resolveContext;
     #clockSkewSeconds = 0;
     #maxTokenBodyBytes;
+    #realm = "Service";
+    /** Protection space named in `WWW-Authenticate` challenges. */
+    get realm() {
+        return this.#realm;
+    }
+    /**
+     * Sets the protection space, preserving the previous value if validation
+     * fails.
+     *
+     * @throws {TypeError} If the value contains a character outside printable
+     *   ASCII (U+0020 to U+007E).
+     */
+    set realm(value) {
+        assertRealm(value);
+        this.#realm = value;
+    }
     /**
      * Leeway in seconds applied to the access token's expiry. Defaults to `0`.
      * May be reassigned to any non-negative finite number with a finite
@@ -107,6 +122,8 @@ export class ResourceServer {
      * @throws {RangeError} If `clockSkewSeconds` is negative, non-finite, or
      *   overflows when converted to milliseconds, or if `maxTokenBodyBytes` is
      *   not a positive integer.
+     * @throws {TypeError} If `realm` contains a character outside printable
+     *   ASCII.
      */
     constructor(options) {
         this.Scope =
@@ -138,31 +155,33 @@ export class ResourceServer {
      * {@linkcode InsufficientScopeError} is the one that tells it "your token is
      * fine, it just lacks scope" rather than sending it off to refresh.
      *
+     * The result is always printable ASCII, so it never makes `Headers` throw.
+     * `error_description` is the same text the oauth2 response body uses (the
+     * `error_description` extension, else the error's exposed message, so an
+     * unexposed message stays out of both), narrowed to the RFC 6750 character
+     * set: control characters are dropped, `"` becomes `'`, and any other
+     * character outside the set becomes `?`. `scope` is omitted entirely when
+     * any of its tokens falls outside the RFC 6750 set.
+     *
      * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3
      */
     buildWwwAuthenticate(error, requiredScope) {
-        const quote = (value) => value
-            // oxlint-disable-next-line no-control-regex
-            .replace(/[\x00-\x1f\x7f]/g, "")
-            .replace(/\\/g, "\\\\")
-            .replace(/"/g, '\\"');
-        const parts = [`realm="${quote(this.realm)}"`];
+        const parts = [`realm=${quoteRealm(this.realm)}`];
         const code = error?.extensions.error;
         if (error && code && CHALLENGE_ERROR_CODES.has(code)) {
-            parts.push(`error="${quote(code)}"`);
-            if (error.message) {
-                parts.push(`error_description="${quote(error.message)}"`);
+            parts.push(`error="${code}"`);
+            const description = toChallengeDescription(error.extensions.error_description ?? error.exposedMessage);
+            if (description) {
+                parts.push(`error_description="${description}"`);
             }
         }
-        if (requiredScope) {
-            parts.push(`scope="${quote(requiredScope)}"`);
-        }
-        else if (error instanceof InsufficientScopeError) {
-            const scope = error.extensions
-                .requiredScope;
-            if (scope) {
-                parts.push(`scope="${quote(scope)}"`);
-            }
+        const scope = requiredScope ||
+            (error instanceof InsufficientScopeError
+                ? error.extensions.requiredScope
+                : undefined);
+        const challengeScope = scope ? toChallengeScope(scope) : undefined;
+        if (challengeScope) {
+            parts.push(`scope="${challengeScope}"`);
         }
         return `Bearer ${parts.join(", ")}`;
     }

package/dist/utils/_body.d.ts

@@ -1,6 +1,7 @@
 /**
- * Internal bounded request-body reader for the endpoints that parse a body
- * before they have authenticated the caller.
+ * Internal bounded body reader for the request bodies the endpoints parse
+ * before they have authenticated the caller, and for the responses the
+ * package reads from the servers it calls.
  *
  * @module
  */
@@ -17,20 +18,30 @@ export declare const DEFAULT_MAX_BODY_BYTES: number;
  * block, so any token a client could send as `Authorization: Bearer` fits.
  */
 export declare const DEFAULT_MAX_TOKEN_BODY_BYTES: number;
+/**
+ * The default cap on an introspection response: 64 KiB, the same cap the
+ * clients apply to every authorization-server response.
+ */
+export declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+/**
+ * The default cap on a discovery document or JWKS: 256 KiB, room for dozens
+ * of RSA keys that each carry an X.509 certificate chain.
+ */
+export declare const DEFAULT_MAX_KEY_SET_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.
+ * Reads `request`'s body — or a response's — 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?: {
+export declare function readBoundedBody(request: Request | Response, maxBytes: number, options?: {
     keepReadable?: boolean;
 }): Promise<Uint8Array<ArrayBuffer> | null>;
 /**

package/dist/utils/_body.js

@@ -1,6 +1,7 @@
 /**
- * Internal bounded request-body reader for the endpoints that parse a body
- * before they have authenticated the caller.
+ * Internal bounded body reader for the request bodies the endpoints parse
+ * before they have authenticated the caller, and for the responses the
+ * package reads from the servers it calls.
  *
  * @module
  */
@@ -17,6 +18,16 @@ export const DEFAULT_MAX_BODY_BYTES = 64 * 1024;
  * block, so any token a client could send as `Authorization: Bearer` fits.
  */
 export const DEFAULT_MAX_TOKEN_BODY_BYTES = 16 * 1024;
+/**
+ * The default cap on an introspection response: 64 KiB, the same cap the
+ * clients apply to every authorization-server response.
+ */
+export const DEFAULT_MAX_RESPONSE_BYTES = 64 * 1024;
+/**
+ * The default cap on a discovery document or JWKS: 256 KiB, room for dozens
+ * of RSA keys that each carry an X.509 certificate chain.
+ */
+export const DEFAULT_MAX_KEY_SET_BYTES = 256 * 1024;
 /**
  * Throws a `RangeError` naming `option` unless `maxBodyBytes` is a positive
  * safe integer.
@@ -27,12 +38,12 @@ export function assertMaxBodyBytes(maxBodyBytes, option) {
     }
 }
 /**
- * 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.
+ * Reads `request`'s body — or a response's — 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)

package/package.json

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