@udibo/oauth2 0.18.0 → 0.19.0

package/dist/errors.d.ts

@@ -64,11 +64,11 @@ export declare function isOAuth2Error(value: unknown): value is OAuth2Error;
  * anything else is wrapped in a {@link ServerError} with the original error
  * attached as `cause`.
  *
- * Either way, `type` and `extensions.error_uri` are synced so that if one is
- * set the other is too — **mutating an OAuth2Error input in place**. This lets
- * both the standard OAuth2 error format (which emits `error_uri`) and the
- * RFC 9457 Problem Details format (which emits `type`) carry the same URI
- * without the handler having to set both fields.
+ * An error that sets `extensions.error_uri` but no `type` gets `type` set to
+ * the same URI — **mutating an OAuth2Error input in place** — so the RFC 9457
+ * Problem Details format, which emits `type`, carries it. `type` is never
+ * copied into `extensions.error_uri`, so a problem-details body does not repeat
+ * it; the RFC 6749 error format emits `error_uri` from either field.
  */
 export declare function toOAuth2Error(error: unknown): OAuth2Error;
 /**

package/dist/errors.js

@@ -38,20 +38,17 @@ export function isOAuth2Error(value) {
  * anything else is wrapped in a {@link ServerError} with the original error
  * attached as `cause`.
  *
- * Either way, `type` and `extensions.error_uri` are synced so that if one is
- * set the other is too — **mutating an OAuth2Error input in place**. This lets
- * both the standard OAuth2 error format (which emits `error_uri`) and the
- * RFC 9457 Problem Details format (which emits `type`) carry the same URI
- * without the handler having to set both fields.
+ * An error that sets `extensions.error_uri` but no `type` gets `type` set to
+ * the same URI — **mutating an OAuth2Error input in place** — so the RFC 9457
+ * Problem Details format, which emits `type`, carries it. `type` is never
+ * copied into `extensions.error_uri`, so a problem-details body does not repeat
+ * it; the RFC 6749 error format emits `error_uri` from either field.
  */
 export function toOAuth2Error(error) {
     const oauth2Error = isOAuth2Error(error)
         ? error
         : new ServerError("unexpected error", { cause: error });
-    if (oauth2Error.type && !oauth2Error.extensions.error_uri) {
-        oauth2Error.extensions.error_uri = oauth2Error.type;
-    }
-    else if (oauth2Error.extensions.error_uri && !oauth2Error.type) {
+    if (oauth2Error.extensions.error_uri && !oauth2Error.type) {
         oauth2Error.type = oauth2Error.extensions.error_uri;
     }
     return oauth2Error;

package/dist/server/_error-response.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Serializes OAuth2 errors into responses for the resource and authorization
+ * servers.
+ *
+ * @module
+ */
+import type { OAuth2Error } from "../errors.ts";
+/** Copies the error's headers onto the response, except `Content-Type`, which the serializer owns. */
+export declare function copyErrorHeaders(oauth2Error: OAuth2Error, response: Response): Response;
+/** The RFC 6749 §5.2 error response: `{ error, error_description?, error_uri? }` as `application/json`, carrying the error's headers. */
+export declare function oauth2ErrorResponse(oauth2Error: OAuth2Error): Response;

package/dist/server/_error-response.js

@@ -0,0 +1,33 @@
+/**
+ * Serializes OAuth2 errors into responses for the resource and authorization
+ * servers.
+ *
+ * @module
+ */
+/** Copies the error's headers onto the response, except `Content-Type`, which the serializer owns. */
+export function copyErrorHeaders(oauth2Error, response) {
+    for (const [key, value] of oauth2Error.headers) {
+        if (key.toLowerCase() === "content-type")
+            continue;
+        response.headers.set(key, value);
+    }
+    return response;
+}
+/** The RFC 6749 §5.2 error response: `{ error, error_description?, error_uri? }` as `application/json`, carrying the error's headers. */
+export function oauth2ErrorResponse(oauth2Error) {
+    const body = {
+        error: oauth2Error.extensions.error ?? "server_error",
+    };
+    const description = oauth2Error.extensions.error_description ?? oauth2Error.exposedMessage;
+    if (description) {
+        body.error_description = description;
+    }
+    const errorUri = oauth2Error.extensions.error_uri ?? oauth2Error.type;
+    if (errorUri) {
+        body.error_uri = errorUri;
+    }
+    return copyErrorHeaders(oauth2Error, new Response(JSON.stringify(body), {
+        status: oauth2Error.status,
+        headers: { "Content-Type": "application/json;charset=UTF-8" },
+    }));
+}

package/dist/server/authorization-server.js

@@ -20,7 +20,7 @@
  * @module
  */
 import { snapshotAuthenticationContext } from "../utils/authentication-context.js";
-import { AccessDeniedError, InvalidRequestError, InvalidTokenError, isOAuth2Error, OAuth2Error, ServerError, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, } from "../errors.js";
+import { AccessDeniedError, InvalidRequestError, InvalidTokenError, isOAuth2Error, OAuth2Error, ServerError, toOAuth2Error, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, } from "../errors.js";
 import { authenticateClientCredentials, extractClientCredentials, } from "./client-authentication.js";
 import { isRedirectUriPattern, matchRedirectUri } from "./redirect-uri.js";
 import { AuthorizationCodeGrant } from "./grants/authorization-code.js";
@@ -28,6 +28,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 { oauth2ErrorResponse } from "./_error-response.js";
 import { assertMaxBodyBytes, DEFAULT_MAX_BODY_BYTES, readBoundedBody, } from "../utils/_body.js";
 const ENDPOINTS = {
     authorization: {
@@ -237,6 +238,13 @@ export class AuthorizationServer extends ResourceServer {
         this.#introspectionClaims = options.introspectionClaims;
         this.#canIntrospectToken = options.canIntrospectToken;
     }
+    #handleEndpointError(error, prepare) {
+        const oauth2Error = toOAuth2Error(error);
+        prepare?.(oauth2Error);
+        if (this.throwOnError)
+            throw oauth2Error;
+        return oauth2ErrorResponse(oauth2Error);
+    }
     /**
      * Whether this instance will actually serve the OIDC surface: `true` once
      * `signingKeys` is set, which is what gates `id_token` issuance and the
@@ -441,7 +449,7 @@ export class AuthorizationServer extends ResourceServer {
             return await this.createTokenResponse(token, context, grant);
         }
         catch (error) {
-            return this.handleError(error, this.prepareClientAuthError(request));
+            return this.#handleEndpointError(error, this.prepareClientAuthError(request));
         }
     }
     /**
@@ -485,7 +493,7 @@ export class AuthorizationServer extends ResourceServer {
      */
     async handleOidcMetadataRequest(request) {
         if (!this.signingKeys) {
-            return this.handleError(new OAuth2Error(404, "OIDC issuance is not enabled", {
+            return this.#handleEndpointError(new OAuth2Error(404, "OIDC issuance is not enabled", {
                 extensions: { error: "not_found" },
             }));
         }
@@ -497,7 +505,7 @@ export class AuthorizationServer extends ResourceServer {
      */
     async handleJwksRequest(_request) {
         if (!this.signingKeys) {
-            return this.handleError(new OAuth2Error(404, "OIDC issuance is not enabled", {
+            return this.#handleEndpointError(new OAuth2Error(404, "OIDC issuance is not enabled", {
                 extensions: { error: "not_found" },
             }));
         }
@@ -512,7 +520,7 @@ export class AuthorizationServer extends ResourceServer {
             });
         }
         catch (error) {
-            return this.handleError(error);
+            return this.#handleEndpointError(error);
         }
     }
     /**
@@ -626,7 +634,7 @@ export class AuthorizationServer extends ResourceServer {
             return new Response(null, { status: 302, headers });
         }
         catch (error) {
-            return this.handleError(error);
+            return this.#handleEndpointError(error);
         }
     }
     // RP-Initiated Logout §2: parameters come from the GET query or POST body.
@@ -799,7 +807,7 @@ export class AuthorizationServer extends ResourceServer {
     }
     #authorizeErrorResponse(error, redirectUrl) {
         if (!redirectUrl || !(error instanceof Error) || !isOAuth2Error(error)) {
-            return this.handleError(error);
+            return this.#handleEndpointError(error);
         }
         const { searchParams } = redirectUrl;
         searchParams.set("error", error.extensions.error ?? "server_error");
@@ -958,7 +966,7 @@ export class AuthorizationServer extends ResourceServer {
             return new Response(null, { status: 200 });
         }
         catch (error) {
-            return this.handleError(error, this.prepareClientAuthError(request));
+            return this.#handleEndpointError(error, this.prepareClientAuthError(request));
         }
     }
     async #resolveToken(tokenService, value, hint) {
@@ -1086,7 +1094,7 @@ export class AuthorizationServer extends ResourceServer {
             });
         }
         catch (error) {
-            return this.handleError(error, this.prepareClientAuthError(request));
+            return this.#handleEndpointError(error, this.prepareClientAuthError(request));
         }
     }
     /**
@@ -1189,7 +1197,7 @@ export class AuthorizationServer extends ResourceServer {
             });
         }
         catch (error) {
-            return this.handleError(error);
+            return this.#handleEndpointError(error);
         }
     }
     /**
@@ -1244,7 +1252,7 @@ export class AuthorizationServer extends ResourceServer {
             });
         }
         catch (error) {
-            return this.handleError(error, this.prepareClientAuthError(request));
+            return this.#handleEndpointError(error, this.prepareClientAuthError(request));
         }
     }
 }

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

@@ -77,12 +77,24 @@ export interface ResourceServerOptions<Client extends ClientInterface, User, S e
      */
     maxTokenBodyBytes?: number;
     /**
-     * Format for error responses.
-     * - `"oauth2"` (default): Standard OAuth2 error format with `error`,
-     *   `error_description`, and `error_uri` fields.
-     * - `"problem-details"`: RFC 9457 Problem Details format with OAuth2
-     *   extensions. `type` and `error_uri` carry the same URI; `detail` and
-     *   `error_description` carry the same message.
+     * Format for protected-resource refusals: the responses from `protect()`,
+     * {@linkcode ResourceServer.handleAuthError} and
+     * {@linkcode ResourceServer.createErrorResponse}, including an
+     * authorization server's own protected resources such as UserInfo.
+     * - `"oauth2"` (default): `{ error, error_description?, error_uri? }` as
+     *   `application/json`.
+     * - `"problem-details"`: RFC 9457 Problem Details as
+     *   `application/problem+json`: `status`, `title`, `detail` (the message),
+     *   `type` when set, the OAuth2 `error` code and any other extension members
+     *   such as `requiredScope`. `error_description` and `error_uri` appear only
+     *   when the error sets them as extensions.
+     *
+     * Either way, a 401 or 403 from `protect()` or `handleAuthError` carries the
+     * `error` code and `error_description` in its `WWW-Authenticate` challenge.
+     *
+     * An authorization server's OAuth endpoints (token, revocation,
+     * introspection, device authorization, authorize, end-session, metadata and
+     * JWKS) ignore it and always answer in the RFC 6749 §5.2 format.
      */
     errorFormat?: "oauth2" | "problem-details";
     /**
@@ -160,7 +172,7 @@ export declare class ResourceServer<Client extends ClientInterface, User, S exte
     Scope: ScopeConstructor<S>;
     /** Protection space named in `WWW-Authenticate` challenges. */
     realm: string;
-    /** Body format used for error responses: OAuth2 or RFC 9457 problem details. */
+    /** 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;

package/dist/server/resource-server.js

@@ -9,6 +9,7 @@
 import { BasicScope } from "../models/scope.js";
 import { AccessDeniedError, InsufficientPermissionsError, InsufficientScopeError, InvalidTokenError, toOAuth2Error, } from "../errors.js";
 import { authorizationFromClaims, } from "../models/authorization.js";
+import { copyErrorHeaders, oauth2ErrorResponse } from "./_error-response.js";
 import { assertClockSkewSeconds } from "./_clock-skew.js";
 import { assertMaxBodyBytes, DEFAULT_MAX_TOKEN_BODY_BYTES, peekBoundedBody, } from "../utils/_body.js";
 /** Bearer token regex pattern. */
@@ -74,7 +75,7 @@ export class ResourceServer {
     Scope;
     /** Protection space named in `WWW-Authenticate` challenges. */
     realm;
-    /** Body format used for error responses: OAuth2 or RFC 9457 problem details. */
+    /** 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. */
     throwOnError;
@@ -179,32 +180,10 @@ export class ResourceServer {
      */
     createErrorResponse(error) {
         const oauth2Error = toOAuth2Error(error);
-        const response = this.errorFormat === "problem-details"
-            ? oauth2Error.getResponse()
-            : this.#createOAuth2ErrorResponse(oauth2Error);
-        for (const [key, value] of oauth2Error.headers) {
-            if (key.toLowerCase() === "content-type")
-                continue;
-            response.headers.set(key, value);
+        if (this.errorFormat !== "problem-details") {
+            return oauth2ErrorResponse(oauth2Error);
         }
-        return response;
-    }
-    #createOAuth2ErrorResponse(oauth2Error) {
-        const body = {
-            error: oauth2Error.extensions.error ?? "server_error",
-        };
-        const description = oauth2Error.extensions.error_description ?? oauth2Error.exposedMessage;
-        if (description) {
-            body.error_description = description;
-        }
-        const errorUri = oauth2Error.extensions.error_uri ?? oauth2Error.type;
-        if (errorUri) {
-            body.error_uri = errorUri;
-        }
-        return new Response(JSON.stringify(body), {
-            status: oauth2Error.status,
-            headers: { "Content-Type": "application/json;charset=UTF-8" },
-        });
+        return copyErrorHeaders(oauth2Error, oauth2Error.getResponse());
     }
     /**
      * Normalizes an error at a handler boundary and either rethrows it (when

package/package.json

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