@udibo/oauth2 0.27.0 → 0.28.0

package/README.md

@@ -85,7 +85,7 @@ The package implements these specifications, with the limits noted:
   [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`.
+  with an `issuer`, and so do the external sign-in connectors.
 - [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):

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

@@ -296,7 +296,9 @@ export interface BffCallbackError {
      * `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).
+     * a later step threw: `resolveUser` or the session store), or
+     * `login_required` (a pinned `max_age` and an ID token whose `auth_time`
+     * does not satisfy it — see {@link HonoBffOptions.extraParams}).
      */
     error: string;
     /** Human-readable description; never contains secrets. */
@@ -514,7 +516,18 @@ export interface HonoBffOptions {
      * value, name it in {@link forwardedParams} instead.
      *
      * `prompt` is an ordinary name here — pin `{ prompt: "login" }` to make
-     * every sign-in re-authenticate. A pinned `scope` is accepted only when
+     * every sign-in re-authenticate. A pinned `max_age` must be a non-negative
+     * integer, and `/auth/callback` then checks the ID token's `auth_time`
+     * (OpenID Connect Core §3.1.3.7): a sign-in whose `auth_time` is missing,
+     * more than 60 seconds in the future, or older than `max_age` plus those
+     * 60 seconds (an allowance for clock skew between the BFF and the
+     * authorization server) fails with
+     * `login_required`. `max_age=0` means `prompt=login`, so it needs
+     * `auth_time` but no particular age. A token response without an ID token
+     * is not checked, unless {@link HonoBffOptions.forwardedParams} names
+     * `scope`: the browser could then leave out `openid` to skip the check, so
+     * a missing ID token fails with `login_required` too. A pinned `scope` is
+     * accepted only when
      * {@link scope} is unset; setting both would leave which one applies
      * ambiguous. Either configuration supplies the scope the login flow records
      * for its authorization request.
@@ -744,9 +757,10 @@ export declare class HonoBff {
      * {@linkcode HonoBffOptions.forwardedParams} names a reserved authorize
      * parameter, gives one a name that is empty or not equal to its trimmed
      * form (`" state"` and `"organization "` are refused rather than trimmed),
-     * names the same parameter in both, or pins `scope` in
+     * names the same parameter in both, pins `scope` in
      * {@linkcode HonoBffOptions.extraParams} while
-     * {@linkcode HonoBffOptions.scope} is also set.
+     * {@linkcode HonoBffOptions.scope} is also set, or pins a `max_age` that is
+     * not a non-negative integer.
      */
     constructor(options: HonoBffOptions);
     /**

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

@@ -150,6 +150,47 @@ const RESERVED_AUTHORIZE_PARAMS = [
     "request_uri",
 ];
 const RESERVED_AUTHORIZE_PARAM_SET = new Set(RESERVED_AUTHORIZE_PARAMS);
+const AUTH_TIME_LEEWAY_SECONDS = 60;
+function pinnedMaxAge(fixed) {
+    let strictest;
+    for (const [name, value] of Object.entries(fixed)) {
+        if (name.toLowerCase() !== "max_age" || value === "")
+            continue;
+        const seconds = Number(value);
+        if (!/^\d+$/.test(value) || !Number.isSafeInteger(seconds)) {
+            throw new Error(`extraParams pins ${JSON.stringify(name)} to ${JSON.stringify(value)}, ` +
+                "which is not a non-negative integer number of seconds. The " +
+                "authorization server refuses such a max_age, and the callback " +
+                "could not check the ID token's auth_time against it.");
+        }
+        strictest =
+            strictest === undefined ? seconds : Math.min(strictest, seconds);
+    }
+    return strictest;
+}
+class CallbackRefusal extends Error {
+    refusal;
+    constructor(refusal) {
+        super(refusal.error_description);
+        this.refusal = refusal;
+    }
+}
+function authTimeShortfall(claims, maxAge, now) {
+    const authTime = typeof claims === "object" && claims !== null
+        ? claims.auth_time
+        : undefined;
+    if (typeof authTime !== "number" || !Number.isFinite(authTime)) {
+        return "the ID token has no auth_time, which the max_age this sign-in requested requires";
+    }
+    const age = Math.floor(now / 1000) - authTime;
+    if (age < -AUTH_TIME_LEEWAY_SECONDS) {
+        return "the ID token's auth_time is in the future";
+    }
+    if (maxAge > 0 && age > maxAge + AUTH_TIME_LEEWAY_SECONDS) {
+        return "the ID token's auth_time is older than the max_age this sign-in requested";
+    }
+    return undefined;
+}
 function assertUsableAuthorizeParamName(name, option) {
     if (name === "" || name !== name.trim()) {
         throw new Error(`${option} may not use ${JSON.stringify(name)} as an ` +
@@ -207,7 +248,12 @@ function resolveExtraAuthorizeParams(options) {
                 "alone.");
         }
     }
-    return { fixed, forwarded };
+    return {
+        fixed,
+        forwarded,
+        maxAge: pinnedMaxAge(fixed),
+        scopeForwarded: forwarded.some((name) => name.toLowerCase() === "scope"),
+    };
 }
 function authorizeParamsForRequest(resolved, requestParams) {
     const entries = Object.entries(resolved.fixed);
@@ -365,9 +411,10 @@ export class HonoBff {
      * {@linkcode HonoBffOptions.forwardedParams} names a reserved authorize
      * parameter, gives one a name that is empty or not equal to its trimmed
      * form (`" state"` and `"organization "` are refused rather than trimmed),
-     * names the same parameter in both, or pins `scope` in
+     * names the same parameter in both, pins `scope` in
      * {@linkcode HonoBffOptions.extraParams} while
-     * {@linkcode HonoBffOptions.scope} is also set.
+     * {@linkcode HonoBffOptions.scope} is also set, or pins a `max_age` that is
+     * not a non-negative integer.
      */
     constructor(options) {
         assertStoresConfigured(options);
@@ -737,6 +784,23 @@ export class HonoBff {
                 let user = null;
                 let sid;
                 const idToken = raw.id_token;
+                const { maxAge, scopeForwarded } = this.#extraAuthorizeParams;
+                if (maxAge !== undefined && (idToken || scopeForwarded)) {
+                    let claims;
+                    try {
+                        claims = idToken ? this.#client.decodeIdToken(idToken) : undefined;
+                    }
+                    catch {
+                        claims = undefined;
+                    }
+                    const shortfall = authTimeShortfall(claims, maxAge, Date.now());
+                    if (shortfall) {
+                        throw new CallbackRefusal({
+                            error: "login_required",
+                            error_description: shortfall,
+                        });
+                    }
+                }
                 if (idToken) {
                     try {
                         const claims = this.#client.decodeIdToken(idToken);
@@ -774,6 +838,8 @@ export class HonoBff {
                 return c.redirect(this.#safeReturnTo(returnTo));
             }
             catch (cause) {
+                if (cause instanceof CallbackRefusal)
+                    return await fail(cause.refusal);
                 return await fail({
                     error: "invalid_grant",
                     error_description: "code exchange failed",

package/dist/client/_http.d.ts

@@ -6,11 +6,16 @@
  *
  * @module
  */
-import { type OAuth2Error } from "../errors.ts";
+import { type OAuth2Error, type OAuth2ErrorClass as OAuth2ErrorClassType } from "../errors.ts";
 /** Response bytes accepted from an endpoint before the call is refused. */
 export declare const MAX_RESPONSE_BYTES: number;
 /** Wall-clock budget for one call, covering the connect and the body read. */
 export declare const REQUEST_TIMEOUT_MS = 10000;
+/**
+ * The typed error class for an OAuth2 or OpenID Connect error code, or the
+ * generic `OAuth2Error` for a code without one.
+ */
+export declare function errorClassForCode(code: string): OAuth2ErrorClassType;
 /** How a call describes itself in an error message, e.g. `"token endpoint"`. */
 export type Endpoint = string;
 /** How {@link sendGuarded} treats a `3xx`. */

package/dist/client/_http.js

@@ -6,7 +6,7 @@
  *
  * @module
  */
-import { AccessDeniedError, AuthorizationPendingError, ExpiredTokenError, InsufficientScopeError, InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, InvalidTokenError, OAuth2Error as OAuth2ErrorClass, ServerError, SlowDownError, TemporarilyUnavailableError, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, UnsupportedTokenTypeError, } from "../errors.js";
+import { AccessDeniedError, AccountSelectionRequiredError, AuthorizationPendingError, ConsentRequiredError, ExpiredTokenError, InsufficientScopeError, InteractionRequiredError, InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, InvalidTokenError, LoginRequiredError, OAuth2Error as OAuth2ErrorClass, ServerError, SlowDownError, TemporarilyUnavailableError, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, UnsupportedTokenTypeError, } from "../errors.js";
 import { packageDeadlineSignal } from "../utils/_default-fetch.js";
 import { sanitizeProviderText } from "../utils/text.js";
 /** Response bytes accepted from an endpoint before the call is refused. */
@@ -15,14 +15,18 @@ export const MAX_RESPONSE_BYTES = 64 * 1024;
 export const REQUEST_TIMEOUT_MS = 10_000;
 const ERROR_CLASS_BY_CODE = {
     access_denied: AccessDeniedError,
+    account_selection_required: AccountSelectionRequiredError,
     authorization_pending: AuthorizationPendingError,
+    consent_required: ConsentRequiredError,
     expired_token: ExpiredTokenError,
     insufficient_scope: InsufficientScopeError,
+    interaction_required: InteractionRequiredError,
     invalid_client: InvalidClientError,
     invalid_grant: InvalidGrantError,
     invalid_request: InvalidRequestError,
     invalid_scope: InvalidScopeError,
     invalid_token: InvalidTokenError,
+    login_required: LoginRequiredError,
     server_error: ServerError,
     slow_down: SlowDownError,
     temporarily_unavailable: TemporarilyUnavailableError,
@@ -31,6 +35,15 @@ const ERROR_CLASS_BY_CODE = {
     unsupported_response_type: UnsupportedResponseTypeError,
     unsupported_token_type: UnsupportedTokenTypeError,
 };
+/**
+ * The typed error class for an OAuth2 or OpenID Connect error code, or the
+ * generic `OAuth2Error` for a code without one.
+ */
+export function errorClassForCode(code) {
+    return Object.hasOwn(ERROR_CLASS_BY_CODE, code)
+        ? ERROR_CLASS_BY_CODE[code]
+        : OAuth2ErrorClass;
+}
 /**
  * Sends one request with a deadline.
  *
@@ -228,7 +241,7 @@ function reportedError(value) {
     };
 }
 function buildError(reported, status) {
-    const ErrorClass = ERROR_CLASS_BY_CODE[reported.error] ?? OAuth2ErrorClass;
+    const ErrorClass = errorClassForCode(reported.error);
     return new ErrorClass(reported.description ?? reported.error, {
         status: status !== undefined && status >= 400 ? status : undefined,
         extensions: {

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

@@ -1,3 +1,10 @@
 import { type OAuth2Error } from "../errors.ts";
 export declare function issuerRefusal(message: string): OAuth2Error;
 export declare function isIssuerRefusal(error: unknown): error is OAuth2Error;
+export declare const DUPLICATE_ISS_PROBLEM = "the authorization response carries more than one `iss` (RFC 9207)";
+/**
+ * Why an authorization response's `iss` values (RFC 9207 §2.4) are refused, or
+ * `undefined` when they are accepted: more than one value, none when
+ * `required`, or one that is not exactly one of `accepted`.
+ */
+export declare function authorizationResponseIssuerProblem(received: readonly string[], accepted: readonly string[], required: boolean): string | undefined;

package/dist/client/_issuer-refusal.js

@@ -8,3 +8,25 @@ export function issuerRefusal(message) {
 export function isIssuerRefusal(error) {
     return error instanceof Error && refusals.has(error);
 }
+export const DUPLICATE_ISS_PROBLEM = "the authorization response carries more than one `iss` (RFC 9207)";
+/**
+ * Why an authorization response's `iss` values (RFC 9207 §2.4) are refused, or
+ * `undefined` when they are accepted: more than one value, none when
+ * `required`, or one that is not exactly one of `accepted`.
+ */
+export function authorizationResponseIssuerProblem(received, accepted, required) {
+    if (received.length > 1)
+        return DUPLICATE_ISS_PROBLEM;
+    const [iss] = received;
+    if (iss === undefined) {
+        if (!required)
+            return undefined;
+        return ("the authorization response is missing `iss`, which the issuer " +
+            "advertises with `authorization_response_iss_parameter_supported` " +
+            "(RFC 9207 §2.4)");
+    }
+    if (accepted.includes(iss))
+        return undefined;
+    return ("the authorization response `iss` does not match the issuer the " +
+        "request was sent to (RFC 9207 §2.4)");
+}

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

@@ -423,7 +423,8 @@ export declare class DirectClient extends OAuth2ClientBase {
      * 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.
+     * exchange fails. A code with a typed class, such as `login_required`
+     * (`LoginRequiredError`), is thrown as that class.
      * @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

package/dist/client/direct-client.js

@@ -10,16 +10,16 @@
  *
  * @module
  */
-import { AccessDeniedError, InvalidGrantError, isOAuth2Error, OAuth2Error as OAuth2ErrorClass, ServerError, } from "../errors.js";
+import { AccessDeniedError, InvalidGrantError, isOAuth2Error, ServerError, } from "../errors.js";
 import { challengeMethods, generateCodeVerifier, generateState, } from "../utils/pkce.js";
 import { encodeBasicAuth } from "../utils/basic-auth.js";
 import { base64urlDecode } from "../utils/crypto.js";
 import { delay } from "../utils/_delay.js";
 import { sanitizeProviderText } from "../utils/text.js";
-import { assertField, assertTokenResponse, errorFromResponse, receiveJson, sendGuarded, } from "./_http.js";
+import { assertField, assertTokenResponse, errorClassForCode, 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 { authorizationResponseIssuerProblem, 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;
@@ -396,7 +396,8 @@ export class DirectClient extends OAuth2ClientBase {
      * 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.
+     * exchange fails. A code with a typed class, such as `login_required`
+     * (`LoginRequiredError`), is thrown as that class.
      * @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
@@ -501,26 +502,11 @@ export class DirectClient extends OAuth2ClientBase {
         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)");
+        const problem = authorizationResponseIssuerProblem(params.getAll("iss"), accepted, metadata.authorization_response_iss_parameter_supported === true);
+        return problem === undefined ? undefined : issuerRefusal(problem);
     }
     /**
      * **Advanced (BFF / multi-session servers).** SPA, mobile, and CLI consumers
@@ -1322,7 +1308,8 @@ function metadataToEndpoints(meta) {
 }
 function authorizationResponseError(error, params) {
     const description = params.get("error_description") ?? undefined;
-    return new OAuth2ErrorClass(description ?? "authorization error", {
+    const ErrorClass = errorClassForCode(error);
+    return new ErrorClass(description ?? "authorization error", {
         extensions: {
             error,
             error_description: description,

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

@@ -53,6 +53,24 @@ export declare function readProviderText(res: Response, provider: string, source
  * the body, so the caller must not read it again.
  */
 export declare function readErrorBody(res: Response): Promise<string>;
+/** Input to {@link assertAuthorizationResponseIssuer}. */
+export interface AuthorizationResponseIssuerInput {
+    /** The connector id, for the error prefix. */
+    provider: string;
+    /** The callback's `iss`, from {@link ExternalProfileInput.iss}. */
+    iss: string | undefined;
+    /** The provider's issuer identifier; `iss` must equal it exactly. */
+    issuer: string;
+    /** Whether the provider advertises `authorization_response_iss_parameter_supported`. */
+    required: boolean;
+}
+/**
+ * Refuses a callback whose `iss` (RFC 9207 §2.4) is not exactly `issuer`, or
+ * is absent while `required`. Call it before redeeming the code.
+ *
+ * @throws {ExternalAuthError} `invalid_callback` when the response is refused.
+ */
+export declare function assertAuthorizationResponseIssuer(input: AuthorizationResponseIssuerInput): void;
 /**
  * Drops one trailing `"/"` so issuer URLs compare and concatenate consistently
  * (`"https://x/"` and `"https://x"` identify the same issuer).

package/dist/identity/external/_shared.js

@@ -8,6 +8,7 @@
  *
  * @module
  */
+import { authorizationResponseIssuerProblem } from "../../client/_issuer-refusal.js";
 import { isOAuth2Error } from "../../errors.js";
 import { readBoundedBody } from "../../utils/_body.js";
 import { timingSafeEqualString } from "../../utils/crypto.js";
@@ -90,6 +91,20 @@ export async function readErrorBody(res) {
         return "";
     }
 }
+/**
+ * Refuses a callback whose `iss` (RFC 9207 §2.4) is not exactly `issuer`, or
+ * is absent while `required`. Call it before redeeming the code.
+ *
+ * @throws {ExternalAuthError} `invalid_callback` when the response is refused.
+ */
+export function assertAuthorizationResponseIssuer(input) {
+    const problem = authorizationResponseIssuerProblem(input.iss === undefined ? [] : [input.iss], [input.issuer], input.required);
+    if (problem === undefined)
+        return;
+    throw new ExternalAuthError(input.provider, "invalid_callback", `${problem}. The callback did not come from "${input.issuer}" — a ` +
+        `response from another provider replayed here, or a provider that ` +
+        `does not send the issuer it advertises. Ask the user to start again.`);
+}
 /**
  * Drops one trailing `"/"` so issuer URLs compare and concatenate consistently
  * (`"https://x/"` and `"https://x"` identify the same issuer).

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

@@ -50,6 +50,9 @@ export interface AppleProviderOptions extends Pick<AppleClientSecretOptions, "te
  * `id_token`'s RS256 signature against Apple's published keys before trusting
  * its claims (`iss`, `aud`, `azp`, `exp`, and the `nonce` when one was sent,
  * checked as {@link oidcProvider} checks them, with the default `azp` policy).
+ * A callback `iss` (RFC 9207) other than `https://appleid.apple.com` is
+ * refused before the code is redeemed; Apple does not advertise the
+ * parameter, so a callback without one is accepted.
  * `emailVerified` is `true` when Apple's `email_verified` claim is `true` or
  * the string `"true"`; private-relay addresses
  * (`@privaterelay.appleid.com`) are returned as-is. The raw `id_token`

package/dist/identity/external/apple.js

@@ -18,7 +18,7 @@
 import { toArrayBuffer } from "../../utils/_buffer.js";
 import { base64urlDecode } from "../../utils/crypto.js";
 import { defaultFetch, packageDeadlineSignal, } from "../../utils/_default-fetch.js";
-import { assertIdTokenClaims, describeError, PROVIDER_REQUEST_TIMEOUT_MS, readProviderText, } from "./_shared.js";
+import { assertAuthorizationResponseIssuer, assertIdTokenClaims, describeError, PROVIDER_REQUEST_TIMEOUT_MS, readProviderText, } from "./_shared.js";
 import { runTokenExchange } from "./_token-exchange.js";
 import { createAppleClientSecretFactory, } from "./apple-client-secret.js";
 import { ExternalAuthError } from "./errors.js";
@@ -41,6 +41,9 @@ const SIGNATURE_NOT_VERIFIED = `Apple id_token signature did not verify against
  * `id_token`'s RS256 signature against Apple's published keys before trusting
  * its claims (`iss`, `aud`, `azp`, `exp`, and the `nonce` when one was sent,
  * checked as {@link oidcProvider} checks them, with the default `azp` policy).
+ * A callback `iss` (RFC 9207) other than `https://appleid.apple.com` is
+ * refused before the code is redeemed; Apple does not advertise the
+ * parameter, so a callback without one is accepted.
  * `emailVerified` is `true` when Apple's `email_verified` claim is `true` or
  * the string `"true"`; private-relay addresses
  * (`@privaterelay.appleid.com`) are returned as-is. The raw `id_token`
@@ -205,6 +208,12 @@ export function appleProvider(options) {
             return Promise.resolve(url.toString());
         },
         async fetchProfile(input) {
+            assertAuthorizationResponseIssuer({
+                provider: id,
+                iss: input.iss,
+                issuer: APPLE_ISSUER,
+                required: false,
+            });
             const idToken = await exchangeCode(input);
             const claims = await verifyIdToken(idToken, input.nonce);
             return profileFromClaims(claims);

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

@@ -19,7 +19,9 @@
  * - `provider_error` — the provider rejected the request (callback `error`
  *   param, token-endpoint error, profile-endpoint failure, malformed
  *   response). The message carries the provider's error code/description.
- * - `invalid_callback` — the callback URL is missing `code` or `state`.
+ * - `invalid_callback` — the callback URL is missing `code` or `state`, or
+ *   its `iss` (RFC 9207) is not the provider's issuer: repeated, naming
+ *   another issuer, or missing from a provider that advertises it.
  * - `state_mismatch` — the callback `state` does not match the transient
  *   (possible CSRF or a stale/mixed-up sign-in attempt).
  * - `transient_expired` — the sign-in attempt outlived the configured max

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

@@ -99,8 +99,10 @@ export declare class ExternalAuthFlow {
      * Completes a sign-in attempt from the provider callback: checks the
      * transient belongs to this flow's provider, enforces the max transient
      * age, verifies `state` with a timing-safe compare, and only then surfaces a
-     * provider `error` callback param; finally the provider exchanges the code
-     * and (for nonce-using providers) validates the id_token nonce, and the
+     * provider `error` callback param. A callback with more than one `iss` is
+     * refused; a single `iss` is handed to the provider, which checks it against
+     * its issuer (RFC 9207) before it exchanges the code. The provider then
+     * (for nonce-using providers) validates the id_token nonce, and the
      * normalized profile is returned.
      *
      * @throws {ExternalAuthError} with a code describing the failure — see

package/dist/identity/external/flow.js

@@ -6,6 +6,7 @@
  *
  * @module
  */
+import { DUPLICATE_ISS_PROBLEM } from "../../client/_issuer-refusal.js";
 import { timingSafeEqualString } from "../../utils/crypto.js";
 import { generateCodeVerifier, generateState } from "../../utils/pkce.js";
 import { ExternalAuthError } from "./errors.js";
@@ -91,8 +92,10 @@ export class ExternalAuthFlow {
      * Completes a sign-in attempt from the provider callback: checks the
      * transient belongs to this flow's provider, enforces the max transient
      * age, verifies `state` with a timing-safe compare, and only then surfaces a
-     * provider `error` callback param; finally the provider exchanges the code
-     * and (for nonce-using providers) validates the id_token nonce, and the
+     * provider `error` callback param. A callback with more than one `iss` is
+     * refused; a single `iss` is handed to the provider, which checks it against
+     * its issuer (RFC 9207) before it exchanges the code. The provider then
+     * (for nonce-using providers) validates the id_token nonce, and the
      * normalized profile is returned.
      *
      * @throws {ExternalAuthError} with a code describing the failure — see
@@ -134,11 +137,16 @@ export class ExternalAuthFlow {
         if (!code) {
             throw new ExternalAuthError(providerId, "invalid_callback", `callback is missing the "code" parameter.`);
         }
+        const issValues = params.getAll("iss");
+        if (issValues.length > 1) {
+            throw new ExternalAuthError(providerId, "invalid_callback", `${DUPLICATE_ISS_PROBLEM}. Ask the user to start again.`);
+        }
         return await this.provider.fetchProfile({
             code,
             redirectUri: transient.redirectUri,
             codeVerifier: transient.codeVerifier,
             nonce: transient.nonce,
+            ...(issValues.length === 1 ? { iss: issValues[0] } : {}),
         });
     }
 }

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

@@ -85,6 +85,20 @@ export interface OAuth2ProviderOptions {
      * downgrade PKCE.
      */
     authorizationParams?: Record<string, string>;
+    /**
+     * The provider's issuer identifier, for the RFC 9207 check. When set, a
+     * callback `iss` that is not exactly this value is refused before the code
+     * is redeemed. Unset, the callback's `iss` is not checked.
+     */
+    issuer?: string;
+    /**
+     * Set `true` when the provider always sends `iss` in its authorization
+     * responses (its metadata advertises
+     * `authorization_response_iss_parameter_supported`), so a callback without
+     * one is refused. Requires {@link OAuth2ProviderOptions.issuer}. Defaults to
+     * `false`.
+     */
+    authorizationResponseIssParameterSupported?: boolean;
     /**
      * Fetch implementation for all provider traffic. Defaults to
      * `globalThis.fetch`. A wrapper must pass `init` through intact: its
@@ -100,7 +114,11 @@ export interface OAuth2ProviderOptions {
  * credentials in the body (`client_secret_post`); the profile is read from
  * `userInfoEndpoint` with the bearer token when set, else from the token
  * response, and handed to `mapProfile`. Presets like {@link discordProvider}
- * are thin wrappers over this.
+ * are thin wrappers over this. With `issuer` set, the callback's `iss`
+ * (RFC 9207) is checked before the exchange.
+ *
+ * @throws {ExternalAuthError} `configuration` when
+ *   `authorizationResponseIssParameterSupported` is set without `issuer`.
  *
  * @example
  * ```ts

package/dist/identity/external/oauth2.js

@@ -9,7 +9,7 @@
  */
 import { defaultFetch, packageDeadlineSignal, } from "../../utils/_default-fetch.js";
 import { generateCodeChallenge } from "../../utils/pkce.js";
-import { describeError, PROVIDER_REQUEST_TIMEOUT_MS, readErrorBody, readProviderText, } from "./_shared.js";
+import { assertAuthorizationResponseIssuer, describeError, PROVIDER_REQUEST_TIMEOUT_MS, readErrorBody, readProviderText, } from "./_shared.js";
 import { runTokenExchange } from "./_token-exchange.js";
 import { ExternalAuthError } from "./errors.js";
 /**
@@ -20,7 +20,11 @@ import { ExternalAuthError } from "./errors.js";
  * credentials in the body (`client_secret_post`); the profile is read from
  * `userInfoEndpoint` with the bearer token when set, else from the token
  * response, and handed to `mapProfile`. Presets like {@link discordProvider}
- * are thin wrappers over this.
+ * are thin wrappers over this. With `issuer` set, the callback's `iss`
+ * (RFC 9207) is checked before the exchange.
+ *
+ * @throws {ExternalAuthError} `configuration` when
+ *   `authorizationResponseIssParameterSupported` is set without `issuer`.
  *
  * @example
  * ```ts
@@ -40,6 +44,13 @@ import { ExternalAuthError } from "./errors.js";
  */
 export function oauth2Provider(options) {
     const id = options.id;
+    const { issuer } = options;
+    const issRequired = options.authorizationResponseIssParameterSupported === true;
+    if (issRequired && issuer === undefined) {
+        throw new ExternalAuthError(id, "configuration", `authorizationResponseIssParameterSupported needs an issuer to ` +
+            `compare the callback's "iss" with — set the provider's issuer ` +
+            `identifier as "issuer".`);
+    }
     const fetchImpl = (input, init) => (options.fetch ?? defaultFetch)(input, init);
     const scopeSeparator = options.scopeSeparator ?? " ";
     async function exchangeCode(input) {
@@ -120,6 +131,14 @@ export function oauth2Provider(options) {
             return url.toString();
         },
         async fetchProfile(input) {
+            if (issuer !== undefined) {
+                assertAuthorizationResponseIssuer({
+                    provider: id,
+                    iss: input.iss,
+                    issuer,
+                    required: issRequired,
+                });
+            }
             const tokens = await exchangeCode(input);
             const profile = options.userInfoEndpoint
                 ? await fetchUserInfo(tokens.accessToken)

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

@@ -65,6 +65,12 @@ export interface OidcProviderOptions {
  * id_token `sub` (OIDC Core §5.3.2) is discarded, and a UserInfo failure is
  * non-fatal — the profile then comes from the id_token claims alone.
  *
+ * **Authorization response issuer:** before the code is redeemed, a callback
+ * `iss` (RFC 9207) that is not exactly the discovered issuer is refused, and
+ * so is a missing `iss` when the discovery document advertises
+ * `authorization_response_iss_parameter_supported: true`. A provider that
+ * does not advertise it may leave `iss` out.
+ *
  * **id_token validation:** the `iss`, `aud`, `azp` (when the token has multiple
  * audiences or an `azp` claim, unless `azp: "ignore"` is configured), `exp`,
  * and `nonce` claims are checked per OpenID Connect Core §3.1.3.7. The

package/dist/identity/external/oidc.js

@@ -9,7 +9,7 @@ import { MemoryAuthRequestStorage } from "../../client/storage.js";
 import { isOAuth2Error } from "../../errors.js";
 import { defaultFetch, packageDeadlineSignal, } from "../../utils/_default-fetch.js";
 import { generateCodeChallenge } from "../../utils/pkce.js";
-import { assertIdTokenClaims, describeError, PROVIDER_REQUEST_TIMEOUT_MS, readProviderText, stripTrailingSlash, } from "./_shared.js";
+import { assertAuthorizationResponseIssuer, assertIdTokenClaims, describeError, PROVIDER_REQUEST_TIMEOUT_MS, readProviderText, stripTrailingSlash, } from "./_shared.js";
 import { ExternalAuthError } from "./errors.js";
 /**
  * Creates a connector for any spec-compliant OpenID Connect provider.
@@ -23,6 +23,12 @@ import { ExternalAuthError } from "./errors.js";
  * id_token `sub` (OIDC Core §5.3.2) is discarded, and a UserInfo failure is
  * non-fatal — the profile then comes from the id_token claims alone.
  *
+ * **Authorization response issuer:** before the code is redeemed, a callback
+ * `iss` (RFC 9207) that is not exactly the discovered issuer is refused, and
+ * so is a missing `iss` when the discovery document advertises
+ * `authorization_response_iss_parameter_supported: true`. A provider that
+ * does not advertise it may leave `iss` out.
+ *
  * **id_token validation:** the `iss`, `aud`, `azp` (when the token has multiple
  * audiences or an `azp` claim, unless `azp: "ignore"` is configured), `exp`,
  * and `nonce` claims are checked per OpenID Connect Core §3.1.3.7. The
@@ -191,6 +197,12 @@ export function oidcProvider(options) {
         },
         async fetchProfile(input) {
             const meta = await discover();
+            assertAuthorizationResponseIssuer({
+                provider: id,
+                iss: input.iss,
+                issuer: meta.issuer,
+                required: meta.authorization_response_iss_parameter_supported === true,
+            });
             const response = await exchangeCode(input);
             const claims = decodeAndValidateIdToken(response, meta, input.nonce);
             const userInfo = await fetchUserInfoClaims(meta, response.access_token, claims.sub);

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

@@ -93,6 +93,14 @@ export interface ExternalProfileInput {
     codeVerifier?: string;
     /** The expected id_token `nonce` from the transient, when one was sent. */
     nonce?: string;
+    /**
+     * The callback's `iss` parameter (RFC 9207), when it carried one. Refuse
+     * the callback before redeeming `code` when this is not exactly the
+     * provider's issuer, or when it is missing and the provider advertises
+     * `authorization_response_iss_parameter_supported`. The flow has already
+     * refused a callback with more than one `iss`.
+     */
+    iss?: string;
 }
 /**
  * What a connector must provide for {@link ExternalAuthFlow} to drive it.
@@ -125,10 +133,12 @@ export interface ExternalProvider {
     /**
      * Exchanges the authorization code and returns the verified, normalized
      * profile. Implementations must validate the id_token `nonce` against
-     * `input.nonce` when one was sent.
+     * `input.nonce` when one was sent, and should check `input.iss` before the
+     * exchange as {@link ExternalProfileInput.iss} describes.
      *
      * @throws {ExternalAuthError} `provider_error` when the exchange or profile
-     *   fetch fails, `nonce_mismatch` when the id_token nonce does not match.
+     *   fetch fails, `nonce_mismatch` when the id_token nonce does not match,
+     *   `invalid_callback` when `input.iss` is refused.
      */
     fetchProfile(input: ExternalProfileInput): Promise<ExternalProfile>;
 }

package/package.json

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