@udibo/oauth2 0.26.0 → 0.27.0

package/README.md

@@ -89,8 +89,10 @@ The package implements these specifications, with the limits noted:
 - [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068) JWT access tokens, opt-in;
   access tokens are opaque by default.
 - [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html):
-  the authorization code flow, ES256 ID tokens, `nonce`, and UserInfo. The
-  server does not act on `prompt` or `max_age`.
+  the authorization code flow, ES256 ID tokens, `nonce`, UserInfo, and the
+  `prompt`, `max_age` and `acr_values` controls, with `auth_time` and `acr` in
+  the ID token. Your login callback performs any re-authentication they need,
+  and there is no `claims` request parameter.
 - OpenID Connect [Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)
   and [RP-Initiated Logout 1.0](https://openid.net/specs/openid-connect-rpinitiated-1_0.html).
 - [OpenID Connect Back-Channel Logout 1.0](https://openid.net/specs/openid-connect-backchannel-1_0.html),

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

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

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

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

package/dist/cli/idp/server.js

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

package/dist/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.
  *
@@ -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;
+}

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

@@ -21,7 +21,7 @@
  * @module
  */
 import type { AuthorizeParameters } from "../models/authorization-code.ts";
-import type { AuthenticationContext } from "../models/authentication.ts";
+import type { AuthenticationContext, AuthenticationRequest } from "../models/authentication.ts";
 import type { ClientInterface } from "../models/client.ts";
 import type { Token, TokenResponse } from "../models/token.ts";
 import type { AuthorizationServerMetadata } from "../models/responses.ts";
@@ -288,6 +288,32 @@ export interface AuthorizationServerOptions<Client extends ClientInterface, User
      *   integer.
      */
     maxBodyBytes?: number;
+    /**
+     * The `prompt` values the authorization endpoint accepts, advertised as
+     * `prompt_values_supported`. A request carrying any other value is refused
+     * with `invalid_request`.
+     *
+     * The server enforces `none`, `login` and `consent` itself. List another
+     * value, such as `select_account` or `create`, only when your
+     * `authenticateUser` honors it: the server passes it through in the
+     * {@linkcode AuthenticationRequest} and cannot check the result.
+     *
+     * @default ["none", "login", "consent"]
+     * @throws {TypeError} From the constructor when an entry is empty or
+     *   contains a space or non-ASCII character.
+     */
+    promptValuesSupported?: readonly string[];
+    /**
+     * Authentication context class references your `authenticateUser` can
+     * achieve, advertised as `acr_values_supported` in the OIDC discovery
+     * document. It does not restrict `acr_values`: the request's preferences
+     * reach `authenticateUser` either way, and the ID token's `acr` is what the
+     * returned `authenticationContext` records.
+     *
+     * @throws {TypeError} From the constructor when an entry is empty or
+     *   contains a space or non-ASCII character.
+     */
+    acrValuesSupported?: readonly string[];
 }
 /**
  * Function to authenticate the user during authorization.
@@ -305,17 +331,29 @@ export interface AuthorizationServerOptions<Client extends ClientInterface, User
  *   pre-authorize everything, return the requested scope as `authorizedScope`.
  *   Supply only verified event claims in `authenticationContext`; the code,
  *   token and refresh descendants retain a snapshot. Omit unknown claims.
+ *   Set `reauthenticated: true` only when the user actively authenticated in
+ *   response to this authorization request.
  * - `null` — explicit denial. The framework redirects the browser to
  *   `redirect_uri` with `error=access_denied`. Use this for "the user said
  *   no", not for "the user isn't signed in yet."
  * - A `Response` — short-circuits the rest of the authorize flow and is
  *   returned to the browser as-is. Use this to redirect to a login page,
- *   render an interstitial, etc.
+ *   render an interstitial, etc. Under `prompt=none` the server answers
+ *   `login_required` instead of returning it.
+ *
+ * The second argument carries the request's validated `prompt`, `max_age` and
+ * `acr_values`; the server always passes it. Before issuing a code the server
+ * checks the returned user against it with
+ * {@linkcode satisfiesAuthenticationRequest} and answers `login_required` when
+ * the check fails, so send the user to sign in again (return a `Response`)
+ * whenever the session cannot meet it. Report the `acr` the login achieved in
+ * `authenticationContext`, never the requested one.
  */
-export type AuthenticateUserFn<User> = (request: Request) => Promise<{
+export type AuthenticateUserFn<User> = (request: Request, authentication?: AuthenticationRequest) => Promise<{
     user: User;
     authorizedScope?: AbstractScope;
     authenticationContext?: AuthenticationContext;
+    reauthenticated?: boolean;
 } | Response | null>;
 /**
  * Function to handle user consent during authorization.
@@ -330,9 +368,14 @@ export type AuthenticateUserFn<User> = (request: Request) => Promise<{
  *   `redirect_uri` with `error=access_denied`.
  * - A `Response` — short-circuits the rest of the authorize flow and is
  *   returned to the browser as-is. Use this to render a consent page that
- *   later resubmits to the authorize endpoint with the user's decision.
+ *   later resubmits to the authorize endpoint with the user's decision. Under
+ *   `prompt=none` the server answers `consent_required` instead.
+ *
+ * With `prompt=consent` the server calls it even when the scope is already
+ * authorized, and the fourth argument, always passed, says so: ask again
+ * rather than reusing a stored grant.
  */
-export type HandleConsentFn<Client extends ClientInterface, S extends AbstractScope> = (client: Client, requestedScope: S | undefined, user: unknown) => Promise<{
+export type HandleConsentFn<Client extends ClientInterface, S extends AbstractScope> = (client: Client, requestedScope: S | undefined, user: unknown, authentication?: AuthenticationRequest) => Promise<{
     approved: boolean;
     scope?: S;
 } | Response>;
@@ -450,7 +493,8 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * @throws {RangeError} If `maxBodyBytes` or `maxTokenBodyBytes` is not a
      *   positive integer.
      * @throws {TypeError} If `realm` contains a character outside printable
-     *   ASCII.
+     *   ASCII, or a `promptValuesSupported` or `acrValuesSupported` entry is
+     *   empty or contains a space or non-ASCII character.
      */
     constructor(options: AuthorizationServerOptions<Client, User, S>);
     /**
@@ -508,7 +552,9 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * `openid`, or `undefined` when the OIDC surface is off (no signing keys),
      * the token has no user, the scope lacks `openid`, or no issuer resolved.
      * The id_token's `aud` is the client id and it expires one hour after
-     * issue.
+     * issue. Its `auth_time` and `acr` are the token's recorded
+     * `authenticationContext`, present exactly when the context has them,
+     * whatever `userClaims` returns.
      */
     mintIdToken(token: Token<Client, User, S>, context: AuthorizationServerContext<Client, User, S>): Promise<string | undefined>;
     /**
@@ -828,6 +874,8 @@ export { AbstractAuthorizationCodeService, type AbstractAuthorizationCodeService
 export type { DeviceAuthorizationServiceInterface } from "./services/device-authorization.ts";
 export type { UserServiceInterface } from "./services/user.ts";
 export type { AuthorizationCode, AuthorizeParameters, } from "../models/authorization-code.ts";
+export type { AuthenticationRequest } from "../models/authentication.ts";
+export { type AuthenticationOutcome, satisfiesAuthenticationRequest, } from "./authentication-request.ts";
 export type { DeviceAuthorization } from "../models/device-authorization.ts";
 export type { AuthorizationServerMetadata, DeviceAuthorizationResponse, ErrorResponse, OAuth2ErrorCode, } from "../models/responses.ts";
 export { challengeMethods, CODE_VERIFIER_MAX_LENGTH, CODE_VERIFIER_MIN_LENGTH, CODE_VERIFIER_PATTERN, generateCodeChallenge, generateCodeVerifier, generateState, getChallengeMethod, validateCodeChallenge, validateCodeVerifier, verifyCodeChallenge, } from "../utils/pkce.ts";

package/dist/server/authorization-server.js

@@ -21,8 +21,9 @@
  * @module
  */
 import { snapshotAuthenticationContext } from "../utils/authentication-context.js";
-import { AccessDeniedError, InvalidRequestError, InvalidTokenError, isOAuth2Error, OAuth2Error, ServerError, toOAuth2Error, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, } from "../errors.js";
+import { AccessDeniedError, ConsentRequiredError, InvalidRequestError, InvalidTokenError, isOAuth2Error, LoginRequiredError, OAuth2Error, ServerError, toOAuth2Error, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, } from "../errors.js";
 import { authenticateClientCredentials, extractClientCredentials, } from "./client-authentication.js";
+import { assertSupportedValues, authenticationShortfall, DEFAULT_PROMPT_VALUES_SUPPORTED, parseAuthenticationRequest, } from "./authentication-request.js";
 import { isRedirectUriPattern, matchRedirectUri } from "./redirect-uri.js";
 import { AuthorizationCodeGrant } from "./grants/authorization-code.js";
 import { DeviceAuthorizationGrant } from "./grants/device-authorization.js";
@@ -194,6 +195,8 @@ export class AuthorizationServer extends ResourceServer {
     #endSession;
     #isPublicSuffix;
     #maxBodyBytes;
+    #promptValuesSupported;
+    #acrValuesSupported;
     #subjectOf;
     #userClaims;
     #introspectionClaims;
@@ -208,7 +211,8 @@ export class AuthorizationServer extends ResourceServer {
      * @throws {RangeError} If `maxBodyBytes` or `maxTokenBodyBytes` is not a
      *   positive integer.
      * @throws {TypeError} If `realm` contains a character outside printable
-     *   ASCII.
+     *   ASCII, or a `promptValuesSupported` or `acrValuesSupported` entry is
+     *   empty or contains a space or non-ASCII character.
      */
     constructor(options) {
         super({
@@ -242,6 +246,10 @@ export class AuthorizationServer extends ResourceServer {
         this.#isPublicSuffix = options.isPublicSuffix;
         this.#maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
         assertMaxBodyBytes(this.#maxBodyBytes, "maxBodyBytes");
+        this.#promptValuesSupported = assertSupportedValues("promptValuesSupported", options.promptValuesSupported ?? DEFAULT_PROMPT_VALUES_SUPPORTED);
+        if (options.acrValuesSupported) {
+            this.#acrValuesSupported = assertSupportedValues("acrValuesSupported", options.acrValuesSupported);
+        }
         this.#subjectOf = options.subjectOf ?? defaultSubjectOf;
         this.#userClaims = options.userClaims;
         this.#introspectionClaims = options.introspectionClaims;
@@ -466,7 +474,9 @@ export class AuthorizationServer extends ResourceServer {
      * `openid`, or `undefined` when the OIDC surface is off (no signing keys),
      * the token has no user, the scope lacks `openid`, or no issuer resolved.
      * The id_token's `aud` is the client id and it expires one hour after
-     * issue.
+     * issue. Its `auth_time` and `acr` are the token's recorded
+     * `authenticationContext`, present exactly when the context has them,
+     * whatever `userClaims` returns.
      */
     async mintIdToken(token, context) {
         if (!this.signingKeys || !token.user || !context.issuer)
@@ -486,6 +496,15 @@ export class AuthorizationServer extends ResourceServer {
             claims.nonce = token.nonce;
         else
             delete claims.nonce;
+        const event = token.authenticationContext;
+        if (event?.auth_time !== undefined)
+            claims.auth_time = event.auth_time;
+        else
+            delete claims.auth_time;
+        if (event?.acr !== undefined)
+            claims.acr = event.acr;
+        else
+            delete claims.acr;
         return await signJwt(key, claims);
     }
     async #oidcClaims(user, scope, authenticationContext) {
@@ -785,12 +804,21 @@ export class AuthorizationServer extends ResourceServer {
         this.#validateResponseType(params.responseType);
         const requestedScope = grant.parseScope(params.scope);
         this.#validateChallenge(grant, params);
-        const authResult = await authenticateUser(request);
-        if (authResult instanceof Response)
-            return authResult;
+        const authentication = parseAuthenticationRequest(new URL(request.url).searchParams, this.#promptValuesSupported);
+        const silent = authentication.prompt.includes("none");
+        const authResult = await authenticateUser(request, authentication);
+        if (authResult instanceof Response) {
+            if (!silent)
+                return authResult;
+            await authResult.body?.cancel();
+            throw new LoginRequiredError("the user must sign in");
+        }
         if (!authResult) {
             throw new AccessDeniedError("authentication required");
         }
+        const shortfall = authenticationShortfall(authentication, authResult, Date.now());
+        if (shortfall)
+            throw new LoginRequiredError(shortfall);
         const { user, authorizedScope } = authResult;
         const authenticationContext = snapshotAuthenticationContext(authResult.authenticationContext);
         if (grant.requirePKCE && !params.challenge) {
@@ -804,6 +832,7 @@ export class AuthorizationServer extends ResourceServer {
             authorizedScope,
             services,
             handleConsent,
+            authentication,
         });
         if (consented instanceof Response)
             return consented;
@@ -909,14 +938,23 @@ export class AuthorizationServer extends ResourceServer {
         }
     }
     async #resolveScopeAndConsent(options) {
-        const { grant, client, user, requestedScope, authorizedScope, services, handleConsent, } = options;
+        const { grant, client, user, requestedScope, authorizedScope, services, handleConsent, authentication, } = options;
         const acceptedScope = await grant.acceptedScope(client, user, requestedScope, services.tokenService);
         let scope = acceptedScope ?? undefined;
-        const needsConsent = scope !== undefined && !(authorizedScope && authorizedScope.has(scope));
+        const forceConsent = authentication.prompt.includes("consent");
+        if (forceConsent && !handleConsent) {
+            throw new ConsentRequiredError("prompt=consent requires a consent handler");
+        }
+        const needsConsent = forceConsent ||
+            (scope !== undefined && !(authorizedScope && authorizedScope.has(scope)));
         if (needsConsent && handleConsent) {
-            const consent = await handleConsent(client, scope, user);
-            if (consent instanceof Response)
-                return consent;
+            const consent = await handleConsent(client, scope, user, authentication);
+            if (consent instanceof Response) {
+                if (!authentication.prompt.includes("none"))
+                    return consent;
+                await consent.body?.cancel();
+                throw new ConsentRequiredError("the user must consent");
+            }
             if (!consent.approved) {
                 throw new AccessDeniedError("user denied consent");
             }
@@ -1197,6 +1235,7 @@ export class AuthorizationServer extends ResourceServer {
         metadata.response_types_supported = hasAuthCodeGrant ? ["code"] : [];
         if (hasAuthCodeGrant) {
             metadata.authorization_response_iss_parameter_supported = true;
+            metadata.prompt_values_supported = [...this.#promptValuesSupported];
         }
         const scopesSupported = context.scopesSupported ?? this.scopesSupported;
         if (scopesSupported) {
@@ -1206,6 +1245,9 @@ export class AuthorizationServer extends ResourceServer {
             this.#advertiseEndpoints(metadata, endpoints, true);
             metadata.id_token_signing_alg_values_supported = ["ES256"];
             metadata.subject_types_supported = ["public"];
+            if (hasAuthCodeGrant && this.#acrValuesSupported?.length) {
+                metadata.acr_values_supported = [...this.#acrValuesSupported];
+            }
         }
         return metadata;
     }
@@ -1404,6 +1446,7 @@ export { PasswordGrant } from "./grants/password.js";
 export { DeviceAuthorizationGrant } from "./grants/device-authorization.js";
 export { AbstractTokenService, } from "./services/token.js";
 export { AbstractAuthorizationCodeService, } from "./services/authorization-code.js";
+export { satisfiesAuthenticationRequest, } from "./authentication-request.js";
 export { challengeMethods, CODE_VERIFIER_MAX_LENGTH, CODE_VERIFIER_MIN_LENGTH, CODE_VERIFIER_PATTERN, generateCodeChallenge, generateCodeVerifier, generateState, getChallengeMethod, validateCodeChallenge, validateCodeVerifier, verifyCodeChallenge, } from "../utils/pkce.js";
 export { encodeBasicAuth, parseBasicAuth, tryParseBasicAuth, } from "../utils/basic-auth.js";
 export { checkRedirectUriPattern, isRedirectUriPattern, matchRedirectUri, } from "./redirect-uri.js";

package/dist/server/mod.d.ts

@@ -9,14 +9,15 @@
  * @module
  */
 export type { ClientCredentials, ClientInterface } from "../models/client.ts";
-export type { AuthenticationContext } from "../models/authentication.ts";
+export type { AuthenticationContext, AuthenticationRequest, } from "../models/authentication.ts";
 export type { IntrospectionResponse, RefreshToken, Token, TokenResponse, } from "../models/token.ts";
 export { AbstractScope, BasicScope } from "../models/scope.ts";
 export type { ScopeConstructor } from "../models/scope.ts";
 export { Authorization, authorizationFromClaims, } from "../models/authorization.ts";
 export type { AuthorizationFailure, AuthorizationInit, OrganizationContext, RequireConditions, } from "../models/authorization.ts";
-export { AccessDeniedError, AuthorizationPendingError, ExpiredTokenError, InsufficientPermissionsError, InsufficientScopeError, InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, InvalidTokenError, isOAuth2Error, OAuth2Error, ServerError, SlowDownError, TemporarilyUnavailableError, toOAuth2Error, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, UnsupportedTokenTypeError, } from "../errors.ts";
+export { AccessDeniedError, AccountSelectionRequiredError, AuthorizationPendingError, ConsentRequiredError, ExpiredTokenError, InsufficientPermissionsError, InsufficientScopeError, InteractionRequiredError, InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, InvalidTokenError, isOAuth2Error, LoginRequiredError, OAuth2Error, ServerError, SlowDownError, TemporarilyUnavailableError, toOAuth2Error, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, UnsupportedTokenTypeError, } from "../errors.ts";
 export type { OAuth2ErrorClass, OAuth2ProblemDetailsExtensions, } from "../errors.ts";
+export { type AuthenticationOutcome, satisfiesAuthenticationRequest, } from "./authentication-request.ts";
 export type { TokenReaderInterface } from "./services/token.ts";
 export { checkRedirectUriPattern, isRedirectUriPattern, matchRedirectUri, } from "./redirect-uri.ts";
 export type { IsPublicSuffix, RedirectUriPatternRule, RedirectUriPatternViolation, } from "./redirect-uri.ts";

package/dist/server/mod.js

@@ -10,5 +10,6 @@
  */
 export { AbstractScope, BasicScope } from "../models/scope.js";
 export { Authorization, authorizationFromClaims, } from "../models/authorization.js";
-export { AccessDeniedError, AuthorizationPendingError, ExpiredTokenError, InsufficientPermissionsError, InsufficientScopeError, InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, InvalidTokenError, isOAuth2Error, OAuth2Error, ServerError, SlowDownError, TemporarilyUnavailableError, toOAuth2Error, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, UnsupportedTokenTypeError, } from "../errors.js";
+export { AccessDeniedError, AccountSelectionRequiredError, AuthorizationPendingError, ConsentRequiredError, ExpiredTokenError, InsufficientPermissionsError, InsufficientScopeError, InteractionRequiredError, InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, InvalidTokenError, isOAuth2Error, LoginRequiredError, OAuth2Error, ServerError, SlowDownError, TemporarilyUnavailableError, toOAuth2Error, UnauthorizedClientError, UnsupportedGrantTypeError, UnsupportedResponseTypeError, UnsupportedTokenTypeError, } from "../errors.js";
+export { satisfiesAuthenticationRequest, } from "./authentication-request.js";
 export { checkRedirectUriPattern, isRedirectUriPattern, matchRedirectUri, } from "./redirect-uri.js";

package/package.json

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