@udibo/oauth2 0.4.0 → 0.5.0

package/esm/server/authorization-server.js

@@ -106,7 +106,7 @@ const AUTHORIZATION_CODE_GRANT_TYPE = "authorization_code";
  * 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.
@@ -123,7 +123,7 @@ export const ENDPOINT_PATHS = Object
 /**
  * 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
@@ -148,6 +148,7 @@ function isDeviceAuthorizationGrant(grant) {
  * - 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
@@ -189,7 +190,6 @@ export class AuthorizationServer extends ResourceServer {
     #userClaims;
     #introspectionClaims;
     #canIntrospectToken;
-    /** Resolves the per-request {@link AuthorizationServerContext}. */
     #resolve;
     /**
      * Creates an authorization server from the given
@@ -203,6 +203,7 @@ export class AuthorizationServer extends ResourceServer {
             resolve: options.resolve,
             Scope: options.Scope,
             realm: options.realm,
+            clockSkewSeconds: options.clockSkewSeconds,
             errorFormat: options.errorFormat,
             throwOnError: options.throwOnError,
         });
@@ -251,7 +252,6 @@ export class AuthorizationServer extends ResourceServer {
     async authorizationContext(request) {
         return await this.#resolve(request);
     }
-    /** Resolves the endpoint URLs for a request (issuer-derived unless set). */
     #resolvedEndpoints(context) {
         const { issuer } = context;
         const endpoints = {};
@@ -309,22 +309,15 @@ export class AuthorizationServer extends ResourceServer {
             },
         });
     }
-    /**
-     * 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. */
     addCacheHeaders(error) {
         error.headers.set("Cache-Control", "no-store");
         error.headers.set("Pragma", "no-cache");
     }
     /**
-     * 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.
      */
     prepareClientAuthError(request) {
         return (error) => {
@@ -334,16 +327,11 @@ export class AuthorizationServer extends ResourceServer {
             }
         };
     }
-    /**
-     * Rejects a client that is not registered for a grant type
-     * (RFC 6749 Section 5.2 `unauthorized_client`).
-     */
     #assertGrantAuthorized(client, grantType) {
         if (!client.grants?.includes(grantType)) {
             throw new UnauthorizedClientError(`client is not authorized to use the ${grantType} grant type`);
         }
     }
-    /** The grant a token request's `grant_type` dispatches to. */
     #grantFromBody(body) {
         const grantType = body.get("grant_type");
         if (typeof grantType !== "string") {
@@ -381,8 +369,10 @@ export class AuthorizationServer extends ResourceServer {
      * 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`.
      */
     async handleTokenRequest(request) {
         try {
@@ -401,6 +391,8 @@ export class AuthorizationServer extends ResourceServer {
      * 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.
      */
     async mintIdToken(token, context) {
         if (!this.signingKeys || !token.user || !context.issuer)
@@ -418,9 +410,10 @@ export class AuthorizationServer extends ResourceServer {
         };
         if (token.nonce)
             claims.nonce = token.nonce;
+        else
+            delete claims.nonce;
         return await signJwt(key, claims);
     }
-    /** OIDC claims released for a user: `userClaims` under the winning `sub`. */
     async #oidcClaims(user, scope, authenticationContext) {
         return {
             ...(await this.#userClaims?.(user, scope, snapshotAuthenticationContext(authenticationContext)) ?? {}),
@@ -506,8 +499,12 @@ export class AuthorizationServer extends ResourceServer {
      * `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
@@ -519,11 +516,14 @@ export class AuthorizationServer extends ResourceServer {
      * 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
@@ -568,12 +568,7 @@ export class AuthorizationServer extends ResourceServer {
             return this.handleError(error);
         }
     }
-    /**
-     * The logout parameters, from the query string on GET and the form body on
-     * POST — RP-Initiated Logout §2 permits both. A verified `id_token_hint`
-     * contributes the subject and the audience; an unverifiable one contributes
-     * nothing rather than refusing the logout.
-     */
+    // RP-Initiated Logout §2: parameters come from the GET query or POST body.
     async #endSessionParameters(request) {
         const url = new URL(request.url);
         const params = request.method === "POST"
@@ -581,15 +576,19 @@ export class AuthorizationServer extends ResourceServer {
             : url.searchParams;
         const idTokenHint = params.get("id_token_hint");
         const hint = idTokenHint ? await this.#readIdTokenHint(idTokenHint) : null;
+        const clientId = params.get("client_id");
+        if (clientId && hint && hint.audiences.length > 0 &&
+            !hint.audiences.includes(clientId)) {
+            throw new InvalidRequestError("client_id does not match the audience of id_token_hint");
+        }
         return {
-            clientId: params.get("client_id") ?? hint?.audience ?? null,
+            clientId: clientId ?? hint?.audiences[0] ?? null,
             subject: hint?.subject ?? null,
             postLogoutRedirectUri: params.get("post_logout_redirect_uri") ?? null,
             state: params.get("state") ?? null,
             logoutHint: params.get("logout_hint") ?? null,
         };
     }
-    /** The subject and audience of a signature-valid `id_token_hint`, if any. */
     async #readIdTokenHint(idTokenHint) {
         const key = await this.signingKeys?.getSigningKey();
         if (!key)
@@ -600,17 +599,16 @@ export class AuthorizationServer extends ResourceServer {
         if (!payload)
             return null;
         const aud = payload.aud;
-        const audience = typeof aud === "string"
-            ? aud
-            : Array.isArray(aud) && typeof aud[0] === "string"
-                ? aud[0]
-                : null;
+        const audiences = typeof aud === "string"
+            ? [aud]
+            : Array.isArray(aud)
+                ? aud.filter((value) => typeof value === "string")
+                : [];
         return {
             subject: typeof payload.sub === "string" ? payload.sub : null,
-            audience,
+            audiences,
         };
     }
-    /** The client the logout names, or null when it named none we can find. */
     async #resolveEndSessionClient(request, params) {
         if (!params.clientId)
             return null;
@@ -622,11 +620,6 @@ export class AuthorizationServer extends ResourceServer {
             return null;
         }
     }
-    /**
-     * The `post_logout_redirect_uri` to honor, with `state` appended — or
-     * undefined when the request named none, named no resolvable client, or
-     * named a URI that client did not register.
-     */
     #postLogoutRedirect(client, params) {
         const requested = params.postLogoutRedirectUri;
         if (!requested || !client)
@@ -643,8 +636,8 @@ export class AuthorizationServer extends ResourceServer {
     /**
      * 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) {
         const url = new URL(request.url);
@@ -667,10 +660,12 @@ export class AuthorizationServer extends ResourceServer {
      * 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
@@ -690,11 +685,6 @@ export class AuthorizationServer extends ResourceServer {
             return this.#authorizeErrorResponse(error, target.url);
         }
     }
-    /**
-     * The authorize flow proper, recording the redirect target on `target` as
-     * soon as one is verified so {@link handleAuthorizeRequest} can report later
-     * failures to the client.
-     */
     async #authorize(request, target, authenticateUser, handleConsent) {
         const params = this.parseAuthorizeParameters(request);
         const grant = this.#authorizationCodeGrant();
@@ -744,10 +734,6 @@ export class AuthorizationServer extends ResourceServer {
         redirectUrl.searchParams.set("code", authorizationCode.code);
         return Response.redirect(redirectUrl.toString(), 302);
     }
-    /**
-     * Reports an authorize failure: an RFC 6749 Section 4.1.2.1 error redirect
-     * once a verified `redirectUrl` exists, otherwise a plain error response.
-     */
     #authorizeErrorResponse(error, redirectUrl) {
         if (!redirectUrl || !(error instanceof Error) || !isOAuth2Error(error)) {
             return this.handleError(error);
@@ -790,10 +776,6 @@ export class AuthorizationServer extends ResourceServer {
         }
         return grant;
     }
-    /**
-     * The client the authorize request names, once it is registered for the
-     * authorization code grant.
-     */
     async #resolveAuthorizeClient(grant, clientId, services) {
         if (!clientId) {
             throw new InvalidRequestError("client_id parameter required");
@@ -802,11 +784,6 @@ export class AuthorizationServer extends ResourceServer {
         this.#assertGrantAuthorized(client, AUTHORIZATION_CODE_GRANT_TYPE);
         return client;
     }
-    /**
-     * The URL the browser is sent back to: the requested `redirect_uri` once it
-     * matches a registration, or the client's first literal registration when the
-     * request omitted one.
-     */
     #resolveRedirectTarget(client, redirectUri) {
         if (!client.redirectUris?.length) {
             throw new UnauthorizedClientError("no authorized redirect_uri");
@@ -821,7 +798,6 @@ export class AuthorizationServer extends ResourceServer {
         }
         return new URL(redirectUri ?? defaultRedirectUri);
     }
-    /** Rejects any `response_type` other than the `code` this endpoint issues. */
     #validateResponseType(responseType) {
         if (!responseType) {
             throw new InvalidRequestError("response_type required");
@@ -831,10 +807,6 @@ export class AuthorizationServer extends ResourceServer {
             throw new UnsupportedResponseTypeError("response_type not supported");
         }
     }
-    /**
-     * Rejects PKCE parameters the grant cannot honor (RFC 7636 Section 4.3), and
-     * a `code_challenge` malformed for a method whose shape Section 4.2 fixes.
-     */
     #validateChallenge(grant, params) {
         const { challenge, challengeMethod } = params;
         if (challengeMethod && !challenge) {
@@ -847,11 +819,6 @@ export class AuthorizationServer extends ResourceServer {
             throw new InvalidRequestError("code_challenge must be 43-128 characters using [A-Z] / [a-z] / [0-9] / - / . / _ / ~");
         }
     }
-    /**
-     * The scope the authorization code will carry: the requested scope narrowed
-     * by the token service, then by consent when the user has not already
-     * pre-authorized it. A `Response` short-circuits the flow (a consent page).
-     */
     async #resolveScopeAndConsent(options) {
         const { grant, client, user, requestedScope, authorizedScope, services, handleConsent, } = options;
         const acceptedScope = await grant.acceptedScope(client, user, requestedScope, services.tokenService);
@@ -972,8 +939,11 @@ export class AuthorizationServer extends ResourceServer {
      * 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
@@ -1022,16 +992,18 @@ export class AuthorizationServer extends ResourceServer {
                 if (context.issuer) {
                     response.iss = context.issuer;
                 }
-                const user = token.user;
-                if (user?.id) {
-                    response.sub = user.id;
-                }
-                if (user?.username) {
-                    response.username = user.username;
+                if (token.user) {
+                    response.sub = this.#subjectOf(token.user);
+                    const username = token.user.username;
+                    if (typeof username === "string" && username) {
+                        response.username = username;
+                    }
                 }
                 if (this.#introspectionClaims) {
+                    const extensions = await this.#introspectionClaims(token);
+                    const { sub: _sub, username: _username, ...machineExtensions } = extensions;
                     response = {
-                        ...await this.#introspectionClaims(token),
+                        ...(token.user ? extensions : machineExtensions),
                         ...response,
                     };
                 }
@@ -1118,7 +1090,6 @@ export class AuthorizationServer extends ResourceServer {
         const { challengeMethods } = grant;
         return Object.keys(challengeMethods).filter((method) => typeof challengeMethods[method] === "function");
     }
-    /** Publishes the resolved URLs of the OIDC (or plain OAuth2) endpoints. */
     #advertiseEndpoints(metadata, endpoints, oidc) {
         for (const [key, endpoint] of ADVERTISED_ENTRIES) {
             if (endpoint.oidc !== oidc)
@@ -1222,13 +1193,18 @@ export class AuthorizationServer extends ResourceServer {
  * - `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.

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

@@ -24,7 +24,7 @@ export interface AuthorizationCodeGrantServices<Client extends ClientInterface,
  * @see https://datatracker.ietf.org/doc/html/rfc7636
  */
 export interface AuthorizationCodeGrantOptions<Client extends ClientInterface, User, S extends AbstractScope> extends GrantOptions<Client, User, S, AuthorizationCodeGrantServices<Client, User, S>> {
-    /** Allow optional refresh token. Defaults to true. */
+    /** Whether to issue a refresh token with the access token. Defaults to `true`. */
     allowRefreshToken?: boolean;
     /** Custom PKCE challenge methods. Defaults to S256 only. */
     challengeMethods?: ChallengeMethods;
@@ -166,8 +166,12 @@ export declare class AuthorizationCodeGrant<Client extends ClientInterface, User
      * Exchanges an authorization code for an access token. If PKCE was used
      * during authorization, the code_verifier must be provided.
      *
-     * The code is claimed by revoking it: only the caller whose revoke wins
-     * receives a token, so concurrent exchanges of one code cannot both succeed.
+     * The code is claimed by revoking it before the client-match, verifier, and
+     * `redirect_uri` checks, so a failed exchange still consumes the code. Only
+     * the caller whose revoke wins receives a token, given an atomic
+     * `authorizationCodeService.revoke`. Presenting a code that already minted
+     * tokens asks `tokenService.revokeCode` to revoke those tokens and fails with
+     * `invalid_grant` (RFC 6819 §4.4.1.1).
      *
      * @throws {InvalidRequestError} When `code` is missing, a required `code_verifier` is absent, or the verifier is malformed.
      * @throws {InvalidGrantError} When the code is unknown, expired, already claimed, or its verifier or `redirect_uri` does not match.

package/esm/server/grants/authorization-code.js

@@ -164,8 +164,12 @@ export class AuthorizationCodeGrant extends AbstractGrant {
      * Exchanges an authorization code for an access token. If PKCE was used
      * during authorization, the code_verifier must be provided.
      *
-     * The code is claimed by revoking it: only the caller whose revoke wins
-     * receives a token, so concurrent exchanges of one code cannot both succeed.
+     * The code is claimed by revoking it before the client-match, verifier, and
+     * `redirect_uri` checks, so a failed exchange still consumes the code. Only
+     * the caller whose revoke wins receives a token, given an atomic
+     * `authorizationCodeService.revoke`. Presenting a code that already minted
+     * tokens asks `tokenService.revokeCode` to revoke those tokens and fails with
+     * `invalid_grant` (RFC 6819 §4.4.1.1).
      *
      * @throws {InvalidRequestError} When `code` is missing, a required `code_verifier` is absent, or the verifier is malformed.
      * @throws {InvalidGrantError} When the code is unknown, expired, already claimed, or its verifier or `redirect_uri` does not match.

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

@@ -27,7 +27,7 @@ export interface DeviceAuthorizationGrantServices<Client extends ClientInterface
  * @see https://datatracker.ietf.org/doc/html/rfc8628
  */
 export interface DeviceAuthorizationGrantOptions<Client extends ClientInterface, User, S extends AbstractScope> extends GrantOptions<Client, User, S, DeviceAuthorizationGrantServices<Client, User, S>> {
-    /** Allow optional refresh token. Defaults to true. */
+    /** Whether to issue a refresh token with the access token. Defaults to `true`. */
     allowRefreshToken?: boolean;
 }
 /**

package/esm/server/grants/grant.d.ts

@@ -72,7 +72,11 @@ export interface GrantOptions<Client extends ClientInterface, User, Scope extend
     resolve: (request: Request) => Services | Promise<Services>;
     /** Scope constructor used to parse scope strings. Defaults to {@linkcode BasicScope}. */
     Scope?: ScopeConstructor<Scope>;
-    /** Allow optional refresh token. */
+    /**
+     * Whether to issue a refresh token with tokens that have a user, when the
+     * token service generates one. Defaults to `false`; tokens without a user
+     * never get one.
+     */
     allowRefreshToken?: boolean;
 }
 /**
@@ -82,8 +86,7 @@ export interface GrantOptions<Client extends ClientInterface, User, Scope extend
  * interface the grant resolves. A subclass implements {@link token}, reaches
  * its services through {@link resolveServices}, and overrides
  * {@link getAuthenticatedClient} only when it authenticates clients by
- * something other than their registered credentials (as the authorization-code
- * grant does for PKCE).
+ * something other than their registered credentials.
  */
 export declare abstract class AbstractGrant<Client extends ClientInterface, User, Scope extends AbstractScope = BasicScope, Services extends GrantServices<Client, User, Scope> = GrantServices<Client, User, Scope>> implements DispatchableGrant<Client, User, Scope> {
     #private;
@@ -91,7 +94,7 @@ export declare abstract class AbstractGrant<Client extends ClientInterface, User
     abstract readonly grantType: string;
     /** Constructor used to parse scope strings into {@linkcode Scope} objects. */
     Scope: ScopeConstructor<Scope>;
-    /** Allow optional refresh token. Defaults to false. */
+    /** Whether tokens with a user are issued a refresh token. */
     allowRefreshToken: boolean;
     /** Creates a grant from the shared {@linkcode GrantOptions}. */
     constructor(options: GrantOptions<Client, User, Scope, Services>);
@@ -142,16 +145,20 @@ export declare abstract class AbstractGrant<Client extends ClientInterface, User
      * owner whose authorization a rotation could carry forward.
      * `authenticationContext` is verified event evidence, snapshotted before
      * generation and carried to storage. Omit it when unknown; it is discarded
-     * for tokens with no user.
+     * for tokens with no user. `familyExpiresAt` is the ceiling of an existing
+     * rotation family the token joins (the refresh grant passes it); the
+     * expiries are clamped to it before the access token string is generated,
+     * so a signed token's `exp` matches the stored expiry.
      */
-    generateToken(client: Client, user: User | undefined, scope: Scope | null | undefined, tokenService: TokenServiceInterface<Client, User, Scope>, authenticationContext?: AuthenticationContext): Promise<Token<Client, User, Scope>>;
+    generateToken(client: Client, user: User | undefined, scope: Scope | null | undefined, tokenService: TokenServiceInterface<Client, User, Scope>, authenticationContext?: AuthenticationContext, familyExpiresAt?: Date): Promise<Token<Client, User, Scope>>;
     /**
      * Authenticates the client presenting this grant's token request against the
      * grant's own `clientService`, from the credentials the request presents.
      *
      * Override to apply grant-specific authentication rules — the
-     * authorization-code grant accepts a PKCE `code_verifier` in place of a
-     * client secret for public clients.
+     * authorization-code grant, when configured with
+     * `requireClientAuthentication: false`, looks up a client that presents a
+     * PKCE `code_verifier` by id instead of authenticating it.
      *
      * @throws {InvalidClientError} If authentication fails.
      */

package/esm/server/grants/grant.js

@@ -27,13 +27,12 @@ import { authenticateClientCredentials, extractClientCredentials, } from "../cli
  * interface the grant resolves. A subclass implements {@link token}, reaches
  * its services through {@link resolveServices}, and overrides
  * {@link getAuthenticatedClient} only when it authenticates clients by
- * something other than their registered credentials (as the authorization-code
- * grant does for PKCE).
+ * something other than their registered credentials.
  */
 export class AbstractGrant {
     /** Constructor used to parse scope strings into {@linkcode Scope} objects. */
     Scope;
-    /** Allow optional refresh token. Defaults to false. */
+    /** Whether tokens with a user are issued a refresh token. */
     allowRefreshToken;
     #resolve;
     /** Creates a grant from the shared {@linkcode GrantOptions}. */
@@ -114,16 +113,16 @@ export class AbstractGrant {
      * owner whose authorization a rotation could carry forward.
      * `authenticationContext` is verified event evidence, snapshotted before
      * generation and carried to storage. Omit it when unknown; it is discarded
-     * for tokens with no user.
+     * for tokens with no user. `familyExpiresAt` is the ceiling of an existing
+     * rotation family the token joins (the refresh grant passes it); the
+     * expiries are clamped to it before the access token string is generated,
+     * so a signed token's `exp` matches the stored expiry.
      */
-    async generateToken(client, user, scope, tokenService, authenticationContext) {
+    async generateToken(client, user, scope, tokenService, authenticationContext, familyExpiresAt) {
         const event = user === undefined
             ? undefined
             : snapshotAuthenticationContext(authenticationContext);
-        const token = {
-            accessToken: await tokenService.generateAccessToken(client, user, scope, event),
-            client,
-        };
+        const token = { accessToken: "", client };
         if (event)
             token.authenticationContext = event;
         if (user !== undefined)
@@ -133,11 +132,13 @@ export class AbstractGrant {
         const accessTokenExpiresAt = await tokenService.accessTokenExpiresAt(client, user, scope);
         if (accessTokenExpiresAt)
             token.accessTokenExpiresAt = accessTokenExpiresAt;
+        let result = token;
+        let ceiling = familyExpiresAt;
         if (this.allowRefreshToken && user !== undefined) {
             const refreshToken = await tokenService.generateRefreshToken(client, user, scope);
             if (refreshToken) {
                 const familyCreatedAt = new Date();
-                const result = {
+                const withRefresh = {
                     ...token,
                     refreshToken,
                     familyId: crypto.randomUUID(),
@@ -145,24 +146,31 @@ export class AbstractGrant {
                 };
                 const refreshTokenExpiresAt = await tokenService.refreshTokenExpiresAt(client, user, scope);
                 if (refreshTokenExpiresAt) {
-                    result.refreshTokenExpiresAt = refreshTokenExpiresAt;
+                    withRefresh.refreshTokenExpiresAt = refreshTokenExpiresAt;
                 }
-                const familyExpiresAt = await tokenService
+                const newFamilyExpiresAt = await tokenService
                     .refreshTokenFamilyExpiresAt?.(client, user, familyCreatedAt, scope);
-                if (familyExpiresAt)
-                    this.capAtFamilyExpiry(result, familyExpiresAt);
-                return result;
+                if (newFamilyExpiresAt) {
+                    ceiling = ceiling && ceiling < newFamilyExpiresAt
+                        ? ceiling
+                        : newFamilyExpiresAt;
+                }
+                result = withRefresh;
             }
         }
-        return token;
+        if (ceiling)
+            this.capAtFamilyExpiry(result, ceiling);
+        result.accessToken = await tokenService.generateAccessToken(client, user, scope, event, result.accessTokenExpiresAt);
+        return result;
     }
     /**
      * Authenticates the client presenting this grant's token request against the
      * grant's own `clientService`, from the credentials the request presents.
      *
      * Override to apply grant-specific authentication rules — the
-     * authorization-code grant accepts a PKCE `code_verifier` in place of a
-     * client secret for public clients.
+     * authorization-code grant, when configured with
+     * `requireClientAuthentication: false`, looks up a client that presents a
+     * PKCE `code_verifier` by id instead of authenticating it.
      *
      * @throws {InvalidClientError} If authentication fails.
      */

package/esm/server/grants/password.d.ts

@@ -29,7 +29,7 @@ export interface PasswordGrantServices<Client extends ClientInterface, User, S e
 }
 /** Options for configuring the password grant. */
 export interface PasswordGrantOptions<Client extends ClientInterface, User, S extends AbstractScope> extends GrantOptions<Client, User, S, PasswordGrantServices<Client, User, S>> {
-    /** Allow optional refresh token. Defaults to true. */
+    /** Whether to issue a refresh token with the access token. Defaults to `true`. */
     allowRefreshToken?: boolean;
 }
 /**

package/esm/server/grants/refresh-token.d.ts

@@ -30,7 +30,9 @@ export interface TokenReuseEvent<Client extends ClientInterface, User> {
 export interface RefreshTokenGrantOptions<Client extends ClientInterface, User, S extends AbstractScope> extends Omit<GrantOptions<Client, User, S, RefreshTokenGrantServices<Client, User, S>>, "allowRefreshToken"> {
     /**
      * Called when reuse detection catches a rotated-out refresh token being
-     * replayed (after the family was revoked) — record it as a security event.
+     * replayed by the client it was issued to (after the family was revoked) —
+     * record it as a security event. Reuse detection runs only when the token
+     * service implements both `getRevokedRefreshToken` and `revokeFamily`.
      *
      * Trigger point `token-reuse` (see `docs/trigger-points.md`).
      * Fire-and-forget: it is awaited, but a throw is caught and logged, never
@@ -71,8 +73,9 @@ export declare class RefreshTokenGrant<Client extends ClientInterface, User, S e
      * authorization.
      *
      * @throws {InvalidRequestError} If `refresh_token` is missing.
-     * @throws {InvalidGrantError} If the refresh token is unknown or expired, or
-     * its family has outlived the absolute cap.
+     * @throws {InvalidGrantError} If the refresh token is unknown or expired, its
+     * family has outlived the absolute cap, or a concurrent exchange already
+     * claimed it.
      * @throws {InvalidClientError} If the token was issued to another client.
      * @throws {InvalidScopeError} If the requested scope exceeds the original grant.
      */