@idp.global/sdk 18.0.1 → 18.1.0

package/ts_relyingparty/classes.relyingpartysessions.ts

@@ -0,0 +1,970 @@
+import { SecretBox } from './classes.secretbox.js';
+import {
+  AuthorityTokenError,
+  LoginCallbackError,
+  RelyingPartyError,
+  RelyingPartyRefusal,
+} from './classes.errors.js';
+import {
+  OidcCompletionError,
+  OidcRefreshRefusedError,
+  type IOidcCompletion,
+  type IOidcProvider,
+  type IOidcRefreshedTokens,
+  type TOidcTokenHint,
+} from './classes.idpoidcprovider.js';
+import type { IRelyingPartyModels, RelyingPartyLoginAttemptDoc, RelyingPartySessionDoc } from './classes.rpmodels.js';
+import { parseCookies, serializeClearedCookie, serializeCookie } from './helpers.cookies.js';
+import { deriveCsrfToken, randomToken, sha256, timingSafeEqualString } from './helpers.crypto.js';
+import { sanitizeReturnPath } from './helpers.returnpath.js';
+import type {
+  IAuthorityTokenSource,
+  IProviderToken,
+  IRelyingPartyEvent,
+  IRelyingPartyHooks,
+  IRelyingPartyLoginStart,
+  IRelyingPartyPrincipals,
+  IRelyingPartySession,
+  IRelyingPartySessionOpening,
+  IResolvedRelyingPartySession,
+  TLoginCallbackStage,
+  TRelyingPartySessionEndReason,
+} from './interfaces.js';
+
+export const RELYING_PARTY_DEFAULT_SESSION_MAX_AGE_SECONDS = 12 * 60 * 60;
+export const RELYING_PARTY_DEFAULT_LOGIN_PATH_PREFIX = '/auth/';
+/** The label the CSRF HMAC starts with unless the application names its own. */
+export const RELYING_PARTY_DEFAULT_CSRF_LABEL = 'idp.global/sdk relyingparty csrf' + String.fromCharCode(0);
+
+const MAX_COOKIE_TOKEN_LENGTH = 256;
+const SESSION_TOUCH_INTERVAL_MS = 60_000;
+/** A sign-in transaction has to survive an interactive login at the provider, not a working day. */
+export const LOGIN_ATTEMPT_MAX_AGE_SECONDS = 10 * 60;
+/** Attempts are swept once they are this much older than their expiry. */
+const LOGIN_ATTEMPT_SWEEP_GRACE_MS = 60 * 60 * 1_000;
+/** How many of them one sign-in removes; the next sign-in takes the following page. */
+const LOGIN_ATTEMPT_SWEEP_BATCH = 100;
+/**
+ * How long ending a session waits for the provider to take its tokens back.
+ * The local session is already revoked when that call runs.
+ */
+export const TOKEN_REVOCATION_BUDGET_MS = 3_000;
+/** How long before its expiry the provider access token is rotated. */
+export const ACCESS_TOKEN_REFRESH_SKEW_MS = 60_000;
+/**
+ * What the refresh lock adds on top of the provider request it has to cover:
+ * the claim and the store around it, and clock disagreement between replicas.
+ */
+export const REFRESH_LOCK_MARGIN_MS = 20_000;
+
+export interface IRelyingPartySessionsOptions {
+  models: IRelyingPartyModels;
+  principals: IRelyingPartyPrincipals;
+  /** absent: no provider login; sessions are opened by the application only */
+  provider?: IOidcProvider;
+  /** the application's public origin, e.g. `https://app.example`; cookies are `Secure` exactly on https */
+  publicOrigin: string;
+  /** 32 bytes; seals the PKCE verifier and the provider tokens at rest */
+  sessionEncryptionKey: Buffer;
+  /** 32 bytes; the CSRF HMAC key */
+  csrfKey: Buffer;
+  /** the label the CSRF HMAC starts with; an application with live sessions keeps its own */
+  csrfLabel?: string;
+  sessionMaxAgeSeconds?: number;
+  /**
+   * defaults: `__Host-idp_rp_session` / `__Host-idp_rp_intent` on https,
+   * without the prefix otherwise. A `__Host-` or `__Secure-` name needs an
+   * https origin and is refused on http.
+   */
+  cookieNames?: {
+    session?: string;
+    intent?: string;
+  };
+  /** the prefix of the login routes; a login never returns into it */
+  loginPathPrefix?: string;
+  hooks?: IRelyingPartyHooks;
+  /** the clock every comparison reads; tests step it instead of sleeping */
+  now?: () => number;
+}
+
+type TSealedTokens = Pick<RelyingPartySessionDoc, 'sealedAccessToken' | 'sealedRefreshToken'>;
+
+const REVOKED_TOKEN_FIELDS = { sealedAccessToken: '', sealedRefreshToken: '', refreshLockUntil: 0 };
+
+const errorMessage = (errorArg: unknown): string => (errorArg instanceof Error ? errorArg.message : String(errorArg));
+
+/** Browsers store a cookie with one of these prefixes only when it is set `Secure`; they match it case-insensitively. */
+const SECURE_COOKIE_NAME_PREFIX = /^__(host|secure)-/i;
+
+const cookieNameFor = (
+  configuredArg: string | undefined,
+  defaultArg: string,
+  secureArg: boolean,
+  labelArg: 'session' | 'intent',
+): string => {
+  if (configuredArg === undefined) {
+    return defaultArg;
+  }
+  if (!secureArg && SECURE_COOKIE_NAME_PREFIX.test(configuredArg)) {
+    throw new Error(
+      `cookieNames.${labelArg} "${configuredArg}" needs an https publicOrigin: `
+        + 'browsers drop a __Host- or __Secure- cookie that is not set Secure',
+    );
+  }
+  return configuredArg;
+};
+
+/**
+ * The relying-party session layer: provider logins through the authorization
+ * code flow with PKCE, HttpOnly cookie sessions with a session-bound CSRF
+ * 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.
+ */
+export class RelyingPartySessions implements IAuthorityTokenSource {
+  public readonly publicOrigin: string;
+  public readonly secureCookies: boolean;
+  public readonly sessionCookieName: string;
+  public readonly intentCookieName: string;
+  public readonly loginPathPrefix: string;
+  public readonly sessionMaxAgeSeconds: number;
+  readonly #models: IRelyingPartyModels;
+  readonly #principals: IRelyingPartyPrincipals;
+  readonly #provider?: IOidcProvider;
+  readonly #secretBox: SecretBox;
+  readonly #csrfKey: Buffer;
+  readonly #csrfLabel: string;
+  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) {
+    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 maxAge = optionsArg.sessionMaxAgeSeconds ?? RELYING_PARTY_DEFAULT_SESSION_MAX_AGE_SECONDS;
+    if (!Number.isSafeInteger(maxAge) || maxAge < 1) {
+      throw new Error('sessionMaxAgeSeconds must be a positive integer');
+    }
+    this.publicOrigin = origin.origin;
+    this.secureCookies = origin.protocol === 'https:';
+    const prefix = this.secureCookies ? '__Host-' : '';
+    this.sessionCookieName = cookieNameFor(
+      optionsArg.cookieNames?.session,
+      prefix + 'idp_rp_session',
+      this.secureCookies,
+      'session',
+    );
+    this.intentCookieName = cookieNameFor(
+      optionsArg.cookieNames?.intent,
+      prefix + 'idp_rp_intent',
+      this.secureCookies,
+      'intent',
+    );
+    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');
+    }
+    this.sessionMaxAgeSeconds = maxAge;
+    this.#models = optionsArg.models;
+    this.#principals = optionsArg.principals;
+    this.#provider = optionsArg.provider;
+    this.#secretBox = new SecretBox(optionsArg.sessionEncryptionKey);
+    this.#csrfKey = Buffer.from(optionsArg.csrfKey);
+    this.#csrfLabel = optionsArg.csrfLabel ?? RELYING_PARTY_DEFAULT_CSRF_LABEL;
+    this.#hooks = optionsArg.hooks ?? {};
+    this.#now = optionsArg.now ?? (() => Date.now());
+  }
+
+  /** Whether provider logins are offered at all. */
+  public get providerLoginEnabled(): boolean {
+    return this.#provider !== undefined;
+  }
+
+  /**
+   * How long one replica holds the right to rotate a session's tokens. The
+   * provider detects reuse of a superseded refresh token and kills the family,
+   * so the lock strictly outlives its longest possible holder: one provider
+   * request at its full deadline plus the margin.
+   */
+  public get refreshLockMs(): number {
+    return (this.#provider?.requestTimeoutSeconds ?? 0) * 1_000 + REFRESH_LOCK_MARGIN_MS;
+  }
+
+  // ==========================================================================
+  // sessions
+  // ==========================================================================
+
+  /**
+   * Opens a session the application authenticated itself (a local password
+   * login). It carries no provider tokens.
+   */
+  public async openSession(optionsArg: { principalId: string }): Promise<IRelyingPartySessionOpening> {
+    if (typeof optionsArg?.principalId !== 'string' || optionsArg.principalId.length === 0) {
+      throw new Error('openSession needs a principal id');
+    }
+    const token = randomToken(32);
+    const session = this.newSessionDoc(token, optionsArg.principalId);
+    await session.save();
+    return this.opening(session, token);
+  }
+
+  /** The live session behind the session cookie, or `null`. A read touches it at most once a minute. */
+  public async resolveCookieSession(
+    cookieHeaderArg: string | null | undefined,
+  ): Promise<IResolvedRelyingPartySession | null> {
+    const token = parseCookies(cookieHeaderArg).get(this.sessionCookieName);
+    if (!token || token.length > MAX_COOKIE_TOKEN_LENGTH) {
+      return null;
+    }
+    const session = await this.#models.Session.getInstance({ tokenHash: sha256(token) });
+    const live = await this.liveSession(session);
+    if (!live) {
+      return null;
+    }
+    return { session: this.snapshot(live), csrfToken: this.csrfTokenOf(token) };
+  }
+
+  /**
+   * Re-checks a session by its id with the same strength as a cookie request:
+   * live, its principal active, and touched under the liveness it was read
+   * with. What a pinned socket connection runs per request.
+   */
+  public async revalidateSession(sessionIdArg: string): Promise<IRelyingPartySession | null> {
+    if (typeof sessionIdArg !== 'string' || sessionIdArg.length === 0) {
+      return null;
+    }
+    const live = await this.liveSession(await this.#models.Session.getInstance({ id: sessionIdArg }));
+    return live ? this.snapshot(live) : null;
+  }
+
+  /** Whether a session is live right now, without touching it; what a sweep asks. */
+  public async isSessionLive(sessionIdArg: string): Promise<boolean> {
+    if (typeof sessionIdArg !== 'string' || sessionIdArg.length === 0) {
+      return false;
+    }
+    const session = await this.#models.Session.getInstance({ id: sessionIdArg });
+    if (!session || session.revokedAt !== undefined || session.expiresAt <= this.#now()) {
+      return false;
+    }
+    return this.#principals.isActive(session.userId);
+  }
+
+  public validateCsrf(resolvedArg: IResolvedRelyingPartySession, candidateArg: unknown): boolean {
+    return typeof candidateArg === 'string' && timingSafeEqualString(resolvedArg.csrfToken, candidateArg);
+  }
+
+  /** Ends one session; see `endSession`. */
+  public async logout(sessionIdArg: string): Promise<boolean> {
+    return this.endSession(sessionIdArg);
+  }
+
+  /**
+   * Revokes a session once, with one conditional update: a touch running
+   * beside it cannot write the revocation away, and a second call finds
+   * nothing. Its provider tokens go back within `TOKEN_REVOCATION_BUDGET_MS`,
+   * after the local revocation, which never depends on the provider. Answers
+   * whether this call ended it.
+   */
+  public async endSession(
+    sessionIdArg: string,
+    reasonArg: TRelyingPartySessionEndReason = 'logout',
+  ): Promise<boolean> {
+    const ended = await this.revokeSession(sessionIdArg, reasonArg);
+    if (ended) {
+      await this.revokeSealedTokens(ended);
+    }
+    return ended !== null;
+  }
+
+  /**
+   * Ends every live session of a principal but `keepSessionId` (a password
+   * change keeps the session that asked for it) and answers how many ended.
+   */
+  public async endSessionsOfPrincipal(
+    principalIdArg: string,
+    optionsArg: { keepSessionId?: string } = {},
+  ): Promise<number> {
+    let ended = 0;
+    const sessions = await this.#models.Session.getInstances({
+      userId: principalIdArg,
+      revokedAt: { $exists: false },
+    });
+    for (const session of sessions) {
+      if (session.id === optionsArg.keepSessionId) {
+        continue;
+      }
+      if (await this.endSession(session.id)) {
+        ended += 1;
+      }
+    }
+    return ended;
+  }
+
+  public clearSessionCookie(): string {
+    return serializeClearedCookie(this.sessionCookieName, {
+      httpOnly: true,
+      secure: this.secureCookies,
+      sameSite: 'Lax',
+    });
+  }
+
+  public clearIntentCookie(): string {
+    return serializeClearedCookie(this.intentCookieName, {
+      httpOnly: true,
+      secure: this.secureCookies,
+      sameSite: 'Lax',
+    });
+  }
+
+  // ==========================================================================
+  // provider login
+  // ==========================================================================
+
+  /**
+   * Starts a sign-in transaction: one attempt document with the PKCE verifier
+   * sealed next to it, and an intent cookie that binds the callback to this
+   * browser.
+   */
+  public async startLogin(returnPathArg: unknown): Promise<IRelyingPartyLoginStart> {
+    const provider = this.requireProvider();
+    await this.sweepExpiredAttempts();
+    const state = randomToken(32);
+    const nonce = randomToken(32);
+    const pkceVerifier = randomToken(32);
+    const bindingToken = randomToken(32);
+    const now = this.#now();
+
+    const attempt = new this.#models.LoginAttempt();
+    attempt.id = 'lga_' + randomToken(18);
+    attempt.stateHash = sha256(state);
+    attempt.bindingTokenHash = sha256(bindingToken);
+    attempt.sealedPkceVerifier = this.#secretBox.seal(pkceVerifier);
+    attempt.nonce = nonce;
+    attempt.returnPath = sanitizeReturnPath(returnPathArg, this.publicOrigin, this.loginPathPrefix);
+    attempt.createdAt = now;
+    attempt.expiresAt = now + LOGIN_ATTEMPT_MAX_AGE_SECONDS * 1_000;
+    await attempt.save();
+
+    return {
+      authorizationUrl: await provider.buildAuthorizationUrl({ state, nonce, pkceVerifier }),
+      intentCookie: serializeCookie(this.intentCookieName, bindingToken, {
+        httpOnly: true,
+        secure: this.secureCookies,
+        sameSite: 'Lax',
+        maxAgeSeconds: LOGIN_ATTEMPT_MAX_AGE_SECONDS,
+      }),
+    };
+  }
+
+  /**
+   * Consumes the attempt exactly once, exchanges the code, admits the
+   * principal and opens a session. A replayed callback, a foreign intent
+   * cookie and an expired attempt all find nothing to consume. Nothing of a
+   * failed login survives: its tokens are handed back before the failure
+   * leaves.
+   */
+  public async completeLogin(
+    callbackUrlArg: URL,
+    cookieHeaderArg: string | null | undefined,
+  ): Promise<IRelyingPartySessionOpening> {
+    const provider = this.requireProvider();
+    const states = callbackUrlArg.searchParams.getAll('state');
+    if (states.length !== 1 || !states[0]) {
+      throw new RelyingPartyError('invalid_login_callback');
+    }
+    const bindingToken = parseCookies(cookieHeaderArg).get(this.intentCookieName);
+    if (!bindingToken || bindingToken.length > MAX_COOKIE_TOKEN_LENGTH) {
+      throw new RelyingPartyError('missing_login_intent');
+    }
+
+    const now = this.#now();
+    const claimed = await this.#models.LoginAttempt.atomicFindOneAndUpdate(
+      {
+        stateHash: sha256(states[0]),
+        bindingTokenHash: sha256(bindingToken),
+        consumedAt: null,
+        expiresAt: { $gt: now },
+      },
+      { $set: { consumedAt: now } },
+      { returnDocument: 'after' },
+    );
+    if (claimed.status !== 'matched' || !claimed.document) {
+      throw new RelyingPartyError('invalid_or_replayed_login');
+    }
+    const attempt = claimed.document as RelyingPartyLoginAttemptDoc;
+
+    let completion: IOidcCompletion | undefined;
+    let stage: TLoginCallbackStage = 'token_exchange';
+    try {
+      completion = await provider.completeAuthorization({
+        callbackUrl: callbackUrlArg,
+        state: states[0],
+        nonce: attempt.nonce,
+        pkceVerifier: this.#secretBox.open(attempt.sealedPkceVerifier),
+      });
+      stage = 'principal_admission';
+      const { principalId } = await this.#principals.admit(completion);
+      stage = 'session_persistence';
+      return await this.createProviderSession(attempt, principalId, completion);
+    } catch (error) {
+      if (completion) {
+        await this.revokeCompletionTokens(completion);
+      }
+      if (error instanceof RelyingPartyError || error instanceof RelyingPartyRefusal) {
+        throw error;
+      }
+      if (error instanceof OidcCompletionError) {
+        throw new LoginCallbackError(error.stage, error);
+      }
+      throw new LoginCallbackError(stage, error);
+    }
+  }
+
+  /**
+   * The provider sent the browser back without a code. The attempt is
+   * consumed so its state can never complete afterwards; a callback that
+   * matches no open attempt leaves nothing to do.
+   */
+  public async abandonLogin(callbackUrlArg: URL, cookieHeaderArg: string | null | undefined): Promise<void> {
+    const states = callbackUrlArg.searchParams.getAll('state');
+    const bindingToken = parseCookies(cookieHeaderArg).get(this.intentCookieName);
+    if (
+      states.length !== 1
+      || !states[0]
+      || !bindingToken
+      || bindingToken.length > MAX_COOKIE_TOKEN_LENGTH
+    ) {
+      return;
+    }
+    await this.#models.LoginAttempt.atomicUpdate(
+      { stateHash: sha256(states[0]), bindingTokenHash: sha256(bindingToken), consumedAt: null },
+      { $set: { consumedAt: this.#now() } },
+    );
+  }
+
+  /**
+   * The last step of a login: the browser arrives with both cookies, and the
+   * return path is released only when the session cookie belongs to the
+   * session this very attempt created.
+   */
+  public async finalizeLogin(cookieHeaderArg: string | null | undefined): Promise<string> {
+    this.requireProvider();
+    const bindingToken = parseCookies(cookieHeaderArg).get(this.intentCookieName);
+    if (!bindingToken || bindingToken.length > MAX_COOKIE_TOKEN_LENGTH) {
+      throw new RelyingPartyError('invalid_login_finalize');
+    }
+    const attempt = await this.#models.LoginAttempt.getInstance({ bindingTokenHash: sha256(bindingToken) });
+    if (
+      !attempt
+      || attempt.consumedAt === undefined
+      || attempt.consumedAt === null
+      || !attempt.createdSessionId
+      || attempt.expiresAt <= this.#now()
+    ) {
+      throw new RelyingPartyError('invalid_login_finalize');
+    }
+    const resolved = await this.resolveCookieSession(cookieHeaderArg);
+    if (
+      !resolved
+      || resolved.session.id !== attempt.createdSessionId
+      || resolved.session.loginAttemptId !== attempt.id
+    ) {
+      throw new RelyingPartyError('invalid_login_finalize');
+    }
+    return sanitizeReturnPath(attempt.returnPath, this.publicOrigin, this.loginPathPrefix);
+  }
+
+  // ==========================================================================
+  // provider tokens
+  // ==========================================================================
+
+  /**
+   * An access token of this login session that is usable right now. A token
+   * within `ACCESS_TOKEN_REFRESH_SKEW_MS` of its expiry — or one whose expiry
+   * is unknown — is rotated first. The session has to belong to
+   * `expectedPrincipalIdArg`, so a credential is never evaluated with another
+   * person's tokens.
+   */
+  public async liveProviderToken(sessionIdArg: string, expectedPrincipalIdArg: string): Promise<IProviderToken> {
+    const session = await this.#models.Session.getInstance({ id: sessionIdArg });
+    const now = this.#now();
+    if (
+      !session
+      || session.revokedAt !== undefined
+      || session.expiresAt <= now
+      || !session.idpSubject
+      || session.userId !== expectedPrincipalIdArg
+    ) {
+      throw new AuthorityTokenError('authority_login_required');
+    }
+    const subject = session.idpSubject;
+    const expiresAt = typeof session.accessTokenExpiresAt === 'number' ? session.accessTokenExpiresAt : 0;
+    const accessToken = this.openSealed(session.sealedAccessToken);
+    // an unknown expiry is rotated too: afterwards the lifetime is known
+    const due = 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
+        return { accessToken, subject, expiresAt };
+      }
+      await this.endProviderSession(sessionIdArg, 'access_token_unusable');
+      throw new AuthorityTokenError('authority_login_required');
+    }
+    return this.refreshProviderToken(sessionIdArg, subject);
+  }
+
+  private async refreshProviderToken(sessionIdArg: string, subjectArg: string): Promise<IProviderToken> {
+    const running = this.#refreshesInFlight.get(sessionIdArg);
+    if (running) {
+      return running;
+    }
+    const pending = this.runProviderRefresh(sessionIdArg, subjectArg).finally(() => {
+      this.#refreshesInFlight.delete(sessionIdArg);
+    });
+    this.#refreshesInFlight.set(sessionIdArg, pending);
+    return pending;
+  }
+
+  private async runProviderRefresh(sessionIdArg: string, subjectArg: string): Promise<IProviderToken> {
+    const provider = this.#provider;
+    if (!provider) {
+      throw new AuthorityTokenError('authority_unavailable');
+    }
+    const now = this.#now();
+    const lockUntil = now + this.refreshLockMs;
+    const claimed = await this.#models.Session.atomicFindOneAndUpdate(
+      {
+        id: sessionIdArg,
+        revokedAt: { $exists: false },
+        expiresAt: { $gt: now },
+        // a lock another replica holds is left alone until it expires
+        $or: [{ refreshLockUntil: { $lt: now } }, { refreshLockUntil: { $exists: false } }],
+      },
+      { $set: { refreshLockUntil: lockUntil } },
+      { returnDocument: 'after' },
+    );
+    if (claimed.status !== 'matched' || !claimed.document) {
+      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
+    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) {
+      await this.#models.Session.atomicUpdate(
+        { id: sessionIdArg, revokedAt: { $exists: false }, refreshLockUntil: lockUntil },
+        { $set: { refreshLockUntil: 0 } },
+      );
+      return { accessToken: claimedToken, subject: subjectArg, expiresAt: claimedExpiry };
+    }
+    const refreshToken = this.openSealed(session.sealedRefreshToken);
+    if (refreshToken === undefined) {
+      await this.endProviderSession(sessionIdArg, 'sealed_refresh_token_unreadable');
+      throw new AuthorityTokenError('authority_login_required');
+    }
+    let rotated: IOidcRefreshedTokens;
+    try {
+      rotated = await provider.refreshTokens(refreshToken);
+    } catch (error) {
+      if (error instanceof OidcRefreshRefusedError) {
+        await this.endProviderSession(sessionIdArg, 'refresh_token_refused');
+        throw new AuthorityTokenError('authority_login_required', error);
+      }
+      this.emit({ event: 'idp_token_refresh_failed', sessionId: sessionIdArg, message: errorMessage(error) });
+      throw new AuthorityTokenError('authority_unavailable', error);
+    }
+    // the rotated pair replaces the old one under this lock, and only while
+    // the session is live: a logout in between leaves the update unmatched
+    let matched: number;
+    try {
+      const written = await this.#models.Session.atomicUpdate(
+        { id: sessionIdArg, revokedAt: { $exists: false }, refreshLockUntil: lockUntil },
+        {
+          $set: {
+            sealedAccessToken: this.#secretBox.seal(rotated.accessToken),
+            ...(rotated.refreshToken ? { sealedRefreshToken: this.#secretBox.seal(rotated.refreshToken) } : {}),
+            accessTokenExpiresAt: rotated.accessTokenExpiresAt,
+            refreshLockUntil: 0,
+          },
+        },
+      );
+      matched = written.matchedCount;
+    } catch (error) {
+      // the provider has superseded the old pair and nothing here can name the
+      // new one: it goes back at once, the lock expires on its own, and the
+      // request fails closed
+      await this.revokeRotatedTokens(rotated);
+      this.emit({ event: 'idp_token_store_failed', sessionId: sessionIdArg, message: errorMessage(error) });
+      throw new AuthorityTokenError('authority_unavailable', error);
+    }
+    if (matched === 0) {
+      await this.revokeRotatedTokens(rotated);
+      this.notifySessionEnded({ sessionId: sessionIdArg, reason: 'revoked_elsewhere', revokedHere: false });
+      throw new AuthorityTokenError('authority_login_required');
+    }
+    return { accessToken: rotated.accessToken, subject: subjectArg, expiresAt: rotated.accessTokenExpiresAt };
+  }
+
+  /**
+   * Another replica is rotating this session right now. Whatever it has
+   * written by the time this request looks again is used; otherwise the
+   * request fails closed and the next one finds the rotated pair.
+   */
+  private async tokenAfterForeignRefresh(sessionIdArg: string, subjectArg: string): Promise<IProviderToken> {
+    const session = await this.#models.Session.getInstance({ id: sessionIdArg });
+    const now = this.#now();
+    const expiresAt = typeof session?.accessTokenExpiresAt === 'number' ? session.accessTokenExpiresAt : 0;
+    const accessToken = session ? this.openSealed(session.sealedAccessToken) : undefined;
+    if (
+      session
+      && session.revokedAt === undefined
+      && session.expiresAt > now
+      && accessToken !== undefined
+      && expiresAt > now + ACCESS_TOKEN_REFRESH_SKEW_MS
+    ) {
+      return { accessToken, subject: subjectArg, expiresAt };
+    }
+    throw new AuthorityTokenError('authority_unavailable');
+  }
+
+  // ==========================================================================
+  // internals
+  // ==========================================================================
+
+  private requireProvider(): IOidcProvider {
+    if (!this.#provider) {
+      throw new RelyingPartyError('login_method_unavailable');
+    }
+    return this.#provider;
+  }
+
+  private newSessionDoc(tokenArg: string, principalIdArg: string): RelyingPartySessionDoc {
+    const now = this.#now();
+    const session = new this.#models.Session();
+    session.id = 'ses_' + randomToken(18);
+    session.tokenHash = sha256(tokenArg);
+    session.userId = principalIdArg;
+    session.createdAt = now;
+    session.lastSeenAt = now;
+    session.expiresAt = now + this.sessionMaxAgeSeconds * 1_000;
+    return session;
+  }
+
+  private csrfTokenOf(tokenArg: string): string {
+    return deriveCsrfToken(tokenArg, this.#csrfKey, this.#csrfLabel);
+  }
+
+  private opening(sessionArg: RelyingPartySessionDoc, tokenArg: string): IRelyingPartySessionOpening {
+    return {
+      session: this.snapshot(sessionArg),
+      csrfToken: this.csrfTokenOf(tokenArg),
+      sessionCookie: serializeCookie(this.sessionCookieName, tokenArg, {
+        httpOnly: true,
+        secure: this.secureCookies,
+        sameSite: 'Lax',
+        maxAgeSeconds: this.sessionMaxAgeSeconds,
+      }),
+    };
+  }
+
+  private snapshot(sessionArg: RelyingPartySessionDoc): IRelyingPartySession {
+    return {
+      id: sessionArg.id,
+      principalId: sessionArg.userId,
+      createdAt: sessionArg.createdAt,
+      lastSeenAt: sessionArg.lastSeenAt,
+      expiresAt: sessionArg.expiresAt,
+      ...(sessionArg.idpSubject ? { idpSubject: sessionArg.idpSubject } : {}),
+      ...(sessionArg.loginAttemptId ? { loginAttemptId: sessionArg.loginAttemptId } : {}),
+    };
+  }
+
+  /** A session document that is live right now with an active principal, touched at most once a minute. */
+  private async liveSession(sessionArg: RelyingPartySessionDoc | null): Promise<RelyingPartySessionDoc | null> {
+    const now = this.#now();
+    if (!sessionArg || sessionArg.revokedAt !== undefined || sessionArg.expiresAt <= now) {
+      return null;
+    }
+    if (!(await this.#principals.isActive(sessionArg.userId))) {
+      return null;
+    }
+    if (now - sessionArg.lastSeenAt > SESSION_TOUCH_INTERVAL_MS) {
+      // the touch carries the liveness it was read under into the write: a
+      // revocation that landed in between leaves it unmatched
+      const touched = await this.#models.Session.atomicUpdate(
+        { id: sessionArg.id, revokedAt: { $exists: false }, expiresAt: { $gt: now } },
+        { $set: { lastSeenAt: now } },
+      );
+      if (touched.matchedCount === 0) {
+        return null;
+      }
+      sessionArg.lastSeenAt = now;
+    }
+    return sessionArg;
+  }
+
+  private async createProviderSession(
+    attemptArg: RelyingPartyLoginAttemptDoc,
+    principalIdArg: string,
+    completionArg: IOidcCompletion,
+  ): Promise<IRelyingPartySessionOpening> {
+    const token = randomToken(32);
+    const session = this.newSessionDoc(token, principalIdArg);
+    session.idpSubject = completionArg.subject;
+    session.loginAttemptId = attemptArg.id;
+    session.sealedAccessToken = this.#secretBox.seal(completionArg.accessToken);
+    session.sealedRefreshToken = completionArg.refreshToken ? this.#secretBox.seal(completionArg.refreshToken) : '';
+    session.accessTokenExpiresAt = completionArg.accessTokenExpiresAt;
+    session.refreshLockUntil = 0;
+    await session.save();
+
+    const linked = await this.#models.LoginAttempt.atomicUpdate(
+      { id: attemptArg.id, createdSessionId: null },
+      { $set: { createdSessionId: session.id } },
+    );
+    if (linked.matchedCount !== 1) {
+      // the attempt was consumed by another callback in the meantime
+      await this.discardUnopenedSession(session.id);
+      throw new RelyingPartyError('invalid_or_replayed_login');
+    }
+    const opening = this.opening(session, token);
+    try {
+      await this.#hooks.onProviderSessionOpened?.({ session: opening.session });
+    } catch (error) {
+      // the cookie never leaves, so the session is unreachable: it is revoked
+      // and its sealed tokens erased before the application's error goes on;
+      // the caller hands the provider tokens back
+      try {
+        await this.discardUnopenedSession(session.id);
+      } catch (discardError) {
+        this.emit({ event: 'session_discard_failed', sessionId: session.id, message: errorMessage(discardError) });
+      }
+      throw error;
+    }
+    return opening;
+  }
+
+  /** 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(
+      { id: sessionIdArg, revokedAt: { $exists: false } },
+      { $set: { revokedAt: this.#now(), ...REVOKED_TOKEN_FIELDS } },
+    );
+  }
+
+  /**
+   * Tells the application a session ended. Its hook never stands between the
+   * 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 {
+    const hook = this.#hooks.onSessionEnded;
+    if (!hook) {
+      return;
+    }
+    const reportFailure = (errorArg: unknown) => {
+      this.emit({ event: 'hook_failed', hook: 'onSessionEnded', sessionId: eventArg.sessionId, message: errorMessage(errorArg) });
+    };
+    try {
+      const result: unknown = hook.call(this.#hooks, eventArg);
+      if (result instanceof Promise) {
+        result.catch(reportFailure);
+      }
+    } catch (error) {
+      reportFailure(error);
+    }
+  }
+
+  /**
+   * The conditional revocation every end of a session runs. Answers the
+   * sealed tokens it took off the session when this call revoked it, `null`
+   * when the session was already over.
+   */
+  private async revokeSession(
+    sessionIdArg: string,
+    reasonArg: TRelyingPartySessionEndReason,
+  ): Promise<TSealedTokens | null> {
+    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) {
+      return null;
+    }
+    const before = revoked.document as RelyingPartySessionDoc;
+    return { sealedAccessToken: before.sealedAccessToken, sealedRefreshToken: before.sealedRefreshToken };
+  }
+
+  /** The provider says the login is over: the session ends here without asking it anything more. */
+  private async endProviderSession(sessionIdArg: string, reasonArg: TRelyingPartySessionEndReason): Promise<void> {
+    if (await this.revokeSession(sessionIdArg, reasonArg)) {
+      this.emit({ event: 'idp_session_ended', sessionId: sessionIdArg, reason: reasonArg });
+    }
+  }
+
+  /**
+   * Hands the tokens of an ended session back, best-effort and within the
+   * budget. A sealed value this deployment can no longer open is skipped.
+   */
+  private async revokeSealedTokens(sealedArg: TSealedTokens): Promise<void> {
+    if (!this.#provider || (!sealedArg.sealedAccessToken && !sealedArg.sealedRefreshToken)) {
+      return;
+    }
+    await this.withinRevocationBudget(async () => {
+      for (const [sealed, hint] of [
+        [sealedArg.sealedRefreshToken, 'refresh_token'],
+        [sealedArg.sealedAccessToken, 'access_token'],
+      ] as const) {
+        if (!sealed) {
+          continue;
+        }
+        const token = this.openSealed(sealed);
+        if (token === undefined) {
+          this.emit({ event: 'oidc_sealed_token_unreadable', hint, message: 'The sealed provider token could not be opened' });
+          continue;
+        }
+        await this.revokeToken(token, hint);
+      }
+    });
+  }
+
+  private async revokeRotatedTokens(rotatedArg: IOidcRefreshedTokens): Promise<void> {
+    await this.withinRevocationBudget(async () => {
+      if (rotatedArg.refreshToken) {
+        await this.revokeToken(rotatedArg.refreshToken, 'refresh_token');
+      }
+      await this.revokeToken(rotatedArg.accessToken, 'access_token');
+    });
+  }
+
+  private async revokeCompletionTokens(completionArg: IOidcCompletion): Promise<void> {
+    await this.withinRevocationBudget(async () => {
+      if (completionArg.refreshToken) {
+        await this.revokeToken(completionArg.refreshToken, 'refresh_token');
+      }
+      await this.revokeToken(completionArg.accessToken, 'access_token');
+    });
+  }
+
+  private async revokeToken(tokenArg: string, hintArg: TOidcTokenHint): Promise<void> {
+    try {
+      await this.#provider?.revokeToken(tokenArg, hintArg);
+    } catch (error) {
+      // the local session is gone either way; the provider expires the token
+      this.emit({ event: 'oidc_token_revocation_failed', hint: hintArg, message: errorMessage(error) });
+    }
+  }
+
+  /**
+   * Runs a best-effort provider step under `TOKEN_REVOCATION_BUDGET_MS`. What
+   * is still in flight at the deadline keeps running and ends on the provider
+   * client's own request timeout; only the waiting stops. The timer is cleared
+   * on every path and unreferenced.
+   */
+  private async withinRevocationBudget(workArg: () => Promise<void>): Promise<void> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const work = workArg().then(
+      () => 'done' as const,
+      (errorArg: unknown) => {
+        this.emit({ event: 'oidc_token_revocation_failed', message: errorMessage(errorArg) });
+        return 'done' as const;
+      },
+    );
+    const deadline = new Promise<'deadline'>((resolveArg) => {
+      timer = setTimeout(() => resolveArg('deadline'), TOKEN_REVOCATION_BUDGET_MS);
+      timer.unref();
+    });
+    try {
+      if ((await Promise.race([work, deadline])) === 'deadline') {
+        this.emit({
+          event: 'oidc_token_revocation_timed_out',
+          message: 'The provider did not answer within the revocation budget',
+        });
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /** A sealed value this deployment can still open, or `undefined`. */
+  private openSealed(sealedArg: string | undefined): string | undefined {
+    if (!sealedArg) {
+      return undefined;
+    }
+    try {
+      return this.#secretBox.open(sealedArg);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Removes attempts an hour past their expiry, one bounded page per login
+   * start. A sweep that cannot run never blocks a sign-in.
+   */
+  private async sweepExpiredAttempts(): Promise<void> {
+    try {
+      const page = await this.#models.LoginAttempt.getPagedInstances({
+        filter: { expiresAt: { $lt: this.#now() - LOGIN_ATTEMPT_SWEEP_GRACE_MS } },
+        sortField: 'expiresAt',
+        sortDirection: 'asc',
+        limit: LOGIN_ATTEMPT_SWEEP_BATCH,
+      });
+      for (const attempt of page.documents) {
+        await this.#models.LoginAttempt.atomicDelete({ id: attempt.id });
+      }
+    } catch (error) {
+      this.emit({ event: 'login_attempt_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
+   * `console.error` instead.
+   */
+  private emit(eventArg: IRelyingPartyEvent): void {
+    const sink = this.#hooks.onEvent;
+    if (!sink) {
+      console.error(JSON.stringify(eventArg));
+      return;
+    }
+    const reportFailure = (errorArg: unknown) => {
+      const failure: IRelyingPartyEvent = { event: 'hook_failed', hook: 'onEvent', message: errorMessage(errorArg) };
+      console.error(JSON.stringify(failure));
+      console.error(JSON.stringify(eventArg));
+    };
+    try {
+      const result: unknown = sink.call(this.#hooks, eventArg);
+      if (result instanceof Promise) {
+        result.catch(reportFailure);
+      }
+    } catch (error) {
+      reportFailure(error);
+    }
+  }
+}