@udibo/oauth2 0.4.1 → 0.5.0

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

@@ -37,14 +37,18 @@ export interface EndSessionContext<Client extends ClientInterface> {
     /** The logout request itself. */
     request: Request;
     /**
-     * The relying party the logout names — from a signature-valid
-     * `id_token_hint`'s audience, or from `client_id`. Null when the request
-     * named none, or named one this server does not know.
+     * The relying party the logout names — from `client_id`, else from the first
+     * audience of a signature-valid `id_token_hint`. When the request sends
+     * both, `client_id` must be one of the hint's audiences (OIDC RP-Initiated
+     * Logout 1.0 §2); a mismatch is a 400 `invalid_request` and this callback
+     * never runs. Null when the request named none, or named one this server
+     * does not know.
      */
     client: Client | null;
     /**
-     * The `sub` of a signature-valid `id_token_hint`. Null when the request sent
-     * no hint, or one that did not verify — so a session lookup keyed on it must
+     * The `sub` of an `id_token_hint` that verifies against the current signing
+     * key. Null when the request sent no hint, or one that did not verify
+     * (including one signed by a key since rotated out of signing) — so a session lookup keyed on it must
      * handle "no subject", which is the ordinary case for a client that never
      * requested `openid`.
      */
@@ -77,7 +81,8 @@ export interface EndSessionResult {
  * request that reaches the endpoint, including ones whose parameters do not
  * check out — refusing to end a session because a *redirect* was unauthorized
  * would leave the person signed in, which is the opposite of what they asked
- * for.
+ * for. The one request that never reaches it is a self-contradictory one: a
+ * `client_id` that is not an audience of the `id_token_hint` it came with.
  */
 export type EndSessionFn<Client extends ClientInterface> = (context: EndSessionContext<Client>) => EndSessionResult | void | Promise<EndSessionResult | void>;
 /** Grants configuration for the authorization server. */
@@ -156,7 +161,7 @@ export interface AuthorizationServerOptions<Client extends ClientInterface, User
      * the token endpoint mints an `id_token` for user-bound grants with the
      * `openid` scope, and the JWKS/UserInfo endpoints and
      * `openid-configuration` metadata go live. In multi-instance deploys load
-     * one persisted key on every instance (see `signing-keys.ts`).
+     * one persisted key on every instance (see `importSigningKeyJwk`).
      */
     signingKeys?: SigningKeyProvider;
     /**
@@ -190,8 +195,9 @@ export interface AuthorizationServerOptions<Client extends ClientInterface, User
     /**
      * Extra OIDC claims for the id_token and UserInfo response (e.g. `name`,
      * `email` when the scope allows). Merged under the protocol claims — `sub`
-     * (from `subjectOf`) and the id_token's `iss`/`aud`/`iat`/`exp`/`nonce`
-     * always win.
+     * (from `subjectOf`) and the id_token's `iss`/`aud`/`iat`/`exp` always win,
+     * and `nonce` is the authorization request's own: present exactly when that
+     * request carried one, whatever is returned here.
      * The third argument is this credential's recorded authentication event,
      * including on refresh and UserInfo. Return its fields to emit them; never
      * substitute a user's newer session event. It is absent for legacy records.
@@ -202,9 +208,13 @@ export interface AuthorizationServerOptions<Client extends ClientInterface, User
      * permits them), so a resource server validating by introspection sees the
      * same authorization claims a JWT access token carries — feed it the same
      * computation `userClaims` uses and the two validation strategies stay in
-     * field-level parity. Called with the introspected token; the RFC 7662
-     * protocol fields (`active`, `scope`, `client_id`, `token_type`, `exp`,
-     * `iss`, `sub`, `username`) always win over anything it returns.
+     * field-level parity. Called with the introspected token. Each RFC 7662
+     * protocol field the server sets (`active`, `scope`, `client_id`,
+     * `token_type`, `exp`, `iss`, `sub`, `username`) wins over anything it
+     * returns. One the server leaves unset is not stripped — a `scope` for an
+     * unscoped token reaches the response — except `sub` and `username`, which
+     * are dropped for a token with no user so that their presence keeps meaning
+     * "there is a resource owner" (RFC 9700 §4.15.1).
      */
     introspectionClaims?: (token: Token<Client, User, S>) => Promise<Record<string, unknown>> | Record<string, unknown>;
     /**
@@ -246,8 +256,9 @@ export interface AuthorizationServerOptions<Client extends ClientInterface, User
  *
  * - `{ user, authorizedScope?, authenticationContext? }` — user is authenticated; the authorize flow
  *   continues. `authorizedScope` declares scopes the user has already
- *   pre-authorized for this client; anything in the requested scope not
- *   covered by it triggers consent. **Omitting `authorizedScope` means
+ *   pre-authorized for this client; consent is needed unless it covers the
+ *   whole accepted scope (the requested scope after the token service's
+ *   `acceptedScope`). **Omitting `authorizedScope` means
  *   "nothing pre-authorized"** — so any requested scope needs consent: the
  *   framework calls `handleConsent` when one is configured, and otherwise
  *   treats the request as consented and grants the accepted scope. To
@@ -272,8 +283,9 @@ export type AuthenticateUserFn<User> = (request: Request) => Promise<{
  * Called when the requested scope is not already covered by the user's
  * pre-authorized scope. Return one of:
  *
- * - `{ approved: true, scope? }` — consent granted. `scope` optionally
- *   narrows the granted scope (RFC 6749 §3.3 allows partial grants).
+ * - `{ approved: true, scope? }` — consent granted. `scope`, when set,
+ *   replaces the granted scope (RFC 6749 §3.3 allows partial grants). The
+ *   server does not check it against the requested scope, so return a subset.
  * - `{ approved: false }` — consent denied. The framework redirects to
  *   `redirect_uri` with `error=access_denied`.
  * - A `Response` — short-circuits the rest of the authorize flow and is
@@ -304,8 +316,8 @@ export interface ResolvedEndpoints {
     endSession?: string;
 }
 /**
- * Every endpoint the authorization server serves, by name — the seven it
- * advertises in its metadata (the {@link ResolvedEndpoints} keys) plus
+ * Every endpoint the authorization server serves, by name — the eight it can
+ * advertise in its metadata (the {@link ResolvedEndpoints} keys) plus
  * `metadata` and `oidcMetadata`, the two discovery documents that are served
  * but never advertised. Index {@link ENDPOINT_PATHS} and
  * {@link ENDPOINT_METHODS} with it to enumerate the whole surface.
@@ -317,7 +329,7 @@ export type EndpointKey = "authorization" | "token" | "revocation" | "introspect
  * these paths — as the Hono adapter's `routes()` does — to match what the
  * server advertises in its RFC 8414 metadata.
  *
- * Covers the whole served surface: the seven endpoints the server advertises,
+ * Covers the whole served surface: the eight endpoints the server can advertise,
  * plus the two discovery documents (`metadata` for RFC 8414,
  * `oidcMetadata` for OIDC Discovery) that are served but never advertised.
  * Pair it with {@link ENDPOINT_METHODS} to enumerate path *and* verbs.
@@ -333,7 +345,7 @@ export declare const ENDPOINT_PATHS: Readonly<Record<EndpointKey, string>>;
 /**
  * The HTTP methods each endpoint in {@link ENDPOINT_PATHS} answers — `POST` for
  * the token-style endpoints, `GET` for authorize/JWKS/discovery, both for
- * UserInfo. Read it instead of re-deriving verbs per endpoint, so a hand-rolled
+ * UserInfo and end-session. Read it instead of re-deriving verbs per endpoint, so a hand-rolled
  * mount answers exactly what the built-in `routes()` does.
  *
  * @example
@@ -352,6 +364,7 @@ export declare const ENDPOINT_METHODS: Readonly<Record<EndpointKey, readonly str
  * - Introspection endpoint (POST /introspect) - RFC 7662
  * - Device authorization endpoint (POST /device_authorization) - RFC 8628
  * - Metadata endpoint (GET /.well-known/oauth-authorization-server) - RFC 8414
+ * - OIDC discovery, JWKS, UserInfo, and end-session endpoints, when configured
  *
  * Framework-agnostic: each `handle*Request` method takes a web `Request` and
  * returns a `Response`, so an adapter routes its endpoints to them. Extends
@@ -424,19 +437,12 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * (`grant.issuesIdToken !== false`).
      */
     createTokenResponse(token: Token<Client, User, S>, context: AuthorizationServerContext<Client, User, S>, grant?: DispatchableGrant<Client, User, S>): Promise<Response>;
-    /**
-     * Applies `Cache-Control: no-store` and `Pragma: no-cache` headers to an
-     * error per RFC 6749 Section 5.2. The headers land on both the rethrown
-     * error (when {@link throwOnError} is true) and the generated response.
-     */
+    /** Sets the RFC 6749 §5.2 `no-store` cache headers on an error. */
     private addCacheHeaders;
     /**
-     * Error-prepare callback for the endpoints that authenticate the client
-     * (token, revocation, introspection, device authorization). Attaches the
-     * RFC 6749 Section 5.2 cache headers, and — when client authentication was
-     * attempted via the `Authorization` header and failed with a 401 — the
-     * matching `WWW-Authenticate: Basic` challenge that RFC 6749 Section 5.2
-     * requires.
+     * Error-prepare callback for client-authenticated endpoints: cache headers,
+     * plus the RFC 6749 §5.2 `WWW-Authenticate: Basic` challenge on a 401 when
+     * the request sent an `Authorization` header.
      */
     private prepareClientAuthError;
     /**
@@ -444,14 +450,18 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * Supports multiple grant types based on the configured grants.
      *
      * A malformed request — wrong method, a content-type other than
-     * `application/x-www-form-urlencoded`, or an unsupported grant — is a 400
-     * `invalid_request`.
+     * `application/x-www-form-urlencoded`, or no `grant_type` — is a 400
+     * `invalid_request`. A `grant_type` with no registered grant is
+     * `unsupported_grant_type`, checked before client authentication; a client
+     * not registered for the grant is `unauthorized_client`.
      */
     handleTokenRequest(request: Request): Promise<Response>;
     /**
      * Mint an OIDC id_token for a user-bound token whose scope includes
      * `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.
      */
     mintIdToken(token: Token<Client, User, S>, context: AuthorizationServerContext<Client, User, S>): Promise<string | undefined>;
     /**
@@ -488,8 +498,12 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * `endSession` does the ending and this method does the protocol around it:
      * identifying the relying party, authorizing the return trip, and shaping
      * the response. `endSession` is always called, even when nothing else about
-     * the request checks out, because a logout that refuses to log anyone out is
-     * the worst possible failure mode for this endpoint.
+     * the client, hint, or redirect checks out, because a logout that refuses to
+     * log anyone out is the worst possible failure mode for this endpoint. The
+     * sole exception is a `client_id` that is not among the audiences of a
+     * verified `id_token_hint` sent with it: OIDC RP-Initiated Logout 1.0 §2
+     * requires the two to agree, so that request is a 400 `invalid_request`
+     * and ends no session.
      *
      * **Authorizing `post_logout_redirect_uri` is the whole security surface.**
      * It is matched by **exact string** against the resolved client's
@@ -501,11 +515,14 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * registered, the browser is **not** sent there — it goes to `fallback` if
      * the app supplied one, or gets a bare 204.
      *
-     * `id_token_hint` is verified against the signing keys but its expiry is
-     * ignored: by the time anyone logs out the id_token naming their session has
-     * usually expired, and it is a hint, not authority. `client_id` is accepted
-     * as the fallback identifier the spec allows. `state` rides along only to a
-     * URI that passed authorization.
+     * `id_token_hint` is verified against the current signing key only — a hint
+     * signed by a key since rotated out of signing yields no subject — and its
+     * expiry is ignored: by the time anyone logs out the id_token naming their
+     * session has usually expired, and it is a hint, not authority. `client_id`,
+     * when sent, names the client ahead of the hint's audience, and when both
+     * are sent `client_id` must be one of the hint's audiences — a mismatch is
+     * a 400 `invalid_request` (OIDC RP-Initiated Logout 1.0 §2). `state` rides
+     * along only to a URI that passed authorization.
      *
      * Wire the app's session teardown through the `endSession` **constructor
      * option**; this method answers 404 without it, and the discovery document
@@ -529,18 +546,20 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
     /**
      * Parses authorization request parameters from the query string.
      *
-     * The authorization endpoint is GET-only (RFC 6749 Section 3.1 requires GET
-     * and only permits POST), so parameters are read from `url.searchParams`.
+     * Reads only `url.searchParams`: RFC 6749 Section 3.1 requires GET support
+     * and leaves POST optional, and this server serves the endpoint on GET.
      */
     parseAuthorizeParameters(request: Request): AuthorizeParameters;
     /**
      * Handles an authorization request (GET /authorize).
      * Used for the authorization code flow.
      *
-     * Once the request has named a redirect URI the client registered, failures
-     * are reported to that URI as an RFC 6749 Section 4.1.2.1 error redirect;
-     * before that they are error responses from this endpoint, since there is no
-     * verified place to send the user back to.
+     * Once a redirect target is verified — the requested `redirect_uri` matched
+     * a registration, or the request omitted it and the client has a literal
+     * registration, whose first entry is used — failures are reported to it as
+     * an RFC 6749 Section 4.1.2.1 error redirect; before that they are error
+     * responses from this endpoint, since there is no verified place to send the
+     * user back to.
      *
      * Requires a grant extending {@linkcode AuthorizationCodeGrant} registered
      * under `authorization_code`; without one the endpoint answers 500
@@ -608,8 +627,11 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * that field describes how an access token is presented, and its `exp` is
      * the refresh token's own expiry.
      *
-     * A token with no user — the client acting as its own resource owner, as
-     * the client credentials grant issues — carries no `sub` and no `username`;
+     * A token with a user carries `sub` from `subjectOf` — the same value the
+     * id_token and UserInfo carry — and `username` when the user has one. A
+     * token with no user — the client acting as its own resource owner, as the
+     * client credentials grant issues — carries neither, even when
+     * {@linkcode AuthorizationServerOptions.introspectionClaims} returns them;
      * `client_id` identifies the machine. `sub` is optional in RFC 7662, and
      * leaving it absent keeps `sub` an unambiguous "there is a resource owner"
      * signal rather than overloading `client_id` into the subject namespace
@@ -694,13 +716,18 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
  * - `POST {revocationEndpoint}` → `handleRevocationRequest`
  * - `POST {introspectionEndpoint}` → `handleIntrospectionRequest`
  * - `POST {deviceAuthorizationEndpoint}` → `handleDeviceAuthorizationRequest`
- * - `GET  /.well-known/oauth-authorization-server` → `handleMetadataRequest`
+ * - `GET {jwksEndpoint}` → `handleJwksRequest`
+ * - `GET`/`POST {userinfoEndpoint}` → `handleUserInfoRequest`
+ * - `GET /.well-known/oauth-authorization-server` → `handleMetadataRequest`
+ * - `GET /.well-known/openid-configuration` → `handleOidcMetadataRequest`
+ *
+ * The two discovery paths are matched literally, not against the issuer.
  *
- * The authorization endpoint is deliberately **not** routed: `/authorize`
- * needs an `authenticateUser` (and optional `handleConsent`) callback this
- * transport has no access to, and in real flows it's a browser navigation,
- * never a call through the client's `fetch`. A request to it throws an
- * actionable error pointing at `handleAuthorizeRequest`. Any other path also
+ * The authorization and end-session endpoints are deliberately **not**
+ * routed: in real flows both are browser navigations, never calls through the
+ * client's `fetch`, and `/authorize` needs an `authenticateUser` (and optional
+ * `handleConsent`) callback this transport has no access to. A request to
+ * either throws an error naming the handler to drive directly. Any other path also
  * throws — the helper intentionally does not proxy arbitrary paths; if a call
  * lands here unexpectedly, that's a wiring bug worth surfacing rather than
  * silently forwarding.