@idp.global/sdk 19.2.1 → 19.4.0

package/ts_browser/index.ts

@@ -1,3 +1,4 @@
 export * from './classes.idpclient.js';
 export * from './classes.idprequests.js';
 export * from './secret-delivery.js';
+export * from './classes.relyingpartybearerclient.js';

package/ts_relyingparty/classes.authorityobserver.ts

@@ -1,6 +1,6 @@
 import { AuthorityTokenError } from './classes.errors.js';
 import { OidcAuthorityUnavailableError, type IOidcProvider } from './classes.idpoidcprovider.js';
-import type { IAuthorityTokenSource } from './interfaces.js';
+import type { IAuthorityTokenSource, IProviderToken } from './interfaces.js';
 
 /** Why an observation refused: no membership at all, or roles the application maps to nothing. */
 export type TAuthorityRefusalReason = 'idp_membership_absent' | 'idp_roles_unmapped';
@@ -58,6 +58,8 @@ export interface IAuthorityObserverOptions<TGrant> {
 const DEFAULT_MAX_ENTRIES = 2_000;
 /** how much room an eviction makes, so it does not run on every insert */
 const EVICTION_HEADROOM = 0.1;
+/** a session's token is rotated for an inactive answer at most once in this long */
+export const AUTHORITY_FORCED_REFRESH_INTERVAL_MS = 60_000;
 
 interface ICachedObservation<TGrant> {
   outcome: 'active' | 'inactive';
@@ -72,6 +74,14 @@ interface ICachedObservation<TGrant> {
   reported: boolean;
 }
 
+/** The one rotation of a session's token that an inactive answer forced. */
+interface IForcedRefresh {
+  startedAt: number;
+  /** where its start falls among the observer's inactive answers */
+  sequence: number;
+  token: Promise<IProviderToken>;
+}
+
 const assertTtl = (valueArg: number, labelArg: string): number => {
   if (!Number.isSafeInteger(valueArg) || valueArg < 0) {
     throw new Error(labelArg + ' must be a non-negative integer of milliseconds');
@@ -89,11 +99,28 @@ const assertTtl = (valueArg: number, labelArg: string): number => {
  * every attempt while the provider is unreachable. A session that is forgotten
  * while its observation is in flight never stores a positive answer. Nothing
  * runs on a timer: the cache is pruned when it is written to.
+ *
+ * idp.global answers inactive both for a login that ended and for a
+ * membership that is gone, so an inactive answer rotates the session's token
+ * (`rejectedAccessToken`) before it counts. A refused rotation is the ended
+ * login: it throws `authority_login_required` and stores nothing. Only an
+ * inactive answer on a token from a rotation that started after the
+ * observation's own inactive answer is a refusal (`idp_membership_absent`). A session's token is
+ * rotated so at most once per `AUTHORITY_FORCED_REFRESH_INTERVAL_MS`. An inactive
+ * answer that no rotation followed — it came within that time of the last
+ * one, the rotation started before it, or the source did not mark the token
+ * as its own rotation — confirms nothing: it throws `authority_unavailable`
+ * and stores nothing, and after the interval the next one rotates and
+ * decides. One monotonic sequence orders answers and rotation starts, so no
+ * token is compared with another and no clock with another's.
  */
 export class AuthorityObserver<TGrant> {
   readonly #cache = new Map<string, ICachedObservation<TGrant>>();
   readonly #inFlight = new Map<string, Promise<ICachedObservation<TGrant>>>();
   readonly #forgotten = new Set<string>();
+  readonly #forcedRefreshes = new Map<string, IForcedRefresh>();
+  /** counts inactive answers and forced rotation starts, in the order they happen */
+  #sequence = 0;
   readonly #provider: IOidcProvider;
   readonly #tokens: IAuthorityTokenSource;
   readonly #project: (rolesArg: readonly string[]) => TGrant | undefined;
@@ -149,6 +176,7 @@ export class AuthorityObserver<TGrant> {
 
   /** Drops every observation of a session; wire it to the session layer's `onSessionEnded`. */
   public forgetSession(sessionIdArg: string): void {
+    this.#forcedRefreshes.delete(sessionIdArg);
     const prefix = `${sessionIdArg} `;
     for (const key of this.#cache.keys()) {
       if (key.startsWith(prefix)) {
@@ -188,18 +216,15 @@ export class AuthorityObserver<TGrant> {
     optionsArg: { loginSessionId: string; principalId: string; idpOrganizationId: string },
   ): Promise<ICachedObservation<TGrant>> {
     const token = await this.#tokens.liveProviderToken(optionsArg.loginSessionId, optionsArg.principalId);
-    let answer: Awaited<ReturnType<IOidcProvider['introspectOrganization']>>;
-    try {
-      answer = await this.#provider.introspectOrganization({
-        accessToken: token.accessToken,
-        subject: token.subject,
-        organizationId: optionsArg.idpOrganizationId,
-      });
-    } catch (error) {
-      if (error instanceof OidcAuthorityUnavailableError) {
-        throw new AuthorityTokenError('authority_unavailable', error);
+    let answer = await this.introspect(token, optionsArg.idpOrganizationId);
+    if (!answer.active) {
+      const answeredAt = ++this.#sequence;
+      const forced = this.forcedRefresh(optionsArg.loginSessionId, optionsArg.principalId, token.accessToken);
+      const rotated = await forced.token;
+      if (forced.sequence < answeredAt || rotated.rotatedAfterRejection !== true) {
+        throw new AuthorityTokenError('authority_unavailable');
       }
-      throw error;
+      answer = await this.introspect(rotated, optionsArg.idpOrganizationId);
     }
     const grant = answer.active ? this.#project(answer.roles) : undefined;
     const active = answer.active && grant !== undefined;
@@ -228,6 +253,49 @@ export class AuthorityObserver<TGrant> {
     return entry;
   }
 
+  private async introspect(
+    tokenArg: IProviderToken,
+    organizationIdArg: string,
+  ): Promise<Awaited<ReturnType<IOidcProvider['introspectOrganization']>>> {
+    try {
+      return await this.#provider.introspectOrganization({
+        accessToken: tokenArg.accessToken,
+        subject: tokenArg.subject,
+        organizationId: organizationIdArg,
+      });
+    } catch (error) {
+      if (error instanceof OidcAuthorityUnavailableError) {
+        throw new AuthorityTokenError('authority_unavailable', error);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * The session's one forced rotation within `AUTHORITY_FORCED_REFRESH_INTERVAL_MS`,
+   * started for `rejectedArg` when there is none. Its failure is every
+   * caller's failure until the interval is over.
+   */
+  private forcedRefresh(sessionIdArg: string, principalIdArg: string, rejectedArg: string): IForcedRefresh {
+    const now = this.#now();
+    const last = this.#forcedRefreshes.get(sessionIdArg);
+    if (last && now - last.startedAt < AUTHORITY_FORCED_REFRESH_INTERVAL_MS) {
+      return last;
+    }
+    for (const [sessionId, forced] of this.#forcedRefreshes) {
+      if (now - forced.startedAt >= AUTHORITY_FORCED_REFRESH_INTERVAL_MS) {
+        this.#forcedRefreshes.delete(sessionId);
+      }
+    }
+    const forced: IForcedRefresh = {
+      startedAt: now,
+      sequence: ++this.#sequence,
+      token: this.#tokens.liveProviderToken(sessionIdArg, principalIdArg, { rejectedAccessToken: rejectedArg }),
+    };
+    this.#forcedRefreshes.set(sessionIdArg, forced);
+    return forced;
+  }
+
   /** Expired entries go first; if that is not enough, the oldest do. */
   private prune(): void {
     if (this.#cache.size <= this.#maxEntries) {

package/ts_relyingparty/classes.errors.ts

@@ -5,7 +5,17 @@ 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'
+  /** a `sessionsOfPrincipal` cursor that no page of it answered */
+  | 'invalid_sessions_cursor';
 
 const RELYING_PARTY_ERROR_STATUS: Readonly<Record<TRelyingPartyErrorCode, number>> = {
   login_method_unavailable: 404,
@@ -13,6 +23,11 @@ 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,
+  invalid_sessions_cursor: 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,25 @@
 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,
+  IRelyingPartyBearerLogoutAnswer,
+  IRelyingPartyBearerSessionAnswer,
+  IRelyingPartyBearerTokenAnswer,
+  IRelyingPartyBearerTokens,
+  IRelyingPartySession,
+  IResolvedRelyingPartySession,
+} from './interfaces.js';
 
 /**
  * The part of an HTTP request context the routes read. `IRequestContext` of
@@ -42,7 +59,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 +72,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 +108,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 +134,30 @@ 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.
+ *
+ * In bearer-only mode (`RelyingPartySessions` `cookieSessions: false`) only
+ * the bearer routes and the callback answer, and no answer sets a cookie: a
+ * callback that is no bearer login fails without clearing an intent cookie
+ * that was never set, and `login`, `finalize`, `session` and `logout` answer
+ * `null`.
+ *
  * `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 +173,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 +193,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,12 +207,21 @@ export class RelyingPartyRoutes<TPrincipal extends object | undefined = undefine
     const method = contextArg.method.toUpperCase();
     const providerLogin = this.#sessions.providerLoginEnabled;
 
-    if (path === paths.login && method === 'GET' && providerLogin) {
-      return this.login(contextArg);
+    if (this.#sessions.bearerLoginEnabled) {
+      const bearerResponse = await this.handleBearer(contextArg, path, method);
+      if (bearerResponse) {
+        return bearerResponse;
+      }
     }
     if (path === paths.callback && method === 'GET' && providerLogin) {
       return this.callback(contextArg);
     }
+    if (!this.#sessions.cookieSessionsEnabled) {
+      return null;
+    }
+    if (path === paths.login && method === 'GET' && providerLogin) {
+      return this.login(contextArg);
+    }
     if (path === paths.finalize && method === 'GET' && providerLogin) {
       let location = this.#options.failureLocation;
       try {
@@ -185,6 +268,22 @@ 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) {
+      const cookieSessions = this.#sessions.cookieSessionsEnabled;
+      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, cookieSessions ? { 'Set-Cookie': this.#sessions.clearIntentCookie() } : {});
+      }
+      if (delivery) {
+        return this.bearerCallback(callbackUrl, delivery);
+      }
+      if (!cookieSessions) {
+        return this.callbackOfNoBearerLogin(callbackUrl);
+      }
+    }
     const cookieHeader = contextArg.headers.get('cookie');
     const providerError = callbackUrl.searchParams.get('error');
     if (providerError) {
@@ -211,19 +310,244 @@ 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 of no bearer login in bearer-only mode: no attempt of this
+   * relying party can be completed with it, and no cookie is cleared because
+   * none was ever set.
+   */
+  private callbackOfNoBearerLogin(callbackUrlArg: URL): Response {
+    const providerError = callbackUrlArg.searchParams.get('error');
+    if (providerError) {
+      this.emit({ event: 'auth_callback_declined', code: providerError.slice(0, MAX_PROVIDER_ERROR_CODE_LENGTH) });
+      return redirect(this.#options.failureLocation);
+    }
+    return this.callbackFailure(new RelyingPartyError('invalid_login_callback'), {});
+  }
+
+  /** 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;
+      }
+      const answer: IRelyingPartyBearerLogoutAnswer = { endedLiveSession };
+      return answer;
+    });
+  }
+
+  /**
+   * 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);
       }
-      return jsonResponse({ error: 'authentication_failed' }, status, clearIntent);
+      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): IRelyingPartyBearerTokenAnswer {
+    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<IRelyingPartyBearerSessionAnswer> {
+    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> {
     if (contextArg.headers.get('origin') !== this.#sessions.publicOrigin) {
       return jsonResponse({ error: 'forbidden' }, 403);