@rxferrix/client 0.2.0 → 0.3.0

package/src/auth.ts

@@ -5,10 +5,14 @@
  * ```ts
  * const client = new RxFerrixClient("http://localhost:8090");
  * const auth = getAuth(client);                      // restores a stored session, if any
- * await auth.signIn({ email, password });
+ * const r = await auth.signIn({ email, password });
+ * if (r.mfaRequired) await auth.verifyMfa(r.mfaToken, codeFromAuthenticatorApp);
  * auth.subscribe(() => console.log(auth.state()));   // { isLoading, isAuthenticated, userId, isAdmin }
  * ```
  *
+ * Two-factor authentication (an authenticator app, with recovery codes) is per account: `setupTotp()` +
+ * `confirmTotp(code)` turn it on, `getMfaStatus()`, `disableMfa(code)` and `regenerateRecoveryCodes(code)` manage it.
+ *
  * Tokens are kept in `localStorage` (or the `storage` you pass; an in-memory store when neither exists, e.g. SSR).
  * The access token is short-lived (15 minutes by default) and refreshed with the refresh token shortly before it
  * expires and whenever the server rejects it. Refresh tokens rotate on every use; refreshes are serialized across
@@ -76,9 +80,39 @@ export interface AuthTokens {
 /** Proof of email ownership: the token from an email link, or the email address plus the code from the email. */
 export type CodeProof = { token: string } | { email: string; code: string };
 
+/**
+ * How a sign-in ended. With two-factor authentication enabled on the account, the first step (password, magic link,
+ * OAuth, password reset) returns `mfaRequired` with a short-lived `mfaToken` instead of signing in; finish with
+ * {@link RxFerrixAuth.verifyMfa}`(mfaToken, code)`, where `code` is from the authenticator app or a recovery code.
+ */
+export type SignInResult = { mfaRequired: false } | { mfaRequired: true; mfaToken: string; methods: string[] };
+
+/** The account's two-factor authentication (`GET /api/auth/mfa`). */
+export interface MfaStatus {
+  /** Sign-ins need a code. */
+  enabled: boolean;
+  /** A setup was started but not confirmed with a first code yet. */
+  pending: boolean;
+  recoveryCodesLeft: number;
+  /** The enabled factors (`"totp"`). */
+  methods: string[];
+}
+
+/** A started authenticator (TOTP) setup: show the QR code (or the secret) and ask for the first code. */
+export interface MfaSetup {
+  /** The secret in base32, for entering by hand. */
+  secret: string;
+  /** The `otpauth://totp/...` URI the QR code encodes. */
+  uri: string;
+  /** The QR code as an `<svg>` element (inline it; it scales to its container). */
+  qrSvg: string;
+}
+
 /** What {@link RxFerrixAuth.handleRedirectCallback} found in the URL. */
 export type RedirectResult =
   | { type: "signedIn" }
+  /** The account has two-factor authentication: ask for a code, then `verifyMfa(mfaToken, code)`. */
+  | { type: "mfaRequired"; mfaToken: string }
   | { type: "emailVerified" }
   /** A password reset link: ask for a new password, then call `resetPassword({ token }, password)`. */
   | { type: "passwordReset"; token: string }
@@ -119,6 +153,13 @@ export const systemApi = {
   },
 } as const;
 
+/** The server's answer to a sign-in that needs a second factor. */
+interface MfaRequiredResponse {
+  mfaRequired: true;
+  mfaToken: string;
+  methods?: string[];
+}
+
 interface StoredTokens {
   accessToken: string;
   refreshToken: string;
@@ -465,14 +506,92 @@ export class RxFerrixAuth {
     return { verificationRequired: true };
   }
 
-  /** Sign in with email and password. Rejects with code `"invalid_credentials"` on a wrong email or password. */
-  async signIn(args: { email: string; password: string }): Promise<void> {
-    await this.signedIn(await this.post<AuthTokens>("signin", args));
+  /** Tokens: signed in. A second-factor token: the caller finishes with {@link verifyMfa}. */
+  private async signedInOrMfa(res: AuthTokens | MfaRequiredResponse): Promise<SignInResult> {
+    if ("mfaRequired" in res && res.mfaRequired) {
+      return { mfaRequired: true, mfaToken: res.mfaToken, methods: res.methods ?? ["totp"] };
+    }
+    await this.signedIn(res as AuthTokens);
+    return { mfaRequired: false };
+  }
+
+  /**
+   * Sign in with email and password. Rejects with code `"invalid_credentials"` on a wrong email or password. With
+   * two-factor authentication on the account, resolves `{ mfaRequired: true, mfaToken }` without signing in: finish
+   * with {@link verifyMfa}.
+   */
+  async signIn(args: { email: string; password: string }): Promise<SignInResult> {
+    return this.signedInOrMfa(await this.post("signin", args));
+  }
+
+  /**
+   * Sign in to an admin account (dashboard). Functions then see `ctx.auth.is_admin()`. Resolves `mfaRequired` like
+   * {@link signIn} when the administrator has two-factor authentication.
+   */
+  async signInAsAdmin(args: { email: string; password: string }): Promise<SignInResult> {
+    return this.signedInOrMfa(await this.post("admin/signin", args));
+  }
+
+  /**
+   * The second step of a sign-in: the `mfaToken` of a `mfaRequired` result plus a code from the authenticator app
+   * (or a recovery code) sign in. Rejects with `invalid_mfa_code` (wrong or already used), `mfa_locked` (too many
+   * wrong codes; wait) or `invalid_mfa_token` (the sign-in expired after 5 minutes: start again).
+   */
+  async verifyMfa(mfaToken: string, code: string): Promise<void> {
+    await this.signedIn(await this.post<AuthTokens>("mfa/verify", { mfaToken, code }));
+  }
+
+  // ---------------------------------------------------------------------------------------------------------------
+  // Two-factor authentication of the signed-in account
+
+  private async bearer(): Promise<string> {
+    const token = await this.getAccessToken();
+    if (!token) throw new RxFerrixError("Sign in first", { code: "unauthenticated" });
+    return token;
+  }
+
+  /** Whether the signed-in account has two-factor authentication, and how many recovery codes are left. */
+  async getMfaStatus(): Promise<MfaStatus> {
+    const token = await this.bearer();
+    let res: Response;
+    try {
+      res = await this.fetchImpl(`${this.baseUrl}/api/auth/mfa`, { headers: { Authorization: `Bearer ${token}` } });
+    } catch (e) {
+      throw new RxFerrixError("Could not reach the server", { code: "network_error", cause: e });
+    }
+    const json = (await res.json().catch(() => null)) as unknown;
+    if (!res.ok) throw errorFrom(res.status, json);
+    return json as MfaStatus;
+  }
+
+  /**
+   * Start setting up an authenticator app (TOTP) for the signed-in account: returns the QR code and secret to
+   * enroll with; nothing changes until {@link confirmTotp} gets the app's first code. Accounts with a password
+   * must give it (`password_required`, `invalid_current_password`); `mfa_already_enabled` when it is on already.
+   */
+  async setupTotp(args: { password?: string } = {}): Promise<MfaSetup> {
+    return this.post<MfaSetup>("mfa/totp/setup", args, await this.bearer());
+  }
+
+  /**
+   * Confirm the setup with the authenticator's first code. From then on, sign-ins need a code. Resolves the recovery
+   * codes: show them once and tell the user to keep them; each works once in place of a code. `invalid_mfa_code`.
+   */
+  async confirmTotp(code: string): Promise<{ recoveryCodes: string[] }> {
+    return this.post("mfa/totp/confirm", { code }, await this.bearer());
+  }
+
+  /**
+   * Turn two-factor authentication off for the signed-in account. Needs a current code (or a recovery code) once the
+   * factor is confirmed; a pending setup is dropped without one. `invalid_mfa_code`, `mfa_not_enabled`.
+   */
+  async disableMfa(code?: string): Promise<void> {
+    await this.post("mfa/disable", code ? { code } : {}, await this.bearer());
   }
 
-  /** Sign in to an admin account (dashboard). Functions then see `ctx.auth.is_admin()`. */
-  async signInAsAdmin(args: { email: string; password: string }): Promise<void> {
-    await this.signedIn(await this.post<AuthTokens>("admin/signin", args));
+  /** Replace the recovery codes (a current code or recovery code proves it's the user); the old ones stop working. */
+  async regenerateRecoveryCodes(code: string): Promise<{ recoveryCodes: string[] }> {
+    return this.post("mfa/recovery-codes", { code }, await this.bearer());
   }
 
   /** Whether the server has no administrator yet (`GET /api/auth/admin/setup`). */
@@ -522,19 +641,20 @@ export class RxFerrixAuth {
     await this.post("reset/request", args);
   }
 
-  /** Set a new password with the reset link token or code; ends other sessions and signs in. */
   /**
    * Change the signed-in user's password; `currentPassword` proves it's them. Their other sessions end, this one stays
    * signed in. Fails with an `RxFerrixError` code such as `invalid_current_password` or `weak_password`.
    */
   async changePassword(currentPassword: string, newPassword: string): Promise<void> {
-    const token = await this.getAccessToken();
-    if (!token) throw new RxFerrixError("Sign in first", { code: "unauthenticated" });
-    await this.post("password/change", { currentPassword, newPassword }, token);
+    await this.post("password/change", { currentPassword, newPassword }, await this.bearer());
   }
 
-  async resetPassword(proof: CodeProof, password: string): Promise<void> {
-    await this.signedIn(await this.post<AuthTokens>("reset/confirm", { ...proof, password }));
+  /**
+   * Set a new password with the reset link token or code; ends other sessions and signs in (or resolves
+   * `mfaRequired` like {@link signIn}: a reset email doesn't bypass the second factor).
+   */
+  async resetPassword(proof: CodeProof, password: string): Promise<SignInResult> {
+    return this.signedInOrMfa(await this.post("reset/confirm", { ...proof, password }));
   }
 
   /** Email a magic sign-in link and a one-time code. Succeeds whether or not the account exists. */
@@ -542,14 +662,17 @@ export class RxFerrixAuth {
     await this.post("magic/request", args);
   }
 
-  /** Sign in with the one-time code from a magic link email. */
-  async verifyCode(args: { email: string; code: string }): Promise<void> {
-    await this.signedIn(await this.post<AuthTokens>("magic/verify", args));
+  /** Sign in with the one-time code from a magic link email (or resolve `mfaRequired`, as {@link signIn}). */
+  async verifyCode(args: { email: string; code: string }): Promise<SignInResult> {
+    return this.signedInOrMfa(await this.post("magic/verify", args));
   }
 
-  /** Sign in with the token of a magic link (usually done by {@link handleRedirectCallback}). */
-  async verifyMagicLink(token: string): Promise<void> {
-    await this.signedIn(await this.post<AuthTokens>("magic/verify", { token }));
+  /**
+   * Sign in with the token of a magic link (usually done by {@link handleRedirectCallback}); resolves `mfaRequired`
+   * as {@link signIn} does.
+   */
+  async verifyMagicLink(token: string): Promise<SignInResult> {
+    return this.signedInOrMfa(await this.post("magic/verify", { token }));
   }
 
   /** The URL that starts an OAuth sign-in with `provider`, returning to `redirectTo` (default: this page). */
@@ -573,9 +696,10 @@ export class RxFerrixAuth {
 
   /**
    * Handle the `#rxferrix_…` fragment that OAuth redirects and email links put on the URL: stores tokens (OAuth),
-   * signs in (magic link), confirms the email (verification link) or returns the reset token (password reset). The
-   * `rxferrix_` parameters are removed from the address bar first, so a reload can't replay them. Returns null when
-   * the URL has none.
+   * signs in (magic link), confirms the email (verification link) or returns the reset token (password reset). With
+   * two-factor authentication on the account, OAuth and magic links end in `{ type: "mfaRequired", mfaToken }`:
+   * ask for a code and call {@link verifyMfa}. The `rxferrix_` parameters are removed from the address bar first,
+   * so a reload can't replay them. Returns null when the URL has none.
    */
   async handleRedirectCallback(url?: string): Promise<RedirectResult | null> {
     const g = globalThis as {
@@ -610,10 +734,12 @@ export class RxFerrixAuth {
         await this.signedIn({ accessToken: access, refreshToken: refresh, expiresIn, ...(userId ? { userId } : {}) });
         return { type: "signedIn" };
       }
+      const mfaToken = ours.get("rxferrix_mfa_token");
+      if (mfaToken) return { type: "mfaRequired", mfaToken };
       const magic = ours.get("rxferrix_magic_token");
       if (magic) {
-        await this.verifyMagicLink(magic);
-        return { type: "signedIn" };
+        const r = await this.verifyMagicLink(magic);
+        return r.mfaRequired ? { type: "mfaRequired", mfaToken: r.mfaToken } : { type: "signedIn" };
       }
       const verify = ours.get("rxferrix_verify_token");
       if (verify) {

package/src/client.ts

@@ -136,7 +136,25 @@ function jwtExpiry(token: string): number | null {
 
 /** Refresh this long before a JWT's `exp`. */
 const TOKEN_REFRESH_LEEWAY_MS = 30_000;
+/** Never refresh more often than this, even for a token that expires within the leeway (its session may be ending). */
+const MIN_TOKEN_REFRESH_DELAY_MS = 5_000;
+/** A token getter that threw (the server unreachable at page load, ...) is retried with this backoff. */
+const TOKEN_FETCH_RETRY_BASE_MS = 2_000;
+const TOKEN_FETCH_RETRY_MAX_MS = 60_000;
 const MAX_TIMEOUT_MS = 2_147_483_647;
+/** The server's limit of live queries per socket; past it, a `ModifyQuerySet` is a fatal error (docs/PROTOCOL.md). */
+export const MAX_LIVE_QUERIES = 1024;
+
+/** The error for function args that can't be encoded as JSON (a cycle, a BigInt, ...), or null. */
+function unserializable(args: Record<string, unknown>): RxFerrixError | null {
+  try {
+    JSON.stringify(args);
+    return null;
+  } catch (e) {
+    const detail = e instanceof Error ? e.message : String(e);
+    return new RxFerrixError(`Arguments can't be serialized as JSON: ${detail}`, { code: "invalid_args", cause: e });
+  }
+}
 
 interface AuthState {
   fetchToken: AuthTokenFetcher;
@@ -192,6 +210,11 @@ export class RxFerrixClient {
   private isAuthenticated = false;
   private authGeneration = 0;
   private authRefreshTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Token fetches in flight: the last one to finish lets held-back sends through again. */
+  private tokenFetchesInFlight = 0;
+  private tokenFetchFailures = 0;
+  /** Rejecters of `query()` calls still waiting for their first result (settled on `close()`). */
+  private readonly oneShotQueries = new Set<(e: RxFerrixError) => void>();
 
   private readonly removeUnloadListener: () => void;
 
@@ -256,15 +279,20 @@ export class RxFerrixClient {
     return new Promise<OutputOf<Q>>((resolve, reject) => {
       let unsubscribe: (() => void) | null = null;
       let done = false;
-      const check = () => {
+      const finish = (settle: () => void) => {
         if (done) return;
-        const state = watch.localQueryState();
-        if (state.status === "loading") return;
         done = true;
+        this.oneShotQueries.delete(closed);
         if (unsubscribe) unsubscribe();
-        if (state.status === "success") resolve(state.value);
-        else reject(state.error);
+        settle();
       };
+      const closed = (e: RxFerrixError) => finish(() => reject(e));
+      const check = () => {
+        const state = watch.localQueryState();
+        if (state.status === "loading") return;
+        finish(() => (state.status === "success" ? resolve(state.value) : reject(state.error)));
+      };
+      this.oneShotQueries.add(closed);
       unsubscribe = watch.onUpdate(check);
       check();
     });
@@ -294,6 +322,13 @@ export class RxFerrixClient {
     callback: () => void,
   ): () => void {
     if (this.closed) return () => {};
+    if (!this.localQueries.get(token) && this.localQueries.size >= MAX_LIVE_QUERIES) {
+      // The server would answer the subscription with a fatal error and every reconnect would repeat it.
+      throw new RxFerrixError(
+        `Too many live queries: at most ${MAX_LIVE_QUERIES} distinct queries can be watched at once`,
+        { code: "too_many_queries" },
+      );
+    }
     let set = this.listeners.get(token);
     if (!set) {
       set = new Set();
@@ -349,6 +384,10 @@ export class RxFerrixClient {
     if (this.closed) return Promise.reject(new RxFerrixError("Client is closed", { code: CLIENT_CLOSED }));
     const args = normalizeArgs(argsAndOptions[0]);
     const options = argsAndOptions[1] as MutationOptions<ArgsOf<M>> | undefined;
+    // Checked before it is queued: a message that can't be encoded would otherwise be retried on every socket and
+    // block every later request behind it.
+    const invalid = unserializable(args);
+    if (invalid) return Promise.reject(invalid);
     const requestId = this.requests.allocateRequestId();
     const message: MutationMessage = { type: "Mutation", requestId, udfPath: ref._path, args };
     const promise = this.requests.trackMutation(message) as Promise<OutputOf<M>>;
@@ -366,8 +405,11 @@ export class RxFerrixClient {
   /** Runs an action. Rejects with a "connection lost" error if the socket drops while it is in flight. */
   action<A extends FunctionReference<"action">>(ref: A, ...args: OptionalArgs<A>): Promise<OutputOf<A>> {
     if (this.closed) return Promise.reject(new RxFerrixError("Client is closed", { code: CLIENT_CLOSED }));
+    const normalized = normalizeArgs(args[0]);
+    const invalid = unserializable(normalized);
+    if (invalid) return Promise.reject(invalid);
     const requestId = this.requests.allocateRequestId();
-    const message: ActionMessage = { type: "Action", requestId, udfPath: ref._path, args: normalizeArgs(args[0]) };
+    const message: ActionMessage = { type: "Action", requestId, udfPath: ref._path, args: normalized };
     const promise = this.requests.trackAction(message) as Promise<OutputOf<A>>;
     this.sendUnsentRequests();
     this.notifyConnectionState();
@@ -414,18 +456,44 @@ export class RxFerrixClient {
     if (!auth) return;
     const generation = ++this.authGeneration;
     if (pause) this.ws.pause();
-    let token: string | null = null;
+    this.tokenFetchesInFlight++;
     try {
-      token = (await auth.fetchToken({ forceRefresh })) ?? null;
-    } catch (e) {
-      this.logger.error("fetchToken threw; continuing unauthenticated", e);
-      token = null;
+      let token: string | null;
+      try {
+        token = (await auth.fetchToken({ forceRefresh })) ?? null;
+      } catch (e) {
+        if (generation !== this.authGeneration || this.auth !== auth || this.closed) return;
+        // The getter failed (the server unreachable at page load, a refresh that timed out): the session it would
+        // have returned may well be valid, so the token in hand (if any) is kept and the fetch is retried with
+        // backoff instead of treating the user as signed out.
+        this.tokenFetchFailures++;
+        const delay = Math.min(
+          TOKEN_FETCH_RETRY_MAX_MS,
+          TOKEN_FETCH_RETRY_BASE_MS * 2 ** Math.min(this.tokenFetchFailures - 1, 10),
+        );
+        this.logger.warn(`fetchToken failed; retrying in ${delay}ms`, e);
+        this.scheduleTokenFetch(delay, forceRefresh);
+        return;
+      }
+      if (generation !== this.authGeneration || this.auth !== auth || this.closed) return;
+      this.tokenFetchFailures = 0;
+      this.applyToken(token);
+      if (token === null) this.setAuthenticated(false, auth.onChange);
+      this.scheduleTokenRefresh(token);
+    } finally {
+      this.tokenFetchesInFlight--;
+      // Whichever fetch finishes last lets sends through again: a superseded fetch (a newer `setAuth` or
+      // `clearAuth`) must not leave the socket paused for good.
+      if (this.tokenFetchesInFlight === 0 && this.ws.isPaused && !this.closed) this.ws.resume();
     }
-    if (generation !== this.authGeneration || this.auth !== auth || this.closed) return;
-    this.applyToken(token);
-    if (token === null) this.setAuthenticated(false, auth.onChange);
-    this.scheduleTokenRefresh(token);
-    if (pause) this.ws.resume();
+  }
+
+  private scheduleTokenFetch(delay: number, forceRefresh: boolean): void {
+    this.clearAuthRefreshTimer();
+    this.authRefreshTimer = setTimeout(() => {
+      this.authRefreshTimer = null;
+      void this.fetchAndApplyToken(forceRefresh, false);
+    }, delay);
   }
 
   /** Records the desired token and sends `Authenticate` when the server's token differs. */
@@ -449,11 +517,13 @@ export class RxFerrixClient {
     if (!token) return;
     const exp = jwtExpiry(token);
     if (exp === null) return;
-    const delay = Math.min(MAX_TIMEOUT_MS, Math.max(0, exp * 1000 - Date.now() - TOKEN_REFRESH_LEEWAY_MS));
-    this.authRefreshTimer = setTimeout(() => {
-      this.authRefreshTimer = null;
-      void this.fetchAndApplyToken(true, false);
-    }, delay);
+    // Floored: a token that already expires within the leeway (its session is about to end) would otherwise be
+    // refreshed again the moment the refreshed one arrives, in a tight loop.
+    const delay = Math.min(
+      MAX_TIMEOUT_MS,
+      Math.max(MIN_TOKEN_REFRESH_DELAY_MS, exp * 1000 - Date.now() - TOKEN_REFRESH_LEEWAY_MS),
+    );
+    this.scheduleTokenFetch(delay, true);
   }
 
   private clearAuthRefreshTimer(): void {
@@ -706,7 +776,11 @@ export class RxFerrixClient {
     this.clearAuthRefreshTimer();
     this.ws.stop();
     this.removeUnloadListener();
-    this.requests.rejectAll(new RxFerrixError("Client is closed", { code: CLIENT_CLOSED }));
+    const closed = new RxFerrixError("Client is closed", { code: CLIENT_CLOSED });
+    this.requests.rejectAll(closed);
+    // One-shot queries still waiting for a first result would never settle once the listeners are gone.
+    for (const reject of [...this.oneShotQueries]) reject(closed);
+    this.oneShotQueries.clear();
     this.listeners.clear();
     this.notifyConnectionState();
   }

package/src/index.ts

@@ -36,6 +36,9 @@ export {
   type CodeProof,
   type RxFerrixAuthOptions,
   type RedirectResult,
+  type SignInResult,
+  type MfaStatus,
+  type MfaSetup,
   type User,
 } from "./auth.js";
 export type { OptimisticLocalStore, OptimisticUpdate } from "./optimistic_updates.js";

package/src/protocol.ts

@@ -6,7 +6,7 @@ export type QueryId = number;
 export type RequestId = number;
 export type JSONValue = null | boolean | number | string | JSONValue[] | { [key: string]: JSONValue };
 
-export const CLIENT_VERSION = "0.2.0";
+export const CLIENT_VERSION = "0.3.0";
 
 export interface StateVersion {
   querySet: number;

package/src/web_socket_manager.ts

@@ -5,6 +5,11 @@ import type { Logger } from "./logging.js";
 export const SERVER_INACTIVITY_TIMEOUT_MS = 30_000;
 const INITIAL_BACKOFF_MS = 250;
 const MAX_BACKOFF_MS = 16_000;
+/**
+ * A socket that hasn't opened after this long is dropped and retried (a black-holed connect would otherwise hang
+ * forever). As long as the silence threshold: a server that takes longer than that to accept is as good as down.
+ */
+export const CONNECT_TIMEOUT_MS = 30_000;
 /** The close code a server sends when it restarts or hands over to a new process (RFC 6455 "Service Restart"). */
 const SERVICE_RESTART = 1012;
 /** Spread of the immediate reconnects after a restart, so every client doesn't arrive in the same millisecond. */
@@ -62,6 +67,7 @@ export class WebSocketManager {
   private retries = 0;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
   private watchdogTimer: ReturnType<typeof setTimeout> | null = null;
+  private connectTimer: ReturnType<typeof setTimeout> | null = null;
   private readonly removeEnvListeners: () => void;
 
   constructor(options: WebSocketManagerOptions, callbacks: WebSocketManagerCallbacks) {
@@ -157,9 +163,18 @@ export class WebSocketManager {
   private rawSend(message: ClientMessage): boolean {
     const ws = this.ws;
     if (!ws) return false;
+    let data: string;
+    try {
+      data = JSON.stringify(message);
+    } catch (e) {
+      // Not a transport failure: reconnecting wouldn't help, and queueing the message would block every later one
+      // behind it. (Mutation and action args are checked before they are queued; this is the last line of defense.)
+      this.logger.error("message can't be serialized and was dropped", e);
+      return true;
+    }
     try {
       this.logger.debug("->", message);
-      ws.send(JSON.stringify(message));
+      ws.send(data);
       return true;
     } catch (e) {
       this.logger.warn("WebSocket send failed", e);
@@ -185,9 +200,15 @@ export class WebSocketManager {
     this.initialized = false;
     this._connectionCount += 1;
     this.callbacks.onStateChange();
+    this.clearConnectTimer();
+    this.connectTimer = setTimeout(() => {
+      this.connectTimer = null;
+      if (this.ws === ws && this._state === "connecting") this.reconnect("ConnectTimeout");
+    }, CONNECT_TIMEOUT_MS);
 
     ws.onopen = () => {
       if (this.ws !== ws) return;
+      this.clearConnectTimer();
       this._state = "ready";
       this._hasEverConnected = true;
       this.resetWatchdog();
@@ -208,6 +229,8 @@ export class WebSocketManager {
     ws.onmessage = (event: MessageEvent) => {
       if (this.ws !== ws) return;
       this.resetWatchdog();
+      // The server talks on this socket: it is up, so the next reconnect (if any) starts from a short delay.
+      this.retries = 0;
       let message: ServerMessage;
       try {
         message = JSON.parse(typeof event.data === "string" ? event.data : String(event.data)) as ServerMessage;
@@ -238,6 +261,7 @@ export class WebSocketManager {
   /** Detaches and closes the current socket (if any), reporting `onClose` once. */
   private closeCurrent(reason: string): void {
     this.clearWatchdog();
+    this.clearConnectTimer();
     const ws = this.ws;
     if (!ws) return;
     const wasOpen = this._state === "ready";
@@ -291,6 +315,13 @@ export class WebSocketManager {
     }, SERVER_INACTIVITY_TIMEOUT_MS);
   }
 
+  private clearConnectTimer(): void {
+    if (this.connectTimer !== null) {
+      clearTimeout(this.connectTimer);
+      this.connectTimer = null;
+    }
+  }
+
   private clearWatchdog(): void {
     if (this.watchdogTimer !== null) {
       clearTimeout(this.watchdogTimer);