@idp.global/sdk 19.3.0 → 19.4.0

package/ts_relyingparty/classes.relyingpartysessions.ts

@@ -52,6 +52,8 @@ import type {
   IRelyingPartyLoginStart,
   IRelyingPartySession,
   IRelyingPartySessionOpening,
+  IRelyingPartySessionsPage,
+  IRelyingPartySessionsPageOptions,
   IResolvedRelyingPartySession,
   TLoginCallbackStage,
   TRelyingPartyPrincipals,
@@ -69,10 +71,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 +115,12 @@ export interface IRelyingPartySessionsOptions<TPrincipal extends object | undefi
   sessionEncryptionKey: Buffer;
   /** 32 bytes; the CSRF HMAC key */
   csrfKey: Buffer;
+  /**
+   * `true` (the default): cookie sessions with a session-bound CSRF token,
+   * beside bearer hand-off mode when `bearer` is given. Bearer hand-off alone,
+   * without any cookie, is `IRelyingPartyBearerOnlySessionsOptions`.
+   */
+  cookieSessions?: true;
   /** the label the CSRF HMAC starts with; an application with live sessions keeps its own */
   csrfLabel?: string;
   sessionMaxAgeSeconds?: number;
@@ -131,8 +145,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 is a provider login */
+  provider: IOidcProvider;
+  bearer: IRelyingPartyBearerOptions;
+  csrfKey?: never;
+  csrfLabel?: never;
+  cookieNames?: never;
+}
+
 type TSealedTokens = Pick<RelyingPartySessionDoc, 'sealedAccessToken' | 'sealedRefreshToken'>;
 
+/** Cookie sessions as the constructor checked them; absent in bearer-only mode. */
+interface ICookieSessionsMode {
+  csrfKey: Buffer;
+  csrfLabel: string;
+}
+
 /** Bearer hand-off mode as the constructor checked it. */
 interface IBearerMode {
   returnTargets: Readonly<Required<IRelyingPartyBearerReturnTargets>>;
@@ -180,6 +222,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,9 +290,16 @@ const cookieNameFor = (
  * token, provider tokens sealed at rest and rotated under a cross-replica
  * lock, and session ends that hand the tokens back.
  *
- * Nothing here runs on a timer: expired login attempts are swept when the next
- * login starts, and the only timer — the revocation budget — is unreferenced
- * and cleared on every path. Nothing here does I/O while it is constructed,
+ * With `cookieSessions: false` it runs bearer hand-off mode alone and never
+ * touches a cookie (`IRelyingPartyBearerOnlySessionsOptions`).
+ *
+ * Nothing here runs on a timer: expired login attempts, bearer state and
+ * ended sessions are swept one bounded batch at a time when a login starts or
+ * the application opens a session, and the only timer — the revocation
+ * budget — is unreferenced and cleared on every path. Every session comes
+ * from a login start or from `openSession`, and each of those sweeps a batch
+ * of at least one first, so removal keeps pace with creation and the ended
+ * sessions kept stay bounded. Nothing here does I/O while it is constructed,
  * so it is built before the database connects.
  *
  * `TPrincipal` is what a `principals.resolve` answers; with `isActive`
@@ -233,20 +319,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 +412,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 +424,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 +460,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * cookie with it; it is a whole number of seconds from 1 to that maximum.
    */
   public async openSession(optionsArg: { principalId: string; maxAgeSeconds?: number }): Promise<IRelyingPartySessionOpening> {
+    this.requireCookieSessions();
     if (typeof optionsArg?.principalId !== 'string' || optionsArg.principalId.length === 0) {
       throw new Error('openSession needs a principal id');
     }
@@ -361,16 +468,24 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     if (!Number.isSafeInteger(maxAgeSeconds) || maxAgeSeconds < 1 || maxAgeSeconds > this.sessionMaxAgeSeconds) {
       throw new RangeError(`openSession maxAgeSeconds must be a whole number from 1 to ${this.sessionMaxAgeSeconds}`);
     }
+    await this.sweepEndedSessions();
     const token = randomToken(32);
     const session = this.newSessionDoc(token, optionsArg.principalId, maxAgeSeconds);
     await session.save();
     return this.opening(session, token, maxAgeSeconds);
   }
 
-  /** The live session behind the session cookie, or `null`. A read touches it at most once a minute. */
+  /**
+   * The live session behind the session cookie, or `null`. A read touches it
+   * at most once a minute. Always `null` in bearer-only mode, which reads no
+   * cookie.
+   */
   public async resolveCookieSession(
     cookieHeaderArg: string | null | undefined,
   ): Promise<IResolvedRelyingPartySession<TPrincipal> | null> {
+    if (!this.#cookieSessions) {
+      return null;
+    }
     const token = parseCookies(cookieHeaderArg).get(this.sessionCookieName);
     if (!token || token.length > MAX_COOKIE_TOKEN_LENGTH) {
       return null;
@@ -465,7 +580,46 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     return ended;
   }
 
+  /**
+   * One page of a principal's live sessions, newest first: the ones neither
+   * ended nor expired, and none at all while the principal is not active —
+   * exactly the sessions `isSessionLive` confirms. Pass the page's
+   * `nextCursor` as `cursor` to read the next one; the last page has none.
+   * The cursor is opaque, and one this method did not answer is refused with
+   * `invalid_sessions_cursor`. A session opened while the pages are read is
+   * listed only when it sorts after the cursor; none is listed twice.
+   */
+  public async sessionsOfPrincipal(
+    principalIdArg: string,
+    optionsArg: IRelyingPartySessionsPageOptions = {},
+  ): Promise<IRelyingPartySessionsPage> {
+    if (typeof principalIdArg !== 'string' || principalIdArg === '') {
+      throw new Error('sessionsOfPrincipal needs a principal id');
+    }
+    const limit = optionsArg.limit ?? RELYING_PARTY_DEFAULT_SESSIONS_PAGE_LIMIT;
+    if (!Number.isInteger(limit) || limit < 1 || limit > RELYING_PARTY_MAX_SESSIONS_PAGE_LIMIT) {
+      throw new Error(`limit must be an integer from 1 to ${RELYING_PARTY_MAX_SESSIONS_PAGE_LIMIT}`);
+    }
+    const cursor = optionsArg.cursor === undefined ? undefined : parseSessionsCursor(optionsArg.cursor);
+    if (!(await this.#activePrincipal(principalIdArg))) {
+      return { sessions: [] };
+    }
+    const page = await this.#models.Session.getPagedInstances({
+      filter: { userId: principalIdArg, revokedAt: { $exists: false }, expiresAt: { $gt: this.#now() } },
+      sortField: 'createdAt',
+      sortDirection: 'desc',
+      uniqueField: 'id',
+      limit,
+      ...(cursor ? { cursor } : {}),
+    });
+    return {
+      sessions: page.documents.map((documentArg) => this.snapshot(documentArg)),
+      ...(page.nextCursor ? { nextCursor: serializeSessionsCursor(page.nextCursor) } : {}),
+    };
+  }
+
   public clearSessionCookie(): string {
+    this.requireCookieSessions();
     return serializeClearedCookie(this.sessionCookieName, {
       httpOnly: true,
       secure: this.secureCookies,
@@ -474,6 +628,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
   }
 
   public clearIntentCookie(): string {
+    this.requireCookieSessions();
     return serializeClearedCookie(this.intentCookieName, {
       httpOnly: true,
       secure: this.secureCookies,
@@ -491,9 +646,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 +686,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     callbackUrlArg: URL,
     cookieHeaderArg: string | null | undefined,
   ): Promise<IRelyingPartySessionOpening> {
+    this.requireCookieSessions();
     const provider = this.requireProvider();
     const states = callbackUrlArg.searchParams.getAll('state');
     if (states.length !== 1 || !states[0]) {
@@ -564,6 +722,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * matches no open attempt leaves nothing to do.
    */
   public async abandonLogin(callbackUrlArg: URL, cookieHeaderArg: string | null | undefined): Promise<void> {
+    this.requireCookieSessions();
     const states = callbackUrlArg.searchParams.getAll('state');
     const bindingToken = parseCookies(cookieHeaderArg).get(this.intentCookieName);
     if (
@@ -586,6 +745,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * session this very attempt created.
    */
   public async finalizeLogin(cookieHeaderArg: string | null | undefined): Promise<string> {
+    this.requireCookieSessions();
     this.requireProvider();
     const bindingToken = parseCookies(cookieHeaderArg).get(this.intentCookieName);
     if (!bindingToken || bindingToken.length > MAX_COOKIE_TOKEN_LENGTH) {
@@ -648,6 +808,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));
@@ -910,8 +1071,22 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * is unknown — is rotated first. The session has to belong to
    * `expectedPrincipalIdArg`, so a credential is never evaluated with another
    * person's tokens.
+   *
+   * With `rejectedAccessToken` (`IAuthorityTokenSource`) the call rotates the
+   * session's token whatever is stored, and only a rotation that it starts
+   * marks its answer `rotatedAfterRejection`: one that started before it, in
+   * this process or another replica's, says nothing about the rejection, so
+   * the call awaits it and throws `authority_unavailable`. A refused rotation
+   * ends the session (`refresh_token_refused`) and throws
+   * `authority_login_required`. A session without a refresh token has nothing
+   * to rotate with: it throws `authority_unavailable`, or ends as
+   * `access_token_unusable` when its token is dead.
    */
-  public async liveProviderToken(sessionIdArg: string, expectedPrincipalIdArg: string): Promise<IProviderToken> {
+  public async liveProviderToken(
+    sessionIdArg: string,
+    expectedPrincipalIdArg: string,
+    optionsArg: { rejectedAccessToken?: string } = {},
+  ): Promise<IProviderToken> {
     const session = await this.#models.Session.getInstance({ id: sessionIdArg });
     const now = this.#now();
     if (
@@ -926,35 +1101,60 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     const subject = session.idpSubject;
     const expiresAt = typeof session.accessTokenExpiresAt === 'number' ? session.accessTokenExpiresAt : 0;
     const accessToken = this.openSealed(session.sealedAccessToken);
+    const forced = optionsArg.rejectedAccessToken !== undefined;
     // an unknown expiry is rotated too: afterwards the lifetime is known
-    const due = accessToken === undefined || expiresAt === 0 || expiresAt <= now + ACCESS_TOKEN_REFRESH_SKEW_MS;
+    const due = forced
+      || accessToken === undefined
+      || expiresAt === 0
+      || expiresAt <= now + ACCESS_TOKEN_REFRESH_SKEW_MS;
     if (!due && accessToken !== undefined) {
       return { accessToken, subject, expiresAt };
     }
     if (!session.sealedRefreshToken) {
       if (accessToken !== undefined && (expiresAt === 0 || expiresAt > now)) {
         // nothing to rotate with, and the token is not known to be dead
+        if (forced) {
+          throw new AuthorityTokenError('authority_unavailable');
+        }
         return { accessToken, subject, expiresAt };
       }
       await this.endProviderSession(sessionIdArg, 'access_token_unusable');
       throw new AuthorityTokenError('authority_login_required');
     }
-    return this.refreshProviderToken(sessionIdArg, subject);
+    return this.refreshProviderToken(sessionIdArg, subject, forced);
   }
 
-  private async refreshProviderToken(sessionIdArg: string, subjectArg: string): Promise<IProviderToken> {
+  /**
+   * One rotation of the session in this process at a time. A forced call that
+   * finds one running waits for it, so a refusal still ends it, and is
+   * unavailable otherwise: that rotation started before the call.
+   */
+  private async refreshProviderToken(
+    sessionIdArg: string,
+    subjectArg: string,
+    forcedArg: boolean,
+  ): Promise<IProviderToken> {
     const running = this.#refreshesInFlight.get(sessionIdArg);
     if (running) {
-      return running;
+      const joined = await running;
+      if (forcedArg) {
+        throw new AuthorityTokenError('authority_unavailable');
+      }
+      return joined;
     }
-    const pending = this.runProviderRefresh(sessionIdArg, subjectArg).finally(() => {
+    const pending = this.runProviderRefresh(sessionIdArg, subjectArg, forcedArg).finally(() => {
       this.#refreshesInFlight.delete(sessionIdArg);
     });
     this.#refreshesInFlight.set(sessionIdArg, pending);
-    return pending;
+    // only the call that started the rotation is told so; others that join it are not
+    return forcedArg ? { ...(await pending), rotatedAfterRejection: true } : pending;
   }
 
-  private async runProviderRefresh(sessionIdArg: string, subjectArg: string): Promise<IProviderToken> {
+  private async runProviderRefresh(
+    sessionIdArg: string,
+    subjectArg: string,
+    forcedArg: boolean,
+  ): Promise<IProviderToken> {
     const provider = this.#provider;
     if (!provider) {
       throw new AuthorityTokenError('authority_unavailable');
@@ -973,15 +1173,21 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
       { returnDocument: 'after' },
     );
     if (claimed.status !== 'matched' || !claimed.document) {
+      if (forcedArg) {
+        // nothing tells when the other replica's rotation started
+        throw new AuthorityTokenError('authority_unavailable');
+      }
       return this.tokenAfterForeignRefresh(sessionIdArg, subjectArg);
     }
     const session = claimed.document as RelyingPartySessionDoc;
     // the lock holder decides on the state it just read: a rotation that
     // landed in between is used as it stands, because spending a superseded
-    // refresh token would be reuse and would kill the family
+    // refresh token would be reuse and would kill the family; a forced call
+    // rotates the stored pair however long its token would last, since only a
+    // rotation it starts comes after the rejection
     const claimedExpiry = typeof session.accessTokenExpiresAt === 'number' ? session.accessTokenExpiresAt : 0;
     const claimedToken = this.openSealed(session.sealedAccessToken);
-    if (claimedToken !== undefined && claimedExpiry > this.#now() + ACCESS_TOKEN_REFRESH_SKEW_MS) {
+    if (!forcedArg && claimedToken !== undefined && claimedExpiry > this.#now() + ACCESS_TOKEN_REFRESH_SKEW_MS) {
       await this.#models.Session.atomicUpdate(
         { id: sessionIdArg, revokedAt: { $exists: false }, refreshLockUntil: lockUntil },
         { $set: { refreshLockUntil: 0 } },
@@ -1069,6 +1275,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 +1378,8 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
   }
 
   private csrfTokenOf(tokenArg: string): string {
-    return deriveCsrfToken(tokenArg, this.#csrfKey, this.#csrfLabel);
+    const { csrfKey, csrfLabel } = this.requireCookieSessions();
+    return deriveCsrfToken(tokenArg, csrfKey, csrfLabel);
   }
 
   private opening(sessionArg: RelyingPartySessionDoc, tokenArg: string, maxAgeSecondsArg: number = this.sessionMaxAgeSeconds): IRelyingPartySessionOpening {
@@ -1337,10 +1551,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;
   }
 
   /**
@@ -1382,17 +1625,11 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     if (typeof sessionIdArg !== 'string' || sessionIdArg.length === 0) {
       return null;
     }
-    const revoked = await this.#models.Session.atomicFindOneAndUpdate(
-      { id: sessionIdArg, revokedAt: { $exists: false } },
-      { $set: { revokedAt: this.#now(), ...REVOKED_TOKEN_FIELDS } },
-      { returnDocument: 'before' },
-    );
-    const revokedHere = revoked.status === 'matched' && revoked.document !== null;
-    this.notifySessionEnded({ sessionId: sessionIdArg, reason: reasonArg, revokedHere });
-    if (!revokedHere) {
+    const before = await this.revokeSessionDocument(sessionIdArg);
+    this.notifySessionEnded({ sessionId: sessionIdArg, reason: reasonArg, revokedHere: before !== null });
+    if (!before) {
       return null;
     }
-    const before = revoked.document as RelyingPartySessionDoc;
     return { sealedAccessToken: before.sealedAccessToken, sealedRefreshToken: before.sealedRefreshToken };
   }
 
@@ -1564,6 +1801,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

package/ts_relyingparty/classes.rpmodels.ts

@@ -3,10 +3,11 @@ import { RelyingPartyDatabaseUnavailableError } from './classes.errors.js';
 import type { TRelyingPartyBearerClientKind } from './interfaces.js';
 
 /**
- * One browser session of a relying party. The persisted field names, their
- * types and the index declarations are the ones nevermind.finance has stored
- * under `SessionDoc` since before this module existed, so its collection is
- * read and written unchanged.
+ * One browser session of a relying party. The persisted field names and their
+ * types are the ones nevermind.finance has stored under `SessionDoc` since
+ * before this module existed, so its collection is read and written
+ * unchanged; its indexes are those and the `expiresAt` index the sweep of
+ * ended sessions reads.
  */
 export class RelyingPartySessionDoc extends plugins.nosqldb.SmartDataDbDoc<RelyingPartySessionDoc, RelyingPartySessionDoc> {
   @plugins.nosqldb.unI()
@@ -27,7 +28,9 @@ export class RelyingPartySessionDoc extends plugins.nosqldb.SmartDataDbDoc<Relyi
   @plugins.nosqldb.svDb()
   public lastSeenAt: number = 0;
 
+  /** a revocation lowers it to `revokedAt` when that is earlier, so the sweep finds every ended session by it */
   @plugins.nosqldb.svDb()
+  @plugins.nosqldb.index()
   public expiresAt: number = 0;
 
   /** absent while the session is valid */