@udibo/oauth2 0.1.0

package/esm/client/direct-client.d.ts

@@ -0,0 +1,707 @@
+/**
+ * OAuth2 client that talks to the authorization server directly and holds the
+ * resulting tokens (RFC 6749 + RFC 7636 PKCE + RFC 7009 revocation +
+ * RFC 7662 introspection + RFC 8414 metadata + RFC 8628 device authorization).
+ *
+ * Works against any RFC-compliant authorization server. Use it for SPAs
+ * without a Backend-for-Frontend, CLIs, mobile shells, and server-side apps —
+ * anywhere this process is the one that keeps the access and refresh tokens.
+ * When a BFF holds them instead, use `BffClient`.
+ *
+ * @module
+ */
+import type { AuthorizationServerMetadata, DeviceAuthorizationResponse } from "../models/responses.js";
+import type { IntrospectionResponse, TokenResponse } from "../models/token.js";
+import { type BaseLoginOptions, type BaseOptions, type LogoutOptions, type LogoutRedirect, OAuth2ClientBase, type SessionState, type UserInfoClaims } from "./base.js";
+import { type DiscoveryCache } from "./discovery-cache.js";
+import { type AuthRequestStorage, type RefreshTokenStorage, type TokenBundle, type TokenStorage } from "./storage.js";
+/** Endpoints resolved via discovery or provided explicitly by the caller. */
+export interface AuthorizationServerEndpoints {
+    /** URL of the authorization endpoint (required for the auth-code flow). */
+    authorization?: string;
+    /**
+     * URL of the token endpoint. Required by every grant; methods that need it
+     * throw a clear error if it is missing both here and from the server's
+     * discovery metadata.
+     */
+    token?: string;
+    /** URL of the revocation endpoint (RFC 7009). */
+    revocation?: string;
+    /** URL of the introspection endpoint (RFC 7662). */
+    introspection?: string;
+    /** URL of the device authorization endpoint (RFC 8628). */
+    deviceAuthorization?: string;
+    /** URL of the OIDC userinfo endpoint. */
+    userInfo?: string;
+    /** URL of the OIDC end-session endpoint (for logout redirect). */
+    endSession?: string;
+}
+/** Options accepted by {@link DirectClient}. */
+export interface DirectClientOptions extends BaseOptions {
+    /** OAuth2 client identifier. */
+    clientId: string;
+    /**
+     * The client secret, sent via HTTP Basic auth on token-endpoint calls.
+     *
+     * Supplying one makes this a **confidential** client, which unlocks
+     * {@link DirectClient.getClientCredentialsToken} and
+     * {@link DirectClient.introspect}. **Omit the property** for a **public**
+     * client (a browser or a native app, where a secret cannot be kept) — those
+     * require refresh-token rotation with reuse detection on the server side.
+     *
+     * `clientSecret: undefined` reads as omitted, so a wrapper can forward an
+     * optional secret. An **empty string** is a construction error rather than a
+     * request for a public client — nobody spells "public" `""`, so it is a
+     * variable that resolved to blank. Note that `clientSecret: getEnv("X")`
+     * with `X` unset therefore yields a *public* client; require it at the
+     * source if the deployment must be confidential.
+     */
+    clientSecret?: string;
+    /** Registered redirect URI; required for the auth-code flow. */
+    redirectUri?: string;
+    /** Default scope string to request when none is passed explicitly. */
+    scope?: string;
+    /**
+     * Issuer URL. If provided, endpoints are fetched from
+     * `${issuer}/.well-known/oauth-authorization-server` on first use.
+     * Mutually exclusive with an explicit `endpoints` record below.
+     */
+    issuer?: string;
+    /** Explicit endpoint URLs, bypassing discovery. */
+    endpoints?: AuthorizationServerEndpoints;
+    /**
+     * Cache the discovery result is read from and written to, shared with any
+     * other client given the same instance. Without one, metadata is cached on
+     * this client only — a server that builds a client per request then
+     * re-fetches discovery on every request. `MemoryDiscoveryCache` is the
+     * ready-made implementation.
+     */
+    discoveryCache?: DiscoveryCache;
+    /** Access-token storage. Defaults to {@link MemoryTokenStorage}. */
+    tokenStorage?: TokenStorage;
+    /** Refresh-token storage. Defaults to {@link MemoryRefreshTokenStorage}. */
+    refreshTokenStorage?: RefreshTokenStorage;
+    /**
+     * Auth-request storage.
+     *
+     * Defaults to {@link SessionStorageAuthRequestStorage} in a browser document
+     * and {@link MemoryAuthRequestStorage} everywhere else. The browser default
+     * is what makes the authorize redirect work at all: an in-memory record does
+     * not survive the navigation away and back, so the callback rejects every
+     * `state` as unknown. Servers keep the in-memory default so a per-request
+     * client does not write pending logins into one process-wide store.
+     *
+     * Override it when the record must live somewhere else — a per-request
+     * cookie store on a server, or a store scoped to something other than the
+     * tab.
+     */
+    authRequestStorage?: AuthRequestStorage;
+    /**
+     * Max age of a pending auth-request (`state`) record before
+     * {@link DirectClient.exchangeAuthorizationCode} rejects it as stale, in ms.
+     * Bounds the callback replay window and unbounded growth of the in-memory
+     * store. Defaults to 10 minutes; set `Infinity` to disable the check.
+     */
+    authRequestTtlMs?: number;
+}
+/** Options accepted by {@link DirectClient.login}. */
+export interface LoginOptions extends BaseLoginOptions {
+    /** Override the default scope string. */
+    scope?: string;
+    /** OIDC `prompt` parameter. */
+    prompt?: string;
+    /** Extra query parameters to append to the authorize URL. */
+    extraParams?: Record<string, string>;
+    /**
+     * Override the origin (scheme + host) of the authorize endpoint and the
+     * `redirect_uri` for THIS call, keeping their configured paths. Lets one
+     * build-once client serve multiple deployment origins (preview URLs,
+     * multi-tenant subdomains) — e.g. the Hono BFF passes the trusted request
+     * origin so sign-in works on whichever host the request arrived at. The
+     * callback returns to the same origin, so the matching `exchange` call is
+     * given the same origin.
+     */
+    origin?: string;
+    /**
+     * Store the pending authorization request here instead of in the client's
+     * configured `authRequestStorage`, for THIS call. Lets a server bind the
+     * record to the request it belongs to — a per-request cookie store, or a
+     * per-tenant table — rather than sharing one process-wide store. The
+     * matching `exchangeAuthorizationCode` call MUST be given a storage that
+     * can read the record back.
+     */
+    authRequestStorage?: AuthRequestStorage;
+    /**
+     * Override the `redirect_uri` for THIS call (used verbatim, not retargeted
+     * by `origin`). Lets a Backend-for-Frontend derive `redirect_uri` from its
+     * mounted callback path instead of restating it in the client config. The
+     * matching `exchangeAuthorizationCode` call MUST be given the same value
+     * (RFC 6749 §4.1.3 — the token-exchange `redirect_uri` must match
+     * authorize).
+     */
+    redirectUri?: string;
+}
+/** Result of {@link DirectClient.login}. */
+export interface AuthorizationRedirect {
+    /** Fully-built authorize URL for the caller to navigate to. */
+    url: string;
+    /** Opaque `state` value the callback will echo back. */
+    state: string;
+}
+/** Result of {@link DirectClient.handleAuthorizationCallback}. */
+export interface AuthorizationCallbackResult {
+    /** Token bundle saved on the client. */
+    tokens: TokenBundle;
+    /** `returnTo` that was recorded when `login` ran. */
+    returnTo?: string;
+}
+/** Options accepted by {@link DirectClient.startDeviceAuthorization}. */
+export interface DeviceAuthorizationOptions {
+    /** Override the default scope string requested for the device grant. */
+    scope?: string;
+}
+/** Options accepted by {@link DirectClient.pollDeviceToken}. */
+export interface PollDeviceTokenOptions {
+    /** Minimum seconds between polls. Defaults to the RFC 8628 fallback of 5. */
+    interval?: number;
+    /** Unix ms at which polling should give up. */
+    expiresAt?: number;
+    /** Abort signal to cancel polling. */
+    signal?: AbortSignal;
+}
+/** Generic token introspection response. */
+export type IntrospectionResult = IntrospectionResponse;
+/** Options accepted by the low-level exchange primitives. */
+export interface ExchangeOptions {
+    /** Retarget the configured `redirect_uri` at this origin. */
+    origin?: string;
+    /** Use this `redirect_uri` verbatim. */
+    redirectUri?: string;
+    /** Read the pending auth-request record from here. */
+    authRequestStorage?: AuthRequestStorage;
+}
+/** Result of the low-level exchange primitives. */
+export interface ExchangeResult {
+    /** The token bundle, not persisted to this client's storage. */
+    tokens: TokenBundle;
+    /** The rotated refresh token, when the server issued one. */
+    refreshToken?: string;
+    /** `returnTo` recorded at authorize time, for the code exchange. */
+    returnTo?: string;
+    /** The raw token-endpoint response. */
+    raw: TokenResponse;
+}
+/**
+ * OAuth2 client that drives the standard grants against an authorization
+ * server and keeps the tokens in its own storage.
+ *
+ * Public vs confidential is decided by whether `clientSecret` was supplied:
+ * with a secret the client authenticates via HTTP Basic (RFC 6749 §2.3.1) and
+ * may use `client_credentials` and introspection; without one it sends
+ * `client_id` in the body and is limited to the grants a public client may
+ * run.
+ *
+ * **Advanced — multi-session servers.**
+ * {@link exchangeAuthorizationCode} and {@link exchangeRefreshToken} are
+ * lower-level variants that bypass this client's token storage and event bus.
+ * They exist so server-side adapters (e.g. the Hono BFF) can drive many
+ * concurrent sessions through a single shared client without their tokens
+ * clobbering each other. SPA / mobile / CLI consumers should never reach for
+ * them — call {@link handleAuthorizationCallback} and {@link refresh}
+ * instead.
+ *
+ * @example SPA with PKCE against a discovered issuer
+ * ```ts
+ * import {
+ *   DirectClient,
+ *   IndexedDBRefreshTokenStorage,
+ * } from "@udibo/oauth2/client";
+ *
+ * const client = new DirectClient({
+ *   clientId: "spa",
+ *   issuer: "https://auth.example.com",
+ *   redirectUri: "https://app.example.com/callback",
+ *   scope: "openid profile",
+ *   refreshTokenStorage: new IndexedDBRefreshTokenStorage({ clientId: "spa" }),
+ * });
+ *
+ * const { url } = await client.login({ returnTo: "/dashboard" });
+ * location.assign(url);
+ * ```
+ *
+ * @example Confidential client issuing a machine token
+ * ```ts
+ * import { DirectClient } from "@udibo/oauth2/client";
+ *
+ * const client = new DirectClient({
+ *   clientId: "worker",
+ *   clientSecret: Deno.env.get("CLIENT_SECRET")!,
+ *   endpoints: { token: "https://auth.example.com/token" },
+ * });
+ *
+ * const tokens = await client.getClientCredentialsToken({ scope: "jobs:run" });
+ * ```
+ */
+export declare class DirectClient extends OAuth2ClientBase {
+    #private;
+    /**
+     * Builds a client for one OAuth2 client registration.
+     *
+     * @param options Must carry `clientId`, plus either `issuer` (endpoints come
+     * from discovery) or `endpoints` (discovery is skipped). Supply
+     * `clientSecret` for a confidential client; **omit the property entirely**
+     * for a public one.
+     * @throws {TypeError} when both `endpoints` and `issuer` are supplied (they
+     * are mutually exclusive), or when `clientSecret` is an empty string.
+     * @throws {Error} when a secret is supplied in a document context, where it
+     * would ship to every visitor in the bundle.
+     */
+    constructor(options: DirectClientOptions);
+    /** True when the client was given a secret and authenticates via Basic. */
+    get isConfidential(): boolean;
+    /**
+     * Fetches authorization-server metadata and caches it on the instance.
+     *
+     * Tries `.well-known/oauth-authorization-server` (RFC 8414) first, then
+     * falls back to `.well-known/openid-configuration` (OIDC Discovery) — the
+     * two use the same field names, and real IdPs serve one or the other, so
+     * this works against any compliant server. **Lazy + cached**: it only runs
+     * on the first endpoint use of an `issuer`-configured client (never at
+     * construction), so there is no startup cost and no per-request fetch.
+     * Concurrent calls share one in-flight request; a failure clears the cache
+     * so a later call can retry.
+     *
+     * **Re-resolution contract.** The document this client holds is never
+     * permanent: every endpoint use re-resolves once the copy in hand is past
+     * its expiry, so a long-lived client picks up a rotated `jwks_uri` or a
+     * moved endpoint without a restart. Without a `discoveryCache` the copy
+     * expires {@link DEFAULT_DISCOVERY_TTL_MS} after it was fetched. With one,
+     * the cache owns freshness: the copy expires when the cache says its entry
+     * does (the `expiresAt` it reports), so the client reads the cache once
+     * per entry lifetime rather than once per endpoint lookup — a Redis- or
+     * file-backed cache costs one round trip per TTL window, not one per call.
+     * Either way expiry only schedules the *next* resolve; nothing re-fetches on
+     * a timer, and a client that is idle past its expiry makes no requests.
+     *
+     * A server that builds a client per request should supply a
+     * `discoveryCache`, or it re-fetches discovery on every request.
+     *
+     * @returns The server's metadata document.
+     * @throws {Error} when the client was configured with explicit `endpoints`
+     * rather than an `issuer` — there is nothing to discover.
+     * @throws {ServerError} when both well-known paths fail.
+     *
+     * @example
+     * ```ts
+     * import { DirectClient } from "@udibo/oauth2/client";
+     *
+     * const client = new DirectClient({
+     *   clientId: "cli",
+     *   issuer: "https://auth.example.com",
+     * });
+     * const meta = await client.discover();
+     * ```
+     */
+    discover(): Promise<AuthorizationServerMetadata>;
+    /** Last-seen authorization server metadata, if discovery has run. */
+    get metadata(): AuthorizationServerMetadata | undefined;
+    /**
+     * The configured authorization endpoint URL, if known **synchronously** —
+     * set explicitly via `endpoints.authorization`, or learned from a previous
+     * {@link discover}. `undefined` for an issuer-only client that has not
+     * discovered yet.
+     *
+     * Exposed so a Backend-for-Frontend can recognize an in-flight authorize URL
+     * (e.g. to decide whether to *resume* it or *start* a fresh login) without
+     * re-running discovery. See `HonoBff.loginContinuation`.
+     */
+    get authorizationEndpoint(): string | undefined;
+    /**
+     * The configured OIDC end-session endpoint URL, if known **synchronously** —
+     * set explicitly via `endpoints.endSession`, or learned from a previous
+     * {@link discover}. `undefined` when the server advertises none.
+     *
+     * Exposed so a Backend-for-Frontend can drive RP-Initiated Logout (redirect
+     * to the OP's end-session endpoint) without re-running discovery. See
+     * `HonoBffOptions.rpInitiatedLogout`.
+     */
+    get endSessionEndpoint(): string | undefined;
+    /**
+     * This client's `client_id`.
+     *
+     * Exposed for the requests that identify the client without authenticating
+     * it — RP-Initiated Logout's `client_id`, which is how the OP knows whose
+     * registered `post_logout_redirect_uris` to check when no `id_token_hint` is
+     * available. It is a public identifier, never a credential.
+     */
+    get clientId(): string;
+    /**
+     * Builds the PKCE-protected authorize URL and persists the verifier under
+     * the returned `state`. Navigate the browser to `url`; the callback route
+     * then calls {@link handleAuthorizationCallback}. Non-browser callers can
+     * use the URL for out-of-band flows.
+     *
+     * @param options `returnTo` is stored with the pending request and handed
+     * back by the callback. The remaining fields let a server retarget the
+     * authorize URL, override `redirect_uri`, or bind the pending request to a
+     * per-request store.
+     * @returns The authorize URL and the `state` the callback will echo back.
+     * @throws {Error} when no authorization endpoint is configured or
+     * discoverable.
+     *
+     * @example
+     * ```ts
+     * import { DirectClient } from "@udibo/oauth2/client";
+     *
+     * const client = new DirectClient({
+     *   clientId: "spa",
+     *   endpoints: { authorization: "https://auth.example.com/authorize" },
+     *   redirectUri: "https://app.example.com/callback",
+     * });
+     * const { url, state } = await client.login({ returnTo: "/dashboard" });
+     * ```
+     */
+    login(options?: LoginOptions): Promise<AuthorizationRedirect>;
+    /**
+     * Completes the auth-code flow: reads `code` + `state` from the callback
+     * URL, exchanges the code at the token endpoint, persists the token bundle,
+     * and emits `authenticated`.
+     *
+     * Idempotent on duplicate calls with the same `code` — React strict-mode
+     * double-mounts would otherwise double-redeem a single-use code and fail the
+     * second call, so the first in-flight promise is returned again.
+     *
+     * @param input The callback URL, its query string, or the parsed params.
+     * @returns The persisted tokens and the `returnTo` recorded at login.
+     * @throws {OAuth2Error} when the callback carries `?error=…`, or the token
+     * exchange fails.
+     * @throws {TypeError} when `code` or `state` is missing.
+     * @throws {InvalidGrantError} when `state` is unknown or expired.
+     *
+     * @example
+     * ```ts
+     * import { DirectClient } from "@udibo/oauth2/client";
+     *
+     * declare const client: DirectClient;
+     * const { returnTo } = await client.handleAuthorizationCallback(
+     *   location.href,
+     * );
+     * location.replace(returnTo ?? "/");
+     * ```
+     */
+    handleAuthorizationCallback(input: URL | URLSearchParams | string): Promise<AuthorizationCallbackResult>;
+    /**
+     * **Advanced (BFF / multi-session servers).** SPA, mobile, and CLI consumers
+     * should call {@link handleAuthorizationCallback} instead — that variant
+     * persists the token bundle to this client's storage and emits the
+     * `authenticated` event the React adapter listens for.
+     *
+     * Exchanges an authorization code for tokens **without persisting them**.
+     * Used by server-side adapters that manage their own per-session storage
+     * (e.g. the Hono BFF, which keeps tokens in a `SessionStore` keyed by an
+     * HttpOnly cookie). Calling this from a single-session client splits the
+     * token state across this client's storage and the caller's external store,
+     * so refresh, revocation, and logout all stop working as expected.
+     *
+     * The verifier and `returnTo` are looked up under `state`; on success the
+     * record is consumed. Emits nothing — the caller owns session semantics.
+     *
+     * @param code The authorization code from the callback.
+     * @param state The `state` the callback echoed back.
+     * @param options Per-call `redirect_uri` and auth-request storage overrides,
+     * which must match what {@link login} was given.
+     * @returns The tokens, the rotated refresh token, and the recorded
+     * `returnTo`, plus the raw response.
+     * @throws {InvalidGrantError} when `state` is unknown or older than
+     * `authRequestTtlMs`.
+     */
+    exchangeAuthorizationCode(code: string, state: string, options?: ExchangeOptions): Promise<ExchangeResult>;
+    /**
+     * **Advanced (BFF / multi-session servers).** SPA, mobile, and CLI consumers
+     * should call {@link refresh} instead — that variant persists the rotated
+     * bundle, dedupes concurrent calls, and emits `token_refreshed`.
+     *
+     * Exchanges a refresh token for a fresh bundle **without persisting** it.
+     * Used by server-side adapters that manage their own per-session storage
+     * (the Hono BFF's `attachToken` middleware calls this when refreshing on
+     * expiry). Mixing this with this client's own token storage in a
+     * single-session deployment leaves the two out of sync.
+     *
+     * Does not share the single-flight promise with {@link refresh} and emits
+     * nothing — the caller owns concurrency control across its sessions.
+     *
+     * @param refreshToken The refresh token to redeem.
+     * @returns The new tokens, the rotated refresh token, and the raw response.
+     * @throws {OAuth2Error} when the token endpoint rejects the grant.
+     */
+    exchangeRefreshToken(refreshToken: string): Promise<ExchangeResult>;
+    /**
+     * Issues a token via the `client_credentials` grant, persists it, and emits
+     * `authenticated`. For machine-to-machine calls where there is no user.
+     *
+     * @param options `scope` overrides the client's default scope string.
+     * @returns The persisted token bundle.
+     * @throws {Error} when the client has no `clientSecret` — RFC 6749 §4.4
+     * restricts this grant to confidential clients.
+     * @throws {OAuth2Error} when the token endpoint rejects the grant.
+     *
+     * @example
+     * ```ts
+     * import { DirectClient } from "@udibo/oauth2/client";
+     *
+     * declare const client: DirectClient;
+     * const { accessToken } = await client.getClientCredentialsToken({
+     *   scope: "jobs:run",
+     * });
+     * ```
+     */
+    getClientCredentialsToken(options?: {
+        scope?: string;
+    }): Promise<TokenBundle>;
+    /**
+     * Refreshes the access token using the stored refresh token, persists the
+     * result, and emits `token_refreshed`. Single-flight: concurrent callers
+     * share one in-flight promise.
+     *
+     * If the refresh fails with `invalid_grant` (the token was revoked or, under
+     * rotation, already consumed), all local token state is cleared and
+     * `logged_out` is emitted so the framework adapter can redirect to login.
+     *
+     * Single-flight has one consequence worth knowing: a call that **joins** a
+     * refresh already started by {@link renewSession} inherits that call's quiet
+     * policy, so it will not emit `error` on a transport failure even though it
+     * still rejects. The rejection, not the event, is the contract for a caller
+     * that asked directly.
+     *
+     * A refresh-token storage that fails to read refuses the refresh: the
+     * rejection carries the storage's own error, `error` is emitted, and the
+     * stored session is left alone — a broken store is not evidence the grant
+     * died.
+     *
+     * @returns The new access token.
+     * @throws {InvalidGrantError} when no refresh token is stored, or the stored
+     * one is dead.
+     * @throws {Error} whatever the configured `RefreshTokenStorage` threw when
+     * the read itself failed.
+     */
+    refresh(): Promise<string>;
+    /**
+     * Initiates the device authorization flow (RFC 8628 §3.1) for an input-
+     * constrained device. Show the returned `user_code` and
+     * `verification_uri`, then hand `device_code` to {@link pollDeviceToken}.
+     *
+     * @param options `scope` overrides the client's default scope string.
+     * @returns The server's device authorization response.
+     * @throws {Error} when no device authorization endpoint is configured or
+     * discoverable.
+     * @throws {OAuth2Error} when the server rejects the request.
+     *
+     * @example
+     * ```ts
+     * import { DirectClient } from "@udibo/oauth2/client";
+     *
+     * declare const client: DirectClient;
+     * const grant = await client.startDeviceAuthorization();
+     * console.log(`go to ${grant.verification_uri}, enter ${grant.user_code}`);
+     * const tokens = await client.pollDeviceToken(grant.device_code, {
+     *   interval: grant.interval,
+     *   expiresAt: Date.now() + grant.expires_in * 1000,
+     * });
+     * ```
+     */
+    startDeviceAuthorization(options?: DeviceAuthorizationOptions): Promise<DeviceAuthorizationResponse>;
+    /**
+     * Polls the token endpoint for a device-code exchange (RFC 8628 §3.4),
+     * persists the tokens, and emits `authenticated`. Handles
+     * `authorization_pending` (keep polling) and `slow_down` (add 5s to the
+     * interval) automatically.
+     *
+     * @param deviceCode The `device_code` from
+     * {@link startDeviceAuthorization}.
+     * @param options Pass `interval` and `expiresAt` from the device
+     * authorization response so polling respects the server's advertised
+     * minimum interval and deadline, and `signal` to cancel.
+     * @returns The persisted token bundle.
+     * @throws {AccessDeniedError} when `signal` aborts, or the user declines.
+     * @throws {InvalidGrantError} when the device code expires before approval.
+     * @throws {OAuth2Error} on any other terminal error from the server.
+     */
+    pollDeviceToken(deviceCode: string, options?: PollDeviceTokenOptions): Promise<TokenBundle>;
+    /**
+     * Calls the introspection endpoint (RFC 7662) to ask the server whether a
+     * token is still active and what it carries.
+     *
+     * @param token The token to introspect.
+     * @param options `tokenTypeHint` tells the server which kind to look up
+     * first.
+     * @returns The introspection response; check `active`.
+     * @throws {Error} when the client has no `clientSecret` — RFC 7662 requires
+     * an authenticated caller.
+     * @throws {OAuth2Error} when the endpoint rejects the request.
+     */
+    introspect(token: string, options?: {
+        tokenTypeHint?: "access_token" | "refresh_token";
+    }): Promise<IntrospectionResult>;
+    /**
+     * Calls the revocation endpoint (RFC 7009) to kill a token server-side.
+     * Does not touch this client's storage — {@link logout} does both.
+     *
+     * @param token The token to revoke.
+     * @param options `tokenTypeHint` tells the server which kind to look up
+     * first.
+     * @throws {Error} when no revocation endpoint is configured or discoverable.
+     * @throws {OAuth2Error} when the endpoint rejects the request.
+     */
+    revoke(token: string, options?: {
+        tokenTypeHint?: "access_token" | "refresh_token";
+    }): Promise<void>;
+    /**
+     * Fetches the OIDC userinfo endpoint with the current access token,
+     * refreshing it first if it is close to expiry.
+     *
+     * @returns The claims the server returns.
+     * @throws {Error} when no userinfo endpoint is configured or discoverable.
+     * @throws {AccessDeniedError} when no token is stored and none can be
+     * refreshed.
+     */
+    getUserInfo(): Promise<UserInfoClaims>;
+    /**
+     * Base64url-decodes an OIDC `id_token` payload and returns the claims.
+     *
+     * **Does not verify the signature** — the token arrives from the token
+     * endpoint over TLS, so verification would only defend against a compromised
+     * TLS chain and is not a normal client concern. If you need verification
+     * (e.g. the token was obtained out-of-band), use a dedicated JWT library
+     * with your server's JWKS.
+     *
+     * @param idToken A compact-serialized JWS.
+     * @returns The decoded payload claims.
+     * @throws {TypeError | RangeError | SyntaxError} on a token that isn't a
+     * decodable JWS with a JSON payload. Callers that surface an authorization
+     * server's response to a user should catch, since a broken or hostile
+     * server controls this input.
+     */
+    decodeIdToken(idToken: string): UserInfoClaims;
+    /**
+     * Fetches with `Authorization: Bearer <access token>` attached, retrying
+     * once after a silent {@link refresh} if the response is a `401` carrying
+     * `WWW-Authenticate: … error="invalid_token"`.
+     *
+     * A `401` without that challenge is returned as-is — it means "not allowed",
+     * not "token stale", and re-minting would not help.
+     *
+     * @param input Request target, as for `fetch`. A `Request` keeps the headers
+     * and body it was built with; it is cloned up front so the retry has an
+     * unread body.
+     * @param init Request options. A caller-set `Authorization` header wins, and
+     * `init.headers` override same-named headers on a `Request` input.
+     * @returns The response; the original `401` when no new token could be
+     * minted. A transport failure on the retry itself rejects rather than
+     * masquerading as the original `401`.
+     *
+     * @example
+     * ```ts
+     * import { DirectClient } from "@udibo/oauth2/client";
+     *
+     * declare const client: DirectClient;
+     * const res = await client.fetch("https://api.example.com/items");
+     * ```
+     */
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /**
+     * Revokes the stored refresh token (best effort), clears all local token
+     * state, emits `logged_out`, and returns the OIDC end-session URL when the
+     * server advertises one.
+     *
+     * Best effort covers the read too: a refresh-token store that cannot be read
+     * skips the revocation rather than failing the sign-out, because a client
+     * that stays signed in locally because its store broke is the worse outcome.
+     *
+     * @param options `returnTo` becomes `post_logout_redirect_uri` on the
+     * end-session URL.
+     * @returns `{ url }` when the browser should visit the OP's end-session
+     * endpoint to drop the upstream SSO session, `{}` when sign-out completed
+     * locally.
+     *
+     * @example
+     * ```ts
+     * import { DirectClient } from "@udibo/oauth2/client";
+     *
+     * declare const client: DirectClient;
+     * const { url } = await client.logout({ returnTo: "https://app.test/" });
+     * if (url) location.assign(url);
+     * ```
+     */
+    logout(options?: LogoutOptions): Promise<LogoutRedirect>;
+    /**
+     * The signed-in user's claims: the decoded `id_token` when one was issued,
+     * otherwise the userinfo endpoint when one is configured, otherwise `null`.
+     *
+     * @returns The claims, or `null` when no token is stored or neither source
+     * is available.
+     */
+    getUser(): Promise<UserInfoClaims | null>;
+    /**
+     * The session as this client sees it, derived from stored tokens — no
+     * network call unless the claims come from a userinfo endpoint.
+     *
+     * `isAuthenticated` requires a usable access token: a stored bundle whose
+     * `accessToken` is non-empty and not past its expiry. A holder of a valid
+     * token therefore still reads as signed in when the server issues neither an
+     * `id_token` nor a userinfo endpoint, while an expired one reads as signed
+     * out rather than leaving the UI authenticated over a dead token. An expired
+     * bundle that a stored refresh token could still revive also reads as signed
+     * in, with `sessionExpiresIn: 0` — call {@link renewSession} to revive it.
+     *
+     * `logoutUrl` is always `null`: sign-out runs through {@link logout}, which
+     * revokes and clears locally rather than sending the browser somewhere.
+     *
+     * Never rejects — a failure to resolve claims reports a signed-out session
+     * and emits `error`, per {@link OAuth2ClientBase.getSession}.
+     *
+     * @returns The current {@link SessionState}.
+     */
+    getSession(): Promise<SessionState>;
+    /**
+     * Refreshes the access token, then reports the resulting session.
+     *
+     * Never rejects: a dead grant has already cleared the session and emitted
+     * `logged_out`, so the reported state is signed out, while a transient
+     * network failure leaves the stored tokens — and the reported state — as
+     * they were. Unlike {@link refresh}, nothing on this path emits `error`:
+     * it runs on a background timer, and a blip the client will simply retry
+     * must not paint a user-visible error over a session that is still perfectly
+     * good. A dead grant still emits `logged_out`, because the UI does have to
+     * react to that.
+     *
+     * "Transient" here means only "not `invalid_grant`", so a durable failure —
+     * a rotated client secret answering `invalid_client`, or a token endpoint
+     * returning `500` indefinitely — is retried silently for as long as the
+     * timer runs. The session ends when the access token finally expires and a
+     * request 401s, not when renewal starts failing. Subscribe to
+     * `token_refreshed` if you need to notice renewals that stopped landing.
+     *
+     * **A client with no refresh token cannot renew.** That includes the
+     * `client_credentials` case, where re-running the grant would be possible in
+     * principle: doing it automatically is refused because a confidential client
+     * that had signed a *user* in would silently swap that user's session for a
+     * machine identity. Re-run {@link getClientCredentialsToken} yourself.
+     *
+     * @returns The {@link SessionState} after the refresh attempt.
+     */
+    renewSession(): Promise<SessionState>;
+    /**
+     * Returns a usable access token, refreshing first when the stored one is
+     * within 30 seconds of expiry.
+     *
+     * Reach for this when you must attach `Authorization: Bearer <token>` to a
+     * request {@link fetch} can't carry (a custom transport, a third-party SDK).
+     * For ordinary HTTP calls prefer {@link fetch}, which attaches the token and
+     * handles the 401/refresh dance for you.
+     *
+     * @returns A non-expired access token.
+     * @throws {InvalidGrantError} when nothing is stored and no refresh token is
+     * available.
+     */
+    getAccessToken(): Promise<string>;
+}