@udibo/oauth2 0.25.0 → 0.27.0

package/dist/client/direct-client.js

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

package/dist/client/mod.d.ts

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

package/dist/errors.d.ts

@@ -6,6 +6,7 @@
  * - RFC 6749 Section 5.2 (Token errors)
  * - RFC 6750 Section 3.1 (Bearer token errors)
  * - RFC 8628 Section 3.5 (Device flow errors)
+ * - OpenID Connect Core 1.0 Section 3.1.2.6 (Authentication errors)
  *
  * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
  * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
@@ -204,3 +205,36 @@ export declare const SlowDownError: OAuth2ErrorClass;
  * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.5
  */
 export declare const ExpiredTokenError: OAuth2ErrorClass;
+/**
+ * The authorization request requires the user to authenticate, and the server
+ * cannot show a login page (`prompt=none`) or cannot re-authenticate the user
+ * as `prompt=login` or `max_age` requires.
+ *
+ * @see https://openid.net/specs/openid-connect-core-1_0.html#AuthError
+ */
+export declare const LoginRequiredError: OAuth2ErrorClass;
+/**
+ * The authorization request requires the user's consent, and the server
+ * cannot obtain it: `prompt=none` forbids the consent page, or `prompt=consent`
+ * reached a server with no consent handler.
+ *
+ * @see https://openid.net/specs/openid-connect-core-1_0.html#AuthError
+ */
+export declare const ConsentRequiredError: OAuth2ErrorClass;
+/**
+ * The authorization request requires user interaction other than login or
+ * consent, and `prompt=none` forbids showing it. Throw it from
+ * `authenticateUser` or `handleConsent` for an interstitial the request
+ * cannot skip.
+ *
+ * @see https://openid.net/specs/openid-connect-core-1_0.html#AuthError
+ */
+export declare const InteractionRequiredError: OAuth2ErrorClass;
+/**
+ * The user must choose among several accounts and the server cannot ask:
+ * `prompt=none` with more than one signed-in account, or `prompt=select_account`
+ * that the application cannot honor.
+ *
+ * @see https://openid.net/specs/openid-connect-core-1_0.html#AuthError
+ */
+export declare const AccountSelectionRequiredError: OAuth2ErrorClass;

package/dist/errors.js

@@ -6,6 +6,7 @@
  * - RFC 6749 Section 5.2 (Token errors)
  * - RFC 6750 Section 3.1 (Bearer token errors)
  * - RFC 8628 Section 3.5 (Device flow errors)
+ * - OpenID Connect Core 1.0 Section 3.1.2.6 (Authentication errors)
  *
  * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
  * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
@@ -286,3 +287,60 @@ export const ExpiredTokenError = createHttpErrorClass({
         error: "expired_token",
     },
 });
+/**
+ * The authorization request requires the user to authenticate, and the server
+ * cannot show a login page (`prompt=none`) or cannot re-authenticate the user
+ * as `prompt=login` or `max_age` requires.
+ *
+ * @see https://openid.net/specs/openid-connect-core-1_0.html#AuthError
+ */
+export const LoginRequiredError = createHttpErrorClass({
+    name: "Login Required",
+    status: 400,
+    extensions: {
+        error: "login_required",
+    },
+});
+/**
+ * The authorization request requires the user's consent, and the server
+ * cannot obtain it: `prompt=none` forbids the consent page, or `prompt=consent`
+ * reached a server with no consent handler.
+ *
+ * @see https://openid.net/specs/openid-connect-core-1_0.html#AuthError
+ */
+export const ConsentRequiredError = createHttpErrorClass({
+    name: "Consent Required",
+    status: 400,
+    extensions: {
+        error: "consent_required",
+    },
+});
+/**
+ * The authorization request requires user interaction other than login or
+ * consent, and `prompt=none` forbids showing it. Throw it from
+ * `authenticateUser` or `handleConsent` for an interstitial the request
+ * cannot skip.
+ *
+ * @see https://openid.net/specs/openid-connect-core-1_0.html#AuthError
+ */
+export const InteractionRequiredError = createHttpErrorClass({
+    name: "Interaction Required",
+    status: 400,
+    extensions: {
+        error: "interaction_required",
+    },
+});
+/**
+ * The user must choose among several accounts and the server cannot ask:
+ * `prompt=none` with more than one signed-in account, or `prompt=select_account`
+ * that the application cannot honor.
+ *
+ * @see https://openid.net/specs/openid-connect-core-1_0.html#AuthError
+ */
+export const AccountSelectionRequiredError = createHttpErrorClass({
+    name: "Account Selection Required",
+    status: 400,
+    extensions: {
+        error: "account_selection_required",
+    },
+});

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