@idp.global/sdk 19.4.0 → 19.6.0

package/ts_relyingparty/classes.relyingpartysessions.ts

@@ -18,6 +18,7 @@ import type {
   IRelyingPartyBearerModels,
   IRelyingPartyModels,
   RelyingPartyBearerHandoffDoc,
+  RelyingPartyBearerTokenDoc,
   RelyingPartyLoginAttemptDoc,
   RelyingPartySessionDoc,
 } from './classes.rpmodels.js';
@@ -31,7 +32,7 @@ import {
   parseBearerAuthorization,
   verifyPkceChallenge,
 } from './helpers.bearer.js';
-import { parseCookies, serializeClearedCookie, serializeCookie } from './helpers.cookies.js';
+import { parseCookies, serializeClearedCookie, serializeCookie, type ICookieOptions } from './helpers.cookies.js';
 import { deriveCsrfToken, randomToken, sha256, timingSafeEqualString } from './helpers.crypto.js';
 import { sanitizeReturnPath } from './helpers.returnpath.js';
 import type {
@@ -39,11 +40,13 @@ import type {
   IProviderToken,
   IRelyingPartyBearerDelivery,
   IRelyingPartyBearerHandoff,
+  IRelyingPartyBearerHandoffOpening,
   IRelyingPartyBearerLoginRequest,
   IRelyingPartyBearerLoginStart,
   IRelyingPartyBearerOptions,
   IRelyingPartyBearerReturnTargets,
   IRelyingPartyBearerTokens,
+  IRelyingPartyCookiePolicy,
   IRelyingPartyEvent,
   IRelyingPartyHooks,
   IRelyingPartyAdmission,
@@ -52,6 +55,7 @@ import type {
   IRelyingPartyLoginStart,
   IRelyingPartySession,
   IRelyingPartySessionOpening,
+  IRelyingPartySessionsErasure,
   IRelyingPartySessionsPage,
   IRelyingPartySessionsPageOptions,
   IResolvedRelyingPartySession,
@@ -85,6 +89,10 @@ const MAX_SESSIONS_CURSOR_LENGTH = 512;
 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;
+/** How long a spent refresh token may come back as a lost answer unless `bearer.refreshReuseGraceSeconds` says otherwise. */
+export const RELYING_PARTY_DEFAULT_REFRESH_REUSE_GRACE_SECONDS = 60;
+/** The longest `bearer.refreshReuseGraceSeconds`: a spent token that comes back later is always reuse. */
+export const RELYING_PARTY_MAX_REFRESH_REUSE_GRACE_SECONDS = 300;
 /** The codes and tokens of bearer mode are 43 characters; anything far longer is none of them. */
 const MAX_BEARER_TOKEN_LENGTH = 256;
 /**
@@ -133,6 +141,14 @@ export interface IRelyingPartySessionsOptions<TPrincipal extends object | undefi
     session?: string;
     intent?: string;
   };
+  /**
+   * How the session and intent cookies go across sites: `{ sameSite: 'Lax' }`
+   * by default. A page framed on another site needs `sameSite: 'None'` (an
+   * https `publicOrigin` only), with `partitioned: true` where the browser
+   * keeps third-party cookies per top-level site. The constructor refuses
+   * every other combination.
+   */
+  cookiePolicy?: IRelyingPartyCookiePolicy;
   /** the prefix of the login routes; a login never returns into it */
   loginPathPrefix?: string;
   /**
@@ -150,21 +166,23 @@ export interface IRelyingPartySessionsOptions<TPrincipal extends object | undefi
  * 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
+ * `csrfKey`, `csrfLabel`, `cookieNames` and `cookiePolicy` 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'> {
+  extends Omit<IRelyingPartySessionsOptions<TPrincipal>, 'provider' | 'csrfKey' | 'csrfLabel' | 'cookieNames' | 'cookiePolicy' | 'cookieSessions' | 'bearer'> {
   cookieSessions: false;
-  /** every bearer session is a provider login */
+  /** 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;
+  cookiePolicy?: never;
 }
 
 type TSealedTokens = Pick<RelyingPartySessionDoc, 'sealedAccessToken' | 'sealedRefreshToken'>;
@@ -179,6 +197,8 @@ interface ICookieSessionsMode {
 interface IBearerMode {
   returnTargets: Readonly<Required<IRelyingPartyBearerReturnTargets>>;
   accessTokenMaxAgeSeconds: number;
+  /** `0`: a spent refresh token that comes back is always reuse */
+  refreshReuseGraceMs: number;
   models: IRelyingPartyBearerModels;
 }
 
@@ -190,7 +210,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) {
@@ -205,9 +225,18 @@ const bearerModeOf = (
   ) {
     throw new Error(`bearer.accessTokenMaxAgeSeconds must be a whole number from 1 to ${optionsArg.sessionMaxAgeSeconds}`);
   }
+  const refreshReuseGraceSeconds = bearerArg.refreshReuseGraceSeconds ?? RELYING_PARTY_DEFAULT_REFRESH_REUSE_GRACE_SECONDS;
+  if (
+    !Number.isSafeInteger(refreshReuseGraceSeconds)
+    || refreshReuseGraceSeconds < 0
+    || refreshReuseGraceSeconds > RELYING_PARTY_MAX_REFRESH_REUSE_GRACE_SECONDS
+  ) {
+    throw new Error(`bearer.refreshReuseGraceSeconds must be a whole number from 0 to ${RELYING_PARTY_MAX_REFRESH_REUSE_GRACE_SECONDS}`);
+  }
   return {
     returnTargets: normalizeBearerReturnTargets(bearerArg.returnTargets, optionsArg.publicOrigin, optionsArg.loginPathPrefix),
     accessTokenMaxAgeSeconds,
+    refreshReuseGraceMs: refreshReuseGraceSeconds * 1_000,
     models: { BearerHandoff, BearerToken },
   };
 };
@@ -284,6 +313,34 @@ const cookieNameFor = (
   return configuredArg;
 };
 
+/**
+ * The cookie policy as the constructor checked it. Every combination it does
+ * not resolve is refused here, never when a cookie is written.
+ */
+const cookiePolicyOf = (policyArg: unknown, secureArg: boolean): Readonly<Required<IRelyingPartyCookiePolicy>> => {
+  if (policyArg === undefined) {
+    return { sameSite: 'Lax', partitioned: false };
+  }
+  if (!policyArg || typeof policyArg !== 'object' || Array.isArray(policyArg)) {
+    throw new Error('cookiePolicy must be an object');
+  }
+  const sameSite: unknown = Reflect.get(policyArg, 'sameSite') ?? 'Lax';
+  const partitioned: unknown = Reflect.get(policyArg, 'partitioned') ?? false;
+  if (sameSite !== 'Lax' && sameSite !== 'None') {
+    throw new Error("cookiePolicy.sameSite must be 'Lax' or 'None'");
+  }
+  if (typeof partitioned !== 'boolean') {
+    throw new Error('cookiePolicy.partitioned must be true or false');
+  }
+  if (sameSite === 'None' && !secureArg) {
+    throw new Error("cookiePolicy.sameSite 'None' needs an https publicOrigin: browsers drop a SameSite=None cookie that is not set Secure");
+  }
+  if (partitioned && sameSite !== 'None') {
+    throw new Error("cookiePolicy.partitioned needs sameSite 'None': only a cross-site cookie is partitioned");
+  }
+  return { sameSite, partitioned };
+};
+
 /**
  * The relying-party session layer: provider logins through the authorization
  * code flow with PKCE, HttpOnly cookie sessions with a session-bound CSRF
@@ -297,10 +354,10 @@ const cookieNameFor = (
  * 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.
+ * 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`.
@@ -310,6 +367,8 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
   public readonly secureCookies: boolean;
   public readonly sessionCookieName: string;
   public readonly intentCookieName: string;
+  /** how the session and intent cookies go across sites, as the constructor resolved `cookiePolicy` */
+  public readonly cookiePolicy: Readonly<Required<IRelyingPartyCookiePolicy>>;
   public readonly loginPathPrefix: string;
   public readonly sessionMaxAgeSeconds: number;
   readonly #models: IRelyingPartyModels;
@@ -339,7 +398,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
         throw new Error('csrfKey must be 32 bytes');
       }
     } else {
-      for (const name of ['csrfKey', 'csrfLabel', 'cookieNames'] as const) {
+      for (const name of ['csrfKey', 'csrfLabel', 'cookieNames', 'cookiePolicy'] as const) {
         if (optionsArg[name] !== undefined) {
           throw new Error(`${name} has no use with cookieSessions: false, which reads and sets no cookie`);
         }
@@ -367,6 +426,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
       this.secureCookies,
       'intent',
     );
+    this.cookiePolicy = cookiePolicyOf(optionsArg.cookiePolicy, this.secureCookies);
     this.loginPathPrefix = optionsArg.loginPathPrefix ?? RELYING_PARTY_DEFAULT_LOGIN_PATH_PREFIX;
     if (!this.loginPathPrefix.startsWith('/') || !this.loginPathPrefix.endsWith('/')) {
       throw new Error('loginPathPrefix must start and end with a slash');
@@ -559,6 +619,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
   /**
    * Ends every live session of a principal but `keepSessionId` (a password
    * change keeps the session that asked for it) and answers how many ended.
+   * A session that expired is over already and is neither ended nor counted.
    */
   public async endSessionsOfPrincipal(
     principalIdArg: string,
@@ -568,6 +629,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     const sessions = await this.#models.Session.getInstances({
       userId: principalIdArg,
       revokedAt: { $exists: false },
+      expiresAt: { $gt: this.#now() },
     });
     for (const session of sessions) {
       if (session.id === optionsArg.keepSessionId) {
@@ -580,6 +642,54 @@ 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 —
@@ -620,20 +730,12 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
 
   public clearSessionCookie(): string {
     this.requireCookieSessions();
-    return serializeClearedCookie(this.sessionCookieName, {
-      httpOnly: true,
-      secure: this.secureCookies,
-      sameSite: 'Lax',
-    });
+    return serializeClearedCookie(this.sessionCookieName, this.cookieAttributes());
   }
 
   public clearIntentCookie(): string {
     this.requireCookieSessions();
-    return serializeClearedCookie(this.intentCookieName, {
-      httpOnly: true,
-      secure: this.secureCookies,
-      sameSite: 'Lax',
-    });
+    return serializeClearedCookie(this.intentCookieName, this.cookieAttributes());
   }
 
   // ==========================================================================
@@ -667,9 +769,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     return {
       authorizationUrl,
       intentCookie: serializeCookie(this.intentCookieName, bindingToken, {
-        httpOnly: true,
-        secure: this.secureCookies,
-        sameSite: 'Lax',
+        ...this.cookieAttributes(),
         maxAgeSeconds: LOGIN_ATTEMPT_MAX_AGE_SECONDS,
       }),
     };
@@ -876,28 +976,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);
@@ -950,17 +1107,26 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     if (!live) {
       throw new RelyingPartyError('invalid_bearer_handoff');
     }
-    return this.issueBearerTokens(bearer, live.document);
+    return (await this.issueBearerTokens(bearer, live.document)).tokens;
   }
 
   /**
    * 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.
+   * A client serializes its refreshes, because a refresh token that comes
+   * back after it was spent ends the whole session, with one exception for
+   * an answer that never reached the client: within
+   * `bearer.refreshReuseGraceSeconds` of its rotation (60 by default), a
+   * spent refresh token whose successor was never presented — neither its
+   * access token nor its refresh token — revokes that successor and answers a
+   * new pair (`bearer_refresh_reissued`). Only hashes are stored, so the lost
+   * pair is replaced, never repeated. Once the successor was presented, after
+   * the window, or for a second retry that loses the race to the first, it is
+   * reuse. 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();
@@ -973,39 +1139,135 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     if (!current) {
       throw new RelyingPartyError('invalid_bearer_grant');
     }
-    if (current.rotatedAt !== null) {
+    const lostSuccessor = current.rotatedAt !== null ? await this.lostSuccessorOf(bearer, current) : null;
+    if (current.rotatedAt !== null && !lostSuccessor) {
       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');
     }
+    // presented: from now on its predecessor's refresh token is no lost answer;
+    // one that a lost answer of its predecessor revoked just now is reuse
+    if (!lostSuccessor && !(await this.markBearerGenerationPresented(bearer, current))) {
+      await this.bearerCredentialReused(current.sessionId, 'refresh_token_reused');
+      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');
+    // 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;
+    }
+    if (lostSuccessor) {
+      return this.reissueLostRotation(bearer, current, lostSuccessor, live.document);
     }
     // 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() } },
+      { $set: { rotatedAt: this.#now(), successorId: issued.generationId } },
     );
     if (rotated.matchedCount !== 1) {
-      // a concurrent refresh spent it first; the generation just issued never
-      // left this call and dies with the session
+      // a concurrent refresh spent it first, or a lost answer of its
+      // predecessor revoked it; 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;
+    return issued.tokens;
+  }
+
+  /**
+   * The successor of a spent generation when its answer may have been lost:
+   * the rotation is at most `refreshReuseGraceMs` old, and the successor is
+   * still current and was never presented. `null` otherwise, which is reuse.
+   */
+  private async lostSuccessorOf(
+    bearerArg: IBearerMode,
+    spentArg: RelyingPartyBearerTokenDoc,
+  ): Promise<RelyingPartyBearerTokenDoc | null> {
+    if (
+      bearerArg.refreshReuseGraceMs === 0
+      || spentArg.rotatedAt === null
+      || typeof spentArg.successorId !== 'string'
+      || this.#now() - spentArg.rotatedAt > bearerArg.refreshReuseGraceMs
+    ) {
+      return null;
+    }
+    const successor = await bearerArg.models.BearerToken.getInstance({ id: spentArg.successorId });
+    if (!successor || successor.sessionId !== spentArg.sessionId || successor.rotatedAt !== null || successor.firstUsedAt !== null) {
+      return null;
+    }
+    return successor;
+  }
+
+  /**
+   * Issues a pair again for a spent generation whose answer was lost. The
+   * successor that answer carried is revoked first, by one conditional write
+   * that needs it current and unpresented: of two retries at once exactly one
+   * takes it, and the other is reuse, as is a successor presented in the
+   * meantime. Then the new generation is stored and the spent one names it,
+   * so a retry after this answer is lost too finds it within the same window
+   * (counted from the original rotation). A failure after the revocation
+   * leaves the session without a current generation; its retry is reuse.
+   */
+  private async reissueLostRotation(
+    bearerArg: IBearerMode,
+    spentArg: RelyingPartyBearerTokenDoc,
+    successorArg: RelyingPartyBearerTokenDoc,
+    sessionArg: RelyingPartySessionDoc,
+  ): Promise<IRelyingPartyBearerTokens> {
+    const revoked = await bearerArg.models.BearerToken.atomicUpdate(
+      { id: successorArg.id, rotatedAt: null, firstUsedAt: null },
+      { $set: { rotatedAt: this.#now() } },
+    );
+    if (revoked.matchedCount !== 1) {
+      await this.bearerCredentialReused(spentArg.sessionId, 'refresh_token_reused');
+      throw new RelyingPartyError('invalid_bearer_grant');
+    }
+    const issued = await this.issueBearerTokens(bearerArg, sessionArg);
+    // only the call that revoked the successor gets here, so the link is its own to move
+    await bearerArg.models.BearerToken.atomicUpdate(
+      { id: spentArg.id, successorId: successorArg.id },
+      { $set: { successorId: issued.generationId } },
+    );
+    this.emit({ event: 'bearer_refresh_reissued', sessionId: spentArg.sessionId });
+    return issued.tokens;
+  }
+
+  /**
+   * Records the first presentation of a current generation's access or refresh
+   * token, once. Answers whether the generation is still current: `false`
+   * when a lost answer of its predecessor revoked it just now.
+   */
+  private async markBearerGenerationPresented(bearerArg: IBearerMode, generationArg: RelyingPartyBearerTokenDoc): Promise<boolean> {
+    if (generationArg.firstUsedAt !== null) {
+      return true;
+    }
+    const now = this.#now();
+    const marked = await bearerArg.models.BearerToken.atomicUpdate(
+      { id: generationArg.id, rotatedAt: null, firstUsedAt: null },
+      { $set: { firstUsedAt: now } },
+    );
+    if (marked.matchedCount === 1) {
+      generationArg.firstUsedAt = now;
+      return true;
+    }
+    // another request marked it first, or it was revoked in between
+    const stored = await bearerArg.models.BearerToken.getInstance({ id: generationArg.id });
+    return stored !== null && stored.rotatedAt === null;
   }
 
   /**
@@ -1023,7 +1285,11 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
       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;
+    // presented: its predecessor's refresh token is no lost answer any more
+    if (!live || !(await this.markBearerGenerationPresented(this.#bearer, generation))) {
+      return null;
+    }
+    return { session: this.snapshot(live.document), principal: live.principal };
   }
 
   /** `resolveBearerAccessToken` for an `Authorization: Bearer <token>` header. */
@@ -1036,7 +1302,9 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
   /**
    * 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.
+   * is reuse and ends the session as such, unless `refreshBearerTokens` would
+   * take it as a lost answer (`lostSuccessorOf`): then it is a logout like the
+   * current one. Answers whether this call ended it.
    */
   public async endBearerSession(tokenArg: unknown): Promise<boolean> {
     const token = this.#bearer ? bearerCredentialOf(tokenArg) : null;
@@ -1055,7 +1323,8 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     if (!byRefreshToken) {
       return false;
     }
-    if (byRefreshToken.rotatedAt !== null) {
+    // the same predicate as the refresh: a sign-out after a lost answer is no theft
+    if (byRefreshToken.rotatedAt !== null && !(await this.lostSuccessorOf(this.#bearer, byRefreshToken))) {
       return this.bearerCredentialReused(byRefreshToken.sessionId, 'refresh_token_reused');
     }
     return this.endSession(byRefreshToken.sessionId, 'logout');
@@ -1377,6 +1646,16 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     return session;
   }
 
+  /** The attributes every session and intent cookie is set and cleared with: one policy for all of them. */
+  private cookieAttributes(): Omit<ICookieOptions, 'maxAgeSeconds'> {
+    return {
+      httpOnly: true,
+      secure: this.secureCookies,
+      sameSite: this.cookiePolicy.sameSite,
+      ...(this.cookiePolicy.partitioned ? { partitioned: true } : {}),
+    };
+  }
+
   private csrfTokenOf(tokenArg: string): string {
     const { csrfKey, csrfLabel } = this.requireCookieSessions();
     return deriveCsrfToken(tokenArg, csrfKey, csrfLabel);
@@ -1387,9 +1666,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
       session: this.snapshot(sessionArg),
       csrfToken: this.csrfTokenOf(tokenArg),
       sessionCookie: serializeCookie(this.sessionCookieName, tokenArg, {
-        httpOnly: true,
-        secure: this.secureCookies,
-        sameSite: 'Lax',
+        ...this.cookieAttributes(),
         maxAgeSeconds: maxAgeSecondsArg,
       }),
     };
@@ -1466,7 +1743,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
@@ -1500,8 +1778,34 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     };
   }
 
-  /** 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> {
+  /**
+   * 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 and its id; no token is stored in the clear. */
+  private async issueBearerTokens(
+    bearerArg: IBearerMode,
+    sessionArg: RelyingPartySessionDoc,
+  ): Promise<{ tokens: IRelyingPartyBearerTokens; generationId: string }> {
     const accessToken = randomToken(32);
     const refreshToken = randomToken(32);
     const now = this.#now();
@@ -1514,14 +1818,19 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     generation.accessTokenExpiresAt = Math.min(now + bearerArg.accessTokenMaxAgeSeconds * 1_000, sessionArg.expiresAt);
     generation.expiresAt = sessionArg.expiresAt;
     generation.rotatedAt = null;
+    generation.firstUsedAt = null;
+    generation.successorId = null;
     await generation.save();
     return {
-      session: this.snapshot(sessionArg),
-      issuedAt: now,
-      accessToken,
-      accessTokenExpiresAt: generation.accessTokenExpiresAt,
-      refreshToken,
-      refreshTokenExpiresAt: generation.expiresAt,
+      generationId: generation.id,
+      tokens: {
+        session: this.snapshot(sessionArg),
+        issuedAt: now,
+        accessToken,
+        accessTokenExpiresAt: generation.accessTokenExpiresAt,
+        refreshToken,
+        refreshTokenExpiresAt: generation.expiresAt,
+      },
     };
   }
 
@@ -1591,11 +1900,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;
@@ -1626,10 +1931,11 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
       return null;
     }
     const before = await this.revokeSessionDocument(sessionIdArg);
-    this.notifySessionEnded({ sessionId: sessionIdArg, reason: reasonArg, revokedHere: before !== null });
     if (!before) {
+      this.notifySessionEnded({ sessionId: sessionIdArg, reason: reasonArg, revokedHere: false });
       return null;
     }
+    this.notifySessionEnded({ sessionId: sessionIdArg, reason: reasonArg, revokedHere: true, principalId: before.userId });
     return { sealedAccessToken: before.sealedAccessToken, sealedRefreshToken: before.sealedRefreshToken };
   }
 
@@ -1806,9 +2112,13 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * 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
+   * row goes without an end, a hook or a provider call. Its children go
+   * first: in bearer mode its hand-offs and token generations, by their
+   * `sessionId` index, and only then the session row, which is the only link
+   * from a principal to them; a sweep that fails half way leaves the session
+   * row, and the next sweep finds it and deletes the rest. Expiry never moves
+   * later, so a session past the cutoff stays past it, and its row is deleted
+   * only while that still holds. A sweep that cannot run never blocks a
    * sign-in.
    */
   private async sweepEndedSessions(): Promise<void> {
@@ -1820,7 +2130,12 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
         sortDirection: 'asc',
         limit: LOGIN_ATTEMPT_SWEEP_BATCH,
       });
+      const bearerModels = this.#bearer?.models;
       for (const session of page.documents) {
+        if (bearerModels) {
+          await bearerModels.BearerHandoff.atomicDeleteMany({ sessionId: session.id });
+          await bearerModels.BearerToken.atomicDeleteMany({ sessionId: session.id });
+        }
         await this.#models.Session.atomicDelete({ id: session.id, expiresAt: { $lt: cutoff } });
       }
     } catch (error) {