@johnnyboy11234/esg-idea-contest 0.2.0 → 0.2.2

package/backend/internal/shared/config/config_test.go

@@ -8,6 +8,8 @@ import (
 	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/config"
 )
 
+const key = "0123456789abcdef0123456789abcdef"
+
 func env(m map[string]string) func(string) string { return func(k string) string { return m[k] } }
 
 func TestDefaults(t *testing.T) {
@@ -16,14 +18,14 @@ func TestDefaults(t *testing.T) {
 		t.Fatal(err)
 	}
 	if c.Profile != "local" || c.PublicAddr != ":8080" || c.ManagementAddr != ":8081" ||
-		c.LogLevel != slog.LevelInfo || c.ShutdownTimeout != 20*time.Second {
+		c.LogLevel != slog.LevelInfo || c.ShutdownTimeout != 20*time.Second || c.CSRFKey != config.DefaultCSRFKey {
 		t.Fatalf("%+v", c)
 	}
 }
 
 func TestOverrides(t *testing.T) {
 	c, err := config.Load(env(map[string]string{
-		"ESG_PROFILE": "dev", "ESG_LOG_LEVEL": "debug", "ESG_SHUTDOWN_TIMEOUT": "5s", "ESG_READY_DRAIN_DELAY": "1s",
+		"ESG_PROFILE": "dev", "ESG_CSRF_KEY": key, "ESG_CSRF_KEY_PREVIOUS": key + "2", "ESG_LOG_LEVEL": "debug", "ESG_SHUTDOWN_TIMEOUT": "5s", "ESG_READY_DRAIN_DELAY": "1s",
 	}))
 	if err != nil || c.Profile != "dev" || c.LogLevel != slog.LevelDebug || c.ReadyDrainDelay != time.Second {
 		t.Fatalf("%+v %v", c, err)
@@ -32,12 +34,16 @@ func TestOverrides(t *testing.T) {
 
 func TestInvalid(t *testing.T) {
 	for name, m := range map[string]map[string]string{
-		"profile":      {"ESG_PROFILE": "prod"},
-		"log level":    {"ESG_LOG_LEVEL": "loud"},
-		"timeout":      {"ESG_SHUTDOWN_TIMEOUT": "soon"},
-		"zero timeout": {"ESG_SHUTDOWN_TIMEOUT": "0s"},
-		"drain":        {"ESG_READY_DRAIN_DELAY": "x"},
-		"same address": {"ESG_PUBLIC_ADDR": ":9", "ESG_MANAGEMENT_ADDR": ":9"},
+		"profile":            {"ESG_PROFILE": "prod"},
+		"log level":          {"ESG_LOG_LEVEL": "loud"},
+		"timeout":            {"ESG_SHUTDOWN_TIMEOUT": "soon"},
+		"zero timeout":       {"ESG_SHUTDOWN_TIMEOUT": "0s"},
+		"drain":              {"ESG_READY_DRAIN_DELAY": "x"},
+		"short csrf key":     {"ESG_CSRF_KEY": "short"},
+		"short previous key": {"ESG_CSRF_KEY": key, "ESG_CSRF_KEY_PREVIOUS": "short"},
+		"dev needs csrf key": {"ESG_PROFILE": "dev"},
+		"k3s needs csrf key": {"ESG_PROFILE": "k3s"},
+		"same address":       {"ESG_PUBLIC_ADDR": ":9", "ESG_MANAGEMENT_ADDR": ":9"},
 	} {
 		if _, err := config.Load(env(m)); err == nil {
 			t.Errorf("%s: want error", name)

package/backend/internal/shared/db/intx_test.go

@@ -5,6 +5,7 @@ import (
 	"database/sql"
 	"database/sql/driver"
 	"errors"
+	"fmt"
 	"net/http"
 	"testing"
 	"time"
@@ -221,3 +222,27 @@ func TestSQLStateClassNonMySQL(t *testing.T) {
 		t.Error("non-MySQL error must have no class and no contention")
 	}
 }
+
+func TestDuplicateKey(t *testing.T) {
+	dup := func(msg string) error { return fmt.Errorf("wrap: %w", &mysql.MySQLError{Number: 1062, Message: msg}) }
+	cases := []struct {
+		name string
+		err  error
+		key  string
+		ok   bool
+	}{
+		{"plain", dup("Duplicate entry 'a@b' for key 'uq_app_user_email'"), "uq_app_user_email", true},
+		{"table qualified", dup("Duplicate entry '1' for key 'app_user.uq_app_user_emp_no'"), "uq_app_user_emp_no", true},
+		{"value contains the marker", dup("Duplicate entry 'for key ''x' for key 'uq_a'"), "uq_a", true},
+		{"no key in message", dup("boom"), "", true},
+		{"unterminated", dup("Duplicate entry 'x' for key 'uq_a"), "uq_a", true},
+		{"other number", &mysql.MySQLError{Number: 1205}, "", false},
+		{"not a mysql error", errors.New("x"), "", false},
+	}
+	for _, tc := range cases {
+		key, ok := DuplicateKey(tc.err)
+		if key != tc.key || ok != tc.ok {
+			t.Errorf("%s: got (%q, %v), want (%q, %v)", tc.name, key, ok, tc.key, tc.ok)
+		}
+	}
+}

package/backend/internal/shared/db/mysqlerr.go

@@ -2,6 +2,7 @@ package db
 
 import (
 	"errors"
+	"strings"
 
 	"github.com/go-sql-driver/mysql"
 )
@@ -31,3 +32,28 @@ func sqlStateClass(err error) string {
 	}
 	return string(me.SQLState[:2])
 }
+
+const errDupEntry = 1062 // ER_DUP_ENTRY
+
+// DuplicateKey reports whether err is a unique-key violation (1062) and names
+// the violated key, as in "Duplicate entry 'x' for key 'uq_app_user_email'".
+func DuplicateKey(err error) (key string, ok bool) {
+	var me *mysql.MySQLError
+	if !errors.As(err, &me) || me.Number != errDupEntry {
+		return "", false
+	}
+	const marker = "for key '"
+	i := strings.LastIndex(me.Message, marker)
+	if i < 0 {
+		return "", true
+	}
+	rest := me.Message[i+len(marker):]
+	if j := strings.IndexByte(rest, '\''); j >= 0 {
+		rest = rest[:j]
+	}
+	// MariaDB may qualify the key with the table name ("app_user.uq_x").
+	if k := strings.LastIndexByte(rest, '.'); k >= 0 {
+		rest = rest[k+1:]
+	}
+	return rest, true
+}

package/backend/internal/shared/security/security.go

@@ -4,7 +4,11 @@
 // that any package may import it.
 package security
 
-import "context"
+import (
+	"context"
+
+	"github.com/google/uuid"
+)
 
 // Role is an account role (PRD §3). Leader, Member and Applicant are relations
 // to one Idea, not roles.
@@ -34,7 +38,7 @@ const (
 // Principal is the caller resolved from a valid session. The role is read from
 // the account on every request, never copied into the session (PRD §6.5).
 type Principal struct {
-	UserID int64
+	UserID uuid.UUID
 	EmpNo  string
 	Role   Role
 }

package/backend/internal/shared/security/security_test.go

@@ -4,6 +4,8 @@ import (
 	"context"
 	"testing"
 
+	"github.com/google/uuid"
+
 	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/security"
 )
 
@@ -12,7 +14,7 @@ func TestPrincipalRoundTrip(t *testing.T) {
 	if _, ok := security.PrincipalFrom(ctx); ok {
 		t.Fatal("empty context must have no principal")
 	}
-	want := security.Principal{UserID: 7, EmpNo: "A123", Role: security.RoleUser}
+	want := security.Principal{UserID: uuid.New(), EmpNo: "A123", Role: security.RoleUser}
 	got, ok := security.PrincipalFrom(security.WithPrincipal(ctx, want))
 	if !ok || got != want {
 		t.Fatalf("got %+v, %v", got, ok)
@@ -21,9 +23,9 @@ func TestPrincipalRoundTrip(t *testing.T) {
 
 func TestActorRole(t *testing.T) {
 	bg := context.Background()
-	user := security.Principal{UserID: 1, EmpNo: "U1", Role: security.RoleUser}
-	admin := security.Principal{UserID: 2, EmpNo: "A1", Role: security.RoleAdmin}
-	bad := security.Principal{UserID: 3, EmpNo: "X", Role: "ROOT"}
+	user := security.Principal{UserID: uuid.New(), EmpNo: "U1", Role: security.RoleUser}
+	admin := security.Principal{UserID: uuid.New(), EmpNo: "A1", Role: security.RoleAdmin}
+	bad := security.Principal{UserID: uuid.New(), EmpNo: "X", Role: "ROOT"}
 
 	tests := []struct {
 		name string

package/backend/internal/shared/web/problem.go

@@ -41,6 +41,12 @@ type Error struct {
 	// AuditTargetType and AuditTargetID name the resource, when there is one.
 	AuditTargetType string
 	AuditTargetID   uuid.UUID
+	// AuditSubmittedEmpNo is the employee ID typed into a failed registration
+	// or login; the audit package sanitizes it before storing.
+	AuditSubmittedEmpNo string
+	// AuditDetail adds keys to the row's after_json beside "reason". Callers
+	// must not put secrets here.
+	AuditDetail map[string]string
 }
 
 func (e *Error) Error() string {

package/backend/internal/shared/web/request.go

@@ -0,0 +1,27 @@
+package web
+
+import (
+	"net/http"
+	"net/netip"
+
+	"github.com/go-chi/chi/v5"
+)
+
+// RoutePattern is the matched chi pattern (/api/v1/ideas/{id}), never the raw
+// path, so IDs do not leak into the audit log and rows group by route. It is
+// empty when no route matched.
+func RoutePattern(r *http.Request) string {
+	if rc := chi.RouteContext(r.Context()); rc != nil {
+		return rc.RoutePattern()
+	}
+	return ""
+}
+
+// ClientIP is the TCP peer. Trusted-proxy handling is not decided yet.
+func ClientIP(r *http.Request) netip.Addr {
+	ap, err := netip.ParseAddrPort(r.RemoteAddr)
+	if err != nil {
+		return netip.Addr{}
+	}
+	return ap.Addr().Unmap()
+}

package/frontend/src/app/App.test.tsx

@@ -161,3 +161,16 @@ describe('accessibility', () => {
     expect((await axe(container)).violations).toEqual([]);
   });
 });
+
+describe('global 401 (Frontend.md §5.2)', () => {
+  it('goes to /login?next=<current> with a session-ended notice and forgets the user', async () => {
+    const { router } = await open('/ideas?page=2', 'USER');
+    await screen.findByRole('heading', { level: 1 });
+    server.use(http.get(`${API}/ideas`, () => problem(401, 'UNAUTHENTICATED')));
+    const { apiFetch } = await import('@/shared/api');
+    await expect(apiFetch('/ideas')).rejects.toMatchObject({ status: 401 });
+    await waitFor(() => expect(router.state.location.pathname).toBe('/login'));
+    expect(router.state.location.search).toBe(`?next=${encodeURIComponent('/ideas?page=2')}`);
+    expect(router.state.location.state).toEqual({ notice: 'sessionEnded' });
+  });
+});

package/frontend/src/app/App.tsx

@@ -1,11 +1,15 @@
+import { useEffect } from 'react';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { RouterProvider, createBrowserRouter, type DataRouter } from 'react-router';
+import { setUnauthenticatedHandler } from '@/shared/api';
 import { routes } from './router';
+import { handleSessionEnded } from './session';
 
 const queryClient = new QueryClient();
 const browserRouter = createBrowserRouter(routes);
 
 export function App({ router = browserRouter, client = queryClient }: { router?: DataRouter; client?: QueryClient }) {
+  useEffect(() => setUnauthenticatedHandler(() => handleSessionEnded(client, router)), [client, router]);
   return (
     <QueryClientProvider client={client}>
       <RouterProvider router={router} />

package/frontend/src/app/session.ts

@@ -1,5 +1,7 @@
-import { useQuery } from '@tanstack/react-query';
-import { parseApiError } from '@/shared/api';
+import { useQuery, type QueryClient } from '@tanstack/react-query';
+import type { DataRouter } from 'react-router';
+import { ApiError, apiFetch } from '@/shared/api';
+import { findRoute } from './access';
 import type { Role } from './routes';
 
 /** GET /auth/me body (docs/API/response-bodies.md); `email` is null for Admins. */
@@ -14,10 +16,30 @@ export const meKey = ['me'] as const;
 
 /** A 401 means visitor → null (Frontend.md §6.3 rule 1). */
 export async function fetchMe(signal?: AbortSignal): Promise<Me | null> {
-  const res = await fetch(`${location.origin}/api/v1/auth/me`, { headers: { Accept: 'application/json' }, signal });
-  if (res.status === 401) return null;
-  if (!res.ok) throw await parseApiError(res);
-  return (await res.json()) as Me;
+  try {
+    const res = await apiFetch('/auth/me', { signal, allowUnauthenticated: true });
+    return (await res.json()) as Me;
+  } catch (e) {
+    if (e instanceof ApiError && e.status === 401) return null;
+    throw e;
+  }
+}
+
+/** Router state a 401 redirect leaves for the login page to show "your session ended" (Frontend.md §5.2). */
+export interface SessionEndedState {
+  notice: 'sessionEnded';
+}
+
+/**
+ * Global 401 (Frontend.md §5.2): forget the user and go to `/login?next=<current>`.
+ * Already on a public route (login, register) there is nothing to leave, so only `me` is cleared.
+ */
+export function handleSessionEnded(client: QueryClient, router: DataRouter): void {
+  client.setQueryData(meKey, null);
+  const { pathname, search } = router.state.location;
+  if (findRoute(pathname)?.access === 'public') return;
+  const state: SessionEndedState = { notice: 'sessionEnded' };
+  void router.navigate(`/login?next=${encodeURIComponent(pathname + search)}`, { replace: true, state });
 }
 
 export function useMe() {

package/frontend/src/shared/api/csrf.ts

@@ -0,0 +1,51 @@
+import { parseApiError } from './problem';
+
+/**
+ * Session-bound CSRF token, kept in memory only (PRD §6.5, Frontend.md §5.2, F13).
+ * The token is bound to the current session (anonymous before login), so it is
+ * dropped on login, logout and any 401 and fetched again lazily.
+ */
+let token: string | null = null;
+let inflight: Promise<string> | null = null;
+/** Bumped by clearCsrfToken so a fetch started before the clear cannot repopulate the cache. */
+let generation = 0;
+
+export const API_BASE = () => `${location.origin}/api/v1`;
+
+async function fetchToken(): Promise<string> {
+  const res = await fetch(`${API_BASE()}/auth/csrf`, { headers: { Accept: 'application/json' }, credentials: 'same-origin' });
+  if (!res.ok) throw await parseApiError(res);
+  const body = (await res.json()) as { token?: unknown };
+  if (typeof body.token !== 'string' || body.token === '') throw await parseApiError(new Response(null, { status: 500 }));
+  return body.token;
+}
+
+/** Returns the cached token, fetching it once (shared by concurrent callers) when absent. */
+export function getCsrfToken(): Promise<string> {
+  if (token !== null) return Promise.resolve(token);
+  if (inflight) return inflight;
+  const started = generation;
+  const p = fetchToken()
+    .then((t) => {
+      if (started === generation) token = t;
+      return t;
+    })
+    .finally(() => {
+      if (inflight === p) inflight = null;
+    });
+  inflight = p;
+  return p;
+}
+
+/** Drops the token (login, logout, 401). The next write fetches a new one. */
+export function clearCsrfToken(): void {
+  generation += 1;
+  token = null;
+  inflight = null;
+}
+
+/** Drops the token and fetches a new one (the `CSRF_INVALID` retry). */
+export function refreshCsrfToken(): Promise<string> {
+  clearCsrfToken();
+  return getCsrfToken();
+}

package/frontend/src/shared/api/http.test.tsx

@@ -0,0 +1,209 @@
+import { http, HttpResponse } from 'msw';
+import { problem } from './mocks/problem';
+import { server } from './mocks/server';
+import { ApiError } from './problem';
+import { clearCsrfToken } from './csrf';
+import { apiFetch, setUnauthenticatedHandler } from './http';
+
+const API = 'http://localhost:3000/api/v1';
+
+/** Counts GET /auth/csrf and hands out t1, t2, … */
+function csrfEndpoint() {
+  const state = { calls: 0 };
+  server.use(
+    http.get(`${API}/auth/csrf`, () => {
+      state.calls += 1;
+      return HttpResponse.json({ token: `t${state.calls}` });
+    }),
+  );
+  return state;
+}
+
+beforeEach(() => {
+  clearCsrfToken();
+  setUnauthenticatedHandler(null);
+});
+
+describe('CSRF token', () => {
+  it('is fetched lazily, cached, and sent on writes only', async () => {
+    const csrf = csrfEndpoint();
+    const seen: (string | null)[] = [];
+    server.use(
+      http.get(`${API}/deadline`, ({ request }) => {
+        seen.push(request.headers.get('X-CSRF-Token'));
+        return HttpResponse.json({});
+      }),
+      http.post(`${API}/join-requests`, ({ request }) => {
+        seen.push(request.headers.get('X-CSRF-Token'));
+        return HttpResponse.json({}, { status: 201 });
+      }),
+      http.delete(`${API}/ideas/x`, ({ request }) => {
+        seen.push(request.headers.get('X-CSRF-Token'));
+        return new HttpResponse(null, { status: 204 });
+      }),
+    );
+    await apiFetch('/deadline');
+    expect(csrf.calls).toBe(0);
+    await apiFetch('/join-requests', { method: 'POST', body: { a: 1 } });
+    await apiFetch('/ideas/x', { method: 'DELETE' });
+    expect(csrf.calls).toBe(1);
+    expect(seen).toEqual([null, 't1', 't1']);
+  });
+
+  it('is shared by concurrent first writes', async () => {
+    const csrf = csrfEndpoint();
+    server.use(http.post(`${API}/join-requests`, () => HttpResponse.json({}, { status: 201 })));
+    await Promise.all([1, 2, 3].map(() => apiFetch('/join-requests', { method: 'POST', body: {} })));
+    expect(csrf.calls).toBe(1);
+  });
+
+  it('sends JSON bodies with a JSON content type', async () => {
+    csrfEndpoint();
+    let ct: string | null = null;
+    let body: unknown;
+    server.use(
+      http.post(`${API}/auth/register`, async ({ request }) => {
+        ct = request.headers.get('Content-Type');
+        body = await request.json();
+        return HttpResponse.json({}, { status: 201 });
+      }),
+    );
+    await apiFetch('/auth/register', { method: 'POST', body: { empNo: '1' } });
+    expect(ct).toBe('application/json');
+    expect(body).toEqual({ empNo: '1' });
+  });
+
+  it.each(['/auth/login', '/auth/logout'])('is refetched after a successful %s', async (path) => {
+    const csrf = csrfEndpoint();
+    const seen: string[] = [];
+    server.use(
+      http.post(`${API}${path}`, ({ request }) => {
+        seen.push(request.headers.get('X-CSRF-Token') ?? '');
+        return path === '/auth/login' ? HttpResponse.json({}) : new HttpResponse(null, { status: 204 });
+      }),
+    );
+    await apiFetch(path, { method: 'POST', body: {} });
+    await apiFetch(path, { method: 'POST', body: {} });
+    expect(csrf.calls).toBe(2);
+    expect(seen).toEqual(['t1', 't2']);
+  });
+
+  it('is kept after a failed login', async () => {
+    const csrf = csrfEndpoint();
+    server.use(http.post(`${API}/auth/login`, () => problem(401, 'INVALID_CREDENTIALS')));
+    const unauth = vi.fn();
+    setUnauthenticatedHandler(unauth);
+    await expect(apiFetch('/auth/login', { method: 'POST', body: {} })).rejects.toMatchObject({ code: 'INVALID_CREDENTIALS' });
+    await expect(apiFetch('/auth/login', { method: 'POST', body: {} })).rejects.toBeInstanceOf(ApiError);
+    expect(csrf.calls).toBe(1);
+    expect(unauth).not.toHaveBeenCalled();
+  });
+});
+
+describe('CSRF_INVALID', () => {
+  it('refetches and retries once, resending the same body', async () => {
+    const csrf = csrfEndpoint();
+    const attempts: { token: string | null; body: unknown }[] = [];
+    server.use(
+      http.post(`${API}/join-requests`, async ({ request }) => {
+        attempts.push({ token: request.headers.get('X-CSRF-Token'), body: await request.json() });
+        return attempts.length === 1 ? problem(403, 'CSRF_INVALID') : HttpResponse.json({}, { status: 201 });
+      }),
+    );
+    const res = await apiFetch('/join-requests', { method: 'POST', body: { ideaId: 'i' } });
+    expect(res.status).toBe(201);
+    expect(csrf.calls).toBe(2);
+    expect(attempts).toEqual([
+      { token: 't1', body: { ideaId: 'i' } },
+      { token: 't2', body: { ideaId: 'i' } },
+    ]);
+  });
+
+  it('does not retry a second time', async () => {
+    const csrf = csrfEndpoint();
+    let posts = 0;
+    server.use(
+      http.post(`${API}/join-requests`, () => {
+        posts += 1;
+        return problem(403, 'CSRF_INVALID');
+      }),
+    );
+    await expect(apiFetch('/join-requests', { method: 'POST', body: {} })).rejects.toMatchObject({ status: 403, code: 'CSRF_INVALID' });
+    expect(posts).toBe(2);
+    expect(csrf.calls).toBe(2);
+  });
+
+  it('does not retry other 403s', async () => {
+    const csrf = csrfEndpoint();
+    let posts = 0;
+    server.use(
+      http.post(`${API}/join-requests`, () => {
+        posts += 1;
+        return problem(403, 'SUBMISSION_CLOSED');
+      }),
+    );
+    await expect(apiFetch('/join-requests', { method: 'POST', body: {} })).rejects.toMatchObject({ code: 'SUBMISSION_CLOSED' });
+    expect(posts).toBe(1);
+    expect(csrf.calls).toBe(1);
+  });
+
+  it('resends a multipart body on retry', async () => {
+    csrfEndpoint();
+    const names: (string | null)[] = [];
+    server.use(
+      http.post(`${API}/ideas`, async ({ request }) => {
+        const f = (await request.formData()).get('title');
+        names.push(f as string);
+        return names.length === 1 ? problem(403, 'CSRF_INVALID') : HttpResponse.json({}, { status: 201 });
+      }),
+    );
+    const fd = new FormData();
+    fd.set('title', 'T');
+    await apiFetch('/ideas', { method: 'POST', body: fd });
+    expect(names).toEqual(['T', 'T']);
+  });
+
+  it('a failed token fetch surfaces its error and caches nothing', async () => {
+    server.use(http.get(`${API}/auth/csrf`, () => problem(429, 'RATE_LIMITED')));
+    await expect(apiFetch('/join-requests', { method: 'POST', body: {} })).rejects.toMatchObject({ status: 429 });
+    const csrf = csrfEndpoint();
+    server.use(http.post(`${API}/join-requests`, () => HttpResponse.json({}, { status: 201 })));
+    await apiFetch('/join-requests', { method: 'POST', body: {} });
+    expect(csrf.calls).toBe(1);
+  });
+});
+
+describe('401', () => {
+  it('clears the token and calls the handler', async () => {
+    const csrf = csrfEndpoint();
+    const unauth = vi.fn();
+    setUnauthenticatedHandler(unauth);
+    let n = 0;
+    server.use(
+      http.post(`${API}/join-requests`, () => {
+        n += 1;
+        return n === 1 ? problem(401, 'UNAUTHENTICATED') : HttpResponse.json({}, { status: 201 });
+      }),
+    );
+    await expect(apiFetch('/join-requests', { method: 'POST', body: {} })).rejects.toMatchObject({ status: 401, code: 'UNAUTHENTICATED' });
+    expect(unauth).toHaveBeenCalledTimes(1);
+    await apiFetch('/join-requests', { method: 'POST', body: {} });
+    expect(csrf.calls).toBe(2);
+  });
+
+  it('is an answer, not a redirect, when allowUnauthenticated is set', async () => {
+    const unauth = vi.fn();
+    setUnauthenticatedHandler(unauth);
+    server.use(http.get(`${API}/auth/me`, () => problem(401, 'UNAUTHENTICATED')));
+    await expect(apiFetch('/auth/me', { allowUnauthenticated: true })).rejects.toMatchObject({ status: 401 });
+    expect(unauth).not.toHaveBeenCalled();
+  });
+
+  it('fires for reads too', async () => {
+    const unauth = vi.fn();
+    setUnauthenticatedHandler(unauth);
+    server.use(http.get(`${API}/ideas`, () => problem(401, 'UNAUTHENTICATED')));
+    await expect(apiFetch('/ideas')).rejects.toBeInstanceOf(ApiError);
+    expect(unauth).toHaveBeenCalledTimes(1);
+  });
+});

package/frontend/src/shared/api/http.ts

@@ -0,0 +1,91 @@
+import { API_BASE, clearCsrfToken, getCsrfToken, refreshCsrfToken } from './csrf';
+import { parseApiError, type ApiError } from './problem';
+
+const SAFE = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+/** Endpoints after which the session binding of the CSRF token changes (PRD §6.5). */
+const SESSION_CHANGING = new Set(['/auth/login', '/auth/logout']);
+
+type Unauthenticated = () => void;
+let onUnauthenticated: Unauthenticated | null = null;
+
+/** The app registers what a 401 does (clear `me`, go to /login?next=). Returns an unregister function. */
+export function setUnauthenticatedHandler(fn: Unauthenticated | null): () => void {
+  onUnauthenticated = fn;
+  return () => {
+    if (onUnauthenticated === fn) onUnauthenticated = null;
+  };
+}
+
+export interface ApiRequestInit extends Omit<RequestInit, 'body'> {
+  /** Plain objects are sent as JSON; strings, FormData and Blobs are sent as given. */
+  body?: BodyInit | Record<string, unknown> | null;
+  /** A 401 is an answer here (e.g. `GET /auth/me` means "visitor"), not a session end. */
+  allowUnauthenticated?: boolean;
+}
+
+function prepare(init: ApiRequestInit): { headers: Headers; body: BodyInit | null | undefined } {
+  const headers = new Headers(init.headers);
+  if (!headers.has('Accept')) headers.set('Accept', 'application/json');
+  let body = init.body as BodyInit | null | undefined;
+  if (body !== null && body !== undefined && typeof body === 'object' && !isNativeBody(body)) {
+    body = JSON.stringify(body);
+    if (!headers.has('Content-Type')) headers.set('Content-Type', 'application/json');
+  }
+  return { headers, body };
+}
+
+function isNativeBody(b: object): boolean {
+  return (
+    b instanceof FormData ||
+    b instanceof Blob ||
+    b instanceof URLSearchParams ||
+    b instanceof ArrayBuffer ||
+    ArrayBuffer.isView(b) ||
+    b instanceof ReadableStream
+  );
+}
+
+/**
+ * fetch for `/api/v1`: `path` is relative to it (`/auth/me`). Resolves with the
+ * Response on 2xx and throws ApiError otherwise.
+ *
+ * - Writes send `X-CSRF-Token` (lazily fetched, cached in memory).
+ * - `CSRF_INVALID` refetches the token and retries the write once. The request
+ *   was rejected before processing, so the retry is safe (Frontend.md §5.2).
+ *   A request whose body is a stream cannot be replayed and is not retried.
+ * - A successful login or logout clears the token (the binding changed).
+ * - A 401 clears the token and calls the registered handler, except for
+ *   `INVALID_CREDENTIALS` (a wrong password is not a session end).
+ */
+export async function apiFetch(path: string, init: ApiRequestInit = {}): Promise<Response> {
+  const method = (init.method ?? 'GET').toUpperCase();
+  const write = !SAFE.has(method);
+  const { headers, body } = prepare(init);
+  const send = (csrf: string | null) => {
+    const h = new Headers(headers);
+    if (csrf !== null) h.set('X-CSRF-Token', csrf);
+    return fetch(`${API_BASE()}${path}`, { ...init, method, headers: h, body, credentials: 'same-origin' });
+  };
+
+  let res = await send(write ? await getCsrfToken() : null);
+  if (write && !res.ok && !(body instanceof ReadableStream) && (await errorCode(res)) === 'CSRF_INVALID') {
+    res = await send(await refreshCsrfToken());
+  }
+
+  if (res.ok) {
+    if (write && SESSION_CHANGING.has(path)) clearCsrfToken();
+    return res;
+  }
+  const err = await parseApiError(res);
+  if (err.status === 401 && err.code !== 'INVALID_CREDENTIALS' && !init.allowUnauthenticated) {
+    clearCsrfToken();
+    onUnauthenticated?.();
+  }
+  throw err;
+}
+
+/** Reads the error code without consuming the response. */
+async function errorCode(res: Response): Promise<ApiError['code']> {
+  return (await parseApiError(res.clone())).code;
+}

package/frontend/src/shared/api/index.ts

@@ -1,3 +1,6 @@
 export { ApiError, parseApiError } from './problem';
 export type { ErrorCode, FieldError } from './problem';
+export { apiFetch, setUnauthenticatedHandler } from './http';
+export type { ApiRequestInit } from './http';
+export { clearCsrfToken, getCsrfToken } from './csrf';
 export type { paths, components } from './types.generated';