refactor(auth): declarative route table [6/8]

[nourshoreibah]

Stack 6/8. Base is #345, not main. Largest handler in the repo (846 lines → 4) and the most security-sensitive. Pure reorganization; no behaviour change.

⚠️ Conflicts with open PR #325 (TOTP MFA) — see the sequencing note at the bottom before merging either.

Route table

Method	Pattern	Controller	Auth
POST	/auth/register	register.handleRegister	unauthenticated by design (invitation-gated)
POST	/auth/login	auth.handleLogin	unauthenticated by design
POST	/auth/respond-challenge	auth.handleRespondChallenge	unauthenticated by design (session-token gated)
POST	/auth/refresh	auth.handleRefresh	unauthenticated by design (refresh-token gated)
GET	/auth/me	auth.handleMe	authenticated
POST	/auth/verify-email	register.handleVerifyEmail	unauthenticated by design
POST	/auth/resend-code	register.handleResendCode	unauthenticated by design
POST	/auth/logout	auth.handleLogout	authenticated
POST	/auth/forgot-password	password.handleForgotPassword	unauthenticated by design
POST	/auth/reset-password	password.handleResetPassword	unauthenticated by design

Order preserved from the if chain. auth is the one service where most routes are deliberately public, so the table doubles as a readable audit of exactly which ones — which the old chain did not give you at a glance.

Gate confirmation

• GET /auth/me — unchanged. Still calls authenticateRequest(event) and 401s on !isAuthenticated || !user before touching the DB.
• POST /auth/logout — unchanged. Still requires the Authorization header locally, then relies on Cognito's own validation via GlobalSignOutCommand (401 on NotAuthorizedException). This route never called the shared authenticateRequest/requireAuth in the original either; that was preserved rather than "upgraded", since tightening it would be a behaviour change and belongs in its own PR.

Layout

• controllers/auth.ts — login, respond-challenge, refresh, me, logout (session lifecycle).
• controllers/register.ts — register, verify-email, resend-code.
• controllers/password.ts — forgot-password, reset-password.
• services/cognito.ts — cognitoClient, pool ids, CHALLENGE_SPECS, validatePassword, authResultResponse, challengeResponse, mapCognitoAuthError.
• Local json() and parseBody() deleted in favour of the shared ones.
• db.ts, auth.ts, swagger-utils.ts, dev-server.ts untouched.

handleLogout was inline in the original chain rather than a named function; it was extracted alongside login/refresh/me instead of getting a fourth controller file for one function. validatePassword moved byte-identical, comment intact — it mirrors the pool's password_policy in infrastructure/aws/cognito.tf.

Body parsing, deliberately inconsistent

handleLogin, handleRespondChallenge and handleRefresh use the shared parseBody, which is byte-identical to the deleted local one, so their 400 "Invalid JSON in request body" is unchanged.

handleRegister, handleVerifyEmail, handleResendCode, handleForgotPassword and handleResetPassword keep raw JSON.parse, because their malformed-JSON behaviour differs: a throw there falls through to a generic 500 rather than a local 400. Using parseBody would have changed those status codes. The underlying inconsistency (some routes 400, some 500 on bad JSON) is pre-existing and left alone — worth a follow-up, but not in a refactor.

Tests

• npx jest test/auth.unit.test.ts test/auth.login.unit.test.ts — 66/66.
• tsc --noEmit clean.
• test/auth.e2e.test.ts — 3 of 4 fail with TypeError: fetch failed; it needs the dev-server on :3000 plus live Postgres, neither started (five sibling conversions were running concurrently). Not claimed to pass; CI gets its own Postgres per lambda.

Sequencing against PR #325

PR #325 (TOTP MFA enrollment and login flow) adds challenge/enrollment routes to handler.ts and extends CHALLENGE_SPECS. This PR gutted handler.ts to one line and moved CHALLENGE_SPECS into services/cognito.ts, so the two will conflict for real — not textually resolvable by rerunning a merge.

Whoever lands second re-applies their change against the new shape: route additions go in routes.ts, challenge-spec additions in services/cognito.ts, handler bodies in controllers/auth.ts. Recommendation: land #325 first, since it is feature work with a deadline shape and this is a refactor that can rebase cheaply.

Stack-wide note: unmatched paths now 404 instead of 401

Previously the top-level auth check ran before route matching, so an unauthenticated request to a nonexistent path got 401. dispatch returns 404 centrally without running auth, so an unauthenticated caller can now distinguish "route exists" (401) from "route doesn't" (404). Accepted deliberately — the route inventory is already in the repo's openapi.yaml files, and auth-before-routing is exactly what forces each lambda to hand-roll public-route exemptions. Least consequential here, where nine of ten routes are public by design.

Noticed, not fixed

auth/openapi.yaml still uses prefix-stripped paths (/login, /register) while the route table uses full-prefixed patterns (/auth/login). A spelling-convention mismatch, not a functional one — dispatch canonicalizes either way. PR 8/8 normalizes the specs.

🤖 Generated with Claude Code