@idp.global/sdk 19.2.1 → 19.3.0

package/readme.md

@@ -700,6 +700,138 @@ for (const connection of await binding.connectionsOfSession(sessionId)) {
 }
 ```
 
+### Bearer Hand-off
+
+Cookies serve the application's own pages. Clients of its own that hold no
+cookie of this origin — a desktop app, a native app, a page framed on another
+origin — sign in through the same idp.global login and receive the relying
+party's own access and refresh tokens instead. The `bearer` option turns this
+on beside the cookie login; no bearer route reads or sets a cookie.
+
+```ts
+const models = createRelyingPartyModels({ db: smartdataDb });
+await models.Session.ensureInitialized();
+await models.LoginAttempt.ensureInitialized();
+await models.BearerHandoff.ensureInitialized();
+await models.BearerToken.ensureInitialized();
+
+const sessions = new RelyingPartySessions({
+  models,
+  provider,
+  // … publicOrigin, keys, principals and hooks as above
+  bearer: {
+    returnTargets: {
+      web: ['/signed-in'],
+      loopback: ['http://127.0.0.1/callback', 'http://[::1]/callback'],
+      custom_scheme: ['com.example.app:/oauth/callback'],
+      popup: ['https://workspace.example'],
+    },
+    accessTokenMaxAgeSeconds: 900, // the default
+  },
+});
+```
+
+The flow, with the routes under the default `/auth/` prefix:
+
+1. The client makes a PKCE verifier and its S256 challenge (RFC 7636) and
+   opens `GET /auth/bearer/login?client_kind=<kind>&return_target=<target>&code_challenge=<challenge>&code_challenge_method=S256&state=<state>`.
+   `state` is optional: the client's own value of 1 to 256 characters of
+   `A-Z a-z 0-9 . _ ~ -`, handed back with the outcome. A malformed request
+   answers 400 `invalid_bearer_request`, a target that is not configured for
+   the kind 400 `return_target_not_allowed`; neither stores anything.
+2. The relying party runs the idp.global login (authorization code with PKCE,
+   as for cookies). Its `GET /auth/callback` opens the session and delivers a
+   hand-off code to the return target. The code is no token: it is valid for
+   one claim within `BEARER_HANDOFF_MAX_AGE_SECONDS` (60), bound to the
+   challenge, and only its hash is stored. `web`, `loopback` and
+   `custom_scheme` get a redirect with `code` and `state` in the query.
+   `popup` gets a page whose one nonce script posts
+   `{ type: RELYING_PARTY_BEARER_MESSAGE_TYPE, code, state }` to
+   `window.opener` with the registered origin as the target origin — never
+   `'*'` — and closes the window. A login that fails delivers `error` instead
+   of `code`: `access_denied` when the provider came back without a code, the
+   code of a `RelyingPartyRefusal` (its `location` is not followed), or
+   `authentication_failed`.
+3. The client claims with `POST /auth/bearer/claim` `{ code, codeVerifier }`.
+   The answer, as for `POST /auth/bearer/refresh` `{ refreshToken }`, is
+   `{ tokenType: 'Bearer', accessToken, accessTokenExpiresAt, expiresIn, refreshToken, refreshTokenExpiresAt, session: { sessionId, principalId, expiresAt } }`
+   (`expiresIn` in seconds, counted on the relying party's clock).
+4. `Authorization: Bearer <accessToken>` authenticates the client:
+   `GET /auth/bearer/session` answers `{ session }` (`null` without a live
+   one), and the application's own routes call
+   `sessions.resolveBearerSession(authorizationHeader)` for the live session.
+   `POST /auth/bearer/logout` ends the session of that access token, or of the
+   body's `{ refreshToken }` once the access token has expired, and answers
+   `{ endedLiveSession }`.
+
+Return targets are an exact allow-list per kind, compared by equality:
+
+- `web`: paths on the public origin outside the login routes.
+- `loopback`: `http://127.0.0.1/<path>` or `http://[::1]/<path>`, configured
+  without a port. The client names its ephemeral port, and any port matches
+  (RFC 8252 §7.3); `localhost` is not accepted.
+- `custom_scheme`: whole URIs of a private-use scheme with a dot in it (RFC
+  8252 §7.1).
+- `popup`: bare origins.
+
+The constructor refuses an entry that is not in its canonical form, carries a
+query or a fragment, or contains a `*`: nothing is a prefix and nothing is a
+wildcard.
+
+Tokens and their ends:
+
+- An access token lives `accessTokenMaxAgeSeconds` and never past its
+  session; the refresh token lives until the session ends, and no refresh
+  extends it.
+- A refresh spends its refresh token and answers a new pair; the old access
+  token stops working at once. A spent refresh token that comes back ends the
+  whole session (`refresh_token_reused`), so a client serializes its refreshes,
+  and a client that lost a refresh answer signs in again. A refused refresh
+  answers 400 `invalid_bearer_grant`.
+- The first claim consumes the code, whatever its verifier. A wrong verifier
+  ends the session (`handoff_verifier_mismatch`), a claimed code that comes
+  back ends it too (`handoff_code_reused`, RFC 6749 §4.1.2), and a code that
+  expired unclaimed ends its session when it comes back or when the next
+  bearer login sweeps it (`handoff_unclaimed`). Each answers 400
+  `invalid_bearer_handoff`; reuse is also reported as a
+  `bearer_credential_reused` event.
+- A bearer session is a provider login like a cookie session: `onSessionEnded`,
+  `endSessionsOfPrincipal` and `AuthorityObserver` apply as they are. A refresh
+  rotates the provider token when it is due and ends the session when
+  idp.global has ended the login (`invalid_bearer_grant`); an unreachable
+  provider answers 503 `authority_unavailable` and spends nothing. Until then
+  an access token works for its remaining lifetime. An application that must
+  see an idp.global logout sooner observes authority per request
+  (`authority.observe({ loginSessionId: live.session.id, … })`).
+
+The four API routes answer CORS, including the preflight, for the popup
+origins exactly and never allow credentials; every other origin gets no CORS
+header.
+
+The client side:
+
+- A web client reads `code` and `state` from its return path, removes them with
+  `history.replaceState` and claims at once. Every delivery is sent with
+  `Referrer-Policy: no-referrer`.
+- A popup client opens the login with `window.open` (without `noopener`) and
+  accepts only the message of the popup it opened, from the relying party's
+  public origin, with its own `state`:
+
+```ts
+const popup = window.open(loginUrl, 'idp-login', 'popup,width=480,height=640');
+window.addEventListener('message', async (event) => {
+  if (event.origin !== 'https://app.example' || event.source !== popup) return;
+  const message = event.data;
+  if (message?.type !== 'idp.global/relyingparty:bearer-handoff' || message.state !== state) return;
+  if (message.error) return showSignInError(message.error);
+  const tokens = await fetch('https://app.example/auth/bearer/claim', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ code: message.code, codeVerifier: verifier }),
+  }).then((response) => response.json());
+});
+```
+
 ### Testing an Application
 
 `@idp.global/sdk/relyingparty/testing` exports `RelyingPartyProviderDouble`, an
@@ -739,20 +871,37 @@ discovery. Once one has succeeded, discovery stays done, as with
 `IdpOidcProvider`; `discoveries` counts the calls. The claims of a login are
 those of its sign-in; introspection reads the persona as it is now.
 
+For bearer clients, `createBearerPkcePair()` makes a verifier and its S256
+challenge, and `readBearerDelivery(response)` reads a callback answer the way
+its client would: the `code`, `error` and `state` of a redirect's location
+(`target` is the location without its query), or a popup page's posted
+`message` and its target origin.
+
+```ts
+import { createBearerPkcePair, readBearerDelivery } from '@idp.global/sdk/relyingparty/testing';
+
+const pkce = createBearerPkcePair();
+const start = await fetch(`${appOrigin}/auth/bearer/login?client_kind=web&return_target=/signed-in&code_challenge=${pkce.challenge}&code_challenge_method=S256`, { redirect: 'manual' });
+const callback = idp.callbackUrlFor(new URL(start.headers.get('location')!), new URL('/auth/callback', appOrigin));
+const delivery = await readBearerDelivery(await fetch(callback, { redirect: 'manual' }));
+// delivery.code is claimed with pkce.verifier at /auth/bearer/claim
+```
+
 ### Relying-Party API Surface
 
 | API | Description |
 | --- | --- |
 | `IdpOidcProvider` | Discovery, PKCE authorization URL, code exchange with UserInfo, refresh, revocation and organization introspection for idp.global. Implements `IOidcProvider`. `trustedCaPem` or `fetch` for an issuer under a private CA. |
-| `createRelyingPartyModels()` | Binds the session and login-attempt models to one `SmartdataDb`, or to a function asked for it on every use, optionally under existing collection names. |
-| `RelyingPartySessions<TPrincipal>` | Login start (with an application intent and a prompt)/complete/abandon/finalize, `openSession` (with a shorter lifetime), `resolveCookieSession`, `revalidateSession`, `revalidateLiveSession`, `isSessionLive`, `validateCsrf`, `logout`/`endSession`, `endSessionsOfPrincipal`, `liveProviderToken`. Principals give `isActive` or `resolve` (`IRelyingPartyPrincipals`, `IRelyingPartyPrincipalResolver<TPrincipal>`); with `resolve`, live sessions carry `principal`. |
+| `createRelyingPartyModels()` | Binds the session, login-attempt, bearer hand-off and bearer token models to one `SmartdataDb`, or to a function asked for it on every use, optionally under existing collection names. |
+| `RelyingPartySessions<TPrincipal>` | Login start (with an application intent and a prompt)/complete/abandon/finalize, `openSession` (with a shorter lifetime), `resolveCookieSession`, `revalidateSession`, `revalidateLiveSession`, `isSessionLive`, `validateCsrf`, `logout`/`endSession`, `endSessionsOfPrincipal`, `liveProviderToken`. Principals give `isActive` or `resolve` (`IRelyingPartyPrincipals`, `IRelyingPartyPrincipalResolver<TPrincipal>`); with `resolve`, live sessions carry `principal`. With `bearer`: `startBearerLogin`, `bearerDeliveryOf`, `completeBearerLogin`, `abandonBearerLogin`, `claimBearerHandoff`, `refreshBearerTokens`, `resolveBearerAccessToken`, `resolveBearerSession`, `endBearerSession`. |
 | `AuthorityObserver` | Live organization authority with opt-in positive and negative reuse. |
-| `RelyingPartyRoutes` | `handle(ctx)` for `/auth/login`, `/auth/callback`, `/auth/finalize`, `/auth/session` and `/auth/logout`; `null` for anything else. Takes a typedserver route context. `onLogout` is awaited after a CSRF-checked logout ended the session. |
+| `RelyingPartyRoutes` | `handle(ctx)` for `/auth/login`, `/auth/callback`, `/auth/finalize`, `/auth/session` and `/auth/logout`; `null` for anything else. Takes a typedserver route context. `onLogout` is awaited after a CSRF-checked logout ended the session. In bearer mode also `/auth/bearer/login`, `/auth/bearer/claim`, `/auth/bearer/refresh`, `/auth/bearer/session` and `/auth/bearer/logout`, with CORS for the popup origins only. |
 | `createActorScope()` | AsyncLocalStorage actor context with a TypedRouter request scope. |
 | `RelyingPartySocketBinding` | TypedSocket browser registration, per-request re-validation and session tags; takes a connection wrapper or its peer. |
 | `SecretBox`, `deriveCsrfToken()`, `decodeSecretKey()`, `parseCookies()`, `serializeCookie()`, `sanitizeReturnPath()` | The primitives underneath. |
+| `pkceChallengeOf()`, `verifyPkceChallenge()`, `parseBearerAuthorization()`, `isBearerReturnTargetAllowed()`, `RELYING_PARTY_BEARER_MESSAGE_TYPE`, `BEARER_HANDOFF_MAX_AGE_SECONDS` | The bearer primitives: S256, the `Authorization` header, the return-target match and the popup message type. |
 | `RelyingPartyError`, `RelyingPartyRefusal`, `LoginCallbackError`, `AuthorityTokenError`, `AuthorityRefusedError`, `RelyingPartyDatabaseUnavailableError` | Errors with stable codes; none carries token material. A `RelyingPartyRefusal` may name the application's `location` for the browser. |
-| `RelyingPartyProviderDouble` (`/relyingparty/testing`) | An in-process idp.global for an application's tests: personas, live organization roles, single-use codes, rotating and reuse-detecting refresh tokens, recorded calls and injectable failures. |
+| `RelyingPartyProviderDouble` (`/relyingparty/testing`) | An in-process idp.global for an application's tests: personas, live organization roles, single-use codes, rotating and reuse-detecting refresh tokens, recorded calls and injectable failures. `createBearerPkcePair()` and `readBearerDelivery()` for bearer clients. |
 
 ## Runtime Notes
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@idp.global/sdk',
-  version: '19.2.1',
+  version: '19.3.0',
   description: 'Reusable browser and server SDK for idp.global authentication.'
 }

package/ts_relyingparty/classes.errors.ts

@@ -5,7 +5,15 @@ export type TRelyingPartyErrorCode =
   | 'invalid_login_callback'
   | 'missing_login_intent'
   | 'invalid_or_replayed_login'
-  | 'invalid_login_finalize';
+  | 'invalid_login_finalize'
+  /** a bearer login start the relying party cannot accept: a missing or malformed parameter */
+  | 'invalid_bearer_request'
+  /** a bearer client named a return target that is not configured for its kind, exactly */
+  | 'return_target_not_allowed'
+  /** a hand-off code that is unknown, expired, already claimed, or claimed with the wrong verifier */
+  | 'invalid_bearer_handoff'
+  /** a refresh token that is unknown, rotated, expired, or of a session that is over */
+  | 'invalid_bearer_grant';
 
 const RELYING_PARTY_ERROR_STATUS: Readonly<Record<TRelyingPartyErrorCode, number>> = {
   login_method_unavailable: 404,
@@ -13,6 +21,10 @@ const RELYING_PARTY_ERROR_STATUS: Readonly<Record<TRelyingPartyErrorCode, number
   missing_login_intent: 400,
   invalid_or_replayed_login: 400,
   invalid_login_finalize: 400,
+  invalid_bearer_request: 400,
+  return_target_not_allowed: 400,
+  invalid_bearer_handoff: 400,
+  invalid_bearer_grant: 400,
 };
 
 /** A request the login flow refuses; the code is safe to answer, the browser learns nothing more. */

package/ts_relyingparty/classes.relyingpartyroutes.ts

@@ -1,8 +1,22 @@
 import * as plugins from './plugins.js';
-import { LoginCallbackError, RelyingPartyError, RelyingPartyRefusal } from './classes.errors.js';
+import { AuthorityTokenError, LoginCallbackError, RelyingPartyError, RelyingPartyRefusal } from './classes.errors.js';
 import type { RelyingPartySessions } from './classes.relyingpartysessions.js';
+import {
+  bearerDeliveryLocation,
+  bearerPopupContentSecurityPolicy,
+  bearerPopupPage,
+  parseBearerAuthorization,
+  type TRelyingPartyBearerOutcome,
+} from './helpers.bearer.js';
+import { randomToken } from './helpers.crypto.js';
 import { sanitizeReturnPath } from './helpers.returnpath.js';
-import type { IRelyingPartySession, IResolvedRelyingPartySession } from './interfaces.js';
+import type {
+  IRelyingPartyBearerDelivery,
+  IRelyingPartyBearerLoginRequest,
+  IRelyingPartyBearerTokens,
+  IRelyingPartySession,
+  IResolvedRelyingPartySession,
+} from './interfaces.js';
 
 /**
  * The part of an HTTP request context the routes read. `IRequestContext` of
@@ -42,7 +56,7 @@ export interface IRelyingPartyRoutesOptions<TPrincipal extends object | undefine
    * never changes the answer — it is reported as a `hook_failed` route event.
    */
   onLogout?(eventArg: { session: IRelyingPartySession; endedLiveSession: boolean }): Promise<void>;
-  /** the largest logout body read, in bytes; a longer one is cancelled as soon as it passes the limit */
+  /** the largest logout, claim or refresh body read, in bytes; a longer one is cancelled as soon as it passes the limit */
   maxBodyBytes?: number;
   /**
    * diagnostics of a failed start or callback; the default writes one JSON
@@ -55,6 +69,10 @@ export interface IRelyingPartyRoutesOptions<TPrincipal extends object | undefine
       | 'auth_callback_failed'
       | 'auth_callback_declined'
       | 'auth_callback_refused'
+      /** a bearer login start named something the relying party does not accept; `code` says what */
+      | 'auth_bearer_start_refused'
+      /** a bearer claim, refresh, session or logout failed for a reason other than its credential */
+      | 'auth_bearer_failed'
       /** an application hook of the routes threw; the step it belonged to is complete */
       | 'hook_failed';
     hook?: 'onLogout';
@@ -87,6 +105,19 @@ const jsonResponse = (bodyArg: object, statusArg: number, headersArg?: Record<st
 const redirect = (locationArg: string, headersArg?: Record<string, string>): Response =>
   new Response(null, { status: 302, headers: noStoreHeaders({ Location: locationArg, ...headersArg }) });
 
+/** A JSON body's field, or `undefined` for anything that is not an object holding it. */
+const bodyField = (bodyArg: unknown, nameArg: string): unknown =>
+  bodyArg && typeof bodyArg === 'object' && Object.hasOwn(bodyArg, nameArg) ? Reflect.get(bodyArg, nameArg) : undefined;
+
+/** A query parameter given once; `null` when it is repeated, so it never passes as given. */
+const singleParam = (paramsArg: URLSearchParams, nameArg: string): string | null | undefined => {
+  const all = paramsArg.getAll(nameArg);
+  return all.length === 0 ? undefined : all.length === 1 ? all[0] : null;
+};
+
+/** The routes a bearer client calls with `fetch`, possibly from a popup client's origin. */
+type TBearerApiRoute = 'bearerClaim' | 'bearerRefresh' | 'bearerSession' | 'bearerLogout';
+
 /**
  * The HTTP steps of a relying-party login, all under the sessions' login path
  * prefix (default `/auth/`):
@@ -100,6 +131,24 @@ const redirect = (locationArg: string, headersArg?: Record<string, string>): Res
  * - `POST logout` ends the session; it needs this origin and the CSRF token,
  *   and `onLogout` runs before it answers
  *
+ * With bearer mode on (`RelyingPartySessions` `bearer`), the routes of the
+ * application's own clients join them; none of them reads or sets a cookie:
+ *
+ * - `GET bearer/login?client_kind=…&return_target=…&code_challenge=…&code_challenge_method=S256[&state=…]`
+ *   redirects to the provider
+ * - `GET callback` answers a bearer login's callback by delivering the
+ *   hand-off code — or the `error` — to the return target: a redirect with
+ *   `code` (or `error`) and `state` in the query, or for a popup a page that
+ *   posts them to its opener at the registered origin
+ * - `POST bearer/claim` `{ code, codeVerifier }` and `POST bearer/refresh`
+ *   `{ refreshToken }` answer the tokens
+ * - `GET bearer/session` answers the session of `Authorization: Bearer <access token>`
+ * - `POST bearer/logout` ends the session of the `Authorization` access token
+ *   or of the body's `{ refreshToken }`
+ *
+ * The four API routes answer CORS requests from the popup return targets'
+ * origins, exactly, and no others; they never allow credentials.
+ *
  * `handle()` answers `null` for every other request, so the application
  * chains its own routes (a local password login) around it. Cookies are only
  * ever set here: a `/typedrequest` answer cannot carry `Set-Cookie`.
@@ -115,8 +164,19 @@ export class RelyingPartyRoutes<TPrincipal extends object | undefined = undefine
     this.#maxBodyBytes = optionsArg.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
   }
 
-  /** The paths the routes answer, for registering them one by one. */
-  public get paths(): { login: string; callback: string; finalize: string; session: string; logout: string } {
+  /** The paths the routes answer, for registering them one by one; the `bearer…` paths answer only in bearer mode. */
+  public get paths(): {
+    login: string;
+    callback: string;
+    finalize: string;
+    session: string;
+    logout: string;
+    bearerLogin: string;
+    bearerClaim: string;
+    bearerRefresh: string;
+    bearerSession: string;
+    bearerLogout: string;
+  } {
     const prefix = this.#sessions.loginPathPrefix;
     return {
       login: prefix + 'login',
@@ -124,6 +184,11 @@ export class RelyingPartyRoutes<TPrincipal extends object | undefined = undefine
       finalize: prefix + 'finalize',
       session: prefix + 'session',
       logout: prefix + 'logout',
+      bearerLogin: prefix + 'bearer/login',
+      bearerClaim: prefix + 'bearer/claim',
+      bearerRefresh: prefix + 'bearer/refresh',
+      bearerSession: prefix + 'bearer/session',
+      bearerLogout: prefix + 'bearer/logout',
     };
   }
 
@@ -133,6 +198,12 @@ export class RelyingPartyRoutes<TPrincipal extends object | undefined = undefine
     const method = contextArg.method.toUpperCase();
     const providerLogin = this.#sessions.providerLoginEnabled;
 
+    if (this.#sessions.bearerLoginEnabled) {
+      const bearerResponse = await this.handleBearer(contextArg, path, method);
+      if (bearerResponse) {
+        return bearerResponse;
+      }
+    }
     if (path === paths.login && method === 'GET' && providerLogin) {
       return this.login(contextArg);
     }
@@ -185,6 +256,18 @@ export class RelyingPartyRoutes<TPrincipal extends object | undefined = undefine
   private async callback(contextArg: IRelyingPartyHttpContext): Promise<Response> {
     // the callback is read from the public origin, never from a forwarded host
     const callbackUrl = new URL(contextArg.url.pathname + contextArg.url.search, this.#sessions.publicOrigin);
+    if (this.#sessions.bearerLoginEnabled) {
+      let delivery: IRelyingPartyBearerDelivery | null;
+      try {
+        delivery = await this.#sessions.bearerDeliveryOf(callbackUrl);
+      } catch (error) {
+        // unknown whose callback this is: answered as the cookie path answers a failure
+        return this.callbackFailure(error, { 'Set-Cookie': this.#sessions.clearIntentCookie() });
+      }
+      if (delivery) {
+        return this.bearerCallback(callbackUrl, delivery);
+      }
+    }
     const cookieHeader = contextArg.headers.get('cookie');
     const providerError = callbackUrl.searchParams.get('error');
     if (providerError) {
@@ -211,17 +294,227 @@ export class RelyingPartyRoutes<TPrincipal extends object | undefined = undefine
         }
         return jsonResponse({ error: 'authentication_failed' }, error.status, clearIntent);
       }
-      const status = error instanceof RelyingPartyError ? error.status : 502;
-      if (status >= 500) {
-        this.emit({
-          event: 'auth_callback_failed',
-          correlationId: plugins.crypto.randomUUID(),
-          stage: error instanceof LoginCallbackError ? error.stage : 'unclassified',
-          message: error instanceof Error ? error.message : String(error),
-        });
+      return this.callbackFailure(error, clearIntent);
+    }
+  }
+
+  /** A callback that failed for a reason other than a refusal: reported when it is the relying party's fault. */
+  private callbackFailure(errorArg: unknown, headersArg: Record<string, string>): Response {
+    const status = this.callbackFailureStatus(errorArg);
+    return jsonResponse({ error: 'authentication_failed' }, status, headersArg);
+  }
+
+  private callbackFailureStatus(errorArg: unknown): number {
+    const status = errorArg instanceof RelyingPartyError ? errorArg.status : 502;
+    if (status >= 500) {
+      this.emit({
+        event: 'auth_callback_failed',
+        correlationId: plugins.crypto.randomUUID(),
+        stage: errorArg instanceof LoginCallbackError ? errorArg.stage : 'unclassified',
+        message: errorArg instanceof Error ? errorArg.message : String(errorArg),
+      });
+    }
+    return status;
+  }
+
+  // ==========================================================================
+  // bearer hand-off
+  // ==========================================================================
+
+  private async handleBearer(contextArg: IRelyingPartyHttpContext, pathArg: string, methodArg: string): Promise<Response | null> {
+    const paths = this.paths;
+    if (pathArg === paths.bearerLogin) {
+      return methodArg === 'GET' ? this.bearerLogin(contextArg) : null;
+    }
+    const route = (['bearerClaim', 'bearerRefresh', 'bearerSession', 'bearerLogout'] as const)
+      .find((routeArg: TBearerApiRoute) => paths[routeArg] === pathArg);
+    if (!route) {
+      return null;
+    }
+    const corsHeaders = this.bearerCorsHeaders(contextArg);
+    if (methodArg === 'OPTIONS') {
+      if (!corsHeaders) {
+        return jsonResponse({ error: 'forbidden' }, 403, { Vary: 'Origin' });
+      }
+      return new Response(null, {
+        status: 204,
+        headers: noStoreHeaders({
+          ...corsHeaders,
+          'Access-Control-Allow-Methods': 'GET, POST',
+          'Access-Control-Allow-Headers': 'authorization, content-type',
+          'Access-Control-Max-Age': '600',
+        }),
+      });
+    }
+    const headers = corsHeaders ?? { Vary: 'Origin' };
+    if (route === 'bearerSession') {
+      return methodArg === 'GET' ? this.bearerApi(headers, () => this.bearerSessionAnswer(contextArg)) : null;
+    }
+    if (methodArg !== 'POST') {
+      return null;
+    }
+    if (route === 'bearerClaim') {
+      return this.bearerApi(headers, async () => {
+        const body = await this.readJsonBody(contextArg);
+        return this.bearerTokenAnswer(
+          await this.#sessions.claimBearerHandoff(bodyField(body, 'code'), bodyField(body, 'codeVerifier')),
+        );
+      });
+    }
+    if (route === 'bearerRefresh') {
+      return this.bearerApi(headers, async () => {
+        const body = await this.readJsonBody(contextArg);
+        return this.bearerTokenAnswer(await this.#sessions.refreshBearerTokens(bodyField(body, 'refreshToken')));
+      });
+    }
+    return this.bearerApi(headers, async () => {
+      const accessToken = parseBearerAuthorization(contextArg.headers.get('authorization'));
+      let endedLiveSession = accessToken ? await this.#sessions.endBearerSession(accessToken) : false;
+      if (!endedLiveSession) {
+        const refreshToken = bodyField(await this.readJsonBody(contextArg), 'refreshToken');
+        endedLiveSession = refreshToken !== undefined ? await this.#sessions.endBearerSession(refreshToken) : false;
       }
-      return jsonResponse({ error: 'authentication_failed' }, status, clearIntent);
+      return { endedLiveSession };
+    });
+  }
+
+  /**
+   * The CORS answer for a request from a popup return target's origin, which
+   * is matched exactly; `null` for every other origin, which gets none.
+   * Credentials are never allowed: bearer mode carries no cookie.
+   */
+  private bearerCorsHeaders(contextArg: IRelyingPartyHttpContext): Record<string, string> | null {
+    const origin = contextArg.headers.get('origin');
+    const popupOrigins = this.#sessions.bearerReturnTargets?.popup ?? [];
+    if (origin === null || !popupOrigins.includes(origin)) {
+      return null;
     }
+    return { 'Access-Control-Allow-Origin': origin, Vary: 'Origin' };
+  }
+
+  private async bearerLogin(contextArg: IRelyingPartyHttpContext): Promise<Response> {
+    const query = contextArg.url.searchParams;
+    const state = singleParam(query, 'state');
+    // every field is checked by startBearerLogin, which takes them as untrusted input
+    const request = {
+      clientKind: singleParam(query, 'client_kind'),
+      returnTarget: singleParam(query, 'return_target'),
+      codeChallenge: singleParam(query, 'code_challenge'),
+      codeChallengeMethod: singleParam(query, 'code_challenge_method'),
+      ...(state !== undefined ? { state } : {}),
+    } as unknown as IRelyingPartyBearerLoginRequest;
+    try {
+      const start = await this.#sessions.startBearerLogin(request);
+      return redirect(start.authorizationUrl.href, { 'Referrer-Policy': 'no-referrer' });
+    } catch (error) {
+      if (error instanceof RelyingPartyError && error.status < 500) {
+        this.emit({ event: 'auth_bearer_start_refused', code: error.code });
+        return jsonResponse({ error: error.code }, error.status);
+      }
+      this.emit({ event: 'auth_login_start_failed', message: error instanceof Error ? error.message : String(error) });
+      return jsonResponse({ error: 'authentication_unavailable' }, 503);
+    }
+  }
+
+  /**
+   * The callback of a bearer login, delivered to its return target whatever
+   * the outcome: the hand-off code, `access_denied` when the provider came
+   * back without one, the code of an application refusal (its `location` is
+   * a page of the cookie flow and not followed), or `authentication_failed`.
+   */
+  private async bearerCallback(callbackUrlArg: URL, deliveryArg: IRelyingPartyBearerDelivery): Promise<Response> {
+    const providerError = callbackUrlArg.searchParams.get('error');
+    if (providerError) {
+      await this.#sessions.abandonBearerLogin(callbackUrlArg);
+      this.emit({ event: 'auth_callback_declined', code: providerError.slice(0, MAX_PROVIDER_ERROR_CODE_LENGTH) });
+      return this.deliverBearerOutcome(deliveryArg, { error: 'access_denied' });
+    }
+    try {
+      const handoff = await this.#sessions.completeBearerLogin(callbackUrlArg);
+      return this.deliverBearerOutcome(handoff.delivery, { code: handoff.code });
+    } catch (error) {
+      if (error instanceof RelyingPartyRefusal) {
+        this.emit({ event: 'auth_callback_refused', code: error.code });
+        return this.deliverBearerOutcome(deliveryArg, { error: error.code });
+      }
+      this.callbackFailureStatus(error);
+      return this.deliverBearerOutcome(deliveryArg, { error: 'authentication_failed' });
+    }
+  }
+
+  /**
+   * A redirect to the return target with the outcome in its query, or for a
+   * popup the page that posts it to the opener. Neither sends a referrer, and
+   * the popup page runs its one nonce script and nothing else.
+   */
+  private deliverBearerOutcome(deliveryArg: IRelyingPartyBearerDelivery, outcomeArg: TRelyingPartyBearerOutcome): Response {
+    if (deliveryArg.clientKind !== 'popup') {
+      return redirect(
+        bearerDeliveryLocation(deliveryArg, outcomeArg, this.#sessions.publicOrigin),
+        { 'Referrer-Policy': 'no-referrer' },
+      );
+    }
+    const nonce = randomToken(16);
+    return new Response(bearerPopupPage(deliveryArg, outcomeArg, nonce), {
+      status: 200,
+      headers: noStoreHeaders({
+        'Content-Type': 'text/html; charset=utf-8',
+        'Content-Security-Policy': bearerPopupContentSecurityPolicy(nonce),
+        'X-Content-Type-Options': 'nosniff',
+        'Referrer-Policy': 'no-referrer',
+      }),
+    });
+  }
+
+  /**
+   * Runs one bearer API step and answers its JSON. A refused credential
+   * answers its code with 400; an unreachable provider answers
+   * `authority_unavailable` with 503 and spends nothing; any other failure is
+   * reported and answers `authentication_unavailable`.
+   */
+  private async bearerApi(headersArg: Record<string, string>, stepArg: () => Promise<object>): Promise<Response> {
+    try {
+      return jsonResponse(await stepArg(), 200, headersArg);
+    } catch (error) {
+      if (error instanceof RelyingPartyError && error.status < 500) {
+        return jsonResponse({ error: error.code }, error.status, headersArg);
+      }
+      if (error instanceof AuthorityTokenError && error.code === 'authority_unavailable') {
+        return jsonResponse({ error: error.code }, error.status, headersArg);
+      }
+      this.emit({
+        event: 'auth_bearer_failed',
+        correlationId: plugins.crypto.randomUUID(),
+        message: error instanceof Error ? error.message : String(error),
+      });
+      return jsonResponse({ error: 'authentication_unavailable' }, 503, headersArg);
+    }
+  }
+
+  private bearerTokenAnswer(tokensArg: IRelyingPartyBearerTokens): object {
+    return {
+      tokenType: 'Bearer',
+      accessToken: tokensArg.accessToken,
+      accessTokenExpiresAt: tokensArg.accessTokenExpiresAt,
+      // counted on the relying party's clock, so a client with another clock can use it
+      expiresIn: Math.max(0, Math.floor((tokensArg.accessTokenExpiresAt - tokensArg.issuedAt) / 1_000)),
+      refreshToken: tokensArg.refreshToken,
+      refreshTokenExpiresAt: tokensArg.refreshTokenExpiresAt,
+      session: {
+        sessionId: tokensArg.session.id,
+        principalId: tokensArg.session.principalId,
+        expiresAt: tokensArg.session.expiresAt,
+      },
+    };
+  }
+
+  private async bearerSessionAnswer(contextArg: IRelyingPartyHttpContext): Promise<object> {
+    const live = await this.#sessions.resolveBearerSession(contextArg.headers.get('authorization'));
+    return {
+      session: live
+        ? { sessionId: live.session.id, principalId: live.session.principalId, expiresAt: live.session.expiresAt }
+        : null,
+    };
   }
 
   private async logout(contextArg: IRelyingPartyHttpContext): Promise<Response> {