@korajs/auth 1.0.0-beta.12 → 1.0.0-beta.14

package/dist/index.js

@@ -38,7 +38,19 @@ var AuthError = class extends KoraError {
     this.name = "AuthError";
   }
 };
+var MfaRequiredError = class extends AuthError {
+  constructor(mfaToken) {
+    super("A second factor is required to finish signing in.", "AUTH_MFA_REQUIRED");
+    this.mfaToken = mfaToken;
+    this.name = "MfaRequiredError";
+  }
+  mfaToken;
+};
 var EXPIRY_BUFFER_SECONDS = 30;
+var DEFAULT_REQUEST_TIMEOUT_MS = 2e4;
+var DEFAULT_BACKOFF_BASE_MS = 2e3;
+var DEFAULT_BACKOFF_MAX_MS = 5 * 6e4;
+var CLOCK_ROLLBACK_TOLERANCE_MS = 5 * 6e4;
 function decodeJwtPayload(token) {
   const parts = token.split(".");
   if (parts.length !== 3) {
@@ -47,25 +59,28 @@ function decodeJwtPayload(token) {
   try {
     const base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
     const json = atob(base64);
-    return JSON.parse(json);
+    const parsed = JSON.parse(json);
+    return isRecord(parsed) ? parsed : null;
   } catch {
     return null;
   }
 }
-function isTokenExpired(token) {
+function isTokenExpired(token, bufferSeconds = EXPIRY_BUFFER_SECONDS) {
   const payload = decodeJwtPayload(token);
   if (!payload || typeof payload.exp !== "number") {
     return true;
   }
   const nowSeconds = Math.floor(Date.now() / 1e3);
-  return payload.exp <= nowSeconds + EXPIRY_BUFFER_SECONDS;
+  return payload.exp <= nowSeconds + bufferSeconds;
 }
-function getUserIdFromToken(token) {
+function tokenIssuedAtMs(token) {
   const payload = decodeJwtPayload(token);
-  if (!payload || typeof payload.sub !== "string") {
-    return null;
-  }
-  return payload.sub;
+  if (!payload) return null;
+  if (typeof payload.iatMs === "number") return payload.iatMs;
+  return typeof payload.iat === "number" ? payload.iat * 1e3 : null;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function getDefaultFetch() {
   if (typeof globalThis.fetch !== "function") {
@@ -97,6 +112,46 @@ function redirectCurrentWindow(url) {
   }
   globalThis.window.location.assign(url);
 }
+var OAUTH_BINDING_PREFIX = "kora_oauth_binding:";
+function getSessionStorage() {
+  try {
+    const storage = globalThis.sessionStorage;
+    return storage && typeof storage.getItem === "function" ? storage : null;
+  } catch {
+    return null;
+  }
+}
+var DEFINITIVE_REFRESH_CODES = /* @__PURE__ */ new Set(["REFRESH_TOKEN_INVALID", "invalid_grant"]);
+function isDefinitiveRejection(response) {
+  if (!isRecord(response.json)) return false;
+  const code = typeof response.json.code === "string" ? response.json.code : void 0;
+  const error = typeof response.json.error === "string" ? response.json.error : void 0;
+  if (response.status === 401) return code !== void 0 || error !== void 0;
+  if (response.status === 400) {
+    return code !== void 0 && DEFINITIVE_REFRESH_CODES.has(code) || error !== void 0 && DEFINITIVE_REFRESH_CODES.has(error);
+  }
+  return false;
+}
+function parseRetryAfter(value) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? void 0 : Math.max(0, date - Date.now());
+}
+function readTokenPair(json) {
+  if (!isRecord(json)) return null;
+  const data = json.data !== void 0 ? json.data : json;
+  if (!isRecord(data)) return null;
+  return typeof data.accessToken === "string" && typeof data.refreshToken === "string" ? { accessToken: data.accessToken, refreshToken: data.refreshToken } : null;
+}
+var inProcessLocks = /* @__PURE__ */ new WeakMap();
+function getWebLocks() {
+  const nav = globalThis.navigator;
+  const locks = nav?.locks;
+  if (typeof locks !== "object" || locks === null) return null;
+  return typeof locks.request === "function" ? locks : null;
+}
 function createTokenStorage(prefix) {
   let useLocalStorage = false;
   try {
@@ -153,10 +208,22 @@ var AuthClient = class {
   fetchFn;
   deviceIdentity;
   listeners = /* @__PURE__ */ new Set();
+  sessionListeners = /* @__PURE__ */ new Set();
+  requestTimeoutMs;
+  maxOfflineGraceMs;
+  backoffBaseMs;
+  backoffMaxMs;
+  lockName;
   _state = "loading";
   _user = null;
   _refreshPromise = null;
   _initialized = false;
+  sessionStatus = "fresh";
+  lastServerContactAt = 0;
+  failureCount = 0;
+  nextAttemptAt = 0;
+  retryTimer = null;
+  detachEnvironment;
   /**
    * Creates a new AuthClient.
    *
@@ -168,6 +235,12 @@ var AuthClient = class {
     this.storage = config.storage ?? createTokenStorage(prefix);
     this.fetchFn = config.fetch ?? getDefaultFetch();
     this.deviceIdentity = config.deviceIdentity;
+    this.requestTimeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    this.maxOfflineGraceMs = config.maxOfflineGraceMs;
+    this.backoffBaseMs = config.refreshBackoff?.baseDelayMs ?? DEFAULT_BACKOFF_BASE_MS;
+    this.backoffMaxMs = config.refreshBackoff?.maxDelayMs ?? DEFAULT_BACKOFF_MAX_MS;
+    this.lockName = `kora-auth-refresh:${prefix}`;
+    this.detachEnvironment = this.attachEnvironmentListeners();
   }
   // -----------------------------------------------------------------------
   // Public getters
@@ -180,10 +253,54 @@ var AuthClient = class {
   get currentUser() {
     return this._user;
   }
-  /** Whether the user is currently authenticated. */
+  /** Whether the user is currently authenticated (fresh or offline). */
   get isAuthenticated() {
     return this._state === "authenticated";
   }
+  /**
+   * The stored session identity and its freshness, or null when signed out.
+   * Unlike {@link getAccessToken}, this is available offline: the identity is
+   * decoupled from whether a fresh access token can be minted right now.
+   */
+  get session() {
+    if (this._state !== "authenticated" || !this._user) return null;
+    return {
+      userId: this._user.id,
+      deviceId: this.cachedDeviceId,
+      status: this.sessionStatus,
+      lastServerContactAt: this.lastServerContactAt
+    };
+  }
+  cachedDeviceId = null;
+  /**
+   * Read the stored session identity (user id and device id) from storage,
+   * without any network request. Returns null when no usable session is stored.
+   */
+  async getStoredIdentity() {
+    const claims = await this.getStoredClaims();
+    if (!claims || typeof claims.sub !== "string" || claims.sub.length === 0) return null;
+    return {
+      userId: claims.sub,
+      deviceId: typeof claims.dev === "string" && claims.dev.length > 0 ? claims.dev : null
+    };
+  }
+  /**
+   * Decoded (unverified) claims of the stored credentials, preferring the access
+   * token even when it has expired. For client-side hints only (local database
+   * name, sync node id, handshake scope narrowing); the server re-derives
+   * everything it authorizes from a verified token.
+   */
+  async getStoredClaims() {
+    const access = await this.storage.getAccessToken();
+    const refresh = await this.storage.getRefreshToken();
+    if (!refresh) return null;
+    for (const token of [access, refresh]) {
+      if (!token) continue;
+      const claims = decodeJwtPayload(token);
+      if (claims && typeof claims.sub === "string" && claims.sub.length > 0) return claims;
+    }
+    return null;
+  }
   // -----------------------------------------------------------------------
   // Initialization
   // -----------------------------------------------------------------------
@@ -192,6 +309,8 @@ var AuthClient = class {
    *
    * Loads tokens from storage, validates the access token, and attempts a
    * refresh if the access token is expired but a refresh token is available.
+   * When the auth server cannot be reached, the stored session is restored as
+   * authenticated-offline instead of being discarded.
    * Safe to call multiple times -- subsequent calls are no-ops once initialized.
    */
   async initialize() {
@@ -205,20 +324,21 @@ var AuthClient = class {
       this.setState("unauthenticated", null);
       return;
     }
+    this.noteIssuedCredential(refreshToken);
     if (!isTokenExpired(accessToken)) {
       await this.restoreSession(accessToken);
       return;
     }
-    try {
-      const newAccessToken = await this.refreshAccessToken(refreshToken);
-      if (newAccessToken) {
-        await this.restoreSession(newAccessToken);
-        return;
-      }
-    } catch {
+    const outcome = await this.refresh();
+    if (outcome.kind === "ok") {
+      await this.restoreSession(outcome.accessToken);
+      return;
     }
-    await this.storage.clear();
-    this.setState("unauthenticated", null);
+    if (outcome.kind === "rejected") {
+      this.setState("unauthenticated", null);
+      return;
+    }
+    await this.enterOfflineSession();
   }
   // -----------------------------------------------------------------------
   // Sign up / Sign in / Sign out
@@ -236,11 +356,7 @@ var AuthClient = class {
       method: "POST",
       body
     });
-    const tokens = "tokens" in response ? response.tokens : response;
-    await this.storage.setTokens(tokens.accessToken, tokens.refreshToken);
-    const user = await this.fetchUserProfile(tokens.accessToken);
-    this.setState("authenticated", user);
-    return user;
+    return this.completeSignIn(response);
   }
   /**
    * Sign in with email and password.
@@ -255,11 +371,22 @@ var AuthClient = class {
       method: "POST",
       body
     });
-    const tokens = "tokens" in response ? response.tokens : response;
-    await this.storage.setTokens(tokens.accessToken, tokens.refreshToken);
-    const user = await this.fetchUserProfile(tokens.accessToken);
-    this.setState("authenticated", user);
-    return user;
+    return this.completeSignIn(response);
+  }
+  /**
+   * Finish a sign-in that required a second factor.
+   *
+   * @param mfaToken - From the {@link MfaRequiredError} thrown by sign-in
+   * @param proof - A current TOTP code, or a recovery code
+   * @returns The authenticated AuthUser
+   * @throws {AuthError} If the code or the MFA session is invalid
+   */
+  async verifyMfa(mfaToken, proof) {
+    const response = await this.request("/auth/mfa/verify", {
+      method: "POST",
+      body: { mfaToken, ...proof }
+    });
+    return this.completeSignIn(response);
   }
   /**
    * Create an OAuth authorization URL and optionally redirect the current window.
@@ -280,14 +407,19 @@ var AuthClient = class {
    */
   async completeOAuthSignIn(provider, params) {
     const body = await this.withDeviceIdentity(params);
+    const binding = params.binding ?? this.takeOAuthBinding(params.state);
     const response = await this.request(
       `/auth/oauth/${encodeURIComponent(provider)}/callback`,
       {
         method: "POST",
-        body: { ...body }
+        body: { ...body, ...binding ? { binding } : {} }
       }
     );
+    if ("mfaRequired" in response) {
+      throw new MfaRequiredError(response.mfaToken);
+    }
     await this.storage.setTokens(response.tokens.accessToken, response.tokens.refreshToken);
+    this.markFresh(response.tokens.refreshToken);
     const user = normalizeAuthUser(response.user);
     this.setState("authenticated", user);
     return user;
@@ -295,19 +427,27 @@ var AuthClient = class {
   /**
    * Create an OAuth authorization URL for linking another provider to the current user.
    */
-  async getOAuthAuthorizationUrl(provider, options = {}) {
-    return this.createOAuthAuthorization(provider, { ...options, redirect: false });
+  async getOAuthAuthorizationUrl(provider, _options = {}) {
+    const token = await this.requireAccessToken();
+    const result = await this.request(
+      `/auth/oauth/${encodeURIComponent(provider)}/link/start`,
+      { method: "POST", body: {}, token }
+    );
+    this.rememberOAuthBinding(result);
+    return result;
   }
   /**
    * Link an OAuth provider to the current authenticated user.
    */
   async linkOAuth(provider, params) {
     const token = await this.requireAccessToken();
+    const binding = params.binding ?? this.takeOAuthBinding(params.state);
     return this.request(`/auth/oauth/${encodeURIComponent(provider)}/link`, {
       method: "POST",
       body: {
         code: params.code,
-        state: params.state
+        state: params.state,
+        ...binding ? { binding } : {}
       },
       token
     });
@@ -344,6 +484,9 @@ var AuthClient = class {
     const refreshToken = await this.storage.getRefreshToken();
     await this.storage.clear();
     this._refreshPromise = null;
+    this.resetBackoff();
+    this.sessionStatus = "fresh";
+    this.cachedDeviceId = null;
     this.setState("unauthenticated", null);
     if (accessToken) {
       try {
@@ -362,24 +505,46 @@ var AuthClient = class {
   /**
    * Get a valid access token, automatically refreshing if expired.
    *
-   * @returns A valid access token string, or null if the user is not
-   *          authenticated and refresh is not possible
+   * Returns null when no fresh token can be obtained right now. That does NOT
+   * mean the user is signed out: check {@link state} / {@link session}. A
+   * transient failure keeps the session (authenticated-offline) and later calls
+   * retry with backoff.
+   *
+   * @returns A valid access token string, or null if none is available now
    */
   async getAccessToken() {
     const accessToken = await this.storage.getAccessToken();
     if (accessToken && !isTokenExpired(accessToken)) {
+      if (this._state === "authenticated" && this.sessionStatus !== "fresh") {
+        this.markFresh(await this.storage.getRefreshToken());
+      }
       return accessToken;
     }
     const refreshToken = await this.storage.getRefreshToken();
     if (!refreshToken) {
       return null;
     }
-    try {
-      const newAccessToken = await this.refreshAccessToken(refreshToken);
-      return newAccessToken;
-    } catch {
+    const outcome = await this.refresh();
+    return outcome.kind === "ok" ? outcome.accessToken : null;
+  }
+  /**
+   * Refresh the session now, even when the cached access token has not expired
+   * locally. Used after the sync server ended a session with `AUTH_EXPIRED` or
+   * `AUTH_REVOKED`: the server's clock or a revocation says the cached token is
+   * no longer good. Concurrent calls (and other tabs) share one refresh.
+   *
+   * A transient failure keeps the session (authenticated-offline) and returns
+   * null; only a definitive server rejection signs the user out.
+   *
+   * @returns The refreshed access token, or null if none could be obtained now
+   */
+  async refreshAccessToken() {
+    const refreshToken = await this.storage.getRefreshToken();
+    if (!refreshToken) {
       return null;
     }
+    const outcome = await this.refresh();
+    return outcome.kind === "ok" ? outcome.accessToken : null;
   }
   /**
    * Get a valid token for the sync engine handshake.
@@ -390,6 +555,23 @@ var AuthClient = class {
   async getSyncToken() {
     return this.getAccessToken();
   }
+  /**
+   * Retry immediately: clears the refresh backoff and attempts a refresh if the
+   * session is offline. Call it when connectivity is known to be back (for
+   * example when a sync transport opens). Also wired to the browser `online`
+   * and `visibilitychange` events automatically.
+   */
+  async retryNow() {
+    this.resetBackoff();
+    if (this._state === "authenticated" && this.sessionStatus !== "fresh") {
+      await this.getAccessToken();
+    }
+  }
+  /** Remove environment listeners and timers (for tests and teardown). */
+  destroy() {
+    this.detachEnvironment();
+    this.clearRetryTimer();
+  }
   // -----------------------------------------------------------------------
   // State change subscriptions
   // -----------------------------------------------------------------------
@@ -416,6 +598,20 @@ var AuthClient = class {
       this.listeners.delete(callback);
     };
   }
+  /**
+   * Subscribe to session freshness changes (fresh, authenticated-offline,
+   * locked). Fires in addition to {@link onAuthChange}, including when the
+   * state stays 'authenticated' but connectivity to the auth server changes.
+   *
+   * @param callback - Called with the current session (null when signed out)
+   * @returns An unsubscribe function
+   */
+  onSessionChange(callback) {
+    this.sessionListeners.add(callback);
+    return () => {
+      this.sessionListeners.delete(callback);
+    };
+  }
   // -----------------------------------------------------------------------
   // Internal helpers
   // -----------------------------------------------------------------------
@@ -433,30 +629,115 @@ var AuthClient = class {
         } catch {
         }
       }
+      this.notifySession();
     }
   }
+  setSessionStatus(status) {
+    if (this.sessionStatus === status) return;
+    this.sessionStatus = status;
+    this.notifySession();
+  }
+  notifySession() {
+    const session = this.session;
+    for (const listener of this.sessionListeners) {
+      try {
+        listener(session);
+      } catch {
+      }
+    }
+  }
+  async completeSignIn(response) {
+    if ("mfaRequired" in response) {
+      throw new MfaRequiredError(response.mfaToken);
+    }
+    const tokens = "tokens" in response ? response.tokens : response;
+    await this.storage.setTokens(tokens.accessToken, tokens.refreshToken);
+    this.markFresh(tokens.refreshToken);
+    const user = "user" in response && response.user ? normalizeAuthUser(response.user) : await this.fetchUserProfile(tokens.accessToken);
+    this.setState("authenticated", user);
+    return user;
+  }
   /**
    * Restore a session from a valid access token by fetching the user profile.
-   * Falls back to extracting the user ID from the token payload if the
-   * /auth/me request fails (offline scenario).
+   * A definitive 401 from `/auth/me` ends the session (NEW-AUTH-4); any other
+   * failure restores it as authenticated-offline from the stored identity.
    */
   async restoreSession(accessToken) {
+    let response;
     try {
-      const user = await this.fetchUserProfile(accessToken);
-      this.setState("authenticated", user);
+      response = await this.rawRequest("/auth/me", { method: "GET", token: accessToken });
     } catch {
-      const userId = getUserIdFromToken(accessToken);
-      if (userId) {
-        this.setState("authenticated", {
-          id: userId,
-          email: "",
-          name: null
-        });
-      } else {
-        await this.storage.clear();
-        this.setState("unauthenticated", null);
+      await this.enterOfflineSession();
+      return;
+    }
+    if (response.ok && isRecord(response.json)) {
+      const profile = response.json.data !== void 0 ? response.json.data : response.json;
+      if (isRecord(profile) && typeof profile.id === "string") {
+        this.markFresh(null);
+        this.setState("authenticated", normalizeAuthUser(profile));
+        return;
       }
     }
+    if (response.status === 401 && isDefinitiveRejection(response)) {
+      await this.endSession();
+      return;
+    }
+    await this.enterOfflineSession();
+  }
+  /**
+   * Restore the session from stored credentials while the auth server is
+   * unreachable. Signs out only when the stored refresh token is unusable.
+   */
+  async enterOfflineSession() {
+    const refreshToken = await this.storage.getRefreshToken();
+    const identity = await this.getStoredIdentity();
+    if (!refreshToken || !identity || isTokenExpired(refreshToken, 0)) {
+      await this.endSession();
+      return;
+    }
+    this.cachedDeviceId = identity.deviceId;
+    this.noteIssuedCredential(refreshToken);
+    const user = this._user && this._user.id === identity.userId ? this._user : { id: identity.userId, email: "", name: null };
+    this.sessionStatus = this.offlineStatus();
+    this.setState("authenticated", user);
+    this.notifySession();
+  }
+  /** Offline, or locked when the grace period ran out or the clock went backwards. */
+  offlineStatus() {
+    const now = Date.now();
+    if (this.lastServerContactAt > 0 && now + CLOCK_ROLLBACK_TOLERANCE_MS < this.lastServerContactAt) {
+      return "locked";
+    }
+    if (this.maxOfflineGraceMs !== void 0 && this.lastServerContactAt > 0 && now - this.lastServerContactAt > this.maxOfflineGraceMs) {
+      return "locked";
+    }
+    return "offline";
+  }
+  async endSession() {
+    await this.storage.clear();
+    this.resetBackoff();
+    this.sessionStatus = "fresh";
+    this.cachedDeviceId = null;
+    this.setState("unauthenticated", null);
+  }
+  /** The refresh token's issue time is the server's clock at the last rotation. */
+  noteIssuedCredential(refreshToken) {
+    if (!refreshToken) return;
+    const issued = tokenIssuedAtMs(refreshToken);
+    if (issued !== null) this.lastServerContactAt = Math.max(this.lastServerContactAt, issued);
+    const claims = decodeJwtPayload(refreshToken);
+    if (claims && typeof claims.dev === "string") this.cachedDeviceId = claims.dev;
+  }
+  markFresh(refreshToken) {
+    this.resetBackoff();
+    this.lastServerContactAt = Math.max(this.lastServerContactAt, Date.now());
+    this.noteIssuedCredential(refreshToken);
+    this.setSessionStatus("fresh");
+  }
+  markOffline() {
+    if (this._state === "authenticated") {
+      this.setSessionStatus(this.offlineStatus());
+    }
   }
   /**
    * Fetch the current user profile from the server.
@@ -470,19 +751,9 @@ var AuthClient = class {
   }
   async createOAuthAuthorization(provider, options) {
     const params = new URLSearchParams();
-    const withIdentity = await this.withDeviceIdentity({
-      deviceId: options.deviceId,
-      devicePublicKey: options.devicePublicKey
-    });
     if (options.returnTo) {
       params.set("returnTo", options.returnTo);
     }
-    if (withIdentity.deviceId) {
-      params.set("deviceId", withIdentity.deviceId);
-    }
-    if (withIdentity.devicePublicKey) {
-      params.set("devicePublicKey", withIdentity.devicePublicKey);
-    }
     if (options.metadata) {
       for (const [key, value] of Object.entries(options.metadata)) {
         if (value !== void 0 && value !== null) {
@@ -491,12 +762,38 @@ var AuthClient = class {
       }
     }
     const query = params.toString();
-    return this.request(
+    const result = await this.request(
       `/auth/oauth/${encodeURIComponent(provider)}${query ? `?${query}` : ""}`,
       {
         method: "GET"
       }
     );
+    this.rememberOAuthBinding(result);
+    return result;
+  }
+  /** Bindings of flows this client started, by state (survives the redirect on web). */
+  oauthBindings = /* @__PURE__ */ new Map();
+  rememberOAuthBinding(result) {
+    if (!result.binding || !result.state) return;
+    this.oauthBindings.set(result.state, result.binding);
+    const session = getSessionStorage();
+    try {
+      session?.setItem(`${OAUTH_BINDING_PREFIX}${result.state}`, result.binding);
+    } catch {
+    }
+  }
+  takeOAuthBinding(state) {
+    const inMemory = this.oauthBindings.get(state);
+    this.oauthBindings.delete(state);
+    const session = getSessionStorage();
+    let stored = null;
+    try {
+      stored = session?.getItem(`${OAUTH_BINDING_PREFIX}${state}`) ?? null;
+      session?.removeItem(`${OAUTH_BINDING_PREFIX}${state}`);
+    } catch {
+      stored = null;
+    }
+    return inMemory ?? stored ?? void 0;
   }
   async withDeviceIdentity(params) {
     if (!this.deviceIdentity || params.deviceId && params.devicePublicKey) {
@@ -510,54 +807,187 @@ var AuthClient = class {
     };
   }
   /**
-   * Refresh the access token using a refresh token.
-   * De-duplicates concurrent refresh calls so only one network request is made.
+   * Refresh the session's tokens. De-duplicates concurrent calls in this
+   * client, serializes refreshes across tabs, and applies backoff after
+   * transient failures.
    */
-  async refreshAccessToken(refreshToken) {
+  refresh() {
     if (this._refreshPromise) {
       return this._refreshPromise;
     }
-    this._refreshPromise = this.performRefresh(refreshToken);
-    try {
-      const result = await this._refreshPromise;
-      return result;
-    } finally {
-      this._refreshPromise = null;
-    }
+    const promise = this.refreshOnce().finally(() => {
+      if (this._refreshPromise === promise) this._refreshPromise = null;
+    });
+    this._refreshPromise = promise;
+    return promise;
   }
-  async requireAccessToken() {
-    const token = await this.getAccessToken();
-    if (!token) {
-      throw new AuthError("You must be signed in to perform this action.", "AUTH_REQUIRED");
+  async refreshOnce() {
+    const refreshToken = await this.storage.getRefreshToken();
+    if (!refreshToken) return { kind: "rejected" };
+    if (isTokenExpired(refreshToken, 0)) {
+      await this.endSession();
+      return { kind: "rejected" };
     }
-    return token;
+    if (Date.now() < this.nextAttemptAt) {
+      this.markOffline();
+      return { kind: "transient" };
+    }
+    let outcome;
+    try {
+      outcome = await this.withRefreshLock(async () => {
+        const current = await this.storage.getRefreshToken();
+        if (!current) return { kind: "rejected" };
+        const currentAccess = await this.storage.getAccessToken();
+        if (current !== refreshToken && currentAccess && !isTokenExpired(currentAccess)) {
+          return { kind: "ok", accessToken: currentAccess };
+        }
+        return this.performRefresh(current);
+      });
+    } catch {
+      outcome = { kind: "transient" };
+    }
+    if (outcome.kind === "ok") {
+      this.markFresh(await this.storage.getRefreshToken());
+    } else if (outcome.kind === "rejected") {
+      this.resetBackoff();
+      this.cachedDeviceId = null;
+      this.sessionStatus = "fresh";
+      this.setState("unauthenticated", null);
+    } else {
+      this.registerFailure(outcome.retryAfterMs);
+      this.markOffline();
+    }
+    return outcome;
   }
   /**
-   * Execute the token refresh network request.
+   * Execute the token refresh network request and classify the answer.
    */
   async performRefresh(refreshToken) {
+    let response;
     try {
-      const response = await this.request("/auth/refresh", {
+      response = await this.rawRequest("/auth/refresh", {
         method: "POST",
         body: { refreshToken }
       });
-      await this.storage.setTokens(response.accessToken, response.refreshToken);
-      return response.accessToken;
     } catch {
-      await this.storage.clear();
-      this.setState("unauthenticated", null);
-      return null;
+      return { kind: "transient" };
+    }
+    if (response.ok) {
+      const tokens = readTokenPair(response.json);
+      if (!tokens) {
+        return { kind: "transient" };
+      }
+      await this.storage.setTokens(tokens.accessToken, tokens.refreshToken);
+      return { kind: "ok", accessToken: tokens.accessToken };
+    }
+    if (isDefinitiveRejection(response)) {
+      if (await this.storage.getRefreshToken() === refreshToken) {
+        await this.storage.clear();
+        return { kind: "rejected" };
+      }
+      const adopted = await this.storage.getAccessToken();
+      return adopted && !isTokenExpired(adopted) ? { kind: "ok", accessToken: adopted } : { kind: "transient" };
     }
+    return { kind: "transient", retryAfterMs: response.retryAfterMs };
+  }
+  async withRefreshLock(fn) {
+    const locks = getWebLocks();
+    if (locks) {
+      const controller = typeof AbortController === "function" ? new AbortController() : null;
+      const timer = controller ? setTimeout(() => controller.abort(), this.requestTimeoutMs * 2) : null;
+      try {
+        return await locks.request(
+          this.lockName,
+          controller ? { signal: controller.signal } : {},
+          async () => {
+            if (timer) clearTimeout(timer);
+            return fn();
+          }
+        );
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+    }
+    const key = this.storage;
+    const previous = inProcessLocks.get(key) ?? Promise.resolve();
+    const run = previous.then(fn, fn);
+    inProcessLocks.set(
+      key,
+      run.then(
+        () => void 0,
+        () => void 0
+      )
+    );
+    return run;
   }
   /**
-   * Make an HTTP request to the auth server.
-   *
-   * @param path - URL path relative to serverUrl (e.g. '/auth/signin')
-   * @param options - Request options
-   * @returns Parsed JSON response body
-   * @throws {AuthError} On network failure or non-2xx response
+   * Schedule the next allowed refresh attempt. The first retry after a failure
+   * is immediate (it recovers a rotation response lost on the wire); after
+   * that, exponential backoff with equal jitter, never earlier than Retry-After.
    */
-  async request(path, options) {
+  registerFailure(retryAfterMs) {
+    this.failureCount++;
+    let delay = 0;
+    if (this.failureCount > 1) {
+      const ceiling = Math.min(this.backoffBaseMs * 2 ** (this.failureCount - 2), this.backoffMaxMs);
+      delay = ceiling / 2 + Math.random() * (ceiling / 2);
+    }
+    if (retryAfterMs !== void 0) delay = Math.max(delay, retryAfterMs);
+    this.nextAttemptAt = Date.now() + delay;
+    this.scheduleRetry(Math.max(delay, this.backoffBaseMs));
+  }
+  resetBackoff() {
+    this.failureCount = 0;
+    this.nextAttemptAt = 0;
+    this.clearRetryTimer();
+  }
+  /** Background retry so an offline session recovers without the app calling in. */
+  scheduleRetry(delayMs) {
+    this.clearRetryTimer();
+    if (typeof setTimeout !== "function") return;
+    const timer = setTimeout(() => {
+      this.retryTimer = null;
+      if (this._state === "authenticated" && this.sessionStatus !== "fresh") {
+        void this.getAccessToken().catch(() => void 0);
+      }
+    }, delayMs);
+    timer.unref?.();
+    this.retryTimer = timer;
+  }
+  clearRetryTimer() {
+    if (this.retryTimer !== null) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = null;
+    }
+  }
+  attachEnvironmentListeners() {
+    const target = globalThis.window;
+    if (!target || typeof target.addEventListener !== "function") return () => {
+    };
+    const wake = () => {
+      const doc = globalThis.document;
+      if (doc?.visibilityState === "hidden") return;
+      void this.retryNow().catch(() => void 0);
+    };
+    target.addEventListener("online", wake);
+    target.addEventListener("visibilitychange", wake);
+    return () => {
+      target.removeEventListener?.("online", wake);
+      target.removeEventListener?.("visibilitychange", wake);
+    };
+  }
+  async requireAccessToken() {
+    const token = await this.getAccessToken();
+    if (!token) {
+      throw new AuthError("You must be signed in to perform this action.", "AUTH_REQUIRED");
+    }
+    return token;
+  }
+  /**
+   * Send one request with a timeout and return status plus parsed JSON (if any).
+   * Throws only for transport failures (network, abort, timeout).
+   */
+  async rawRequest(path, options) {
     const url = `${this.serverUrl}${path}`;
     const headers = {};
     if (options.body) {
@@ -566,14 +996,61 @@ var AuthClient = class {
     if (options.token) {
       headers.Authorization = `Bearer ${options.token}`;
     }
+    const controller = typeof AbortController === "function" ? new AbortController() : null;
+    let timer = null;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        controller?.abort();
+        reject(
+          new AuthError(
+            `Request to ${path} timed out after ${this.requestTimeoutMs}ms.`,
+            "AUTH_TIMEOUT",
+            { path }
+          )
+        );
+      }, this.requestTimeoutMs);
+    });
+    try {
+      const response = await Promise.race([
+        this.fetchFn(url, {
+          method: options.method,
+          headers,
+          body: options.body ? JSON.stringify(options.body) : void 0,
+          ...controller ? { signal: controller.signal } : {}
+        }),
+        timeout
+      ]);
+      let json;
+      try {
+        json = await Promise.race([response.json(), timeout]);
+      } catch {
+        json = void 0;
+      }
+      const headerGetter = response.headers;
+      return {
+        status: response.status,
+        ok: response.ok,
+        json,
+        retryAfterMs: parseRetryAfter(headerGetter?.get?.("Retry-After"))
+      };
+    } finally {
+      if (timer !== null) clearTimeout(timer);
+    }
+  }
+  /**
+   * Make an HTTP request to the auth server.
+   *
+   * @param path - URL path relative to serverUrl (e.g. '/auth/signin')
+   * @param options - Request options
+   * @returns Parsed JSON response body
+   * @throws {AuthError} On network failure, timeout, or non-2xx response
+   */
+  async request(path, options) {
     let response;
     try {
-      response = await this.fetchFn(url, {
-        method: options.method,
-        headers,
-        body: options.body ? JSON.stringify(options.body) : void 0
-      });
+      response = await this.rawRequest(path, options);
     } catch (cause) {
+      if (cause instanceof AuthError) throw cause;
       throw new AuthError(
         `Network request to ${path} failed. The auth server at ${this.serverUrl} may be unreachable. Check your network connection and serverUrl configuration.`,
         "AUTH_NETWORK_ERROR",
@@ -583,26 +1060,33 @@ var AuthClient = class {
     if (!response.ok) {
       let errorMessage = `Auth server returned HTTP ${response.status}`;
       let serverError;
-      try {
-        const body = await response.json();
-        if (typeof body.error === "string") {
-          errorMessage = body.error;
+      let serverCode;
+      if (isRecord(response.json)) {
+        if (typeof response.json.error === "string") {
+          errorMessage = response.json.error;
           serverError = errorMessage;
-        } else if (typeof body.message === "string") {
-          errorMessage = body.message;
+        } else if (typeof response.json.message === "string") {
+          errorMessage = response.json.message;
           serverError = errorMessage;
         }
-      } catch {
+        if (typeof response.json.code === "string") serverCode = response.json.code;
       }
       throw new AuthError(errorMessage, "AUTH_SERVER_ERROR", {
         path,
         status: response.status,
-        serverError
+        serverError,
+        serverCode
       });
     }
-    const json = await response.json();
-    const data = json.data !== void 0 ? json.data : json;
-    return data;
+    if (!isRecord(response.json) && !Array.isArray(response.json)) {
+      throw new AuthError(
+        `Auth server returned a non-JSON response for ${path}. A captive portal or proxy may be intercepting requests.`,
+        "AUTH_INVALID_RESPONSE",
+        { path, status: response.status }
+      );
+    }
+    const json = response.json;
+    return json.data !== void 0 ? json.data : json;
   }
 };
 
@@ -940,7 +1424,10 @@ function createKoraAuth(options) {
     storageKey: options.storageKey,
     storage,
     fetch: options.fetch,
-    deviceIdentity
+    deviceIdentity,
+    requestTimeoutMs: options.requestTimeoutMs,
+    maxOfflineGraceMs: options.maxOfflineGraceMs,
+    refreshBackoff: options.refreshBackoff
   });
 }
 function tryCreateDefaultTokenStorage(storageKey) {
@@ -1002,38 +1489,49 @@ function decodeJwtPayload2(token) {
     return null;
   }
 }
-function readDeviceIdFromClaims(claims) {
-  const dev = claims.dev;
-  return typeof dev === "string" && dev.length > 0 ? dev : void 0;
+function readString(claims, key) {
+  const value = claims?.[key];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
 }
 function createKoraAuthSync(options) {
   const { authClient, schema, scopeFromClaims, anonymous = "suspend" } = options;
+  const resolveClaims = async () => {
+    const token = await authClient.getAccessToken();
+    if (token) return { claims: decodeJwtPayload2(token), token };
+    if (authClient.state === "unauthenticated" || !authClient.getStoredClaims) {
+      return { claims: null, token: null };
+    }
+    return { claims: await authClient.getStoredClaims(), token: null };
+  };
   const binding = {
-    auth: async () => {
-      const token = await authClient.getAccessToken();
+    auth: async (request) => {
+      const token = request?.forceRefresh && authClient.refreshAccessToken ? await authClient.refreshAccessToken() : await authClient.getAccessToken();
       return { token: token ?? "" };
     }
   };
   binding.resolveSyncState = async () => {
     if (authClient.state === "loading") return { state: "loading" };
-    const token = await authClient.getAccessToken();
-    if (!token) {
-      return anonymous === "allow" ? { state: "anonymous", mayConnectAnonymously: true } : { state: "signed-out", mayConnectAnonymously: false };
-    }
-    const claims = decodeJwtPayload2(token);
-    const userId = typeof claims?.sub === "string" ? claims.sub : "";
+    const { claims, token } = await resolveClaims();
+    const userId = readString(claims, "sub");
     if (!userId) {
       return anonymous === "allow" ? { state: "anonymous", mayConnectAnonymously: true } : { state: "signed-out", mayConnectAnonymously: false };
     }
-    return { state: "authenticated", userId, token };
+    const deviceId = readString(claims, "dev");
+    if (token) {
+      return { state: "authenticated", userId, token, ...deviceId ? { deviceId } : {} };
+    }
+    return {
+      state: "authenticated",
+      userId,
+      token: null,
+      offline: true,
+      locked: authClient.session?.status === "locked",
+      ...deviceId ? { deviceId } : {}
+    };
   };
   if (schema) {
     binding.resolveScopeMap = async () => {
-      const token = await authClient.getAccessToken();
-      if (!token) {
-        return void 0;
-      }
-      const claims = decodeJwtPayload2(token);
+      const { claims } = await resolveClaims();
       if (!claims) {
         return void 0;
       }
@@ -1042,30 +1540,24 @@ function createKoraAuthSync(options) {
     };
   }
   binding.resolveNodeId = async () => {
-    const token = await authClient.getAccessToken();
-    if (!token) {
-      return void 0;
-    }
-    const claims = decodeJwtPayload2(token);
-    if (!claims) {
-      return void 0;
-    }
-    return readDeviceIdFromClaims(claims);
+    const { claims } = await resolveClaims();
+    return readString(claims, "dev");
   };
   binding.resolveUserId = async () => {
-    const token = await authClient.getAccessToken();
-    if (!token) {
-      return void 0;
-    }
-    const claims = decodeJwtPayload2(token);
-    if (!claims || typeof claims.sub !== "string" || claims.sub.length === 0) {
-      return void 0;
-    }
-    return claims.sub;
+    const { claims } = await resolveClaims();
+    return readString(claims, "sub");
   };
-  if (authClient.onAuthChange) {
-    binding.subscribe = (listener) => authClient.onAuthChange?.(() => listener()) ?? (() => {
-    });
+  if (authClient.onAuthChange || authClient.onSessionChange) {
+    binding.subscribe = (listener) => {
+      const offAuth = authClient.onAuthChange?.(() => listener()) ?? (() => {
+      });
+      const offSession = authClient.onSessionChange?.(() => listener()) ?? (() => {
+      });
+      return () => {
+        offAuth();
+        offSession();
+      };
+    };
   }
   return binding;
 }
@@ -1248,10 +1740,11 @@ var OrgClient = class {
     await this.request(`/orgs/${orgId}/invitations/${invitationId}`, { method: "DELETE" });
   }
   /**
-   * List pending invitations for the current user's email.
+   * List pending invitations addressed to the signed-in user's verified email.
+   * The server resolves the email from the session; tokens are never returned.
    */
-  async listMyInvitations(email) {
-    return this.request(`/invitations?email=${encodeURIComponent(email)}`, {
+  async listMyInvitations() {
+    return this.request("/invitations", {
       method: "GET"
     });
   }
@@ -1843,6 +2336,7 @@ export {
   InMemoryDeviceKeyStore,
   IndexedDBDeviceKeyStore,
   KeyDerivationError,
+  MfaRequiredError,
   OperationEncryptionError,
   OperationEncryptor,
   OrgClient,