When to Use
User needs to control what actions users can perform. Agent handles permission design, role hierarchies, policy evaluation, and access control middleware.
Quick Reference
| Topic | File |
|---|---|
| RBAC vs ABAC comparison | models.md |
| Implementation patterns | patterns.md |
| Framework middleware | middleware.md |
Core Rules
1. Auth ≠ Authorization
- Authentication: Who you are (login, OAuth, tokens)
- Authorization: What you can do (permissions, roles, policies)
- Never mix concerns — auth happens BEFORE authorization
2. Principle of Least Privilege
- Default deny — explicit grants only
- Users get minimum permissions for their job
- Audit permissions periodically (revoke unused)
- Temporary elevation over permanent grants
3. Choose the Right Model
| Model | Best For | Complexity |
|---|---|---|
| ACL | Simple resource ownership | Low |
| RBAC | Organizational hierarchies | Medium |
| ABAC | Dynamic context-based rules | High |
| ReBAC | Social graphs, sharing | High |
Start simple → evolve when needed.
4. Role Design Patterns
- Roles represent jobs, not permissions
- Max 3 inheritance levels (admin → manager → user)
- Avoid role explosion — combine with ABAC for edge cases
- Document role definitions (what can this role DO?)
5. Permission Naming
resource:action:scope
documents:write:own ← Can edit own documents
documents:write:team ← Can edit team documents
documents:delete:all ← Can delete any document
Consistent naming prevents ambiguity.
6. Policy Evaluation Order
- Explicit deny → always wins
- Explicit allow → checked second
- No match → default deny
- Log all denials for debugging
7. Never Hardcode
// ❌ Bad — hardcoded role check
if (user.role === 'admin') { ... }
// ✅ Good — permission check
if (can(user, 'settings:update')) { ... }
Roles change. Permissions are stable.
Common Traps
- Checking roles instead of permissions → brittle when roles change
- OR logic in permissions → "can edit OR is admin" creates backdoors
- Caching permissions too long → stale grants after role changes
- Frontend-only checks → always verify server-side
- God roles → split "admin" into specific permission sets
- Circular inheritance → A inherits B inherits A crashes system
Security & Privacy
Data that stays local:
- All documentation and patterns are reference material
- No data collection or external requests
This skill does NOT:
- Access your codebase automatically
- Make network requests
- Store any user data
Feedback
- If useful:
clawhub star authorization - Stay updated:
clawhub sync