hoangsonww / hoangsonww/JWT-Module

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

Open
#3 0 comments 0 reactions 1 assignee Claimed by @hoangsonww View on GitHub
bug documentation duplicate enhancement good first issue help wanted
Dominant language
TypeScript
Stars
12
Forks
6
PR merge metrics
No merged PRs in 30d

Description

## 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)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.