feat(admin-web): proactively refresh access tokens before expiry

Track access token expires_at, dedupe concurrent refreshes, retry SSE on
401, and refresh on window focus/visibility so long-lived sessions stop
hitting the login redirect mid-task.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

apps/admin-web/src/lib/api.ts

@@ -115,6 +115,7 @@ import {
   clearStoredSession,
   getStoredAccessToken,
   getStoredRefreshToken,
+  readStoredSession,
   setStoredTokens,
 } from "./session";
 import {
@@ -126,8 +127,10 @@ import {
 
 const baseURL = import.meta.env.VITE_API_BASE_URL ?? "";
 const generationStreamEnabled = import.meta.env.VITE_GENERATION_STREAM_ENABLED === "true";
+const accessRefreshSkewMs = 2 * 60 * 1000;
 
 const publicClient = createApiClient({ baseURL });
+let storedRefreshPromise: Promise<AuthTokens> | null = null;
 
 export function getApiBaseURL(): string {
   if (baseURL) {
@@ -157,24 +160,88 @@ export function resolveApiURL(value?: string | null): string {
   return new URL(trimmed, apiBaseURL.endsWith("/") ? apiBaseURL : `${apiBaseURL}/`).toString();
 }
 
+function toAuthTokens(data: RefreshResponse): AuthTokens {
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token,
+    expiresAt: data.expires_at,
+  };
+}
+
+function authRequiredError(): ApiClientError {
+  return new ApiClientError({
+    message: "not_authenticated",
+    code: 40100,
+    status: 401,
+  });
+}
+
+function expireStoredSession(): void {
+  clearStoredSession({ notifyAuthExpired: true });
+}
+
+export function shouldRefreshAccessToken(
+  expiresAt: number | null,
+  minRemainingMs = accessRefreshSkewMs,
+): boolean {
+  return !expiresAt || expiresAt * 1000 - Date.now() <= minRemainingMs;
+}
+
+export async function refreshStoredAuthSession(refreshToken = getStoredRefreshToken()): Promise<AuthTokens> {
+  if (!refreshToken) {
+    expireStoredSession();
+    throw authRequiredError();
+  }
+
+  if (!storedRefreshPromise) {
+    storedRefreshPromise = publicClient
+      .post<RefreshResponse, { refresh_token: string }>("/api/auth/refresh", {
+        refresh_token: refreshToken,
+      })
+      .then((data) => {
+        const tokens = toAuthTokens(data);
+        setStoredTokens(tokens);
+        return tokens;
+      })
+      .catch((error) => {
+        expireStoredSession();
+        throw error;
+      })
+      .finally(() => {
+        storedRefreshPromise = null;
+      });
+  }
+
+  return storedRefreshPromise;
+}
+
+async function getFreshStoredAccessToken(): Promise<string> {
+  const snapshot = readStoredSession();
+
+  if (snapshot.refreshToken && shouldRefreshAccessToken(snapshot.accessTokenExpiresAt)) {
+    return (await refreshStoredAuthSession(snapshot.refreshToken)).accessToken;
+  }
+
+  if (snapshot.accessToken) {
+    return snapshot.accessToken;
+  }
+
+  if (snapshot.refreshToken) {
+    return (await refreshStoredAuthSession(snapshot.refreshToken)).accessToken;
+  }
+
+  expireStoredSession();
+  throw authRequiredError();
+}
+
 export const apiClient = createApiClient({
   baseURL,
   auth: {
     getAccessToken: getStoredAccessToken,
     getRefreshToken: getStoredRefreshToken,
     setTokens: setStoredTokens,
-    clearTokens: clearStoredSession,
-    async refresh(refreshToken: string): Promise<AuthTokens> {
-      const data = await publicClient.post<RefreshResponse, { refresh_token: string }>(
-        "/api/auth/refresh",
-        { refresh_token: refreshToken },
-      );
-
-      return {
-        accessToken: data.access_token,
-        refreshToken: data.refresh_token,
-      };
-    },
+    clearTokens: expireStoredSession,
+    refresh: refreshStoredAuthSession,
   },
 });
 
@@ -182,6 +249,7 @@ export const authApi = {
   login(payload: LoginRequest) {
     return publicClient.post<LoginResponse, LoginRequest>("/api/auth/login", payload);
   },
+  refresh: refreshStoredAuthSession,
   me() {
     return apiClient.get<UserInfo>("/api/auth/me");
   },
@@ -710,23 +778,37 @@ async function subscribeSSE<TEvent extends SSEEventShape>(
   },
   signal: AbortSignal,
 ): Promise<void> {
-  const accessToken = getStoredAccessToken();
-  if (!accessToken) {
-    throw new Error("missing access token");
-  }
-
   const requestHeaders = new Headers(init.headers);
   requestHeaders.set("Accept", "text/event-stream");
-  requestHeaders.set("Authorization", `Bearer ${accessToken}`);
+  requestHeaders.set("Authorization", `Bearer ${await getFreshStoredAccessToken()}`);
 
-  const response = await fetch(`${baseURL}${path}`, {
+  let response = await fetch(`${baseURL}${path}`, {
     ...init,
     headers: requestHeaders,
     signal,
   });
 
+  if (response.status === 401) {
+    try {
+      const tokens = await refreshStoredAuthSession();
+      requestHeaders.set("Authorization", `Bearer ${tokens.accessToken}`);
+      response = await fetch(`${baseURL}${path}`, {
+        ...init,
+        headers: requestHeaders,
+        signal,
+      });
+    } catch (error) {
+      expireStoredSession();
+      throw error;
+    }
+  }
+
   if (!response.ok) {
-    throw await buildSSERequestError(response);
+    const error = await buildSSERequestError(response);
+    if (response.status === 401) {
+      expireStoredSession();
+    }
+    throw error;
   }
   if (!response.body) {
     throw new Error("stream response body is empty");