@udibo/oauth2 0.1.0

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

@@ -0,0 +1,103 @@
+/**
+ * Device Authorization Grant implementation (RFC 8628).
+ *
+ * This grant type allows devices with limited input capabilities
+ * to obtain user authorization by having the user authorize
+ * the request on a secondary device.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8628
+ * @module
+ */
+import type { ClientInterface } from "../../models/client.js";
+import type { Token } from "../../models/token.js";
+import type { AbstractScope, BasicScope } from "../../models/scope.js";
+import type { DeviceAuthorization } from "../../models/device-authorization.js";
+import type { DeviceAuthorizationServiceInterface } from "../services/device-authorization.js";
+import { AbstractGrant, type GrantOptions, type GrantServices } from "./grant.js";
+/**
+ * Services required by the device authorization grant.
+ */
+export interface DeviceAuthorizationGrantServices<Client extends ClientInterface, User, S extends AbstractScope> extends GrantServices<Client, User, S> {
+    /** Generates, stores, and polls device/user codes for the device flow. */
+    deviceAuthorizationService: DeviceAuthorizationServiceInterface<Client, User, S>;
+}
+/**
+ * Options for configuring the device authorization grant.
+ *
+ * @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. */
+    allowRefreshToken?: boolean;
+}
+/**
+ * The Device Authorization Grant type (RFC 8628).
+ *
+ * This grant is used for devices that lack a browser or have limited
+ * input capabilities (TVs, game consoles, CLI tools, etc.).
+ *
+ * Flow:
+ * 1. Device requests authorization, receives device_code and user_code
+ * 2. User visits verification_uri on another device and enters user_code
+ * 3. User authorizes or denies the request
+ * 4. Device polls token endpoint with device_code until authorized/denied/expired
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8628
+ */
+export declare class DeviceAuthorizationGrant<Client extends ClientInterface, User, S extends AbstractScope = BasicScope> extends AbstractGrant<Client, User, S, DeviceAuthorizationGrantServices<Client, User, S>> {
+    #private;
+    /**
+     * The grant type identifier.
+     * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.4
+     */
+    readonly grantType = "urn:ietf:params:oauth:grant-type:device_code";
+    /** Creates the grant from its {@linkcode DeviceAuthorizationGrantOptions}. */
+    constructor(options: DeviceAuthorizationGrantOptions<Client, User, S>);
+    /**
+     * Initiates a device authorization request.
+     *
+     * Called by the device authorization endpoint to create a new
+     * pending authorization that the user can approve. Resolves its own
+     * `deviceAuthorizationService` from the request.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.1
+     */
+    initiateDeviceAuthorization(client: Client, request: Request, scope?: S | null): Promise<DeviceAuthorization<Client, User, S>>;
+    /**
+     * Handles a token request for the device authorization grant.
+     *
+     * The client polls this endpoint with the device_code until:
+     * - The user authorizes the request (returns tokens)
+     * - The user denies the request (returns access_denied)
+     * - The device_code expires (returns expired_token)
+     * - The client polls too frequently (returns slow_down)
+     *
+     * Ownership is authenticated before the authorization is acted on: a client
+     * polling a device code issued to a different client is refused
+     * `invalid_grant` whether that code is live or expired, and the record is
+     * left untouched, so a poll the caller is not entitled to make can neither
+     * destroy the authorization nor distinguish its state.
+     *
+     * The device code is claimed by revoking it once the user has approved, so
+     * concurrent polls of one approved device code cannot both receive a token.
+     * Recording the poll time is bookkeeping for `slow_down` only: it is skipped
+     * on every outcome that revokes the authorization. When the store **raises**
+     * for the vanished record — as it must, if a lost race is to be
+     * distinguishable — the poll is refused with `invalid_grant` rather than
+     * surfacing the store's own error. A store whose poll write instead resolves
+     * for a record that is gone leaves that poll answering
+     * `authorization_pending`, and the next one gets `invalid_grant` from the
+     * existence check; the code is still single-use either way, because only the
+     * caller whose `revoke` resolved `true` is issued a token.
+     *
+     * @throws {InvalidRequestError} If `device_code` is missing.
+     * @throws {InvalidGrantError} If the device code is unknown, was issued to another client, or was already claimed by another poll.
+     * @throws {ExpiredTokenError} If the device code has expired.
+     * @throws {SlowDownError} If the client polls faster than the interval allows.
+     * @throws {AccessDeniedError} If the user denied the request.
+     * @throws {AuthorizationPendingError} If the user has not yet approved the request.
+     * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.4
+     * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.5
+     */
+    token(request: Request, client: Client, body: FormData): Promise<Token<Client, User, S>>;
+}

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

@@ -0,0 +1,156 @@
+/**
+ * Device Authorization Grant implementation (RFC 8628).
+ *
+ * This grant type allows devices with limited input capabilities
+ * to obtain user authorization by having the user authorize
+ * the request on a secondary device.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8628
+ * @module
+ */
+import { AccessDeniedError, AuthorizationPendingError, ExpiredTokenError, InvalidGrantError, InvalidRequestError, SlowDownError, } from "../../errors.js";
+import { AbstractGrant, } from "./grant.js";
+/**
+ * The Device Authorization Grant type (RFC 8628).
+ *
+ * This grant is used for devices that lack a browser or have limited
+ * input capabilities (TVs, game consoles, CLI tools, etc.).
+ *
+ * Flow:
+ * 1. Device requests authorization, receives device_code and user_code
+ * 2. User visits verification_uri on another device and enters user_code
+ * 3. User authorizes or denies the request
+ * 4. Device polls token endpoint with device_code until authorized/denied/expired
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8628
+ */
+export class DeviceAuthorizationGrant extends AbstractGrant {
+    /**
+     * The grant type identifier.
+     * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.4
+     */
+    grantType = "urn:ietf:params:oauth:grant-type:device_code";
+    /** Creates the grant from its {@linkcode DeviceAuthorizationGrantOptions}. */
+    constructor(options) {
+        super({
+            ...options,
+            allowRefreshToken: options.allowRefreshToken ?? true,
+        });
+    }
+    /**
+     * Initiates a device authorization request.
+     *
+     * Called by the device authorization endpoint to create a new
+     * pending authorization that the user can approve. Resolves its own
+     * `deviceAuthorizationService` from the request.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.1
+     */
+    async initiateDeviceAuthorization(client, request, scope) {
+        const { deviceAuthorizationService } = await this.resolveServices(request);
+        const deviceAuthorization = {
+            deviceCode: await deviceAuthorizationService.generateDeviceCode(client, scope),
+            userCode: await deviceAuthorizationService.generateUserCode(client, scope),
+            expiresAt: await deviceAuthorizationService.expiresAt(client, scope),
+            client,
+            scope,
+            interval: deviceAuthorizationService.interval,
+        };
+        return await deviceAuthorizationService.save(deviceAuthorization);
+    }
+    /**
+     * Handles a token request for the device authorization grant.
+     *
+     * The client polls this endpoint with the device_code until:
+     * - The user authorizes the request (returns tokens)
+     * - The user denies the request (returns access_denied)
+     * - The device_code expires (returns expired_token)
+     * - The client polls too frequently (returns slow_down)
+     *
+     * Ownership is authenticated before the authorization is acted on: a client
+     * polling a device code issued to a different client is refused
+     * `invalid_grant` whether that code is live or expired, and the record is
+     * left untouched, so a poll the caller is not entitled to make can neither
+     * destroy the authorization nor distinguish its state.
+     *
+     * The device code is claimed by revoking it once the user has approved, so
+     * concurrent polls of one approved device code cannot both receive a token.
+     * Recording the poll time is bookkeeping for `slow_down` only: it is skipped
+     * on every outcome that revokes the authorization. When the store **raises**
+     * for the vanished record — as it must, if a lost race is to be
+     * distinguishable — the poll is refused with `invalid_grant` rather than
+     * surfacing the store's own error. A store whose poll write instead resolves
+     * for a record that is gone leaves that poll answering
+     * `authorization_pending`, and the next one gets `invalid_grant` from the
+     * existence check; the code is still single-use either way, because only the
+     * caller whose `revoke` resolved `true` is issued a token.
+     *
+     * @throws {InvalidRequestError} If `device_code` is missing.
+     * @throws {InvalidGrantError} If the device code is unknown, was issued to another client, or was already claimed by another poll.
+     * @throws {ExpiredTokenError} If the device code has expired.
+     * @throws {SlowDownError} If the client polls faster than the interval allows.
+     * @throws {AccessDeniedError} If the user denied the request.
+     * @throws {AuthorizationPendingError} If the user has not yet approved the request.
+     * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.4
+     * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.5
+     */
+    async token(request, client, body) {
+        const { deviceAuthorizationService, tokenService } = await this
+            .resolveServices(request);
+        const deviceCode = body.get("device_code");
+        if (typeof deviceCode !== "string") {
+            throw new InvalidRequestError("device_code parameter required");
+        }
+        const authorization = await deviceAuthorizationService.getByDeviceCode(deviceCode);
+        if (!authorization) {
+            throw new InvalidGrantError("invalid device_code");
+        }
+        if (authorization.client.id !== client.id) {
+            throw new InvalidGrantError("device_code was issued to another client");
+        }
+        if (authorization.expiresAt < new Date()) {
+            await deviceAuthorizationService.revoke(authorization);
+            throw new ExpiredTokenError("device_code has expired");
+        }
+        if (authorization.lastPolled) {
+            const elapsed = Date.now() - authorization.lastPolled.getTime();
+            const minInterval = authorization.interval * 1000;
+            if (elapsed < minInterval) {
+                authorization.interval += 5;
+                await this.#recordPoll(deviceAuthorizationService, authorization, deviceCode);
+                throw new SlowDownError("polling too frequently");
+            }
+        }
+        if (authorization.denied) {
+            await deviceAuthorizationService.revoke(authorization);
+            throw new AccessDeniedError("authorization request was denied");
+        }
+        if (!authorization.authorized || !authorization.user) {
+            await this.#recordPoll(deviceAuthorizationService, authorization, deviceCode);
+            throw new AuthorizationPendingError("authorization request is pending user approval");
+        }
+        const { user, scope } = authorization;
+        if (!await deviceAuthorizationService.revoke(authorization)) {
+            throw new InvalidGrantError("device_code already used");
+        }
+        const token = await this.generateToken(client, user, scope, tokenService);
+        return await tokenService.save(token);
+    }
+    async #recordPoll(deviceAuthorizationService, authorization, deviceCode) {
+        try {
+            await deviceAuthorizationService.updateLastPolled(authorization);
+        }
+        catch (error) {
+            let stillStored;
+            try {
+                stillStored = await deviceAuthorizationService.getByDeviceCode(deviceCode);
+            }
+            catch {
+                throw error;
+            }
+            if (stillStored)
+                throw error;
+            throw new InvalidGrantError("device_code already used");
+        }
+    }
+}

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

@@ -0,0 +1,165 @@
+/**
+ * Base grant type implementation for OAuth2.
+ *
+ * Provides the abstract base class and the framework-facing grant contract for
+ * implementing OAuth2 grant types per RFC 6749.
+ *
+ * **Service resolution.** A grant holds no storage. It is constructed with a
+ * `resolve(request) => services` function that returns the full set of services
+ * that grant needs, and the base resolves them per request through
+ * `resolveServices`. The grant infers its `Client`/`User`/`Scope` types from
+ * that `resolve` return, so a grant can be built standalone (e.g. for tests) and
+ * the {@link AuthorizationServer} infers its own generics from the grants. The
+ * base provides stateless helpers (`acceptedScope`, `generateToken`) that take
+ * the resolved services as arguments.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4
+ * @module
+ */
+import type { ClientCredentials, ClientInterface } from "../../models/client.js";
+import type { RefreshToken, Token } from "../../models/token.js";
+import type { AuthenticationContext } from "../../models/authentication.js";
+import type { AbstractScope, ScopeConstructor } from "../../models/scope.js";
+import { BasicScope } from "../../models/scope.js";
+import type { ClientServiceInterface } from "../services/client.js";
+import type { TokenServiceInterface } from "../services/token.js";
+/**
+ * The core services every grant needs: client lookup/authentication and token
+ * storage. Each grant defines its own services interface by extending this with
+ * the grant-specific services it resolves (e.g. `authorizationCodeService`).
+ */
+export interface GrantServices<Client extends ClientInterface, User, Scope extends AbstractScope = BasicScope> {
+    /** Looks up and authenticates clients presenting a token request. */
+    clientService: ClientServiceInterface<Client, User>;
+    /** Generates and persists access and refresh tokens. */
+    tokenService: TokenServiceInterface<Client, User, Scope>;
+}
+/**
+ * The framework-facing grant contract that {@link AuthorizationServer}
+ * dispatches through. It carries no grant-specific service types, so any grant —
+ * including a third-party grant with its own services — is assignable to it and
+ * lives in the server's grant map without `any`. Grants resolve their own
+ * services from the request, so these methods take no services argument.
+ */
+export interface DispatchableGrant<Client extends ClientInterface, User, Scope extends AbstractScope = BasicScope> {
+    /** The OAuth2 `grant_type` value this grant handles (e.g. `authorization_code`). */
+    readonly grantType: string;
+    /**
+     * Whether this grant's tokens represent an end-user authentication, making
+     * them eligible for an id_token. Treated as `true` when absent; grants with
+     * no authentication event (client_credentials) set `false`.
+     */
+    readonly issuesIdToken?: boolean;
+    /**
+     * Authenticates the client presenting this grant's token request. `body` is
+     * the request's form body, parsed once by the token endpoint — a grant reads
+     * its parameters from it instead of consuming the request.
+     */
+    getAuthenticatedClient(request: Request, body: FormData): Promise<Client>;
+    /**
+     * Exchanges the request for a token. `body` is the request's form body,
+     * parsed once by the token endpoint.
+     */
+    token(request: Request, client: Client, body: FormData): Promise<Token<Client, User, Scope>>;
+}
+/**
+ * Configuration shared by all grants: how to reach the services the grant
+ * needs, plus the scope and refresh-token settings. Each grant's own options
+ * type extends this with its grant-specific settings.
+ */
+export interface GrantOptions<Client extends ClientInterface, User, Scope extends AbstractScope = BasicScope, Services extends GrantServices<Client, User, Scope> = GrantServices<Client, User, Scope>> {
+    /** Resolves the services this grant needs for a request. */
+    resolve: (request: Request) => Services | Promise<Services>;
+    /** Scope constructor used to parse scope strings. Defaults to {@linkcode BasicScope}. */
+    Scope?: ScopeConstructor<Scope>;
+    /** Allow optional refresh token. */
+    allowRefreshToken?: boolean;
+}
+/**
+ * Abstract base class for grant type implementations.
+ *
+ * Extend this to create custom grant types, parameterized by the services
+ * 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).
+ */
+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;
+    /** The OAuth2 `grant_type` value this grant handles (e.g. `authorization_code`). */
+    abstract readonly grantType: string;
+    /** Constructor used to parse scope strings into {@linkcode Scope} objects. */
+    Scope: ScopeConstructor<Scope>;
+    /** Allow optional refresh token. Defaults to false. */
+    allowRefreshToken: boolean;
+    /** Creates a grant from the shared {@linkcode GrantOptions}. */
+    constructor(options: GrantOptions<Client, User, Scope, Services>);
+    /** The services this grant needs for `request`, from its `resolve` option. */
+    protected resolveServices(request: Request): Promise<Services>;
+    /** Parses a scope string into a Scope object. */
+    parseScope(scopeText?: string | null): Scope | undefined;
+    /**
+     * Validates and returns the accepted scope for the client and user, per the
+     * `TokenServiceInterface.acceptedScope` contract: a returned scope replaces
+     * the requested one (narrowing), `null`/`undefined` accepts the requested
+     * scope as-is, and `false` rejects.
+     *
+     * `user` is `undefined` when the client is acting as its own resource owner
+     * (client credentials, RFC 6749 §4.4), so the token service decides scope
+     * from the client alone.
+     *
+     * Throws InvalidScopeError if the scope is rejected.
+     */
+    acceptedScope(client: Client, user: User | undefined, scope: Scope | null | undefined, tokenService: TokenServiceInterface<Client, User, Scope>): Promise<Scope | null | undefined>;
+    /**
+     * Extracts client credentials from a request: HTTP Basic first, then the
+     * `client_id`/`client_secret` of the already-parsed `body`. Override to add
+     * grant-specific credential rules (as the authorization-code grant does for
+     * PKCE).
+     *
+     * @throws {InvalidClientError} If the request presents no usable credentials.
+     */
+    protected getClientCredentials(request: Request, body: FormData): ClientCredentials;
+    /**
+     * Clamps a token's expiries to the absolute expiry of its rotation family,
+     * so nothing derived from a family outlives it — an access token issued a
+     * moment before the ceiling included. Mutates `token`; a token with no
+     * expiry of its own takes the family's.
+     */
+    protected capAtFamilyExpiry(token: Token<Client, User, Scope> | RefreshToken<Client, User, Scope>, familyExpiresAt: Date): void;
+    /**
+     * Generates a token for a client and user from a resolved `tokenService`.
+     * Includes a refresh token if allowed, which starts a new rotation family:
+     * `familyId` plus the `familyCreatedAt` anchor the refresh grant caps
+     * rotations against. When the token service caps families
+     * ({@linkcode TokenServiceInterface.refreshTokenFamilyExpiresAt}), both
+     * expiries are clamped to the new family's ceiling.
+     *
+     * Pass `user: undefined` for a token the client holds as its own resource
+     * owner (client credentials, RFC 6749 §4.4). Such a token is never issued a
+     * refresh token whatever `allowRefreshToken` says — there is no resource
+     * 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.
+     */
+    generateToken(client: Client, user: User | undefined, scope: Scope | null | undefined, tokenService: TokenServiceInterface<Client, User, Scope>, authenticationContext?: AuthenticationContext): 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.
+     *
+     * @throws {InvalidClientError} If authentication fails.
+     */
+    getAuthenticatedClient(request: Request, body: FormData): Promise<Client>;
+    /**
+     * Handles a token request. `body` is the request's form body, parsed once by
+     * the token endpoint; the grant resolves the services it needs from the
+     * request internally.
+     */
+    abstract token(request: Request, client: Client, body: FormData): Promise<Token<Client, User, Scope>>;
+}

package/esm/server/grants/grant.js

@@ -0,0 +1,173 @@
+/**
+ * Base grant type implementation for OAuth2.
+ *
+ * Provides the abstract base class and the framework-facing grant contract for
+ * implementing OAuth2 grant types per RFC 6749.
+ *
+ * **Service resolution.** A grant holds no storage. It is constructed with a
+ * `resolve(request) => services` function that returns the full set of services
+ * that grant needs, and the base resolves them per request through
+ * `resolveServices`. The grant infers its `Client`/`User`/`Scope` types from
+ * that `resolve` return, so a grant can be built standalone (e.g. for tests) and
+ * the {@link AuthorizationServer} infers its own generics from the grants. The
+ * base provides stateless helpers (`acceptedScope`, `generateToken`) that take
+ * the resolved services as arguments.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4
+ * @module
+ */
+import { snapshotAuthenticationContext } from "../../utils/authentication-context.js";
+import { BasicScope } from "../../models/scope.js";
+import { InvalidScopeError } from "../../errors.js";
+import { authenticateClientCredentials, extractClientCredentials, } from "../client-authentication.js";
+/**
+ * Abstract base class for grant type implementations.
+ *
+ * Extend this to create custom grant types, parameterized by the services
+ * 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).
+ */
+export class AbstractGrant {
+    /** Constructor used to parse scope strings into {@linkcode Scope} objects. */
+    Scope;
+    /** Allow optional refresh token. Defaults to false. */
+    allowRefreshToken;
+    #resolve;
+    /** Creates a grant from the shared {@linkcode GrantOptions}. */
+    constructor(options) {
+        this.allowRefreshToken = options.allowRefreshToken ?? false;
+        this.Scope = options.Scope ??
+            BasicScope;
+        this.#resolve = options.resolve;
+    }
+    /** The services this grant needs for `request`, from its `resolve` option. */
+    resolveServices(request) {
+        return Promise.resolve(this.#resolve(request));
+    }
+    /** Parses a scope string into a Scope object. */
+    parseScope(scopeText) {
+        return scopeText ? new this.Scope(scopeText) : undefined;
+    }
+    /**
+     * Validates and returns the accepted scope for the client and user, per the
+     * `TokenServiceInterface.acceptedScope` contract: a returned scope replaces
+     * the requested one (narrowing), `null`/`undefined` accepts the requested
+     * scope as-is, and `false` rejects.
+     *
+     * `user` is `undefined` when the client is acting as its own resource owner
+     * (client credentials, RFC 6749 §4.4), so the token service decides scope
+     * from the client alone.
+     *
+     * Throws InvalidScopeError if the scope is rejected.
+     */
+    async acceptedScope(client, user, scope, tokenService) {
+        const acceptedScope = await tokenService.acceptedScope(client, user, scope);
+        if (acceptedScope === false) {
+            throw new InvalidScopeError(scope ? "invalid scope" : "scope required");
+        }
+        return acceptedScope ?? scope;
+    }
+    /**
+     * Extracts client credentials from a request: HTTP Basic first, then the
+     * `client_id`/`client_secret` of the already-parsed `body`. Override to add
+     * grant-specific credential rules (as the authorization-code grant does for
+     * PKCE).
+     *
+     * @throws {InvalidClientError} If the request presents no usable credentials.
+     */
+    getClientCredentials(request, body) {
+        return extractClientCredentials(request, body);
+    }
+    /**
+     * Clamps a token's expiries to the absolute expiry of its rotation family,
+     * so nothing derived from a family outlives it — an access token issued a
+     * moment before the ceiling included. Mutates `token`; a token with no
+     * expiry of its own takes the family's.
+     */
+    capAtFamilyExpiry(token, familyExpiresAt) {
+        if (!token.accessTokenExpiresAt ||
+            familyExpiresAt < token.accessTokenExpiresAt) {
+            token.accessTokenExpiresAt = familyExpiresAt;
+        }
+        if ("refreshToken" in token) {
+            const refreshToken = token;
+            if (!refreshToken.refreshTokenExpiresAt ||
+                familyExpiresAt < refreshToken.refreshTokenExpiresAt) {
+                refreshToken.refreshTokenExpiresAt = familyExpiresAt;
+            }
+        }
+    }
+    /**
+     * Generates a token for a client and user from a resolved `tokenService`.
+     * Includes a refresh token if allowed, which starts a new rotation family:
+     * `familyId` plus the `familyCreatedAt` anchor the refresh grant caps
+     * rotations against. When the token service caps families
+     * ({@linkcode TokenServiceInterface.refreshTokenFamilyExpiresAt}), both
+     * expiries are clamped to the new family's ceiling.
+     *
+     * Pass `user: undefined` for a token the client holds as its own resource
+     * owner (client credentials, RFC 6749 §4.4). Such a token is never issued a
+     * refresh token whatever `allowRefreshToken` says — there is no resource
+     * 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.
+     */
+    async generateToken(client, user, scope, tokenService, authenticationContext) {
+        const event = user === undefined
+            ? undefined
+            : snapshotAuthenticationContext(authenticationContext);
+        const token = {
+            accessToken: await tokenService.generateAccessToken(client, user, scope, event),
+            client,
+        };
+        if (event)
+            token.authenticationContext = event;
+        if (user !== undefined)
+            token.user = user;
+        if (scope)
+            token.scope = scope;
+        const accessTokenExpiresAt = await tokenService.accessTokenExpiresAt(client, user, scope);
+        if (accessTokenExpiresAt)
+            token.accessTokenExpiresAt = accessTokenExpiresAt;
+        if (this.allowRefreshToken && user !== undefined) {
+            const refreshToken = await tokenService.generateRefreshToken(client, user, scope);
+            if (refreshToken) {
+                const familyCreatedAt = new Date();
+                const result = {
+                    ...token,
+                    refreshToken,
+                    familyId: crypto.randomUUID(),
+                    familyCreatedAt,
+                };
+                const refreshTokenExpiresAt = await tokenService.refreshTokenExpiresAt(client, user, scope);
+                if (refreshTokenExpiresAt) {
+                    result.refreshTokenExpiresAt = refreshTokenExpiresAt;
+                }
+                const familyExpiresAt = await tokenService
+                    .refreshTokenFamilyExpiresAt?.(client, user, familyCreatedAt, scope);
+                if (familyExpiresAt)
+                    this.capAtFamilyExpiry(result, familyExpiresAt);
+                return result;
+            }
+        }
+        return token;
+    }
+    /**
+     * 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.
+     *
+     * @throws {InvalidClientError} If authentication fails.
+     */
+    async getAuthenticatedClient(request, body) {
+        const { clientService } = await this.resolveServices(request);
+        return await authenticateClientCredentials(this.getClientCredentials(request, body), clientService);
+    }
+}