feat(auth): client-side idle-session timeout (AUTH-1 slice 1) (#675)

The Authentication-policy 'Idle timeout' had no observable effect in the
browser: the backend measures idle by HTTP request activity and slides the
session window on every authenticated request, but the SPA polls several
endpoints every 15-60s and holds a persistent SSE stream, so the window never
elapsed even when the user walked away.

Add useIdleLogout, mounted from AppFrame (the authenticated shell), which
measures REAL user input (pointer/keyboard/touch) instead of HTTP traffic.
On inactivity for the configured window it revokes the session
(POST /api/v1/auth/logout) and returns to /login. The window is read from
GET /api/v1/auth-policy with a 15-minute safe default (matching the backend),
and the activity clock is shared across tabs via localStorage so one active
tab keeps all alive.

New spec frontend-session-idle (5 ACs, 6 tests). Does NOT yet address the
absolute-timeout ceiling in the refresh-cookie path or server-side
slide-on-user-activity hardening (AUTH-1 slices b/c).

Author: remyluslosius

frontend/src/components/shell/AppFrame.tsx

@@ -4,10 +4,11 @@ import { Sidebar } from './Sidebar';
 import { TopBar } from './TopBar';
 import { ErrorBoundary } from './ErrorBoundary';
 import { usePreferencesStore } from '@/store/usePreferencesStore';
+import { useIdleLogout } from '@/hooks/useIdleLogout';
 
 // AppFrame — the persistent shell that wraps every authenticated route.
 //
-// Spec: frontend-foundation C-08, C-09, AC-10.
+// Spec: frontend-foundation C-08, C-09, AC-10; frontend-session-idle.
 
 export function AppFrame() {
   // Reconcile per-user UI preferences with the server once the
@@ -18,6 +19,11 @@ export function AppFrame() {
     void hydratePreferences();
   }, [hydratePreferences]);
 
+  // Enforce the operator-configured idle timeout against REAL user activity
+  // (background polling slides the server-side window, so a client timer is
+  // what actually terminates an unattended session). Spec frontend-session-idle.
+  useIdleLogout();
+
   return (
     <div
       style={{

frontend/src/hooks/useIdleLogout.ts

@@ -0,0 +1,148 @@
+import { useEffect, useRef } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { api, onAuthFailure } from '@/api/client';
+import { useAuthStore } from '@/store/useAuthStore';
+
+// useIdleLogout — client-side inactivity timeout.
+//
+// WHY this exists (and why the server-side window is not enough): the backend
+// enforces the configured idle window in internal/identity/sessions.go, but it
+// measures "idle" by HTTP request activity. The SPA polls several endpoints
+// every 15-60s and holds a persistent SSE stream, so every background request
+// slides the server's expires_at forward — the session never goes idle even
+// when the human has walked away. This hook measures REAL user activity
+// (pointer / keyboard / touch), so the Authentication-policy "Idle timeout"
+// setting actually terminates an unattended session and returns to /login.
+//
+// It reads the operator-configured window from GET /api/v1/auth-policy and
+// falls back to the backend default (15 min) when that can't be read — failing
+// toward enforcing a timeout rather than leaving the session open forever.
+//
+// Mounted once from AppFrame (the authenticated shell), so it is armed only
+// while a user is signed in.
+//
+// Spec: frontend-session-idle.
+
+// Matches DefaultSessionInactivityWindow in internal/identity/sessions.go.
+const DEFAULT_IDLE_SECONDS = 15 * 60;
+
+// Shared "last user activity" timestamp (epoch ms) across tabs of the same
+// origin. Activity in any tab keeps every tab's session alive; without this a
+// background tab would log the user out while they work in another.
+export const ACTIVITY_STORAGE_KEY = 'ow.session.lastActivity';
+
+// How often we re-check elapsed idle time. This is the granularity of the
+// check, not the timeout itself.
+const CHECK_INTERVAL_MS = 5_000;
+
+// Throttle how often raw activity events rewrite the shared timestamp so a
+// burst of mousemove events is cheap.
+const ACTIVITY_WRITE_THROTTLE_MS = 1_000;
+
+// Real user-input signals only. Deliberately NOT HTTP/visibility driven — the
+// whole point is to ignore background traffic and tab focus.
+const ACTIVITY_EVENTS: readonly string[] = [
+  'mousemove',
+  'mousedown',
+  'keydown',
+  'wheel',
+  'scroll',
+  'touchstart',
+];
+
+function readLastActivity(fallback: number): number {
+  try {
+    const raw = localStorage.getItem(ACTIVITY_STORAGE_KEY);
+    const n = raw ? Number(raw) : NaN;
+    if (Number.isFinite(n)) return n;
+  } catch {
+    /* localStorage unavailable (private mode / SSR) — use the fallback */
+  }
+  return fallback;
+}
+
+export function useIdleLogout(): void {
+  const identity = useAuthStore((s) => s.identity);
+
+  const { data: policy } = useQuery({
+    queryKey: ['auth-policy'],
+    queryFn: async () => {
+      const { data, error, response } = await api.GET('/api/v1/auth-policy');
+      if (error || !response.ok) throw new Error('failed to load auth policy');
+      return data!;
+    },
+    // The window changes rarely; one fetch per shell mount is plenty. A short
+    // refetch interval would itself be background traffic, which is the very
+    // thing this hook exists to stop counting as activity.
+    staleTime: 5 * 60 * 1000,
+  });
+
+  const idleSeconds = policy?.session_idle_timeout_seconds ?? DEFAULT_IDLE_SECONDS;
+
+  // Hold the latest window in a ref so a policy change does not tear down and
+  // rebuild the listeners/interval.
+  const idleMsRef = useRef(idleSeconds * 1000);
+  idleMsRef.current = idleSeconds * 1000;
+
+  useEffect(() => {
+    // Arm only while authenticated.
+    if (!identity) return;
+
+    let lastWrite = 0;
+    let loggingOut = false;
+
+    const markActivity = (): void => {
+      const t = Date.now();
+      if (t - lastWrite < ACTIVITY_WRITE_THROTTLE_MS) return;
+      lastWrite = t;
+      try {
+        localStorage.setItem(ACTIVITY_STORAGE_KEY, String(t));
+      } catch {
+        /* ignore — readLastActivity falls back to lastWrite via the closure */
+      }
+    };
+
+    const logout = async (): Promise<void> => {
+      if (loggingOut) return;
+      loggingOut = true;
+      // Best-effort server-side revoke so the cookie session is actually dead,
+      // not merely hidden from this tab. Redirect regardless of the result.
+      try {
+        await api.POST('/api/v1/auth/logout');
+      } catch {
+        /* ignore — we still clear the client and redirect */
+      }
+      try {
+        localStorage.removeItem(ACTIVITY_STORAGE_KEY);
+      } catch {
+        /* ignore */
+      }
+      onAuthFailure();
+    };
+
+    const check = (): void => {
+      if (loggingOut) return;
+      const last = readLastActivity(lastWrite || Date.now());
+      if (Date.now() - last >= idleMsRef.current) {
+        void logout();
+      }
+    };
+
+    // Seed an initial timestamp so a freshly-mounted shell is not treated as
+    // already idle.
+    lastWrite = 0;
+    markActivity();
+
+    for (const ev of ACTIVITY_EVENTS) {
+      window.addEventListener(ev, markActivity, { passive: true });
+    }
+    const interval = window.setInterval(check, CHECK_INTERVAL_MS);
+
+    return () => {
+      window.clearInterval(interval);
+      for (const ev of ACTIVITY_EVENTS) {
+        window.removeEventListener(ev, markActivity);
+      }
+    };
+  }, [identity]);
+}

frontend/tests/hooks/useIdleLogout.test.tsx

@@ -0,0 +1,176 @@
+// @spec frontend-session-idle
+//
+// AC traceability (this file):
+//
+//   AC-01  test('frontend-session-idle/AC-01 — idle past the window logs out (revoke + redirect)')
+//   AC-02  test('frontend-session-idle/AC-02 — user input before the window resets the clock')
+//   AC-03  test('frontend-session-idle/AC-03 — honors the configured window; falls back to 15m default')
+//   AC-04  test('frontend-session-idle/AC-04 — a fresher cross-tab timestamp prevents logout')
+//   AC-05  test('frontend-session-idle/AC-05 — AppFrame mounts the hook; listeners are user-input only')
+
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { ReactNode } from 'react';
+
+import { api, onAuthFailure } from '@/api/client';
+import { ACTIVITY_STORAGE_KEY, useIdleLogout } from '@/hooks/useIdleLogout';
+import { useAuthStore } from '@/store/useAuthStore';
+
+vi.mock('@/api/client', () => ({
+  api: { GET: vi.fn(), POST: vi.fn() },
+  onAuthFailure: vi.fn(),
+}));
+
+const mockedGet = vi.mocked(api.GET);
+const mockedPost = vi.mocked(api.POST);
+const mockedAuthFailure = vi.mocked(onAuthFailure);
+
+const T0 = new Date('2026-01-01T00:00:00Z').getTime();
+
+// Policy GET result helpers (the openapi-fetch result shape).
+function policyOk(idleSeconds: number) {
+  return {
+    data: {
+      require_mfa: false,
+      session_idle_timeout_seconds: idleSeconds,
+      session_absolute_timeout_seconds: 43200,
+      updated_at: '2026-01-01T00:00:00Z',
+    },
+    error: undefined,
+    response: { ok: true } as Response,
+  };
+}
+function policyFail() {
+  return { data: undefined, error: { code: 'x' }, response: { ok: false } as Response };
+}
+
+function wrapper({ children }: { children: ReactNode }) {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return <QueryClientProvider client={qc}>{children}</QueryClientProvider>;
+}
+
+// Render the hook and let the auth-policy query settle so idleMsRef is primed.
+async function mount() {
+  const view = renderHook(() => useIdleLogout(), { wrapper });
+  await act(async () => {
+    await vi.advanceTimersByTimeAsync(0);
+  });
+  return view;
+}
+
+async function advance(ms: number) {
+  await act(async () => {
+    await vi.advanceTimersByTimeAsync(ms);
+  });
+}
+
+describe('frontend-session-idle — client idle logout', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(T0);
+    mockedGet.mockReset();
+    mockedPost.mockReset();
+    mockedAuthFailure.mockReset();
+    mockedPost.mockResolvedValue({ data: {}, error: undefined, response: { ok: true } } as never);
+    try {
+      localStorage.clear();
+    } catch {
+      /* ignore */
+    }
+    useAuthStore.getState().setIdentity({
+      id: 'u1',
+      username: 'alice',
+      email: 'alice@example.com',
+      role: 'admin',
+      permissions: [],
+      mfaEnabled: false,
+    });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    useAuthStore.getState().clear();
+  });
+
+  // @ac AC-01
+  test('frontend-session-idle/AC-01 — idle past the window logs out (revoke + redirect)', async () => {
+    mockedGet.mockResolvedValue(policyOk(60) as never);
+    await mount();
+
+    // No activity for 65s (> 60s window) → revoke + redirect.
+    await advance(65_000);
+
+    expect(mockedPost).toHaveBeenCalledWith('/api/v1/auth/logout');
+    expect(mockedAuthFailure).toHaveBeenCalledTimes(1);
+  });
+
+  // @ac AC-02
+  test('frontend-session-idle/AC-02 — user input before the window resets the clock', async () => {
+    mockedGet.mockResolvedValue(policyOk(60) as never);
+    await mount();
+
+    // Sit idle for 50s, then the user presses a key (resets the clock).
+    await advance(50_000);
+    act(() => {
+      window.dispatchEvent(new Event('keydown'));
+    });
+    // 50s more: 50s since the keypress (< 60s) → still NOT logged out.
+    await advance(50_000);
+
+    expect(mockedAuthFailure).not.toHaveBeenCalled();
+    expect(mockedPost).not.toHaveBeenCalled();
+  });
+
+  // @ac AC-03
+  test('frontend-session-idle/AC-03 — honors the configured window; falls back to 15m default', async () => {
+    // Configured short window: fires at the configured value, not before.
+    mockedGet.mockResolvedValue(policyOk(120) as never);
+    await mount();
+    await advance(100_000); // < 120s
+    expect(mockedAuthFailure).not.toHaveBeenCalled();
+    await advance(30_000); // now > 120s
+    expect(mockedAuthFailure).toHaveBeenCalledTimes(1);
+  });
+
+  // @ac AC-03
+  test('frontend-session-idle/AC-03b — policy unavailable falls back to the 15-minute default', async () => {
+    mockedGet.mockResolvedValue(policyFail() as never);
+    await mount();
+    // 5 minutes idle is well past a short window but under the 15-min default →
+    // must NOT log out (proves the safe default, not a 0/immediate timeout).
+    await advance(5 * 60_000);
+    expect(mockedAuthFailure).not.toHaveBeenCalled();
+  });
+
+  // @ac AC-04
+  test('frontend-session-idle/AC-04 — a fresher cross-tab timestamp prevents logout', async () => {
+    mockedGet.mockResolvedValue(policyOk(60) as never);
+    await mount();
+
+    // This tab sees no local input, but another tab records activity by writing
+    // the shared key. Keep it fresh across the window.
+    for (let i = 0; i < 6; i++) {
+      localStorage.setItem(ACTIVITY_STORAGE_KEY, String(Date.now()));
+      await advance(20_000); // 20s < 60s window each step
+    }
+
+    expect(mockedAuthFailure).not.toHaveBeenCalled();
+    expect(mockedPost).not.toHaveBeenCalled();
+  });
+
+  // @ac AC-05
+  test('frontend-session-idle/AC-05 — AppFrame mounts the hook; listeners are user-input only', () => {
+    const appFrame = readFileSync(resolve(__dirname, '../../src/components/shell/AppFrame.tsx'), 'utf8');
+    expect(appFrame).toContain('useIdleLogout');
+
+    const hook = readFileSync(resolve(__dirname, '../../src/hooks/useIdleLogout.ts'), 'utf8');
+    for (const ev of ['mousemove', 'mousedown', 'keydown', 'wheel', 'scroll', 'touchstart']) {
+      expect(hook).toContain(`'${ev}'`);
+    }
+    // Tab focus / visibility and background HTTP must NOT count as activity.
+    expect(hook).not.toContain('visibilitychange');
+  });
+});