@idp.global/sdk 19.2.1 → 19.3.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,
@@ -46,10 +69,16 @@ 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 and token generations — 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 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.
@@ -92,6 +121,11 @@ 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;
@@ -99,6 +133,53 @@ export interface IRelyingPartySessionsOptions<TPrincipal extends object | undefi
 
 type TSealedTokens = Pick<RelyingPartySessionDoc, 'sealedAccessToken' | 'sealedRefreshToken'>;
 
+/** 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;
+
 const REVOKED_TOKEN_FIELDS = { sealedAccessToken: '', sealedRefreshToken: '', refreshLockUntil: 0 };
 
 const errorMessage = (errorArg: unknown): string => (errorArg instanceof Error ? errorArg.message : String(errorArg));
@@ -150,6 +231,7 @@ 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;
@@ -220,6 +302,15 @@ 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;
@@ -232,6 +323,16 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     return this.#provider !== undefined;
   }
 
+  /** 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,
@@ -391,34 +492,19 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    */
   public async startLogin(returnPathArg: unknown, optionsArg: IRelyingPartyLoginOptions = {}): Promise<IRelyingPartyLoginStart> {
     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);
     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 {
@@ -468,35 +554,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);
   }
 
   /**
@@ -553,6 +612,294 @@ 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();
+    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
   // ==========================================================================
@@ -722,6 +1069,89 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     return this.#provider;
   }
 
+  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();
@@ -790,11 +1220,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 +1250,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,7 +1264,75 @@ 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. */
@@ -1015,6 +1519,51 @@ 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) });
+    }
+  }
+
   /**
    * 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