@udibo/oauth2 0.1.0

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

@@ -0,0 +1,736 @@
+/**
+ * Authorization Server implementation for issuing OAuth2 tokens.
+ *
+ * Implements the OAuth 2.0 Authorization Framework (RFC 6749) with support for:
+ * - Token endpoint (RFC 6749 Section 3.2)
+ * - Authorization endpoint (RFC 6749 Section 3.1)
+ * - Token revocation (RFC 7009)
+ * - Token introspection (RFC 7662)
+ * - Server metadata (RFC 8414)
+ * - Device authorization (RFC 8628)
+ *
+ * **Configuration.** A single instance serves every tenant/origin. The only
+ * configuration seam is `resolve(request)`, which returns the services the
+ * server's own endpoints need (`{ clientService, tokenService }`) plus the
+ * issuer/endpoints. Each grant resolves its own services independently. For a
+ * single-tenant server, `resolve` is a constant function (create the services
+ * once, outside it, and return them every time).
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749
+ * @module
+ */
+import "../_dnt.polyfills.js";
+import type { AuthorizeParameters } from "../models/authorization-code.js";
+import type { AuthenticationContext } from "../models/authentication.js";
+import type { ClientInterface } from "../models/client.js";
+import type { Token, TokenResponse } from "../models/token.js";
+import type { AuthorizationServerMetadata } from "../models/responses.js";
+import type { AbstractScope, BasicScope } from "../models/scope.js";
+import type { IsPublicSuffix } from "./redirect-uri.js";
+import type { DispatchableGrant } from "./grants/grant.js";
+import type { ClientServiceInterface } from "./services/client.js";
+import type { TokenServiceInterface } from "./services/token.js";
+import { ResourceServer, type ResourceServerOptions, type ResourceServerServices } from "./resource-server.js";
+import { type SigningKeyProvider } from "./signing-keys.js";
+/** What {@link AuthorizationServer.handleEndSessionRequest} tells the app. */
+export interface EndSessionContext<Client extends ClientInterface> {
+    /** The logout request itself. */
+    request: Request;
+    /**
+     * The relying party the logout names — from a signature-valid
+     * `id_token_hint`'s audience, or from `client_id`. Null when the request
+     * named none, or named one this server does not know.
+     */
+    client: Client | null;
+    /**
+     * The `sub` of a signature-valid `id_token_hint`. Null when the request sent
+     * no hint, or one that did not verify — so a session lookup keyed on it must
+     * handle "no subject", which is the ordinary case for a client that never
+     * requested `openid`.
+     */
+    subject: string | null;
+    /**
+     * The RP's `logout_hint`, verbatim. **Unvalidated and unauthenticated** —
+     * OIDC defines it as a hint about which user to log out and nothing checks
+     * it, so treat it as a suggestion for a chooser UI, never as an identifier
+     * to end a session by.
+     */
+    logoutHint: string | null;
+}
+/** What an app's {@link EndSessionFn} may ask the server to do afterwards. */
+export interface EndSessionResult {
+    /**
+     * Headers to merge into the response — the session-clearing `Set-Cookie`,
+     * typically. The server owns `Location`; anything else is yours.
+     */
+    headers?: HeadersInit;
+    /**
+     * Where to send the browser when the request named no **authorized**
+     * `post_logout_redirect_uri` — your own "you are signed out" page. Not
+     * validated: it comes from your code, not from the request. Omit it and such
+     * a logout answers 204.
+     */
+    fallback?: string;
+}
+/**
+ * Ends the app's session for an RP-initiated logout. Called for every logout
+ * request that reaches the endpoint, including ones whose parameters do not
+ * check out — refusing to end a session because a *redirect* was unauthorized
+ * would leave the person signed in, which is the opposite of what they asked
+ * for.
+ */
+export type EndSessionFn<Client extends ClientInterface> = (context: EndSessionContext<Client>) => EndSessionResult | void | Promise<EndSessionResult | void>;
+/** Grants configuration for the authorization server. */
+export interface AuthorizationServerGrants<Client extends ClientInterface, User, S extends AbstractScope> {
+    /** Maps an OAuth2 `grant_type` value to the grant that handles it. */
+    [grantType: string]: DispatchableGrant<Client, User, S>;
+}
+/**
+ * Services the authorization server's OWN endpoints need: client lookup/auth
+ * (token, revocation, introspection, device-authorization) and token storage
+ * (plus the inherited bearer-token validation). Grant-specific services
+ * (authorization-code, user, device) live on the grants, not here.
+ */
+export interface AuthorizationServerServices<Client extends ClientInterface, User, S extends AbstractScope> extends ResourceServerServices<Client, User, S> {
+    /** Looks up and authenticates clients for the AS endpoints. */
+    clientService: ClientServiceInterface<Client, User>;
+    /** The full token service (read + write) the AS endpoints need. */
+    tokenService: TokenServiceInterface<Client, User, S>;
+}
+/**
+ * Per-request context resolved by an {@link AuthorizationServer}.
+ *
+ * `services` is the server's own services for this request. The issuer and
+ * endpoint fields drive the RFC 8414 metadata and the in-process
+ * {@link localAuthServerFetch} routing; any endpoint omitted defaults to
+ * `${issuer}${path}` (e.g. `${issuer}/token`), so a server whose endpoints sit
+ * at the issuer root needs only `issuer`.
+ */
+export interface AuthorizationServerContext<Client extends ClientInterface, User, S extends AbstractScope> {
+    /** The server's own services for this request. */
+    services: AuthorizationServerServices<Client, User, S>;
+    /** The issuer identifier URL for this request. */
+    issuer?: string;
+    /** URL of the authorization endpoint. Defaults to `${issuer}/authorize`. */
+    authorizationEndpoint?: string;
+    /** URL of the token endpoint. Defaults to `${issuer}/token`. */
+    tokenEndpoint?: string;
+    /** URL of the token revocation endpoint (RFC 7009). Defaults to `${issuer}/revoke`. */
+    revocationEndpoint?: string;
+    /** URL of the token introspection endpoint (RFC 7662). Defaults to `${issuer}/introspect`. */
+    introspectionEndpoint?: string;
+    /** URL of the device authorization endpoint (RFC 8628). Defaults to `${issuer}/device_authorization`. */
+    deviceAuthorizationEndpoint?: string;
+    /**
+     * URL where users verify device codes (RFC 8628 Section 3.2). Unlike the
+     * `*Endpoint` fields it has no issuer-derived default: the device
+     * authorization endpoint answers 500 `server_error` until it is set.
+     */
+    verificationUri?: string;
+    /** URL of the JWKS endpoint. Defaults to `${issuer}/jwks`. */
+    jwksEndpoint?: string;
+    /** URL of the OIDC UserInfo endpoint. Defaults to `${issuer}/userinfo`. */
+    userinfoEndpoint?: string;
+    /**
+     * URL of the OIDC RP-Initiated Logout end-session endpoint. Defaults to
+     * `${issuer}/end_session`.
+     */
+    endSessionEndpoint?: string;
+}
+/**
+ * Options for configuring the authorization server.
+ */
+export interface AuthorizationServerOptions<Client extends ClientInterface, User, S extends AbstractScope> extends Omit<ResourceServerOptions<Client, User, S>, "resolve"> {
+    /**
+     * Resolves the per-request context — the server's own services plus the
+     * issuer/endpoints. This is the only services seam: for a single-tenant
+     * server it is a constant function returning the same context every time.
+     */
+    resolve: (request: Request) => AuthorizationServerContext<Client, User, S> | Promise<AuthorizationServerContext<Client, User, S>>;
+    /** Grants the server supports, keyed by `grant_type` (each key must equal `grant.grantType`). */
+    grants: AuthorizationServerGrants<Client, User, S>;
+    /** Scopes supported by this server (advertised in RFC 8414 metadata). */
+    scopesSupported?: string[];
+    /**
+     * OIDC issuance keys. Configuring this turns the OIDC provider surface on:
+     * the token endpoint mints an `id_token` for user-bound grants with the
+     * `openid` scope, and the JWKS/UserInfo endpoints and
+     * `openid-configuration` metadata go live. In multi-instance deploys load
+     * one persisted key on every instance (see `signing-keys.ts`).
+     */
+    signingKeys?: SigningKeyProvider;
+    /**
+     * Refuses to construct a server that would run with OIDC issuance off. Set
+     * it on any deployment that issues `id_token`s: without `signingKeys` an
+     * instance still boots and serves plain OAuth2 while answering 404 from the
+     * OIDC surface, so a rollout that dropped the key presents as "some relying
+     * parties broke" instead of a failed deploy.
+     *
+     * It asserts that a {@linkcode SigningKeyProvider} is wired, not that the
+     * provider can produce a key. For a true fail-to-start, load the key before
+     * constructing the server (`await importSigningKeyJwk(...)` into a
+     * `StaticSigningKeyProvider`) so an unreadable key throws on the same boot
+     * path.
+     *
+     * @default false
+     */
+    requireOidc?: boolean;
+    /**
+     * Ends the app's session for an OIDC RP-Initiated Logout. Configuring it is
+     * what turns the end-session endpoint on: without it the endpoint answers
+     * 404 **and** `end_session_endpoint` stays out of the discovery document, so
+     * metadata never advertises a logout the server cannot perform.
+     */
+    endSession?: EndSessionFn<Client>;
+    /**
+     * Maps a user to the id_token/UserInfo `sub` claim. Defaults to the user's
+     * `id` property; override when your subject identifier differs.
+     */
+    subjectOf?: (user: User) => string;
+    /**
+     * Extra OIDC claims for the id_token and UserInfo response (e.g. `name`,
+     * `email` when the scope allows). Merged under the protocol claims — `sub`
+     * (from `subjectOf`) and the id_token's `iss`/`aud`/`iat`/`exp`/`nonce`
+     * always win.
+     * The third argument is this credential's recorded authentication event,
+     * including on refresh and UserInfo. Return its fields to emit them; never
+     * substitute a user's newer session event. It is absent for legacy records.
+     */
+    userClaims?: (user: User, scope?: S | null, authenticationContext?: AuthenticationContext) => Promise<Record<string, unknown>> | Record<string, unknown>;
+    /**
+     * Extension fields for an **active** introspection response (RFC 7662
+     * permits them), so a resource server validating by introspection sees the
+     * same authorization claims a JWT access token carries — feed it the same
+     * computation `userClaims` uses and the two validation strategies stay in
+     * field-level parity. Called with the introspected token; the RFC 7662
+     * protocol fields (`active`, `scope`, `client_id`, `token_type`, `exp`,
+     * `iss`, `sub`, `username`) always win over anything it returns.
+     */
+    introspectionClaims?: (token: Token<Client, User, S>) => Promise<Record<string, unknown>> | Record<string, unknown>;
+    /**
+     * Authorizes a client to introspect a resolved, unexpired token. A false
+     * result returns only `{ active: false }`, without invoking
+     * {@linkcode introspectionClaims}. An error fails the request closed.
+     * `tokenType` is the resolved kind, regardless of the request's hint.
+     *
+     * Omitted by default for compatibility with separately authorized resource
+     * servers: every client admitted to the endpoint may introspect any token.
+     * Configure this policy when ordinary client credentials can reach the
+     * endpoint. A public client ID alone does not authenticate its holder.
+     *
+     * @example
+     * ```ts
+     * const canIntrospectToken = (client: { id: string; confidential?: boolean },
+     *   token: { client: { id: string } }): boolean =>
+     *   client.confidential === true && client.id === token.client.id;
+     * ```
+     */
+    canIntrospectToken?: (client: Client, token: Token<Client, User, S>, tokenType: "access_token" | "refresh_token") => boolean | Promise<boolean>;
+    /**
+     * Decides whether the domain under a wildcard redirect URI is a public
+     * suffix, which is what bounds a wildcard registration to one registrant's
+     * namespace. Import `isPublicSuffix` from
+     * `@udibo/oauth2/server/public-suffix` to use the bundled list.
+     *
+     * Leaving it unset makes every wildcard registration inert — the authorize
+     * endpoint will not match one — which is the right setting for a server that
+     * only ever registers literal redirect URIs, and keeps the list out of the
+     * bundle.
+     */
+    isPublicSuffix?: IsPublicSuffix;
+}
+/**
+ * Function to authenticate the user during authorization.
+ *
+ * Return one of:
+ *
+ * - `{ user, authorizedScope?, authenticationContext? }` — user is authenticated; the authorize flow
+ *   continues. `authorizedScope` declares scopes the user has already
+ *   pre-authorized for this client; anything in the requested scope not
+ *   covered by it triggers consent. **Omitting `authorizedScope` means
+ *   "nothing pre-authorized"** — so any requested scope needs consent: the
+ *   framework calls `handleConsent` when one is configured, and otherwise
+ *   treats the request as consented and grants the accepted scope. To
+ *   pre-authorize everything, return the requested scope as `authorizedScope`.
+ *   Supply only verified event claims in `authenticationContext`; the code,
+ *   token and refresh descendants retain a snapshot. Omit unknown claims.
+ * - `null` — explicit denial. The framework redirects the browser to
+ *   `redirect_uri` with `error=access_denied`. Use this for "the user said
+ *   no", not for "the user isn't signed in yet."
+ * - A `Response` — short-circuits the rest of the authorize flow and is
+ *   returned to the browser as-is. Use this to redirect to a login page,
+ *   render an interstitial, etc.
+ */
+export type AuthenticateUserFn<User> = (request: Request) => Promise<{
+    user: User;
+    authorizedScope?: AbstractScope;
+    authenticationContext?: AuthenticationContext;
+} | Response | null>;
+/**
+ * Function to handle user consent during authorization.
+ *
+ * Called when the requested scope is not already covered by the user's
+ * pre-authorized scope. Return one of:
+ *
+ * - `{ approved: true, scope? }` — consent granted. `scope` optionally
+ *   narrows the granted scope (RFC 6749 §3.3 allows partial grants).
+ * - `{ approved: false }` — consent denied. The framework redirects to
+ *   `redirect_uri` with `error=access_denied`.
+ * - A `Response` — short-circuits the rest of the authorize flow and is
+ *   returned to the browser as-is. Use this to render a consent page that
+ *   later resubmits to the authorize endpoint with the user's decision.
+ */
+export type HandleConsentFn<Client extends ClientInterface, S extends AbstractScope> = (client: Client, requestedScope: S | undefined, user: unknown) => Promise<{
+    approved: boolean;
+    scope?: S;
+} | Response>;
+/** Resolved endpoint URLs for a request (issuer-derived unless overridden). */
+export interface ResolvedEndpoints {
+    /** Authorization endpoint URL, if resolved. */
+    authorization?: string;
+    /** Token endpoint URL, if resolved. */
+    token?: string;
+    /** Token revocation endpoint URL, if resolved. */
+    revocation?: string;
+    /** Token introspection endpoint URL, if resolved. */
+    introspection?: string;
+    /** Device authorization endpoint URL, if resolved. */
+    deviceAuthorization?: string;
+    /** JWKS endpoint URL, if resolved. */
+    jwks?: string;
+    /** OIDC UserInfo endpoint URL, if resolved. */
+    userinfo?: string;
+    /** OIDC RP-Initiated Logout end-session endpoint URL, if resolved. */
+    endSession?: string;
+}
+/**
+ * Every endpoint the authorization server serves, by name — the seven it
+ * advertises in its metadata (the {@link ResolvedEndpoints} keys) plus
+ * `metadata` and `oidcMetadata`, the two discovery documents that are served
+ * but never advertised. Index {@link ENDPOINT_PATHS} and
+ * {@link ENDPOINT_METHODS} with it to enumerate the whole surface.
+ */
+export type EndpointKey = "authorization" | "token" | "revocation" | "introspection" | "deviceAuthorization" | "jwks" | "userinfo" | "endSession" | "metadata" | "oidcMetadata";
+/**
+ * The path each endpoint is served from when the request context supplies only
+ * an `issuer` (so the endpoint URL is `${issuer}${path}`). Mount handlers at
+ * these paths — as the Hono adapter's `routes()` does — to match what the
+ * server advertises in its RFC 8414 metadata.
+ *
+ * Covers the whole served surface: the seven endpoints the server advertises,
+ * plus the two discovery documents (`metadata` for RFC 8414,
+ * `oidcMetadata` for OIDC Discovery) that are served but never advertised.
+ * Pair it with {@link ENDPOINT_METHODS} to enumerate path *and* verbs.
+ *
+ * @example Mount every endpoint yourself
+ * ```ts
+ * for (const key of Object.keys(ENDPOINT_PATHS) as (keyof typeof ENDPOINT_PATHS)[]) {
+ *   app.on([...ENDPOINT_METHODS[key]], ENDPOINT_PATHS[key], handlerFor(key));
+ * }
+ * ```
+ */
+export declare const ENDPOINT_PATHS: Readonly<Record<EndpointKey, string>>;
+/**
+ * The HTTP methods each endpoint in {@link ENDPOINT_PATHS} answers — `POST` for
+ * the token-style endpoints, `GET` for authorize/JWKS/discovery, both for
+ * UserInfo. Read it instead of re-deriving verbs per endpoint, so a hand-rolled
+ * mount answers exactly what the built-in `routes()` does.
+ *
+ * @example
+ * ```ts
+ * app.on([...ENDPOINT_METHODS.userinfo], ENDPOINT_PATHS.userinfo, handler);
+ * ```
+ */
+export declare const ENDPOINT_METHODS: Readonly<Record<EndpointKey, readonly string[]>>;
+/**
+ * Authorization Server for issuing OAuth2 tokens.
+ *
+ * Handles OAuth2 endpoints including:
+ * - Token endpoint (POST /token)
+ * - Authorization endpoint (GET /authorize)
+ * - Revocation endpoint (POST /revoke) - RFC 7009
+ * - Introspection endpoint (POST /introspect) - RFC 7662
+ * - Device authorization endpoint (POST /device_authorization) - RFC 8628
+ * - Metadata endpoint (GET /.well-known/oauth-authorization-server) - RFC 8414
+ *
+ * Framework-agnostic: each `handle*Request` method takes a web `Request` and
+ * returns a `Response`, so an adapter routes its endpoints to them. Extends
+ * {@linkcode ResourceServer}, so the same instance also validates bearer
+ * tokens. A single instance serves every tenant/origin via the `resolve`
+ * callback in {@linkcode AuthorizationServerOptions}.
+ *
+ * The handlers throw {@linkcode HttpError} subclasses on failure (e.g.
+ * {@linkcode InvalidRequestError}, {@linkcode InvalidClientError},
+ * {@linkcode UnsupportedGrantTypeError}) and convert them to RFC 6749 §5.2
+ * error responses unless `throwOnError` is set.
+ *
+ * @template Client The client entity type.
+ * @template User The resource-owner entity type.
+ * @template S The scope type used across grants and metadata.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749
+ *
+ * @example
+ * ```ts
+ * const server = new AuthorizationServer({
+ *   resolve: () => ({ services, issuer: "https://auth.example.com" }),
+ *   grants: { authorization_code: authCodeGrant, refresh_token: refreshGrant },
+ * });
+ *
+ * app.post("/token", (c) => server.handleTokenRequest(c.req.raw));
+ * ```
+ */
+export declare class AuthorizationServer<Client extends ClientInterface, User, S extends AbstractScope = BasicScope> extends ResourceServer<Client, User, S> {
+    #private;
+    /** Grants the server supports, keyed by `grant_type`. */
+    grants: AuthorizationServerGrants<Client, User, S>;
+    /** Scopes advertised in RFC 8414 metadata, if configured. */
+    scopesSupported?: string[];
+    /** OIDC signing keys; the OIDC surface is active when set. */
+    signingKeys?: SigningKeyProvider;
+    /**
+     * Creates an authorization server from the given
+     * {@linkcode AuthorizationServerOptions}.
+     *
+     * @throws {Error} If any grant's map key does not equal its `grantType`.
+     * @throws {Error} If `requireOidc` is set without `signingKeys`.
+     */
+    constructor(options: AuthorizationServerOptions<Client, User, S>);
+    /**
+     * Whether this instance will actually serve the OIDC surface: `true` once
+     * `signingKeys` is set, which is what gates `id_token` issuance and the
+     * `/jwks`, `/userinfo`, and `openid-configuration` endpoints (they answer
+     * 404 while it is `false`).
+     *
+     * Read it in a readiness probe to keep an instance that booted without its
+     * signing key out of the load balancer instead of letting it 404 relying
+     * parties. It reports the provider this server configured — not that the
+     * provider can produce a key, which surfaces on first use — and it tracks
+     * the `signingKeys` field, so it is meaningful from construction onward and
+     * follows any later reassignment.
+     */
+    get oidcEnabled(): boolean;
+    /** Resolves the per-request {@link AuthorizationServerContext}. */
+    authorizationContext(request: Request): Promise<AuthorizationServerContext<Client, User, S>>;
+    /** The resolved endpoint URLs for a request. Used by {@link localAuthServerFetch}. */
+    resolveEndpoints(request: Request): Promise<ResolvedEndpoints>;
+    /**
+     * Converts a token to a bearer token response body.
+     */
+    bearerToken(token: Token<Client, User, S>, services: AuthorizationServerServices<Client, User, S>): TokenResponse;
+    /**
+     * Creates a token response. When the issuing `grant` is passed, an id_token
+     * is only minted for grants that represent an end-user authentication
+     * (`grant.issuesIdToken !== false`).
+     */
+    createTokenResponse(token: Token<Client, User, S>, context: AuthorizationServerContext<Client, User, S>, grant?: DispatchableGrant<Client, User, S>): Promise<Response>;
+    /**
+     * Applies `Cache-Control: no-store` and `Pragma: no-cache` headers to an
+     * error per RFC 6749 Section 5.2. The headers land on both the rethrown
+     * error (when {@link throwOnError} is true) and the generated response.
+     */
+    private addCacheHeaders;
+    /**
+     * Error-prepare callback for the endpoints that authenticate the client
+     * (token, revocation, introspection, device authorization). Attaches the
+     * RFC 6749 Section 5.2 cache headers, and — when client authentication was
+     * attempted via the `Authorization` header and failed with a 401 — the
+     * matching `WWW-Authenticate: Basic` challenge that RFC 6749 Section 5.2
+     * requires.
+     */
+    private prepareClientAuthError;
+    /**
+     * Handles a token request (POST /token).
+     * Supports multiple grant types based on the configured grants.
+     *
+     * A malformed request — wrong method, a content-type other than
+     * `application/x-www-form-urlencoded`, or an unsupported grant — is a 400
+     * `invalid_request`.
+     */
+    handleTokenRequest(request: Request): Promise<Response>;
+    /**
+     * Mint an OIDC id_token for a user-bound token whose scope includes
+     * `openid`, or `undefined` when the OIDC surface is off (no signing keys),
+     * the token has no user, the scope lacks `openid`, or no issuer resolved.
+     */
+    mintIdToken(token: Token<Client, User, S>, context: AuthorizationServerContext<Client, User, S>): Promise<string | undefined>;
+    /**
+     * Handles an OIDC discovery request (GET /.well-known/openid-configuration):
+     * the RFC 8414 metadata document including the OIDC fields. 404 when OIDC
+     * issuance is off (no signing keys), so relying parties fail fast instead of
+     * reading a document missing its REQUIRED OIDC members.
+     */
+    handleOidcMetadataRequest(request: Request): Promise<Response>;
+    /**
+     * Handles a JWKS request (GET /jwks): the public signing keys id_tokens and
+     * JWT access tokens verify against. 404 when OIDC issuance is off.
+     */
+    handleJwksRequest(_request: Request): Promise<Response>;
+    /**
+     * Handles an OIDC UserInfo request (GET/POST /userinfo): validates the
+     * bearer token (which must carry the `openid` scope and a user) and returns
+     * `sub` plus any configured `userClaims`.
+     *
+     * Failures follow RFC 6750 Section 3.1, which OIDC Core Section 5.3.3 defers
+     * to: a missing, malformed, or expired token is a 401 (`invalid_token`,
+     * omitted from the challenge when no credentials were presented at all),
+     * while a **valid** token that simply lacks the `openid` scope is a 403
+     * `insufficient_scope` whose challenge names `scope="openid"`. The
+     * distinction matters to relying parties — a 401 tells an RP its credential
+     * is bad, so answering one for a scope problem sends it to refresh a token
+     * that will fail again the same way.
+     */
+    handleUserInfoRequest(request: Request): Promise<Response>;
+    /**
+     * Handles an OIDC RP-Initiated Logout request (GET/POST /end_session).
+     *
+     * The server does not know what a session **is** — that is the app's — so
+     * `endSession` does the ending and this method does the protocol around it:
+     * identifying the relying party, authorizing the return trip, and shaping
+     * the response. `endSession` is always called, even when nothing else about
+     * the request checks out, because a logout that refuses to log anyone out is
+     * the worst possible failure mode for this endpoint.
+     *
+     * **Authorizing `post_logout_redirect_uri` is the whole security surface.**
+     * It is matched by **exact string** against the resolved client's
+     * {@link ClientInterface.postLogoutRedirectUris} — no patterns, no prefixes,
+     * unlike the authorization endpoint's redirect matching. A logout redirect
+     * carries no code to steal, but an unvalidated one is an open redirect on the
+     * IDP's own domain, which is a phishing primitive: the victim really did just
+     * come from your login page. When no client resolves, or the URI is not
+     * registered, the browser is **not** sent there — it goes to `fallback` if
+     * the app supplied one, or gets a bare 204.
+     *
+     * `id_token_hint` is verified against the signing keys but its expiry is
+     * ignored: by the time anyone logs out the id_token naming their session has
+     * usually expired, and it is a hint, not authority. `client_id` is accepted
+     * as the fallback identifier the spec allows. `state` rides along only to a
+     * URI that passed authorization.
+     *
+     * Wire the app's session teardown through the `endSession` **constructor
+     * option**; this method answers 404 without it, and the discovery document
+     * omits `end_session_endpoint` to match.
+     *
+     * @example
+     * ```ts
+     * const server = new AuthorizationServer({
+     *   resolve,
+     *   grants,
+     *   signingKeys,
+     *   endSession: async ({ subject }) => {
+     *     if (subject) await sessions.deleteByUserId(subject);
+     *     return { headers: { "Set-Cookie": clearSessionCookie() }, fallback: "/" };
+     *   },
+     * });
+     * app.all("/end_session", (c) => server.handleEndSessionRequest(c.req.raw));
+     * ```
+     */
+    handleEndSessionRequest(request: Request): Promise<Response>;
+    /**
+     * Parses authorization request parameters from the query string.
+     *
+     * The authorization endpoint is GET-only (RFC 6749 Section 3.1 requires GET
+     * and only permits POST), so parameters are read from `url.searchParams`.
+     */
+    parseAuthorizeParameters(request: Request): AuthorizeParameters;
+    /**
+     * Handles an authorization request (GET /authorize).
+     * Used for the authorization code flow.
+     *
+     * Once the request has named a redirect URI the client registered, failures
+     * are reported to that URI as an RFC 6749 Section 4.1.2.1 error redirect;
+     * before that they are error responses from this endpoint, since there is no
+     * verified place to send the user back to.
+     *
+     * Requires a grant extending {@linkcode AuthorizationCodeGrant} registered
+     * under `authorization_code`; without one the endpoint answers 500
+     * `server_error` (or rethrows, with `throwOnError`).
+     *
+     * @param request The incoming request
+     * @param authenticateUser Function to authenticate the user
+     * @param handleConsent Optional function to handle user consent
+     * @returns A Response (redirect to client or error page)
+     */
+    handleAuthorizeRequest(request: Request, authenticateUser: AuthenticateUserFn<User>, handleConsent?: HandleConsentFn<Client, S>): Promise<Response>;
+    /**
+     * Authenticates a client from the credentials the request presents: Basic
+     * authentication (RFC 6749 Section 2.3.1) or the `client_id`/`client_secret`
+     * of `body`, the form body the endpoint already parsed. The grants
+     * authenticate through the same implementation, so a request that fails here
+     * fails identically at the token endpoint.
+     *
+     * @throws {InvalidClientError} If client authentication fails
+     */
+    authenticateClient(request: Request, body: FormData, services: AuthorizationServerServices<Client, User, S>): Promise<Client>;
+    /**
+     * Handles a token revocation request (POST /revoke).
+     *
+     * Per RFC 7009, requires client authentication and accepts:
+     * - token: The token to revoke (required)
+     * - token_type_hint: Hint about token type (optional)
+     *
+     * **A client can only revoke its own tokens.** RFC 7009 Section 2.1 requires
+     * the server to verify that the presented token was issued to the
+     * authenticated client; without that check any client that has observed a
+     * token value — a resource server it called, a shared browser, a log — could
+     * end another application's live sessions at will. A token belonging to a
+     * different client is left alone.
+     *
+     * Always returns 200 OK, even if the token was invalid, already revoked, or
+     * issued to another client: RFC 7009 Section 2.2 requires that answer so the
+     * endpoint cannot be used as an oracle for whether a token value is live or
+     * whose it is. That covers the token only: a malformed request — wrong
+     * method, a content-type other than `application/x-www-form-urlencoded`, or
+     * no `token` parameter — is a 400 `invalid_request`, as on the token
+     * endpoint.
+     *
+     * `token_type_hint` orders the lookup rather than restricting it, so a client
+     * that mislabels its token still gets it revoked.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc7009
+     */
+    handleRevocationRequest(request: Request): Promise<Response>;
+    /**
+     * Handles a token introspection request (POST /introspect).
+     *
+     * Per RFC 7662, requires client authentication and returns information
+     * about the token including whether it is active.
+     * {@linkcode AuthorizationServerOptions.canIntrospectToken} controls which
+     * tokens an authenticated caller may inspect. A denial returns only
+     * `{ active: false }`; without a policy, all admitted clients may inspect
+     * any token, including separately authorized resource servers.
+     *
+     * Both access tokens and refresh tokens introspect. `token_type_hint` orders
+     * the lookup rather than restricting it (RFC 7662 Section 2.1 requires the
+     * other kind to be tried when the hinted lookup misses), so a mislabelled
+     * token still resolves. An active access token carries
+     * `token_type: "Bearer"`; a refresh token carries no `token_type`, since
+     * that field describes how an access token is presented, and its `exp` is
+     * the refresh token's own expiry.
+     *
+     * A token with no user — the client acting as its own resource owner, as
+     * the client credentials grant issues — carries no `sub` and no `username`;
+     * `client_id` identifies the machine. `sub` is optional in RFC 7662, and
+     * leaving it absent keeps `sub` an unambiguous "there is a resource owner"
+     * signal rather than overloading `client_id` into the subject namespace
+     * (RFC 9700 §4.15.1).
+     *
+     * A wrong method, or a content type other than
+     * `application/x-www-form-urlencoded`, is a 400 `invalid_request`, as on the
+     * token endpoint.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc7662
+     */
+    handleIntrospectionRequest(request: Request): Promise<Response>;
+    /**
+     * Gets OAuth2 server metadata (RFC 8414).
+     *
+     * Returns metadata about this authorization server including supported
+     * grant types, endpoints, and capabilities.
+     *
+     * `code_challenge_methods_supported` is derived from the registered
+     * authorization code grant's own `challengeMethods`, so a server that
+     * registers an extra method (or drops `S256`) advertises what it will
+     * actually accept. It is omitted entirely when no authorization code grant
+     * is registered, since PKCE has nothing to apply to.
+     *
+     * `token_endpoint_auth_methods_supported` always includes `none`, the
+     * RFC 7591 method for a client with no secret. The token endpoint accepts it
+     * on every deployment and for every grant — a request carrying only
+     * `client_id` reaches `ClientServiceInterface.getAuthenticated` with no
+     * secret, which that interface's contract requires to resolve a public
+     * client (an authorization-code exchange carrying a `code_verifier` looks
+     * the client up with `get` instead when `requireClientAuthentication` is
+     * explicitly `false`) — and there is no option that turns it off, so it is not
+     * conditional on anything a caller configures. Which clients may use it is
+     * decided per client, by whether the client has a secret; discovery
+     * describes the endpoint, not the client population.
+     *
+     * @throws {ServerError} If the resolved context has no `issuer` — RFC 8414
+     * makes it REQUIRED and it is the field clients validate against.
+     * @see https://datatracker.ietf.org/doc/html/rfc8414#section-2
+     * @see https://datatracker.ietf.org/doc/html/rfc7591#section-2
+     */
+    getMetadata(context: AuthorizationServerContext<Client, User, S>): AuthorizationServerMetadata;
+    /**
+     * Handles a metadata request (GET /.well-known/oauth-authorization-server).
+     *
+     * Returns the authorization server metadata as JSON per RFC 8414.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc8414
+     */
+    handleMetadataRequest(request: Request): Promise<Response>;
+    /**
+     * Handles a device authorization request (POST /device_authorization).
+     *
+     * Initiates the device authorization flow by generating a device_code
+     * and user_code that the user can use to authorize the request on
+     * a secondary device.
+     *
+     * Requires a grant extending {@linkcode DeviceAuthorizationGrant} registered
+     * under `urn:ietf:params:oauth:grant-type:device_code`, and a
+     * `verificationUri` on the resolved context; without either the endpoint
+     * answers 500 `server_error`. A wrong method, or a content type other than
+     * `application/x-www-form-urlencoded`, is a 400 `invalid_request`, as on the
+     * token endpoint.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.1
+     * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.2
+     */
+    handleDeviceAuthorizationRequest(request: Request): Promise<Response>;
+}
+/**
+ * Returns a `fetch`-compatible function that dispatches requests directly
+ * to the {@link AuthorizationServer}'s handlers in-process, bypassing the
+ * network.
+ *
+ * Use this to point a `DirectClient` at a co-located authorization
+ * server — the request flow becomes a plain method call, so token refresh
+ * (and every other client → server interaction) stays in-process.
+ *
+ * Routing is by pathname against the endpoints the server resolves for the
+ * request (so it follows per-request issuer/origin):
+ * - `POST {tokenEndpoint}` → `handleTokenRequest`
+ * - `POST {revocationEndpoint}` → `handleRevocationRequest`
+ * - `POST {introspectionEndpoint}` → `handleIntrospectionRequest`
+ * - `POST {deviceAuthorizationEndpoint}` → `handleDeviceAuthorizationRequest`
+ * - `GET  /.well-known/oauth-authorization-server` → `handleMetadataRequest`
+ *
+ * The authorization endpoint is deliberately **not** routed: `/authorize`
+ * needs an `authenticateUser` (and optional `handleConsent`) callback this
+ * transport has no access to, and in real flows it's a browser navigation,
+ * never a call through the client's `fetch`. A request to it throws an
+ * actionable error pointing at `handleAuthorizeRequest`. Any other path also
+ * throws — the helper intentionally does not proxy arbitrary paths; if a call
+ * lands here unexpectedly, that's a wiring bug worth surfacing rather than
+ * silently forwarding.
+ */
+export declare function localAuthServerFetch<Client extends ClientInterface, User, S extends AbstractScope>(authServer: AuthorizationServer<Client, User, S>): typeof fetch;
+export { AbstractGrant } from "./grants/grant.js";
+export type { DispatchableGrant, GrantOptions, GrantServices, } from "./grants/grant.js";
+export { AuthorizationCodeGrant } from "./grants/authorization-code.js";
+export type { PKCEClientCredentials } from "./grants/authorization-code.js";
+export type { AuthorizationCodeGrantOptions, AuthorizationCodeGrantServices, GenerateAuthorizationCodeOptions, } from "./grants/authorization-code.js";
+export { ClientCredentialsGrant } from "./grants/client-credentials.js";
+export type { ClientCredentialsGrantOptions, ClientCredentialsGrantServices, } from "./grants/client-credentials.js";
+export { createJwtAccessTokenGenerator, exportSigningKeyJwk, generateSigningKey, importSigningKeyJwk, RotatingSigningKeyProvider, type RotatingSigningKeyProviderOptions, type SigningKey, type SigningKeyProvider, signJwt, StaticSigningKeyProvider, verifyJwt, type VerifyJwtOptions, } from "./signing-keys.js";
+export { RefreshTokenGrant } from "./grants/refresh-token.js";
+export type { RefreshTokenGrantOptions, RefreshTokenGrantServices, TokenReuseEvent, } from "./grants/refresh-token.js";
+export { PasswordGrant } from "./grants/password.js";
+export type { PasswordGrantOptions, PasswordGrantServices, } from "./grants/password.js";
+export { DeviceAuthorizationGrant } from "./grants/device-authorization.js";
+export type { DeviceAuthorizationGrantOptions, DeviceAuthorizationGrantServices, } from "./grants/device-authorization.js";
+export { AbstractTokenService, type AbstractTokenServiceOptions, type TokenServiceInterface, } from "./services/token.js";
+export type { ClientServiceInterface } from "./services/client.js";
+export { AbstractAuthorizationCodeService, type AbstractAuthorizationCodeServiceOptions, type AuthorizationCodeServiceInterface, } from "./services/authorization-code.js";
+export type { DeviceAuthorizationServiceInterface } from "./services/device-authorization.js";
+export type { UserServiceInterface } from "./services/user.js";
+export type { AuthorizationCode, AuthorizeParameters, } from "../models/authorization-code.js";
+export type { DeviceAuthorization } from "../models/device-authorization.js";
+export type { AuthorizationServerMetadata, DeviceAuthorizationResponse, ErrorResponse, OAuth2ErrorCode, } from "../models/responses.js";
+export { challengeMethods, CODE_VERIFIER_MAX_LENGTH, CODE_VERIFIER_MIN_LENGTH, CODE_VERIFIER_PATTERN, generateCodeChallenge, generateCodeVerifier, generateState, getChallengeMethod, validateCodeChallenge, validateCodeVerifier, verifyCodeChallenge, } from "../utils/pkce.js";
+export type { ChallengeMethod, ChallengeMethods } from "../utils/pkce.js";
+export { encodeBasicAuth, parseBasicAuth, tryParseBasicAuth, } from "../utils/basic-auth.js";
+export type { BasicAuth } from "../utils/basic-auth.js";
+export { checkRedirectUriPattern, isRedirectUriPattern, matchRedirectUri, } from "./redirect-uri.js";
+export type { IsPublicSuffix, RedirectUriPatternRule, RedirectUriPatternViolation, } from "./redirect-uri.js";