Role & Permission Design
Purpose
Design the role authorization and permission authorization layers: which roles exist, which permissions they grant, how they're stored and checked, and how the model evolves without a rewrite.
When to Use
- When the system has more than one class of user (user/admin, staff tiers, plan tiers).
- Not for per-resource access — ownership/tenant/object checks are
ownership-authorization, layered on top of roles.
Inputs
- Authorization matrix (
backend-authorization), user classes from requirements.
- Session/claims mechanism (
backend-authentication).
Discovery Questions
- What action classes exist, and which user classes may perform each?
- Are plain roles enough, or do features need individual permissions (role = permission bundle)?
- Can one user hold multiple roles? Do roles vary per organization (tenant-scoped roles)?
- Who assigns roles, and is assignment itself an admin-only, audited action?
Responsibilities
- Derive the minimal role set from real action classes — not speculative hierarchies.
- Decide granularity: role checks alone (small systems) vs permission checks with roles as bundles (checks stay stable while bundles evolve — prefer this once actions multiply).
- Define storage: roles/permissions in the database as data; claims in session/token as a cache of that data (with a staleness/refresh story if cached).
- Specify the check API: one central
can(user, action) / guard — call sites never string-compare roles ad hoc.
- Design role assignment/removal as audited admin actions; protect against self-escalation.
- In multi-tenant systems, scope roles per organization membership (a user can be admin of org A, member of org B) — coordinate with
ownership-authorization.
Required Workflow
- List action classes; map user classes → allowed actions.
- Choose role-only vs role+permission granularity; record why.
- Define storage, claims, and staleness handling.
- Define the central check API and wire it into guards/policies.
- Specify negative tests: non-admin cannot perform each admin action; role change takes effect (and revocation propagates).
Decision Rules
- Check permissions at call sites when granularity is needed; roles remain the assignment unit.
- Never encode business rules in role names ("premium_user_v2") — map plans/features to permissions.
- Role claims cached in a JWT need a refresh/invalidation story; demotion must actually demote (
backend-authentication lifecycle).
- Default role for new users is the least-privileged one.
Rules
- Server-side data is the source of truth; client-asserted roles are never read.
- Role assignment is itself permission-gated and audited.
- Every admin surface/endpoint appears in the authorization matrix with its role/permission requirement.
Anti-Patterns
- Hardcoded
role === 'admin' string checks scattered through handlers.
- A role explosion (per-feature roles) instead of permissions.
- Roles in the JWT with no expiry/refresh, making demotion cosmetic.
- Assuming role checks cover per-resource access (they don't — IDOR remains).
- Letting users set their own role at signup via mass assignment (
backend-validation).
Validation Checklist
Definition of Done
A recorded role/permission model — role set, granularity rationale, storage/claims, central check API, audited assignment — with negative tests proving non-admins are rejected and demotion propagates.
Related Skills
backend-authorization, ownership-authorization, backend-authentication, backend-validation, backend-integration-testing, ../../security-review.
Related Knowledge
../../../knowledge/ (user classes, plan/feature mapping).
Related References
../../../references/backend/auth/ (role matrix, when populated).
Context Loading Guidance
- Requires: action classes, user classes, claims mechanism.
- Does not require: resource ownership model (separate skill), UI role gating.
- May load:
backend-authorization (matrix), ownership-authorization (tenant-scoped roles).
- Stop when: the model + check API + negative tests are recorded.
Token Efficiency Guidance
The role/permission × action table is the artifact; keep prose to the granularity and staleness decisions.
1---2name: role-permission-design3description: Use to design the role and permission model — role set, permission granularity, role→permission mapping, storage/claims, admin surfaces, and evolution. Roles gate action classes; ownership/tenant checks remain separate.4---56# Role & Permission Design78## Purpose910Design the **role authorization** and **permission authorization** layers: which roles exist, which permissions they grant, how they're stored and checked, and how the model evolves without a rewrite.1112## When to Use1314- When the system has more than one class of user (user/admin, staff tiers, plan tiers).15- **Not** for per-resource access — ownership/tenant/object checks are `ownership-authorization`, layered on top of roles.1617## Inputs1819- Authorization matrix (`backend-authorization`), user classes from requirements.20- Session/claims mechanism (`backend-authentication`).2122## Discovery Questions2324- What action classes exist, and which user classes may perform each?25- Are plain roles enough, or do features need individual permissions (role = permission bundle)?26- Can one user hold multiple roles? Do roles vary per organization (tenant-scoped roles)?27- Who assigns roles, and is assignment itself an admin-only, audited action?2829## Responsibilities3031- Derive the **minimal role set** from real action classes — not speculative hierarchies.32- Decide granularity: role checks alone (small systems) vs **permission checks with roles as bundles** (checks stay stable while bundles evolve — prefer this once actions multiply).33- Define storage: roles/permissions in the database as data; claims in session/token as a cache of that data (with a staleness/refresh story if cached).34- Specify the check API: one central `can(user, action)` / guard — call sites never string-compare roles ad hoc.35- Design role assignment/removal as audited admin actions; protect against self-escalation.36- In multi-tenant systems, scope roles per organization membership (a user can be admin of org A, member of org B) — coordinate with `ownership-authorization`.3738## Required Workflow39401. List action classes; map user classes → allowed actions.412. Choose role-only vs role+permission granularity; record why.423. Define storage, claims, and staleness handling.434. Define the central check API and wire it into guards/policies.445. Specify negative tests: non-admin cannot perform each admin action; role change takes effect (and revocation propagates).4546## Decision Rules4748- Check **permissions** at call sites when granularity is needed; roles remain the assignment unit.49- Never encode business rules in role names ("premium_user_v2") — map plans/features to permissions.50- Role claims cached in a JWT need a refresh/invalidation story; demotion must actually demote (`backend-authentication` lifecycle).51- Default role for new users is the least-privileged one.5253## Rules5455- Server-side data is the source of truth; client-asserted roles are never read.56- Role assignment is itself permission-gated and audited.57- Every admin surface/endpoint appears in the authorization matrix with its role/permission requirement.5859## Anti-Patterns6061- Hardcoded `role === 'admin'` string checks scattered through handlers.62- A role explosion (per-feature roles) instead of permissions.63- Roles in the JWT with no expiry/refresh, making demotion cosmetic.64- Assuming role checks cover per-resource access (they don't — IDOR remains).65- Letting users set their own role at signup via mass assignment (`backend-validation`).6667## Validation Checklist6869- [ ] Role set derived from real action classes.70- [ ] Granularity decision (role vs permission) recorded.71- [ ] Storage + claims + staleness handling defined.72- [ ] Central check API defined; no ad-hoc string checks.73- [ ] Assignment audited and escalation-protected.74- [ ] Negative tests: each admin action rejected for non-admins; demotion effective.7576## Definition of Done7778A recorded role/permission model — role set, granularity rationale, storage/claims, central check API, audited assignment — with negative tests proving non-admins are rejected and demotion propagates.7980## Related Skills8182`backend-authorization`, `ownership-authorization`, `backend-authentication`, `backend-validation`, `backend-integration-testing`, `../../security-review`.8384## Related Knowledge8586`../../../knowledge/` (user classes, plan/feature mapping).8788## Related References8990`../../../references/backend/auth/` (role matrix, when populated).9192## Context Loading Guidance9394- **Requires:** action classes, user classes, claims mechanism.95- **Does not require:** resource ownership model (separate skill), UI role gating.96- **May load:** `backend-authorization` (matrix), `ownership-authorization` (tenant-scoped roles).97- **Stop when:** the model + check API + negative tests are recorded.9899## Token Efficiency Guidance100101The role/permission × action table is the artifact; keep prose to the granularity and staleness decisions.
ahtishamshahzad