@udibo/oauth2 0.1.0

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

@@ -0,0 +1,80 @@
+/**
+ * Resource Owner Password Credentials grant type implementation.
+ * RFC 6749 Section 4.3.
+ *
+ * @deprecated The password grant is **NOT RECOMMENDED** for use and is
+ * removed in OAuth 2.1. It exposes user credentials directly to clients
+ * and cannot support modern security features like MFA.
+ *
+ * Consider using the authorization code grant with PKCE instead.
+ *
+ * This grant performs **no second-factor check**: a token request is
+ * non-interactive, so there is nowhere to challenge the user. Wiring it means
+ * enforcing your own MFA policy inside `getAuthenticated`, or accepting that a
+ * password alone mints tokens for every user — including ones enrolled in MFA.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.3
+ * @see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-2.4
+ * @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 { UserServiceInterface } from "../services/user.js";
+import { AbstractGrant, type GrantOptions, type GrantServices } from "./grant.js";
+/** Services required by the password grant. */
+export interface PasswordGrantServices<Client extends ClientInterface, User, S extends AbstractScope> extends GrantServices<Client, User, S> {
+    /** Authenticates the resource owner by username and password. */
+    userService: UserServiceInterface<User>;
+}
+/** 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. */
+    allowRefreshToken?: boolean;
+}
+/**
+ * The resource owner password credentials grant type.
+ *
+ * Allows exchanging a user's username and password directly for tokens.
+ * This grant type should only be used when there is a high degree of trust
+ * between the resource owner and the client.
+ *
+ * @deprecated This grant is **NOT RECOMMENDED** and is removed in OAuth 2.1.
+ * Use the authorization code grant with PKCE instead. Only use this for:
+ * - Legacy system migration
+ * - First-party trusted applications where no alternative exists
+ *
+ * Security concerns:
+ * - Exposes user credentials directly to the client application
+ * - Cannot support MFA or other modern authentication flows
+ * - No user consent UI for scope approval
+ *
+ * **MFA is not enforced here and cannot be.** The grant treats a truthy
+ * {@linkcode UserServiceInterface.getAuthenticated} result as sufficient to
+ * issue tokens; it never asks whether the user has a second factor, and a
+ * token request has no interactive step in which to challenge one. If any of
+ * your users can enroll in MFA, either reject them from `getAuthenticated`
+ * (fail closed) or accept that their password alone yields full tokens.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.3
+ * @see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-2.4
+ */
+export declare class PasswordGrant<Client extends ClientInterface, User, S extends AbstractScope = BasicScope> extends AbstractGrant<Client, User, S, PasswordGrantServices<Client, User, S>> {
+    /** The OAuth2 grant type: `password`. */
+    readonly grantType = "password";
+    /** Creates the grant from its {@linkcode PasswordGrantOptions}. */
+    constructor(options: PasswordGrantOptions<Client, User, S>);
+    /**
+     * Handles a token request for the password grant.
+     * Validates the username/password and issues tokens.
+     *
+     * The password is the only factor checked. Any second-factor policy must be
+     * applied by {@linkcode UserServiceInterface.getAuthenticated}, whose errors
+     * propagate to the token response unchanged.
+     *
+     * @throws {InvalidRequestError} If `username` or `password` is missing.
+     * @throws {InvalidGrantError} If user authentication fails.
+     * @throws {InvalidScopeError} If the requested scope is rejected.
+     */
+    token(request: Request, client: Client, body: FormData): Promise<Token<Client, User, S>>;
+}

package/esm/server/grants/password.js

@@ -0,0 +1,92 @@
+/**
+ * Resource Owner Password Credentials grant type implementation.
+ * RFC 6749 Section 4.3.
+ *
+ * @deprecated The password grant is **NOT RECOMMENDED** for use and is
+ * removed in OAuth 2.1. It exposes user credentials directly to clients
+ * and cannot support modern security features like MFA.
+ *
+ * Consider using the authorization code grant with PKCE instead.
+ *
+ * This grant performs **no second-factor check**: a token request is
+ * non-interactive, so there is nowhere to challenge the user. Wiring it means
+ * enforcing your own MFA policy inside `getAuthenticated`, or accepting that a
+ * password alone mints tokens for every user — including ones enrolled in MFA.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.3
+ * @see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-2.4
+ * @module
+ */
+import { InvalidGrantError, InvalidRequestError } from "../../errors.js";
+import { AbstractGrant, } from "./grant.js";
+/**
+ * The resource owner password credentials grant type.
+ *
+ * Allows exchanging a user's username and password directly for tokens.
+ * This grant type should only be used when there is a high degree of trust
+ * between the resource owner and the client.
+ *
+ * @deprecated This grant is **NOT RECOMMENDED** and is removed in OAuth 2.1.
+ * Use the authorization code grant with PKCE instead. Only use this for:
+ * - Legacy system migration
+ * - First-party trusted applications where no alternative exists
+ *
+ * Security concerns:
+ * - Exposes user credentials directly to the client application
+ * - Cannot support MFA or other modern authentication flows
+ * - No user consent UI for scope approval
+ *
+ * **MFA is not enforced here and cannot be.** The grant treats a truthy
+ * {@linkcode UserServiceInterface.getAuthenticated} result as sufficient to
+ * issue tokens; it never asks whether the user has a second factor, and a
+ * token request has no interactive step in which to challenge one. If any of
+ * your users can enroll in MFA, either reject them from `getAuthenticated`
+ * (fail closed) or accept that their password alone yields full tokens.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.3
+ * @see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-2.4
+ */
+export class PasswordGrant extends AbstractGrant {
+    /** The OAuth2 grant type: `password`. */
+    grantType = "password";
+    /** Creates the grant from its {@linkcode PasswordGrantOptions}. */
+    constructor(options) {
+        super({
+            ...options,
+            allowRefreshToken: options.allowRefreshToken ?? true,
+        });
+    }
+    /**
+     * Handles a token request for the password grant.
+     * Validates the username/password and issues tokens.
+     *
+     * The password is the only factor checked. Any second-factor policy must be
+     * applied by {@linkcode UserServiceInterface.getAuthenticated}, whose errors
+     * propagate to the token response unchanged.
+     *
+     * @throws {InvalidRequestError} If `username` or `password` is missing.
+     * @throws {InvalidGrantError} If user authentication fails.
+     * @throws {InvalidScopeError} If the requested scope is rejected.
+     */
+    async token(request, client, body) {
+        const { tokenService, userService } = await this.resolveServices(request);
+        const scopeText = body.get("scope");
+        let scope = this.parseScope(typeof scopeText === "string" ? scopeText : undefined);
+        const username = body.get("username");
+        if (!username || typeof username !== "string") {
+            throw new InvalidRequestError("username parameter required");
+        }
+        const password = body.get("password");
+        if (!password || typeof password !== "string") {
+            throw new InvalidRequestError("password parameter required");
+        }
+        const user = await userService.getAuthenticated(username, password);
+        if (!user) {
+            throw new InvalidGrantError("user authentication failed");
+        }
+        const acceptedScope = await this.acceptedScope(client, user, scope, tokenService);
+        scope = acceptedScope ?? undefined;
+        const token = await this.generateToken(client, user, scope, tokenService);
+        return await tokenService.save(token);
+    }
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Refresh Token grant type implementation.
+ * RFC 6749 Section 6.
+ * @module
+ */
+import type { ClientInterface } from "../../models/client.js";
+import type { RefreshToken } from "../../models/token.js";
+import type { AbstractScope, BasicScope } from "../../models/scope.js";
+import { AbstractGrant, type GrantOptions, type GrantServices } from "./grant.js";
+/** Services required by the refresh token grant. */
+export type RefreshTokenGrantServices<Client extends ClientInterface, User, S extends AbstractScope> = GrantServices<Client, User, S>;
+/**
+ * What the refresh grant observed when a rotated-out refresh token was
+ * replayed. Passed to {@link RefreshTokenGrantOptions.onTokenReuse}.
+ */
+export interface TokenReuseEvent<Client extends ClientInterface, User> {
+    /** The rotation family the replayed token belonged to. */
+    familyId: string;
+    /** The client the replayed token was issued to. */
+    client: Client;
+    /** The user the replayed token was issued for, if any. */
+    user?: User;
+    /** Whether {@linkcode TokenServiceInterface.revokeFamily} revoked anything. */
+    familyRevoked: boolean;
+}
+/**
+ * Options for configuring the refresh token grant. The grant always issues a
+ * refresh token, so `allowRefreshToken` is not offered.
+ */
+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.
+     *
+     * Trigger point `token-reuse` (see `docs/trigger-points.md`).
+     * Fire-and-forget: it is awaited, but a throw is caught and logged, never
+     * rethrown, so a failing security-logging hook cannot change the
+     * client-facing `invalid_grant` a replayed token always yields.
+     */
+    onTokenReuse?: (event: TokenReuseEvent<Client, User>) => void | Promise<void>;
+}
+/**
+ * The refresh token grant type.
+ * https://datatracker.ietf.org/doc/html/rfc6749.html#section-6
+ *
+ * Allows clients to obtain a new access token using a refresh token
+ * without requiring the user to re-authenticate.
+ */
+export declare class RefreshTokenGrant<Client extends ClientInterface, User, S extends AbstractScope = BasicScope> extends AbstractGrant<Client, User, S, RefreshTokenGrantServices<Client, User, S>> {
+    #private;
+    /** The OAuth2 grant type: `refresh_token`. */
+    readonly grantType = "refresh_token";
+    /** Creates the grant from its {@linkcode RefreshTokenGrantOptions}. */
+    constructor(options: RefreshTokenGrantOptions<Client, User, S>);
+    /**
+     * Handles a token request for the refresh token grant. Issues a new access
+     * token (and rotates the refresh token when the token service supports it)
+     * from a valid, unexpired refresh token.
+     *
+     * Rotation revokes the exchanged token through the token service's
+     * `revokeRotated` when implemented, falling back to `revoke` — so a service
+     * whose `revoke` ends the owning session can keep this bookkeeping step
+     * from signing the person out.
+     *
+     * Rotation renews the refresh token's sliding lifetime, bounded by the
+     * family's absolute cap when the token service implements
+     * {@linkcode TokenServiceInterface.refreshTokenFamilyExpiresAt} and the
+     * record carries a {@linkcode RefreshToken.familyCreatedAt} anchor: both the
+     * access and refresh expiries are clamped to the family's ceiling, and once
+     * the cap has passed the exchange fails, so the client must obtain a fresh
+     * 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 {InvalidClientError} If the token was issued to another client.
+     * @throws {InvalidScopeError} If the requested scope exceeds the original grant.
+     */
+    token(request: Request, client: Client, body: FormData): Promise<RefreshToken<Client, User, S>>;
+}

package/esm/server/grants/refresh-token.js

@@ -0,0 +1,136 @@
+/**
+ * Refresh Token grant type implementation.
+ * RFC 6749 Section 6.
+ * @module
+ */
+import { InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, } from "../../errors.js";
+import { AbstractGrant, } from "./grant.js";
+/**
+ * The refresh token grant type.
+ * https://datatracker.ietf.org/doc/html/rfc6749.html#section-6
+ *
+ * Allows clients to obtain a new access token using a refresh token
+ * without requiring the user to re-authenticate.
+ */
+export class RefreshTokenGrant extends AbstractGrant {
+    /** The OAuth2 grant type: `refresh_token`. */
+    grantType = "refresh_token";
+    #onTokenReuse;
+    /** Creates the grant from its {@linkcode RefreshTokenGrantOptions}. */
+    constructor(options) {
+        super({ ...options, allowRefreshToken: true });
+        this.#onTokenReuse = options.onTokenReuse;
+    }
+    /**
+     * Handles a token request for the refresh token grant. Issues a new access
+     * token (and rotates the refresh token when the token service supports it)
+     * from a valid, unexpired refresh token.
+     *
+     * Rotation revokes the exchanged token through the token service's
+     * `revokeRotated` when implemented, falling back to `revoke` — so a service
+     * whose `revoke` ends the owning session can keep this bookkeeping step
+     * from signing the person out.
+     *
+     * Rotation renews the refresh token's sliding lifetime, bounded by the
+     * family's absolute cap when the token service implements
+     * {@linkcode TokenServiceInterface.refreshTokenFamilyExpiresAt} and the
+     * record carries a {@linkcode RefreshToken.familyCreatedAt} anchor: both the
+     * access and refresh expiries are clamped to the family's ceiling, and once
+     * the cap has passed the exchange fails, so the client must obtain a fresh
+     * 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 {InvalidClientError} If the token was issued to another client.
+     * @throws {InvalidScopeError} If the requested scope exceeds the original grant.
+     */
+    async token(request, client, body) {
+        const { tokenService } = await this.resolveServices(request);
+        const refreshTokenStr = body.get("refresh_token");
+        if (typeof refreshTokenStr !== "string") {
+            throw new InvalidRequestError("refresh_token parameter required");
+        }
+        const currentToken = await tokenService.getRefreshToken(refreshTokenStr);
+        if (!currentToken) {
+            // Reuse detection: an unknown-but-previously-rotated token means the
+            // old member of a rotation family was replayed (stolen or raced) —
+            // revoke the entire family so neither party keeps a live session.
+            if (tokenService.getRevokedRefreshToken && tokenService.revokeFamily) {
+                const replayed = await tokenService.getRevokedRefreshToken(refreshTokenStr);
+                if (replayed?.familyId &&
+                    replayed.client.id.toString() === client.id.toString()) {
+                    const familyRevoked = await tokenService.revokeFamily(replayed.familyId);
+                    await this.#notifyTokenReuse({
+                        familyId: replayed.familyId,
+                        client: replayed.client,
+                        user: replayed.user,
+                        familyRevoked,
+                    });
+                }
+            }
+            throw new InvalidGrantError("invalid refresh_token");
+        }
+        if (currentToken.refreshTokenExpiresAt &&
+            currentToken.refreshTokenExpiresAt < new Date()) {
+            throw new InvalidGrantError("invalid refresh_token");
+        }
+        const { client: tokenClient, user, scope } = currentToken;
+        if (client.id.toString() !== tokenClient.id.toString()) {
+            throw new InvalidClientError("refresh_token was issued to another client");
+        }
+        // RFC 6749 §6: a requested scope may only narrow, never exceed, the original grant.
+        let nextScope = scope;
+        const requestedScopeText = body.get("scope");
+        if (typeof requestedScopeText === "string") {
+            const requestedScope = this.parseScope(requestedScopeText);
+            if (requestedScope) {
+                if (!scope || !scope.has(requestedScope)) {
+                    throw new InvalidScopeError("requested scope exceeds the scope of the original grant");
+                }
+                nextScope = requestedScope;
+            }
+        }
+        const familyExpiresAt = currentToken.familyCreatedAt &&
+            tokenService.refreshTokenFamilyExpiresAt
+            ? await tokenService.refreshTokenFamilyExpiresAt(client, user, currentToken.familyCreatedAt, nextScope)
+            : undefined;
+        if (familyExpiresAt && familyExpiresAt.getTime() <= Date.now()) {
+            throw new InvalidGrantError("refresh_token family expired");
+        }
+        const nextToken = await this.generateToken(client, user, nextScope, tokenService, currentToken.authenticationContext);
+        const nextRefreshToken = "refreshToken" in nextToken
+            ? nextToken
+            : {
+                ...nextToken,
+                refreshToken: currentToken.refreshToken,
+                refreshTokenExpiresAt: currentToken.refreshTokenExpiresAt,
+            };
+        // A rotation stays in its ancestor's family so replaying any rotated-out
+        // member revokes the whole chain.
+        nextRefreshToken.familyId = currentToken.familyId ??
+            nextRefreshToken.familyId;
+        nextRefreshToken.familyCreatedAt = currentToken.familyCreatedAt ??
+            nextRefreshToken.familyCreatedAt;
+        if (familyExpiresAt) {
+            this.capAtFamilyExpiry(nextRefreshToken, familyExpiresAt);
+        }
+        const claimed = tokenService.revokeRotated
+            ? await tokenService.revokeRotated(currentToken)
+            : await tokenService.revoke(currentToken);
+        if (!claimed) {
+            throw new InvalidGrantError("refresh_token was already consumed");
+        }
+        return await tokenService.save(nextRefreshToken);
+    }
+    async #notifyTokenReuse(event) {
+        if (!this.#onTokenReuse)
+            return;
+        try {
+            await this.#onTokenReuse(event);
+        }
+        catch (error) {
+            console.error("[@udibo/oauth2] onTokenReuse hook failed:", error instanceof Error ? error.message : error);
+        }
+    }
+}

package/esm/server/introspection-token-reader.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Token reader that validates tokens via an OAuth2 introspection endpoint.
+ *
+ * This is the standard way for resource servers to validate tokens when
+ * they are separate from the authorization server. The reader calls the
+ * authorization server's introspection endpoint (RFC 7662) to check
+ * whether a token is active and retrieve its metadata.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7662
+ * @module
+ */
+import type { ClientInterface } from "../models/client.js";
+import type { AbstractScope, ScopeConstructor } from "../models/scope.js";
+import { BasicScope } from "../models/scope.js";
+import type { IntrospectionResponse, Token } from "../models/token.js";
+import type { TokenReaderInterface } from "./services/token.js";
+/**
+ * Options for configuring the introspection token reader.
+ *
+ * The {@linkcode getClient} and {@linkcode getUser} mappers project the
+ * introspection response into the resource server's `Client` / `User`
+ * types — RFC 7662 only fixes a minimal set of fields, and most
+ * authorization servers carry app-specific claims as extension fields.
+ */
+export interface IntrospectionTokenReaderOptions<Client extends ClientInterface, User, S extends AbstractScope = BasicScope> {
+    /** URL of the authorization server's introspection endpoint. */
+    introspectionEndpoint: string;
+    /** Client ID used to authenticate introspection requests. */
+    clientId: string;
+    /** Client secret used to authenticate introspection requests. */
+    clientSecret: string;
+    /** Optional scope constructor for parsing scope strings. Defaults to BasicScope. */
+    Scope?: ScopeConstructor<S>;
+    /**
+     * Projects an active introspection response into a typed `Client`.
+     * Required because the client shape is app-specific: RFC 7662 only
+     * guarantees `client_id` may be present, and authorization servers may
+     * include extension fields.
+     *
+     * May be async — return a promise to enrich from a DB lookup or a
+     * downstream API call (e.g. fetching a client record by `client_id`).
+     */
+    getClient: (data: IntrospectionResponse) => Client | Promise<Client>;
+    /**
+     * Projects an active introspection response into a typed `User`. Return
+     * `undefined` when the token doesn't represent a user. Omit entirely if
+     * your app never reads user info off the token.
+     *
+     * A machine token (client credentials) carries no `sub`, so `data.sub` is
+     * present only when there is a resource owner — `data.sub ? {…} : undefined`
+     * is the whole discriminator, and a client-credentials caller resolves to no
+     * user.
+     *
+     * May be async — return a promise to enrich from a DB lookup or the
+     * authorization server's OIDC UserInfo endpoint, using `data.sub` as
+     * the lookup key.
+     */
+    getUser?: (data: IntrospectionResponse) => User | undefined | Promise<User | undefined>;
+    /**
+     * Deadline in milliseconds for an introspection request. Defaults to 5000.
+     * Without it an authorization server that accepts the connection and then
+     * stops answering hangs every request this resource server is serving, since
+     * introspection sits on the hot path of each one. Ignored by an injected
+     * {@linkcode fetch} that doesn't honour `AbortSignal`.
+     */
+    fetchTimeoutMs?: number;
+    /**
+     * `fetch` implementation used to call the introspection endpoint. Defaults
+     * to the global `fetch`. Inject it to route through a custom client (mTLS,
+     * timeouts, retries) or to stub the network in tests.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Validates tokens by calling an OAuth2 introspection endpoint (RFC 7662).
+ *
+ * Use this with {@linkcode ResourceServer} when your resource server is
+ * separate from the authorization server. The reader authenticates with
+ * the introspection endpoint using client credentials (HTTP Basic Auth)
+ * and projects the response into the resource server's `Client` / `User`
+ * types via the {@linkcode IntrospectionTokenReaderOptions.getClient} and
+ * {@linkcode IntrospectionTokenReaderOptions.getUser} mappers.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   IntrospectionTokenReader,
+ *   ResourceServer,
+ * } from "@udibo/oauth2/server/resource";
+ *
+ * interface MyClient { id: string }
+ * interface MyUser { id: string; email?: string }
+ *
+ * const tokenReader = new IntrospectionTokenReader<MyClient, MyUser>({
+ *   introspectionEndpoint: "https://auth.example.com/introspect",
+ *   clientId: "my-api",
+ *   clientSecret: "my-secret",
+ *   getClient: (data) => ({ id: data.client_id! }),
+ *   getUser: (data) =>
+ *     data.sub
+ *       ? { id: data.sub, email: data.email as string | undefined }
+ *       : undefined,
+ * });
+ *
+ * const resourceServer = new ResourceServer<MyClient, MyUser>({
+ *   resolve: () => ({ services: { tokenService: tokenReader } }),
+ * });
+ * ```
+ */
+export declare class IntrospectionTokenReader<Client extends ClientInterface, User, S extends AbstractScope = BasicScope> implements TokenReaderInterface<Client, User, S> {
+    #private;
+    private introspectionEndpoint;
+    private clientId;
+    private clientSecret;
+    private Scope;
+    private getClient;
+    private getUser?;
+    private fetchTimeoutMs;
+    private customFetch?;
+    /**
+     * `Scope` defaults to {@linkcode BasicScope}, `fetchTimeoutMs` to 5000, and
+     * `fetch` to the global `fetch` when omitted from `options`.
+     */
+    constructor(options: IntrospectionTokenReaderOptions<Client, User, S>);
+    /**
+     * Validates an access token by calling the introspection endpoint.
+     *
+     * Sends a POST request with the token to the configured introspection
+     * endpoint, authenticated with client credentials via HTTP Basic Auth.
+     *
+     * @returns The token with client/user/scope info, or `undefined` when the
+     *   endpoint reports the token inactive (RFC 7662 `{ active: false }`) or
+     *   does not identify it as a bearer access token.
+     * @throws {TemporarilyUnavailableError} If the introspection endpoint is
+     *   unreachable, takes longer than
+     *   {@linkcode IntrospectionTokenReaderOptions.fetchTimeoutMs} to answer, or
+     *   returns a 5xx — a down authorization server must be distinguishable from
+     *   a genuinely invalid token (which is `undefined` → `invalid_token`), not
+     *   collapsed into it.
+     * @throws {ServerError} If the endpoint returns a 4xx (e.g. the reader's own
+     *   introspection credentials are rejected) — a misconfiguration, not a
+     *   verdict on the caller's token.
+     *
+     * An active response is only accepted when its `token_type` names a bearer
+     * token. RFC 7662 answers for refresh tokens too, and a refresh token's
+     * response is otherwise indistinguishable from an access token's — without
+     * this check a refresh token presented as `Authorization: Bearer …` would
+     * authenticate at the resource server, bypassing rotation and reuse
+     * detection. An authorization server that omits `token_type` from an active
+     * response cannot be read by this reader.
+     */
+    getToken(accessToken: string): Promise<Token<Client, User, S> | undefined>;
+}