@idp.global/sdk 19.3.0 → 19.4.0

package/ts_browser/classes.relyingpartybearerclient.ts

@@ -0,0 +1,821 @@
+import {
+  RELYING_PARTY_BEARER_MESSAGE_TYPE,
+  type IRelyingPartyBearerLogoutAnswer,
+  type IRelyingPartyBearerTokenAnswer,
+} from '../ts_relyingparty/contract.bearer.js';
+
+export type {
+  IRelyingPartyBearerErrorAnswer,
+  IRelyingPartyBearerLogoutAnswer,
+  IRelyingPartyBearerMessage,
+  IRelyingPartyBearerSessionAnswer,
+  IRelyingPartyBearerSessionInfo,
+  IRelyingPartyBearerTokenAnswer,
+  TRelyingPartyBearerDeliveryError,
+  TRelyingPartyBearerErrorCode,
+} from '../ts_relyingparty/contract.bearer.js';
+export { RELYING_PARTY_BEARER_MESSAGE_TYPE };
+
+/** The client kinds a browser signs in as; native clients use `loopback` and `custom_scheme` themselves. */
+export type TRelyingPartyBearerBrowserClientKind = 'web' | 'popup';
+
+/** The pair a bearer client keeps: the relying party's answer and when it arrived. */
+export interface IRelyingPartyBearerStoredTokens extends IRelyingPartyBearerTokenAnswer {
+  /** epoch milliseconds on this device's clock when the answer arrived; with `expiresIn` it dates the access token's end here */
+  receivedAt: number;
+}
+
+/**
+ * Where the application keeps the token pair — IndexedDB, say — for every
+ * tab of its origin. The client keeps no pair in memory: it reads this store
+ * on every use and again inside the refresh lock, so a pair another tab
+ * rotated is seen at once. `set` and `clear` resolve once the change is
+ * durable; the client hands out a rotated pair only after `set` resolved.
+ *
+ * Each `set` and `clear` is given the signal of its operation's deadline
+ * (`requestTimeoutMs`). An adapter either honours it, so a write the signal
+ * aborted is not made and the call rejects, or completes synchronously, as
+ * one over `localStorage` does, so it is never late. The lock is never held
+ * past the deadline, whatever a write still does: an adapter that ignores the
+ * signal can finish one after another tab took the lock. A late `set`
+ * overwrites what that tab stored or cleared, and the pair it leaves can be
+ * spent or of an ended session; its refresh then ends the session
+ * (`refresh_token_reused`) or is refused. A late `clear` removes the pair that
+ * tab stored. Either way the user signs in again.
+ */
+export interface IRelyingPartyBearerTokenStorage {
+  get(): Promise<IRelyingPartyBearerStoredTokens | null>;
+  set(tokensArg: IRelyingPartyBearerStoredTokens, optionsArg: { signal: AbortSignal }): Promise<void>;
+  clear(optionsArg: { signal: AbortSignal }): Promise<void>;
+}
+
+/**
+ * A login on its way: what `createLogin` made and the receiver needs back.
+ * A `web` login leaves the page, so the application keeps it until the
+ * return target page hands it to `completeRedirectLogin` — in
+ * `sessionStorage` or IndexedDB, never in a URL or a log: `codeVerifier` is
+ * the secret that makes the code worth anything.
+ */
+export interface IRelyingPartyBearerClientLogin {
+  clientKind: TRelyingPartyBearerBrowserClientKind;
+  returnTarget: string;
+  state: string;
+  codeVerifier: string;
+  /** the bearer login start: navigate to it (`web`) or open it (`popup`) */
+  url: string;
+}
+
+/** What the client reads of a `message` event. */
+export interface IRelyingPartyBearerMessageEvent {
+  readonly origin: string;
+  readonly source: unknown;
+  readonly data: unknown;
+}
+
+/** What the client reads of a popup it opened. */
+export interface IRelyingPartyBearerPopup {
+  readonly closed: boolean;
+}
+
+/** The parts of `window` the login receivers use; `window` itself is one. */
+export interface IRelyingPartyBearerClientWindow {
+  readonly location: { readonly href: string };
+  readonly history: {
+    readonly state: unknown;
+    replaceState(dataArg: unknown, unusedArg: string, urlArg?: string): void;
+  };
+  open(urlArg: string, targetArg?: string, featuresArg?: string): IRelyingPartyBearerPopup | null;
+  addEventListener(typeArg: 'message', listenerArg: (eventArg: IRelyingPartyBearerMessageEvent) => void): void;
+  removeEventListener(typeArg: 'message', listenerArg: (eventArg: IRelyingPartyBearerMessageEvent) => void): void;
+}
+
+export interface IRelyingPartyBearerClientOptions {
+  /** the relying party's public origin, exactly: where its bearer routes and its popup page are served */
+  origin: string;
+  /** the prefix of the relying party's login routes; `/auth/` unless it mounts them elsewhere */
+  loginPathPrefix?: string;
+  storage: IRelyingPartyBearerTokenStorage;
+  /** the Web Lock every refresh, logout and store of a claimed pair holds; one name per pair in `storage` */
+  lockName?: string;
+  /** how long before its end on this device's clock an access token is rotated; at most half its lifetime */
+  refreshSkewMs?: number;
+  /**
+   * The deadline of each operation of the client: the claim of a login's
+   * code, a refresh with the write of its pair, the store of a claimed pair
+   * with the end of the session it replaced, and a logout. 30 seconds unless
+   * given, at most two minutes, since every tab of the origin waits on the
+   * lock meanwhile. When it fires the request and the storage write are
+   * aborted, a late answer is never stored and the lock is released.
+   */
+  requestTimeoutMs?: number;
+  /** `navigator.locks` unless given */
+  locks?: LockManager;
+  /** `globalThis.fetch` unless given */
+  fetch?: typeof globalThis.fetch;
+  /** `window` unless given; only the login receivers need one */
+  window?: IRelyingPartyBearerClientWindow;
+  now?: () => number;
+}
+
+export interface IRelyingPartyBearerPopupOptions {
+  /** how long the popup may take; ten minutes, the life of a login attempt, unless given */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  /** the `features` of `window.open`; never `noopener`, the popup posts to its opener */
+  windowFeatures?: string;
+}
+
+/** What a login did to the pair stored before it. */
+export type TRelyingPartyBearerPreviousSessionOutcome =
+  /** no pair was stored */
+  | 'no_previous_session'
+  /** the stored pair was of the session this login opened; there was nothing to end */
+  | 'same_session'
+  /** the logout route ended the previous session, or answered that it was over already */
+  | 'previous_session_ended'
+  /** the previous session could not be ended and lives on at the relying party until it expires; `previousSessionError` says why */
+  | 'previous_session_not_revoked';
+
+/** A received login: the pair now stored, and what became of the session of the pair it replaced. */
+export interface IRelyingPartyBearerLoginResult {
+  tokens: IRelyingPartyBearerStoredTokens;
+  previousSession: TRelyingPartyBearerPreviousSessionOutcome;
+  /** with `previous_session_not_revoked`: why the logout route did not end it */
+  previousSessionError?: RelyingPartyBearerClientError;
+}
+
+export type TRelyingPartyBearerClientErrorCode =
+  /** the delivery's state is not the one of the login it came back to; nothing was claimed */
+  | 'state_mismatch'
+  /** the delivery carries no code; `deliveryError` says why */
+  | 'login_failed'
+  /** this login was received once already; a code is claimed once, never again */
+  | 'already_received'
+  /** the browser opened no popup */
+  | 'popup_blocked'
+  /** the popup was closed before it delivered */
+  | 'popup_closed'
+  /** the popup delivered nothing in time */
+  | 'popup_timeout'
+  /** the request got no answer (network, CORS, a redirect) or none before `requestTimeoutMs`; a claim or refresh may have been spent anyway */
+  | 'request_failed'
+  /** the relying party refused the request; `status` and `answerError` say how */
+  | 'request_refused'
+  /** an answer outside the bearer contract */
+  | 'unexpected_answer'
+  /** `logout()` cleared the pair, so this device is signed out, but the relying party did not confirm the session's end; `cause` says why */
+  | 'session_not_revoked';
+
+export class RelyingPartyBearerClientError extends Error {
+  public readonly status?: number;
+  /** the `error` the relying party answered (`TRelyingPartyBearerErrorCode`) */
+  public readonly answerError?: string;
+  /** the `error` a delivery carried (`TRelyingPartyBearerDeliveryError`) */
+  public readonly deliveryError?: string;
+
+  constructor(
+    public readonly code: TRelyingPartyBearerClientErrorCode,
+    detailsArg: { status?: number; answerError?: string; deliveryError?: string; cause?: unknown } = {},
+  ) {
+    super(code, detailsArg.cause !== undefined ? { cause: detailsArg.cause } : undefined);
+    this.name = 'RelyingPartyBearerClientError';
+    if (detailsArg.status !== undefined) this.status = detailsArg.status;
+    if (detailsArg.answerError !== undefined) this.answerError = detailsArg.answerError;
+    if (detailsArg.deliveryError !== undefined) this.deliveryError = detailsArg.deliveryError;
+  }
+}
+
+const DEFAULT_LOGIN_PATH_PREFIX = '/auth/';
+const DEFAULT_REFRESH_SKEW_MS = 60_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+/** Every tab of the origin waits on the lock while a section runs: two minutes at most. */
+const MAX_REQUEST_TIMEOUT_MS = 120_000;
+/** The life of a login attempt at the relying party (`LOGIN_ATTEMPT_MAX_AGE_SECONDS`). */
+const DEFAULT_POPUP_TIMEOUT_MS = 10 * 60 * 1_000;
+const DEFAULT_POPUP_FEATURES = 'popup,width=480,height=720';
+const POPUP_CLOSED_POLL_MS = 500;
+/** A popup posts and closes at once; its message can arrive after the opener sees it closed. */
+const POPUP_CLOSED_GRACE_MS = 1_000;
+/** 32 random bytes: a 43-character verifier and state (RFC 7636 §4.1). */
+const RANDOM_BYTES = 32;
+const DELIVERY_PARAMS = ['code', 'error', 'state'] as const;
+
+const base64Url = (bytesArg: Uint8Array): string => {
+  let binary = '';
+  for (const byte of bytesArg) binary += String.fromCharCode(byte);
+  return globalThis.btoa(binary).replace(/\+/gu, '-').replace(/\//gu, '_').replace(/=+$/u, '');
+};
+
+const randomBase64Url = (): string => base64Url(globalThis.crypto.getRandomValues(new Uint8Array(RANDOM_BYTES)));
+
+/** The S256 challenge of a verifier: BASE64URL(SHA-256(ASCII(verifier))). */
+const pkceChallengeOf = async (verifierArg: string): Promise<string> =>
+  base64Url(new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifierArg))));
+
+const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+const isText = (valueArg: unknown): valueArg is string => typeof valueArg === 'string' && valueArg.length > 0;
+
+const isTime = (valueArg: unknown): valueArg is number => typeof valueArg === 'number' && Number.isFinite(valueArg);
+
+/** Throws `request_failed` once a section's deadline has fired: nothing is sent or written past it. */
+const inTime = (signalArg: AbortSignal): void => {
+  if (signalArg.aborted) {
+    throw new RelyingPartyBearerClientError('request_failed');
+  }
+};
+
+/** The one value of a parameter, or `undefined` when it is absent or repeated. */
+const singleParam = (paramsArg: URLSearchParams, nameArg: string): string | undefined => {
+  const values = paramsArg.getAll(nameArg);
+  return values.length === 1 ? values[0] : undefined;
+};
+
+/** A token answer exactly as the bearer contract says, or `null`. */
+const tokenAnswerOf = (answerArg: unknown): IRelyingPartyBearerTokenAnswer | null => {
+  if (
+    !isRecord(answerArg)
+    || answerArg.tokenType !== 'Bearer'
+    || !isText(answerArg.accessToken)
+    || !isText(answerArg.refreshToken)
+    || !isTime(answerArg.accessTokenExpiresAt)
+    || !isTime(answerArg.expiresIn)
+    || answerArg.expiresIn <= 0
+    || !isTime(answerArg.refreshTokenExpiresAt)
+    || !isRecord(answerArg.session)
+    || !isText(answerArg.session.sessionId)
+    || !isText(answerArg.session.principalId)
+    || !isTime(answerArg.session.expiresAt)
+  ) {
+    return null;
+  }
+  return {
+    tokenType: 'Bearer',
+    accessToken: answerArg.accessToken,
+    accessTokenExpiresAt: answerArg.accessTokenExpiresAt,
+    expiresIn: answerArg.expiresIn,
+    refreshToken: answerArg.refreshToken,
+    refreshTokenExpiresAt: answerArg.refreshTokenExpiresAt,
+    session: {
+      sessionId: answerArg.session.sessionId,
+      principalId: answerArg.session.principalId,
+      expiresAt: answerArg.session.expiresAt,
+    },
+  };
+};
+
+/**
+ * The browser side of bearer hand-off (`@idp.global/sdk/relyingparty`
+ * `bearer`): it starts a `web` or `popup` login with PKCE and a state,
+ * receives the delivery, claims the code once and keeps the token pair in
+ * the application's storage. Every refresh, logout and store of a claimed
+ * pair holds one Web Lock, so the tabs of an origin rotate the pair one at a
+ * time: inside the lock the pair is read from storage again, a pair another
+ * tab rotated is used as it is, and a rotated pair is stored before the lock
+ * is released and before its access token is handed out. Each claim and
+ * each section that holds the lock ends by `requestTimeoutMs`, so a hanging
+ * request or write never holds the other tabs. A login replaces the stored
+ * pair and ends that pair's session. Rotation is strict at the relying
+ * party: a refresh token spent once ends the session when it comes back, so
+ * nothing here retries a claim or a refresh.
+ *
+ * It needs the Web Locks API and Web Crypto, both of them only in a secure
+ * context, and has no fallback for either.
+ */
+export class RelyingPartyBearerClient {
+  public readonly origin: string;
+  readonly #paths: { claim: string; refresh: string; logout: string; login: string };
+  readonly #storage: IRelyingPartyBearerTokenStorage;
+  readonly #lockName: string;
+  readonly #refreshSkewMs: number;
+  readonly #requestTimeoutMs: number;
+  readonly #locks: LockManager;
+  readonly #fetch: typeof globalThis.fetch;
+  readonly #window: IRelyingPartyBearerClientWindow | undefined;
+  readonly #now: () => number;
+  /** the states of the logins received here; a login is received once */
+  readonly #receivedStates = new Set<string>();
+
+  constructor(optionsArg: IRelyingPartyBearerClientOptions) {
+    const origin = optionsArg?.origin;
+    let parsedOrigin: URL | null = null;
+    try {
+      parsedOrigin = typeof origin === 'string' ? new URL(origin) : null;
+    } catch {
+      parsedOrigin = null;
+    }
+    if (!parsedOrigin || parsedOrigin.origin !== origin || !['https:', 'http:'].includes(parsedOrigin.protocol)) {
+      throw new Error('origin must be the relying party\'s exact origin, such as https://app.example');
+    }
+    const prefix = optionsArg.loginPathPrefix ?? DEFAULT_LOGIN_PATH_PREFIX;
+    if (typeof prefix !== 'string' || !/^\/(?:[A-Za-z0-9._~-]+\/)*$/u.test(prefix)) {
+      throw new Error('loginPathPrefix must be a path that starts and ends with /');
+    }
+    const storage = optionsArg.storage;
+    if (!storage || typeof storage.get !== 'function' || typeof storage.set !== 'function' || typeof storage.clear !== 'function') {
+      throw new Error('storage must have get, set and clear');
+    }
+    const locks = optionsArg.locks ?? globalThis.navigator?.locks;
+    if (!locks || typeof locks.request !== 'function') {
+      throw new Error('RelyingPartyBearerClient needs the Web Locks API (navigator.locks)');
+    }
+    if (typeof globalThis.crypto?.subtle?.digest !== 'function' || typeof globalThis.crypto.getRandomValues !== 'function') {
+      throw new Error('RelyingPartyBearerClient needs Web Crypto (crypto.subtle), which a browser offers only in a secure context');
+    }
+    const fetchFunction = optionsArg.fetch ?? globalThis.fetch?.bind(globalThis);
+    if (typeof fetchFunction !== 'function') {
+      throw new Error('RelyingPartyBearerClient needs fetch');
+    }
+    const refreshSkewMs = optionsArg.refreshSkewMs ?? DEFAULT_REFRESH_SKEW_MS;
+    if (!Number.isInteger(refreshSkewMs) || refreshSkewMs < 0) {
+      throw new Error('refreshSkewMs must be a whole number of milliseconds');
+    }
+    // only an absent deadline takes the default: any other value that is not one throws
+    const requestTimeoutMs = optionsArg.requestTimeoutMs === undefined ? DEFAULT_REQUEST_TIMEOUT_MS : optionsArg.requestTimeoutMs;
+    if (
+      typeof requestTimeoutMs !== 'number'
+      || !Number.isFinite(requestTimeoutMs)
+      || requestTimeoutMs <= 0
+      || requestTimeoutMs > MAX_REQUEST_TIMEOUT_MS
+    ) {
+      throw new Error(`requestTimeoutMs must be more than 0 and at most ${MAX_REQUEST_TIMEOUT_MS} milliseconds`);
+    }
+    this.origin = origin;
+    this.#paths = {
+      login: `${origin}${prefix}bearer/login`,
+      claim: `${origin}${prefix}bearer/claim`,
+      refresh: `${origin}${prefix}bearer/refresh`,
+      logout: `${origin}${prefix}bearer/logout`,
+    };
+    this.#storage = storage;
+    this.#lockName = optionsArg.lockName ?? `idp.global/relyingparty:bearer-tokens ${origin}`;
+    this.#refreshSkewMs = refreshSkewMs;
+    this.#requestTimeoutMs = requestTimeoutMs;
+    this.#locks = locks;
+    this.#fetch = fetchFunction;
+    this.#window = optionsArg.window ?? (globalThis as { window?: IRelyingPartyBearerClientWindow }).window;
+    this.#now = optionsArg.now ?? Date.now;
+  }
+
+  /**
+   * A new login: a fresh verifier, its S256 challenge and a state, each from
+   * 32 random bytes, and the URL that starts it. Make a popup login before
+   * the click that opens it: this is async, and a browser opens a popup only
+   * within the user's gesture.
+   */
+  public async createLogin(optionsArg: {
+    clientKind: TRelyingPartyBearerBrowserClientKind;
+    returnTarget: string;
+  }): Promise<IRelyingPartyBearerClientLogin> {
+    const { clientKind, returnTarget } = optionsArg ?? ({} as typeof optionsArg);
+    if (clientKind !== 'web' && clientKind !== 'popup') {
+      throw new Error('a browser signs in as a web or popup client');
+    }
+    if (!isText(returnTarget)) {
+      throw new Error('returnTarget must name the configured return target');
+    }
+    const codeVerifier = randomBase64Url();
+    const state = randomBase64Url();
+    const url = new URL(this.#paths.login);
+    url.searchParams.set('client_kind', clientKind);
+    url.searchParams.set('return_target', returnTarget);
+    url.searchParams.set('code_challenge', await pkceChallengeOf(codeVerifier));
+    url.searchParams.set('code_challenge_method', 'S256');
+    url.searchParams.set('state', state);
+    return { clientKind, returnTarget, state, codeVerifier, url: url.href };
+  }
+
+  /**
+   * Receives a `web` login on its return target page. The delivery leaves
+   * the address first, before anything is checked, so neither a reload nor
+   * the history holds the code. A delivery whose state is not the login's is
+   * refused unclaimed; a code is claimed once, and a failed claim is not
+   * retried. The claimed pair replaces the stored one, whose session is
+   * ended then (`IRelyingPartyBearerLoginResult`). Answers `null` on a page
+   * that holds no delivery.
+   */
+  public async completeRedirectLogin(
+    loginArg: IRelyingPartyBearerClientLogin | null | undefined,
+  ): Promise<IRelyingPartyBearerLoginResult | null> {
+    const window = this.requireWindow();
+    const url = new URL(window.location.href);
+    if (!DELIVERY_PARAMS.some((nameArg) => url.searchParams.has(nameArg))) {
+      return null;
+    }
+    const delivered = url.searchParams;
+    const code = singleParam(delivered, 'code');
+    const error = singleParam(delivered, 'error');
+    const state = singleParam(delivered, 'state');
+    const kept = new URL(url.href);
+    for (const name of DELIVERY_PARAMS) {
+      kept.searchParams.delete(name);
+    }
+    window.history.replaceState(window.history.state, '', kept.pathname + kept.search + kept.hash);
+    if (!loginArg || loginArg.clientKind !== 'web' || state === undefined || state !== loginArg.state) {
+      throw new RelyingPartyBearerClientError('state_mismatch');
+    }
+    return this.receive(loginArg, code, error);
+  }
+
+  /**
+   * Opens a `popup` login and receives what its page posts: a message is
+   * taken only from the relying party's origin, from this very popup, of the
+   * bearer message type and with the login's state; any other is ignored.
+   * The popup opens before this returns, so call it in the click handler
+   * itself, with a login made beforehand. The claimed pair replaces the
+   * stored one like `completeRedirectLogin`'s.
+   */
+  public openPopupLogin(
+    loginArg: IRelyingPartyBearerClientLogin,
+    optionsArg: IRelyingPartyBearerPopupOptions = {},
+  ): Promise<IRelyingPartyBearerLoginResult> {
+    let window: IRelyingPartyBearerClientWindow;
+    try {
+      window = this.requireWindow();
+      if (!loginArg || loginArg.clientKind !== 'popup') {
+        throw new Error('openPopupLogin needs a popup login');
+      }
+      if (this.#receivedStates.has(loginArg.state)) {
+        throw new RelyingPartyBearerClientError('already_received');
+      }
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    let popup: IRelyingPartyBearerPopup | null;
+    try {
+      popup = window.open(loginArg.url, '_blank', optionsArg.windowFeatures ?? DEFAULT_POPUP_FEATURES);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    if (!popup) {
+      return Promise.reject(new RelyingPartyBearerClientError('popup_blocked'));
+    }
+    return this.receivePopup(window, popup, loginArg, optionsArg);
+  }
+
+  /**
+   * An access token to send right now, or `null` when there is no session.
+   * One that is about to end is rotated first, by one tab for all of them.
+   */
+  public async accessToken(): Promise<string | null> {
+    const stored = await this.#storage.get();
+    if (!stored) {
+      return null;
+    }
+    if (this.isFresh(stored)) {
+      return stored.accessToken;
+    }
+    return (await this.rotate(stored.refreshToken, null))?.accessToken ?? null;
+  }
+
+  /**
+   * Rotates the pair now — after the relying party refused
+   * `rejectedAccessTokenArg`, say — unless another tab already did, and
+   * answers the pair to use: `null` once the session is over, which clears
+   * the storage. A relying party that cannot refresh right now
+   * (`authority_unavailable`) keeps the pair as it is; try again later.
+   */
+  public async refresh(rejectedAccessTokenArg?: string): Promise<IRelyingPartyBearerStoredTokens | null> {
+    const stored = await this.#storage.get();
+    if (!stored) {
+      return null;
+    }
+    return this.rotate(stored.refreshToken, rejectedAccessTokenArg ?? null);
+  }
+
+  /**
+   * Clears the storage and then ends the session at the relying party with
+   * the pair it held, and answers whether that ended a live session. When the
+   * relying party cannot be reached, refuses or gives no answer by
+   * `requestTimeoutMs`, the call throws `session_not_revoked` with that
+   * failure as its `cause`: this device is signed out, and the session may
+   * live on at the relying party until it expires, so tell the user they are
+   * signed out on this device only. A deadline that fires before the storage
+   * is cleared throws `request_failed`, and the pair stays.
+   */
+  public async logout(): Promise<boolean> {
+    let cleared = false;
+    const notRevoked = (errorArg: unknown) => new RelyingPartyBearerClientError('session_not_revoked', { cause: errorArg });
+    return this.#locks.request(this.#lockName, () => this.withDeadline(async (signalArg) => {
+      const current = await this.#storage.get();
+      if (!current) {
+        return false;
+      }
+      inTime(signalArg);
+      await this.#storage.clear({ signal: signalArg });
+      cleared = true;
+      try {
+        return await this.endSessionOf(current, signalArg);
+      } catch (error) {
+        throw notRevoked(error);
+      }
+    }, () => {
+      // once the pair is cleared this device is signed out, whatever the request still does
+      const failure = new RelyingPartyBearerClientError('request_failed');
+      throw cleared ? notRevoked(failure) : failure;
+    }));
+  }
+
+  private requireWindow(): IRelyingPartyBearerClientWindow {
+    if (!this.#window) {
+      throw new Error('the login receivers of RelyingPartyBearerClient need a window');
+    }
+    return this.#window;
+  }
+
+  private isFresh(storedArg: IRelyingPartyBearerStoredTokens): boolean {
+    const lifetimeMs = storedArg.expiresIn * 1_000;
+    const skewMs = Math.min(this.#refreshSkewMs, lifetimeMs / 2);
+    return this.#now() < storedArg.receivedAt + lifetimeMs - skewMs;
+  }
+
+  /** Takes a delivery for its login, once, claims its code and stores the pair in place of the one before. */
+  private async receive(
+    loginArg: IRelyingPartyBearerClientLogin,
+    codeArg: unknown,
+    errorArg: unknown,
+  ): Promise<IRelyingPartyBearerLoginResult> {
+    if (this.#receivedStates.has(loginArg.state)) {
+      throw new RelyingPartyBearerClientError('already_received');
+    }
+    this.#receivedStates.add(loginArg.state);
+    if (errorArg !== undefined) {
+      throw new RelyingPartyBearerClientError(isText(errorArg) && codeArg === undefined ? 'login_failed' : 'unexpected_answer', {
+        ...(isText(errorArg) ? { deliveryError: errorArg } : {}),
+      });
+    }
+    if (!isText(codeArg)) {
+      throw new RelyingPartyBearerClientError('unexpected_answer');
+    }
+    // the claim touches no stored pair, so it holds no lock, only its own deadline; a failed one leaves the stored pair as it was
+    const answer = tokenAnswerOf(await this.withDeadline((signalArg) =>
+      this.post(this.#paths.claim, { code: codeArg, codeVerifier: loginArg.codeVerifier }, {}, signalArg)));
+    if (!answer) {
+      throw new RelyingPartyBearerClientError('unexpected_answer', { status: 200 });
+    }
+    return this.replacePair({ ...answer, receivedAt: this.#now() });
+  }
+
+  /**
+   * Stores a claimed pair in place of the stored one and then ends the
+   * session of that one with its tokens, held here, through the logout
+   * route. Both run under the lock a refresh holds, so no tab rotates the
+   * replaced pair meanwhile. A session that cannot be ended is the result's
+   * `previous_session_not_revoked`, neither thrown nor dropped: the new pair
+   * is stored by then.
+   */
+  private replacePair(tokensArg: IRelyingPartyBearerStoredTokens): Promise<IRelyingPartyBearerLoginResult> {
+    /** what the login answers if the deadline fires now: nothing before the pair is stored */
+    let atDeadline: IRelyingPartyBearerLoginResult | null = null;
+    const notRevoked = (errorArg: unknown): IRelyingPartyBearerLoginResult => ({
+      tokens: tokensArg,
+      previousSession: 'previous_session_not_revoked',
+      previousSessionError: errorArg instanceof RelyingPartyBearerClientError
+        ? errorArg
+        : new RelyingPartyBearerClientError('unexpected_answer', { cause: errorArg }),
+    });
+    return this.#locks.request(this.#lockName, () => this.withDeadline<IRelyingPartyBearerLoginResult>(async (signalArg) => {
+      const previous = await this.#storage.get();
+      inTime(signalArg);
+      await this.#storage.set(tokensArg, { signal: signalArg });
+      if (!previous) {
+        return { tokens: tokensArg, previousSession: 'no_previous_session' };
+      }
+      if (previous.session.sessionId === tokensArg.session.sessionId) {
+        return { tokens: tokensArg, previousSession: 'same_session' };
+      }
+      atDeadline = notRevoked(new RelyingPartyBearerClientError('request_failed'));
+      try {
+        await this.endSessionOf(previous, signalArg);
+        return { tokens: tokensArg, previousSession: 'previous_session_ended' };
+      } catch (error) {
+        return notRevoked(error);
+      }
+    }, () => {
+      // past its write the login stands; only the end of the previous session is cut short
+      if (!atDeadline) {
+        throw new RelyingPartyBearerClientError('request_failed');
+      }
+      return atDeadline;
+    }));
+  }
+
+  private receivePopup(
+    windowArg: IRelyingPartyBearerClientWindow,
+    popupArg: IRelyingPartyBearerPopup,
+    loginArg: IRelyingPartyBearerClientLogin,
+    optionsArg: IRelyingPartyBearerPopupOptions,
+  ): Promise<IRelyingPartyBearerLoginResult> {
+    return new Promise<IRelyingPartyBearerLoginResult>((resolve, reject) => {
+      const cleanups: Array<() => void> = [];
+      let settled = false;
+      const settle = (actionArg: () => void) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        for (const cleanup of cleanups) {
+          cleanup();
+        }
+        actionArg();
+      };
+      const fail = (errorArg: unknown) => settle(() => reject(errorArg));
+
+      const onMessage = (eventArg: IRelyingPartyBearerMessageEvent) => {
+        const data: unknown = eventArg?.data;
+        if (
+          eventArg?.origin !== this.origin
+          || eventArg.source !== popupArg
+          || !isRecord(data)
+          || data.type !== RELYING_PARTY_BEARER_MESSAGE_TYPE
+          || data.state !== loginArg.state
+        ) {
+          return;
+        }
+        settle(() => {
+          this.receive(loginArg, data.code, data.error).then(resolve, reject);
+        });
+      };
+      windowArg.addEventListener('message', onMessage);
+      cleanups.push(() => windowArg.removeEventListener('message', onMessage));
+
+      const timeout = setTimeout(
+        () => fail(new RelyingPartyBearerClientError('popup_timeout')),
+        optionsArg.timeoutMs ?? DEFAULT_POPUP_TIMEOUT_MS,
+      );
+      cleanups.push(() => clearTimeout(timeout));
+      let closedGrace: ReturnType<typeof setTimeout> | undefined;
+      const closedPoll = setInterval(() => {
+        if (popupArg.closed && closedGrace === undefined) {
+          closedGrace = setTimeout(() => fail(new RelyingPartyBearerClientError('popup_closed')), POPUP_CLOSED_GRACE_MS);
+        }
+      }, POPUP_CLOSED_POLL_MS);
+      cleanups.push(() => {
+        clearInterval(closedPoll);
+        if (closedGrace !== undefined) {
+          clearTimeout(closedGrace);
+        }
+      });
+
+      const signal = optionsArg.signal;
+      if (signal) {
+        if (signal.aborted) {
+          fail(signal.reason);
+          return;
+        }
+        const onAbort = () => fail(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        cleanups.push(() => signal.removeEventListener('abort', onAbort));
+      }
+    });
+  }
+
+  /**
+   * One rotation under the lock. The pair is read again inside it: one
+   * whose refresh token is no longer `seenRefreshTokenArg`, or whose access
+   * token is no longer `rejectedAccessTokenArg`, was rotated already and is
+   * used as it is. A rotated pair is stored before the lock is released. The
+   * whole section has one deadline: past it, the lock is released with
+   * `request_failed` and an answer that still arrives is dropped unstored.
+   */
+  private rotate(
+    seenRefreshTokenArg: string,
+    rejectedAccessTokenArg: string | null,
+  ): Promise<IRelyingPartyBearerStoredTokens | null> {
+    return this.#locks.request(this.#lockName, () => this.withDeadline(async (signalArg) => {
+      const current = await this.#storage.get();
+      if (!current) {
+        return null;
+      }
+      if (
+        current.refreshToken !== seenRefreshTokenArg
+        || (rejectedAccessTokenArg !== null && current.accessToken !== rejectedAccessTokenArg)
+      ) {
+        return current;
+      }
+      let answer: IRelyingPartyBearerTokenAnswer | null;
+      try {
+        answer = tokenAnswerOf(await this.post(this.#paths.refresh, { refreshToken: current.refreshToken }, {}, signalArg));
+      } catch (error) {
+        if (error instanceof RelyingPartyBearerClientError && error.answerError === 'invalid_bearer_grant') {
+          // the session is over: this pair opens nothing any more
+          inTime(signalArg);
+          await this.#storage.clear({ signal: signalArg });
+          return null;
+        }
+        throw error;
+      }
+      if (!answer) {
+        throw new RelyingPartyBearerClientError('unexpected_answer', { status: 200 });
+      }
+      const stored: IRelyingPartyBearerStoredTokens = { ...answer, receivedAt: this.#now() };
+      inTime(signalArg);
+      await this.#storage.set(stored, { signal: signalArg });
+      return stored;
+    }));
+  }
+
+  /** Ends the session of a pair through the logout route and answers whether that ended a live one. */
+  private async endSessionOf(pairArg: IRelyingPartyBearerStoredTokens, signalArg: AbortSignal): Promise<boolean> {
+    const answer = await this.post(
+      this.#paths.logout,
+      { refreshToken: pairArg.refreshToken },
+      { authorization: `Bearer ${pairArg.accessToken}` },
+      signalArg,
+    );
+    if (!isRecord(answer) || typeof answer.endedLiveSession !== 'boolean') {
+      throw new RelyingPartyBearerClientError('unexpected_answer', { status: 200 });
+    }
+    return (answer as unknown as IRelyingPartyBearerLogoutAnswer).endedLiveSession;
+  }
+
+  /**
+   * Runs one operation, a claim or a section that holds the lock, under
+   * `requestTimeoutMs`. When the deadline fires, the section's signal aborts
+   * its request and its storage write and keeps it from writing anything
+   * more (`inTime`), and the call answers `onDeadlineArg()` at once, so the
+   * lock is released whatever the request or the storage still does.
+   */
+  private async withDeadline<T>(
+    sectionArg: (signalArg: AbortSignal) => Promise<T>,
+    onDeadlineArg: () => T = () => {
+      throw new RelyingPartyBearerClientError('request_failed');
+    },
+  ): Promise<T> {
+    const controller = new AbortController();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const deadline = new Promise<T>((resolve, reject) => {
+      timer = setTimeout(() => {
+        controller.abort(new RelyingPartyBearerClientError('request_failed'));
+        try {
+          resolve(onDeadlineArg());
+        } catch (error) {
+          reject(error);
+        }
+      }, this.#requestTimeoutMs);
+    });
+    const section = sectionArg(controller.signal);
+    // past the deadline the section's own end, its aborted request among them, has nobody left to answer
+    section.catch(() => undefined);
+    try {
+      return await Promise.race([section, deadline]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * A bearer API call: JSON in, JSON out, no cookie, no cache, no redirect.
+   * With `signalArg` none is sent past the deadline and an answer that
+   * arrives after it counts as none.
+   */
+  private async post(
+    urlArg: string,
+    bodyArg: Record<string, string>,
+    headersArg: Record<string, string> = {},
+    signalArg?: AbortSignal,
+  ): Promise<unknown> {
+    if (signalArg) {
+      inTime(signalArg);
+    }
+    let response: Response;
+    try {
+      response = await this.#fetch(urlArg, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...headersArg },
+        body: JSON.stringify(bodyArg),
+        credentials: 'omit',
+        cache: 'no-store',
+        redirect: 'error',
+        referrerPolicy: 'no-referrer',
+        ...(signalArg ? { signal: signalArg } : {}),
+      });
+    } catch (error) {
+      throw new RelyingPartyBearerClientError('request_failed', { cause: error });
+    }
+    let answer: unknown;
+    try {
+      answer = await response.json();
+    } catch {
+      // the parse error is not kept: its message quotes the body
+      answer = undefined;
+      if (signalArg) {
+        inTime(signalArg);
+      }
+      if (response.status === 200) {
+        throw new RelyingPartyBearerClientError('unexpected_answer', { status: 200 });
+      }
+    }
+    if (signalArg) {
+      inTime(signalArg);
+    }
+    if (response.status !== 200) {
+      throw new RelyingPartyBearerClientError('request_refused', {
+        status: response.status,
+        ...(isRecord(answer) && isText(answer.error) ? { answerError: answer.error } : {}),
+      });
+    }
+    return answer;
+  }
+}