feat: Stage 1 authentication

[Nickatak]

feat/auth: Stage 1 authentication

Stacks on develop (the modernization chain landed 2026-05-07
through #747). First "real feature" PR after pattern work.

Summary

Wires up the Stage 1 auth flow end-to-end. Frontend already had
LoginForm + SignupForm at /login and /signup rendering /
validating but their submit handlers console.log'd - this PR
makes them actually authenticate against the backend.

Splits CustomUser and the /api/users/<uuid>/ endpoint out into
a new accounts Django app, then adds the five /api/auth/*
endpoints (signup, login, logout, me, csrf) using Django session

• cookie auth. SPA gets a shared apiFetch client + AuthContext
  provider; the forms call into the context and redirect on success.

Same-origin via Next rewrites in dev / compose / stage / prod
means no CORS surface anywhere; CSRF flows through the csrftoken
cookie + X-CSRFToken header.

A clean-install audit + browser walk-through (run before opening
this PR) added the last four commits: a Next-proxy trailing-slash
fix (the SPA's /api/* calls 404'd through the dev/compose proxy),
a CSRF_TRUSTED_ORIGINS fix (logout failed Django's CSRF Origin
check behind the proxy), two doc corrections, and a deliberately
minimal signed-in nav indicator. The two proxy bugs are
dev/compose-only -- deployed stage/prod route /api/* to Django on
the same hostname via the ALB -- but they made the SPA auth flow
non-functional in local dev, which is where every contributor runs
it. See Open questions for the design-side
questions that surfaced (signed-in nav shape, logout placement,
email-verification transport).

Open questions

Things that need an answer (from the wireframes, from devops, or
just a call) before the relevant pieces are finished. Flagged here
rather than guessed at.

1. Signed-in nav, for real. There is no Figma frame for the
   logged-in state, but the wireframes do show the difference: the
   "Log In" button is replaced by a "View open roles" button.
   That button needs a destination, and the open-roles / opportunities
   browse page doesn't exist in the frontend yet -- only the
   qualifier flow, whose own end-of-flow "View available roles"
   button is currently stubbed to href="/". (Backend has
   /api/opportunities/ and /api/roles/; no listing UI consumes
   them.) Commit 10 ships an interim "Log out" button in that
   slot instead. Confirm: target is "View open roles"; interim
   "Log out" placeholder is acceptable until the roles page lands.
2. Where does logout live? If the nav slot becomes "View open
   roles" per Q1, there is no logout control anywhere in the designed
   UI -- no account menu, no avatar dropdown. Options: fold it under
   a "View open roles" dropdown, add a separate nav element, put it
   on a (not-yet-designed) account page, or accept "no visible logout
   in Stage 1" (session just expires). Needs a call.
3. Email transport for verification. The wireframes include an
   email-verification step (scratch/planning/planned_auth.md
   deferred it for Stage 1 precisely because it needs email
   transport). Building it is fine -- but what are we sending
   through: Mailgun, AWS SES, something else? Partly a devops
   question (CTJ declares the env vars, devops populates the
   provider + credentials per environment); CTJ just needs to know
   which client to wire. Resolving it determines whether email
   verification is in-scope for this PR's Stage 1 or a follow-up.

Commits

Thirteen commits; tests fold into the commit that introduces the
code they cover. Each commit passes make lint + both test suites at
its tip. One leading chore: commit applies tree-wide pre-commit
auto-fixes that surfaced the first time make lint ran
post-modernization (separated so the feature diff stays readable).
Commits 8-11 (fix: / docs: / nav feat: / fix:) land the
findings from a clean-install audit and a manual browser walk-through
(see the test plan): two dev/compose-only proxy bugs and two doc
corrections. Trailing commits 12-13 close two lint-job failures that
CI surfaced after the audit work: 12 closes a lint:types failure
by typing the vi.spyOn spies via MockInstance<F> directly; 13
closes a lint:dead (knip) failure by dropping a dead export on the
API client's internal error-body type.

1. chore: Apply tree-wide pre-commit auto-fixes (18 files;
   EOF / CRLF / prettier-format only)
2. refactor: Split CustomUser and user resource code into a new accounts app (30 files; structural; nuked + regenerated
   migrations; existing tests still pass)
3. feat: Same-origin via Next rewrites for host-based dev
   (3 files; Makefile FRONTEND_RUN macro + comment cleanups)
4. feat: Add Stage 1 auth endpoints (signup, login, logout, me, csrf) (6 files; pins
   DEFAULT_AUTHENTICATION_CLASSES = [SessionAuthentication];
   drops the broken opportunities field on
   CustomUserReadSerializer; 14 new tests + 1 uncomment)
5. feat: Add frontend API client + AuthContext (6 files;
   apiFetch + typed authApi + AuthProvider mounted in root
   layout; 16 new tests)
6. feat: Wire LoginForm and SignupForm to the auth backend
   (7 files; replaces console.log onSubmits; 7 new tests)
7. docs: Document accounts app and Stage 1 auth flow (2 files;
   project layout, API table, auth narrative, test shape,
   permissions paths, lint command args)
8. fix: Preserve trailing slashes when proxying /api and /admin to Django (1 file; next.config.ts rewrite destinations always
   carry a trailing slash + paired slash/no-slash sources). Found
   during a clean-install audit: Next's default trailingSlash: false
   308-strips the slash before rewrites() runs, so the SPA's
   trailing-slash API calls reached Django slashless, missed every
   path(), and hit the api_not_found catch-all -- the browser auth
   flow through :3000 was non-functional. Unit tests missed it
   (vitest mocks fetch); deployed stage was unaffected (ALB
   path-routes /api/* directly).
9. docs: Fix healthcheck URL slash and stale docker-compose invocation (2 files; quickstart-guide.md /api/healthcheck ->
   /api/healthcheck/ per ADR-0011; installation.md step 3
   docker compose up --watch -> make docker-up per ADR-0014)
10. feat: Show signed-in state in the site nav (2 files;
    HeaderNav becomes a "use client" component reading
    useAuth() -> "Log out" button when signed in, "Log In" link
    otherwise; consumes the previously-unused logout action;
    3 new tests). Deliberately minimal interim -- no Figma frame
    exists for the signed-in nav; no avatar / menu / name. See
    follow-ups.
11. fix: Trust the proxied SPA origin for CSRF (CSRF_TRUSTED_ORIGINS)
    (5 files; new env-driven CSRF_TRUSTED_ORIGINS setting + dev
    default, env examples, backend.md note, 2 new tests). The SPA
    is proxied to Django on a different Host, so an authenticated
    POST arrives with Origin: http://localhost:3000 against a
    non-matching host and Django's CSRF Origin check rejects it
    ("Origin checking failed"). First hit on logout (the first
    authenticated POST). dev/compose-only; deployed stage/prod
    route /api/* same-hostname. The curl smoke missed it (curl
    doesn't send Origin); a browser walk-through caught it.
12. chore: Type vi.spyOn results via MockInstance to fix lint:types
    (2 files; test-only). Closes the test plan's previously-pre-existing
    lint:types failure. vitest 3 narrowed the default MockInstance
    returned by a bare vi.spyOn reference, so
    ReturnType<typeof vi.spyOn> resolves to
    MockInstance<(this: unknown, ...args: unknown[]) => unknown>,
    which the parameterized spy returned by vi.spyOn(authApi, "login")
    etc. can't assign into (function parameters are contravariant).
    Fix: type the spy variables directly as
    MockInstance<typeof target.method>, sidestepping vi.spyOn's
    own generic constraints. Three spies affected (login, signup,
    fetch); no-arg spies (csrf, me, logout) had no contravariance
    problem and were left unchanged. No runtime / behavior change.
13. chore: Drop ApiErrorBody export to satisfy knip lint:dead
    (1 file). ApiErrorBody is used only inside client.ts to type
    the parsed error envelope before constructing an ApiError;
    nothing imports it. Knip's lint:dead job caught the dead
    export on CI. Consumers should read ApiError.code /
    .message / .fields rather than the raw body shape (which is
    exactly what the rest of the codebase does). No runtime /
    behavior change.

Decisions baked in

• Auth strategy: Django session + cookie (Stage 1). Cognito
  JWT (Stage 2) explicitly out of scope. Sessions over tokens
  because Django admin already uses sessions.
• Same-origin via Next rewrites in dev / compose / stage /
  prod -> no CORS, no django-cors-headers, no
  NEXT_PUBLIC_API_URL cross-origin path. CSRF via cookie +
  header. Two consequences of the rewrite layer, both handled in
  the trailing commits: (a) Next strips trailing slashes before
  rewrites run, so the proxy destination must re-append them for
  Django's trailing-slash routes (commit 8); (b) the proxy rewrites
  Host, so the browser's Origin won't match the request host
  Django sees -- the SPA origin must be in CSRF_TRUSTED_ORIGINS
  (commit 11). Neither bites deployed stage/prod (ALB path routing,
  same hostname).
• App boundary: separate accounts Django app (not a
  subpackage in ctj_api). Wide scope: CustomUser,
  /api/users/<uuid>/, UserDetailPermission, the auth flow
  endpoints all live here. Domain (Opportunity, Project, etc.)
  stays in ctj_api. Cross-app FKs to user use
  settings.AUTH_USER_MODEL.
• Migration strategy: nuke and regenerate. No real data to
  preserve. Anyone with a local dev DB needs make db-reset-hard.
• DRF auth classes: pinned to [SessionAuthentication].
  Drops DRF's implicit BasicAuthentication default since
  nothing here uses it.
• AuthContext mount point: root layout. Logged-out is a real
  state nav consumers care about (Log In link vs signed-in
  control), so every route gets it.
• Signup auto-login: yes. Signup -> session created -> redirect
  to /. Smoother flow for the common case.
• URL shape: group by function (/api/auth/*) not by app
  boundary (/api/accounts/auth/*). Public URL contract should
  reflect what the endpoint does, not where the view lives.

CSRF caveat

DRF's @api_view marks the resulting view csrf_exempt at the
Django middleware level; CSRF is only enforced by
SessionAuthentication's own check, which fires for authenticated
requests. Effect: signup and login do not enforce CSRF
(anonymous when called); logout, me, and any post-login mutation
do. The frontend client sends X-CSRFToken on every mutation
regardless - it's free once the cookie is set. Hardening
signup/login CSRF (via @csrf_protect over @api_view, or a
custom EnforceCsrfMixin) is a follow-up.

Because SessionAuthentication's check runs the full
CsrfViewMiddleware pass, it also does the Origin/Referer check

• which is why authenticated mutations need the proxied SPA origin
  in CSRF_TRUSTED_ORIGINS (commit 11; see "Same-origin via Next
  rewrites" above).

Test plan

• Backend: make local-test-backend -> 27 tests pass
• Frontend: npx vitest run -> 37 tests pass (2 file-level
  skips + 3 test-level skips are all pre-existing)
• make lint clean (ruff / ruff-format / prettier / eslint /
  stylelint pass)
• mypy accounts ctj_api backend clean (36 source files)
• bandit -r accounts ctj_api backend clean
• npm run lint:types clean. Was previously failing with 3
  vi.spyOn MockInstance errors in
  tests/contexts/AuthContext.test.tsx (login/signup spies) and
  tests/lib/api/client.test.ts (fetch spy); fixed in commit 12
  by typing the spy variables directly as
  MockInstance<typeof target.method>. See commit 12 for the
  mechanism.
• npm run lint:dead (knip) clean. CI flagged an unused
  export on ApiErrorBody in frontend/src/shared/lib/api/client.ts;
  fixed in commit 13 by dropping the export keyword (the type
  is internal to client.ts).
• Clean-install audit (scratch/planning/clean-install-audit.md):
  nuked the DB volume + both project images, regenerated
  dev/dev.env from dev.env.example, make docker-up ->
  images build, all three containers up, migrations apply in
  dependency order (accounts.0001 -> ctj_api.0001 ->
  accounts.0002 -> ...). Surfaced and fixed the proxy
  trailing-slash bug (commit 8).
• Smoke via curl against the :3000 proxy after the commit-8
  fix -- the same path the React forms' apiFetch calls take:
  • GET /api/auth/csrf/ -> 204, sets csrftoken.
  • POST /api/auth/signup/ -> 201, sets sessionid (auto-login),
    returns the new user; GET /api/auth/me/ then returns it.
  • POST /api/auth/login/ with bad password -> structured
    validation_error; correct credentials create a session;
    POST /api/auth/logout/ -> 204 (no Origin header from curl,
    so this path didn't exercise the CSRF Origin check -- see below).
  • GET /api/healthcheck/ -> 200; GET /admin/login/ -> 200;
    SPA pages (/, /login, /signup, /credits,
    /privacy-policy) -> 200.
  • createsuperuser works (docker compose run --rm django ...).
• Browser walk-through (host dev: make local-run-backend +
  make local-run-frontend, app at localhost:3000): signup ->
  /, login -> /, login with bad password shows the server
  error banner. Surfaced two things the curl smoke couldn't:
  login produced no visible nav change (-> commit 10), and
  logout failed with CSRF Failed: Origin checking failed
  (-> commit 11). Both verified fixed after.
  • One more pass: confirm the loading -> signed-in nav flip
    and inline RHF field errors look right (cosmetic; not blocking).

Follow-ups (out of scope for this PR)

• Proper signed-in nav: avatar / account menu / display name, once a
  Figma frame exists for it. Commit 10 ships an interim "Log out"
  button only; the logout action now has a consumer.
• Wire the (currently inert) mobile hamburger menu in HeaderNav.
• Hardening CSRF on anonymous signup / login (see caveat above).
• Phase 2 work: Cognito JWT verification, PeopleDepot integration.
• Inline field-level error display (err.fields) on the forms.
  Currently we surface err.message only.