@udibo/oauth2 0.1.0

package/esm/adapters/hono/bff/bff.d.ts

@@ -0,0 +1,852 @@
+/**
+ * Backend-for-Frontend (BFF) adapter for Hono.
+ *
+ * Wraps a {@link DirectClient} configured with a client secret
+ * and exposes the session endpoints a browser SPA talks to:
+ *
+ * - `POST /auth/login` — redirects the browser to the authorize endpoint,
+ *   persisting a per-request state/verifier record and binding its `state` to
+ *   this browser with a short-lived cookie.
+ * - `GET  /auth/callback` — requires the browser to present that binding
+ *   cookie, exchanges the code, opens a session (or, in
+ *   `sessionMode: "shared"`, attaches the tokens to the app's existing
+ *   session), and redirects to the app's `return_to` path.
+ * - `GET|POST /auth/logout` — destroys the session and (best-effort) revokes
+ *   the refresh token upstream. Registered for both methods because the
+ *   shipped React client navigates the browser here (a GET).
+ * - `GET  /auth/session` — returns `{ isAuthenticated, user }` from the
+ *   session. **Never** exposes tokens to the browser.
+ * - `POST /auth/backchannel` — OIDC Back-Channel Logout receiver, mounted only
+ *   when `backchannelLogout` is configured. A server-to-server call from the OP
+ *   that ends the matching server-side session(s).
+ *
+ * A companion {@link HonoBff.attachToken} middleware reads the session
+ * cookie, looks up / refreshes the access token, and sets
+ * `Authorization: Bearer <token>` on the inbound request so a co-located
+ * resource-server adapter can validate it normally — all in-process, no
+ * outbound HTTP.
+ *
+ * The credentialed surface is **CSRF-protected by default**: a request that
+ * carries the session cookie must also carry a custom `x-csrf` header (the
+ * shipped `BffClient` and React adapter send it automatically), and the
+ * `GET /auth/logout` navigation — which cannot carry one, and is what the
+ * shipped client uses — is guarded by a same-origin check that fails closed.
+ * `POST /auth/logout` is the stronger path to adopt. See
+ * {@link HonoBffCsrfOptions}; pass `csrf: false` to disable.
+ *
+ * Sign-in itself is bound to the browser that started it, and that binding is
+ * **not** configurable: `/auth/login` records the `state` it minted in a
+ * short-lived `HttpOnly` `SameSite=Lax` cookie, and `/auth/callback` refuses
+ * any authorization response whose `state` that cookie does not vouch for. A
+ * pending authorization is therefore never completable from a browser other
+ * than the one that began it, whatever
+ * {@link HonoBffOptions.authRequestStorage} it is kept in — without it an
+ * attacker could start a sign-in and hand the victim the callback URL to log
+ * the victim into the attacker's account.
+ *
+ * @module
+ */
+import { Hono } from "hono";
+import type { Context, Handler, MiddlewareHandler } from "hono";
+import type { DirectClient, TokenBundle, UserInfoClaims } from "../../../client/mod.js";
+import type { ClientInterface } from "../../../models/client.js";
+import type { AbstractScope, BasicScope } from "../../../models/scope.js";
+import type { HonoAuthorizationServer } from "../authorization-server.js";
+import type { HonoResourceServer } from "../resource-server.js";
+import type { AuthRequestStorageFactory } from "./auth-request-store.js";
+import { type SessionStore } from "./session-store.js";
+import { type HonoBffProxyOptions } from "./proxy.js";
+/**
+ * A resource server the BFF can compose with `attachToken()` to expose a
+ * single `bff.protect()` middleware.
+ *
+ * Accepted in two shapes so both deployment topologies stay symmetric:
+ *
+ * - **Own-issuer** (the Udibo case): pass a {@link HonoAuthorizationServer}.
+ *   `protect()` validates against the same in-process token service the
+ *   issuer uses — no introspection round-trip.
+ * - **Third-party-issuer**: pass a {@link HonoResourceServer} configured
+ *   with `IntrospectionTokenReader`. `protect()` validates via RFC 7662
+ *   against the upstream.
+ */
+export type HonoBffResourceServer<Client extends ClientInterface = any, User = any, S extends AbstractScope = BasicScope> = HonoResourceServer<Client, User, S> | HonoAuthorizationServer<Client, User, S>;
+/**
+ * Cookie settings for the BFF session cookie. Defaults follow the IETF
+ * "OAuth 2.0 for Browser-Based Apps" BCP §6.1.3.2: `Secure`, `HttpOnly`,
+ * `SameSite=Strict`, `Path=/`, no `Domain`, and the `__Host-` name prefix.
+ *
+ * The **default** name is prefix-aware: it carries `__Host-` only when every
+ * attribute that prefix requires holds, and falls back to the bare name
+ * otherwise. An **explicit** {@link name} whose prefix contradicts the other
+ * attributes throws from the {@link HonoBff} constructor instead of emitting a
+ * cookie every browser silently drops.
+ */
+export interface HonoBffCookieOptions {
+    /**
+     * Cookie name. Defaults to `"__Host-oauth2_session"` (the BCP `__Host-`
+     * prefix) when the other options satisfy that prefix — {@link secure} on,
+     * {@link path} `"/"`, and no {@link domain} — and to `"oauth2_session"`
+     * otherwise, because a browser rejects a `__Host-` cookie that breaks any of
+     * them.
+     *
+     * Setting this explicitly to a `__Host-` or `__Secure-` prefixed name throws
+     * from the {@link HonoBff} constructor when the other options contradict the
+     * prefix. Prefixes are matched case-insensitively, as browsers match them.
+     */
+    name?: string;
+    /**
+     * Cookie path. Defaults to `"/"`. Any other value drops the default
+     * `__Host-` prefix, which requires `Path=/`.
+     */
+    path?: string;
+    /**
+     * Marks the cookie Secure. Defaults to `true`. Turning it off drops the
+     * default `__Host-` prefix, which requires `Secure`.
+     */
+    secure?: boolean;
+    /** Marks the cookie HttpOnly. Defaults to `true`. */
+    httpOnly?: boolean;
+    /**
+     * SameSite attribute. Defaults to `"Strict"` (per the BCP). Use `"Lax"` if
+     * you run `sessionMode: "shared"` with a cross-origin IDP, so the cookie
+     * survives the cross-site callback return.
+     *
+     * `"None"` requires {@linkcode HonoBffCookieOptions.secure}; the constructor
+     * throws on the combination rather than emitting a cookie every modern
+     * browser silently drops.
+     */
+    sameSite?: "Lax" | "Strict" | "None";
+    /**
+     * Optional cookie domain. The BCP recommends omitting it (host-bound).
+     * Setting it drops the default `__Host-` prefix, which forbids `Domain`.
+     */
+    domain?: string;
+    /**
+     * `Max-Age` in seconds, for the **cookie only**. Defaults to
+     * {@linkcode HonoBffOptions.sessionMaxAgeMs}, so the browser keeps the
+     * cookie exactly as long as the session behind it is honored.
+     *
+     * Set it to lengthen the cookie past the session (harmless: the session ends
+     * first and the stale cookie is cleared). Setting it **shorter** than the
+     * session lifetime throws from the {@link HonoBff} constructor — that is the
+     * pairing where the browser drops the cookie while the session stays active
+     * and listed.
+     *
+     * Pass `"session"` for a true session cookie (no `Max-Age`, gone when the
+     * browser closes). The server-side bound still applies, so the two agree:
+     * an ephemeral cookie shortens the window, it never unbounds the session.
+     */
+    maxAge?: number | "session";
+}
+/**
+ * CSRF defense for the BFF's credentialed surface.
+ *
+ * The BFF's session cookie is an ambient credential the browser attaches
+ * automatically, so a cross-site page can trigger credentialed requests
+ * (classic CSRF). The defense (as used by Duende.BFF's `X-CSRF` and Curity's
+ * `token-handler-version` headers) requires a **custom request header** on the
+ * fetch-driven surface: a custom header makes the request "non-simple", forcing
+ * a CORS preflight that an untrusted origin cannot satisfy, so the browser never
+ * attaches the cookie. The shipped `BffClient` (and therefore the React
+ * adapter) sends this header automatically.
+ *
+ * Enforced only when the session cookie is actually present (an anonymous
+ * request has nothing to abuse). Applies to `GET /auth/session`, the
+ * `POST /auth/logout` path, and {@link HonoBff.protect} / {@link HonoBff.attachToken}'s
+ * cookie path.
+ *
+ * `POST /auth/logout` is the **preferred** sign-out path because it is covered
+ * by that header check. The `GET /auth/logout` navigation cannot carry a custom
+ * header, so it is guarded instead by a same-origin check that reads
+ * `Sec-Fetch-Site` (accepting only `same-origin` and `none`) and falls back to
+ * comparing `Origin`, else `Referer`, for clients that send no fetch metadata.
+ * `same-site` is rejected along with `cross-site`, so a `GET` logout link
+ * followed from a sibling subdomain does not pass. That check **fails closed**:
+ * a request carrying none of the three signals is rejected. Two residuals come
+ * with it. A `GET` logout link followed from a no-referrer page on a browser too
+ * old to send `Sec-Fetch-Site` stops working. And because
+ * `Sec-Fetch-Site: none` survives redirects by design (W3C Fetch Metadata §4.1),
+ * a navigation with no browser initiator — the address bar, a bookmark, or a
+ * link opened from a native app such as an email client — that redirects into
+ * the `GET` route still passes.
+ *
+ * **Both residuals apply to the shipped client today**, which signs out by
+ * navigating the browser to `GET /auth/logout` (`BffClient.logout()` returns
+ * the URL and the React adapter assigns it to `location`). `POST` is the path
+ * to **adopt**, not one you already get: wire your sign-out control to post to
+ * this route with the `x-csrf` header if a forgeable `GET` sign-out matters to
+ * you.
+ *
+ * Pass `csrf: false` to disable (e.g. an example whose page uses hand-written
+ * `fetch` for readability, or an app that has not yet migrated its call sites).
+ */
+export interface HonoBffCsrfOptions {
+    /**
+     * Header name required on credentialed fetch requests. Defaults to `"x-csrf"`.
+     * Matched case-insensitively.
+     */
+    headerName?: string;
+    /**
+     * If set, the header must equal this value. Otherwise any non-empty value is
+     * accepted — presence is what forces the CORS preflight. Defaults to presence.
+     */
+    headerValue?: string;
+}
+/** Paths for the session endpoints mounted by {@link HonoBff.routes}. */
+export interface HonoBffPaths {
+    /**
+     * The base the caller mounts {@link HonoBff.routes} under — stripped from
+     * the paths below so each handler registers at the right sub-path. Defaults
+     * to `/auth`, matching the default paths and the documented
+     * `app.route("/auth", bff.routes())`.
+     *
+     * Set it whenever you move the surface: with
+     * `basePath: "/session", login: "/session/login"` the router registers
+     * `/login`, so `app.route("/session", bff.routes())` serves
+     * `/session/login`. Pass `""` to mount the paths verbatim at the app root.
+     *
+     * A trailing slash is ignored. Unless it is `""`, **every path that gets
+     * mounted must sit strictly under it** (`${basePath}/…`) — the constructor
+     * throws otherwise, because `routes()` strips the base to mount each handler
+     * while {@link HonoBff.loginContinuation} and the session probe's `logoutUrl`
+     * hand out the unstripped paths, so a stray path would be served at one URL
+     * and advertised at another. {@link HonoBffPaths.backchannel} is exempt
+     * unless {@link HonoBffOptions.backchannelLogout} is configured, since
+     * `routes()` mounts it only then.
+     */
+    basePath?: string;
+    /** Where the browser is sent to begin sign-in. Defaults to `/auth/login`. */
+    login?: string;
+    /** Redirect target the IDP returns to after authorization. Defaults to `/auth/callback`. */
+    callback?: string;
+    /** Ends the session and clears the cookie. Defaults to `/auth/logout`. */
+    logout?: string;
+    /** Probed by the SPA for `{ isAuthenticated, user }`. Defaults to `/auth/session`. */
+    session?: string;
+    /** OIDC Back-Channel Logout receiver. Defaults to `/auth/backchannel`. */
+    backchannel?: string;
+}
+/**
+ * The subject / OP-session-id a validated OIDC `logout_token` says to log out.
+ * Returned by {@link HonoBffBackchannelOptions.verifyLogoutToken}.
+ */
+export interface BackchannelLogoutSubject {
+    /** The `sub` claim — log out all of the subject's sessions when no `sid`. */
+    sub?: string;
+    /** The `sid` claim — log out only the session with this OP session id. */
+    sid?: string;
+}
+/**
+ * OIDC Back-Channel Logout configuration. When set, {@link HonoBff.routes}
+ * mounts a `POST /auth/backchannel` receiver.
+ *
+ * **Signature verification is yours.** The package stays dependency-free, so you
+ * supply `verifyLogoutToken`: verify the JWT's signature (against the OP's JWKS,
+ * e.g. with `jose`, or in-process for a co-located IDP) **and** its claims
+ * (`iss`, `aud`, `iat`, `exp`, the required `events` member
+ * `http://schemas.openid.net/event/backchannel-logout`, `sub`/`sid` presence,
+ * `nonce` absence, and `jti` replay), then return the `{ sub, sid }` to log out.
+ * Throw or return `null` to reject (the receiver responds `400`).
+ *
+ * Requires a {@link SessionStore} that implements `destroyByLogout`
+ * (the in-memory and DB-backed stateful stores do; the stateless encrypted
+ * cookie store cannot — construction throws if the store can't support it).
+ */
+export interface HonoBffBackchannelOptions {
+    /**
+     * Verifies a raw `logout_token` JWT (signature and claims) and returns the
+     * `{ sub, sid }` to log out. Throw or return `null` to reject the request.
+     */
+    verifyLogoutToken: (logoutToken: string) => Promise<BackchannelLogoutSubject | null> | BackchannelLogoutSubject | null;
+}
+/**
+ * Why `/auth/callback` could not complete a sign-in. Passed to
+ * {@link HonoBffOptions.onCallbackError} so the app can render or redirect to a
+ * friendly page instead of the default JSON.
+ */
+export interface BffCallbackError {
+    /**
+     * OAuth2-style error code: the IDP's `error` (e.g. `access_denied`),
+     * `invalid_request` (missing `code`/`state`, or a `state` this browser never
+     * started — see {@link HonoBffOptions.loginStateTtlMs}), or `invalid_grant`
+     * (the code exchange failed — expired/replayed code, unknown `state`).
+     */
+    error: string;
+    /** Human-readable description; never contains secrets. */
+    error_description: string;
+    /** The thrown cause for the `invalid_grant` (exchange) case; otherwise `undefined`. */
+    cause?: unknown;
+}
+/** Options accepted by the {@link HonoBff} constructor. */
+export interface HonoBffOptions {
+    /**
+     * OAuth2 client for the authorization server, constructed with a
+     * `clientSecret`. The BFF drives the flows through its
+     * `exchangeAuthorizationCode` / `exchangeRefreshToken` primitives; tokens
+     * are stored in {@link HonoBffOptions.sessionStore} — **not** in the
+     * client's token storage.
+     */
+    client: DirectClient;
+    /**
+     * Where session data lives. Defaults to {@link MemorySessionStore},
+     * which is fine for dev and tests but must be replaced for production.
+     */
+    sessionStore?: SessionStore;
+    /**
+     * How long a BFF session is meant to live, in milliseconds. Defaults to 14
+     * days ({@link DEFAULT_SESSION_MAX_AGE_MS}). Milliseconds match the store's
+     * `maxAgeMs` and `loginStateTtlMs`; `cookie.maxAge` stays in seconds because
+     * that is the unit of the HTTP `Max-Age` attribute it sets.
+     *
+     * This is the **one** place the lifetime is stated. It sets the session
+     * cookie's `Max-Age` (see {@linkcode HonoBffCookieOptions.maxAge}) and, in
+     * the default `sessionMode: "own"`, it is enforced on every read: a session
+     * older than this is destroyed and its cookie cleared, so the cookie and the
+     * record behind it can never disagree about whether the user is signed in.
+     * Measured from `createdAt`, so it caps the session absolutely rather than
+     * rolling forward with each token refresh. A store that does not persist
+     * `createdAt` therefore opts its sessions out of this cap entirely — they
+     * never age out. `runSessionStoreContractTests` pins that round-trip, so run
+     * it against any store you write.
+     *
+     * Applies in the default `sessionMode: "own"` only. In
+     * `sessionMode: "shared"` the app owns the session record and its cookie's
+     * lifetime — often per session (remember-me vs ephemeral) — so this value is
+     * ignored there: the BFF writes only an explicit {@linkcode
+     * HonoBffCookieOptions.maxAge}, or an ephemeral cookie the app re-stamps.
+     *
+     * A store that advertises its own bound (see `BoundedSessionStore`, which
+     * {@linkcode EncryptedCookieSessionStore} implements) is cross-checked at
+     * construction: if the cookie would die before that store stops honoring the
+     * session, the constructor throws instead of shipping the mismatch.
+     */
+    sessionMaxAgeMs?: number;
+    /**
+     * Where the pending authorization request (`state` → PKCE verifier,
+     * return-to) lives, resolved per request. Defaults to the client's
+     * configured `authRequestStorage`, which is in-memory unless the client was
+     * given something else — fine for a single long-lived process, wrong for any
+     * platform that can serve `/auth/login` and `/auth/callback` from different
+     * isolates. Pass an {@link EncryptedCookieAuthRequestStorage} to carry the
+     * record in an encrypted cookie instead, or implement
+     * {@link AuthRequestStorageFactory} over storage of your own.
+     *
+     * Whatever this resolves to, the pending request is **also** bound to the
+     * browser that started it by the login-state cookie, which no option turns
+     * off. See {@link loginStateTtlMs}.
+     */
+    authRequestStorage?: AuthRequestStorageFactory;
+    /**
+     * How long, in ms, the browser keeps the login-state cookie `/auth/login`
+     * sets and `/auth/callback` requires — the `Max-Age` on that cookie, and so
+     * the window a started sign-in can still be completed in. Defaults to 10
+     * minutes, matching `DirectClient`'s `authRequestTtlMs` default; raise both
+     * together, since whichever expires first ends the pending sign-in.
+     *
+     * The cookie holds only SHA-256 hashes of the `state` values (the three most
+     * recent, so parallel sign-ins in several tabs all stay completable), is
+     * `HttpOnly`, `SameSite=Lax` — the strictest value that survives the
+     * identity provider's redirect back — and inherits {@link cookie}'s
+     * `secure` / `path` / `domain` so plain-HTTP local development works.
+     */
+    loginStateTtlMs?: number;
+    /**
+     * Who owns the BFF's session record. Defaults to `"own"`.
+     *
+     * - `"own"` (default): the BFF creates and owns its session at
+     *   `/auth/callback` — it always mints a fresh id (`sessionStore.create`)
+     *   and ignores any inbound cookie. Use when the app has no session here
+     *   until the OAuth flow completes: standalone BFFs, or apps whose login
+     *   lives on a separate / external IDP.
+     * - `"shared"`: the app already created the session at its own login step,
+     *   and the BFF **attaches** tokens to that existing session at
+     *   `/auth/callback` (via `sessionStore.update`) instead of creating its
+     *   own. Set {@link HonoBffCookieOptions.name} to the app's session-cookie
+     *   name and back `sessionStore` with the app's session record. Use for a
+     *   colocated first-party SPA that is also its own IDP, so the user has
+     *   **one** session (login + tokens on one record), not two. If no session
+     *   cookie is present at the callback the BFF falls back to creating one.
+     *   `/auth/logout` destroys the whole shared session (a full sign-out).
+     *   The app's cookie stays the app's: the BFF emits `Set-Cookie` only when
+     *   the store hands back a **different** value (a stateless store does on
+     *   every write), never to re-stamp an unchanged one — re-stamping would
+     *   replace the attributes the app chose, turning a remember-me cookie
+     *   with a `Max-Age` into a session cookie the browser drops on exit.
+     *
+     * Note on session fixation: this is the standard "renew the session id on
+     * authentication" control. In `"own"` mode the BFF performs the renewal
+     * (fresh id at the callback). In `"shared"` mode that responsibility sits
+     * with your login step — use a login that mints a fresh session id on
+     * success (the typical behavior, e.g. a session service that generates a
+     * new id per login) so a pre-planted cookie can't survive authentication.
+     */
+    sessionMode?: "own" | "shared";
+    /** Cookie attribute tweaks. */
+    cookie?: HonoBffCookieOptions;
+    /**
+     * CSRF defense for the credentialed surface. Enabled by default with a
+     * `"x-csrf"` header requirement; pass `false` to disable, or an object to
+     * customize the header. See {@link HonoBffCsrfOptions}.
+     */
+    csrf?: HonoBffCsrfOptions | false;
+    /**
+     * OIDC RP-Initiated Logout. When `true` **and** the configured client knows
+     * an end-session endpoint (`endpoints.endSession`, or via discovery),
+     * `/auth/logout` — after destroying the local session — additionally
+     * redirects the browser to the OP's `end_session_endpoint` with
+     * `id_token_hint` (the session's id_token, if any) and a
+     * `post_logout_redirect_uri` built from the resolved origin + the
+     * open-redirect-guarded `return_to`. This ends the upstream IDP SSO session,
+     * not just the local BFF session.
+     *
+     * Defaults to `false` (local logout only): not every IDP supports it, and it
+     * adds a redirect hop. When enabled but no end-session endpoint is known,
+     * logout falls back to the plain local redirect and warns once via
+     * `console.warn` — a client built from an explicit `endpoints` object with no
+     * `endSession` and no `issuer` can never learn one by discovery, so the
+     * feature would otherwise no-op silently.
+     */
+    rpInitiatedLogout?: boolean;
+    /**
+     * OIDC Back-Channel Logout. When set, `routes()` mounts a
+     * `POST /auth/backchannel` receiver that ends the matching server-side
+     * session(s) when the OP notifies it. See {@link HonoBffBackchannelOptions}.
+     */
+    backchannelLogout?: HonoBffBackchannelOptions;
+    /** Endpoint paths (within whatever base the caller mounts this under). */
+    paths?: HonoBffPaths;
+    /**
+     * Scope string requested at `/auth/login`, and the scope the login flow
+     * records for the authorization request it started.
+     *
+     * Server-chosen: a browser cannot change it by putting `scope` on the login
+     * URL. An application that wants the browser to choose lists `scope` in
+     * {@link forwardedParams}, and a forwarded value then **replaces** this one
+     * rather than narrowing it. An empty forwarded value counts as none
+     * supplied, so this value stands: a login link ending `?scope=` would
+     * otherwise send no `scope` at all, leaving an authorization server that
+     * defaults an absent scope to pick the grant instead.
+     */
+    scope?: string;
+    /**
+     * Extra parameters added to every authorize request `/auth/login` builds —
+     * `login_hint`, `ui_locales`, `acr_values`, or whatever else the
+     * authorization server accepts, such as a parameter naming the organization
+     * a sign-in should land in.
+     *
+     * Server-chosen: these values are fixed when the BFF is constructed, so they
+     * carry the same trust as {@link scope} and nothing a browser sends can
+     * change them. When the browser is the one that should choose a parameter's
+     * value, name it in {@link forwardedParams} instead.
+     *
+     * `prompt` is an ordinary name here — pin `{ prompt: "login" }` to make
+     * every sign-in re-authenticate. A pinned `scope` is accepted only when
+     * {@link scope} is unset; setting both would leave which one applies
+     * ambiguous. Either configuration supplies the scope the login flow records
+     * for its authorization request.
+     *
+     * A name the login flow reserves is refused at construction rather than
+     * quietly dropped — {@link forwardedParams} carries the list and the reason.
+     *
+     * @example Pin every sign-in to one organization
+     * ```ts
+     * declare const client: DirectClient;
+     *
+     * const bff = new HonoBff({ client, extraParams: { organization: "acme" } });
+     * ```
+     */
+    extraParams?: Record<string, string>;
+    /**
+     * Names of extra authorize parameters `/auth/login` may take off its own
+     * query string. Empty by default, so a parameter that is not listed here is
+     * not forwarded no matter who puts it on the login URL — `scope` and
+     * `prompt` included. `routes()` serves login at `GET` and `POST` alike, and
+     * both read the query string only, never a request body.
+     *
+     * Browser-chosen, and so untrusted: whatever a browser puts in
+     * `/auth/login?<name>=…` reaches the authorization server verbatim, and the
+     * BFF checks nothing but the name. The test to apply is not "does the
+     * authorization server validate this parameter" but **"would I accept every
+     * value it could carry"** — the two are different properties, and a
+     * parameter can pass the first and fail the second. `acr_values` and
+     * `max_age` are refused here, case-insensitively, because browser choices
+     * could weaken assurance or lengthen the re-authentication window. Pin these
+     * controls in {@link extraParams}, which no browser can change.
+     *
+     * A parameter already baked into the configured authorization endpoint's
+     * own query string is overridable this way too, and silently: the client
+     * keeps that query string and then sets each extra parameter over it. The
+     * reserved list below cannot know a name a deployment baked into its
+     * endpoint URL, so check that URL before listing anything here.
+     *
+     * Reserved on this option and on {@link extraParams} alike, and refused when
+     * the BFF is constructed — matched case-insensitively, since an
+     * authorization server that folds parameter-name case would otherwise make
+     * `Client_Id` a way around the list:
+     *
+     * - `response_type`, `client_id`, `redirect_uri`, `state`,
+     *   `code_challenge`, `code_challenge_method` — the client mints or derives
+     *   each one for the single sign-in in progress, and a supplied value
+     *   replaces it, which variously redirects the authorization code, breaks
+     *   the PKCE binding the token exchange depends on, or unpicks the `state`
+     *   the login-state cookie commits to.
+     * - `response_mode` — moves the authorization response out of the callback
+     *   URL's query string, the only place `/auth/callback` reads it from.
+     * - `nonce` — this client neither sends nor verifies one, so a supplied
+     *   value would look like replay protection that nothing checks.
+     * - `request`, `request_uri` — a request object supersedes the parameters
+     *   beside it at an authorization server implementing RFC 9101, which puts
+     *   every name above back within reach.
+     *
+     * Naming the same parameter both here and in {@link extraParams} is refused
+     * as well: one pins the value every sign-in carries and the other lets the
+     * browser choose it, so which one applies would be ambiguous.
+     *
+     * `scope` and `prompt` are ordinary names on this option, and the two worth
+     * the most thought before listing. Listing `scope` lets whoever writes the
+     * login link choose the breadth of the grant the session is minted with:
+     * the value replaces {@link scope} rather than narrowing it, bounded only
+     * by what the authorization server will grant this client. An empty `scope`
+     * is the one exception, and counts as absent so {@link scope} stands.
+     * Listing `prompt` hands over the authentication ceremony instead of the
+     * grant — it is what a SPA needs to start a silent renew with
+     * `/auth/login?prompt=none`, and the same entry lets a link suppress a
+     * re-authentication the application meant to force. Where the deployment should decide either one, use
+     * {@link scope} or a pinned {@link extraParams} entry, which no browser can
+     * reach.
+     *
+     * @example Let a sign-in link choose the organization
+     * ```ts
+     * declare const client: DirectClient;
+     *
+     * const bff = new HonoBff({ client, forwardedParams: ["organization"] });
+     * ```
+     *
+     * A link to `/auth/login?organization=acme&return_to=/dashboard` then
+     * reaches the authorization server as `…&organization=acme`.
+     */
+    forwardedParams?: readonly string[];
+    /** Default `return_to` applied when the browser doesn't pass one. */
+    defaultReturnTo?: string;
+    /**
+     * Optional hook run after the authorization code is exchanged. Lets
+     * apps enrich the session with database-backed user info before the
+     * session cookie is set.
+     */
+    resolveUser?: (tokens: TokenBundle, idTokenClaims: UserInfoClaims | null) => Promise<UserInfoClaims | null> | UserInfoClaims | null;
+    /**
+     * Optional hook invoked when `/auth/callback` cannot complete the sign-in
+     * (see {@link BffCallbackError} for the cases). The browser reaches the
+     * callback via a full-page navigation, so the default JSON `400` is not
+     * user-friendly — return a redirect to a sign-in/error page instead, e.g.
+     * `c.redirect(`/sign-in?error=${err.error}`)`. When omitted, the BFF responds
+     * with a `400` JSON body `{ error, error_description }`.
+     */
+    onCallbackError?: (c: Context, error: BffCallbackError) => Response | Promise<Response>;
+    /**
+     * Clock skew (seconds) applied when deciding whether the access token
+     * is close enough to expiry that {@link HonoBff.attachToken} should
+     * refresh proactively. Defaults to 30s.
+     */
+    refreshSkewSeconds?: number;
+    /**
+     * Optional resource server. When provided, {@link HonoBff.protect}
+     * becomes available — a single middleware that composes
+     * {@link HonoBff.attachToken} with `resourceServer.protect(scope)`.
+     *
+     * Pass a {@link HonoAuthorizationServer} for own-issuer co-located
+     * deployments (validation happens against the in-process token service)
+     * or a {@link HonoResourceServer} for third-party-issuer deployments
+     * (validation goes through `IntrospectionTokenReader`).
+     */
+    resourceServer?: HonoBffResourceServer;
+    /**
+     * Resolves the per-request origin (scheme + host) used to build the
+     * browser-facing authorize URL and `redirect_uri`. Lets ONE build-once BFF
+     * serve every deployment host (preview URLs, multi-tenant subdomains): the
+     * configured client's authorize/redirect paths are retargeted at this
+     * origin per request. Return only allowlisted/trusted origins (never a raw
+     * forged `Host`). When omitted, the client's configured origin is used.
+     */
+    resolveOrigin?: (c: Context) => string;
+    /**
+     * Derive the OAuth2 `redirect_uri` from the mounted callback path instead of
+     * requiring it in the client config. When `true`, every login/callback uses
+     * `redirect_uri = <origin><callback path>` (origin from {@link resolveOrigin},
+     * else the request's). The same value is sent at authorize and at the token
+     * exchange (RFC 6749 §4.1.3), re-derived from the request each time. Pairs
+     * with an `issuer`-configured client (discovery) for a BFF you configure by
+     * issuer alone — no restated endpoints or redirect URI. Defaults to `false`
+     * (use the client's configured `redirectUri`).
+     */
+    deriveRedirectUri?: boolean;
+}
+/**
+ * Backend-for-Frontend adapter for Hono. Construct once per app, mount
+ * `routes()` under `/auth`, and use `attachToken()` as middleware on
+ * protected API routes. Apps that own their login surface (a custom sign-in
+ * form, create-account, forgot-password) call `loginContinuation()` to hand
+ * back to the OAuth2 flow after authenticating a user.
+ */
+export declare class HonoBff {
+    #private;
+    /**
+     * Defaults are applied for the session store ({@linkcode MemorySessionStore}),
+     * session mode (`"own"`), cookie name, and CSRF.
+     *
+     * @throws {Error} When {@linkcode HonoBffOptions.backchannelLogout} is
+     * configured against a store that cannot enumerate sessions (e.g.
+     * {@linkcode EncryptedCookieSessionStore}), when an explicit
+     * {@linkcode HonoBffCookieOptions.name} carries a `__Host-`/`__Secure-`
+     * prefix the other cookie options contradict, when
+     * {@linkcode HonoBffCookieOptions.sameSite} is `"None"` without
+     * {@linkcode HonoBffCookieOptions.secure}, when any
+     * {@linkcode HonoBffPaths} entry falls outside a non-empty
+     * {@linkcode HonoBffPaths.basePath}, when the session cookie would die
+     * before the session behind it (see
+     * {@linkcode HonoBffOptions.sessionMaxAgeMs}), or when
+     * {@linkcode HonoBffOptions.extraParams} or
+     * {@linkcode HonoBffOptions.forwardedParams} names a reserved authorize
+     * parameter, gives one a name that is empty or not equal to its trimmed
+     * form (`" state"` and `"organization "` are refused rather than trimmed),
+     * names the same parameter in both, or pins `scope` in
+     * {@linkcode HonoBffOptions.extraParams} while
+     * {@linkcode HonoBffOptions.scope} is also set.
+     */
+    constructor(options: HonoBffOptions);
+    /**
+     * Cookie name used for the session cookie. Read-only; configured via
+     * {@link HonoBffOptions.cookie}.
+     */
+    get cookieName(): string;
+    /**
+     * Name of the cookie `/auth/login` binds the pending sign-in's `state` to
+     * and `/auth/callback` requires. Read-only; derived from
+     * {@link HonoBffOptions.cookie}'s `secure` / `path` / `domain` (it carries
+     * the `__Host-` prefix whenever they allow it). A test that drives the
+     * login flow by hand must carry this cookie from the login response into
+     * the callback request, exactly as a browser would.
+     */
+    get loginStateCookieName(): string;
+    /**
+     * The CSRF header name required on credentialed requests, or `undefined`
+     * when CSRF is disabled. Useful in tests that seed a session and then call a
+     * protected route — they must send `{ [bff.csrfHeaderName!]: "1" }` alongside
+     * the cookie. The shipped `BffClient` / React adapter send it
+     * automatically in real apps.
+     */
+    get csrfHeaderName(): string | undefined;
+    /**
+     * The underlying session store. Exposed primarily for testing helpers
+     * (e.g. seeding a session directly without driving the login flow);
+     * production code should not reach in here.
+     */
+    get sessionStore(): SessionStore;
+    /**
+     * Returns a Hono app with all session endpoints mounted, each registered
+     * relative to {@link HonoBffPaths.basePath} (default `/auth`). Mount it under
+     * that same base — `app.route("/auth", bff.routes())` — so the served URLs
+     * are the configured {@link HonoBffPaths}. To mount at the app root instead,
+     * set `paths.basePath` to `""`.
+     */
+    routes(): Hono;
+    /**
+     * Builds the URL that (re)starts sign-in toward `returnTo`, for an app that
+     * owns its login surface (a custom sign-in form, create-account,
+     * forgot-password) and needs to hand back to the OAuth2/BFF flow after it
+     * authenticates the user.
+     *
+     * - When `returnTo` is an **in-flight authorize URL** — its path matches the
+     *   client's authorization endpoint, i.e. the user was bounced to your login
+     *   surface mid-authorize with the PKCE `state` already minted — it is
+     *   returned unchanged so the flow **resumes** without a redundant
+     *   `/auth/login` hop.
+     * - Otherwise it returns `${login}?return_to=<returnTo>` so the BFF **starts**
+     *   a fresh login (mints `state` at the login endpoint, attaches tokens to the
+     *   session at the callback).
+     *
+     * `returnTo` is open-redirect-guarded (`safeReturnTo`), so the result is
+     * always a safe same-origin path. This is the mechanism of the own-auth + BFF
+     * topology; the credential form, validation, and copy stay in your app. It
+     * replaces hand-rolled helpers that hardcode the authorize + login paths —
+     * the BFF already knows both from its client config and `paths`.
+     *
+     * ```ts
+     * // after your sign-in / create-account action authenticates the user:
+     * return c.redirect(bff.loginContinuation(returnTo));
+     * ```
+     *
+     * Note: the in-flight-authorize check needs the client's authorization
+     * endpoint to be known synchronously (an explicit `endpoints.authorization`,
+     * or after `client.discover()` has run). For an issuer-only client that has
+     * not discovered yet, every `returnTo` is treated as "start a fresh login".
+     */
+    loginContinuation(returnTo: string | null | undefined): string;
+    /**
+     * Login handler — builds the authorize URL, binds the `state` it minted to
+     * this browser with the login-state cookie, and redirects the browser.
+     *
+     * The authorize request carries every {@link HonoBffOptions.extraParams}
+     * entry, plus each {@link HonoBffOptions.forwardedParams} name this
+     * request's query string supplies a value for. Nothing else off this
+     * request's query string reaches the authorize URL: `scope` falls back to
+     * {@link HonoBffOptions.scope} and `prompt` is sent only when one of those
+     * two options supplies it.
+     */
+    loginHandler(): Handler;
+    /**
+     * Callback handler — requires the login-state cookie to vouch for the
+     * returned `state`, then exchanges the code and opens a session.
+     */
+    callbackHandler(): Handler;
+    /** Logout handler — revokes the refresh token and clears the session cookie. */
+    logoutHandler(): Handler;
+    /** Session probe — returns `{ isAuthenticated, user }` without tokens. */
+    sessionHandler(): Handler;
+    /**
+     * OIDC Back-Channel Logout receiver. A server-to-server `POST` from the OP
+     * carrying a signed `logout_token`; the configured verifier validates it (and
+     * returns the subject / OP session id), then the matching server-side
+     * session(s) are destroyed. Responds `200` on success and `400` on a
+     * missing/invalid token, with `Cache-Control: no-store`, per the spec.
+     */
+    backchannelHandler(): Handler;
+    /**
+     * Middleware that reads the session cookie, refreshes the access token
+     * if it's near expiry, and sets `Authorization: Bearer <token>` on the
+     * inbound request so downstream middleware can read it from the
+     * standard header.
+     *
+     * Prefer {@link protect} for the common case — it authenticates against
+     * the configured `resourceServer` directly without mutating the
+     * request, so middleware ordering doesn't matter. Reach for
+     * `attachToken` only when composing with downstream middleware that
+     * expects a bearer token in the `Authorization` header (e.g. a custom
+     * resource-server-like guard, or an in-process proxy).
+     *
+     * **Ordering caveat**: mount `attachToken` *before* any middleware
+     * that reads the request body (CSRF parsers, validators, etc.).
+     * `attachToken` replaces `c.req.raw` with a clone that carries the
+     * Authorization header, which transfers the body stream from the
+     * original Request to the clone. Downstream middleware that reads
+     * through `c.req` is fine; middleware that captured a pre-clone
+     * reference to `c.req.raw` will see a "used" body on it.
+     *
+     * Unauthenticated requests fall through without a header — the
+     * downstream guard returns the proper 401 with `WWW-Authenticate`.
+     */
+    attachToken(): MiddlewareHandler;
+    /**
+     * Returns a Hono middleware that asserts an **already-authenticated**
+     * request (guarded upstream by {@link protect}) carries `requiredScope`,
+     * **without** re-validating the token — the per-route companion to
+     * `protect` for mounts whose routes need different scopes (e.g. `read` vs
+     * `write`). Delegates to the configured resource server's `requireScope`;
+     * see {@link HonoResourceServer.requireScope}.
+     *
+     * @throws {Error} When the BFF was constructed without a `resourceServer` —
+     * thrown when the middleware is built, not per request.
+     *
+     * @example
+     * ```ts
+     * app.use("/api/*", bff.protect()); // session cookie OR bearer
+     * app.get("/api/items", bff.requireScope("read"), list);
+     * app.post("/api/items", bff.requireScope("write"), create);
+     * ```
+     */
+    requireScope(requiredScope: string): MiddlewareHandler;
+    /**
+     * Middleware that authenticates the request against the configured
+     * `resourceServer`, accepting **either** auth style so one guard protects an
+     * API used by both the BFF's own frontend and machine-to-machine clients:
+     *
+     * - **Browser frontend** — no `Authorization` header; the access token is
+     *   resolved from the BFF session cookie (refreshed if near expiry) and
+     *   validated. Available only when the BFF was constructed with a
+     *   `resourceServer` option.
+     * - **Machine-to-machine** — an inbound `Authorization: Bearer <token>` is
+     *   validated directly (e.g. a `client_credentials` token), so direct API
+     *   clients work without a session cookie.
+     *
+     * Unlike `attachToken + resourceServer.protect()`, this does **not**
+     * mutate `c.req.raw` for the session path — the token is read from the
+     * session and handed to `resourceServer.authenticate()` directly, so
+     * middleware ordering doesn't matter and earlier middleware that already
+     * touched the request body is unaffected.
+     *
+     * ```ts
+     * app.use("/api/*", bff.protect("read")); // session cookie OR bearer token
+     * ```
+     *
+     * Without `resourceServer` configured, throws an error with a hint to
+     * either pass `resourceServer` or compose the middleware chain manually
+     * (`app.use(bff.attachToken(), resourceServer.protect(scope))`).
+     */
+    protect(requiredScope?: string): MiddlewareHandler;
+    /**
+     * Handler that forwards the request to a **separate** resource server with
+     * the session's access token attached, and streams the response back — the
+     * full-proxy BFF of the IETF "OAuth 2.0 for Browser-Based Apps" BCP §6.1.1.
+     * Tokens stay server-side and the browser only ever talks to its own origin,
+     * so there is no CORS to configure.
+     *
+     * Reach for this when the API lives in another service. When the resource
+     * server is co-located in the same process, {@link protect} is faster and
+     * simpler — it validates in-process with no outbound HTTP.
+     *
+     * Mount it as a catch-all and strip the mount prefix:
+     *
+     * @example
+     * ```ts
+     * app.all(
+     *   "/api/*",
+     *   bff.proxy("https://api.example.com/v1", { stripPrefix: "/api" }),
+     * );
+     * ```
+     *
+     * Semantics:
+     *
+     * - **Session only.** The access token comes from the session cookie
+     *   (refreshed when within {@link HonoBffOptions.refreshSkewSeconds} of
+     *   expiry, exactly as {@link protect} does). An inbound `Authorization`
+     *   header is *not* honored and never forwarded — point machine-to-machine
+     *   clients at the resource server directly. No session is `401`
+     *   `invalid_token`.
+     * - **CSRF.** The same custom-header check the rest of the credentialed BFF
+     *   surface enforces, so mounting a proxy cannot reopen it. See
+     *   {@link HonoBffCsrfOptions}.
+     * - **Retry.** An upstream `401` carrying `error="invalid_token"` triggers
+     *   one refresh-and-retry, when the session has a refresh token. A refresh
+     *   the authorization server rejects clears the session and answers `401`; a
+     *   refresh that merely fails to complete (network error, 5xx, 429) leaves
+     *   the session intact and answers `502` `temporarily_unavailable`. Bodied
+     *   requests are not retried (the body was streamed). Disable with
+     *   `retryOn401: false`.
+     * - **Headers.** Only {@link DEFAULT_PROXY_FORWARD_HEADERS} (or your
+     *   `forwardHeaders`) travel upstream; the session cookie, inbound
+     *   `Authorization`, and hop-by-hop headers never do. Coming back, upstream
+     *   `Set-Cookie` and hop-by-hop headers are dropped and everything else —
+     *   including problem-details error bodies and their status — is passed
+     *   through verbatim.
+     * - **Bodies stream** in both directions; nothing is buffered. Upstream
+     *   redirects are returned to the browser rather than followed, so the token
+     *   is never replayed to a `Location` the BFF did not vet.
+     *
+     * A `502` with `temporarily_unavailable` is returned when the upstream
+     * cannot be reached, and a `400` `invalid_request` when a path segment has a
+     * malformed percent-escape or hides a `..`.
+     *
+     * **Ordering caveat**: mount this before any middleware that reads the
+     * request body — the proxy forwards `c.req.raw.body` as a stream, and a
+     * middleware that already consumed it leaves nothing to forward.
+     *
+     * @param target Upstream base URL. Fixed here, never derived from the
+     * request, so the proxy cannot be steered at another host. Query parameters
+     * pinned on it are merged into every proxied request and win over an inbound
+     * parameter of the same name.
+     * @param options Prefix stripping, header allowlist, retry, and `fetch`
+     * injection. See {@link HonoBffProxyOptions}.
+     * @returns A Hono handler to mount on a catch-all route.
+     */
+    proxy(target: string | URL, options?: HonoBffProxyOptions): Handler;
+}