@udibo/oauth2 0.26.0 → 0.28.0

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/dist/models/authentication.d.ts

@@ -22,3 +22,31 @@ export interface AuthenticationContext {
     /** Truthful authentication methods; omitted when the complete set is unknown. */
     readonly amr?: readonly string[];
 }
+/**
+ * The OpenID Connect authentication controls of one authorization request,
+ * validated by the authorization server and handed to the application's
+ * `authenticateUser` and `handleConsent` callbacks.
+ *
+ * The server enforces what it can verify: `prompt=none` never reaches a login
+ * or consent page, and a code is issued only when the returned authentication
+ * satisfies `prompt=login` and `max_age` (see
+ * `satisfiesAuthenticationRequest`). `acrValues` is a preference the
+ * application meets as it can; report the `acr` it actually achieved.
+ *
+ * @example
+ * ```ts
+ * const authentication: AuthenticationRequest = {
+ *   prompt: ["login"],
+ *   maxAge: 300,
+ *   acrValues: ["urn:example:mfa"],
+ * };
+ * ```
+ */
+export interface AuthenticationRequest {
+    /** Requested `prompt` values, each one the server supports; empty when absent. */
+    readonly prompt: readonly string[];
+    /** Requested `max_age` in seconds, when present. */
+    readonly maxAge?: number;
+    /** Requested `acr_values` in preference order; empty when absent. */
+    readonly acrValues: readonly string[];
+}

package/dist/models/authorization-code.d.ts

@@ -38,11 +38,11 @@ export interface AuthorizationCode<Client extends ClientInterface, User, Scope e
  * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1
  */
 export interface AuthorizeParameters {
-    /** Raw space-delimited ACR preferences; application policy must validate and honor them. */
+    /** Raw space-delimited ACR preferences; `authenticateUser` receives them validated. */
     acrValues?: string;
-    /** Raw maximum authentication age in seconds; application policy must validate and enforce it. */
+    /** Raw maximum authentication age in seconds; the authorize endpoint validates and enforces it. */
     maxAge?: string;
-    /** Raw prompt values; application policy must honor or refuse every supported control. */
+    /** Raw prompt values; the authorize endpoint validates them and enforces `none`, `login` and `consent`. */
     prompt?: string;
     /** Must be "code" for authorization code flow. */
     responseType?: string;

package/dist/models/responses.d.ts

@@ -4,12 +4,14 @@
  * Includes the RFC 6750 Section 3.1 bearer-token error codes
  * (`invalid_token`, `insufficient_scope`) emitted by resource servers, in
  * addition to the RFC 6749 Section 5.2 / Section 4.1.2.1 codes and the RFC
- * 8628 device-flow codes.
+ * 8628 device-flow codes and the OpenID Connect Core §3.1.2.6
+ * authentication-error codes.
  *
  * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
  * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
+ * @see https://openid.net/specs/openid-connect-core-1_0.html#AuthError
  */
-export type OAuth2ErrorCode = "invalid_request" | "invalid_client" | "invalid_grant" | "unauthorized_client" | "unsupported_grant_type" | "unsupported_response_type" | "unsupported_token_type" | "invalid_scope" | "invalid_token" | "insufficient_scope" | "access_denied" | "server_error" | "temporarily_unavailable" | "authorization_pending" | "slow_down" | "expired_token";
+export type OAuth2ErrorCode = "invalid_request" | "invalid_client" | "invalid_grant" | "unauthorized_client" | "unsupported_grant_type" | "unsupported_response_type" | "unsupported_token_type" | "invalid_scope" | "invalid_token" | "insufficient_scope" | "access_denied" | "server_error" | "temporarily_unavailable" | "authorization_pending" | "slow_down" | "expired_token" | "login_required" | "consent_required" | "interaction_required" | "account_selection_required";
 /**
  * Standard OAuth2 error response.
  *
@@ -74,6 +76,10 @@ export interface AuthorizationServerMetadata {
     id_token_signing_alg_values_supported?: string[];
     /** Subject identifier types supported (OIDC Discovery). */
     subject_types_supported?: string[];
+    /** `prompt` values the authorization endpoint honors (OIDC Prompt Create). */
+    prompt_values_supported?: string[];
+    /** Authentication context class references the server can achieve (OIDC Discovery). */
+    acr_values_supported?: string[];
 }
 /**
  * Device authorization response as defined in RFC 8628.

package/dist/server/authentication-request.d.ts

@@ -0,0 +1,60 @@
+import type { AuthenticationContext, AuthenticationRequest } from "../models/authentication.ts";
+/** The `prompt` values the authorization server enforces on its own. */
+export declare const DEFAULT_PROMPT_VALUES_SUPPORTED: readonly string[];
+/**
+ * What an `authenticateUser` callback reports about the authentication behind
+ * the user it returns, as {@linkcode satisfiesAuthenticationRequest} reads it.
+ */
+export interface AuthenticationOutcome {
+    /** The verified authentication event, when known. */
+    authenticationContext?: AuthenticationContext;
+    /**
+     * `true` only when the user actively authenticated in response to this
+     * authorization request, which is what `prompt=login` and `max_age=0` ask
+     * for. A session that merely exists, or was refreshed, is not that.
+     */
+    reauthenticated?: boolean;
+}
+export declare function assertSupportedValues(name: string, values: readonly string[]): readonly string[];
+/**
+ * Validates the `prompt`, `max_age` and `acr_values` of an authorization
+ * request. Parameters sent without a value are treated as omitted (OIDC Core
+ * §3.1.2.1).
+ *
+ * @throws {InvalidRequestError} For a repeated parameter, a `prompt` value not
+ *   in `promptValuesSupported`, `none` combined with another `prompt` value, or
+ *   a `max_age` that is not a non-negative integer.
+ */
+export declare function parseAuthenticationRequest(params: URLSearchParams, promptValuesSupported: readonly string[]): AuthenticationRequest;
+/**
+ * Why `outcome` does not satisfy `request`, as an `error_description`, or
+ * `undefined` when it does.
+ */
+export declare function authenticationShortfall(request: AuthenticationRequest, outcome: AuthenticationOutcome, now: number): string | undefined;
+/**
+ * Whether an authentication meets the request's `prompt=login` and `max_age`
+ * controls — the check the authorization server applies to what
+ * `authenticateUser` returns before it issues a code. Call it from
+ * `authenticateUser` with the session's event to decide whether to send the
+ * user to sign in again instead of returning them.
+ *
+ * `prompt=login` and `max_age=0`, which OIDC Core makes equivalent, need
+ * `reauthenticated: true`. Any `max_age` needs a recorded `auth_time`, since
+ * the ID token must carry one, never more than a minute in the future. Above
+ * zero, it must also be no older than `max_age` seconds, whether or not the
+ * user re-authenticated. `acr_values` is a preference and never fails the
+ * check.
+ *
+ * @param now The current time in epoch milliseconds. Defaults to `Date.now()`.
+ *
+ * @example
+ * ```ts
+ * import { satisfiesAuthenticationRequest } from "@udibo/oauth2/server";
+ *
+ * const fresh = satisfiesAuthenticationRequest(
+ *   { prompt: [], maxAge: 300, acrValues: [] },
+ *   { authenticationContext: { auth_time: Math.floor(Date.now() / 1000) } },
+ * );
+ * ```
+ */
+export declare function satisfiesAuthenticationRequest(request: AuthenticationRequest, outcome: AuthenticationOutcome, now?: number): boolean;

package/dist/server/authentication-request.js

@@ -0,0 +1,102 @@
+import { InvalidRequestError } from "../errors.js";
+/** The `prompt` values the authorization server enforces on its own. */
+export const DEFAULT_PROMPT_VALUES_SUPPORTED = Object.freeze(["none", "login", "consent"]);
+const MAX_AUTH_TIME_SKEW_SECONDS = 60;
+function spaceDelimited(value) {
+    return [...new Set((value ?? "").split(" ").filter(Boolean))];
+}
+export function assertSupportedValues(name, values) {
+    if (values.some((value) => typeof value !== "string" || !/^[\x21-\x7e]+$/.test(value))) {
+        throw new TypeError(`${name} entries must be non-empty strings of visible ASCII without spaces`);
+    }
+    return Object.freeze([...new Set(values)]);
+}
+/**
+ * Validates the `prompt`, `max_age` and `acr_values` of an authorization
+ * request. Parameters sent without a value are treated as omitted (OIDC Core
+ * §3.1.2.1).
+ *
+ * @throws {InvalidRequestError} For a repeated parameter, a `prompt` value not
+ *   in `promptValuesSupported`, `none` combined with another `prompt` value, or
+ *   a `max_age` that is not a non-negative integer.
+ */
+export function parseAuthenticationRequest(params, promptValuesSupported) {
+    for (const name of ["prompt", "max_age", "acr_values"]) {
+        if (params.getAll(name).length > 1) {
+            throw new InvalidRequestError(`${name} parameter must not be repeated`);
+        }
+    }
+    const prompt = spaceDelimited(params.get("prompt"));
+    if (prompt.some((value) => !promptValuesSupported.includes(value))) {
+        throw new InvalidRequestError("prompt value not supported");
+    }
+    if (prompt.includes("none") && prompt.length > 1) {
+        throw new InvalidRequestError("prompt=none cannot be combined with other prompt values");
+    }
+    const rawMaxAge = params.get("max_age") || undefined;
+    if (rawMaxAge !== undefined &&
+        (!/^\d+$/.test(rawMaxAge) || !Number.isSafeInteger(Number(rawMaxAge)))) {
+        throw new InvalidRequestError("max_age must be a non-negative integer");
+    }
+    return Object.freeze({
+        prompt: Object.freeze(prompt),
+        ...(rawMaxAge === undefined ? {} : { maxAge: Number(rawMaxAge) }),
+        acrValues: Object.freeze(spaceDelimited(params.get("acr_values"))),
+    });
+}
+/**
+ * Why `outcome` does not satisfy `request`, as an `error_description`, or
+ * `undefined` when it does.
+ */
+export function authenticationShortfall(request, outcome, now) {
+    const reauthenticated = outcome.reauthenticated === true;
+    if (request.prompt.includes("login") && !reauthenticated) {
+        return "prompt=login requires the user to authenticate again";
+    }
+    if (request.maxAge === 0 && !reauthenticated) {
+        return "max_age=0 requires the user to authenticate again";
+    }
+    if (request.maxAge === undefined)
+        return undefined;
+    const authTime = outcome.authenticationContext?.auth_time;
+    if (typeof authTime !== "number" || !Number.isFinite(authTime)) {
+        return "max_age requires the time the user authenticated";
+    }
+    const age = Math.floor(now / 1000) - authTime;
+    if (age < -MAX_AUTH_TIME_SKEW_SECONDS) {
+        return "the user's authentication time is in the future";
+    }
+    if (request.maxAge > 0 && age > request.maxAge) {
+        return "the user's last authentication is older than max_age";
+    }
+    return undefined;
+}
+/**
+ * Whether an authentication meets the request's `prompt=login` and `max_age`
+ * controls — the check the authorization server applies to what
+ * `authenticateUser` returns before it issues a code. Call it from
+ * `authenticateUser` with the session's event to decide whether to send the
+ * user to sign in again instead of returning them.
+ *
+ * `prompt=login` and `max_age=0`, which OIDC Core makes equivalent, need
+ * `reauthenticated: true`. Any `max_age` needs a recorded `auth_time`, since
+ * the ID token must carry one, never more than a minute in the future. Above
+ * zero, it must also be no older than `max_age` seconds, whether or not the
+ * user re-authenticated. `acr_values` is a preference and never fails the
+ * check.
+ *
+ * @param now The current time in epoch milliseconds. Defaults to `Date.now()`.
+ *
+ * @example
+ * ```ts
+ * import { satisfiesAuthenticationRequest } from "@udibo/oauth2/server";
+ *
+ * const fresh = satisfiesAuthenticationRequest(
+ *   { prompt: [], maxAge: 300, acrValues: [] },
+ *   { authenticationContext: { auth_time: Math.floor(Date.now() / 1000) } },
+ * );
+ * ```
+ */
+export function satisfiesAuthenticationRequest(request, outcome, now = Date.now()) {
+    return authenticationShortfall(request, outcome, now) === undefined;
+}