@johnnyboy11234/esg-idea-contest 0.2.1 → 0.2.2

package/backend/internal/auth/middleware_test.go

@@ -0,0 +1,153 @@
+package auth_test
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/google/uuid"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/auth"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/security"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+type fakeValidator struct {
+	live  map[string]security.Principal
+	err   error
+	calls int
+}
+
+func (f *fakeValidator) Validate(_ context.Context, id string) (security.Principal, bool, error) {
+	f.calls++
+	if f.err != nil {
+		return security.Principal{}, false, f.err
+	}
+	p, ok := f.live[id]
+	return p, ok, nil
+}
+
+func isPublic(r *http.Request) bool {
+	return r.Method == "GET" && r.URL.Path == "/open"
+}
+
+// chain mirrors production: middleware wraps the router, whose NotFound and
+// MethodNotAllowed hooks are the web ones.
+func chain(v auth.Validator, seen *security.Principal) http.Handler {
+	r := chi.NewRouter()
+	r.NotFound(web.NotFound)
+	r.MethodNotAllowed(web.MethodNotAllowed)
+	h := func(w http.ResponseWriter, req *http.Request) {
+		if p, ok := security.PrincipalFrom(req.Context()); ok && seen != nil {
+			*seen = p
+		}
+		w.WriteHeader(http.StatusNoContent)
+	}
+	r.Get("/open", h)
+	r.Get("/closed", h)
+	return web.RequestID(auth.Middleware(v, isPublic, slog.New(slog.DiscardHandler))(r))
+}
+
+func request(method, path, cookie string) *http.Request {
+	req := httptest.NewRequest(method, path, nil)
+	if cookie != "" {
+		req.AddCookie(&http.Cookie{Name: auth.SessionCookie, Value: cookie})
+	}
+	return req
+}
+
+func TestMiddlewareCombinations(t *testing.T) {
+	user := security.Principal{UserID: uuid.New(), EmpNo: "U1", Role: security.RoleUser}
+	v := &fakeValidator{live: map[string]security.Principal{"good": user}}
+
+	tests := []struct {
+		name         string
+		method, path string
+		cookie       string
+		status       int
+		code         string
+		principal    bool
+	}{
+		{"public, no session", "GET", "/open", "", 204, "", false},
+		{"public, valid session", "GET", "/open", "good", 204, "", true},
+		{"public, invalid session is anonymous", "GET", "/open", "stale", 204, "", false},
+		{"public path, other method, no session", "POST", "/open", "", 401, "UNAUTHENTICATED", false},
+		{"public path, other method, session", "POST", "/open", "good", 405, "METHOD_NOT_ALLOWED", false},
+		{"protected, no session", "GET", "/closed", "", 401, "UNAUTHENTICATED", false},
+		{"protected, invalid session", "GET", "/closed", "stale", 401, "UNAUTHENTICATED", false},
+		{"protected, valid session", "GET", "/closed", "good", 204, "", true},
+		{"unknown path, no session", "GET", "/nope", "", 401, "UNAUTHENTICATED", false},
+		{"unknown path, invalid session", "GET", "/nope", "stale", 401, "UNAUTHENTICATED", false},
+		{"unknown path, session", "GET", "/nope", "good", 404, "NOT_FOUND", false},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			var seen security.Principal
+			rec := httptest.NewRecorder()
+			chain(v, &seen).ServeHTTP(rec, request(tc.method, tc.path, tc.cookie))
+			if rec.Code != tc.status {
+				t.Fatalf("status = %d, want %d (%s)", rec.Code, tc.status, rec.Body)
+			}
+			if tc.code != "" && !strings.Contains(rec.Body.String(), `"code":"`+tc.code+`"`) {
+				t.Errorf("body %s lacks code %s", rec.Body, tc.code)
+			}
+			if tc.code != "" && rec.Header().Get("Content-Type") != web.ProblemContentType {
+				t.Errorf("Content-Type = %q", rec.Header().Get("Content-Type"))
+			}
+			if got := seen == user; got != tc.principal {
+				t.Errorf("principal in context = %v, want %v", got, tc.principal)
+			}
+		})
+	}
+}
+
+func TestMiddlewareNoCookieSkipsStore(t *testing.T) {
+	v := &fakeValidator{}
+	chain(v, nil).ServeHTTP(httptest.NewRecorder(), request("GET", "/open", ""))
+	// An empty cookie value is the same as none.
+	req := httptest.NewRequest("GET", "/open", nil)
+	req.AddCookie(&http.Cookie{Name: auth.SessionCookie, Value: ""})
+	chain(v, nil).ServeHTTP(httptest.NewRecorder(), req)
+	if v.calls != 0 {
+		t.Errorf("store called %d times without a cookie value", v.calls)
+	}
+}
+
+func TestMiddlewareIgnoresOtherCookies(t *testing.T) {
+	v := &fakeValidator{live: map[string]security.Principal{"good": {Role: security.RoleUser}}}
+	req := httptest.NewRequest("GET", "/closed", nil)
+	req.AddCookie(&http.Cookie{Name: "session", Value: "good"})
+	rec := httptest.NewRecorder()
+	chain(v, nil).ServeHTTP(rec, req)
+	if rec.Code != 401 || v.calls != 0 {
+		t.Errorf("status %d, store calls %d", rec.Code, v.calls)
+	}
+}
+
+func TestMiddlewareStoreFailureIs500NotPublicFallthrough(t *testing.T) {
+	v := &fakeValidator{err: errors.New("db down")}
+	for _, path := range []string{"/open", "/closed", "/nope"} {
+		rec := httptest.NewRecorder()
+		chain(v, nil).ServeHTTP(rec, request("GET", path, "good"))
+		if rec.Code != 500 || !strings.Contains(rec.Body.String(), "INTERNAL_ERROR") {
+			t.Errorf("%s: status %d body %s", path, rec.Code, rec.Body)
+		}
+		if strings.Contains(rec.Body.String(), "db down") {
+			t.Errorf("%s: cause leaked: %s", path, rec.Body)
+		}
+	}
+}
+
+func TestMiddlewareNilPublicMeansAllProtected(t *testing.T) {
+	h := auth.Middleware(&fakeValidator{}, nil, slog.New(slog.DiscardHandler))(http.NotFoundHandler())
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, request("GET", "/open", ""))
+	if rec.Code != 401 {
+		t.Errorf("status = %d", rec.Code)
+	}
+}

package/backend/internal/server/api.go

@@ -5,6 +5,7 @@ import (
 
 	"github.com/brian-huanggg/AwardRegistration/backend/internal/account"
 	"github.com/brian-huanggg/AwardRegistration/backend/internal/api"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/auth"
 	"github.com/brian-huanggg/AwardRegistration/backend/internal/deadline"
 )
 
@@ -12,6 +13,7 @@ import (
 // module has not landed yet stay api.Unimplemented (501).
 type API struct {
 	api.Unimplemented
+	Auth     auth.Handler
 	Account  account.Handler
 	Deadline deadline.Handler
 }
@@ -23,3 +25,6 @@ func (a API) GetDeadline(w http.ResponseWriter, r *http.Request) { a.Deadline.Ge
 func (a API) Register(w http.ResponseWriter, r *http.Request, _ api.RegisterParams) {
 	a.Account.Register(w, r)
 }
+
+// GetCsrfToken serves GET /auth/csrf.
+func (a API) GetCsrfToken(w http.ResponseWriter, r *http.Request) { a.Auth.GetCsrfToken(w, r) }

package/backend/internal/server/public.go

@@ -0,0 +1,35 @@
+package server
+
+import "net/http"
+
+// PublicRoutes is the explicit list of operations that need no session
+// (Backend.md §3). It must equal the operations marked `security: []` in
+// api/openapi.yaml; a test locks that. B1-10 adds POST /auth/login to both. Paths include the /api/v1 prefix.
+var PublicRoutes = []struct{ Method, Path string }{
+	{http.MethodGet, "/api/v1/auth/csrf"},
+	{http.MethodPost, "/api/v1/auth/register"},
+	{http.MethodPost, "/api/v1/auth/logout"},
+	{http.MethodGet, "/api/v1/deadline"},
+}
+
+// IsPublic reports whether r is exactly one of PublicRoutes. A public path with
+// another method is not public: without a session it answers 401, with one 405.
+func IsPublic(r *http.Request) bool {
+	for _, p := range PublicRoutes {
+		if r.Method == p.Method && r.URL.Path == p.Path {
+			return true
+		}
+	}
+	return false
+}
+
+// WriteActions maps the writes that exist today to their audit action, so a
+// CSRF denial is recorded (PRD §6.11). Later PRs add their routes here, with
+// the same exact-path rule; a write on an unknown path is not audited.
+var WriteActions = map[string]string{
+	http.MethodPost + " /api/v1/auth/register": "AUTH_REGISTER",
+	http.MethodPost + " /api/v1/auth/logout":   "AUTH_LOGOUT",
+}
+
+// ActionFor returns the audit action of r, or "" when unknown.
+func ActionFor(r *http.Request) string { return WriteActions[r.Method+" "+r.URL.Path] }

package/backend/internal/server/public_test.go

@@ -0,0 +1,73 @@
+package server_test
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"slices"
+	"testing"
+
+	"github.com/getkin/kin-openapi/openapi3"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/server"
+)
+
+// The public list in code must equal the operations the spec marks
+// `security: []`; otherwise the contract and the middleware disagree.
+func TestPublicRoutesMatchOpenAPI(t *testing.T) {
+	doc, err := openapi3.NewLoader().LoadFromFile("../../api/openapi.yaml")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var want []string
+	for path, item := range doc.Paths.Map() {
+		for method, op := range item.Operations() {
+			if op.Security != nil && len(*op.Security) == 0 {
+				want = append(want, method+" /api/v1"+path)
+			}
+		}
+	}
+	var got []string
+	for _, p := range server.PublicRoutes {
+		got = append(got, p.Method+" "+p.Path)
+	}
+	slices.Sort(want)
+	slices.Sort(got)
+	if !slices.Equal(want, got) {
+		t.Errorf("PublicRoutes\n got  %v\n want %v (spec, security: [])", got, want)
+	}
+}
+
+func TestIsPublicNeedsExactMethodAndPath(t *testing.T) {
+	tests := []struct {
+		method, path string
+		want         bool
+	}{
+		{"GET", "/api/v1/auth/csrf", true},
+		{"POST", "/api/v1/auth/logout", true},
+		{"POST", "/api/v1/auth/csrf", false},
+		{"HEAD", "/api/v1/deadline", false},
+		{"GET", "/api/v1/auth/csrf/", false},
+		{"GET", "/api/v1/auth/me", false},
+		{"GET", "/api/v1/auth/../ideas", false},
+		{"GET", "/auth/csrf", false},
+	}
+	for _, tc := range tests {
+		req := httptest.NewRequestWithContext(context.Background(), tc.method, "http://x"+tc.path, nil)
+		if got := server.IsPublic(req); got != tc.want {
+			t.Errorf("%s %s = %v, want %v", tc.method, tc.path, got, tc.want)
+		}
+	}
+}
+
+func TestActionForCoversPublicWrites(t *testing.T) {
+	for _, p := range server.PublicRoutes {
+		if p.Method == http.MethodGet {
+			continue
+		}
+		r := httptest.NewRequest(p.Method, p.Path, nil)
+		if server.ActionFor(r) == "" {
+			t.Errorf("%s %s has no audit action for a CSRF denial", p.Method, p.Path)
+		}
+	}
+}

package/backend/internal/server/server.go

@@ -22,8 +22,8 @@ const (
 
 // NewPublic builds the public router. Module routes are mounted by `mount`
 // (nil in the skeleton) under the chain: request ID → access log → recover →
-// Accept check.
-func NewPublic(log *slog.Logger, mount func(chi.Router)) http.Handler {
+// extra (the session middleware, so 401 beats 406) → Accept check.
+func NewPublic(log *slog.Logger, mount func(chi.Router), extra ...func(http.Handler) http.Handler) http.Handler {
 	r := chi.NewRouter()
 	r.NotFound(web.NotFound)
 	r.MethodNotAllowed(web.MethodNotAllowed)
@@ -32,7 +32,11 @@ func NewPublic(log *slog.Logger, mount func(chi.Router)) http.Handler {
 	}
 	// The chain wraps the router instead of using r.Use: chi skips r.Use
 	// middleware (also for NotFound) while no route is registered.
-	return web.RequestID(web.AccessLog(log)(web.Recover(log)(web.AcceptCheck(r))))
+	h := web.AcceptCheck(r)
+	for i := len(extra) - 1; i >= 0; i-- {
+		h = extra[i](h)
+	}
+	return web.RequestID(web.AccessLog(log)(web.Recover(log)(h)))
 }
 
 // Check reports whether one dependency is usable; a non-nil error makes

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

@@ -18,8 +18,16 @@ type Config struct {
 	LogLevel        slog.Level
 	ShutdownTimeout time.Duration // must stay below terminationGracePeriodSeconds
 	ReadyDrainDelay time.Duration // time readiness stays false before Shutdown starts
+	CSRFKey         string        // HMAC key that signs CSRF tokens (>= 32 bytes)
+	CSRFKeyPrevious string        // optional: still verifies for 8 h after a rotation
 }
 
+// DefaultCSRFKey is the throwaway key of the local profile only; every other
+// profile must set ESG_CSRF_KEY.
+const DefaultCSRFKey = "local-dev-csrf-key-not-a-secret-0000"
+
+const minCSRFKeyBytes = 32
+
 // DefaultDSN matches docker-compose.yml (throwaway local credentials). The query
 // pins UTC and matched-row counts (Backend.md §2.3).
 const DefaultDSN = "esg:esg@tcp(localhost:3306)/esg?parseTime=true&loc=UTC&time_zone=%27%2B00%3A00%27&clientFoundRows=true"
@@ -33,16 +41,27 @@ func Load(getenv func(string) string) (Config, error) {
 		return def
 	}
 	c := Config{
-		Profile:        get("ESG_PROFILE", "local"),
-		PublicAddr:     get("ESG_PUBLIC_ADDR", ":8080"),
-		ManagementAddr: get("ESG_MANAGEMENT_ADDR", ":8081"),
-		DBDSN:          get("ESG_DB_DSN", DefaultDSN),
+		Profile:         get("ESG_PROFILE", "local"),
+		PublicAddr:      get("ESG_PUBLIC_ADDR", ":8080"),
+		ManagementAddr:  get("ESG_MANAGEMENT_ADDR", ":8081"),
+		DBDSN:           get("ESG_DB_DSN", DefaultDSN),
+		CSRFKey:         getenv("ESG_CSRF_KEY"),
+		CSRFKeyPrevious: getenv("ESG_CSRF_KEY_PREVIOUS"),
 	}
 	switch c.Profile {
 	case "local", "k3s", "dev":
 	default:
 		return Config{}, fmt.Errorf("ESG_PROFILE %q: want local, k3s or dev", c.Profile)
 	}
+	if c.CSRFKey == "" && c.Profile == "local" {
+		c.CSRFKey = DefaultCSRFKey
+	}
+	if len(c.CSRFKey) < minCSRFKeyBytes {
+		return Config{}, fmt.Errorf("ESG_CSRF_KEY: need at least %d bytes", minCSRFKeyBytes)
+	}
+	if c.CSRFKeyPrevious != "" && len(c.CSRFKeyPrevious) < minCSRFKeyBytes {
+		return Config{}, fmt.Errorf("ESG_CSRF_KEY_PREVIOUS: need at least %d bytes", minCSRFKeyBytes)
+	}
 	if err := c.LogLevel.UnmarshalText([]byte(strings.ToUpper(get("ESG_LOG_LEVEL", "info")))); err != nil {
 		return Config{}, fmt.Errorf("ESG_LOG_LEVEL: %w", err)
 	}

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/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();
+}