Merge pull request #268 from quarto-dev/bugfix/bd-3o8zmz46-ws-auth-expiry

fix(bd-3o8zmz46): evidence-based session expiry handling in hub-client

Author: shikokuchuo

claude-notes/plans/2026-06-10-ws-auth-expiry-handling.md

@@ -0,0 +1,106 @@
+# WS auth-expiry handling (bd-3o8zmz46)
+
+## Overview
+
+Diagnosed 2026-06-10: when the Google ID token (1 h `exp`) expires and GIS One
+Tap renewal is unavailable (observed `accounts.google.com/gsi/status` 403 in
+dev), the auth cookie is evicted by the browser and every Automerge WS upgrade
+gets 401 from the hub. The SPA never notices:
+
+- Browsers hide the HTTP status of a failed WS upgrade from JS, and nothing
+  probes `/auth/me` out-of-band when sync drops.
+- `useAuth`'s visibilitychange handler resets `cookieSetAt = Date.now()` on
+  every refocus where `/auth/me` still returns 200, drifting the assumed
+  expiry up to an hour past the real one, so the `cookieExpired()` guards and
+  the App's auth-lost effect never fire.
+
+Net effect: UI stays "logged in", shows "Connection lost — working offline",
+and the WS adapter retries forever.
+
+Evidence record (end-to-end): probed `ws://localhost:5173/ws` (Vite proxy)
+and `http://127.0.0.1:3000/ws` directly → both 401; user's DevTools showed
+the failing upgrades carry **no Cookie header** (cookie evicted at expiry);
+`fetch('/auth/me')` → 401 while the editor remained open; page reload landed
+on the login screen.
+
+**Offline-mode invariant (drives all fixes):** only a definitive 401/403 from
+a reachable hub may clear auth. Network errors, timeouts, and 5xx must never
+log the user out — offline editing is a feature. Logout on evidence, not on
+schedule.
+
+Related: bd-ey6jg70f (hub-minted sliding sessions, out of scope here).
+
+## Phase 1 — server: expose token expiry on /auth/me
+
+- [x] Failing test: `/auth/me` response includes `exp` (epoch seconds) equal
+      to the token's `exp` claim
+- [x] Surface `exp` in `OidcClaims` (if not already deserialized) and add it
+      to `AuthMeResponse` in `crates/quarto-hub/src/server.rs`
+- [x] Targeted tests pass (`cargo nextest run -p quarto-hub`)
+
+## Phase 2 — client: schedule from real expiry; offline-safe catches
+
+- [x] Failing tests (vitest, fake timers) for `useAuth`:
+  - schedules silent refresh at `exp − 15 min` and hard re-check at `exp`,
+    from the server-reported `exp` (not a local 1 h assumption)
+  - refocus `/auth/me` 200 does NOT extend assumed expiry beyond server `exp`
+    (the drift bug)
+  - refocus `/auth/me` network error keeps auth (today: logs out)
+  - expiry-time `/auth/me` network error keeps auth and reschedules a
+    re-check (today: logs out)
+  - expiry-time `/auth/me` 401 with failed renewal → auth cleared with
+    `sessionExpired` flag
+- [x] Implement: `AuthState.expiresAt` (from `exp`, fallback +1 h if absent),
+      remove `cookieSetAt` drift resets, offline-safe catch branches,
+      `sessionExpired` state exposed from the hook
+- [x] Targeted vitest run green
+
+## Phase 3 — client: WS-failure auth probe + session-expired UX
+
+- [x] Failing tests for new `useAuthProbe` hook:
+  - while sync is disconnected (and authed, project open): probes
+    `/auth/me` immediately and then on an interval
+  - probe 200 → no action; probe network error → no action (offline mode)
+  - first 401/403 → `triggerRefresh()` only (renewal gets a chance)
+  - second consecutive 401/403 → `onAuthRejected()` (clears auth)
+  - reconnect / 200 resets the strike counter; probing stops when online
+- [x] Implement `useAuthProbe`, wire in `App.tsx` off `isOnline`
+- [x] LoginScreen shows "Session expired — please sign in again" when auth
+      was cleared by evidence (distinct from the generic offline banner and
+      from ordinary logout)
+- [x] Targeted vitest run green
+
+## Phase 4 — verification & bookkeeping
+
+- [x] `npm run build:all` from hub-client (production build is stricter)
+- [x] `npm run test:ci` from hub-client
+- [x] `cargo xtask verify` (full: quarto-hub Rust change + hub-client change)
+- [x] Commits (hub-client two-commit changelog dance), strand comment + close
+- [x] Honest E2E note: real-expiry flow needs a browser with a live Google
+      session; record what was and wasn't exercised end-to-end
+
+## Design details
+
+- Probe three-way split maps directly onto `fetchAuthMe()`'s contract:
+  `AuthState` = valid, `null` = definitive 401/403, throw = network/5xx.
+- Strike-2 semantics: first 401 triggers renewal; only a second 401 on the
+  next probe cycle (~30 s later) clears auth. Avoids racing One Tap and
+  avoids relying on One Tap callbacks ever firing (they may not when GIS is
+  blocked — the coalesced `isRefreshing` flag would otherwise wedge).
+- Cold-starting the app while fully offline still lands on login (mount-time
+  probe can't succeed; HttpOnly cookie unreadable client-side). Known
+  limitation, unchanged by this strand; belongs to bd-ey6jg70f territory.
+
+## Verification record (2026-06-10)
+
+- `cargo xtask verify` (full): 9648 Rust tests passed; hub-client 574 unit +
+  66 integration + 81 wasm tests passed; WASM + production builds green.
+- New tests: `auth_me_returns_token_exp` (Rust); 5 expiry/offline tests in
+  `useAuth.test.tsx`; 6 tests in `useAuthProbe.test.tsx`; 2 LoginScreen tests.
+- Commits: `465de01f` (fix), `329e3702` (changelog).
+- **E2E honesty note**: the real expiry flow (Google token aging past 1 h with
+  One Tap blocked) was NOT exercised end-to-end in a browser — it needs a live
+  Google session. Manual recipe: sign in, delete the `quarto_hub_token` cookie
+  in DevTools → Application, restart the hub (drops the established WS); the
+  client should attempt renewal within ~30 s and land on the login screen with
+  the "session expired" message within ~60 s, instead of retrying forever.

crates/quarto-hub/src/auth.rs

@@ -195,6 +195,13 @@ pub struct OidcClaims {
     /// [`validate_azp_and_iat`]).
     #[serde(default)]
     pub iat: Option<i64>,
+
+    /// Expiry (epoch seconds). Required by the validator
+    /// (`set_required_spec_claims`), so always present in accepted
+    /// tokens; surfaced on `/auth/me` so the client can schedule
+    /// refresh from the real expiry (bd-3o8zmz46).
+    #[serde(default)]
+    pub exp: i64,
 }
 
 /// Accept either a single-string `aud` or a `["a", "b"]` array.
@@ -709,6 +716,7 @@ mod tests {
             aud: vec!["test-client-id".to_string()],
             azp: None,
             iat: None,
+            exp: 0,
         }
     }
 
@@ -947,6 +955,7 @@ mod tests {
             aud: vec!["spa-client".into()],
             azp: None,
             iat: None,
+            exp: 0,
         };
         let allowed = allowed_list();
         assert!(validate_azp_and_iat(&claims, allowed.iter(), 1_000_000, 60).is_ok());
@@ -963,6 +972,7 @@ mod tests {
             aud: vec!["spa-client".into(), "mcp-client".into()],
             azp: None,
             iat: None,
+            exp: 0,
         };
         let allowed = allowed_list();
         assert_eq!(
@@ -982,6 +992,7 @@ mod tests {
             aud: vec!["spa-client".into()],
             azp: Some("attacker-client".into()),
             iat: None,
+            exp: 0,
         };
         let allowed = allowed_list();
         assert_eq!(
@@ -1001,6 +1012,7 @@ mod tests {
             aud: vec!["spa-client".into(), "mcp-client".into()],
             azp: Some("spa-client".into()),
             iat: None,
+            exp: 0,
         };
         let allowed = allowed_list();
         assert!(validate_azp_and_iat(&claims, allowed.iter(), 1_000_000, 60).is_ok());
@@ -1017,6 +1029,7 @@ mod tests {
             aud: vec!["spa-client".into()],
             azp: None,
             iat: Some(1_000_000 + 3600),
+            exp: 0,
         };
         let allowed = allowed_list();
         assert_eq!(
@@ -1036,6 +1049,7 @@ mod tests {
             aud: vec!["spa-client".into()],
             azp: None,
             iat: Some(1_000_000 + 30),
+            exp: 0,
         };
         let allowed = allowed_list();
         assert!(validate_azp_and_iat(&claims, allowed.iter(), 1_000_000, 60).is_ok());

crates/quarto-hub/src/server.rs

@@ -733,6 +733,9 @@ struct AuthMeResponse {
     email: String,
     name: Option<String>,
     picture: Option<String>,
+    /// Token expiry (epoch seconds) so the client can schedule silent
+    /// refresh from the real expiry instead of assuming a fixed lifetime.
+    exp: i64,
 }
 
 /// Query parameters for GET /auth/actor.
@@ -770,6 +773,7 @@ async fn auth_me(
         email: claims.email,
         name: claims.name,
         picture: claims.picture,
+        exp: claims.exp,
     }))
 }
 

crates/quarto-hub/tests/auth_bearer.rs

@@ -1002,6 +1002,33 @@ async fn cookie_still_authenticates() {
     assert_eq!(resp.status(), 200);
 }
 
+// ── /auth/me reports token expiry (bd-3o8zmz46) ──────────────────
+
+#[tokio::test]
+async fn auth_me_returns_token_exp() {
+    let (provider, hub) = shared_setup().await;
+    let exp = chrono::Utc::now().timestamp() + 600;
+    let token = provider.sign(
+        &ClaimsBuilder::from_provider(provider)
+            .sub("auth-me-exp")
+            .exp(exp)
+            .to_value(),
+    );
+
+    let resp = hub
+        .get_auth_me()
+        .header("cookie", format!("quarto_hub_token={token}"))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), 200);
+    let body: serde_json::Value = resp.json().await.unwrap();
+    assert_eq!(
+        body["exp"], exp,
+        "client schedules refresh from the real token expiry"
+    );
+}
+
 // ── Dual-credential 400 (bd-wzhsf CVE) ───────────────────────────
 
 #[tokio::test]

hub-client/changelog.md

@@ -15,6 +15,10 @@ be in reverse chronological order (latest first).
 
 -->
 
+### 2026-06-10
+
+- [`465de01f`](https://github.com/quarto-dev/q2/commits/465de01f): An expired sign-in no longer presents as a permanent "working offline" state — the client now detects the rejected session, attempts silent renewal, and returns to the login screen with a "session expired" message; genuine network outages keep offline editing intact.
+
 ### 2026-06-09
 
 - [`57bc49cf`](https://github.com/quarto-dev/q2/commits/57bc49cf): Preview renders no longer re-copy unchanged artifacts (theme CSS, fonts, shared JS) into the virtual filesystem on every keystroke — byte-identical re-writes are now skipped.

hub-client/src/App.tsx

@@ -34,6 +34,7 @@ import { getUserIdentity, updateUserName } from './services/userSettings';
 import { useRouting } from './hooks/useRouting';
 import { useProjectSet } from './hooks/useProjectSet';
 import { useAuth } from './hooks/useAuth';
+import { useAuthProbe } from './hooks/useAuthProbe';
 import { fetchActorId } from './services/authService';
 import type { Route, ShareRoute, LinkProjectSetRoute } from './utils/routing';
 import './App.css';
@@ -63,7 +64,14 @@ const AUTH_ENABLED = !!import.meta.env.VITE_GOOGLE_CLIENT_ID;
 
 
 function App() {
-  const { auth, loading: authLoading, logout, triggerRefresh } = useAuth();
+  const {
+    auth,
+    loading: authLoading,
+    logout,
+    triggerRefresh,
+    sessionExpired,
+    expireSession,
+  } = useAuth();
 
   const [project, setProject] = useState<ProjectEntry | null>(null);
   const [files, setFiles] = useState<FileEntry[]>([]);
@@ -76,6 +84,17 @@ function App() {
   const [identities, setIdentities] = useState<Record<string, ActorIdentity>>({});
   const [isOnline, setIsOnline] = useState<boolean>(false);
 
+  // While a project's sync is disconnected, check whether the disconnect is
+  // actually an auth rejection (browsers hide the WS upgrade status). Only
+  // definitive 401/403 evidence ever clears auth — never network errors.
+  // Past the token's exp, useAuth's expiry timer logs out on the first 401
+  // (preempting this probe's two-strike); the probe governs earlier drops.
+  useAuthProbe({
+    enabled: AUTH_ENABLED && !!auth && !!project && !isOnline,
+    triggerRefresh,
+    onAuthRejected: expireSession,
+  });
+
   // Project set management (synced project list)
   const [projectSetState, projectSetActions] = useProjectSet();
 
@@ -551,7 +570,12 @@ function App() {
   }
 
   if (AUTH_ENABLED && !auth) {
-    return <LoginScreen error={authError} />;
+    return (
+      <LoginScreen
+        error={authError}
+        message={sessionExpired ? 'Your session expired — please sign in again.' : undefined}
+      />
+    );
   }
 
   // Gate on screen name being loaded (fast IndexedDB read).

hub-client/src/components/auth/LoginScreen.test.tsx

@@ -49,4 +49,16 @@ describe('LoginScreen', () => {
     expect(screen.getByText(/Sign-in failed/i)).toBeTruthy();
     expect(screen.queryByText(/Sign in with Google to continue/i)).toBeNull();
   });
+
+  it('renders a custom message (session expiry) instead of the default copy', () => {
+    render(withProvider(<LoginScreen message="Your session expired — please sign in again." />));
+    expect(screen.getByText(/session expired/i)).toBeTruthy();
+    expect(screen.queryByText(/Sign in with Google to continue/i)).toBeNull();
+  });
+
+  it('error copy wins over a custom message', () => {
+    render(withProvider(<LoginScreen error message="Your session expired — please sign in again." />));
+    expect(screen.getByText(/Sign-in failed/i)).toBeTruthy();
+    expect(screen.queryByText(/session expired/i)).toBeNull();
+  });
 });

hub-client/src/components/auth/LoginScreen.tsx

@@ -13,7 +13,7 @@
 
 import { useAuthProvider } from '../../auth/AuthProvider';
 
-export function LoginScreen({ error }: { error?: boolean }) {
+export function LoginScreen({ error, message }: { error?: boolean; message?: string }) {
   const provider = useAuthProvider();
 
   return (
@@ -25,6 +25,10 @@ export function LoginScreen({ error }: { error?: boolean }) {
           <p style={{ color: 'var(--posit-red)', fontSize: '14px', margin: '0 0 16px' }}>
             Sign-in failed. Your account is not authorized to access this hub.
           </p>
+        ) : message ? (
+          <p style={{ color: 'var(--text-secondary)', fontSize: '14px', margin: '0 0 16px' }}>
+            {message}
+          </p>
         ) : (
           <p style={{ color: 'var(--text-secondary)', fontSize: '14px', margin: '0 0 16px' }}>
             Sign in with Google to continue