authorization

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