hard: role-gated endpoints trust stale JWT role claims

[Godfrey-Delight]

🔗 Related Issue

Closes #122

---

🔖 Title

feat(auth): enforce server-truth role authorization and add audited admin role reset

---

📝 Description

Centralized role-based authorization on server truth rather than un-enforced JWT role claims. RolesGuard now resolves live user roles from the datastore via UserStatusService (cached in-memory with a documented 30-second staleness bound), preventing stale-token attacks where a downgraded user retains role access until token expiration. Added an admin-only role-management endpoint (POST /admin/users/:wallet/role/reset) allowing role resets and overrides with full audit logging via AuditInterceptor. Role changes automatically invalidate the server-side status cache for immediate effect.

---

🔄 Changes Made

• Server-Truth Authorization: Extended UserStatusService to cache status and role (getUserState, getRole). Updated RolesGuard to enforce datastore roles rather than trusting JWT claims.
• Cache Invalidation: Injected UserStatusService into UsersService and wired userStatusService.invalidate(wallet) into setRole() so role selection updates immediately.
• Admin Role Reset Endpoint: Created AdminRolesController exposing POST /admin/users/:wallet/role/reset, guarded by JwtAuthGuard & AdminGuard, and audited via @AuditAction('admin_users', 'RESET_USER_ROLE') and AuditInterceptor.
• Repository Layer: Added UsersRepository.forceSetRole(wallet, role) to allow admin role overrides and resets.
• Module Wiring: Exported RolesGuard and UserStatusService from AuthModule and imported AuthModule in UsersModule, VouchingModule, and AdminModule.
• Unit Tests: Added test suites for RolesGuard (roles.guard.spec.ts), AdminRolesController (admin-roles.controller.spec.ts), and updated users.service.spec.ts & vendors.service.spec.ts.
• Documentation: Updated context/progress-tracker.md.

---

📸 Screenshots (if applicable)

N/A (Backend API logic change)

---

🗒️ Additional Notes

• npm run build passed cleanly with 0 TypeScript compilation errors.
• npm test passed with 34/34 test suites green (388/388 total tests passing).
• Staleness bound is set to 30 seconds (USER_STATUS_CACHE_TTL_MS = 30_000), matching account blocking enforcement.

[EmeditWeb]

⚠️ Automated Audit: partial

@Godfrey-Delight Good start — please look into the gaps identified below.

The PR genuinely addresses the root cause of Issue #122: RolesGuard now resolves live user roles from the datastore via UserStatusService (30s cached) instead of trusting JWT claims, admin role reset endpoint exists with audit logging, cache invalidation is wired into role changes, and regression tests cover the stale-token attack path. However, context/progress-tracker.md contains unresolved merge conflict markers (<<<<<<< Updated upstream / ======= / >>>>>>> Stashed changes) which is a blockable defect and indicates the change was not properly landed.

Gaps identified:

• Unresolved git merge conflict markers in context/progress-tracker.md (<<<<<<< Updated upstream / ======= / >>>>>>> Stashed changes) — must be resolved before merge

---

CI checks: ✅ PASSED: build-test

_{Audited by stepfi-audit-bot 🤖}