feat(backend): JWT Authentication & RBAC with Refresh Token Rotation (#23)

[jayteemoney]

Closes #23.

What this adds

Spring Security JWT authentication with role-based authorization and secure refresh-token rotation (revocation + reuse detection) for backend-api. Full design notes: backend-api/docs/AUTHENTICATION.md.

Flow: register → login → refresh (rotate) → logout, plus /me and an ADMIN-gated demo endpoint.

Key design decisions

• Dedicated UserAccount principal (email + bcrypt hash + Role), separate from the Client/SkilledWorker domain entities, so the existing (messy) domain login/registration is left untouched. The legacy JwtUtils/ClientServiceImpl.login stub is intentionally not modified — migrating it onto this flow is a documented follow-up.
• Access token = short-lived HS256 JWT (sub/email/role claims) → per-request authorization needs no DB hit. Refresh token = opaque 256-bit secret, stored only as a SHA-256 hash (a DB leak exposes no usable tokens).
• Rotation + reuse detection: each refresh revokes the presented token and issues a successor in the same family (session lineage). Replaying an already-revoked token revokes the whole family, killing the session.
• Reuse revoke runs in a REQUIRES_NEW transaction. Detection happens in rotate(), which then throws to signal the caller — and that throw would otherwise roll back the revocation. This was a real bug the integration test caught before it could ship.
• Concurrency-safe: revoke-old is an atomic conditional UPDATE … WHERE revoked=false, so two simultaneous refreshes can't both mint a successor; the loser is treated as reuse.
• No privilege escalation: self-registration can only create CLIENT/SKILLED_WORKER, never ADMIN.
• RBAC via URL rules + @EnableMethodSecurity/@PreAuthorize (/api/v1/admin/** → hasRole('ADMIN')).
• Consistent error contract { error, success:false } across 400/401/403/409, including filter-level 401/403 via custom entry-point / access-denied handlers.

Acceptance criteria

• ✅ Implements the objective — JWT auth + RBAC + refresh rotation with revocation & reuse detection.
• ✅ No failing tests / compilation errors — full suite green (see below).
• ✅ Failure & concurrency paths covered — reuse → 401, race-loss, wrong password, expired/unknown token, RBAC 403; plus a real multi-threaded concurrent-refresh test asserting at most one winner and a fully-revoked family.
• ✅ OpenAPI documented + consistent error contract — springdoc Swagger UI at /swagger-ui.html; uniform {error, success} responses.
• ✅ Maven dependency caching in CI — already present via actions/setup-java cache: maven in test.yml (the CI already runs a Postgres service the integration tests use).

Verification (run locally against Postgres 16)

• ./mvnw test — 43 passed, 0 failed
• ./mvnw verify — BUILD SUCCESS (jar built + repackaged)

Tests: unit (JwtServiceTest, RefreshTokenServiceTest) run without a DB; AuthIntegrationTest (@SpringBootTest + MockMvc) runs against the CI Postgres service.

New dependencies

• spring-boot-starter-validation — @Valid on request DTOs
• springdoc-openapi-starter-webmvc-ui:2.6.0 — OpenAPI 3 + Swagger UI

Notes for reviewers

• New tables (user_accounts, refresh_tokens) are created by Hibernate (ddl-auto=update).
• JWT_SECRET ships with a dev-only placeholder default; it must be overridden in real environments (documented).
• No changes to existing endpoints — the previously public client/skilledWorker routes remain permitAll, so current behaviour and tests are unaffected.

🤖 Generated with Claude Code

[meshackyaro]

Security is an integral part of this SaaS project and I can see that it was handled properly.

Well done @jayteemoney. Thanks for your contribution