@idp.global/sdk 19.5.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 {
@@ -45,6 +46,7 @@ import type {
   IRelyingPartyBearerOptions,
   IRelyingPartyBearerReturnTargets,
   IRelyingPartyBearerTokens,
+  IRelyingPartyCookiePolicy,
   IRelyingPartyEvent,
   IRelyingPartyHooks,
   IRelyingPartyAdmission,
@@ -87,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;
 /**
@@ -135,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;
   /**
@@ -152,14 +166,15 @@ 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 comes from a live provider login, directly or through a hand-off opened from one */
   provider: IOidcProvider;
@@ -167,6 +182,7 @@ export interface IRelyingPartyBearerOnlySessionsOptions<TPrincipal extends objec
   csrfKey?: never;
   csrfLabel?: never;
   cookieNames?: never;
+  cookiePolicy?: never;
 }
 
 type TSealedTokens = Pick<RelyingPartySessionDoc, 'sealedAccessToken' | 'sealedRefreshToken'>;
@@ -181,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;
 }
 
@@ -207,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 },
   };
 };
@@ -286,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
@@ -312,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;
@@ -341,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`);
         }
@@ -369,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');
@@ -561,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,
@@ -570,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) {
@@ -670,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());
   }
 
   // ==========================================================================
@@ -717,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,
       }),
     };
@@ -1057,16 +1107,23 @@ 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 of a bearer login is checked on the way: a login
-   * idp.global ended ends the session here (`invalid_bearer_grant`), an
+   * 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.
@@ -1082,13 +1139,20 @@ 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');
@@ -1105,20 +1169,105 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
         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;
   }
 
   /**
@@ -1136,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. */
@@ -1149,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;
@@ -1168,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');
@@ -1490,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);
@@ -1500,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,
       }),
     };
@@ -1637,8 +1801,11 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     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> {
+  /** 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();
@@ -1651,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,
+      },
     };
   }
 
@@ -1940,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> {
@@ -1954,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) {

package/ts_relyingparty/classes.rpmodels.ts

@@ -129,7 +129,9 @@ export class RelyingPartyLoginAttemptDoc extends plugins.nosqldb.SmartDataDbDoc<
 /**
  * The single-use code a bearer login hands its client. Only the hash of the
  * code is stored; the code is bound to the client's S256 challenge, lives at
- * most a minute and is consumed by one conditional update.
+ * most a minute and is consumed by one conditional update. The `sessionId`
+ * index is what the session sweep and the erase delete a session's hand-offs
+ * by.
  */
 export class RelyingPartyBearerHandoffDoc extends plugins.nosqldb.SmartDataDbDoc<RelyingPartyBearerHandoffDoc, RelyingPartyBearerHandoffDoc> {
   @plugins.nosqldb.unI()
@@ -141,6 +143,7 @@ export class RelyingPartyBearerHandoffDoc extends plugins.nosqldb.SmartDataDbDoc
 
   /** the session the login opened; the code is its only way out */
   @plugins.nosqldb.svDb()
+  @plugins.nosqldb.index()
   public sessionId: string = '';
 
   @plugins.nosqldb.svDb()
@@ -163,8 +166,9 @@ export class RelyingPartyBearerHandoffDoc extends plugins.nosqldb.SmartDataDbDoc
  * One generation of a bearer session's tokens: an access token and the
  * refresh token that replaces both. Only hashes are stored. Exactly one
  * generation of a session is current (`rotatedAt` `null`); a rotated one is
- * kept until the session expires, so its refresh token coming back is
- * recognized as reuse.
+ * kept until its session is swept, so its refresh token coming back is
+ * recognized as reuse. The `sessionId` index is what the session sweep and
+ * the erase delete a session's generations by.
  */
 export class RelyingPartyBearerTokenDoc extends plugins.nosqldb.SmartDataDbDoc<RelyingPartyBearerTokenDoc, RelyingPartyBearerTokenDoc> {
   @plugins.nosqldb.unI()
@@ -177,6 +181,7 @@ export class RelyingPartyBearerTokenDoc extends plugins.nosqldb.SmartDataDbDoc<R
   public refreshTokenHash: string = '';
 
   @plugins.nosqldb.svDb()
+  @plugins.nosqldb.index()
   public sessionId: string = '';
 
   @plugins.nosqldb.svDb()
@@ -190,9 +195,27 @@ export class RelyingPartyBearerTokenDoc extends plugins.nosqldb.SmartDataDbDoc<R
   @plugins.nosqldb.index()
   public expiresAt: number = 0;
 
-  /** `null` while this generation is current; when its refresh token was spent otherwise */
+  /** `null` while this generation is current; when its refresh token was spent, or the generation revoked, otherwise */
   @plugins.nosqldb.svDb()
   public rotatedAt: number | null = null;
+
+  /**
+   * When its access token or its refresh token was first presented; `null`
+   * until then (and on a generation stored before 19.6.0). A rotated
+   * generation whose successor was never presented may come back within the
+   * reuse grace window as a lost answer.
+   */
+  @plugins.nosqldb.svDb()
+  public firstUsedAt: number | null = null;
+
+  /**
+   * The generation that replaced this one: set by its rotation and moved to
+   * the new one when a lost answer is issued again. `null` on a current
+   * generation, on one that was revoked unpresented, and on one stored before
+   * 19.6.0.
+   */
+  @plugins.nosqldb.svDb()
+  public successorId: string | null = null;
 }
 
 export const RELYING_PARTY_DEFAULT_COLLECTION_NAMES = {

package/ts_relyingparty/helpers.cookies.ts

@@ -3,6 +3,12 @@ export interface ICookieOptions {
   maxAgeSeconds?: number;
   sameSite?: 'Lax' | 'Strict' | 'None';
   secure?: boolean;
+  /**
+   * `Partitioned` (CHIPS): the browser keeps the cookie per top-level site, so
+   * a page framed on another site gets a cookie jar of its own there. Needs
+   * `secure`; a cookie set partitioned is also cleared partitioned.
+   */
+  partitioned?: boolean;
 }
 
 // Control characters, space, DEL and the cookie delimiters are never valid.
@@ -60,6 +66,13 @@ export const serializeCookie = (
   if (optionsArg.sameSite) {
     parts.push('SameSite=' + optionsArg.sameSite);
   }
+  if (optionsArg.partitioned) {
+    if (!optionsArg.secure) {
+      // browsers drop a partitioned cookie that is not set Secure
+      throw new Error('A Partitioned cookie needs Secure');
+    }
+    parts.push('Partitioned');
+  }
   if (optionsArg.maxAgeSeconds !== undefined) {
     if (!Number.isSafeInteger(optionsArg.maxAgeSeconds) || optionsArg.maxAgeSeconds < 0) {
       throw new Error('Invalid cookie max age');

package/ts_relyingparty/interfaces.ts

@@ -45,6 +45,27 @@ export interface IResolvedRelyingPartySession<TPrincipal extends object | undefi
   csrfToken: string;
 }
 
+/**
+ * How the session cookie and the login's intent cookie are sent across
+ * sites; one policy for both, on every cookie they are set and cleared with.
+ */
+export interface IRelyingPartyCookiePolicy {
+  /**
+   * `Lax`, the default: the browser sends the cookies with this origin's own
+   * requests and with a top-level navigation to it, never into a frame on
+   * another site. `None`: also for a page of this origin framed on another
+   * site; it needs an https `publicOrigin`, because a `SameSite=None` cookie
+   * must be `Secure`.
+   */
+  sameSite?: 'Lax' | 'None';
+  /**
+   * `Partitioned` (CHIPS): the browser keeps the cookies per top-level site,
+   * so the framed application has a jar of its own under each site that frames
+   * it. Only with `sameSite: 'None'`. `false` by default.
+   */
+  partitioned?: boolean;
+}
+
 /** A session just opened: the answer, the CSRF token and the `Set-Cookie` value that carries it. */
 export interface IRelyingPartySessionOpening {
   session: IRelyingPartySession;
@@ -119,6 +140,15 @@ export interface IRelyingPartyBearerOptions {
   returnTargets: IRelyingPartyBearerReturnTargets;
   /** how long an access token lives, in seconds; 900 by default, never past its session */
   accessTokenMaxAgeSeconds?: number;
+  /**
+   * How long after a rotation its spent refresh token may come back as a lost
+   * answer instead of reuse, in whole seconds: 60 by default, 0 turns it off,
+   * at most 300. Within it, 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; once the successor was presented, or
+   * after the window, it is reuse and ends the session.
+   */
+  refreshReuseGraceSeconds?: number;
 }
 
 /** What a bearer client sends to start its login. Every field is checked as untrusted input. */
@@ -310,6 +340,8 @@ export type TRelyingPartyEventName =
   | 'session_sweep_failed'
   /** a bearer hand-off code or refresh token came back after its use; `reason` names which, the session ended */
   | 'bearer_credential_reused'
+  /** a spent refresh token came back within `refreshReuseGraceSeconds` before its successor was presented: the successor was revoked and a new pair issued */
+  | 'bearer_refresh_reissued'
   /** an application hook threw; the step it belonged to ran on regardless */
   | 'hook_failed'
   /** a session whose opening failed could not be revoked; its provider tokens went back anyway */