Phase 1.d — Wire Better Auth JWKS → waveflow-server JWT verification

[InstaZDLL]

Tracking issue for sub-phase 1.d of RFC-001.

Replace the dev-mode X-User-Id header from 1.b with real JWT verification against the JWKS exposed by waveflow-web/Better Auth (1.c). End-to-end authenticated requests from web → server.

Scope

• waveflow-server side:
  • jsonwebtoken crate for verification.
  • JWKS fetcher with TTL cache (1h, configurable). Background refresh loop.
  • axum extractor AuthenticatedUser that:
    1. Pulls Authorization: Bearer <token> header.
    2. Verifies signature against cached JWKS.
    3. Validates exp, iat, iss, aud.
    4. Extracts sub (= user_id UUID) and scope claims.
  • All CRUD endpoints from 1.b switched from X-User-Id to AuthenticatedUser.
  • Graceful 401 response with WWW-Authenticate: Bearer header.
• waveflow-web side:
  • Server-side fetch helper that auto-includes the JWT from the active session.
  • Refresh token flow: when a 401 hits, transparently refresh and retry once.

JWKS rotation runbook (deliverable)

• Cache TTL = 1h.
• Keys rotate quarterly.
• Overlap window = 1 week (old + new keys both valid).
• Documented in docs/operations/jwks-rotation.md (new file in waveflow-server).

Dependencies

• Blocks on: 1.b (CRUD endpoints exist) + 1.c (JWKS endpoint live).

Acceptance criteria

• curl -H \"Authorization: Bearer <jwt>\" http://server/profiles returns 200; without header returns 401.
• Expired token → 401 with Bearer error=\"invalid_token\".
• JWKS rotation test: rotate keys on web side, server picks up new key within cache TTL.
• Refresh-token round-trip from web → server tested.
• JWKS rotation runbook documented.

Estimate

~2 weeks.