@idp.global/sdk 19.2.1 → 19.4.0

package/ts_relyingparty/classes.relyingpartysessions.ts

@@ -14,13 +14,36 @@ import {
   type IOidcRefreshedTokens,
   type TOidcTokenHint,
 } from './classes.idpoidcprovider.js';
-import type { IRelyingPartyModels, RelyingPartyLoginAttemptDoc, RelyingPartySessionDoc } from './classes.rpmodels.js';
+import type {
+  IRelyingPartyBearerModels,
+  IRelyingPartyModels,
+  RelyingPartyBearerHandoffDoc,
+  RelyingPartyLoginAttemptDoc,
+  RelyingPartySessionDoc,
+} from './classes.rpmodels.js';
+import {
+  isBearerClientKind,
+  isBearerClientState,
+  isBearerReturnTargetAllowed,
+  isPkceChallenge,
+  isPkceVerifier,
+  normalizeBearerReturnTargets,
+  parseBearerAuthorization,
+  verifyPkceChallenge,
+} from './helpers.bearer.js';
 import { parseCookies, serializeClearedCookie, serializeCookie } from './helpers.cookies.js';
 import { deriveCsrfToken, randomToken, sha256, timingSafeEqualString } from './helpers.crypto.js';
 import { sanitizeReturnPath } from './helpers.returnpath.js';
 import type {
   IAuthorityTokenSource,
   IProviderToken,
+  IRelyingPartyBearerDelivery,
+  IRelyingPartyBearerHandoff,
+  IRelyingPartyBearerLoginRequest,
+  IRelyingPartyBearerLoginStart,
+  IRelyingPartyBearerOptions,
+  IRelyingPartyBearerReturnTargets,
+  IRelyingPartyBearerTokens,
   IRelyingPartyEvent,
   IRelyingPartyHooks,
   IRelyingPartyAdmission,
@@ -29,6 +52,8 @@ import type {
   IRelyingPartyLoginStart,
   IRelyingPartySession,
   IRelyingPartySessionOpening,
+  IRelyingPartySessionsPage,
+  IRelyingPartySessionsPageOptions,
   IResolvedRelyingPartySession,
   TLoginCallbackStage,
   TRelyingPartyPrincipals,
@@ -46,10 +71,22 @@ const SESSION_TOUCH_INTERVAL_MS = 60_000;
 export const LOGIN_ATTEMPT_MAX_AGE_SECONDS = 10 * 60;
 /** The longest intent a login carries (`IRelyingPartyLoginOptions.intent`), in characters. */
 export const RELYING_PARTY_MAX_INTENT_LENGTH = 4_096;
-/** Attempts are swept once they are this much older than their expiry. */
+/** Attempts — and bearer hand-offs, token generations and sessions — are swept once they are this much older than their expiry. */
 const LOGIN_ATTEMPT_SWEEP_GRACE_MS = 60 * 60 * 1_000;
 /** How many of them one sign-in removes; the next sign-in takes the following page. */
 const LOGIN_ATTEMPT_SWEEP_BATCH = 100;
+/** How many sessions one page of `sessionsOfPrincipal` holds unless its `limit` says otherwise. */
+export const RELYING_PARTY_DEFAULT_SESSIONS_PAGE_LIMIT = 100;
+/** The largest `limit` of `sessionsOfPrincipal`; the store reads no larger page. */
+export const RELYING_PARTY_MAX_SESSIONS_PAGE_LIMIT = 1_000;
+/** A `sessionsOfPrincipal` cursor is a short base64url text; anything far longer is none. */
+const MAX_SESSIONS_CURSOR_LENGTH = 512;
+/** How long a bearer hand-off code can be claimed, at most; never past its session. */
+export const BEARER_HANDOFF_MAX_AGE_SECONDS = 60;
+/** How long a bearer access token lives unless `bearer.accessTokenMaxAgeSeconds` says otherwise. */
+export const RELYING_PARTY_DEFAULT_BEARER_ACCESS_TOKEN_MAX_AGE_SECONDS = 15 * 60;
+/** The codes and tokens of bearer mode are 43 characters; anything far longer is none of them. */
+const MAX_BEARER_TOKEN_LENGTH = 256;
 /**
  * How long ending a session waits for the provider to take its tokens back.
  * The local session is already revoked when that call runs.
@@ -78,6 +115,12 @@ export interface IRelyingPartySessionsOptions<TPrincipal extends object | undefi
   sessionEncryptionKey: Buffer;
   /** 32 bytes; the CSRF HMAC key */
   csrfKey: Buffer;
+  /**
+   * `true` (the default): cookie sessions with a session-bound CSRF token,
+   * beside bearer hand-off mode when `bearer` is given. Bearer hand-off alone,
+   * without any cookie, is `IRelyingPartyBearerOnlySessionsOptions`.
+   */
+  cookieSessions?: true;
   /** the label the CSRF HMAC starts with; an application with live sessions keeps its own */
   csrfLabel?: string;
   sessionMaxAgeSeconds?: number;
@@ -92,13 +135,130 @@ export interface IRelyingPartySessionsOptions<TPrincipal extends object | undefi
   };
   /** the prefix of the login routes; a login never returns into it */
   loginPathPrefix?: string;
+  /**
+   * absent: no bearer hand-off mode. Needs `provider` and the bearer models
+   * (`createRelyingPartyModels` binds them).
+   */
+  bearer?: IRelyingPartyBearerOptions;
   hooks?: IRelyingPartyHooks;
   /** the clock every comparison reads; tests step it instead of sleeping */
   now?: () => number;
 }
 
+/**
+ * Bearer-only mode (`cookieSessions: false`): the application's own clients
+ * sign in through bearer hand-off and nothing else. The relying party never
+ * reads or sets a cookie — not even the clearing intent cookie of a callback
+ * that is no bearer login — so it has no CSRF token and takes no CSRF key:
+ * `csrfKey`, `csrfLabel` and `cookieNames` are refused, not ignored. The
+ * cookie steps (`openSession`, `startLogin`, `completeLogin`, `abandonLogin`,
+ * `finalizeLogin`, `clearSessionCookie`, `clearIntentCookie`) throw
+ * `RelyingPartyError('login_method_unavailable')` and `resolveCookieSession`
+ * answers `null`.
+ */
+export interface IRelyingPartyBearerOnlySessionsOptions<TPrincipal extends object | undefined = undefined>
+  extends Omit<IRelyingPartySessionsOptions<TPrincipal>, 'provider' | 'csrfKey' | 'csrfLabel' | 'cookieNames' | 'cookieSessions' | 'bearer'> {
+  cookieSessions: false;
+  /** every bearer session is a provider login */
+  provider: IOidcProvider;
+  bearer: IRelyingPartyBearerOptions;
+  csrfKey?: never;
+  csrfLabel?: never;
+  cookieNames?: never;
+}
+
 type TSealedTokens = Pick<RelyingPartySessionDoc, 'sealedAccessToken' | 'sealedRefreshToken'>;
 
+/** Cookie sessions as the constructor checked them; absent in bearer-only mode. */
+interface ICookieSessionsMode {
+  csrfKey: Buffer;
+  csrfLabel: string;
+}
+
+/** Bearer hand-off mode as the constructor checked it. */
+interface IBearerMode {
+  returnTargets: Readonly<Required<IRelyingPartyBearerReturnTargets>>;
+  accessTokenMaxAgeSeconds: number;
+  models: IRelyingPartyBearerModels;
+}
+
+const bearerModeOf = (
+  bearerArg: IRelyingPartyBearerOptions,
+  optionsArg: { models: IRelyingPartyModels; hasProvider: boolean; publicOrigin: string; loginPathPrefix: string; sessionMaxAgeSeconds: number },
+): IBearerMode => {
+  if (!bearerArg || typeof bearerArg !== 'object') {
+    throw new Error('bearer must be an object with returnTargets');
+  }
+  if (!optionsArg.hasProvider) {
+    throw new Error('bearer needs a provider: every bearer session is a provider login');
+  }
+  const { BearerHandoff, BearerToken } = optionsArg.models;
+  if (!BearerHandoff || !BearerToken) {
+    throw new Error('bearer needs the BearerHandoff and BearerToken models; createRelyingPartyModels binds them');
+  }
+  const accessTokenMaxAgeSeconds = bearerArg.accessTokenMaxAgeSeconds
+    ?? Math.min(RELYING_PARTY_DEFAULT_BEARER_ACCESS_TOKEN_MAX_AGE_SECONDS, optionsArg.sessionMaxAgeSeconds);
+  if (
+    !Number.isSafeInteger(accessTokenMaxAgeSeconds)
+    || accessTokenMaxAgeSeconds < 1
+    || accessTokenMaxAgeSeconds > optionsArg.sessionMaxAgeSeconds
+  ) {
+    throw new Error(`bearer.accessTokenMaxAgeSeconds must be a whole number from 1 to ${optionsArg.sessionMaxAgeSeconds}`);
+  }
+  return {
+    returnTargets: normalizeBearerReturnTargets(bearerArg.returnTargets, optionsArg.publicOrigin, optionsArg.loginPathPrefix),
+    accessTokenMaxAgeSeconds,
+    models: { BearerHandoff, BearerToken },
+  };
+};
+
+/** The one `state` of a callback, or `null` when it carries none or several. */
+const singleStateOf = (callbackUrlArg: URL): string | null => {
+  const states = callbackUrlArg.searchParams.getAll('state');
+  return states.length === 1 && states[0] ? states[0] : null;
+};
+
+/** A code or token of bearer mode as a client presents it, or `null` when it cannot be one. */
+const bearerCredentialOf = (valueArg: unknown): string | null =>
+  typeof valueArg === 'string' && valueArg.length > 0 && valueArg.length <= MAX_BEARER_TOKEN_LENGTH ? valueArg : null;
+
+/** Where a `sessionsOfPrincipal` page ends: its last session's `createdAt` and `id`. */
+interface ISessionsCursor {
+  sortValue: number;
+  uniqueValue: string;
+}
+
+const serializeSessionsCursor = (cursorArg: { sortValue: number | string; uniqueValue: string }): string =>
+  Buffer.from(JSON.stringify([cursorArg.sortValue, cursorArg.uniqueValue]), 'utf8').toString('base64url');
+
+/**
+ * The position a cursor of `sessionsOfPrincipal` names. It seeks within the
+ * principal's own sessions only, so it needs no seal; anything that is not
+ * such a position is refused.
+ */
+const parseSessionsCursor = (cursorArg: unknown): ISessionsCursor => {
+  if (typeof cursorArg !== 'string' || cursorArg.length > MAX_SESSIONS_CURSOR_LENGTH || !/^[A-Za-z0-9_-]+$/.test(cursorArg)) {
+    throw new RelyingPartyError('invalid_sessions_cursor');
+  }
+  let position: unknown;
+  try {
+    position = JSON.parse(Buffer.from(cursorArg, 'base64url').toString('utf8'));
+  } catch {
+    throw new RelyingPartyError('invalid_sessions_cursor');
+  }
+  if (
+    !Array.isArray(position)
+    || position.length !== 2
+    || !Number.isSafeInteger(position[0])
+    || position[0] < 0
+    || typeof position[1] !== 'string'
+    || position[1] === ''
+  ) {
+    throw new RelyingPartyError('invalid_sessions_cursor');
+  }
+  return { sortValue: position[0], uniqueValue: position[1] };
+};
+
 const REVOKED_TOKEN_FIELDS = { sealedAccessToken: '', sealedRefreshToken: '', refreshLockUntil: 0 };
 
 const errorMessage = (errorArg: unknown): string => (errorArg instanceof Error ? errorArg.message : String(errorArg));
@@ -130,9 +290,16 @@ const cookieNameFor = (
  * token, provider tokens sealed at rest and rotated under a cross-replica
  * lock, and session ends that hand the tokens back.
  *
- * Nothing here runs on a timer: expired login attempts are swept when the next
- * login starts, and the only timer — the revocation budget — is unreferenced
- * and cleared on every path. Nothing here does I/O while it is constructed,
+ * With `cookieSessions: false` it runs bearer hand-off mode alone and never
+ * touches a cookie (`IRelyingPartyBearerOnlySessionsOptions`).
+ *
+ * Nothing here runs on a timer: expired login attempts, bearer state and
+ * ended sessions are swept one bounded batch at a time when a login starts or
+ * the application opens a session, and the only timer — the revocation
+ * budget — is unreferenced and cleared on every path. Every session comes
+ * from a login start or from `openSession`, and each of those sweeps a batch
+ * of at least one first, so removal keeps pace with creation and the ended
+ * sessions kept stay bounded. Nothing here does I/O while it is constructed,
  * so it is built before the database connects.
  *
  * `TPrincipal` is what a `principals.resolve` answers; with `isActive`
@@ -150,21 +317,36 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
   /** the principal of a session when it may act right now, `null` otherwise */
   readonly #activePrincipal: (principalIdArg: string) => Promise<{ principal: TPrincipal } | null>;
   readonly #provider?: IOidcProvider;
+  readonly #bearer?: IBearerMode;
   readonly #secretBox: SecretBox;
-  readonly #csrfKey: Buffer;
-  readonly #csrfLabel: string;
+  readonly #cookieSessions: ICookieSessionsMode | null;
   readonly #hooks: IRelyingPartyHooks;
   readonly #now: () => number;
   /** one rotation per session in this process, however many requests need it at once */
   readonly #refreshesInFlight = new Map<string, Promise<IProviderToken>>();
 
-  constructor(optionsArg: IRelyingPartySessionsOptions<TPrincipal>) {
+  constructor(optionsArg: IRelyingPartySessionsOptions<TPrincipal> | IRelyingPartyBearerOnlySessionsOptions<TPrincipal>) {
     const origin = new URL(optionsArg.publicOrigin);
     if (origin.origin !== optionsArg.publicOrigin) {
       throw new Error('publicOrigin must be a bare origin such as https://app.example');
     }
-    if (!Buffer.isBuffer(optionsArg.csrfKey) || optionsArg.csrfKey.length !== 32) {
-      throw new Error('csrfKey must be 32 bytes');
+    const cookieSessions: unknown = optionsArg.cookieSessions ?? true;
+    if (cookieSessions !== true && cookieSessions !== false) {
+      throw new Error('cookieSessions must be true or false');
+    }
+    if (cookieSessions) {
+      if (!Buffer.isBuffer(optionsArg.csrfKey) || optionsArg.csrfKey.length !== 32) {
+        throw new Error('csrfKey must be 32 bytes');
+      }
+    } else {
+      for (const name of ['csrfKey', 'csrfLabel', 'cookieNames'] as const) {
+        if (optionsArg[name] !== undefined) {
+          throw new Error(`${name} has no use with cookieSessions: false, which reads and sets no cookie`);
+        }
+      }
+      if (optionsArg.bearer === undefined) {
+        throw new Error('cookieSessions: false needs bearer: without cookies, bearer hand-off is the only way in');
+      }
     }
     const maxAge = optionsArg.sessionMaxAgeSeconds ?? RELYING_PARTY_DEFAULT_SESSION_MAX_AGE_SECONDS;
     if (!Number.isSafeInteger(maxAge) || maxAge < 1) {
@@ -220,9 +402,19 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
           : null;
     }
     this.#provider = optionsArg.provider;
+    if (optionsArg.bearer !== undefined) {
+      this.#bearer = bearerModeOf(optionsArg.bearer, {
+        models: optionsArg.models,
+        hasProvider: optionsArg.provider !== undefined,
+        publicOrigin: this.publicOrigin,
+        loginPathPrefix: this.loginPathPrefix,
+        sessionMaxAgeSeconds: maxAge,
+      });
+    }
     this.#secretBox = new SecretBox(optionsArg.sessionEncryptionKey);
-    this.#csrfKey = Buffer.from(optionsArg.csrfKey);
-    this.#csrfLabel = optionsArg.csrfLabel ?? RELYING_PARTY_DEFAULT_CSRF_LABEL;
+    this.#cookieSessions = cookieSessions
+      ? { csrfKey: Buffer.from(optionsArg.csrfKey), csrfLabel: optionsArg.csrfLabel ?? RELYING_PARTY_DEFAULT_CSRF_LABEL }
+      : null;
     this.#hooks = optionsArg.hooks ?? {};
     this.#now = optionsArg.now ?? (() => Date.now());
   }
@@ -232,6 +424,21 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     return this.#provider !== undefined;
   }
 
+  /** Whether cookie sessions are offered; `false` only in bearer-only mode (`cookieSessions: false`). */
+  public get cookieSessionsEnabled(): boolean {
+    return this.#cookieSessions !== null;
+  }
+
+  /** Whether bearer hand-off mode is offered. */
+  public get bearerLoginEnabled(): boolean {
+    return this.#bearer !== undefined;
+  }
+
+  /** The return targets bearer clients may name, per kind, as configured; `undefined` without bearer mode. */
+  public get bearerReturnTargets(): Readonly<Required<IRelyingPartyBearerReturnTargets>> | undefined {
+    return this.#bearer?.returnTargets;
+  }
+
   /**
    * How long one replica holds the right to rotate a session's tokens. The
    * provider detects reuse of a superseded refresh token and kills the family,
@@ -253,6 +460,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * cookie with it; it is a whole number of seconds from 1 to that maximum.
    */
   public async openSession(optionsArg: { principalId: string; maxAgeSeconds?: number }): Promise<IRelyingPartySessionOpening> {
+    this.requireCookieSessions();
     if (typeof optionsArg?.principalId !== 'string' || optionsArg.principalId.length === 0) {
       throw new Error('openSession needs a principal id');
     }
@@ -260,16 +468,24 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     if (!Number.isSafeInteger(maxAgeSeconds) || maxAgeSeconds < 1 || maxAgeSeconds > this.sessionMaxAgeSeconds) {
       throw new RangeError(`openSession maxAgeSeconds must be a whole number from 1 to ${this.sessionMaxAgeSeconds}`);
     }
+    await this.sweepEndedSessions();
     const token = randomToken(32);
     const session = this.newSessionDoc(token, optionsArg.principalId, maxAgeSeconds);
     await session.save();
     return this.opening(session, token, maxAgeSeconds);
   }
 
-  /** The live session behind the session cookie, or `null`. A read touches it at most once a minute. */
+  /**
+   * The live session behind the session cookie, or `null`. A read touches it
+   * at most once a minute. Always `null` in bearer-only mode, which reads no
+   * cookie.
+   */
   public async resolveCookieSession(
     cookieHeaderArg: string | null | undefined,
   ): Promise<IResolvedRelyingPartySession<TPrincipal> | null> {
+    if (!this.#cookieSessions) {
+      return null;
+    }
     const token = parseCookies(cookieHeaderArg).get(this.sessionCookieName);
     if (!token || token.length > MAX_COOKIE_TOKEN_LENGTH) {
       return null;
@@ -364,7 +580,46 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     return ended;
   }
 
+  /**
+   * One page of a principal's live sessions, newest first: the ones neither
+   * ended nor expired, and none at all while the principal is not active —
+   * exactly the sessions `isSessionLive` confirms. Pass the page's
+   * `nextCursor` as `cursor` to read the next one; the last page has none.
+   * The cursor is opaque, and one this method did not answer is refused with
+   * `invalid_sessions_cursor`. A session opened while the pages are read is
+   * listed only when it sorts after the cursor; none is listed twice.
+   */
+  public async sessionsOfPrincipal(
+    principalIdArg: string,
+    optionsArg: IRelyingPartySessionsPageOptions = {},
+  ): Promise<IRelyingPartySessionsPage> {
+    if (typeof principalIdArg !== 'string' || principalIdArg === '') {
+      throw new Error('sessionsOfPrincipal needs a principal id');
+    }
+    const limit = optionsArg.limit ?? RELYING_PARTY_DEFAULT_SESSIONS_PAGE_LIMIT;
+    if (!Number.isInteger(limit) || limit < 1 || limit > RELYING_PARTY_MAX_SESSIONS_PAGE_LIMIT) {
+      throw new Error(`limit must be an integer from 1 to ${RELYING_PARTY_MAX_SESSIONS_PAGE_LIMIT}`);
+    }
+    const cursor = optionsArg.cursor === undefined ? undefined : parseSessionsCursor(optionsArg.cursor);
+    if (!(await this.#activePrincipal(principalIdArg))) {
+      return { sessions: [] };
+    }
+    const page = await this.#models.Session.getPagedInstances({
+      filter: { userId: principalIdArg, revokedAt: { $exists: false }, expiresAt: { $gt: this.#now() } },
+      sortField: 'createdAt',
+      sortDirection: 'desc',
+      uniqueField: 'id',
+      limit,
+      ...(cursor ? { cursor } : {}),
+    });
+    return {
+      sessions: page.documents.map((documentArg) => this.snapshot(documentArg)),
+      ...(page.nextCursor ? { nextCursor: serializeSessionsCursor(page.nextCursor) } : {}),
+    };
+  }
+
   public clearSessionCookie(): string {
+    this.requireCookieSessions();
     return serializeClearedCookie(this.sessionCookieName, {
       httpOnly: true,
       secure: this.secureCookies,
@@ -373,6 +628,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
   }
 
   public clearIntentCookie(): string {
+    this.requireCookieSessions();
     return serializeClearedCookie(this.intentCookieName, {
       httpOnly: true,
       secure: this.secureCookies,
@@ -390,35 +646,22 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * browser.
    */
   public async startLogin(returnPathArg: unknown, optionsArg: IRelyingPartyLoginOptions = {}): Promise<IRelyingPartyLoginStart> {
+    this.requireCookieSessions();
     const provider = this.requireProvider();
-    const { intent, prompt } = optionsArg;
-    if (intent !== undefined && (typeof intent !== 'string' || intent.length === 0 || intent.length > RELYING_PARTY_MAX_INTENT_LENGTH)) {
-      throw new RangeError(`a login intent is text of 1 to ${RELYING_PARTY_MAX_INTENT_LENGTH} characters`);
-    }
-    if (prompt !== undefined && !OIDC_PROMPTS.includes(prompt)) {
-      throw new RangeError(`a login prompt is one of ${OIDC_PROMPTS.join(', ')}`);
-    }
+    this.checkLoginOptions(optionsArg);
     await this.sweepExpiredAttempts();
-    const state = randomToken(32);
-    const nonce = randomToken(32);
-    const pkceVerifier = randomToken(32);
+    await this.sweepEndedSessions();
     const bindingToken = randomToken(32);
-    const now = this.#now();
-
-    const attempt = new this.#models.LoginAttempt();
-    attempt.id = 'lga_' + randomToken(18);
-    attempt.stateHash = sha256(state);
+    const { attempt, state, nonce, pkceVerifier } = this.newLoginAttempt(optionsArg.intent);
     attempt.bindingTokenHash = sha256(bindingToken);
-    attempt.sealedPkceVerifier = this.#secretBox.seal(pkceVerifier);
-    attempt.nonce = nonce;
     attempt.returnPath = sanitizeReturnPath(returnPathArg, this.publicOrigin, this.loginPathPrefix);
-    if (intent !== undefined) {
-      attempt.sealedIntent = this.#secretBox.seal(intent);
-    }
-    attempt.createdAt = now;
-    attempt.expiresAt = now + LOGIN_ATTEMPT_MAX_AGE_SECONDS * 1_000;
     // the URL first: a login the provider cannot start yet (before discovery) stores no attempt
-    const authorizationUrl = await provider.buildAuthorizationUrl({ state, nonce, pkceVerifier, ...(prompt ? { prompt } : {}) });
+    const authorizationUrl = await provider.buildAuthorizationUrl({
+      state,
+      nonce,
+      pkceVerifier,
+      ...(optionsArg.prompt ? { prompt: optionsArg.prompt } : {}),
+    });
     await attempt.save();
 
     return {
@@ -443,6 +686,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     callbackUrlArg: URL,
     cookieHeaderArg: string | null | undefined,
   ): Promise<IRelyingPartySessionOpening> {
+    this.requireCookieSessions();
     const provider = this.requireProvider();
     const states = callbackUrlArg.searchParams.getAll('state');
     if (states.length !== 1 || !states[0]) {
@@ -468,35 +712,8 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
       throw new RelyingPartyError('invalid_or_replayed_login');
     }
     const attempt = claimed.document as RelyingPartyLoginAttemptDoc;
-
-    let completion: IOidcCompletion | undefined;
-    let stage: TLoginCallbackStage = 'token_exchange';
-    try {
-      completion = await provider.completeAuthorization({
-        callbackUrl: callbackUrlArg,
-        state: states[0],
-        nonce: attempt.nonce,
-        pkceVerifier: this.#secretBox.open(attempt.sealedPkceVerifier),
-      });
-      stage = 'principal_admission';
-      const { principalId } = await this.#admit(completion, {
-        loginAttemptId: attempt.id,
-        ...(attempt.sealedIntent ? { intent: this.#secretBox.open(attempt.sealedIntent) } : {}),
-      });
-      stage = 'session_persistence';
-      return await this.createProviderSession(attempt, principalId, completion);
-    } catch (error) {
-      if (completion) {
-        await this.revokeCompletionTokens(completion);
-      }
-      if (error instanceof RelyingPartyError || error instanceof RelyingPartyRefusal) {
-        throw error;
-      }
-      if (error instanceof OidcCompletionError) {
-        throw new LoginCallbackError(error.stage, error);
-      }
-      throw new LoginCallbackError(stage, error);
-    }
+    const opened = await this.openProviderLogin(provider, callbackUrlArg, states[0], attempt);
+    return this.opening(opened.document, opened.token);
   }
 
   /**
@@ -505,6 +722,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * matches no open attempt leaves nothing to do.
    */
   public async abandonLogin(callbackUrlArg: URL, cookieHeaderArg: string | null | undefined): Promise<void> {
+    this.requireCookieSessions();
     const states = callbackUrlArg.searchParams.getAll('state');
     const bindingToken = parseCookies(cookieHeaderArg).get(this.intentCookieName);
     if (
@@ -527,6 +745,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * session this very attempt created.
    */
   public async finalizeLogin(cookieHeaderArg: string | null | undefined): Promise<string> {
+    this.requireCookieSessions();
     this.requireProvider();
     const bindingToken = parseCookies(cookieHeaderArg).get(this.intentCookieName);
     if (!bindingToken || bindingToken.length > MAX_COOKIE_TOKEN_LENGTH) {
@@ -553,6 +772,295 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     return sanitizeReturnPath(attempt.returnPath, this.publicOrigin, this.loginPathPrefix);
   }
 
+  // ==========================================================================
+  // bearer hand-off
+  // ==========================================================================
+
+  /**
+   * Starts a bearer login for one of the application's own clients: the same
+   * provider login as `startLogin`, but the outcome goes to the return target
+   * the client named — exactly one of the configured targets of its kind —
+   * and it sets no cookie. The login is bound to the client's S256 challenge
+   * instead of a browser: whoever claims its hand-off code has to present the
+   * verifier. Every field of the request is checked as untrusted input.
+   */
+  public async startBearerLogin(
+    requestArg: IRelyingPartyBearerLoginRequest,
+    optionsArg: IRelyingPartyLoginOptions = {},
+  ): Promise<IRelyingPartyBearerLoginStart> {
+    const provider = this.requireProvider();
+    const bearer = this.requireBearer();
+    const request: Partial<Record<keyof IRelyingPartyBearerLoginRequest, unknown>> | null =
+      requestArg && typeof requestArg === 'object' ? requestArg : null;
+    if (
+      !request
+      || !isBearerClientKind(request.clientKind)
+      || typeof request.returnTarget !== 'string'
+      || !isPkceChallenge(request.codeChallenge)
+      || request.codeChallengeMethod !== 'S256'
+      || (request.state !== undefined && !isBearerClientState(request.state))
+    ) {
+      throw new RelyingPartyError('invalid_bearer_request');
+    }
+    if (!isBearerReturnTargetAllowed(bearer.returnTargets, request.clientKind, request.returnTarget)) {
+      throw new RelyingPartyError('return_target_not_allowed');
+    }
+    this.checkLoginOptions(optionsArg);
+    await this.sweepExpiredAttempts();
+    await this.sweepBearerState();
+    await this.sweepEndedSessions();
+    const { attempt, state, nonce, pkceVerifier } = this.newLoginAttempt(optionsArg.intent);
+    // a binding token that never leaves: no cookie callback can consume this attempt
+    attempt.bindingTokenHash = sha256(randomToken(32));
+    attempt.bearerClientKind = request.clientKind;
+    attempt.bearerReturnTarget = request.returnTarget;
+    attempt.bearerCodeChallenge = request.codeChallenge;
+    if (isBearerClientState(request.state)) {
+      attempt.bearerClientState = request.state;
+    }
+    const authorizationUrl = await provider.buildAuthorizationUrl({
+      state,
+      nonce,
+      pkceVerifier,
+      ...(optionsArg.prompt ? { prompt: optionsArg.prompt } : {}),
+    });
+    await attempt.save();
+    return { authorizationUrl };
+  }
+
+  /**
+   * Where the outcome of a login callback goes when it belongs to a bearer
+   * login: the client kind, the return target and the client's `state`, read
+   * without consuming anything. `null` for a cookie login, an unknown state,
+   * and a return target that is no longer configured — the callback is then
+   * not answered as a bearer login at all.
+   */
+  public async bearerDeliveryOf(callbackUrlArg: URL): Promise<IRelyingPartyBearerDelivery | null> {
+    const state = this.#bearer ? singleStateOf(callbackUrlArg) : null;
+    if (!state) {
+      return null;
+    }
+    const attempt = await this.#models.LoginAttempt.getInstance({ stateHash: sha256(state) });
+    return attempt ? this.bearerDeliveryOfAttempt(attempt) : null;
+  }
+
+  /**
+   * Consumes a bearer login's attempt exactly once, exchanges the code, admits
+   * the principal and opens its session — everything `completeLogin` does,
+   * with the same failures — and answers a single-use hand-off code bound to
+   * the client's challenge. The code lives `BEARER_HANDOFF_MAX_AGE_SECONDS`
+   * at most and only its hash is stored. A code nobody claims ends its session.
+   */
+  public async completeBearerLogin(callbackUrlArg: URL): Promise<IRelyingPartyBearerHandoff> {
+    const provider = this.requireProvider();
+    const bearer = this.requireBearer();
+    const state = singleStateOf(callbackUrlArg);
+    if (!state) {
+      throw new RelyingPartyError('invalid_login_callback');
+    }
+    const now = this.#now();
+    const claimed = await this.#models.LoginAttempt.atomicFindOneAndUpdate(
+      { stateHash: sha256(state), consumedAt: null, expiresAt: { $gt: now }, bearerClientKind: { $exists: true } },
+      { $set: { consumedAt: now } },
+      { returnDocument: 'after' },
+    );
+    if (claimed.status !== 'matched' || !claimed.document) {
+      throw new RelyingPartyError('invalid_or_replayed_login');
+    }
+    const attempt = claimed.document as RelyingPartyLoginAttemptDoc;
+    const delivery = this.bearerDeliveryOfAttempt(attempt);
+    if (!delivery) {
+      throw new RelyingPartyError('return_target_not_allowed');
+    }
+    const codeChallenge = attempt.bearerCodeChallenge;
+    if (!isPkceChallenge(codeChallenge)) {
+      throw new RelyingPartyError('invalid_or_replayed_login');
+    }
+    const code = randomToken(32);
+    let handoff: RelyingPartyBearerHandoffDoc | undefined;
+    const opened = await this.openProviderLogin(provider, callbackUrlArg, state, attempt, async (sessionArg) => {
+      const created = new bearer.models.BearerHandoff();
+      created.id = 'rbh_' + randomToken(18);
+      created.codeHash = sha256(code);
+      created.sessionId = sessionArg.id;
+      created.codeChallenge = codeChallenge;
+      created.createdAt = this.#now();
+      created.expiresAt = Math.min(created.createdAt + BEARER_HANDOFF_MAX_AGE_SECONDS * 1_000, sessionArg.expiresAt);
+      created.consumedAt = null;
+      await created.save();
+      handoff = created;
+    });
+    return {
+      session: this.snapshot(opened.document),
+      delivery,
+      code,
+      expiresAt: (handoff as RelyingPartyBearerHandoffDoc).expiresAt,
+    };
+  }
+
+  /** `abandonLogin` for a bearer login: the provider came back without a code. */
+  public async abandonBearerLogin(callbackUrlArg: URL): Promise<void> {
+    const state = singleStateOf(callbackUrlArg);
+    if (!state) {
+      return;
+    }
+    await this.#models.LoginAttempt.atomicUpdate(
+      { stateHash: sha256(state), consumedAt: null, bearerClientKind: { $exists: true } },
+      { $set: { consumedAt: this.#now() } },
+    );
+  }
+
+  /**
+   * Trades a hand-off code and the verifier of its challenge for the first
+   * access and refresh token of the session. The code is consumed by the first
+   * claim whatever its verifier: a wrong verifier ends the session, and so
+   * does the code coming back after it was claimed (RFC 6749 §4.1.2). A code
+   * that expired unclaimed ends its session too.
+   */
+  public async claimBearerHandoff(codeArg: unknown, codeVerifierArg: unknown): Promise<IRelyingPartyBearerTokens> {
+    const bearer = this.requireBearer();
+    const code = bearerCredentialOf(codeArg);
+    if (!code || !isPkceVerifier(codeVerifierArg)) {
+      throw new RelyingPartyError('invalid_bearer_request');
+    }
+    const codeHash = sha256(code);
+    const now = this.#now();
+    const claimed = await bearer.models.BearerHandoff.atomicFindOneAndUpdate(
+      { codeHash, consumedAt: null, expiresAt: { $gt: now } },
+      { $set: { consumedAt: now } },
+      { returnDocument: 'after' },
+    );
+    if (claimed.status !== 'matched' || !claimed.document) {
+      const known = await bearer.models.BearerHandoff.getInstance({ codeHash });
+      if (known?.consumedAt === null) {
+        await this.endUnclaimedHandoff(known);
+      } else if (known && known.consumedAt !== null && known.consumedAt < known.expiresAt) {
+        // a claim took it while it was valid; one taken after its expiry was
+        // ended unclaimed, and coming back late is no reuse
+        await this.bearerCredentialReused(known.sessionId, 'handoff_code_reused');
+      }
+      throw new RelyingPartyError('invalid_bearer_handoff');
+    }
+    const handoff = claimed.document as RelyingPartyBearerHandoffDoc;
+    if (!verifyPkceChallenge(codeVerifierArg, handoff.codeChallenge)) {
+      await this.endSession(handoff.sessionId, 'handoff_verifier_mismatch');
+      throw new RelyingPartyError('invalid_bearer_handoff');
+    }
+    const live = await this.liveSession(await this.#models.Session.getInstance({ id: handoff.sessionId }));
+    if (!live) {
+      throw new RelyingPartyError('invalid_bearer_handoff');
+    }
+    return this.issueBearerTokens(bearer, live.document);
+  }
+
+  /**
+   * Rotates a bearer session's tokens: the refresh token is spent, a new
+   * access and refresh token answer, and the old access token stops working.
+   * Rotation is strict — a client serializes its refreshes — because a
+   * refresh token that comes back after it was spent ends the whole session.
+   * The provider login is checked on the way: a login idp.global ended ends
+   * the session here (`invalid_bearer_grant`), an unreachable provider fails
+   * with `AuthorityTokenError('authority_unavailable')` and spends nothing.
+   */
+  public async refreshBearerTokens(refreshTokenArg: unknown): Promise<IRelyingPartyBearerTokens> {
+    const bearer = this.requireBearer();
+    const refreshToken = bearerCredentialOf(refreshTokenArg);
+    if (!refreshToken) {
+      throw new RelyingPartyError('invalid_bearer_grant');
+    }
+    const refreshTokenHash = sha256(refreshToken);
+    const current = await bearer.models.BearerToken.getInstance({ refreshTokenHash });
+    if (!current) {
+      throw new RelyingPartyError('invalid_bearer_grant');
+    }
+    if (current.rotatedAt !== null) {
+      await this.bearerCredentialReused(current.sessionId, 'refresh_token_reused');
+      throw new RelyingPartyError('invalid_bearer_grant');
+    }
+    if (current.expiresAt <= this.#now()) {
+      throw new RelyingPartyError('invalid_bearer_grant');
+    }
+    const live = await this.liveSession(await this.#models.Session.getInstance({ id: current.sessionId }));
+    if (!live) {
+      throw new RelyingPartyError('invalid_bearer_grant');
+    }
+    try {
+      await this.liveProviderToken(live.document.id, live.document.userId);
+    } catch (error) {
+      if (error instanceof AuthorityTokenError && error.code === 'authority_login_required') {
+        throw new RelyingPartyError('invalid_bearer_grant');
+      }
+      throw error;
+    }
+    // the next generation first: a rotation that fails half way leaves an
+    // unknown generation behind, never a session without a current one
+    const issued = await this.issueBearerTokens(bearer, live.document);
+    const rotated = await bearer.models.BearerToken.atomicUpdate(
+      { refreshTokenHash, rotatedAt: null },
+      { $set: { rotatedAt: this.#now() } },
+    );
+    if (rotated.matchedCount !== 1) {
+      // a concurrent refresh spent it first; the generation just issued never
+      // left this call and dies with the session
+      await this.bearerCredentialReused(current.sessionId, 'refresh_token_reused');
+      throw new RelyingPartyError('invalid_bearer_grant');
+    }
+    return issued;
+  }
+
+  /**
+   * The live session behind a bearer access token, or `null`: the token of the
+   * session's current generation, not expired, its session live and its
+   * principal active. A read touches the session at most once a minute.
+   */
+  public async resolveBearerAccessToken(accessTokenArg: unknown): Promise<IRelyingPartyLiveSession<TPrincipal> | null> {
+    const accessToken = this.#bearer ? bearerCredentialOf(accessTokenArg) : null;
+    if (!this.#bearer || !accessToken) {
+      return null;
+    }
+    const generation = await this.#bearer.models.BearerToken.getInstance({ accessTokenHash: sha256(accessToken) });
+    if (!generation || generation.rotatedAt !== null || generation.accessTokenExpiresAt <= this.#now()) {
+      return null;
+    }
+    const live = await this.liveSession(await this.#models.Session.getInstance({ id: generation.sessionId }));
+    return live ? { session: this.snapshot(live.document), principal: live.principal } : null;
+  }
+
+  /** `resolveBearerAccessToken` for an `Authorization: Bearer <token>` header. */
+  public async resolveBearerSession(
+    authorizationHeaderArg: string | null | undefined,
+  ): Promise<IRelyingPartyLiveSession<TPrincipal> | null> {
+    return this.resolveBearerAccessToken(parseBearerAuthorization(authorizationHeaderArg));
+  }
+
+  /**
+   * Ends the session of a bearer token — a live access token or the current
+   * refresh token — like `endSession`. A refresh token that was already spent
+   * is reuse and ends the session as such. Answers whether this call ended it.
+   */
+  public async endBearerSession(tokenArg: unknown): Promise<boolean> {
+    const token = this.#bearer ? bearerCredentialOf(tokenArg) : null;
+    if (!this.#bearer || !token) {
+      return false;
+    }
+    const tokenHash = sha256(token);
+    const byAccessToken = await this.#bearer.models.BearerToken.getInstance({ accessTokenHash: tokenHash });
+    if (byAccessToken) {
+      if (byAccessToken.rotatedAt !== null || byAccessToken.accessTokenExpiresAt <= this.#now()) {
+        return false;
+      }
+      return this.endSession(byAccessToken.sessionId, 'logout');
+    }
+    const byRefreshToken = await this.#bearer.models.BearerToken.getInstance({ refreshTokenHash: tokenHash });
+    if (!byRefreshToken) {
+      return false;
+    }
+    if (byRefreshToken.rotatedAt !== null) {
+      return this.bearerCredentialReused(byRefreshToken.sessionId, 'refresh_token_reused');
+    }
+    return this.endSession(byRefreshToken.sessionId, 'logout');
+  }
+
   // ==========================================================================
   // provider tokens
   // ==========================================================================
@@ -563,8 +1071,22 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * is unknown — is rotated first. The session has to belong to
    * `expectedPrincipalIdArg`, so a credential is never evaluated with another
    * person's tokens.
+   *
+   * With `rejectedAccessToken` (`IAuthorityTokenSource`) the call rotates the
+   * session's token whatever is stored, and only a rotation that it starts
+   * marks its answer `rotatedAfterRejection`: one that started before it, in
+   * this process or another replica's, says nothing about the rejection, so
+   * the call awaits it and throws `authority_unavailable`. A refused rotation
+   * ends the session (`refresh_token_refused`) and throws
+   * `authority_login_required`. A session without a refresh token has nothing
+   * to rotate with: it throws `authority_unavailable`, or ends as
+   * `access_token_unusable` when its token is dead.
    */
-  public async liveProviderToken(sessionIdArg: string, expectedPrincipalIdArg: string): Promise<IProviderToken> {
+  public async liveProviderToken(
+    sessionIdArg: string,
+    expectedPrincipalIdArg: string,
+    optionsArg: { rejectedAccessToken?: string } = {},
+  ): Promise<IProviderToken> {
     const session = await this.#models.Session.getInstance({ id: sessionIdArg });
     const now = this.#now();
     if (
@@ -579,35 +1101,60 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     const subject = session.idpSubject;
     const expiresAt = typeof session.accessTokenExpiresAt === 'number' ? session.accessTokenExpiresAt : 0;
     const accessToken = this.openSealed(session.sealedAccessToken);
+    const forced = optionsArg.rejectedAccessToken !== undefined;
     // an unknown expiry is rotated too: afterwards the lifetime is known
-    const due = accessToken === undefined || expiresAt === 0 || expiresAt <= now + ACCESS_TOKEN_REFRESH_SKEW_MS;
+    const due = forced
+      || accessToken === undefined
+      || expiresAt === 0
+      || expiresAt <= now + ACCESS_TOKEN_REFRESH_SKEW_MS;
     if (!due && accessToken !== undefined) {
       return { accessToken, subject, expiresAt };
     }
     if (!session.sealedRefreshToken) {
       if (accessToken !== undefined && (expiresAt === 0 || expiresAt > now)) {
         // nothing to rotate with, and the token is not known to be dead
+        if (forced) {
+          throw new AuthorityTokenError('authority_unavailable');
+        }
         return { accessToken, subject, expiresAt };
       }
       await this.endProviderSession(sessionIdArg, 'access_token_unusable');
       throw new AuthorityTokenError('authority_login_required');
     }
-    return this.refreshProviderToken(sessionIdArg, subject);
+    return this.refreshProviderToken(sessionIdArg, subject, forced);
   }
 
-  private async refreshProviderToken(sessionIdArg: string, subjectArg: string): Promise<IProviderToken> {
+  /**
+   * One rotation of the session in this process at a time. A forced call that
+   * finds one running waits for it, so a refusal still ends it, and is
+   * unavailable otherwise: that rotation started before the call.
+   */
+  private async refreshProviderToken(
+    sessionIdArg: string,
+    subjectArg: string,
+    forcedArg: boolean,
+  ): Promise<IProviderToken> {
     const running = this.#refreshesInFlight.get(sessionIdArg);
     if (running) {
-      return running;
+      const joined = await running;
+      if (forcedArg) {
+        throw new AuthorityTokenError('authority_unavailable');
+      }
+      return joined;
     }
-    const pending = this.runProviderRefresh(sessionIdArg, subjectArg).finally(() => {
+    const pending = this.runProviderRefresh(sessionIdArg, subjectArg, forcedArg).finally(() => {
       this.#refreshesInFlight.delete(sessionIdArg);
     });
     this.#refreshesInFlight.set(sessionIdArg, pending);
-    return pending;
+    // only the call that started the rotation is told so; others that join it are not
+    return forcedArg ? { ...(await pending), rotatedAfterRejection: true } : pending;
   }
 
-  private async runProviderRefresh(sessionIdArg: string, subjectArg: string): Promise<IProviderToken> {
+  private async runProviderRefresh(
+    sessionIdArg: string,
+    subjectArg: string,
+    forcedArg: boolean,
+  ): Promise<IProviderToken> {
     const provider = this.#provider;
     if (!provider) {
       throw new AuthorityTokenError('authority_unavailable');
@@ -626,15 +1173,21 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
       { returnDocument: 'after' },
     );
     if (claimed.status !== 'matched' || !claimed.document) {
+      if (forcedArg) {
+        // nothing tells when the other replica's rotation started
+        throw new AuthorityTokenError('authority_unavailable');
+      }
       return this.tokenAfterForeignRefresh(sessionIdArg, subjectArg);
     }
     const session = claimed.document as RelyingPartySessionDoc;
     // the lock holder decides on the state it just read: a rotation that
     // landed in between is used as it stands, because spending a superseded
-    // refresh token would be reuse and would kill the family
+    // refresh token would be reuse and would kill the family; a forced call
+    // rotates the stored pair however long its token would last, since only a
+    // rotation it starts comes after the rejection
     const claimedExpiry = typeof session.accessTokenExpiresAt === 'number' ? session.accessTokenExpiresAt : 0;
     const claimedToken = this.openSealed(session.sealedAccessToken);
-    if (claimedToken !== undefined && claimedExpiry > this.#now() + ACCESS_TOKEN_REFRESH_SKEW_MS) {
+    if (!forcedArg && claimedToken !== undefined && claimedExpiry > this.#now() + ACCESS_TOKEN_REFRESH_SKEW_MS) {
       await this.#models.Session.atomicUpdate(
         { id: sessionIdArg, revokedAt: { $exists: false }, refreshLockUntil: lockUntil },
         { $set: { refreshLockUntil: 0 } },
@@ -722,6 +1275,96 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     return this.#provider;
   }
 
+  private requireCookieSessions(): ICookieSessionsMode {
+    if (!this.#cookieSessions) {
+      throw new RelyingPartyError('login_method_unavailable');
+    }
+    return this.#cookieSessions;
+  }
+
+  private requireBearer(): IBearerMode {
+    if (!this.#bearer) {
+      throw new RelyingPartyError('login_method_unavailable');
+    }
+    return this.#bearer;
+  }
+
+  private checkLoginOptions(optionsArg: IRelyingPartyLoginOptions): void {
+    const { intent, prompt } = optionsArg;
+    if (intent !== undefined && (typeof intent !== 'string' || intent.length === 0 || intent.length > RELYING_PARTY_MAX_INTENT_LENGTH)) {
+      throw new RangeError(`a login intent is text of 1 to ${RELYING_PARTY_MAX_INTENT_LENGTH} characters`);
+    }
+    if (prompt !== undefined && !OIDC_PROMPTS.includes(prompt)) {
+      throw new RangeError(`a login prompt is one of ${OIDC_PROMPTS.join(', ')}`);
+    }
+  }
+
+  /** An unsaved attempt with its state, nonce and sealed verifier; the caller binds it and names where it returns. */
+  private newLoginAttempt(intentArg: string | undefined): {
+    attempt: RelyingPartyLoginAttemptDoc;
+    state: string;
+    nonce: string;
+    pkceVerifier: string;
+  } {
+    const state = randomToken(32);
+    const nonce = randomToken(32);
+    const pkceVerifier = randomToken(32);
+    const now = this.#now();
+    const attempt = new this.#models.LoginAttempt();
+    attempt.id = 'lga_' + randomToken(18);
+    attempt.stateHash = sha256(state);
+    attempt.sealedPkceVerifier = this.#secretBox.seal(pkceVerifier);
+    attempt.nonce = nonce;
+    if (intentArg !== undefined) {
+      attempt.sealedIntent = this.#secretBox.seal(intentArg);
+    }
+    attempt.createdAt = now;
+    attempt.expiresAt = now + LOGIN_ATTEMPT_MAX_AGE_SECONDS * 1_000;
+    return { attempt, state, nonce, pkceVerifier };
+  }
+
+  /**
+   * The provider half of a consumed attempt: exchanges the code, admits the
+   * principal and opens the session. Nothing of a failed login survives: its
+   * tokens are handed back before the failure leaves.
+   */
+  private async openProviderLogin(
+    providerArg: IOidcProvider,
+    callbackUrlArg: URL,
+    stateArg: string,
+    attemptArg: RelyingPartyLoginAttemptDoc,
+    beforeOpenedArg?: (sessionArg: RelyingPartySessionDoc) => Promise<void>,
+  ): Promise<{ document: RelyingPartySessionDoc; token: string }> {
+    let completion: IOidcCompletion | undefined;
+    let stage: TLoginCallbackStage = 'token_exchange';
+    try {
+      completion = await providerArg.completeAuthorization({
+        callbackUrl: callbackUrlArg,
+        state: stateArg,
+        nonce: attemptArg.nonce,
+        pkceVerifier: this.#secretBox.open(attemptArg.sealedPkceVerifier),
+      });
+      stage = 'principal_admission';
+      const { principalId } = await this.#admit(completion, {
+        loginAttemptId: attemptArg.id,
+        ...(attemptArg.sealedIntent ? { intent: this.#secretBox.open(attemptArg.sealedIntent) } : {}),
+      });
+      stage = 'session_persistence';
+      return await this.createProviderSession(attemptArg, principalId, completion, beforeOpenedArg);
+    } catch (error) {
+      if (completion) {
+        await this.revokeCompletionTokens(completion);
+      }
+      if (error instanceof RelyingPartyError || error instanceof RelyingPartyRefusal) {
+        throw error;
+      }
+      if (error instanceof OidcCompletionError) {
+        throw new LoginCallbackError(error.stage, error);
+      }
+      throw new LoginCallbackError(stage, error);
+    }
+  }
+
   private newSessionDoc(tokenArg: string, principalIdArg: string, maxAgeSecondsArg: number = this.sessionMaxAgeSeconds): RelyingPartySessionDoc {
     const now = this.#now();
     const session = new this.#models.Session();
@@ -735,7 +1378,8 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
   }
 
   private csrfTokenOf(tokenArg: string): string {
-    return deriveCsrfToken(tokenArg, this.#csrfKey, this.#csrfLabel);
+    const { csrfKey, csrfLabel } = this.requireCookieSessions();
+    return deriveCsrfToken(tokenArg, csrfKey, csrfLabel);
   }
 
   private opening(sessionArg: RelyingPartySessionDoc, tokenArg: string, maxAgeSecondsArg: number = this.sessionMaxAgeSeconds): IRelyingPartySessionOpening {
@@ -790,11 +1434,17 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     return { document: sessionArg, principal: active.principal };
   }
 
+  /**
+   * Stores the session of a provider login and links it to its attempt.
+   * `beforeOpenedArg` stores what the session is handed out with besides its
+   * cookie; like the hook after it, a throw discards the session.
+   */
   private async createProviderSession(
     attemptArg: RelyingPartyLoginAttemptDoc,
     principalIdArg: string,
     completionArg: IOidcCompletion,
-  ): Promise<IRelyingPartySessionOpening> {
+    beforeOpenedArg?: (sessionArg: RelyingPartySessionDoc) => Promise<void>,
+  ): Promise<{ document: RelyingPartySessionDoc; token: string }> {
     const token = randomToken(32);
     const session = this.newSessionDoc(token, principalIdArg);
     session.idpSubject = completionArg.subject;
@@ -814,13 +1464,13 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
       await this.discardUnopenedSession(session.id);
       throw new RelyingPartyError('invalid_or_replayed_login');
     }
-    const opening = this.opening(session, token);
     try {
-      await this.#hooks.onProviderSessionOpened?.({ session: opening.session });
+      await beforeOpenedArg?.(session);
+      await this.#hooks.onProviderSessionOpened?.({ session: this.snapshot(session) });
     } catch (error) {
-      // the cookie never leaves, so the session is unreachable: it is revoked
-      // and its sealed tokens erased before the application's error goes on;
-      // the caller hands the provider tokens back
+      // the cookie (or the hand-off code) never leaves, so the session is
+      // unreachable: it is revoked and its sealed tokens erased before the
+      // error goes on; the caller hands the provider tokens back
       try {
         await this.discardUnopenedSession(session.id);
       } catch (discardError) {
@@ -828,15 +1478,112 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
       }
       throw error;
     }
-    return opening;
+    return { document: session, token };
+  }
+
+  /** Where a bearer attempt's outcome goes, while its return target is still configured; `null` otherwise. */
+  private bearerDeliveryOfAttempt(attemptArg: RelyingPartyLoginAttemptDoc): IRelyingPartyBearerDelivery | null {
+    const clientKind = attemptArg.bearerClientKind;
+    const returnTarget = attemptArg.bearerReturnTarget;
+    if (
+      !this.#bearer
+      || !isBearerClientKind(clientKind)
+      || typeof returnTarget !== 'string'
+      || !isBearerReturnTargetAllowed(this.#bearer.returnTargets, clientKind, returnTarget)
+    ) {
+      return null;
+    }
+    return {
+      clientKind,
+      returnTarget,
+      ...(attemptArg.bearerClientState !== undefined ? { state: attemptArg.bearerClientState } : {}),
+    };
+  }
+
+  /** Stores the next token generation of a live session and answers its tokens; none of them is stored in the clear. */
+  private async issueBearerTokens(bearerArg: IBearerMode, sessionArg: RelyingPartySessionDoc): Promise<IRelyingPartyBearerTokens> {
+    const accessToken = randomToken(32);
+    const refreshToken = randomToken(32);
+    const now = this.#now();
+    const generation = new bearerArg.models.BearerToken();
+    generation.id = 'rbt_' + randomToken(18);
+    generation.accessTokenHash = sha256(accessToken);
+    generation.refreshTokenHash = sha256(refreshToken);
+    generation.sessionId = sessionArg.id;
+    generation.createdAt = now;
+    generation.accessTokenExpiresAt = Math.min(now + bearerArg.accessTokenMaxAgeSeconds * 1_000, sessionArg.expiresAt);
+    generation.expiresAt = sessionArg.expiresAt;
+    generation.rotatedAt = null;
+    await generation.save();
+    return {
+      session: this.snapshot(sessionArg),
+      issuedAt: now,
+      accessToken,
+      accessTokenExpiresAt: generation.accessTokenExpiresAt,
+      refreshToken,
+      refreshTokenExpiresAt: generation.expiresAt,
+    };
+  }
+
+  /** A spent hand-off code or refresh token came back: whoever holds it, the session ends. */
+  private async bearerCredentialReused(
+    sessionIdArg: string,
+    reasonArg: 'handoff_code_reused' | 'refresh_token_reused',
+  ): Promise<boolean> {
+    this.emit({ event: 'bearer_credential_reused', sessionId: sessionIdArg, reason: reasonArg });
+    return this.endSession(sessionIdArg, reasonArg);
+  }
+
+  /**
+   * Takes a hand-off whose code expired unclaimed and ends its session, which
+   * nothing can reach any more. The caller has read it expired; expiry never
+   * moves, so only a claim in between can stop this.
+   */
+  private async endUnclaimedHandoff(handoffArg: RelyingPartyBearerHandoffDoc): Promise<void> {
+    const taken = await this.requireBearer().models.BearerHandoff.atomicUpdate(
+      { id: handoffArg.id, consumedAt: null },
+      { $set: { consumedAt: this.#now() } },
+    );
+    if (taken.matchedCount === 1) {
+      await this.endSession(handoffArg.sessionId, 'handoff_unclaimed');
+    }
   }
 
   /** Revokes a session that was never handed out and erases its sealed tokens. */
   private async discardUnopenedSession(sessionIdArg: string): Promise<void> {
-    await this.#models.Session.atomicUpdate(
+    await this.revokeSessionDocument(sessionIdArg);
+  }
+
+  /**
+   * Revokes a session not revoked yet and erases its sealed tokens; answers
+   * the document as it was before, `null` when it was over already. Its
+   * expiry comes forward to the revocation, never later, so the sweep finds
+   * an ended session by its expiry alone and `revokedAt` keeps when and that
+   * it was ended. Two conditional writes keep the earlier of the two times:
+   * the first ends a session within its expiry, the second one past it. A
+   * crash between them leaves an expired row unrevoked, which reads as over
+   * and is swept; a row revoked before 19.4.0 kept its later expiry, which is
+   * harmless because every reader checks `revokedAt` or reads live rows only,
+   * and it ages out.
+   */
+  private async revokeSessionDocument(sessionIdArg: string): Promise<RelyingPartySessionDoc | null> {
+    const now = this.#now();
+    const withinExpiry = await this.#models.Session.atomicFindOneAndUpdate(
+      { id: sessionIdArg, revokedAt: { $exists: false }, expiresAt: { $gt: now } },
+      { $set: { revokedAt: now, expiresAt: now, ...REVOKED_TOKEN_FIELDS } },
+      { returnDocument: 'before' },
+    );
+    if (withinExpiry.status === 'matched' && withinExpiry.document !== null) {
+      return withinExpiry.document as RelyingPartySessionDoc;
+    }
+    const pastExpiry = await this.#models.Session.atomicFindOneAndUpdate(
       { id: sessionIdArg, revokedAt: { $exists: false } },
-      { $set: { revokedAt: this.#now(), ...REVOKED_TOKEN_FIELDS } },
+      { $set: { revokedAt: now, ...REVOKED_TOKEN_FIELDS } },
+      { returnDocument: 'before' },
     );
+    return pastExpiry.status === 'matched' && pastExpiry.document !== null
+      ? pastExpiry.document as RelyingPartySessionDoc
+      : null;
   }
 
   /**
@@ -878,17 +1625,11 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     if (typeof sessionIdArg !== 'string' || sessionIdArg.length === 0) {
       return null;
     }
-    const revoked = await this.#models.Session.atomicFindOneAndUpdate(
-      { id: sessionIdArg, revokedAt: { $exists: false } },
-      { $set: { revokedAt: this.#now(), ...REVOKED_TOKEN_FIELDS } },
-      { returnDocument: 'before' },
-    );
-    const revokedHere = revoked.status === 'matched' && revoked.document !== null;
-    this.notifySessionEnded({ sessionId: sessionIdArg, reason: reasonArg, revokedHere });
-    if (!revokedHere) {
+    const before = await this.revokeSessionDocument(sessionIdArg);
+    this.notifySessionEnded({ sessionId: sessionIdArg, reason: reasonArg, revokedHere: before !== null });
+    if (!before) {
       return null;
     }
-    const before = revoked.document as RelyingPartySessionDoc;
     return { sealedAccessToken: before.sealedAccessToken, sealedRefreshToken: before.sealedRefreshToken };
   }
 
@@ -1015,6 +1756,78 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     }
   }
 
+  /**
+   * One bounded page per bearer login start, oldest first: hand-offs whose
+   * code expired unclaimed end their session, and hand-offs and token
+   * generations an hour past their expiry are removed — an unclaimed hand-off
+   * only after its session was ended. A sweep that cannot run never blocks a
+   * sign-in.
+   */
+  private async sweepBearerState(): Promise<void> {
+    const bearer = this.requireBearer();
+    try {
+      const now = this.#now();
+      const unclaimed = await bearer.models.BearerHandoff.getPagedInstances({
+        filter: { consumedAt: null, expiresAt: { $lt: now } },
+        sortField: 'expiresAt',
+        sortDirection: 'asc',
+        limit: LOGIN_ATTEMPT_SWEEP_BATCH,
+      });
+      for (const handoff of unclaimed.documents) {
+        await this.endUnclaimedHandoff(handoff);
+      }
+      const staleHandoffs = await bearer.models.BearerHandoff.getPagedInstances({
+        filter: { expiresAt: { $lt: now - LOGIN_ATTEMPT_SWEEP_GRACE_MS } },
+        sortField: 'expiresAt',
+        sortDirection: 'asc',
+        limit: LOGIN_ATTEMPT_SWEEP_BATCH,
+      });
+      for (const handoff of staleHandoffs.documents) {
+        if (handoff.consumedAt !== null) {
+          await bearer.models.BearerHandoff.atomicDelete({ id: handoff.id });
+        }
+      }
+      const staleGenerations = await bearer.models.BearerToken.getPagedInstances({
+        filter: { expiresAt: { $lt: now - LOGIN_ATTEMPT_SWEEP_GRACE_MS } },
+        sortField: 'expiresAt',
+        sortDirection: 'asc',
+        limit: LOGIN_ATTEMPT_SWEEP_BATCH,
+      });
+      for (const generation of staleGenerations.documents) {
+        await bearer.models.BearerToken.atomicDelete({ id: generation.id });
+      }
+    } catch (error) {
+      this.emit({ event: 'bearer_sweep_failed', message: errorMessage(error) });
+    }
+  }
+
+  /**
+   * Removes sessions an hour past their expiry, oldest first, one bounded
+   * page per login start and per session the application opens. An ended
+   * session's expiry is its revocation at the latest, so the expiry index
+   * finds expired and revoked sessions alike. Each of them ended already: the
+   * row goes without an end, a hook or a provider call. A row is deleted only
+   * while its expiry is still past the cutoff, so a row whose expiry moved
+   * after the page was read stays. A sweep that cannot run never blocks a
+   * sign-in.
+   */
+  private async sweepEndedSessions(): Promise<void> {
+    try {
+      const cutoff = this.#now() - LOGIN_ATTEMPT_SWEEP_GRACE_MS;
+      const page = await this.#models.Session.getPagedInstances({
+        filter: { expiresAt: { $lt: cutoff } },
+        sortField: 'expiresAt',
+        sortDirection: 'asc',
+        limit: LOGIN_ATTEMPT_SWEEP_BATCH,
+      });
+      for (const session of page.documents) {
+        await this.#models.Session.atomicDelete({ id: session.id, expiresAt: { $lt: cutoff } });
+      }
+    } catch (error) {
+      this.emit({ event: 'session_sweep_failed', message: errorMessage(error) });
+    }
+  }
+
   /**
    * Reports one diagnostic. Every cleanup step reports through here, so a
    * throwing sink must not end it: the event and the sink's failure go to