@udibo/oauth2 0.25.0 → 0.26.0

package/README.md

@@ -1,13 +1,16 @@
 # @udibo/oauth2
 
-OAuth2 and OpenID Connect tools for TypeScript applications. Connect your app to
-Udibo's identity service, or host an authorization server for your own app. The
-package includes clients, authorization and resource servers, Hono middleware,
-React bindings, and optional login flows over your own database.
+[![npm version](https://img.shields.io/npm/v/@udibo/oauth2)](https://www.npmjs.com/package/@udibo/oauth2) [![JSR version](https://jsr.io/badges/@udibo/oauth2)](https://jsr.io/@udibo/oauth2) [![JSR score](https://jsr.io/badges/@udibo/oauth2/score)](https://jsr.io/@udibo/oauth2/score) [![CI](https://github.com/udibo/oauth2/actions/workflows/ci-cd.yml/badge.svg?branch=main)](https://github.com/udibo/oauth2/actions/workflows/ci-cd.yml?query=branch%3Amain) [![License: MIT](https://img.shields.io/npm/l/@udibo/oauth2)](LICENSE) [![npm downloads](https://img.shields.io/npm/dw/@udibo/oauth2)](https://www.npmjs.com/package/@udibo/oauth2) [![Node.js version](https://img.shields.io/node/v/@udibo/oauth2)](https://www.npmjs.com/package/@udibo/oauth2)
 
-Using Udibo's managed identity service requires a Udibo account; see
-[udibo.com](https://www.udibo.com/) for how to get one. The self-hosted examples
-run locally without a hosted account.
+OAuth2 and OpenID Connect tools for TypeScript applications: clients,
+authorization and resource servers, Hono middleware, React bindings, and
+optional login flows over your own database. It runs standalone in your own app:
+host an authorization server, protect an API, or sign users in through an
+OAuth2 or OpenID Connect issuer.
+
+The package also connects your app to Udibo's managed identity service, which
+requires a Udibo account; see [udibo.com](https://www.udibo.com/) for how to get
+one. The self-hosted examples run locally without a hosted account.
 
 ## Choose your path
 
@@ -25,77 +28,100 @@ run locally without a hosted account.
 ## Install
 
 The package supports Node.js 22 and later and ships ESM with type declarations.
-Install it from npm:
-
-```sh
-npm install @udibo/oauth2
-# or
-pnpm add @udibo/oauth2
-```
-
-It is also published to [JSR](https://jsr.io/@udibo/oauth2) as TypeScript
-source:
+It is published to npm, and to [JSR](https://jsr.io/@udibo/oauth2) as
+TypeScript source:
 
 ```sh
-npx jsr add @udibo/oauth2
-# or, with Deno
-deno add jsr:@udibo/oauth2
+npm install @udibo/oauth2   # or: pnpm add @udibo/oauth2
+npx jsr add @udibo/oauth2   # or, with Deno: deno add jsr:@udibo/oauth2
 ```
 
 `hono`, `react`, and `react-dom` are optional peer dependencies. Install the
 ones for the entrypoints you import: `hono` for the `/hono/*` adapters, `react`
 and `react-dom` for `/react` and `/react/components`. `vitest` is an optional
-peer dependency of the testing helpers.
+peer dependency of the testing helpers. Import the part you use; there is no
+root barrel or default export.
+
+## Protect an API
 
-Import the part you use; there is no root barrel or default export:
+This Hono API accepts JWT access tokens from your issuer and requires the
+`profile` scope. The [API protection guide](docs/guides/protect-an-api.md)
+covers token introspection and scope checks.
 
 ```ts
-import { BffClient, DirectClient } from "@udibo/oauth2/client";
-import { HonoBff } from "@udibo/oauth2/hono/bff";
+import { Hono } from "hono";
 import { HonoResourceServer } from "@udibo/oauth2/hono/resource-server";
+import { JwksTokenReader } from "@udibo/oauth2/server/resource";
+
+const tokenService = new JwksTokenReader({
+  issuer: "https://auth.example.com",
+  audience: "https://api.example.com",
+  getClient: (claims) => ({ id: String(claims.client_id) }),
+  getUser: (claims) => (claims.sub ? { id: claims.sub } : undefined),
+});
+const api = new HonoResourceServer({
+  resolve: () => ({ services: { tokenService } }),
+});
+
+const app = new Hono();
+app.get("/api/me", api.protect("profile"), (c) =>
+  c.json(api.getContext(c).user),
+);
 ```
 
-The package is pre-1.0. Minor releases may contain breaking changes; review the
-[stability policy](docs/stability.md) before upgrading.
+## Standards
+
+The package implements these specifications, with the limits noted:
+
+- [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749) OAuth 2.0: authorization
+  code, client credentials, refresh token, and password grants; no implicit grant.
+- [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750) bearer tokens in the
+  `Authorization` header or a form body, with `WWW-Authenticate` challenges.
+- [RFC 7636](https://www.rfc-editor.org/rfc/rfc7636) PKCE, `S256` unless you
+  register other methods.
+- [RFC 7009](https://www.rfc-editor.org/rfc/rfc7009) revocation,
+  [RFC 7662](https://www.rfc-editor.org/rfc/rfc7662) introspection,
+  [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414) server metadata, and
+  [RFC 8628](https://www.rfc-editor.org/rfc/rfc8628) device authorization.
+- [RFC 9207](https://www.rfc-editor.org/rfc/rfc9207) `iss` in authorization
+  responses. `DirectClient` and the BFF check it when the client is configured
+  with an `issuer`.
+- [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068) JWT access tokens, opt-in;
+  access tokens are opaque by default.
+- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html):
+  the authorization code flow, ES256 ID tokens, `nonce`, and UserInfo. The
+  server does not act on `prompt` or `max_age`.
+- OpenID Connect [Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)
+  and [RP-Initiated Logout 1.0](https://openid.net/specs/openid-connect-rpinitiated-1_0.html).
+- [OpenID Connect Back-Channel Logout 1.0](https://openid.net/specs/openid-connect-backchannel-1_0.html),
+  as a receiver in the BFF only. You supply the `logout_token` verifier, and the
+  server sends no logout tokens.
 
 ## How the pieces fit
 
-For a browser app, use a backend-for-frontend (BFF). The browser holds an
-HttpOnly session cookie; the BFF exchanges authorization codes and keeps access
-and refresh tokens on the server. `BffClient` connects the browser to the BFF,
-and the React adapter uses that same client.
-
-```mermaid
-sequenceDiagram
-    participant Browser
-    participant App as Your app / BFF
-    participant Issuer as Udibo or your app's authorization server
-    participant API as Your API
-    Browser->>App: Start sign-in
-    App-->>Browser: Redirect to authorization endpoint
-    Browser->>Issuer: Sign in
-    Issuer-->>Browser: Redirect back with code and state
-    Browser->>App: Complete callback
-    App->>Issuer: Exchange code with PKCE and client authentication
-    Issuer-->>App: Tokens
-    App-->>Browser: Session cookie
-    Browser->>App: Request application data
-    App->>API: Access token
-    API-->>Browser: Application data, through the BFF
-```
+For a browser app, use a backend-for-frontend (BFF), so tokens stay on the
+server. `BffClient` connects the browser to it, and the React adapter uses that
+same client:
 
-`DirectClient` is for a process that holds tokens: your backend, a CLI, a native
-app, or a public browser client. Supply a client secret only on the server. For
-a browser app with a backend, start with the BFF guide.
+1. The browser starts sign-in at your BFF, which redirects it to the issuer's
+   authorization endpoint.
+2. The user signs in, and the issuer redirects back with a code and `state`.
+3. The BFF exchanges the code, with PKCE and client authentication, for tokens.
+4. The BFF keeps the tokens and sets an HttpOnly session cookie.
+5. Later requests carry the cookie; the BFF calls your API with the access
+   token and returns the data.
+
+The [BFF guide](docs/guides/use-udibo.md#how-sign-in-flows) has this flow as a
+sequence diagram.
 
-`HonoResourceServer` validates access tokens and enforces scopes on API routes.
+`DirectClient` is for a process that holds tokens: your backend, a CLI, a native
+app, or a public browser client. Supply a client secret only on the server.
 `HonoAuthorizationServer` issues tokens when your app hosts its own
 authorization server. The framework-independent core accepts standard `Request`
 and `Response` objects; Hono adapters add routing and middleware.
 
-For app-owned login, `CaptchaProvider` and `verifyCaptcha` let your route check
-a client-issued bot-challenge token before calling `IdentityService`. The
-package does not include a challenge provider; see the
+For app-owned login, `verifyCaptcha` checks a bot-challenge token from a
+`CaptchaProvider` you supply before your route calls `IdentityService`; see the
 [CAPTCHA route example](docs/guides/add-login.md#captcha-at-the-route-boundary).
 
 ## Examples
@@ -163,11 +189,9 @@ checks a consumer of every entrypoint, and imports each one on Node.
 | `/testing`, `/testing/contract`, `/hono/bff/testing`, `/react/testing` | Tested; need Vitest   | Not supported                               | Not verified  |
 | `udibo-oauth2` command (`bin`)                                         | Tested                | Not supported                               | Not supported |
 
-The `udibo-oauth2` command is a development tool: `udibo-oauth2 oidc keygen`
-prints an OIDC signing key, and `udibo-oauth2 idp dev` runs a local identity
-provider. Run it with `npx udibo-oauth2` once the package is installed; the
-[local identity provider guide](docs/guides/run-a-local-identity-provider.md)
-covers its options. Nothing on the library path imports it.
+The `udibo-oauth2` development command prints OIDC signing keys (`oidc keygen`)
+and runs a [local identity provider](docs/guides/run-a-local-identity-provider.md)
+(`idp dev`). Nothing on the library path imports it.
 
 See [stability](docs/stability.md#runtime-support) for the support boundary.
 
@@ -184,6 +208,13 @@ cookie-session, OIDC, and optional-protection behavior. Identity feature
 examples apply to apps hosting their own login; Udibo clients use the hosted
 sign-in flow.
 
+## Upgrading
+
+The package is pre-1.0, so a minor release may contain breaking changes. Each
+release lists them under **⚠ BREAKING CHANGES** in [CHANGELOG.md](CHANGELOG.md).
+The [stability policy](docs/stability.md) says what counts as public API and
+what a patch release preserves.
+
 ## For coding agents
 
 Start with [llms.txt](llms.txt) for the task-to-guide map and integration rules.

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

@@ -289,15 +289,22 @@ export interface HonoBffBackchannelOptions {
 export interface BffCallbackError {
     /**
      * OAuth2-style error code: the IDP's `error` (e.g. `access_denied`),
-     * `invalid_request` (missing `code`/`state`, or a `state` this browser never
-     * started — see {@link HonoBffOptions.loginStateTtlMs}), or `invalid_grant`
+     * `invalid_request` (missing `code`/`state`, a `state` this browser never
+     * started — see {@link HonoBffOptions.loginStateTtlMs} — or an `iss` the
+     * client refused, see `DirectClient.verifyAuthorizationResponseIssuer`),
+     * `server_error` or `temporarily_unavailable` (discovery failed or
+     * `resolveOrigin` threw, so `iss` could not be checked; the description is
+     * fixed and the failure is in `cause`), or `invalid_grant`
      * (the code exchange failed — expired/replayed code, unknown `state` — or
      * a later step threw: `resolveUser` or the session store).
      */
     error: string;
     /** Human-readable description; never contains secrets. */
     error_description: string;
-    /** The thrown cause for the `invalid_grant` case; otherwise `undefined`. */
+    /**
+     * The thrown cause for the `invalid_grant` case and for an `iss` that was
+     * refused or could not be checked; otherwise `undefined`.
+     */
     cause?: unknown;
 }
 /** Options accepted by the {@link HonoBff} constructor. */
@@ -823,8 +830,9 @@ export declare class HonoBff {
      */
     loginHandler(): Handler;
     /**
-     * Callback handler — requires the login-state cookie to vouch for the
-     * returned `state`, then exchanges the code and opens a session.
+     * Callback handler — checks the response's `iss` (RFC 9207), requires the
+     * login-state cookie to vouch for the returned `state`, then exchanges the
+     * code and opens a session.
      */
     callbackHandler(): Handler;
     /** Logout handler — revokes the refresh token and clears the session cookie. */

package/dist/adapters/hono/bff/bff.js

@@ -60,6 +60,7 @@ import { DEFAULT_MAX_RETURN_TO_LENGTH, loginContinuation as computeLoginContinua
 import { resolveCookieName, resolvePrefixConstrainedAttributes, } from "./cookie-prefix.js";
 import { DEFAULT_SESSION_MAX_AGE_MS, sessionStoreMaxAgeMs, supportsBackchannelLogout, supportsRefreshLock, } from "./session-store.js";
 import { RotatedCookies } from "./_rotated-cookies.js";
+import { isIssuerRefusal } from "../../../client/_issuer-refusal.js";
 import { buildDownstreamHeaders, buildUpstreamHeaders, isInvalidTokenChallenge, resolveForwardHeaders, resolveProxyUrl, } from "./proxy.js";
 const DEFAULT_ROTATED_COOKIE_GRACE_MS = 10_000;
 const DEFAULT_ROTATED_COOKIE_MAX_ENTRIES = 1000;
@@ -686,8 +687,9 @@ export class HonoBff {
         };
     }
     /**
-     * Callback handler — requires the login-state cookie to vouch for the
-     * returned `state`, then exchanges the code and opens a session.
+     * Callback handler — checks the response's `iss` (RFC 9207), requires the
+     * login-state cookie to vouch for the returned `state`, then exchanges the
+     * code and opens a session.
      */
     callbackHandler() {
         return async (c) => {
@@ -699,6 +701,9 @@ export class HonoBff {
                     error: error.error,
                     error_description: error.error_description,
                 }, 400);
+            const issuerRefusal = await this.#issuerRefusal(c, params);
+            if (issuerRefusal)
+                return await fail(issuerRefusal);
             if (params.get("error")) {
                 return await fail({
                     error: params.get("error"),
@@ -777,6 +782,30 @@ export class HonoBff {
             }
         };
     }
+    async #issuerRefusal(c, params) {
+        try {
+            await this.#client.verifyAuthorizationResponseIssuer(params, {
+                origin: this.#options.resolveOrigin?.(c),
+            });
+            return undefined;
+        }
+        catch (cause) {
+            if (isIssuerRefusal(cause)) {
+                return {
+                    error: "invalid_request",
+                    error_description: cause.message,
+                    cause,
+                };
+            }
+            const unreachable = isOAuth2Error(cause) &&
+                cause.extensions.error === "temporarily_unavailable";
+            return {
+                error: unreachable ? "temporarily_unavailable" : "server_error",
+                error_description: "the authorization response issuer could not be checked",
+                cause,
+            };
+        }
+    }
     /** Logout handler — revokes the refresh token and clears the session cookie. */
     logoutHandler() {
         return async (c) => {

package/dist/client/_issuer-refusal.d.ts

@@ -0,0 +1,3 @@
+import { type OAuth2Error } from "../errors.ts";
+export declare function issuerRefusal(message: string): OAuth2Error;
+export declare function isIssuerRefusal(error: unknown): error is OAuth2Error;

package/dist/client/_issuer-refusal.js

@@ -0,0 +1,10 @@
+import { InvalidRequestError } from "../errors.js";
+const refusals = new WeakSet();
+export function issuerRefusal(message) {
+    const error = new InvalidRequestError(message);
+    refusals.add(error);
+    return error;
+}
+export function isIssuerRefusal(error) {
+    return error instanceof Error && refusals.has(error);
+}

package/dist/client/direct-client.d.ts

@@ -161,6 +161,15 @@ export interface AuthorizationRedirect {
     /** Opaque `state` value the callback will echo back. */
     state: string;
 }
+/** Options accepted by {@link DirectClient.verifyAuthorizationResponseIssuer}. */
+export interface VerifyIssuerOptions {
+    /**
+     * The origin {@link DirectClient.login} retargeted the authorize URL at, if
+     * any. The issuer moved to that origin, path kept, is accepted as well as
+     * the discovered one.
+     */
+    origin?: string;
+}
 /** Result of {@link DirectClient.handleAuthorizationCallback}. */
 export interface AuthorizationCallbackResult {
     /** Token bundle saved on the client. */
@@ -402,13 +411,20 @@ export declare class DirectClient extends OAuth2ClientBase {
      * than redeeming the single-use code twice. A call after it settles redeems
      * again, and fails.
      *
+     * The response's `iss` is checked first, error responses included, as
+     * {@link verifyAuthorizationResponseIssuer} describes. A refused response
+     * is never redeemed.
+     *
      * @param input The callback URL, its query string, or the parsed params.
+     * @param options The `origin` given to {@link login}, when it retargeted
+     * the authorize URL, so the issuer at that origin is accepted as `iss`.
      * @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 {InvalidRequestError} when the response's `iss` is refused.
      * @throws {TypeError} when `code` or `state` is missing, or outside a
      * browser when the client has no `authRequestStorage` or no
      * `refreshTokenStorage`; checked before the pending request is claimed.
@@ -425,7 +441,39 @@ export declare class DirectClient extends OAuth2ClientBase {
      * location.replace(returnTo ?? "/");
      * ```
      */
-    handleAuthorizationCallback(input: URL | URLSearchParams | string): Promise<AuthorizationCallbackResult>;
+    handleAuthorizationCallback(input: URL | URLSearchParams | string, options?: VerifyIssuerOptions): Promise<AuthorizationCallbackResult>;
+    /**
+     * Checks an authorization response's `iss` parameter (RFC 9207), which
+     * tells a client that signs in with more than one authorization server
+     * which of them answered. {@link handleAuthorizationCallback} calls it; a
+     * server that completes the flow with {@link exchangeAuthorizationCode}
+     * calls it first, on every response, error responses included.
+     *
+     * For a client configured with an `issuer`, it refuses an `iss` that is
+     * not exactly the discovered issuer, an `iss` given more than once, and a
+     * missing `iss` when the metadata advertises
+     * `authorization_response_iss_parameter_supported: true`. A missing `iss`
+     * is accepted from a server that does not advertise it. A client
+     * configured with `endpoints` has no issuer to compare against, so it
+     * accepts every response.
+     *
+     * @param input The callback URL, its query string, or the parsed params.
+     * @param options The `origin` the authorize URL was retargeted at, if any.
+     * @throws {InvalidRequestError} when the response is refused.
+     * @throws {ServerError} when discovery fails.
+     * @throws {TemporarilyUnavailableError} when the discovery endpoint cannot
+     * be reached.
+     *
+     * @example
+     * ```ts
+     * import { DirectClient } from "@udibo/oauth2/client";
+     *
+     * declare const client: DirectClient;
+     * declare const callbackUrl: string;
+     * await client.verifyAuthorizationResponseIssuer(callbackUrl);
+     * ```
+     */
+    verifyAuthorizationResponseIssuer(input: URL | URLSearchParams | string, options?: VerifyIssuerOptions): Promise<void>;
     /**
      * **Advanced (BFF / multi-session servers).** SPA, mobile, and CLI consumers
      * should call {@link handleAuthorizationCallback} instead — that variant
@@ -444,7 +492,8 @@ export declare class DirectClient extends OAuth2ClientBase {
      * two callbacks racing on one `state` reach the token endpoint at most once
      * (atomically so for a storage that implements
      * {@link AuthRequestStorage.take}). Emits nothing — the caller owns session
-     * semantics.
+     * semantics. It does not see the response's `iss`: call
+     * {@link verifyAuthorizationResponseIssuer} before it.
      *
      * @param code The authorization code from the callback.
      * @param state The `state` the callback echoed back.

package/dist/client/direct-client.js

@@ -19,6 +19,7 @@ import { sanitizeProviderText } from "../utils/text.js";
 import { assertField, assertTokenResponse, errorFromResponse, receiveJson, sendGuarded, } from "./_http.js";
 import { mergedHeaders, OAuth2ClientBase, SIGNED_OUT, } from "./base.js";
 import { SessionStorageAuthRequestStorage } from "./browser-storage.js";
+import { issuerRefusal } from "./_issuer-refusal.js";
 import { DEFAULT_DISCOVERY_TTL_MS, } from "./discovery-cache.js";
 import { MemoryAuthRequestStorage, MemoryRefreshTokenStorage, MemoryTokenStorage, } from "./storage.js";
 const REFRESH_SKEW_MS = 30_000;
@@ -383,13 +384,20 @@ export class DirectClient extends OAuth2ClientBase {
      * than redeeming the single-use code twice. A call after it settles redeems
      * again, and fails.
      *
+     * The response's `iss` is checked first, error responses included, as
+     * {@link verifyAuthorizationResponseIssuer} describes. A refused response
+     * is never redeemed.
+     *
      * @param input The callback URL, its query string, or the parsed params.
+     * @param options The `origin` given to {@link login}, when it retargeted
+     * the authorize URL, so the issuer at that origin is accepted as `iss`.
      * @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 {InvalidRequestError} when the response's `iss` is refused.
      * @throws {TypeError} when `code` or `state` is missing, or outside a
      * browser when the client has no `authRequestStorage` or no
      * `refreshTokenStorage`; checked before the pending request is claimed.
@@ -406,22 +414,12 @@ export class DirectClient extends OAuth2ClientBase {
      * location.replace(returnTo ?? "/");
      * ```
      */
-    handleAuthorizationCallback(input) {
+    handleAuthorizationCallback(input, options = {}) {
         const params = toSearchParams(input);
+        const { origin } = options;
         const error = params.get("error");
-        if (error) {
-            const description = params.get("error_description") ?? undefined;
-            const errorUri = params.get("error_uri") ?? undefined;
-            const instance = new OAuth2ErrorClass(description ?? "authorization error", {
-                extensions: {
-                    error,
-                    error_description: description,
-                    error_uri: errorUri,
-                },
-            });
-            this.emit({ type: "error", error: instance });
-            return Promise.reject(instance);
-        }
+        if (error)
+            return this.#rejectAuthorizationError(error, params, origin);
         try {
             this.#requireAuthRequestStorage();
             this.#requireRefreshTokenStorage();
@@ -439,19 +437,91 @@ export class DirectClient extends OAuth2ClientBase {
         const existing = this.#callbackPromises.get(code);
         if (existing)
             return existing;
-        const promise = this.#exchangeCode(code, state);
+        const promise = this.#exchangeCode(code, state, params, origin);
         this.#callbackPromises.set(code, promise);
         const cleanup = () => queueMicrotask(() => this.#callbackPromises.delete(code));
         promise.then(cleanup, cleanup);
         return promise;
     }
-    async #exchangeCode(code, state) {
+    async #rejectAuthorizationError(code, params, origin) {
+        const error = (await this.#issuerRefusal(params, origin)) ??
+            authorizationResponseError(code, params);
+        this.emit({ type: "error", error });
+        throw error;
+    }
+    async #exchangeCode(code, state, params, origin) {
         const version = ++this.#sessionVersion;
+        const refusal = await this.#issuerRefusal(params, origin);
+        if (refusal) {
+            this.emit({ type: "error", error: refusal });
+            throw refusal;
+        }
         const result = await this.exchangeAuthorizationCode(code, state);
         const tokens = await this.#saveTokens(result.raw, version);
         this.emit({ type: "authenticated", tokens });
         return { tokens, returnTo: result.returnTo };
     }
+    /**
+     * Checks an authorization response's `iss` parameter (RFC 9207), which
+     * tells a client that signs in with more than one authorization server
+     * which of them answered. {@link handleAuthorizationCallback} calls it; a
+     * server that completes the flow with {@link exchangeAuthorizationCode}
+     * calls it first, on every response, error responses included.
+     *
+     * For a client configured with an `issuer`, it refuses an `iss` that is
+     * not exactly the discovered issuer, an `iss` given more than once, and a
+     * missing `iss` when the metadata advertises
+     * `authorization_response_iss_parameter_supported: true`. A missing `iss`
+     * is accepted from a server that does not advertise it. A client
+     * configured with `endpoints` has no issuer to compare against, so it
+     * accepts every response.
+     *
+     * @param input The callback URL, its query string, or the parsed params.
+     * @param options The `origin` the authorize URL was retargeted at, if any.
+     * @throws {InvalidRequestError} when the response is refused.
+     * @throws {ServerError} when discovery fails.
+     * @throws {TemporarilyUnavailableError} when the discovery endpoint cannot
+     * be reached.
+     *
+     * @example
+     * ```ts
+     * import { DirectClient } from "@udibo/oauth2/client";
+     *
+     * declare const client: DirectClient;
+     * declare const callbackUrl: string;
+     * await client.verifyAuthorizationResponseIssuer(callbackUrl);
+     * ```
+     */
+    async verifyAuthorizationResponseIssuer(input, options = {}) {
+        const refusal = await this.#issuerRefusal(toSearchParams(input), options.origin);
+        if (refusal)
+            throw refusal;
+    }
+    async #issuerRefusal(params, origin) {
+        if (!this.#issuer)
+            return undefined;
+        const metadata = await this.discover();
+        const received = params.getAll("iss");
+        if (received.length > 1) {
+            return issuerRefusal("the authorization response carries more than one `iss` (RFC 9207)");
+        }
+        const [iss] = received;
+        if (iss === undefined) {
+            if (metadata.authorization_response_iss_parameter_supported !== true) {
+                return undefined;
+            }
+            return issuerRefusal("the authorization response is missing `iss`, which the issuer " +
+                "advertises with `authorization_response_iss_parameter_supported` " +
+                "(RFC 9207 §2.4)");
+        }
+        const accepted = [metadata.issuer];
+        if (origin)
+            accepted.push(issuerAtOrigin(metadata.issuer, origin));
+        if (accepted.includes(iss))
+            return undefined;
+        return issuerRefusal("the authorization response `iss` does not match the issuer the " +
+            "request was sent to (RFC 9207 §2.4)");
+    }
     /**
      * **Advanced (BFF / multi-session servers).** SPA, mobile, and CLI consumers
      * should call {@link handleAuthorizationCallback} instead — that variant
@@ -470,7 +540,8 @@ export class DirectClient extends OAuth2ClientBase {
      * two callbacks racing on one `state` reach the token endpoint at most once
      * (atomically so for a storage that implements
      * {@link AuthRequestStorage.take}). Emits nothing — the caller owns session
-     * semantics.
+     * semantics. It does not see the response's `iss`: call
+     * {@link verifyAuthorizationResponseIssuer} before it.
      *
      * @param code The authorization code from the callback.
      * @param state The `state` the callback echoed back.
@@ -1249,6 +1320,19 @@ function metadataToEndpoints(meta) {
         out.endSession = meta.end_session_endpoint;
     return out;
 }
+function authorizationResponseError(error, params) {
+    const description = params.get("error_description") ?? undefined;
+    return new OAuth2ErrorClass(description ?? "authorization error", {
+        extensions: {
+            error,
+            error_description: description,
+            error_uri: params.get("error_uri") ?? undefined,
+        },
+    });
+}
+function issuerAtOrigin(issuer, origin) {
+    return `${new URL(origin).origin}${issuer.slice(new URL(issuer).origin.length)}`;
+}
 function toSearchParams(input) {
     if (input instanceof URLSearchParams)
         return input;

package/dist/client/mod.d.ts

@@ -27,7 +27,7 @@
  */
 export { type BaseLoginOptions, type BaseOptions, type LoginRedirect, type LogoutOptions, type LogoutRedirect, OAuth2ClientBase, type SessionState, SIGNED_OUT, type UserInfoClaims, } from "./base.ts";
 export { BffClient, type BffClientOptions, type BffEndpoints, } from "./bff-client.ts";
-export { type AuthorizationCallbackResult, type AuthorizationRedirect, type AuthorizationServerEndpoints, type DeviceAuthorizationOptions, DirectClient, type DirectClientOptions, type ExchangeOptions, type ExchangeResult, type IntrospectionResult, type LoginOptions, type PollDeviceTokenOptions, } from "./direct-client.ts";
+export { type AuthorizationCallbackResult, type AuthorizationRedirect, type AuthorizationServerEndpoints, type DeviceAuthorizationOptions, DirectClient, type DirectClientOptions, type ExchangeOptions, type ExchangeResult, type IntrospectionResult, type LoginOptions, type PollDeviceTokenOptions, type VerifyIssuerOptions, } from "./direct-client.ts";
 export { DEFAULT_DISCOVERY_CACHE_MAX_ENTRIES, DEFAULT_DISCOVERY_TTL_MS, type DiscoveryCache, type DiscoveryCacheEntry, MemoryDiscoveryCache, type MemoryDiscoveryCacheOptions, } from "./discovery-cache.ts";
 export { type AuthenticatedEvent, type ErrorEvent, type LoggedOutEvent, type OAuth2ClientEvent, type OAuth2ClientEventListener, type TokenRefreshedEvent, } from "./events.ts";
 export { type AuthRequestRecord, type AuthRequestStorage, MemoryAuthRequestStorage, type MemoryAuthRequestStorageOptions, MemoryRefreshTokenStorage, MemoryTokenStorage, type RefreshTokenStorage, type TokenBundle, type TokenStorage, } from "./storage.ts";

package/dist/models/responses.d.ts

@@ -61,6 +61,11 @@ export interface AuthorizationServerMetadata {
     scopes_supported?: string[];
     /** Supported response types. */
     response_types_supported?: string[];
+    /**
+     * Whether every authorization response carries the `iss` parameter
+     * (RFC 9207 §3). A client that sees `true` refuses a response without one.
+     */
+    authorization_response_iss_parameter_supported?: boolean;
     /** Supported grant types. */
     grant_types_supported?: string[];
     /** URL of the JWKS document (OIDC Discovery / RFC 8414). */

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

@@ -610,6 +610,11 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * responses from this endpoint, since there is no verified place to send the
      * user back to.
      *
+     * Every redirect to the client, the code and the error alike, carries `iss`
+     * set to the request's resolved issuer (RFC 9207), replacing any `iss` the
+     * registered `redirect_uri` itself carries. A request that resolves no
+     * `issuer` sends none.
+     *
      * Requires a grant extending {@linkcode AuthorizationCodeGrant} registered
      * under `authorization_code`; without one the endpoint answers 500
      * `server_error` (or rethrows, with `throwOnError`).
@@ -719,7 +724,9 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * authorization code grant's own `challengeMethods`, so a server that
      * registers an extra method (or drops `S256`) advertises what it will
      * actually accept. It is omitted entirely when no authorization code grant
-     * is registered, since PKCE has nothing to apply to.
+     * is registered, since PKCE has nothing to apply to. The same condition
+     * governs `authorization_response_iss_parameter_supported: true`
+     * (RFC 9207 §3): the authorization endpoint's redirects carry `iss`.
      *
      * `token_endpoint_auth_methods_supported` always includes `none`, the
      * RFC 7591 method for a client with no secret. The token endpoint accepts it

package/dist/server/authorization-server.js

@@ -134,6 +134,11 @@ export const ENDPOINT_PATHS = Object.fromEntries(ENDPOINT_ENTRIES.map(([key, { p
  * ```
  */
 export const ENDPOINT_METHODS = Object.fromEntries(ENDPOINT_ENTRIES.map(([key, { methods }]) => [key, methods]));
+function authorizationResponseRedirect(target) {
+    if (target.issuer)
+        target.url.searchParams.set("iss", target.issuer);
+    return Response.redirect(target.url.toString(), 302);
+}
 function isAuthorizationCodeGrant(grant) {
     return grant instanceof AuthorizationCodeGrant;
 }
@@ -742,6 +747,11 @@ export class AuthorizationServer extends ResourceServer {
      * responses from this endpoint, since there is no verified place to send the
      * user back to.
      *
+     * Every redirect to the client, the code and the error alike, carries `iss`
+     * set to the request's resolved issuer (RFC 9207), replacing any `iss` the
+     * registered `redirect_uri` itself carries. A request that resolves no
+     * `issuer` sends none.
+     *
      * Requires a grant extending {@linkcode AuthorizationCodeGrant} registered
      * under `authorization_code`; without one the endpoint answers 500
      * `server_error` (or rethrows, with `throwOnError`).
@@ -757,16 +767,17 @@ export class AuthorizationServer extends ResourceServer {
             return await this.#authorize(request, target, authenticateUser, handleConsent);
         }
         catch (error) {
-            return this.#authorizeErrorResponse(error, target.url);
+            return this.#authorizeErrorResponse(error, target);
         }
     }
     async #authorize(request, target, authenticateUser, handleConsent) {
         const params = this.parseAuthorizeParameters(request);
         const grant = this.#authorizationCodeGrant();
-        const { services } = await this.authorizationContext(request);
+        const { services, issuer } = await this.authorizationContext(request);
         const client = await this.#resolveAuthorizeClient(grant, params.clientId, services);
         const redirectUrl = this.#resolveRedirectTarget(client, params.redirectUri);
         target.url = redirectUrl;
+        target.issuer = issuer;
         if (!params.state) {
             throw new InvalidRequestError("state required");
         }
@@ -807,9 +818,10 @@ export class AuthorizationServer extends ResourceServer {
             authenticationContext,
         }, request);
         redirectUrl.searchParams.set("code", authorizationCode.code);
-        return Response.redirect(redirectUrl.toString(), 302);
+        return authorizationResponseRedirect({ url: redirectUrl, issuer });
     }
-    #authorizeErrorResponse(error, redirectUrl) {
+    #authorizeErrorResponse(error, target) {
+        const redirectUrl = target.url;
         if (!redirectUrl || !(error instanceof Error) || !isOAuth2Error(error)) {
             return this.#handleEndpointError(error);
         }
@@ -824,7 +836,10 @@ export class AuthorizationServer extends ResourceServer {
         if (errorUri) {
             searchParams.set("error_uri", errorUri);
         }
-        return Response.redirect(redirectUrl.toString(), 302);
+        return authorizationResponseRedirect({
+            url: redirectUrl,
+            issuer: target.issuer,
+        });
     }
     #authorizationCodeGrant() {
         const grant = this.grants[AUTHORIZATION_CODE_GRANT_TYPE];
@@ -1136,7 +1151,9 @@ export class AuthorizationServer extends ResourceServer {
      * authorization code grant's own `challengeMethods`, so a server that
      * registers an extra method (or drops `S256`) advertises what it will
      * actually accept. It is omitted entirely when no authorization code grant
-     * is registered, since PKCE has nothing to apply to.
+     * is registered, since PKCE has nothing to apply to. The same condition
+     * governs `authorization_response_iss_parameter_supported: true`
+     * (RFC 9207 §3): the authorization endpoint's redirects carry `iss`.
      *
      * `token_endpoint_auth_methods_supported` always includes `none`, the
      * RFC 7591 method for a client with no secret. The token endpoint accepts it
@@ -1178,6 +1195,9 @@ export class AuthorizationServer extends ResourceServer {
             metadata.code_challenge_methods_supported = challengeMethods;
         }
         metadata.response_types_supported = hasAuthCodeGrant ? ["code"] : [];
+        if (hasAuthCodeGrant) {
+            metadata.authorization_response_iss_parameter_supported = true;
+        }
         const scopesSupported = context.scopesSupported ?? this.scopesSupported;
         if (scopesSupported) {
             metadata.scopes_supported = scopesSupported;

package/package.json

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