@johnnyboy11234/esg-idea-contest 0.2.1 → 0.2.3

package/frontend/src/features/auth/RegisterForm.tsx

@@ -0,0 +1,211 @@
+import { useRef, useState, type FormEvent } from "react";
+import { useTranslation } from "react-i18next";
+import { Link } from "react-router";
+import { Button } from "@/shared/ui/button";
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+} from "@/shared/ui/field";
+import { Input } from "@/shared/ui/input";
+import {
+  mapServerError,
+  precheck,
+  register,
+  REGISTER_FIELDS,
+  type FieldProblems,
+  type RegisterField,
+  type RegisterResult,
+} from "./register";
+
+type Values = Record<RegisterField, string>;
+const EMPTY: Values = {
+  empNo: "",
+  name: "",
+  email: "",
+  password: "",
+  confirmPassword: "",
+};
+
+const FIELD_ATTRS: Record<
+  RegisterField,
+  {
+    type?: string;
+    autoComplete: string;
+    maxLength?: number;
+    inputMode?: "numeric";
+  }
+> = {
+  empNo: { autoComplete: "username", inputMode: "numeric" },
+  name: { autoComplete: "name" },
+  email: { type: "email", autoComplete: "email" },
+  password: { type: "password", autoComplete: "new-password" },
+  confirmPassword: { type: "password", autoComplete: "new-password" },
+};
+
+const HINTS: Partial<Record<RegisterField, string>> = {
+  empNo: "pages.register.empNoHint",
+  email: "pages.register.emailHint",
+  password: "pages.register.passwordHint",
+};
+
+/** The register form: format pre-check, error summary with focus, server errors mapped to fields (Frontend.md §5.6, §8). */
+export function RegisterForm({
+  onRegistered,
+}: {
+  onRegistered: (r: RegisterResult) => void;
+}) {
+  const { t, i18n } = useTranslation();
+  const [values, setValues] = useState<Values>(EMPTY);
+  const [problems, setProblems] = useState<FieldProblems>({});
+  const [formError, setFormError] = useState<string | null>(null);
+  const [pending, setPending] = useState(false);
+  const summary = useRef<HTMLDivElement>(null);
+  const form = useRef<HTMLFormElement>(null);
+  const [summaryKey, setSummaryKey] = useState(0);
+
+  const message = (code: string): string => {
+    if (code === "PASSWORD_MISMATCH") return t("pages.register.mismatch");
+    return i18n.exists(`errors.${code}`)
+      ? t(`errors.${code}`)
+      : t("errors.VALIDATION_FAILED");
+  };
+
+  const fail = (p: FieldProblems, rest: string | null) => {
+    setProblems(p);
+    setFormError(rest);
+    setSummaryKey((k) => k + 1);
+    // wait for the summary to render, then move focus to it (WCAG 3.3.1)
+    queueMicrotask(() => summary.current?.focus());
+  };
+
+  const onSubmit = async (e: FormEvent) => {
+    e.preventDefault();
+    if (pending) return;
+    const { values: body, problems: local } = precheck(values);
+    if (Object.keys(local).length > 0) {
+      fail(local, null);
+      return;
+    }
+    setPending(true);
+    setProblems({});
+    setFormError(null);
+    try {
+      onRegistered(await register(body));
+    } catch (err) {
+      const { problems: p, rest } = mapServerError(err);
+      fail(
+        p,
+        rest
+          ? t(`errors.${rest.code}`) +
+              (rest.requestId
+                ? ` ${t("common.requestId", { id: rest.requestId })}`
+                : "")
+          : null,
+      );
+    } finally {
+      setPending(false);
+    }
+  };
+
+  const focusField =
+    (f: RegisterField) => (e: { preventDefault: () => void }) => {
+      e.preventDefault();
+      form.current?.querySelector<HTMLInputElement>(`#${f}`)?.focus();
+    };
+
+  const listed = REGISTER_FIELDS.filter((f) => problems[f] !== undefined);
+  const hasSummary = listed.length > 0 || formError !== null;
+
+  return (
+    <form ref={form} onSubmit={(e) => void onSubmit(e)} noValidate>
+      <FieldGroup>
+        {hasSummary && (
+          <div
+            key={summaryKey}
+            ref={summary}
+            role="alert"
+            tabIndex={-1}
+            className="rounded-md border border-destructive p-3 text-sm outline-none focus-visible:ring-[3px] focus-visible:ring-destructive/40"
+          >
+            <p className="font-medium text-destructive">
+              {t("pages.register.summaryTitle")}
+            </p>
+            {formError !== null && <p>{formError}</p>}
+            {listed.length > 0 && (
+              <ul className="mt-1 list-disc pl-5">
+                {listed.map((f) => (
+                  <li key={f}>
+                    <a
+                      href={`#${f}`}
+                      onClick={focusField(f)}
+                      className="underline underline-offset-4"
+                    >
+                      {t(`fields.${f}`)}: {message(problems[f]!)}
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </div>
+        )}
+        {REGISTER_FIELDS.map((f) => {
+          const a = FIELD_ATTRS[f];
+          const problem = problems[f];
+          const hint = HINTS[f];
+          const describedBy =
+            [hint && `${f}-hint`, problem && `${f}-error`]
+              .filter(Boolean)
+              .join(" ") || undefined;
+          return (
+            <Field key={f} data-invalid={problem ? true : undefined}>
+              <FieldLabel htmlFor={f}>{t(`fields.${f}`)}</FieldLabel>
+              <Input
+                id={f}
+                name={f}
+                type={a.type}
+                autoComplete={a.autoComplete}
+                inputMode={a.inputMode}
+                required
+                aria-required="true"
+                aria-invalid={problem ? true : undefined}
+                aria-describedby={describedBy}
+                value={values[f]}
+                onChange={(e) =>
+                  setValues((v) => ({ ...v, [f]: e.target.value }))
+                }
+              />
+              {hint && (
+                <FieldDescription id={`${f}-hint`}>{t(hint)}</FieldDescription>
+              )}
+              {problem && (
+                <FieldError id={`${f}-error`} role={undefined}>
+                  {message(problem)}
+                </FieldError>
+              )}
+            </Field>
+          );
+        })}
+        <Field>
+          <Button
+            type="submit"
+            disabled={pending}
+            aria-busy={pending || undefined}
+          >
+            {pending
+              ? t("pages.register.submitting")
+              : t("pages.register.submit")}
+          </Button>
+          <FieldDescription className="text-center">
+            {t("pages.register.haveAccount")}{" "}
+            <Link to="/login" className="underline underline-offset-4">
+              {t("nav.signIn")}
+            </Link>
+          </FieldDescription>
+        </Field>
+      </FieldGroup>
+    </form>
+  );
+}

package/frontend/src/features/auth/login.ts

@@ -0,0 +1,23 @@
+import { apiFetch } from "@/shared/api";
+
+/** GET /auth/me and POST /auth/login body (docs/API/response-bodies.md); `email` is null for Admins. */
+export interface Me {
+  empNo: string;
+  name: string;
+  email: string | null;
+  role: "USER" | "ADMIN";
+}
+
+/** POST /auth/login. Sets the session cookie; the body is the same shape as `GET /auth/me`. */
+export async function login(body: {
+  empNo: string;
+  password: string;
+}): Promise<Me> {
+  const res = await apiFetch("/auth/login", { method: "POST", body });
+  return (await res.json()) as Me;
+}
+
+/** POST /auth/logout: idempotent 204; `apiFetch` drops the session-bound CSRF token afterwards. */
+export async function logout(): Promise<void> {
+  await apiFetch("/auth/logout", { method: "POST" });
+}

package/frontend/src/features/auth/register.ts

@@ -0,0 +1,105 @@
+import { ApiError, apiFetch } from "@/shared/api";
+import { checkEmail, checkName } from "@/shared/text";
+
+export const REGISTER_FIELDS = [
+  "empNo",
+  "name",
+  "email",
+  "password",
+  "confirmPassword",
+] as const;
+export type RegisterField = (typeof REGISTER_FIELDS)[number];
+
+export interface RegisterValues {
+  empNo: string;
+  name: string;
+  email: string;
+  password: string;
+  confirmPassword: string;
+}
+
+/** A field problem: `code` is an `errors.<code>` key, or `PASSWORD_MISMATCH` (client only). */
+export type FieldProblems = Partial<Record<RegisterField, string>>;
+
+const NAME_MAX = 50;
+
+/**
+ * Same checks, same order as the server for the format step (PRD §6.3, §6.2),
+ * one problem per field. The password policy is the server's (and F1b-01's) job;
+ * only "required" and "matches the confirmation" are checked here.
+ */
+export function precheck(v: RegisterValues): {
+  values: Omit<RegisterValues, "confirmPassword">;
+  problems: FieldProblems;
+} {
+  const problems: FieldProblems = {};
+  if (v.empNo.trim() === "") problems.empNo = "REQUIRED";
+  else if (!/^[0-9]{6}$/.test(v.empNo)) problems.empNo = "INVALID_FORMAT";
+
+  const name = checkName(v.name, NAME_MAX);
+  if (name.problem) problems.name = name.problem;
+
+  const email = checkEmail(v.email);
+  if (email.problem) problems.email = email.problem;
+
+  if (v.password === "") problems.password = "REQUIRED";
+  if (v.confirmPassword !== v.password)
+    problems.confirmPassword = "PASSWORD_MISMATCH";
+
+  return {
+    values: {
+      empNo: v.empNo,
+      name: name.cleaned,
+      email: email.cleaned,
+      password: v.password,
+    },
+    problems,
+  };
+}
+
+export interface RegisterResult {
+  empNo: string;
+  name: string;
+  email: string;
+}
+
+/** POST /auth/register. Creates no session; the caller sends the user to /login. */
+export async function register(body: {
+  empNo: string;
+  name: string;
+  email: string;
+  password: string;
+}): Promise<RegisterResult> {
+  const res = await apiFetch("/auth/register", { method: "POST", body });
+  return (await res.json()) as RegisterResult;
+}
+
+const isField = (f: string): f is RegisterField =>
+  (REGISTER_FIELDS as readonly string[]).includes(f);
+
+/**
+ * Maps a failed register call to field problems. A 409 names its field, a 422 lists
+ * `errors[]`. `rest` is what has no field of its own (CSRF, 503, …) and is shown
+ * as a form-level message.
+ */
+export function mapServerError(e: unknown): {
+  problems: FieldProblems;
+  rest: ApiError | null;
+} {
+  if (!(e instanceof ApiError))
+    return { problems: {}, rest: new ApiError({ status: 0, code: "UNKNOWN" }) };
+  if (e.code === "EMP_NO_TAKEN")
+    return { problems: { empNo: "EMP_NO_TAKEN" }, rest: null };
+  if (e.code === "EMAIL_TAKEN")
+    return { problems: { email: "EMAIL_TAKEN" }, rest: null };
+  const problems: FieldProblems = {};
+  for (const fe of e.errors) {
+    // the first error of a field wins; a password lists every violated rule, the top code covers them
+    if (isField(fe.field) && problems[fe.field] === undefined)
+      problems[fe.field] =
+        fe.field === "password" && e.code === "PASSWORD_POLICY"
+          ? "PASSWORD_POLICY"
+          : fe.code;
+  }
+  return { problems, rest: Object.keys(problems).length > 0 ? null : e };
+}

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;
+}