@udibo/oauth2 0.26.0 → 0.28.0

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.28.0",
   "description": "A flexible OAuth2 toolkit: framework-agnostic authorization & resource servers, a typed client, Hono adapters (including a backend-for-frontend), and React bindings.",
   "keywords": [
     "authorization-server",