@idp.global/sdk 19.3.0 → 19.5.0

package/ts_relyingparty/classes.relyingpartysessions.ts

@@ -39,6 +39,7 @@ import type {
   IProviderToken,
   IRelyingPartyBearerDelivery,
   IRelyingPartyBearerHandoff,
+  IRelyingPartyBearerHandoffOpening,
   IRelyingPartyBearerLoginRequest,
   IRelyingPartyBearerLoginStart,
   IRelyingPartyBearerOptions,
@@ -52,6 +53,9 @@ import type {
   IRelyingPartyLoginStart,
   IRelyingPartySession,
   IRelyingPartySessionOpening,
+  IRelyingPartySessionsErasure,
+  IRelyingPartySessionsPage,
+  IRelyingPartySessionsPageOptions,
   IResolvedRelyingPartySession,
   TLoginCallbackStage,
   TRelyingPartyPrincipals,
@@ -69,10 +73,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 — and bearer hand-offs and token generations — 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. */
@@ -107,6 +117,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;
@@ -131,8 +147,36 @@ export interface IRelyingPartySessionsOptions<TPrincipal extends object | undefi
   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 comes from a live provider login, directly or through a hand-off opened from one */
+  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>>;
@@ -148,7 +192,7 @@ const bearerModeOf = (
     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');
+    throw new Error('bearer needs a provider: every bearer session comes from a provider login');
   }
   const { BearerHandoff, BearerToken } = optionsArg.models;
   if (!BearerHandoff || !BearerToken) {
@@ -180,6 +224,43 @@ const singleStateOf = (callbackUrlArg: URL): string | null => {
 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));
@@ -211,10 +292,17 @@ 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,
- * so it is built before the database connects.
+ * 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, `openSession` or `openBearerHandoff`, 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`
  * principals it stays `undefined`.
@@ -233,20 +321,34 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
   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) {
@@ -312,8 +414,9 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
       });
     }
     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());
   }
@@ -323,6 +426,11 @@ 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;
@@ -354,6 +462,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');
     }
@@ -361,16 +470,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;
@@ -465,7 +582,94 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     return ended;
   }
 
+  /**
+   * Erases every session of a principal, live or ended, and every row that
+   * belongs to one, without waiting for a sweep: what an application runs
+   * when it deletes an account, after its own erasers and before its user
+   * record.
+   *
+   * First each session not revoked yet, an expired one too, ends as
+   * `endSession` ends it: its tokens stop working at once, `onSessionEnded`
+   * names the principal, and its provider tokens go back to idp.global,
+   * which a deleted row could no longer do. Then each session's rows go: in
+   * bearer mode its hand-offs, claimed or not, and its token generations;
+   * the login attempt a provider session came out of; and the session row
+   * last, because it is the only link from the principal to the others, so
+   * an erase that fails half way leaves a retry everything it needs. A
+   * session opened or a token issued while the erase runs is not covered;
+   * it works only while the principal is active.
+   */
+  public async eraseSessionsOfPrincipal(principalIdArg: string): Promise<IRelyingPartySessionsErasure> {
+    if (typeof principalIdArg !== 'string' || principalIdArg === '') {
+      throw new Error('eraseSessionsOfPrincipal needs a principal id');
+    }
+    const erasure: IRelyingPartySessionsErasure = {
+      endedSessions: 0,
+      deletedSessions: 0,
+      deletedLoginAttempts: 0,
+      deletedBearerHandoffs: 0,
+      deletedBearerTokens: 0,
+    };
+    const sessions = await this.#models.Session.getInstances({ userId: principalIdArg });
+    for (const session of sessions) {
+      if (session.revokedAt === undefined && (await this.endSession(session.id))) {
+        erasure.endedSessions += 1;
+      }
+    }
+    const bearerModels = this.#bearer?.models;
+    for (const session of sessions) {
+      if (bearerModels) {
+        erasure.deletedBearerHandoffs += (await bearerModels.BearerHandoff.atomicDeleteMany({ sessionId: session.id })).deletedCount;
+        erasure.deletedBearerTokens += (await bearerModels.BearerToken.atomicDeleteMany({ sessionId: session.id })).deletedCount;
+      }
+      if (session.loginAttemptId) {
+        erasure.deletedLoginAttempts += (await this.#models.LoginAttempt.atomicDelete({ id: session.loginAttemptId })).deletedCount;
+      }
+      erasure.deletedSessions += (await this.#models.Session.atomicDelete({ id: session.id })).deletedCount;
+    }
+    return erasure;
+  }
+
+  /**
+   * 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,
@@ -474,6 +678,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
   }
 
   public clearIntentCookie(): string {
+    this.requireCookieSessions();
     return serializeClearedCookie(this.intentCookieName, {
       httpOnly: true,
       secure: this.secureCookies,
@@ -491,9 +696,11 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * browser.
    */
   public async startLogin(returnPathArg: unknown, optionsArg: IRelyingPartyLoginOptions = {}): Promise<IRelyingPartyLoginStart> {
+    this.requireCookieSessions();
     const provider = this.requireProvider();
     this.checkLoginOptions(optionsArg);
     await this.sweepExpiredAttempts();
+    await this.sweepEndedSessions();
     const bindingToken = randomToken(32);
     const { attempt, state, nonce, pkceVerifier } = this.newLoginAttempt(optionsArg.intent);
     attempt.bindingTokenHash = sha256(bindingToken);
@@ -529,6 +736,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]) {
@@ -564,6 +772,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 (
@@ -586,6 +795,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) {
@@ -648,6 +858,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     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));
@@ -715,28 +926,85 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     if (!isPkceChallenge(codeChallenge)) {
       throw new RelyingPartyError('invalid_or_replayed_login');
     }
-    const code = randomToken(32);
-    let handoff: RelyingPartyBearerHandoffDoc | undefined;
+    let handoff: { code: string; expiresAt: number } | 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;
+      handoff = await this.storeBearerHandoff(bearer, sessionArg, codeChallenge);
     });
+    const stored = handoff as { code: string; expiresAt: number };
     return {
       session: this.snapshot(opened.document),
       delivery,
-      code,
-      expiresAt: (handoff as RelyingPartyBearerHandoffDoc).expiresAt,
+      code: stored.code,
+      expiresAt: stored.expiresAt,
     };
   }
 
+  /**
+   * Opens a bearer session for a device the application pairs to a person
+   * who is signed in here, and answers its single-use hand-off code, which
+   * the device claims at `bearer/claim` with the verifier of `codeChallenge`,
+   * exactly like the code of a bearer login.
+   *
+   * `openerSessionId` names the session that confirmed the pairing, taken
+   * from the application's own record, never from the device. It must be a
+   * live provider login: not ended, not expired, its principal active, and
+   * with a provider login of its own. A session the application opened
+   * itself or one opened here does not qualify, so a paired device never
+   * pairs another one. Anything else throws
+   * `RelyingPartyError('invalid_handoff_opener')`.
+   *
+   * The new session acts as the opener's principal and has no provider login
+   * of its own: it ends by its expiry, `endSession`, `endSessionsOfPrincipal`,
+   * `bearer/logout` or the reuse of one of its credentials, never by an
+   * idp.global logout, and `AuthorityObserver` refuses it
+   * (`authority_login_required`). `maxAgeSeconds` is a whole number from 1 to
+   * `sessionMaxAgeSeconds`, the default, as for `openSession`. The code lives
+   * `BEARER_HANDOFF_MAX_AGE_SECONDS` at most and never past the session, and
+   * only its hash is stored; a code nobody claims ends its session. Nothing
+   * is stored for a refused opening.
+   */
+  public async openBearerHandoff(optionsArg: {
+    openerSessionId: string;
+    codeChallenge: string;
+    maxAgeSeconds?: number;
+  }): Promise<IRelyingPartyBearerHandoffOpening> {
+    const bearer = this.requireBearer();
+    if (!isPkceChallenge(optionsArg?.codeChallenge)) {
+      throw new RelyingPartyError('invalid_bearer_request');
+    }
+    const codeChallenge = optionsArg.codeChallenge;
+    const maxAgeSeconds = optionsArg.maxAgeSeconds ?? this.sessionMaxAgeSeconds;
+    if (!Number.isSafeInteger(maxAgeSeconds) || maxAgeSeconds < 1 || maxAgeSeconds > this.sessionMaxAgeSeconds) {
+      throw new RangeError(`openBearerHandoff maxAgeSeconds must be a whole number from 1 to ${this.sessionMaxAgeSeconds}`);
+    }
+    await this.sweepBearerState();
+    await this.sweepEndedSessions();
+    // read after the sweeps, so the opener is as live as it can be when the session is created
+    const openerSessionId = optionsArg.openerSessionId;
+    const opener = typeof openerSessionId === 'string' && openerSessionId.length > 0
+      ? await this.liveSession(await this.#models.Session.getInstance({ id: openerSessionId }))
+      : null;
+    if (!opener || typeof opener.document.idpSubject !== 'string' || opener.document.idpSubject.length === 0) {
+      throw new RelyingPartyError('invalid_handoff_opener');
+    }
+    // the token is never handed out: the session is reached by its code only, as a bearer login's
+    const session = this.newSessionDoc(randomToken(32), opener.document.userId, maxAgeSeconds);
+    await session.save();
+    let handoff: { code: string; expiresAt: number };
+    try {
+      handoff = await this.storeBearerHandoff(bearer, session, codeChallenge);
+    } catch (error) {
+      // the code never leaves, so the session is unreachable: it is revoked before the error goes on
+      try {
+        await this.discardUnopenedSession(session.id);
+      } catch (discardError) {
+        this.emit({ event: 'session_discard_failed', sessionId: session.id, message: errorMessage(discardError) });
+      }
+      throw error;
+    }
+    return { session: this.snapshot(session), code: handoff.code, expiresAt: handoff.expiresAt };
+  }
+
   /** `abandonLogin` for a bearer login: the provider came back without a code. */
   public async abandonBearerLogin(callbackUrlArg: URL): Promise<void> {
     const state = singleStateOf(callbackUrlArg);
@@ -797,9 +1065,11 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * 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.
+   * The provider login of a bearer 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. A session `openBearerHandoff` opened has no provider
+   * login (no `idpSubject` is stored) and rotates without the provider.
    */
   public async refreshBearerTokens(refreshTokenArg: unknown): Promise<IRelyingPartyBearerTokens> {
     const bearer = this.requireBearer();
@@ -823,13 +1093,17 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     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');
+    // decided by what the session stores alone, never by a failure: a session
+    // with a provider subject is a provider login and always asks the provider
+    if (typeof live.document.idpSubject === 'string') {
+      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;
       }
-      throw error;
     }
     // the next generation first: a rotation that fails half way leaves an
     // unknown generation behind, never a session without a current one
@@ -910,8 +1184,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 (
@@ -926,35 +1214,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');
@@ -973,15 +1286,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 } },
@@ -1069,6 +1388,13 @@ 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');
@@ -1165,7 +1491,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 {
@@ -1252,7 +1579,8 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     }
     try {
       await beforeOpenedArg?.(session);
-      await this.#hooks.onProviderSessionOpened?.({ session: this.snapshot(session) });
+      const delivery = this.bearerDeliveryOfAttempt(attemptArg);
+      await this.#hooks.onProviderSessionOpened?.({ session: this.snapshot(session), ...(delivery ? { delivery } : {}) });
     } catch (error) {
       // the cookie (or the hand-off code) never leaves, so the session is
       // unreachable: it is revoked and its sealed tokens erased before the
@@ -1286,6 +1614,29 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     };
   }
 
+  /**
+   * Stores a new hand-off of a session, bound to the client's challenge, and
+   * answers its code, which is stored only as a hash. The code lives
+   * `BEARER_HANDOFF_MAX_AGE_SECONDS` at most and never past the session.
+   */
+  private async storeBearerHandoff(
+    bearerArg: IBearerMode,
+    sessionArg: RelyingPartySessionDoc,
+    codeChallengeArg: string,
+  ): Promise<{ code: string; expiresAt: number }> {
+    const code = randomToken(32);
+    const handoff = new bearerArg.models.BearerHandoff();
+    handoff.id = 'rbh_' + randomToken(18);
+    handoff.codeHash = sha256(code);
+    handoff.sessionId = sessionArg.id;
+    handoff.codeChallenge = codeChallengeArg;
+    handoff.createdAt = this.#now();
+    handoff.expiresAt = Math.min(handoff.createdAt + BEARER_HANDOFF_MAX_AGE_SECONDS * 1_000, sessionArg.expiresAt);
+    handoff.consumedAt = null;
+    await handoff.save();
+    return { code, expiresAt: handoff.expiresAt };
+  }
+
   /** 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);
@@ -1337,10 +1688,39 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
 
   /** 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;
   }
 
   /**
@@ -1348,11 +1728,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * local revocation and the provider revocation: a throw or a rejection is
    * reported as `hook_failed` and the end runs on.
    */
-  private notifySessionEnded(eventArg: {
-    sessionId: string;
-    reason: TRelyingPartySessionEndReason;
-    revokedHere: boolean;
-  }): void {
+  private notifySessionEnded(eventArg: Parameters<NonNullable<IRelyingPartyHooks['onSessionEnded']>>[0]): void {
     const hook = this.#hooks.onSessionEnded;
     if (!hook) {
       return;
@@ -1382,17 +1758,12 @@ 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);
+    if (!before) {
+      this.notifySessionEnded({ sessionId: sessionIdArg, reason: reasonArg, revokedHere: false });
       return null;
     }
-    const before = revoked.document as RelyingPartySessionDoc;
+    this.notifySessionEnded({ sessionId: sessionIdArg, reason: reasonArg, revokedHere: true, principalId: before.userId });
     return { sealedAccessToken: before.sealedAccessToken, sealedRefreshToken: before.sealedRefreshToken };
   }
 
@@ -1564,6 +1935,33 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     }
   }
 
+  /**
+   * 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