@udibo/oauth2 0.25.0 → 0.27.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,102 @@ 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`, UserInfo, and the
+  `prompt`, `max_age` and `acr_values` controls, with `auth_time` and `acr` in
+  the ID token. Your login callback performs any re-authentication they need,
+  and there is no `claims` request parameter.
+- 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 +191,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 +210,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/authorization-server.d.ts

@@ -35,7 +35,7 @@
 import { Hono } from "hono";
 import type { Context, Handler, MiddlewareHandler } from "hono";
 import type { RequireConditions } from "../../models/authorization.ts";
-import type { AuthenticationContext } from "../../models/authentication.ts";
+import type { AuthenticationContext, AuthenticationRequest } from "../../models/authentication.ts";
 import type { ClientInterface } from "../../models/client.ts";
 import type { AbstractScope, BasicScope } from "../../models/scope.ts";
 import { AuthorizationServer, type AuthorizationServerOptions } from "../../server/authorization-server.ts";
@@ -47,20 +47,29 @@ import type { AuthenticatedContext } from "../../server/resource-server.ts";
  * or session variables without reconstructing a {@link Request}. Return one
  * of:
  *
- * - `{ user, authorizedScope?, authenticationContext? }` — user is authenticated;
- *   the authorize flow continues. Supply only verified event claims in
- *   `authenticationContext`; the code and its tokens retain that snapshot.
+ * - `{ user, authorizedScope?, authenticationContext?, reauthenticated? }` —
+ *   user is authenticated; the authorize flow continues. Supply only verified
+ *   event claims in `authenticationContext`; the code and its tokens retain
+ *   that snapshot. Set `reauthenticated: true` only when the user actively
+ *   authenticated in response to this authorization request.
  * - `null` — explicit denial; the framework redirects to `redirect_uri` with
  *   `error=access_denied`.
  * - A `Response` (typically `c.redirect(...)` to a login page) —
  *   short-circuits the authorize flow and is returned to the browser as-is.
  *   This is how login redirects, interstitials, etc. are wired without
- *   wrapping the framework handler.
+ *   wrapping the framework handler. Under `prompt=none` the server answers
+ *   `login_required` instead.
+ *
+ * The second argument, always passed, carries the request's validated
+ * `prompt`, `max_age` and `acr_values`. The server answers `login_required`
+ * when the returned user fails `satisfiesAuthenticationRequest`, so send the
+ * user to sign in again whenever the session cannot meet it.
  */
-export type HonoAuthenticateUserFn<User> = (c: Context) => Promise<{
+export type HonoAuthenticateUserFn<User> = (c: Context, authentication?: AuthenticationRequest) => Promise<{
     user: User;
     authorizedScope?: AbstractScope;
     authenticationContext?: AuthenticationContext;
+    reauthenticated?: boolean;
 } | Response | null>;
 /**
  * Collects consent from the resource owner for the requested scope.
@@ -76,9 +85,13 @@ export type HonoAuthenticateUserFn<User> = (c: Context) => Promise<{
  * - A `Response` (typically `c.html(...)` rendering a consent page) —
  *   short-circuits the authorize flow and is returned to the browser as-is.
  *   The consent UI should resubmit to the authorize endpoint with a
- *   decision parameter the callback can read on the next request.
+ *   decision parameter the callback can read on the next request. Under
+ *   `prompt=none` the server answers `consent_required` instead.
+ *
+ * With `prompt=consent` the server calls it even when the scope is already
+ * authorized, and the fifth argument, always passed, says so.
  */
-export type HonoHandleConsentFn<Client extends ClientInterface, S extends AbstractScope> = (c: Context, client: Client, requestedScope: S | undefined, user: unknown) => Promise<{
+export type HonoHandleConsentFn<Client extends ClientInterface, S extends AbstractScope> = (c: Context, client: Client, requestedScope: S | undefined, user: unknown, authentication?: AuthenticationRequest) => Promise<{
     approved: boolean;
     scope?: S;
 } | Response>;

package/dist/adapters/hono/authorization-server.js

@@ -104,9 +104,9 @@ export class HonoAuthorizationServer extends AuthorizationServer {
     authorizeHandler(options) {
         const { authenticateUser, handleConsent } = options;
         return (c) => {
-            const auth = () => authenticateUser(c);
+            const auth = (_request, authentication) => authenticateUser(c, authentication);
             const consent = handleConsent
-                ? (client, requestedScope, user) => handleConsent(c, client, requestedScope, user)
+                ? (client, requestedScope, user, authentication) => handleConsent(c, client, requestedScope, user, authentication)
                 : undefined;
             return this.handleAuthorizeRequest(c.req.raw, auth, consent);
         };

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/cli/idp/server.js

@@ -21,6 +21,7 @@ import { AuthorizationCodeGrant } from "../../server/grants/authorization-code.j
 import { ClientCredentialsGrant } from "../../server/grants/client-credentials.js";
 import { PasswordGrant } from "../../server/grants/password.js";
 import { RefreshTokenGrant } from "../../server/grants/refresh-token.js";
+import { satisfiesAuthenticationRequest } from "../../server/authentication-request.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";
@@ -43,6 +44,14 @@ const WILDCARD_HOSTNAMES = new Set(["0.0.0.0", "::", "[::]"]);
 export function isLoopbackHostname(hostname) {
     return LOOPBACK_HOSTNAMES.has(hostname) || hostname.startsWith("127.");
 }
+const REAUTHENTICATION_WINDOW_SECONDS = 600;
+function newSession(userId, signedInFor) {
+    return {
+        userId,
+        authTime: Math.floor(Date.now() / 1000),
+        ...(signedInFor === undefined ? {} : { signedInFor }),
+    };
+}
 async function createState(config, signingKey, issuer) {
     const userService = new MemoryUserService();
     const clientService = new MemoryClientService(userService);
@@ -181,21 +190,33 @@ function formValue(form, name) {
     const value = form.get(name);
     return typeof value === "string" ? value : undefined;
 }
-async function currentUser(state, request) {
+function currentSession(state, request) {
     const sessionId = readCookie(request, SESSION_COOKIE);
-    if (!sessionId)
-        return undefined;
-    const userId = state.sessions.get(sessionId);
-    if (!userId)
-        return undefined;
-    return await state.userService.get(userId);
+    return sessionId ? state.sessions.get(sessionId) : undefined;
+}
+async function currentUser(state, request) {
+    const session = currentSession(state, request);
+    return session ? await state.userService.get(session.userId) : undefined;
 }
 function authenticateUserFor(state, config, request) {
-    return async () => {
-        const user = await currentUser(state, request);
-        if (user)
-            return { user };
-        return htmlResponse(loginPage({ returnTo: pathAndQuery(request), users: config.users }));
+    return async (_request, authentication) => {
+        const returnTo = pathAndQuery(request);
+        const session = currentSession(state, request);
+        const user = session && (await state.userService.get(session.userId));
+        if (session && user) {
+            const result = {
+                user,
+                authenticationContext: { auth_time: session.authTime },
+                reauthenticated: session.signedInFor === returnTo &&
+                    Math.floor(Date.now() / 1000) - session.authTime <=
+                        REAUTHENTICATION_WINDOW_SECONDS,
+            };
+            if (!authentication ||
+                satisfiesAuthenticationRequest(authentication, result)) {
+                return result;
+            }
+        }
+        return htmlResponse(loginPage({ returnTo, users: config.users }));
     };
 }
 function handleConsentFor(state, request) {
@@ -258,7 +279,7 @@ async function handleLoginSubmission(state, config, request) {
         return htmlResponse(loginPage({ returnTo, users: config.users, error }), 401);
     }
     const sessionId = crypto.randomUUID();
-    state.sessions.set(sessionId, user.id);
+    state.sessions.set(sessionId, newSession(user.id, returnTo));
     return redirect(returnTo, {
         "set-cookie": cookie(SESSION_COOKIE, sessionId),
     });
@@ -334,7 +355,7 @@ async function handleAdminSession(state, request) {
         return jsonError(400, 'no seeded user matched "userId" or "username"');
     }
     const sessionId = crypto.randomUUID();
-    state.sessions.set(sessionId, user.id);
+    state.sessions.set(sessionId, newSession(user.id));
     return new Response(JSON.stringify({
         sessionId,
         cookie: SESSION_COOKIE,

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.