@udibo/oauth2 0.1.0

package/esm/adapters/hono/bff/bff.js

@@ -0,0 +1,1194 @@
+/**
+ * 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 { deleteCookie, getCookie, setCookie } from "hono/cookie";
+import { InvalidRequestError, InvalidTokenError, isOAuth2Error, TemporarilyUnavailableError, } from "../../../errors.js";
+import { timingSafeMatchIndex } from "../../../utils/_timing-safe.js";
+import { sha256Hash } from "../../../server/utils/hash.js";
+import { OAUTH2_CONTEXT_KEY } from "../_common.js";
+import { loginContinuation as computeLoginContinuation, safeReturnTo, } from "../../../utils/url.js";
+import { resolveCookieName, resolvePrefixConstrainedAttributes, } from "./cookie-prefix.js";
+import { DEFAULT_SESSION_MAX_AGE_MS, MemorySessionStore, sessionStoreMaxAgeMs, supportsBackchannelLogout, } from "./session-store.js";
+import { buildDownstreamHeaders, buildUpstreamHeaders, isInvalidTokenChallenge, resolveForwardHeaders, resolveProxyUrl, } from "./proxy.js";
+/**
+ * Whether the authorization server definitively rejected the grant, as opposed
+ * to failing to answer. Only these end the session.
+ */
+function isRevokedGrant(error) {
+    if (!isOAuth2Error(error))
+        return false;
+    const code = error.extensions.error;
+    return code === "invalid_grant" || code === "invalid_token";
+}
+const BFF_PATH_KEYS = [
+    "login",
+    "callback",
+    "logout",
+    "session",
+    "backchannel",
+];
+function resolvePaths(paths = {}, options) {
+    const basePath = (paths.basePath ?? "/auth").replace(/\/+$/, "");
+    const resolved = {
+        basePath,
+        login: paths.login ?? "/auth/login",
+        callback: paths.callback ?? "/auth/callback",
+        logout: paths.logout ?? "/auth/logout",
+        session: paths.session ?? "/auth/session",
+        backchannel: paths.backchannel ?? "/auth/backchannel",
+    };
+    if (basePath === "")
+        return resolved;
+    const stray = BFF_PATH_KEYS
+        .filter((key) => key !== "backchannel" || options.backchannelMounted)
+        .filter((key) => !resolved[key].startsWith(`${basePath}/`))
+        .map((key) => `${key} ("${resolved[key]}")`);
+    if (stray.length > 0) {
+        throw new Error(`HonoBff paths must sit under paths.basePath "${basePath}", but ` +
+            `${stray.join(", ")} ${stray.length === 1 ? "does" : "do"} not. ` +
+            `routes() strips the base to mount each handler while ` +
+            `loginContinuation() and the session probe's logoutUrl hand out the ` +
+            `unstripped paths, so a stray path is served at one URL and ` +
+            `advertised at another. Move it under "${basePath}/", or set ` +
+            `paths.basePath to "" to mount every path verbatim.`);
+    }
+    return resolved;
+}
+function sessionCookieName(opts) {
+    return resolveCookieName({
+        name: opts?.name,
+        base: "oauth2_session",
+        attributes: resolvePrefixConstrainedAttributes(opts),
+        consequence: "the session would silently never persist",
+    });
+}
+function resolveCsrf(opt) {
+    if (opt === false)
+        return null;
+    return {
+        headerName: (opt?.headerName ?? "x-csrf").toLowerCase(),
+        headerValue: opt?.headerValue,
+    };
+}
+const RESERVED_AUTHORIZE_PARAMS = [
+    "response_type",
+    "client_id",
+    "redirect_uri",
+    "state",
+    "code_challenge",
+    "code_challenge_method",
+    "response_mode",
+    "nonce",
+    "request",
+    "request_uri",
+];
+const RESERVED_AUTHORIZE_PARAM_SET = new Set(RESERVED_AUTHORIZE_PARAMS);
+function assertUsableAuthorizeParamName(name, option) {
+    if (name === "" || name !== name.trim()) {
+        throw new Error(`${option} may not use ${JSON.stringify(name)} as an ` +
+            "authorize-parameter name: a name must be non-empty and free of " +
+            "surrounding whitespace. A blank name addresses nothing at the " +
+            "authorization server, and a padded one is not the parameter it " +
+            `looks like — " state" is sent as "+state", so it would slip past ` +
+            "the reserved list below while reading as a name on that list. " +
+            "Splitting a list out of an environment variable without trimming " +
+            "is the usual source.");
+    }
+    if (!RESERVED_AUTHORIZE_PARAM_SET.has(name.toLowerCase()))
+        return;
+    throw new Error(`${option} may not name the authorize parameter "${name}". The login ` +
+        `flow reserves ${RESERVED_AUTHORIZE_PARAMS.join(", ")}, and must be ` +
+        "the only source of their values: one supplied from outside it would " +
+        "variously redirect the authorization code, break the PKCE binding " +
+        "the token exchange depends on, unpick the state the login-state " +
+        "cookie commits to, move the authorization response off the callback " +
+        "URL, pass off replay protection nothing verifies, or supersede the " +
+        "parameters beside it. None of them has a supported override.");
+}
+function resolveExtraAuthorizeParams(options) {
+    const fixed = Object.freeze({ ...options.extraParams });
+    const forwarded = Object.freeze([...(options.forwardedParams ?? [])]);
+    const pinnedByFoldedName = new Map();
+    for (const name of Object.keys(fixed)) {
+        assertUsableAuthorizeParamName(name, "extraParams");
+        if (name.toLowerCase() === "scope" && options.scope !== undefined) {
+            throw new Error(`extraParams may not set ${JSON.stringify(name)} while ` +
+                "HonoBffOptions.scope is set: both fix the scope every authorize " +
+                "request carries, so which one a sign-in should send would be " +
+                "ambiguous. The two are compared case-insensitively, since an " +
+                "authorization server that folds parameter-name case would read " +
+                "them as one parameter. Keep HonoBffOptions.scope, which is also " +
+                "the value the login flow records as the scope it requested.");
+        }
+        pinnedByFoldedName.set(name.toLowerCase(), name);
+    }
+    for (const name of forwarded) {
+        assertUsableAuthorizeParamName(name, "forwardedParams");
+        if (["acr_values", "max_age"].includes(name.toLowerCase())) {
+            throw new Error(`forwardedParams may not name the authentication control "${name}"; ` +
+                "pin it in extraParams so the server chooses the assurance and freshness requirements.");
+        }
+        const pinned = pinnedByFoldedName.get(name.toLowerCase());
+        if (pinned !== undefined) {
+            throw new Error(`forwardedParams may not list "${name}" while extraParams sets ` +
+                `"${pinned}": one pins the value every authorize request carries ` +
+                "and the other lets the browser choose it, so which value a " +
+                "sign-in should send would be ambiguous. The two are compared " +
+                "case-insensitively, since an authorization server that folds " +
+                "parameter-name case would read them as one parameter. Keep the " +
+                "fixed value in extraParams, or list the name in forwardedParams " +
+                "alone.");
+        }
+    }
+    return { fixed, forwarded };
+}
+function authorizeParamsForRequest(resolved, requestParams) {
+    const entries = Object.entries(resolved.fixed);
+    for (const name of resolved.forwarded) {
+        const value = requestParams.get(name);
+        if (value !== null)
+            entries.push([name, value]);
+    }
+    const resolvedParams = {};
+    const extraEntries = [];
+    for (const [name, value] of entries) {
+        const folded = name.toLowerCase();
+        if (folded === "scope")
+            resolvedParams.scope = value || undefined;
+        else if (folded === "prompt")
+            resolvedParams.prompt = value;
+        else
+            extraEntries.push([name, value]);
+    }
+    if (extraEntries.length > 0) {
+        resolvedParams.extraParams = Object.fromEntries(extraEntries);
+    }
+    return resolvedParams;
+}
+function cookieOpts(opts, maxAgeSeconds) {
+    const { secure, path, domain } = resolvePrefixConstrainedAttributes(opts);
+    return {
+        path,
+        secure,
+        httpOnly: opts?.httpOnly ?? true,
+        sameSite: (opts?.sameSite ?? "Strict"),
+        domain,
+        ...(maxAgeSeconds === undefined ? {} : { maxAge: maxAgeSeconds }),
+    };
+}
+const MAX_COOKIE_MAX_AGE_SECONDS = 400 * 24 * 60 * 60;
+const MAX_SESSION_MAX_AGE_MS = MAX_COOKIE_MAX_AGE_SECONDS * 1000;
+function positiveSeconds(value, field) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`${field} must be a positive number of seconds, got ${value}.`);
+    }
+    if (value > MAX_COOKIE_MAX_AGE_SECONDS) {
+        throw new Error(`${field} must not exceed 400 days (${MAX_COOKIE_MAX_AGE_SECONDS} ` +
+            `seconds), got ${value}. Browsers cap cookie lifetimes there, so a ` +
+            "larger value would fail when the cookie is written, not here.");
+    }
+    return value;
+}
+function positiveMs(value, field) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`${field} must be a positive number of milliseconds, got ${value}.`);
+    }
+    if (value > MAX_SESSION_MAX_AGE_MS) {
+        throw new Error(`${field} must not exceed 400 days (${MAX_SESSION_MAX_AGE_MS} ` +
+            `milliseconds), got ${value}. Browsers cap cookie lifetimes there, so ` +
+            "a larger value would fail when the cookie is written, not here.");
+    }
+    return value;
+}
+const LOGIN_STATE_BASE_NAME = "oauth2_login_state";
+const DEFAULT_LOGIN_STATE_TTL_MS = 10 * 60 * 1000;
+const MAX_PENDING_LOGIN_STATES = 3;
+const LOGIN_STATE_SEPARATOR = ".";
+function loginStateCookieName(opts) {
+    return resolveCookieName({
+        name: undefined,
+        base: LOGIN_STATE_BASE_NAME,
+        attributes: resolvePrefixConstrainedAttributes(opts),
+        consequence: "every sign-in would fail at the callback",
+    });
+}
+function loginStateCookieOpts(opts, maxAgeSeconds) {
+    const { secure, path, domain } = resolvePrefixConstrainedAttributes(opts);
+    return {
+        path,
+        secure,
+        httpOnly: true,
+        sameSite: "Lax",
+        ...(domain ? { domain } : {}),
+        ...(maxAgeSeconds === undefined ? {} : { maxAge: maxAgeSeconds }),
+    };
+}
+/**
+ * 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 class HonoBff {
+    #options;
+    #client;
+    #store;
+    #paths;
+    #cookieName;
+    #loginStateCookieName;
+    #loginStateTtlMs;
+    #sessionMaxAgeMs;
+    #cookieMaxAgeSeconds;
+    #warnedLogoutIsLocalOnly = false;
+    #sessionMode;
+    #csrf;
+    #extraAuthorizeParams;
+    #refreshes = new Map();
+    /**
+     * 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) {
+        this.#options = options;
+        this.#client = options.client;
+        this.#store = options.sessionStore ?? new MemorySessionStore();
+        this.#paths = resolvePaths(options.paths, {
+            backchannelMounted: options.backchannelLogout !== undefined,
+        });
+        this.#cookieName = sessionCookieName(options.cookie);
+        this.#loginStateCookieName = loginStateCookieName(options.cookie);
+        this.#loginStateTtlMs = options.loginStateTtlMs ??
+            DEFAULT_LOGIN_STATE_TTL_MS;
+        this.#sessionMode = options.sessionMode ?? "own";
+        this.#csrf = resolveCsrf(options.csrf);
+        this.#extraAuthorizeParams = resolveExtraAuthorizeParams(options);
+        const sessionMaxAgeMs = positiveMs(options.sessionMaxAgeMs ?? DEFAULT_SESSION_MAX_AGE_MS, "sessionMaxAgeMs");
+        this.#sessionMaxAgeMs = sessionMaxAgeMs;
+        if (this.#sessionMode === "shared") {
+            const maxAge = options.cookie?.maxAge;
+            this.#cookieMaxAgeSeconds = maxAge === undefined || maxAge === "session"
+                ? undefined
+                : positiveSeconds(maxAge, "cookie.maxAge");
+        }
+        else {
+            const configuredMaxAge = options.cookie?.maxAge ??
+                Math.ceil(sessionMaxAgeMs / 1000);
+            this.#cookieMaxAgeSeconds = configuredMaxAge === "session"
+                ? undefined
+                : positiveSeconds(configuredMaxAge, "cookie.maxAge");
+            if (this.#cookieMaxAgeSeconds !== undefined) {
+                const storeMaxAgeMs = sessionStoreMaxAgeMs(this.#store);
+                const sessionSeconds = Math.ceil(Math.max(sessionMaxAgeMs, storeMaxAgeMs ?? 0) / 1000);
+                if (this.#cookieMaxAgeSeconds < sessionSeconds) {
+                    const cookieSource = options.cookie?.maxAge !== undefined
+                        ? `cookie.maxAge (${this.#cookieMaxAgeSeconds}s)`
+                        : `the session cookie's Max-Age (${this.#cookieMaxAgeSeconds}s, ` +
+                            "taken from sessionMaxAgeMs)";
+                    const storeDrivesIt = (storeMaxAgeMs ?? 0) > sessionMaxAgeMs;
+                    const remedy = storeDrivesIt
+                        ? `Set sessionMaxAgeMs to ${sessionSeconds * 1000} so it matches ` +
+                            "the session store's maxAgeMs, or lower that maxAgeMs to match " +
+                            "the lifetime you want."
+                        : "Raise cookie.maxAge, lower sessionMaxAgeMs (and the " +
+                            'store\'s maxAgeMs) to match, or pass cookie.maxAge: "session" ' +
+                            "for a deliberately ephemeral cookie.";
+                    throw new Error(`${cookieSource} is shorter than the session lifetime ` +
+                        `(${sessionSeconds}s): the browser drops the cookie while the ` +
+                        "session stays active and listed, so the user is signed out " +
+                        `with no way to reach the session they still have. ${remedy}`);
+                }
+            }
+        }
+        if (options.backchannelLogout && !supportsBackchannelLogout(this.#store)) {
+            throw new Error("backchannelLogout requires a SessionStore that implements " +
+                "destroyByLogout() (a stateful store). The stateless " +
+                "EncryptedCookieSessionStore cannot enumerate sessions.");
+        }
+    }
+    /**
+     * Cookie name used for the session cookie. Read-only; configured via
+     * {@link HonoBffOptions.cookie}.
+     */
+    get cookieName() {
+        return this.#cookieName;
+    }
+    /**
+     * 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() {
+        return this.#loginStateCookieName;
+    }
+    /**
+     * 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() {
+        return this.#csrf?.headerName;
+    }
+    /**
+     * 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() {
+        return this.#store;
+    }
+    #hasSessionCookie(c) {
+        return getCookie(c, this.#cookieName) !== undefined;
+    }
+    #cookieOptions() {
+        return cookieOpts(this.#options.cookie, this.#cookieMaxAgeSeconds);
+    }
+    #isBeyondSessionMaxAge(data) {
+        if (this.#sessionMode !== "own")
+            return false;
+        const { createdAt } = data;
+        if (!Number.isFinite(createdAt) || createdAt <= 0)
+            return false;
+        return Date.now() - createdAt > this.#sessionMaxAgeMs;
+    }
+    async #readLiveSession(c, cookieValue) {
+        const data = await this.#store.read(cookieValue);
+        if (!data)
+            return null;
+        if (!this.#isBeyondSessionMaxAge(data))
+            return data;
+        await this.#store.destroy(cookieValue);
+        deleteCookie(c, this.#cookieName, this.#cookieOptions());
+        return null;
+    }
+    #noStore(c) {
+        c.header("Cache-Control", "no-store");
+        c.header("Vary", "Cookie");
+    }
+    #loginStateHashes(c) {
+        const value = getCookie(c, this.#loginStateCookieName);
+        if (!value)
+            return [];
+        return value.split(LOGIN_STATE_SEPARATOR).filter((hash) => hash.length > 0);
+    }
+    #writeLoginStateHashes(c, hashes) {
+        if (hashes.length === 0) {
+            deleteCookie(c, this.#loginStateCookieName, loginStateCookieOpts(this.#options.cookie));
+            return;
+        }
+        setCookie(c, this.#loginStateCookieName, hashes.slice(-MAX_PENDING_LOGIN_STATES).join(LOGIN_STATE_SEPARATOR), loginStateCookieOpts(this.#options.cookie, Math.ceil(this.#loginStateTtlMs / 1000)));
+    }
+    #derivedRedirectUri(c, origin) {
+        if (!this.#options.deriveRedirectUri)
+            return undefined;
+        const base = origin ?? new URL(c.req.url).origin;
+        return new URL(this.#paths.callback, base).toString();
+    }
+    #csrfHeaderOk(c) {
+        if (!this.#csrf)
+            return true;
+        const value = c.req.header(this.#csrf.headerName);
+        if (this.#csrf.headerValue !== undefined) {
+            return value === this.#csrf.headerValue;
+        }
+        return typeof value === "string" && value.length > 0;
+    }
+    #sameOriginOk(c) {
+        const fetchSite = c.req.header("sec-fetch-site");
+        if (fetchSite)
+            return fetchSite === "same-origin" || fetchSite === "none";
+        const target = new URL(c.req.url).origin;
+        const check = (val) => {
+            if (!val)
+                return undefined;
+            try {
+                return new URL(val).origin === target;
+            }
+            catch {
+                return false;
+            }
+        };
+        const fromOrigin = check(c.req.header("origin"));
+        if (fromOrigin !== undefined)
+            return fromOrigin;
+        const fromReferer = check(c.req.header("referer"));
+        if (fromReferer !== undefined)
+            return fromReferer;
+        return false;
+    }
+    #csrfReject(c) {
+        return c.json({
+            error: "csrf_validation_failed",
+            error_description: "Missing or invalid CSRF header on a credentialed request.",
+        }, 403);
+    }
+    /**
+     * 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() {
+        const app = new Hono();
+        const p = this.#pathsRelative();
+        app.get(p.login, this.loginHandler());
+        app.post(p.login, this.loginHandler());
+        app.get(p.callback, this.callbackHandler());
+        app.get(p.logout, this.logoutHandler());
+        app.post(p.logout, this.logoutHandler());
+        app.get(p.session, this.sessionHandler());
+        if (this.#options.backchannelLogout) {
+            app.post(p.backchannel, this.backchannelHandler());
+        }
+        return app;
+    }
+    /**
+     * 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) {
+        return computeLoginContinuation(returnTo, {
+            authorizeEndpoint: this.#client.authorizationEndpoint,
+            loginPath: this.#paths.login,
+            defaultReturnTo: this.#options.defaultReturnTo,
+        });
+    }
+    #pathsRelative() {
+        const { basePath } = this.#paths;
+        const strip = (p) => basePath && p.startsWith(`${basePath}/`) ? p.slice(basePath.length) : p;
+        return {
+            basePath,
+            login: strip(this.#paths.login),
+            callback: strip(this.#paths.callback),
+            logout: strip(this.#paths.logout),
+            session: strip(this.#paths.session),
+            backchannel: strip(this.#paths.backchannel),
+        };
+    }
+    /**
+     * 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() {
+        return async (c) => {
+            this.#noStore(c);
+            const returnTo = safeReturnTo(c.req.query("return_to"), this.#options.defaultReturnTo ?? "/");
+            const origin = this.#options.resolveOrigin?.(c);
+            const requested = authorizeParamsForRequest(this.#extraAuthorizeParams, new URL(c.req.url).searchParams);
+            const { url, state } = await this.#client.login({
+                returnTo,
+                scope: requested.scope ?? this.#options.scope,
+                origin,
+                prompt: requested.prompt,
+                extraParams: requested.extraParams,
+                redirectUri: this.#derivedRedirectUri(c, origin),
+                authRequestStorage: this.#options.authRequestStorage?.forRequest(c),
+            });
+            this.#writeLoginStateHashes(c, [
+                ...this.#loginStateHashes(c),
+                await sha256Hash(state),
+            ]);
+            return c.redirect(url);
+        };
+    }
+    /**
+     * Callback handler — requires the login-state cookie to vouch for the
+     * returned `state`, then exchanges the code and opens a session.
+     */
+    callbackHandler() {
+        return async (c) => {
+            this.#noStore(c);
+            const params = new URL(c.req.url).searchParams;
+            const fail = (error) => this.#options.onCallbackError
+                ? this.#options.onCallbackError(c, error)
+                : c.json({ error: error.error, error_description: error.error_description }, 400);
+            if (params.get("error")) {
+                return await fail({
+                    error: params.get("error"),
+                    error_description: params.get("error_description") ?? "",
+                });
+            }
+            const code = params.get("code");
+            const state = params.get("state");
+            if (!code || !state) {
+                return await fail({
+                    error: "invalid_request",
+                    error_description: "missing code/state",
+                });
+            }
+            const pendingStates = this.#loginStateHashes(c);
+            const matched = timingSafeMatchIndex(pendingStates, await sha256Hash(state));
+            if (matched === undefined) {
+                return await fail({
+                    error: "invalid_request",
+                    error_description: "state was not started in this browser",
+                });
+            }
+            this.#writeLoginStateHashes(c, pendingStates.filter((_, index) => index !== matched));
+            try {
+                const origin = this.#options.resolveOrigin?.(c);
+                const { tokens, refreshToken, returnTo, raw } = await this.#client
+                    .exchangeAuthorizationCode(code, state, {
+                    origin,
+                    redirectUri: this.#derivedRedirectUri(c, origin),
+                    authRequestStorage: this.#options.authRequestStorage?.forRequest(c),
+                });
+                let user = null;
+                let sid;
+                const idToken = raw.id_token;
+                if (idToken) {
+                    try {
+                        const claims = this.#client.decodeIdToken(idToken);
+                        user = claims;
+                        const claimSid = claims.sid;
+                        if (typeof claimSid === "string")
+                            sid = claimSid;
+                    }
+                    catch {
+                        user = null;
+                    }
+                }
+                if (this.#options.resolveUser) {
+                    user = await this.#options.resolveUser(tokens, user);
+                }
+                const now = Date.now();
+                const data = {
+                    tokens,
+                    refreshToken,
+                    user,
+                    sid,
+                    createdAt: now,
+                    updatedAt: now,
+                };
+                const existing = this.#sessionMode === "shared"
+                    ? getCookie(c, this.#cookieName)
+                    : undefined;
+                const cookieValue = existing
+                    ? await this.#store.update(existing, data)
+                    : await this.#store.create(data);
+                if (cookieValue !== existing) {
+                    setCookie(c, this.#cookieName, cookieValue, this.#cookieOptions());
+                }
+                return c.redirect(safeReturnTo(returnTo, this.#options.defaultReturnTo ?? "/"));
+            }
+            catch (cause) {
+                return await fail({
+                    error: "invalid_grant",
+                    error_description: "code exchange failed",
+                    cause,
+                });
+            }
+        };
+    }
+    /** Logout handler — revokes the refresh token and clears the session cookie. */
+    logoutHandler() {
+        return async (c) => {
+            this.#noStore(c);
+            const cookieValue = getCookie(c, this.#cookieName);
+            if (cookieValue && this.#csrf) {
+                const ok = c.req.method === "GET"
+                    ? this.#sameOriginOk(c)
+                    : this.#csrfHeaderOk(c);
+                if (!ok)
+                    return this.#csrfReject(c);
+            }
+            let idToken;
+            if (cookieValue) {
+                const data = await this.#store.read(cookieValue);
+                idToken = data?.tokens?.idToken;
+                if (data?.refreshToken) {
+                    try {
+                        await this.#client.revoke(data.refreshToken, {
+                            tokenTypeHint: "refresh_token",
+                        });
+                    }
+                    catch {
+                        // best-effort
+                    }
+                }
+                await this.#store.destroy(cookieValue);
+                deleteCookie(c, this.#cookieName, this.#cookieOptions());
+            }
+            const returnTo = safeReturnTo(c.req.query("return_to"), this.#options.defaultReturnTo ?? "/");
+            if (this.#options.rpInitiatedLogout) {
+                const endSession = this.#client.endSessionEndpoint;
+                if (endSession) {
+                    const origin = this.#options.resolveOrigin?.(c) ??
+                        new URL(c.req.url).origin;
+                    const url = new URL(endSession, origin);
+                    if (idToken)
+                        url.searchParams.set("id_token_hint", idToken);
+                    url.searchParams.set("client_id", this.#client.clientId);
+                    url.searchParams.set("post_logout_redirect_uri", new URL(returnTo, origin).toString());
+                    return c.redirect(url.toString());
+                }
+                this.#warnLogoutIsLocalOnly();
+            }
+            return c.redirect(returnTo);
+        };
+    }
+    #warnLogoutIsLocalOnly() {
+        if (this.#warnedLogoutIsLocalOnly)
+            return;
+        this.#warnedLogoutIsLocalOnly = true;
+        console.warn("[@udibo/oauth2] rpInitiatedLogout is enabled but no end_session " +
+            "endpoint is known, so logout only clears this app's session — the " +
+            "identity provider's stays alive and the next sign-in will be " +
+            "silent. Give the client an `issuer` so discovery can find the " +
+            "endpoint, or add `endpoints.endSession` explicitly.");
+    }
+    /** Session probe — returns `{ isAuthenticated, user }` without tokens. */
+    sessionHandler() {
+        return async (c) => {
+            this.#noStore(c);
+            const cookieValue = getCookie(c, this.#cookieName);
+            if (!cookieValue) {
+                return c.json({ isAuthenticated: false, user: null });
+            }
+            if (this.#csrf && !this.#csrfHeaderOk(c))
+                return this.#csrfReject(c);
+            const data = await this.#readLiveSession(c, cookieValue);
+            if (!data) {
+                return c.json({ isAuthenticated: false, user: null });
+            }
+            const expiresAt = data.tokens.accessTokenExpiresAt;
+            const sessionExpiresIn = expiresAt !== undefined
+                ? Math.max(0, Math.round((expiresAt - Date.now()) / 1000))
+                : null;
+            return c.json({
+                isAuthenticated: true,
+                user: data.user ?? null,
+                sessionExpiresIn,
+                logoutUrl: this.#paths.logout,
+            });
+        };
+    }
+    /**
+     * 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() {
+        return async (c) => {
+            c.header("Cache-Control", "no-store");
+            const opts = this.#options.backchannelLogout;
+            if (!opts)
+                return c.json({ error: "not_supported" }, 400);
+            let logoutToken;
+            try {
+                logoutToken = (await c.req.formData()).get("logout_token")?.toString();
+            }
+            catch {
+                logoutToken = undefined;
+            }
+            if (!logoutToken) {
+                return c.json({
+                    error: "invalid_request",
+                    error_description: "missing logout_token",
+                }, 400);
+            }
+            let subject;
+            try {
+                subject = await opts.verifyLogoutToken(logoutToken);
+            }
+            catch {
+                subject = null;
+            }
+            if (!subject || (subject.sub === undefined && subject.sid === undefined)) {
+                return c.json({
+                    error: "invalid_request",
+                    error_description: "invalid logout_token",
+                }, 400);
+            }
+            if (!supportsBackchannelLogout(this.#store)) {
+                return c.json({ error: "not_supported" }, 400);
+            }
+            await this.#store.destroyByLogout({ sub: subject.sub, sid: subject.sid });
+            return c.body(null, 200);
+        };
+    }
+    async #resolveSessionEntry(c) {
+        const cookieValue = getCookie(c, this.#cookieName);
+        if (!cookieValue)
+            return { status: "anonymous" };
+        const data = await this.#readLiveSession(c, cookieValue);
+        if (!data)
+            return { status: "anonymous" };
+        const skew = (this.#options.refreshSkewSeconds ?? 30) * 1000;
+        const needsRefresh = data.tokens.accessTokenExpiresAt !== undefined
+            ? data.tokens.accessTokenExpiresAt - skew < Date.now()
+            : false;
+        if (!needsRefresh || !data.refreshToken) {
+            return { status: "active", entry: { cookieValue, data } };
+        }
+        const outcome = await this.#refreshSessionEntry(c, { cookieValue, data });
+        if (outcome.status === "refreshed") {
+            return { status: "active", entry: outcome.entry };
+        }
+        return outcome.status === "unavailable"
+            ? { status: "unavailable" }
+            : { status: "anonymous" };
+    }
+    #temporarilyUnavailable(c) {
+        return this.#errorResponse(c, new TemporarilyUnavailableError(502, "token refresh temporarily unavailable"));
+    }
+    async #refreshSessionEntry(c, entry) {
+        const outcome = await this.#sharedRefresh(entry);
+        if (outcome.status === "refreshed") {
+            if (outcome.entry.cookieValue !== entry.cookieValue) {
+                setCookie(c, this.#cookieName, outcome.entry.cookieValue, this.#cookieOptions());
+            }
+        }
+        else if (outcome.status === "revoked") {
+            deleteCookie(c, this.#cookieName, this.#cookieOptions());
+        }
+        return outcome;
+    }
+    #sharedRefresh(entry) {
+        const inFlight = this.#refreshes.get(entry.cookieValue);
+        if (inFlight)
+            return inFlight;
+        const pending = this.#exchangeRefresh(entry).finally(() => {
+            this.#refreshes.delete(entry.cookieValue);
+        });
+        this.#refreshes.set(entry.cookieValue, pending);
+        return pending;
+    }
+    async #exchangeRefresh(entry) {
+        const { cookieValue, data } = entry;
+        if (!data.refreshToken)
+            return { status: "unavailable" };
+        try {
+            const result = await this.#client.exchangeRefreshToken(data.refreshToken);
+            const refreshed = {
+                tokens: result.tokens,
+                refreshToken: result.refreshToken ?? data.refreshToken,
+                user: data.user,
+                sid: data.sid,
+                createdAt: data.createdAt,
+                updatedAt: Date.now(),
+            };
+            const newCookieValue = await this.#store.update(cookieValue, refreshed);
+            return {
+                status: "refreshed",
+                entry: { cookieValue: newCookieValue, data: refreshed },
+            };
+        }
+        catch (error) {
+            if (!isRevokedGrant(error))
+                return { status: "unavailable" };
+            const current = await this.#store.read(cookieValue);
+            if (current && current.refreshToken !== data.refreshToken) {
+                return { status: "refreshed", entry: { cookieValue, data: current } };
+            }
+            await this.#store.destroy(cookieValue);
+            return { status: "revoked" };
+        }
+    }
+    /**
+     * 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() {
+        return async (c, next) => {
+            if (this.#csrf && this.#hasSessionCookie(c)) {
+                const inboundAuth = c.req.header("Authorization") ?? "";
+                const hasBearer = /^bearer\s+\S/i.test(inboundAuth);
+                if (!hasBearer && !this.#csrfHeaderOk(c))
+                    return this.#csrfReject(c);
+            }
+            const resolution = await this.#resolveSessionEntry(c);
+            if (resolution.status === "unavailable") {
+                return this.#temporarilyUnavailable(c);
+            }
+            if (resolution.status !== "active") {
+                await next();
+                return;
+            }
+            const headers = new Headers(c.req.raw.headers);
+            headers.set("Authorization", `Bearer ${resolution.entry.data.tokens.accessToken}`);
+            c.req.raw = new Request(c.req.raw, { headers });
+            await next();
+        };
+    }
+    /**
+     * 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) {
+        const resourceServer = this.#options.resourceServer;
+        if (!resourceServer) {
+            throw new Error("HonoBff.requireScope() requires a `resourceServer` option (the same " +
+                "one `protect` authenticates against).");
+        }
+        return resourceServer.requireScope(requiredScope);
+    }
+    /**
+     * 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) {
+        const resourceServer = this.#options.resourceServer;
+        if (!resourceServer) {
+            throw new Error("HonoBff.protect() requires a `resourceServer` option. Either pass " +
+                "one to the constructor or compose middleware manually: " +
+                "`app.use(bff.attachToken(), resourceServer.protect(scope))`.");
+        }
+        return async (c, next) => {
+            try {
+                const inboundAuth = c.req.header("Authorization") ?? "";
+                const hasBearer = /^bearer\s+\S/i.test(inboundAuth);
+                if (!hasBearer && this.#csrf && this.#hasSessionCookie(c) &&
+                    !this.#csrfHeaderOk(c)) {
+                    return this.#csrfReject(c);
+                }
+                let authRequest;
+                if (hasBearer) {
+                    authRequest = c.req.raw;
+                }
+                else {
+                    const resolution = await this.#resolveSessionEntry(c);
+                    if (resolution.status === "unavailable") {
+                        return this.#temporarilyUnavailable(c);
+                    }
+                    if (resolution.status === "active") {
+                        const headers = new Headers(c.req.raw.headers);
+                        headers.set("Authorization", `Bearer ${resolution.entry.data.tokens.accessToken}`);
+                        authRequest = new Request(c.req.raw.url, { headers });
+                    }
+                    else {
+                        authRequest = new Request(c.req.raw.url);
+                    }
+                }
+                const ctx = await resourceServer.authenticate(authRequest, requiredScope);
+                c.set(OAUTH2_CONTEXT_KEY, ctx);
+                await next();
+            }
+            catch (error) {
+                return resourceServer.handleAuthError(error);
+            }
+        };
+    }
+    #errorResponse(c, error) {
+        if (error.status === 401) {
+            c.header("WWW-Authenticate", `Bearer error="${error.extensions.error ?? "invalid_token"}"`);
+        }
+        return c.json({
+            error: error.extensions.error,
+            error_description: error.message,
+        }, error.status);
+    }
+    /**
+     * 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, options = {}) {
+        const base = new URL(target);
+        const allowedHeaders = resolveForwardHeaders(options.forwardHeaders, this.#csrf?.headerName);
+        const fetchImpl = options.fetch ??
+            ((input, init) => fetch(input, init));
+        const retryOn401 = options.retryOn401 ?? true;
+        const mountPrefix = (options.stripPrefix ?? "").endsWith("/")
+            ? options.stripPrefix.slice(0, -1)
+            : options.stripPrefix ?? "";
+        return async (c) => {
+            if (this.#csrf && this.#hasSessionCookie(c) && !this.#csrfHeaderOk(c)) {
+                return this.#csrfReject(c);
+            }
+            let url;
+            try {
+                url = resolveProxyUrl(base, c.req.url, options.stripPrefix);
+            }
+            catch {
+                return this.#errorResponse(c, new InvalidRequestError("invalid proxy path"));
+            }
+            const resolution = await this.#resolveSessionEntry(c);
+            if (resolution.status === "unavailable") {
+                return this.#temporarilyUnavailable(c);
+            }
+            if (resolution.status !== "active") {
+                return this.#errorResponse(c, new InvalidTokenError("no active session"));
+            }
+            const entry = resolution.entry;
+            const body = c.req.raw.body;
+            const send = (accessToken, requestBody) => {
+                const init = {
+                    method: c.req.method,
+                    headers: buildUpstreamHeaders(c.req.raw.headers, allowedHeaders, accessToken),
+                    body: requestBody,
+                    redirect: "manual",
+                };
+                if (requestBody)
+                    init.duplex = "half";
+                return fetchImpl(url, init);
+            };
+            let response;
+            try {
+                response = await send(entry.data.tokens.accessToken, body);
+            }
+            catch (cause) {
+                return this.#errorResponse(c, new TemporarilyUnavailableError(502, "upstream request failed", {
+                    cause,
+                }));
+            }
+            const canRetry = retryOn401 && body === null &&
+                entry.data.refreshToken !== undefined;
+            if (canRetry && isInvalidTokenChallenge(response)) {
+                await response.body?.cancel();
+                const outcome = await this.#refreshSessionEntry(c, entry);
+                if (outcome.status === "revoked") {
+                    return this.#errorResponse(c, new InvalidTokenError("session refresh failed"));
+                }
+                if (outcome.status === "unavailable") {
+                    return this.#temporarilyUnavailable(c);
+                }
+                try {
+                    response = await send(outcome.entry.data.tokens.accessToken, null);
+                }
+                catch (cause) {
+                    return this.#errorResponse(c, new TemporarilyUnavailableError(502, "upstream request failed", {
+                        cause,
+                    }));
+                }
+            }
+            const downstream = response.body;
+            const init = {
+                status: response.status,
+                headers: buildDownstreamHeaders(response, {
+                    upstreamUrl: url,
+                    base,
+                    mountPrefix,
+                }),
+            };
+            return downstream === null ? c.body(null, init) : c.body(downstream, {
+                ...init,
+                status: response.status,
+            });
+        };
+    }
+}