Feature: Role-based access control (RBAC) with permission scopes in JWT claims

[hoangsonww]

Why

The module currently supports authentication but not authorization. Downstream services need a standard way to enforce role/permission checks from tokens.

Proposal

Add first-class RBAC + permission scope support:

• Roles (e.g., user, admin, support)
• Fine-grained scopes (e.g., profile:read, users:write)
• Claims embedded in access tokens
• Middleware helpers: requireRole(...) and requireScope(...)

Scope

• Role + scope models in domain layer
• APIs to assign/revoke roles and scopes
• Include role/scope claims in access token issuance and refresh
• Keep refresh token minimal (no large authz payload)

API Additions (proposed)

• GET /auth/me/permissions
• PATCH /auth/me/roles (admin-protected)
• PATCH /auth/me/scopes (admin-protected)

Technical Notes

• Add claim versioning to allow future authz claim evolution
• Validate that removed permissions take effect on next token refresh (or via forced re-issue)
• Provide middleware error codes: INSUFFICIENT_ROLE, INSUFFICIENT_SCOPE

Acceptance Criteria

• Access tokens contain normalized role/scope claims
• Middleware correctly enforces role/scope checks
• Revoking a role/scope invalidates authorization after token renewal
• Unit + API tests cover positive/negative authorization paths
• README includes authz usage examples for route protection

Out of Scope

• Policy language engine (e.g., OPA/Cedar)
• Attribute-based access control (ABAC)