@udibo/oauth2 0.19.0 → 0.20.0

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udibo/oauth2",
-  "version": "0.19.0",
+  "version": "0.20.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",