From 907f45bd2ffc57f71aaee537c469d6ec40ac9812 Mon Sep 17 00:00:00 2001
From: cosmin chauciuc <kosmin@cosmins-MacBook-Pro.local>
Date: Fri, 5 Jun 2026 13:42:31 +0300
Subject: [PATCH] Phase 1 frontend: login flow, auth context, workspace
 switcher
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Frontend half of Phase 1, built against the new auth API. Session is an
HTTP-only cookie, so the client never handles tokens — it sends credentials
and derives auth state from /auth/me.

- client.ts: withCredentials, X-Workspace-Id request header, global 401 ->
  drop-session handler (auth endpoints excluded to avoid loops)
- AuthContext + useAuth: loads /auth/me, exposes user/workspaces/role,
  active-workspace selection (persisted), refresh/logout, query-cache reset
  on workspace switch + logout
- LoginPage: provider-aware (password + register toggle, magic-link), dev
  token surfaced for local magic-link; MagicLinkVerifyPage for /login/verify
- ProtectedRoute guard; App.tsx public /login + /login/verify, app routes
  gated behind auth
- AppLayout header: workspace switcher, role badge, account menu with sign-out
- authApi client + auth types

Builds (tsc + vite) and lints clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 frontend/src/App.tsx                          |  28 ++-
 frontend/src/api/authApi.ts                   |  16 ++
 frontend/src/api/client.ts                    |  37 ++++
 .../src/components/auth/ProtectedRoute.tsx    |  23 ++
 frontend/src/components/layout/AppLayout.tsx  |  80 ++++++-
 frontend/src/context/AuthContext.tsx          |  76 +++++++
 frontend/src/context/auth.ts                  |  25 +++
 frontend/src/main.tsx                         |   5 +-
 frontend/src/pages/LoginPage.tsx              | 207 ++++++++++++++++++
 frontend/src/pages/MagicLinkVerifyPage.tsx    |  54 +++++
 frontend/src/types/auth.ts                    |  35 +++
 11 files changed, 568 insertions(+), 18 deletions(-)
 create mode 100644 frontend/src/api/authApi.ts
 create mode 100644 frontend/src/components/auth/ProtectedRoute.tsx
 create mode 100644 frontend/src/context/AuthContext.tsx
 create mode 100644 frontend/src/context/auth.ts
 create mode 100644 frontend/src/pages/LoginPage.tsx
 create mode 100644 frontend/src/pages/MagicLinkVerifyPage.tsx
 create mode 100644 frontend/src/types/auth.ts

diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index 3993778..24df0c9 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -1,5 +1,8 @@
 import { Routes, Route, Navigate } from 'react-router-dom';
 import { AppLayout } from './components/layout/AppLayout';
+import { ProtectedRoute } from './components/auth/ProtectedRoute';
+import { LoginPage } from './pages/LoginPage';
+import { MagicLinkVerifyPage } from './pages/MagicLinkVerifyPage';
 import { QueryPage } from './pages/QueryPage';
 import { ConnectionsPage } from './pages/ConnectionsPage';
 import { GlossaryPage } from './pages/GlossaryPage';
@@ -11,15 +14,22 @@ import { HistoryPage } from './pages/HistoryPage';
 export default function App() {
   return (
     <Routes>
-      <Route element={<AppLayout />}>
-        <Route path="/" element={<Navigate to="/query" replace />} />
-        <Route path="/query" element={<QueryPage />} />
-        <Route path="/connections" element={<ConnectionsPage />} />
-        <Route path="/glossary" element={<GlossaryPage />} />
-        <Route path="/metrics" element={<MetricsPage />} />
-        <Route path="/dictionary" element={<DictionaryPage />} />
-        <Route path="/knowledge" element={<KnowledgePage />} />
-        <Route path="/history" element={<HistoryPage />} />
+      {/* Public */}
+      <Route path="/login" element={<LoginPage />} />
+      <Route path="/login/verify" element={<MagicLinkVerifyPage />} />
+
+      {/* Authenticated */}
+      <Route element={<ProtectedRoute />}>
+        <Route element={<AppLayout />}>
+          <Route path="/" element={<Navigate to="/query" replace />} />
+          <Route path="/query" element={<QueryPage />} />
+          <Route path="/connections" element={<ConnectionsPage />} />
+          <Route path="/glossary" element={<GlossaryPage />} />
+          <Route path="/metrics" element={<MetricsPage />} />
+          <Route path="/dictionary" element={<DictionaryPage />} />
+          <Route path="/knowledge" element={<KnowledgePage />} />
+          <Route path="/history" element={<HistoryPage />} />
+        </Route>
       </Route>
     </Routes>
   );
diff --git a/frontend/src/api/authApi.ts b/frontend/src/api/authApi.ts
new file mode 100644
index 0000000..26da0ba
--- /dev/null
+++ b/frontend/src/api/authApi.ts
@@ -0,0 +1,16 @@
+import { api } from './client';
+import type { AuthProviderInfo, MagicLinkResponse, Me, User } from '../types/auth';
+
+export const authApi = {
+  providers: () => api.get<AuthProviderInfo>('/auth/providers').then((r) => r.data),
+  me: () => api.get<Me>('/auth/me').then((r) => r.data),
+  login: (email: string, password: string) =>
+    api.post<User>('/auth/login', { email, password }).then((r) => r.data),
+  register: (email: string, password: string, name?: string) =>
+    api.post<User>('/auth/register', { email, password, name }).then((r) => r.data),
+  requestMagicLink: (email: string) =>
+    api.post<MagicLinkResponse>('/auth/magic-link', { email }).then((r) => r.data),
+  verifyMagicLink: (token: string) =>
+    api.post<User>('/auth/magic-link/verify', { token }).then((r) => r.data),
+  logout: () => api.post('/auth/logout').then((r) => r.data),
+};
diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts
index 2893c64..1842c31 100644
--- a/frontend/src/api/client.ts
+++ b/frontend/src/api/client.ts
@@ -5,8 +5,42 @@ const API_BASE = import.meta.env.VITE_API_URL || 'http://localhost:8000';
 export const api = axios.create({
   baseURL: `${API_BASE}/api/v1`,
   headers: { 'Content-Type': 'application/json' },
+  // Session is an HTTP-only cookie set by the backend, so credentials must
+  // travel with every request (and CORS must allow credentials).
+  withCredentials: true,
 });
 
+// --- Active workspace -------------------------------------------------------
+// Connections + the semantic layer are scoped per workspace. The AuthContext
+// keeps this in sync; the request interceptor forwards it as a header.
+let activeWorkspaceId: string | null = null;
+
+export function setActiveWorkspaceId(id: string | null) {
+  activeWorkspaceId = id;
+}
+
+api.interceptors.request.use((config) => {
+  if (activeWorkspaceId) {
+    config.headers.set('X-Workspace-Id', activeWorkspaceId);
+  }
+  return config;
+});
+
+// --- Unauthorized handling --------------------------------------------------
+// On a 401 the session is gone/expired; the AuthContext registers a handler
+// here to drop the user and bounce to the login screen.
+let onUnauthorized: (() => void) | null = null;
+
+export function setUnauthorizedHandler(fn: (() => void) | null) {
+  onUnauthorized = fn;
+}
+
+// 401s from the auth endpoints themselves (e.g. a bad login) are expected and
+// must not trigger the global logout/redirect.
+function isAuthEndpoint(url?: string): boolean {
+  return !!url && url.includes('/auth/');
+}
+
 // Surface real backend error messages instead of generic "Request failed with status code 500"
 api.interceptors.response.use(
   (response) => response,
@@ -14,6 +48,9 @@ api.interceptors.response.use(
     if (error.response?.data?.error) {
       error.message = error.response.data.error;
     }
+    if (error.response?.status === 401 && !isAuthEndpoint(error.config?.url) && onUnauthorized) {
+      onUnauthorized();
+    }
     return Promise.reject(error);
   },
 );
diff --git a/frontend/src/components/auth/ProtectedRoute.tsx b/frontend/src/components/auth/ProtectedRoute.tsx
new file mode 100644
index 0000000..751e1d4
--- /dev/null
+++ b/frontend/src/components/auth/ProtectedRoute.tsx
@@ -0,0 +1,23 @@
+import { Center, Loader } from '@mantine/core';
+import { Navigate, Outlet, useLocation } from 'react-router-dom';
+import { useAuth } from '../../context/auth';
+
+/** Gate the app routes behind an authenticated session. */
+export function ProtectedRoute() {
+  const { isAuthenticated, isLoading } = useAuth();
+  const location = useLocation();
+
+  if (isLoading) {
+    return (
+      <Center mih="100vh">
+        <Loader />
+      </Center>
+    );
+  }
+
+  if (!isAuthenticated) {
+    return <Navigate to="/login" replace state={{ from: location.pathname + location.search }} />;
+  }
+
+  return <Outlet />;
+}
diff --git a/frontend/src/components/layout/AppLayout.tsx b/frontend/src/components/layout/AppLayout.tsx
index 2d5fd56..b64b047 100644
--- a/frontend/src/components/layout/AppLayout.tsx
+++ b/frontend/src/components/layout/AppLayout.tsx
@@ -1,4 +1,14 @@
-import { AppShell, NavLink, Group, Title, Text } from '@mantine/core';
+import {
+  ActionIcon,
+  AppShell,
+  Badge,
+  Group,
+  Menu,
+  NavLink,
+  Select,
+  Text,
+  Title,
+} from '@mantine/core';
 import {
   IconMessageQuestion,
   IconDatabase,
@@ -7,9 +17,13 @@ import {
   IconVocabulary,
   IconFileText,
   IconHistory,
+  IconLogout,
+  IconUserCircle,
 } from '@tabler/icons-react';
 import { Outlet, useLocation, useNavigate } from 'react-router-dom';
 import { EmbeddingStatusBanner } from '../common/EmbeddingStatusBanner';
+import { useAuth } from '../../context/auth';
+import type { Role } from '../../types/auth';
 
 const NAV_ITEMS = [
   { label: 'Query', path: '/query', icon: IconMessageQuestion },
@@ -21,9 +35,21 @@ const NAV_ITEMS = [
   { label: 'History', path: '/history', icon: IconHistory },
 ];
 
+const ROLE_COLOR: Record<Role, string> = {
+  admin: 'grape',
+  editor: 'blue',
+  viewer: 'gray',
+};
+
 export function AppLayout() {
   const location = useLocation();
   const navigate = useNavigate();
+  const { user, workspaces, activeWorkspace, role, setActiveWorkspace, logout } = useAuth();
+
+  async function handleLogout() {
+    await logout();
+    navigate('/login', { replace: true });
+  }
 
   return (
     <AppShell
@@ -32,13 +58,51 @@ export function AppLayout() {
       padding="md"
     >
       <AppShell.Header>
-        <Group h="100%" px="md">
-          <Title order={3} fw={700}>
-            QueryWise
-          </Title>
-          <Text size="sm" c="dimmed">
-            Ask questions in plain English
-          </Text>
+        <Group h="100%" px="md" justify="space-between" wrap="nowrap">
+          <Group gap="sm" wrap="nowrap">
+            <Title order={3} fw={700}>
+              QueryWise
+            </Title>
+            <Text size="sm" c="dimmed" visibleFrom="sm">
+              Ask questions in plain English
+            </Text>
+          </Group>
+
+          <Group gap="sm" wrap="nowrap">
+            {workspaces.length > 0 && (
+              <Select
+                size="xs"
+                w={200}
+                aria-label="Active workspace"
+                data={workspaces.map((w) => ({ value: w.team_id, label: w.team_name }))}
+                value={activeWorkspace?.team_id ?? null}
+                onChange={(v) => v && setActiveWorkspace(v)}
+                allowDeselect={false}
+                checkIconPosition="right"
+              />
+            )}
+            {role && (
+              <Badge color={ROLE_COLOR[role]} variant="light" visibleFrom="sm">
+                {role}
+              </Badge>
+            )}
+            <Menu position="bottom-end" withArrow>
+              <Menu.Target>
+                <ActionIcon variant="subtle" size="lg" aria-label="Account menu">
+                  <IconUserCircle size={24} stroke={1.5} />
+                </ActionIcon>
+              </Menu.Target>
+              <Menu.Dropdown>
+                <Menu.Label>{user?.email ?? 'Account'}</Menu.Label>
+                <Menu.Item
+                  leftSection={<IconLogout size={16} />}
+                  onClick={handleLogout}
+                >
+                  Sign out
+                </Menu.Item>
+              </Menu.Dropdown>
+            </Menu>
+          </Group>
         </Group>
       </AppShell.Header>
 
diff --git a/frontend/src/context/AuthContext.tsx b/frontend/src/context/AuthContext.tsx
new file mode 100644
index 0000000..9a9a817
--- /dev/null
+++ b/frontend/src/context/AuthContext.tsx
@@ -0,0 +1,76 @@
+import { useEffect, useMemo, useState, type ReactNode } from 'react';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { authApi } from '../api/authApi';
+import { setActiveWorkspaceId, setUnauthorizedHandler } from '../api/client';
+import type { Me } from '../types/auth';
+import { AuthContext, type AuthContextValue } from './auth';
+
+const ACTIVE_WS_KEY = 'activeWorkspaceId';
+
+export function AuthProvider({ children }: { children: ReactNode }) {
+  const queryClient = useQueryClient();
+
+  const meQuery = useQuery<Me>({
+    queryKey: ['me'],
+    queryFn: authApi.me,
+    retry: false,
+    staleTime: Infinity,
+  });
+
+  const me = meQuery.data ?? null;
+  const workspaces = useMemo(() => me?.workspaces ?? [], [me]);
+
+  // Resolve the active workspace: stored choice if still a member, else first.
+  const [selectedId, setSelectedId] = useState<string | null>(
+    () => (typeof window !== 'undefined' ? localStorage.getItem(ACTIVE_WS_KEY) : null),
+  );
+  const activeWorkspace =
+    workspaces.find((w) => w.team_id === selectedId) ?? workspaces[0] ?? null;
+
+  // Keep the axios header + localStorage in sync with the resolved workspace.
+  useEffect(() => {
+    setActiveWorkspaceId(activeWorkspace?.team_id ?? null);
+    if (activeWorkspace) {
+      localStorage.setItem(ACTIVE_WS_KEY, activeWorkspace.team_id);
+    }
+  }, [activeWorkspace]);
+
+  // On any 401 from a non-auth endpoint, drop the session so guards redirect.
+  useEffect(() => {
+    setUnauthorizedHandler(() => {
+      queryClient.setQueryData(['me'], null);
+    });
+    return () => setUnauthorizedHandler(null);
+  }, [queryClient]);
+
+  const value: AuthContextValue = {
+    user: me?.user ?? null,
+    workspaces,
+    activeWorkspace,
+    role: activeWorkspace?.role ?? null,
+    isLoading: meQuery.isLoading,
+    isAuthenticated: !!me?.user,
+    refresh: async () => {
+      await queryClient.invalidateQueries({ queryKey: ['me'] });
+    },
+    logout: async () => {
+      try {
+        await authApi.logout();
+      } finally {
+        setActiveWorkspaceId(null);
+        queryClient.setQueryData(['me'], null);
+        // Workspace-scoped data must not bleed across sessions.
+        queryClient.removeQueries({ predicate: (q) => q.queryKey[0] !== 'me' });
+      }
+    },
+    setActiveWorkspace: (teamId: string) => {
+      localStorage.setItem(ACTIVE_WS_KEY, teamId);
+      setActiveWorkspaceId(teamId);
+      setSelectedId(teamId);
+      // Re-fetch everything for the newly selected workspace.
+      queryClient.removeQueries({ predicate: (q) => q.queryKey[0] !== 'me' });
+    },
+  };
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}
diff --git a/frontend/src/context/auth.ts b/frontend/src/context/auth.ts
new file mode 100644
index 0000000..6e72815
--- /dev/null
+++ b/frontend/src/context/auth.ts
@@ -0,0 +1,25 @@
+import { createContext, useContext } from 'react';
+import type { Role, User, WorkspaceMembership } from '../types/auth';
+
+export interface AuthContextValue {
+  user: User | null;
+  workspaces: WorkspaceMembership[];
+  activeWorkspace: WorkspaceMembership | null;
+  role: Role | null;
+  isLoading: boolean;
+  isAuthenticated: boolean;
+  /** Re-fetch /auth/me (call after a successful login). */
+  refresh: () => Promise<void>;
+  logout: () => Promise<void>;
+  setActiveWorkspace: (teamId: string) => void;
+}
+
+export const AuthContext = createContext<AuthContextValue | null>(null);
+
+export function useAuth(): AuthContextValue {
+  const ctx = useContext(AuthContext);
+  if (!ctx) {
+    throw new Error('useAuth must be used within an AuthProvider');
+  }
+  return ctx;
+}
diff --git a/frontend/src/main.tsx b/frontend/src/main.tsx
index 140f93d..9830bfc 100644
--- a/frontend/src/main.tsx
+++ b/frontend/src/main.tsx
@@ -7,6 +7,7 @@ import { BrowserRouter } from 'react-router-dom';
 import '@mantine/core/styles.css';
 import '@mantine/notifications/styles.css';
 import App from './App';
+import { AuthProvider } from './context/AuthContext';
 
 const queryClient = new QueryClient({
   defaultOptions: {
@@ -20,7 +21,9 @@ createRoot(document.getElementById('root')!).render(
       <Notifications position="top-right" />
       <QueryClientProvider client={queryClient}>
         <BrowserRouter>
-          <App />
+          <AuthProvider>
+            <App />
+          </AuthProvider>
         </BrowserRouter>
       </QueryClientProvider>
     </MantineProvider>
diff --git a/frontend/src/pages/LoginPage.tsx b/frontend/src/pages/LoginPage.tsx
new file mode 100644
index 0000000..f4d657b
--- /dev/null
+++ b/frontend/src/pages/LoginPage.tsx
@@ -0,0 +1,207 @@
+import { useState } from 'react';
+import {
+  Alert,
+  Anchor,
+  Button,
+  Center,
+  Divider,
+  Paper,
+  PasswordInput,
+  Stack,
+  Text,
+  TextInput,
+  Title,
+} from '@mantine/core';
+import { notifications } from '@mantine/notifications';
+import { useQuery } from '@tanstack/react-query';
+import { Navigate, useLocation, useNavigate } from 'react-router-dom';
+import { authApi } from '../api/authApi';
+import { useAuth } from '../context/auth';
+import type { MagicLinkResponse } from '../types/auth';
+
+export function LoginPage() {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const { refresh, isAuthenticated } = useAuth();
+
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [mode, setMode] = useState<'login' | 'register'>('login');
+  const [name, setName] = useState('');
+  const [submitting, setSubmitting] = useState(false);
+  const [magicLink, setMagicLink] = useState<MagicLinkResponse | null>(null);
+
+  const { data: providers } = useQuery({
+    queryKey: ['auth-providers'],
+    queryFn: authApi.providers,
+    staleTime: Infinity,
+  });
+
+  // Already signed in (or auth disabled) — bounce to where they came from.
+  const redirectTo = (location.state as { from?: string } | null)?.from ?? '/';
+  if (isAuthenticated) {
+    return <Navigate to={redirectTo} replace />;
+  }
+
+  async function afterAuth() {
+    await refresh();
+    navigate(redirectTo, { replace: true });
+  }
+
+  async function handlePasswordSubmit() {
+    setSubmitting(true);
+    try {
+      if (mode === 'register') {
+        await authApi.register(email, password, name || undefined);
+      } else {
+        await authApi.login(email, password);
+      }
+      await afterAuth();
+    } catch (err) {
+      notifications.show({
+        color: 'red',
+        title: mode === 'register' ? 'Registration failed' : 'Login failed',
+        message: err instanceof Error ? err.message : 'Please try again.',
+      });
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  async function handleMagicLink() {
+    if (!email) {
+      notifications.show({ color: 'red', message: 'Enter your email first.' });
+      return;
+    }
+    setSubmitting(true);
+    try {
+      setMagicLink(await authApi.requestMagicLink(email));
+    } catch (err) {
+      notifications.show({
+        color: 'red',
+        title: 'Could not send magic link',
+        message: err instanceof Error ? err.message : 'Please try again.',
+      });
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  async function handleDevVerify(token: string) {
+    setSubmitting(true);
+    try {
+      await authApi.verifyMagicLink(token);
+      await afterAuth();
+    } catch (err) {
+      notifications.show({
+        color: 'red',
+        title: 'Verification failed',
+        message: err instanceof Error ? err.message : 'The link may have expired.',
+      });
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  return (
+    <Center mih="100vh" bg="var(--mantine-color-gray-0)">
+      <Paper withBorder shadow="md" p="xl" radius="md" w={400}>
+        <Stack>
+          <div>
+            <Title order={2} fw={700}>
+              QueryWise
+            </Title>
+            <Text size="sm" c="dimmed">
+              {mode === 'register' ? 'Create your account' : 'Sign in to continue'}
+            </Text>
+          </div>
+
+          {providers?.disable_auth && (
+            <Alert color="yellow" title="Authentication disabled">
+              This deployment runs with <code>DISABLE_AUTH</code>. You are signed in
+              automatically as the default admin.
+            </Alert>
+          )}
+
+          {providers?.supports_password && (
+            <>
+              <TextInput
+                label="Email"
+                placeholder="you@company.com"
+                value={email}
+                onChange={(e) => setEmail(e.currentTarget.value)}
+                required
+              />
+              {mode === 'register' && (
+                <TextInput
+                  label="Name"
+                  placeholder="Your name"
+                  value={name}
+                  onChange={(e) => setName(e.currentTarget.value)}
+                />
+              )}
+              <PasswordInput
+                label="Password"
+                value={password}
+                onChange={(e) => setPassword(e.currentTarget.value)}
+                required
+              />
+              <Button onClick={handlePasswordSubmit} loading={submitting} fullWidth>
+                {mode === 'register' ? 'Create account' : 'Sign in'}
+              </Button>
+              <Text size="xs" ta="center">
+                {mode === 'register' ? 'Already have an account? ' : 'No account yet? '}
+                <Anchor
+                  component="button"
+                  type="button"
+                  onClick={() => setMode(mode === 'register' ? 'login' : 'register')}
+                >
+                  {mode === 'register' ? 'Sign in' : 'Create one'}
+                </Anchor>
+              </Text>
+            </>
+          )}
+
+          {providers?.supports_password && providers?.supports_magic_link && (
+            <Divider label="or" labelPosition="center" />
+          )}
+
+          {providers?.supports_magic_link && (
+            <>
+              {!providers.supports_password && (
+                <TextInput
+                  label="Email"
+                  placeholder="you@company.com"
+                  value={email}
+                  onChange={(e) => setEmail(e.currentTarget.value)}
+                  required
+                />
+              )}
+              <Button variant="light" onClick={handleMagicLink} loading={submitting} fullWidth>
+                Email me a magic link
+              </Button>
+            </>
+          )}
+
+          {magicLink?.sent && (
+            <Alert color="blue" title="Magic link sent">
+              <Stack gap="xs">
+                <Text size="sm">Check your email for a sign-in link.</Text>
+                {magicLink.dev_token && (
+                  <Button
+                    size="xs"
+                    variant="outline"
+                    onClick={() => handleDevVerify(magicLink.dev_token!)}
+                    loading={submitting}
+                  >
+                    Dev: continue without email
+                  </Button>
+                )}
+              </Stack>
+            </Alert>
+          )}
+        </Stack>
+      </Paper>
+    </Center>
+  );
+}
diff --git a/frontend/src/pages/MagicLinkVerifyPage.tsx b/frontend/src/pages/MagicLinkVerifyPage.tsx
new file mode 100644
index 0000000..aa3e4b0
--- /dev/null
+++ b/frontend/src/pages/MagicLinkVerifyPage.tsx
@@ -0,0 +1,54 @@
+import { useEffect, useRef, useState } from 'react';
+import { Alert, Anchor, Center, Loader, Paper, Stack, Text } from '@mantine/core';
+import { useNavigate, useSearchParams } from 'react-router-dom';
+import { authApi } from '../api/authApi';
+import { useAuth } from '../context/auth';
+
+export function MagicLinkVerifyPage() {
+  const [params] = useSearchParams();
+  const navigate = useNavigate();
+  const { refresh } = useAuth();
+  const [error, setError] = useState<string | null>(null);
+  const attempted = useRef(false);
+
+  const token = params.get('token');
+
+  useEffect(() => {
+    if (!token || attempted.current) return;
+    attempted.current = true;
+
+    authApi
+      .verifyMagicLink(token)
+      .then(refresh)
+      .then(() => navigate('/', { replace: true }))
+      .catch((err: unknown) =>
+        setError(err instanceof Error ? err.message : 'This link is invalid or has expired.'),
+      );
+  }, [token, refresh, navigate]);
+
+  const message = !token ? 'This link is missing its token.' : error;
+
+  return (
+    <Center mih="100vh" bg="var(--mantine-color-gray-0)">
+      <Paper withBorder shadow="md" p="xl" radius="md" w={400}>
+        {message ? (
+          <Stack>
+            <Alert color="red" title="Sign-in failed">
+              {message}
+            </Alert>
+            <Text size="sm" ta="center">
+              <Anchor onClick={() => navigate('/login', { replace: true })}>Back to login</Anchor>
+            </Text>
+          </Stack>
+        ) : (
+          <Stack align="center">
+            <Loader />
+            <Text size="sm" c="dimmed">
+              Signing you in…
+            </Text>
+          </Stack>
+        )}
+      </Paper>
+    </Center>
+  );
+}
diff --git a/frontend/src/types/auth.ts b/frontend/src/types/auth.ts
new file mode 100644
index 0000000..1346cd9
--- /dev/null
+++ b/frontend/src/types/auth.ts
@@ -0,0 +1,35 @@
+export type Role = 'admin' | 'editor' | 'viewer';
+
+export interface User {
+  id: string;
+  email: string;
+  name: string | null;
+  status: string;
+  last_login_at: string | null;
+  created_at: string;
+}
+
+export interface WorkspaceMembership {
+  team_id: string;
+  team_name: string;
+  role: Role;
+}
+
+export interface Me {
+  user: User;
+  workspaces: WorkspaceMembership[];
+}
+
+export interface AuthProviderInfo {
+  name: string;
+  supports_password: boolean;
+  supports_magic_link: boolean;
+  is_sso: boolean;
+  disable_auth: boolean;
+}
+
+export interface MagicLinkResponse {
+  sent: boolean;
+  dev_token: string | null;
+  dev_verify_url: string | null;
+}