@udibo/oauth2 0.4.0 → 0.5.0

package/README.md

@@ -27,7 +27,7 @@ without a hosted account.
 Requires Deno 2 for the development workflow:
 
 ```sh
-deno add jsr:@udibo/oauth2@0.1.0
+deno add jsr:@udibo/oauth2
 ```
 
 Import the part you use; there is no root barrel or default export:
@@ -38,8 +38,8 @@ import { HonoBff } from "@udibo/oauth2/hono/bff";
 import { HonoResourceServer } from "@udibo/oauth2/hono/resource-server";
 ```
 
-Version `0.1.0` is a pre-1.0 API. Minor releases may contain breaking changes;
-review the [stability policy](docs/stability.md) before upgrading.
+The package is pre-1.0. Minor releases may contain breaking changes; review the
+[stability policy](docs/stability.md) before upgrading.
 
 ## How the pieces fit
 

package/SECURITY.md

@@ -4,10 +4,6 @@
 OpenID Connect protocol surface and password-based identity flows. We take
 reports seriously and value the time of security researchers.
 
-> **Status note:** the package is not yet published to a public registry. Until
-> it is, the disclosure channel below is drafted and monitored, but the package
-> has no external users; the process activates fully at publish.
-
 ## Supported versions
 
 | Version        | Supported                        |

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

@@ -2,11 +2,8 @@
  * Internal helpers shared by the Hono adapters.
  *
  * Not part of the public API — use {@link HonoResourceServer} or
- * {@link HonoAuthorizationServer} instead. Keeping the `protect` /
- * `authenticate` / `getContext` implementations in one place lets both
- * adapter classes stay as direct subclasses of the server type they
- * specialize (no composition / companion objects) without duplicating the
- * Hono-specific plumbing.
+ * {@link HonoAuthorizationServer} instead. Only {@link OAUTH2_CONTEXT_KEY}
+ * and {@link HonoResourceServerVariables} are re-exported publicly.
  *
  * @module
  */
@@ -37,7 +34,7 @@ export interface HonoResourceServerVariables<Client extends ClientInterface, Use
 export declare function createProtectMiddleware<Client extends ClientInterface, User, S extends AbstractScope>(server: ResourceServer<Client, User, S>, requiredScope?: S | string): MiddlewareHandler;
 /**
  * Builds a Hono middleware that asserts the **already-authenticated** request
- * (whose context a prior `protect` / `attachToken` set) carries
+ * (whose context a prior adapter or BFF `protect` set) carries
  * `requiredScope`, without re-validating the token. Shared by both adapter
  * classes' `requireScope` so the check and error stay identical to `protect`'s
  * scope enforcement. `adapterName` names the class in the "context missing"
@@ -52,15 +49,15 @@ export declare function createRequireScopeMiddleware<Client extends ClientInterf
  */
 export declare function createRequireMiddleware<Client extends ClientInterface, User, S extends AbstractScope>(server: ResourceServer<Client, User, S>, adapterName: string, conditions: RequireConditions): MiddlewareHandler;
 /**
- * Resolves a Hono {@link Context} or raw {@link Request} to a Request and
- * calls the base {@link ResourceServer.authenticate} (bypassing any
- * Context-accepting override). This is what both adapter classes'
- * `authenticate` overrides end up calling.
+ * Authenticates a Hono {@link Context} or raw {@link Request} with the base
+ * {@link ResourceServer.authenticate}, bypassing the adapters'
+ * Context-accepting override.
  */
 export declare function authenticateHonoRequest<Client extends ClientInterface, User, S extends AbstractScope>(server: ResourceServer<Client, User, S>, c: Context | Request, requiredScope?: S | string): Promise<AuthenticatedContext<Client, User, S>>;
 /**
- * Reads the authenticated OAuth2 context off the Hono context. Throws if
- * `createProtectMiddleware` has not run first — the error message names the
- * class the user invoked to make the fix obvious.
+ * Reads the authenticated OAuth2 context off the Hono context.
+ *
+ * @throws {Error} If no `protect` (the adapter's or the BFF's) middleware set
+ * it first; the message names `adapterName`.
  */
 export declare function readContext<Client extends ClientInterface, User, S extends AbstractScope>(c: Context, adapterName: string): AuthenticatedContext<Client, User, S>;

package/esm/adapters/hono/_common.js

@@ -2,11 +2,8 @@
  * Internal helpers shared by the Hono adapters.
  *
  * Not part of the public API — use {@link HonoResourceServer} or
- * {@link HonoAuthorizationServer} instead. Keeping the `protect` /
- * `authenticate` / `getContext` implementations in one place lets both
- * adapter classes stay as direct subclasses of the server type they
- * specialize (no composition / companion objects) without duplicating the
- * Hono-specific plumbing.
+ * {@link HonoAuthorizationServer} instead. Only {@link OAUTH2_CONTEXT_KEY}
+ * and {@link HonoResourceServerVariables} are re-exported publicly.
  *
  * @module
  */
@@ -35,7 +32,7 @@ export function createProtectMiddleware(server, requiredScope) {
 }
 /**
  * Builds a Hono middleware that asserts the **already-authenticated** request
- * (whose context a prior `protect` / `attachToken` set) carries
+ * (whose context a prior adapter or BFF `protect` set) carries
  * `requiredScope`, without re-validating the token. Shared by both adapter
  * classes' `requireScope` so the check and error stay identical to `protect`'s
  * scope enforcement. `adapterName` names the class in the "context missing"
@@ -72,31 +69,25 @@ export function createRequireMiddleware(server, adapterName, conditions) {
     };
 }
 /**
- * Resolves a Hono {@link Context} or raw {@link Request} to a Request and
- * calls the base {@link ResourceServer.authenticate} (bypassing any
- * Context-accepting override). This is what both adapter classes'
- * `authenticate` overrides end up calling.
+ * Authenticates a Hono {@link Context} or raw {@link Request} with the base
+ * {@link ResourceServer.authenticate}, bypassing the adapters'
+ * Context-accepting override.
  */
 export function authenticateHonoRequest(server, c, requiredScope) {
     const request = c instanceof Request ? c : c.req.raw;
     return baseAuthenticate(server, request, requiredScope);
 }
-/**
- * Invokes the base {@link ResourceServer.authenticate} directly, bypassing
- * any subclass override. Necessary because {@link HonoResourceServer}
- * overrides `authenticate` to accept `Context | Request`; if this module
- * called `server.authenticate(...)` the dispatch would land back on that
- * override and recurse forever.
- */
+// Base method on purpose: the Hono subclasses' override would recurse.
 function baseAuthenticate(server, request, requiredScope) {
     // deno-lint-ignore no-explicit-any
     const base = ResourceServer.prototype;
     return base.authenticate.call(server, request, requiredScope);
 }
 /**
- * Reads the authenticated OAuth2 context off the Hono context. Throws if
- * `createProtectMiddleware` has not run first — the error message names the
- * class the user invoked to make the fix obvious.
+ * Reads the authenticated OAuth2 context off the Hono context.
+ *
+ * @throws {Error} If no `protect` (the adapter's or the BFF's) middleware set
+ * it first; the message names `adapterName`.
  */
 export function readContext(c, adapterName) {
     const ctx = c.get(OAUTH2_CONTEXT_KEY);

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

@@ -69,8 +69,9 @@ export type HonoAuthenticateUserFn<User> = (c: Context) => Promise<{
  * Receives the Hono {@link Context} so the callback can render a consent
  * page, read form input, etc. Return one of:
  *
- * - `{ approved: true, scope? }` — consent granted (optionally narrowing the
- *   scope per RFC 6749 §3.3).
+ * - `{ approved: true, scope? }` — consent granted. `scope`, when set,
+ *   replaces the granted scope (RFC 6749 §3.3) and is not checked against the
+ *   request, so return a subset.
  * - `{ approved: false }` — consent denied; the framework redirects to
  *   `redirect_uri` with `error=access_denied`.
  * - A `Response` (typically `c.html(...)` rendering a consent page) —
@@ -93,8 +94,9 @@ export interface HonoRoutesOptions<Client extends ClientInterface, User, S exten
 export type HonoAuthorizeHandlerOptions<Client extends ClientInterface, User, S extends AbstractScope> = HonoRoutesOptions<Client, User, S>;
 /**
  * Hono-specific wrapper around {@link AuthorizationServer}. Adds endpoint
- * handler factories and the three resource-server-shaped helpers
- * (`protect`, `authenticate`, `getContext`) against this same instance.
+ * handler factories and the resource-server-shaped helpers (`protect`,
+ * `requireScope`, `require`, `authenticate`, `getContext`) against this same
+ * instance.
  *
  * Resource-server behavior (realm, errorFormat, throwOnError, token lookup)
  * reads directly off the auth-server instance, so mutating those fields
@@ -107,8 +109,9 @@ export declare class HonoAuthorizationServer<Client extends ClientInterface, Use
     /**
      * Returns a Hono middleware that validates the bearer token against this
      * server's token service. On success, sets the authenticated context at
-     * `c.get("@udibo/oauth2")`; on failure returns an RFC 6749 error response
-     * with a `WWW-Authenticate` header per RFC 6750 Section 3.
+     * `c.get("@udibo/oauth2")`; on failure returns an error response, with a
+     * `WWW-Authenticate` challenge (RFC 6750 Section 3) on a 401 or 403, or
+     * rethrows when `throwOnError` is set.
      */
     protect(requiredScope?: S | string): MiddlewareHandler;
     /**
@@ -198,14 +201,17 @@ export declare class HonoAuthorizationServer<Client extends ClientInterface, Use
      * - `GET /.well-known/openid-configuration`
      * - `GET /jwks` and `GET`/`POST /userinfo` (live when OIDC issuance is
      *   configured via `signingKeys`)
+     * - `GET`/`POST /end_session` (live when the server has an `endSession`
+     *   callback)
      *
      * Mount with `app.route("/oauth2", server.routes({...}))`.
      *
      * Every path and verb above comes from
-     * {@link ENDPOINT_PATHS}/{@link ENDPOINT_METHODS}, so the mounted surface and
-     * the URLs the server advertises can never drift apart. Users who want custom
-     * paths or only a subset of endpoints should mount the individual handler
-     * factories instead.
+     * {@link ENDPOINT_PATHS}/{@link ENDPOINT_METHODS}, the same paths the server
+     * derives from an `issuer` alone. The advertised URLs match the mount only
+     * when the issuer (or each explicit `*Endpoint` in the resolved context)
+     * points at where you mounted it. Users who want custom paths or only a
+     * subset of endpoints should mount the individual handler factories instead.
      */
     routes(options: HonoRoutesOptions<Client, User, S>): Hono;
 }

package/esm/adapters/hono/authorization-server.js

@@ -38,8 +38,9 @@ import { AuthorizationServer, ENDPOINT_METHODS, ENDPOINT_PATHS, } from "../../se
 import { authenticateHonoRequest, createProtectMiddleware, createRequireMiddleware, createRequireScopeMiddleware, readContext, } from "./_common.js";
 /**
  * Hono-specific wrapper around {@link AuthorizationServer}. Adds endpoint
- * handler factories and the three resource-server-shaped helpers
- * (`protect`, `authenticate`, `getContext`) against this same instance.
+ * handler factories and the resource-server-shaped helpers (`protect`,
+ * `requireScope`, `require`, `authenticate`, `getContext`) against this same
+ * instance.
  *
  * Resource-server behavior (realm, errorFormat, throwOnError, token lookup)
  * reads directly off the auth-server instance, so mutating those fields
@@ -54,8 +55,9 @@ export class HonoAuthorizationServer extends AuthorizationServer {
     /**
      * Returns a Hono middleware that validates the bearer token against this
      * server's token service. On success, sets the authenticated context at
-     * `c.get("@udibo/oauth2")`; on failure returns an RFC 6749 error response
-     * with a `WWW-Authenticate` header per RFC 6750 Section 3.
+     * `c.get("@udibo/oauth2")`; on failure returns an error response, with a
+     * `WWW-Authenticate` challenge (RFC 6750 Section 3) on a 401 or 403, or
+     * rethrows when `throwOnError` is set.
      */
     protect(requiredScope) {
         return createProtectMiddleware(this, requiredScope);
@@ -182,14 +184,17 @@ export class HonoAuthorizationServer extends AuthorizationServer {
      * - `GET /.well-known/openid-configuration`
      * - `GET /jwks` and `GET`/`POST /userinfo` (live when OIDC issuance is
      *   configured via `signingKeys`)
+     * - `GET`/`POST /end_session` (live when the server has an `endSession`
+     *   callback)
      *
      * Mount with `app.route("/oauth2", server.routes({...}))`.
      *
      * Every path and verb above comes from
-     * {@link ENDPOINT_PATHS}/{@link ENDPOINT_METHODS}, so the mounted surface and
-     * the URLs the server advertises can never drift apart. Users who want custom
-     * paths or only a subset of endpoints should mount the individual handler
-     * factories instead.
+     * {@link ENDPOINT_PATHS}/{@link ENDPOINT_METHODS}, the same paths the server
+     * derives from an `issuer` alone. The advertised URLs match the mount only
+     * when the issuer (or each explicit `*Endpoint` in the resolved context)
+     * points at where you mounted it. Users who want custom paths or only a
+     * subset of endpoints should mount the individual handler factories instead.
      */
     routes(options) {
         const handlers = {

package/esm/adapters/hono/bff/auth-request-store.d.ts

@@ -123,6 +123,10 @@ export interface AuthRequestStorageFactory {
  * `unknown state parameter`. The AES key is derived on first use and shared by
  * every later request.
  *
+ * It has no `take`: the record travels with the browser and cannot be claimed
+ * atomically, so a replayed callback is bounded by the authorization server's
+ * single-use code and PKCE.
+ *
  * @example
  * ```ts
  * const bff = new HonoBff({

package/esm/adapters/hono/bff/auth-request-store.js

@@ -53,6 +53,10 @@ function cookieAttributes(options, maxAgeSeconds) {
  * `unknown state parameter`. The AES key is derived on first use and shared by
  * every later request.
  *
+ * It has no `take`: the record travels with the browser and cannot be claimed
+ * atomically, so a replayed callback is bounded by the authorization server's
+ * single-use code and PKCE.
+ *
  * @example
  * ```ts
  * const bff = new HonoBff({

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

@@ -4,7 +4,7 @@
  * 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,
+ * - `GET|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
@@ -15,7 +15,8 @@
  *   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.
+ *   session, plus `sessionExpiresIn` and `logoutUrl` when signed in.
+ *   **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).
@@ -62,12 +63,12 @@ import { type HonoBffProxyOptions } from "./proxy.js";
  *
  * Accepted in two shapes so both deployment topologies stay symmetric:
  *
- * - **Own-issuer** (the Udibo case): pass a {@link HonoAuthorizationServer}.
+ * - **Own-issuer**: 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.
+ *   with `IntrospectionTokenReader` (RFC 7662 against the upstream) or
+ *   `JwksTokenReader` (signed JWT access tokens, verified locally).
  */
 export type HonoBffResourceServer<Client extends ClientInterface = any, User = any, S extends AbstractScope = BasicScope> = HonoResourceServer<Client, User, S> | HonoAuthorizationServer<Client, User, S>;
 /**
@@ -122,9 +123,11 @@ export interface HonoBffCookieOptions {
      */
     domain?: string;
     /**
-     * `Max-Age` in seconds, for the **cookie only**. Defaults to
+     * `Max-Age` in seconds, for the **cookie only**. In the default
+     * `sessionMode: "own"` it defaults to
      * {@linkcode HonoBffOptions.sessionMaxAgeMs}, so the browser keeps the
-     * cookie exactly as long as the session behind it is honored.
+     * cookie exactly as long as the session behind it is honored; in
+     * `sessionMode: "shared"` it has no default and is not cross-checked.
      *
      * 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
@@ -143,8 +146,7 @@ export interface HonoBffCookieOptions {
  *
  * 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
+ * (classic CSRF). The defense 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
@@ -269,12 +271,13 @@ 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`).
+     * (the code exchange failed — expired/replayed code, unknown `state` — or
+     * a later step threw: `resolveUser` or the session store).
      */
     error: string;
     /** Human-readable description; never contains secrets. */
     error_description: string;
-    /** The thrown cause for the `invalid_grant` (exchange) case; otherwise `undefined`. */
+    /** The thrown cause for the `invalid_grant` case; otherwise `undefined`. */
     cause?: unknown;
 }
 /** Options accepted by the {@link HonoBff} constructor. */
@@ -394,7 +397,7 @@ export interface HonoBffOptions {
      * 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
+     * `id_token_hint` (the session's id_token, if any), `client_id`, 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.
@@ -557,7 +560,8 @@ export interface HonoBffOptions {
      * 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`).
+     * (validation goes through its token reader, such as
+     * `IntrospectionTokenReader` or `JwksTokenReader`).
      */
     resourceServer?: HonoBffResourceServer;
     /**
@@ -604,7 +608,8 @@ export declare class HonoBff {
      * {@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.sessionMaxAgeMs}), when `sessionMaxAgeMs` or a
+     * numeric `cookie.maxAge` is not positive or exceeds 400 days, 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
@@ -701,7 +706,11 @@ export declare class HonoBff {
     callbackHandler(): Handler;
     /** Logout handler — revokes the refresh token and clears the session cookie. */
     logoutHandler(): Handler;
-    /** Session probe — returns `{ isAuthenticated, user }` without tokens. */
+    /**
+     * Session probe — returns `{ isAuthenticated, user }`, plus
+     * `sessionExpiresIn` (seconds until the access token expires, or `null`) and
+     * `logoutUrl` when signed in. Never returns tokens.
+     */
     sessionHandler(): Handler;
     /**
      * OIDC Back-Channel Logout receiver. A server-to-server `POST` from the OP
@@ -825,9 +834,11 @@ export declare class HonoBff {
      * - **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.
+     *   `Set-Cookie` and hop-by-hop headers are dropped; the status, body
+     *   (problem-details errors included), and remaining headers pass through,
+     *   with `Location`/`Content-Location` rewritten into the mount, and the
+     *   response marked `Cache-Control: private`, `Vary: Cookie`, and
+     *   `X-Content-Type-Options: nosniff`.
      * - **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.

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

@@ -4,7 +4,7 @@
  * 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,
+ * - `GET|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
@@ -15,7 +15,8 @@
  *   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.
+ *   session, plus `sessionExpiresIn` and `logoutUrl` when signed in.
+ *   **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).
@@ -56,10 +57,6 @@ import { loginContinuation as computeLoginContinuation, safeReturnTo, } from "..
 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;
@@ -305,7 +302,8 @@ export class HonoBff {
      * {@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.sessionMaxAgeMs}), when `sessionMaxAgeMs` or a
+     * numeric `cookie.maxAge` is not positive or exceeds 400 days, 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
@@ -742,7 +740,11 @@ export class HonoBff {
             "silent. Give the client an `issuer` so discovery can find the " +
             "endpoint, or add `endpoints.endSession` explicitly.");
     }
-    /** Session probe — returns `{ isAuthenticated, user }` without tokens. */
+    /**
+     * Session probe — returns `{ isAuthenticated, user }`, plus
+     * `sessionExpiresIn` (seconds until the access token expires, or `null`) and
+     * `logoutUrl` when signed in. Never returns tokens.
+     */
     sessionHandler() {
         return async (c) => {
             this.#noStore(c);
@@ -1084,9 +1086,11 @@ export class HonoBff {
      * - **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.
+     *   `Set-Cookie` and hop-by-hop headers are dropped; the status, body
+     *   (problem-details errors included), and remaining headers pass through,
+     *   with `Location`/`Content-Location` rewritten into the mount, and the
+     *   response marked `Cache-Control: private`, `Vary: Cookie`, and
+     *   `X-Content-Type-Options: nosniff`.
      * - **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.

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

@@ -10,10 +10,7 @@
  *
  * @module
  */
-/**
- * Hop-by-hop headers (RFC 9110 §7.6.1). They describe a single transport
- * connection, so a proxy must not pass them through in either direction.
- */
+// RFC 9110 §7.6.1: connection-specific, never proxied in either direction.
 const HOP_BY_HOP_HEADERS = [
     "connection",
     "keep-alive",
@@ -46,14 +43,7 @@ export const DEFAULT_PROXY_FORWARD_HEADERS = [
     "tracestate",
     "x-request-id",
 ];
-/**
- * Never forwarded upstream, even when named in
- * {@link HonoBffProxyOptions.forwardHeaders}. `cookie` and `authorization` are
- * the security-critical entries: the browser's session cookie is the BFF's
- * credential (not the API's), and an inbound `Authorization` must never be able
- * to override the token the BFF attaches. `accept-encoding` and `content-length`
- * are dropped because `fetch` owns content coding and body framing.
- */
+// The session cookie is the BFF's credential; the BFF's bearer token must win.
 const NEVER_FORWARDED_REQUEST_HEADERS = [
     ...HOP_BY_HOP_HEADERS,
     "accept-encoding",
@@ -63,26 +53,16 @@ const NEVER_FORWARDED_REQUEST_HEADERS = [
     "cookie2",
     "host",
 ];
-/**
- * Never returned to the browser. `set-cookie` is dropped so an upstream API
- * cannot plant cookies on the BFF's origin, where they would ride along with
- * the session cookie.
- */
+// An upstream Set-Cookie would plant cookies on the BFF's origin.
 const NEVER_RETURNED_RESPONSE_HEADERS = [
     ...HOP_BY_HOP_HEADERS,
     "set-cookie",
 ];
-/**
- * Dropped only when a body is actually streamed back: `fetch` has already
- * decoded it, so the upstream's content coding and length no longer describe
- * what the browser receives. A body-less response (`HEAD`, `204`, `304`) was
- * never decoded, and there `Content-Length` *is* the answer.
- */
+// fetch decodes a streamed body; a body-less response keeps its Content-Length.
 const DECODED_BODY_RESPONSE_HEADERS = [
     "content-encoding",
     "content-length",
 ];
-/** Case-insensitive header name set. */
 function headerSet(names) {
     return new Set(names.map((name) => name.toLowerCase()));
 }
@@ -115,29 +95,17 @@ export function buildUpstreamHeaders(inbound, allowed, accessToken) {
     headers.set("Authorization", `Bearer ${accessToken}`);
     return headers;
 }
-/**
- * The header names an upstream `Connection` field lists. RFC 9110 §7.6.1 makes
- * those connection-specific too, so a proxy must drop them alongside the
- * well-known hop-by-hop set.
- */
+// RFC 9110 §7.6.1: headers named in `Connection` are hop-by-hop too.
 function connectionNamedHeaders(headers) {
     return (headers.get("connection") ?? "")
         .split(",")
         .map((name) => name.trim().toLowerCase())
         .filter((name) => name.length > 0);
 }
-/** Headers whose value is a URL into the upstream's namespace. */
 const URL_VALUED_RESPONSE_HEADERS = [
     "location",
     "content-location",
 ];
-/**
- * Rewrites an upstream URL into the mount's namespace, so a `Location` naming
- * the resource server neither leaks internal topology to the browser nor points
- * it at a host it cannot reach. A relative value resolves against the upstream
- * request first. Anything outside the configured base is left alone — it is a
- * genuinely external destination, not part of what this mount proxies.
- */
 function rewriteUpstreamUrl(value, upstreamUrl, base, mountPrefix) {
     let resolved;
     try {
@@ -159,7 +127,6 @@ function rewriteUpstreamUrl(value, upstreamUrl, base, mountPrefix) {
     const suffix = resolved.pathname.slice(basePath.length) || "/";
     return `${mountPrefix}${suffix}${resolved.search}${resolved.hash}`;
 }
-/** Adds `name` to `Vary` without disturbing what the upstream already varies on. */
 function appendVary(headers, name) {
     const existing = headers.get("vary");
     if (!existing) {
@@ -174,11 +141,7 @@ function appendVary(headers, name) {
     if (!present)
         headers.set("vary", `${existing}, ${name}`);
 }
-/**
- * Forces the response private. Upstream sees an `Authorization`-protected
- * request, which RFC 9111 §3.5 already keeps out of shared caches; downstream
- * the same response is authenticated by a cookie, which carries no such rule.
- */
+// RFC 9111 §3.5 covers the upstream Authorization, not the downstream cookie.
 function forcePrivateCache(headers) {
     const existing = headers.get("cache-control");
     if (!existing) {
@@ -227,18 +190,7 @@ export function buildDownstreamHeaders(upstream, context) {
     headers.set("X-Content-Type-Options", "nosniff");
     return headers;
 }
-/**
- * Rejects a path segment that would become a dot segment once decoded.
- *
- * Fails closed on a malformed escape: `decodeURIComponent` throws on overlong
- * or invalid UTF-8 (`%C0%AF`, the classic `/` smuggle), and a lenient upstream
- * decoder may still reconstruct the separator, so the segment cannot be
- * forwarded unexamined. Encoded separators themselves are allowed through —
- * `a%2Fb` is a legitimate resource id — it is only `..` between them that is
- * refused.
- *
- * @throws {TypeError} If the segment has a malformed escape or hides `..`.
- */
+// A lenient upstream decoder can rebuild `/` from `%C0%AF`: fail closed.
 function assertSafeSegment(segment) {
     let decoded;
     try {

package/esm/adapters/hono/bff/session-store.d.ts

@@ -17,8 +17,9 @@
  *
  * A raw "token in cookie" store is deliberately **not** shipped: a leaked
  * log line containing the cookie would yield a working bearer token. The
- * AES-GCM encryption in the stateless store is what makes that pattern
- * safe.
+ * AES-GCM encryption in the stateless store keeps the tokens unreadable, but
+ * a leaked encrypted cookie still works as a session cookie against the BFF
+ * until it expires.
  *
  * @module
  */
@@ -31,8 +32,8 @@ export interface SessionData {
     refreshToken?: string;
     /**
      * Cached user claims surfaced by `GET /auth/session` without exposing
-     * tokens to the browser. Populated from the id_token or the userinfo
-     * endpoint at callback time.
+     * tokens to the browser. Populated at callback time from the id_token's
+     * claims, as replaced by `HonoBffOptions.resolveUser` when configured.
      */
     user?: UserInfoClaims | null;
     /**
@@ -160,8 +161,8 @@ export interface EncryptedCookieSessionStoreOptions {
      * older secret keeps unsealing. Rotate by deploying `[newSecret, oldSecret]`,
      * then drop `oldSecret` once the grace window (at least {@linkcode maxAgeMs},
      * or your longest session lifetime) has elapsed. This is the session-store
-     * analog of a multi-key JWKS grace window. A single secret behaves exactly as
-     * before — a fleet-wide forced sign-out on rotation.
+     * analog of a multi-key JWKS grace window. With a single secret, rotating it
+     * signs everyone out.
      */
     secret: string | Uint8Array | Array<string | Uint8Array>;
     /**
@@ -181,9 +182,8 @@ export interface EncryptedCookieSessionStoreOptions {
      * milliseconds.
      *
      * The store stamps each cookie with a seal time at `create`/`update`; a
-     * pre-rotation cookie sealed before this field existed has no stamp and falls
-     * back to its own `updatedAt`, so old cookies are bounded too rather than
-     * grandfathered as unbounded.
+     * cookie without that stamp is aged from its `updatedAt` instead, so it is
+     * bounded too.
      */
     maxAgeMs?: number;
 }