fix(auth): register the error handler before routes so it actually runs

[EsTharian]

Fixes #365

The app-level setErrorHandler was registered after both @fastify/autoload calls, under a comment claiming the last position "catches all unhandled errors". It is backwards — a route does not resolve its error handler at request time. Fastify snapshots it while closing the route's enclosing plugin (context.errorHandler = this[kErrorHandler] in the after() callback of fastify/lib/route.js:376-379), and avvio runs queued plugins in registration order. The handler was unreachable from every route, and Fastify's built-in {statusCode, code, error, message} envelope answered every error.

What was silently reverted

• The F-01 register-enumeration fix (PR feat(oauth): pre-launch security hardening #212). UniqueConstraintError is genericised so the DB constraint name never reaches the wire; the built-in envelope echoes error.message, which embeds it.
• RFC 6750 §3 — the WWW-Authenticate: Bearer challenge a bearer-protected resource such as /oauth/userinfo MUST return on a 401.
• RFC 6749 §5.2 OAuth error shapes.
• error_description sanitisation for that challenge header.

Changes

• Move errorHandler registration ahead of cors, not merely ahead of the two AutoLoads. @fastify/cors registers an options('*') route of its own (index.js:79), and @fastify/rate-limit throws its 429 from an earlier onRequest hook, so a rate-limited OPTIONS request would otherwise still render the built-in shape.
• Correct the surrounding ordering comments, which asserted guarantees Fastify does not provide, and record the ones that are genuinely load-bearing:
  • rateLimitPlugin MUST precede the routes AutoLoad — it applies per-route limits through an onRoute hook, and fastify.js:599 routes onRoute past the kChildren recursion in _addHook, so it is not retroactive. Moving it would silently drop the /auth/login brute-force ceiling with no error, warning or boot check. This carried no comment before.
  • securityHeaders / requestId positions are not load-bearing — but via _addHook's recursion into existing child scopes (fastify.js:613-616), not via preReady, which reads a snapshot. The old comments credited the wrong mechanism; the distinction is exactly what separates them from onRoute.
  • main.ts:59-60's validator/serializer compilers MUST precede register(app). A child scope snapshots them at creation with no propagation, so moving them into start() would return every route to ajv validation and reactivate the fast-uri host-confusion advisories (CVE-2026-13676, CVE-2026-16221) that the SECURITY INVARIANT comment says are inert because no request touches ajv. Same failure mode as this issue, with a CVE behind it. Code was already correct; the position requirement is now stated.

Testing

The reason this shipped is in the issue: apps/auth-server's route tests build stubbed Fastify objects, and error-handler.test.ts exercises the handler in isolation where it works correctly. Nothing asserted it was reachable.

apps/auth-server/src/app/error-handler-wiring.test.ts registers the real app plugin and injects over HTTP:

Test	Criterion
(a) POST /oauth/token invalid body returns the custom validation shape, not FST_ERR_VALIDATION	a, d
(b) unauthenticated GET /oauth/userinfo carries an RFC 6750 §3 WWW-Authenticate: Bearer challenge	b, d
(c) a UniqueConstraintError is genericised — the constraint name never reaches the wire (F-01)	c
(d) no autoloaded route answers with the built-in envelope (11-route sweep)	d

Verified in both directions: with the fix, 74 files / 1397 tests pass. With the registration moved back below the AutoLoads, (a), (b) and (d) fail with exactly code: 'FST_ERR_VALIDATION' and a missing WWW-Authenticate.

(c) is deliberately not an ordering guard and stays green under the reintroduced bug — any route added from outside app() inherits the final handler either way. The guard is (a)/(b)/(d) against the real autoloaded routes. This is documented in the file so it is not later misread as the F-01 regression guard.

Reviewer notes

• Scope is wider than apps/auth-server. The root vitest.config.ts gains one server.deps.inline: ['@fastify/autoload'] entry — autoload resolves route modules by absolute path at runtime, which Vite cannot otherwise resolve. It is at the workspace root rather than project-local because the root qauth:test target runs a bare vitest run that globs every project's specs, auth-server's included. nx run-many -t test passes for all 18 projects.
• The suite forces RATE_LIMIT_ENABLED=false — the limiter's store is Redis, and an unreachable Redis kills every request in its onRequest hook with a uniform 500 that hides every response under test. DATABASE_URL/REDIS_URL point at 127.0.0.1:1 deliberately so the suite can never touch a live database.

Follow-ups (not in this PR)

• mcp-guard's sendBearerChallenge JSDoc @example tells host apps to call setErrorHandler with no ordering warning — the same defect shipped as library documentation.
• Swagger's /docs routes and the default 404 context live on the root instance in main.ts, so they resolve the root's error handler and never reach this one. Not a regression; recorded so this fix is not over-read as "every response now goes through error-handler.ts".

🤖 Generated with Claude Code

https://claude.ai/code/session_01DWdz6Yd57TV48dTbVCej6j