Skip to content

Commit f4e059a

Browse files
devondragondevondragon
authored
Merge pull request #32 from devondragon/issue-16-Add-Authorization-Functionality---Roles-and-Permissions
feat: Complete RBAC system with audit logging, caching, and tests
2 parents 5e04a24 + 95d9bb4 commit f4e059a

49 files changed

Lines changed: 22734 additions & 5797 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CLAUDE.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ This is a Cloudflare Workers-based user management framework that provides serve
1111
- **Session Management**: Service-to-service communication between workers
1212
- **Database**: D1 for user data persistence, KV for session storage
1313
- **API Design**: RESTful endpoints with CORS support for cross-origin requests
14+
- **RBAC System**: Optional role-based access control with hierarchical permissions
1415

1516
## Commands
1617
### Development
@@ -72,6 +73,11 @@ workers-users/
7273
- `EMAIL_DKIM_DOMAIN`: Domain for DKIM signing
7374
- `FORGOT_PASSWORD_URL`: Reset password page URL
7475
- `TOKEN_VALID_MINUTES`: Password reset token validity (default: 60)
76+
- `RBAC_ENABLED`: Enable role-based access control (default: false)
77+
- `RBAC_DEFAULT_ROLE`: Default role for new users (optional)
78+
- `SUPER_ADMIN_EMAIL`: Email for initial admin user (optional)
79+
- `SUPER_ADMIN_EMAIL_CONFIRMED`: Must be "true" to confirm admin email ownership before bootstrap (security feature)
80+
- `LOG_IP_ADDRESS`: Enable IP address logging in audit logs (GDPR consideration - default: false)
7581

7682
### Bindings
7783
- **D1 Database**: `usersDB` - User data storage
@@ -88,6 +94,18 @@ workers-users/
8894
- `POST /forgot-password-new-password` - Update password
8995
- `GET /load-user` - Get current user data
9096

97+
### RBAC Endpoints (when RBAC_ENABLED=true)
98+
- `GET /api/roles` - List all roles
99+
- `GET /api/roles/:roleId` - Get role details
100+
- `POST /api/roles` - Create new role
101+
- `PUT /api/roles/:roleId` - Update role
102+
- `DELETE /api/roles/:roleId` - Delete role
103+
- `GET /api/users/:userId/roles` - Get user's roles
104+
- `POST /api/users/:userId/roles` - Assign role to user
105+
- `DELETE /api/users/:userId/roles/:roleId` - Remove role from user
106+
- `GET /api/users/:userId/permissions` - Get user's effective permissions
107+
- `POST /api/permissions/check` - Check specific permissions
108+
91109
### session-state Worker
92110
- `POST /create` - Create new session
93111
- `GET /get/:sessionId` - Retrieve session data

‎RBAC-Implementation-Summary.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# RBAC Implementation Summary
2+
3+
## Overview
4+
The Role-Based Access Control (RBAC) system has been successfully implemented for the Cloudflare Workers Users Framework. The implementation is fully optional, lightweight, and maintains backward compatibility.
5+
6+
## What Was Implemented
7+
8+
### 1. Database Schema (Phase 1)
9+
- ✅ Created migration file `002-rbac.sql` with 4 new tables:
10+
- `roles` - Role definitions
11+
- `permissions` - Permission definitions
12+
- `user_roles` - User-to-role assignments
13+
- `role_permissions` - Role-to-permission mappings
14+
- ✅ Default roles: SUPER_ADMIN, MEMBER
15+
- ✅ Default permissions: admin:all, users:read/write/delete, roles:read/write/assign
16+
- ✅ Migration script `003-assign-default-roles.sql` for existing users
17+
18+
### 2. Environment Configuration (Phase 1)
19+
- ✅ Added `RBAC_ENABLED` and `SUPER_ADMIN_EMAIL` to wrangler.toml
20+
- ✅ Updated TypeScript environment interface
21+
- ✅ Created RBAC types in `src/types/rbac.ts`
22+
23+
### 3. Core RBAC Functions (Phase 2)
24+
- ✅ Created `src/rbac/permissions.ts`:
25+
- `getUserPermissions()` - Get all permissions for a user
26+
- `hasPermission()` - Check if user has a specific permission
27+
- `getUserRoles()` - Get all roles for a user
28+
- ✅ Created `src/rbac/roles.ts`:
29+
- `assignRole()` - Assign a role to a user
30+
- `removeRole()` - Remove a role from a user
31+
- `createRole()` - Create a new role
32+
- `assignDefaultRole()` - Assign MEMBER role to new users
33+
34+
### 4. Session Enhancement (Phase 2)
35+
- ✅ Updated session creation to include permissions when RBAC is enabled
36+
- ✅ Modified user registration to assign default MEMBER role
37+
- ✅ Enhanced session data structure with permissions array
38+
39+
### 5. Authorization Middleware (Phase 3)
40+
- ✅ Created `src/middleware/session.ts`:
41+
- `withSession()` - Load session data from session-state worker
42+
- `withOptionalSession()` - Optional session loading
43+
- ✅ Created `src/middleware/rbac.ts`:
44+
- `requirePermission()` - Check for specific permission
45+
- `requireAnyPermission()` - OR logic for multiple permissions
46+
- `requireAllPermissions()` - AND logic for multiple permissions
47+
- `requireAuth()` - Simple authentication check
48+
49+
### 6. Management APIs (Phase 4)
50+
- ✅ Created `src/handlers/rbac.ts` with endpoints:
51+
- GET `/rbac/roles` - List all roles
52+
- POST `/rbac/roles` - Create new role
53+
- GET `/rbac/permissions` - List all permissions
54+
- GET `/rbac/users/:userId/roles` - Get user's roles
55+
- POST `/rbac/users/:userId/roles` - Assign role to user
56+
- DELETE `/rbac/users/:userId/roles/:roleId` - Remove role from user
57+
- ✅ Updated router to conditionally register RBAC routes
58+
59+
### 7. Additional Features
60+
- ✅ Admin bootstrapping via `SUPER_ADMIN_EMAIL` environment variable
61+
- ✅ Updated `/load-user` endpoint to include roles when RBAC is enabled
62+
- ✅ Bootstrap runs once on worker startup
63+
64+
### 8. Documentation (Phase 5)
65+
- ✅ Created comprehensive `RBAC.md` with:
66+
- Configuration guide
67+
- Migration instructions
68+
- API documentation
69+
- Usage examples
70+
- Troubleshooting guide
71+
- ✅ Updated `README.md` with RBAC section
72+
- ✅ Updated `CLAUDE.md` with RBAC information
73+
74+
## Key Design Decisions
75+
76+
1. **Optional by Default**: RBAC is disabled unless explicitly enabled via `RBAC_ENABLED=true`
77+
2. **Performance Optimized**: Permissions are cached in session to avoid repeated D1 queries
78+
3. **Flexible Permission Model**: Uses `resource:action` format (e.g., "users:read")
79+
4. **Backward Compatible**: Existing deployments work unchanged
80+
5. **Middleware-Based**: Clean integration with itty-router for route protection
81+
82+
## How to Enable RBAC
83+
84+
1. Run the database migration:
85+
```bash
86+
npx wrangler d1 execute users --file=./migrations/002-rbac.sql --remote
87+
```
88+
89+
2. Assign default roles to existing users:
90+
```bash
91+
npx wrangler d1 execute users --file=./migrations/003-assign-default-roles.sql --remote
92+
```
93+
94+
3. Update wrangler.toml:
95+
```toml
96+
RBAC_ENABLED = "true"
97+
SUPER_ADMIN_EMAIL = "admin@example.com"
98+
```
99+
100+
4. Deploy the worker:
101+
```bash
102+
npm run deploy
103+
```
104+
105+
## Testing the Implementation
106+
107+
1. Register a new user - they will automatically get the MEMBER role
108+
2. The super admin will be assigned on first request after deployment
109+
3. Use the `/load-user` endpoint to see roles and permissions
110+
4. Try accessing RBAC management endpoints with different permission levels
111+
112+
## Files Created/Modified
113+
114+
### New Files:
115+
- `/packages/user-mgmt/migrations/002-rbac.sql`
116+
- `/packages/user-mgmt/migrations/003-assign-default-roles.sql`
117+
- `/packages/user-mgmt/src/types/rbac.ts`
118+
- `/packages/user-mgmt/src/rbac/permissions.ts`
119+
- `/packages/user-mgmt/src/rbac/roles.ts`
120+
- `/packages/user-mgmt/src/rbac/bootstrap.ts`
121+
- `/packages/user-mgmt/src/rbac/index.ts`
122+
- `/packages/user-mgmt/src/middleware/session.ts`
123+
- `/packages/user-mgmt/src/middleware/rbac.ts`
124+
- `/packages/user-mgmt/src/middleware/index.ts`
125+
- `/packages/user-mgmt/src/handlers/rbac.ts`
126+
- `/RBAC.md`
127+
128+
### Modified Files:
129+
- `/packages/user-mgmt/wrangler.toml`
130+
- `/packages/user-mgmt/src/env.ts`
131+
- `/packages/user-mgmt/src/session.ts`
132+
- `/packages/user-mgmt/src/utils.ts`
133+
- `/packages/user-mgmt/src/handlers.ts`
134+
- `/packages/user-mgmt/src/index.ts`
135+
- `/README.md`
136+
- `/CLAUDE.md`
137+
138+
## Next Steps
139+
140+
1. Test the implementation thoroughly
141+
2. Consider creating an admin UI for role/permission management
142+
3. Add audit logging for permission changes
143+
4. Implement session revocation for immediate permission updates
144+
5. Add more granular permissions as needed
145+
146+
The RBAC system is now fully implemented and ready for use!

‎RBAC-Plan.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# RBAC (Role-Based Access Control) Implementation Plan
2+
3+
## Executive Summary
4+
5+
This document outlines the plan to add an optional, lightweight Role-Based Access Control system to the Cloudflare Workers Users Framework. The RBAC system will be completely optional, ensuring zero impact on existing deployments while providing powerful authorization capabilities for applications that need them.
6+
7+
## High-Level Design
8+
9+
### Core Principles
10+
1. **Optional by Default**: RBAC is disabled unless explicitly enabled via environment variable
11+
2. **Zero Breaking Changes**: Existing deployments continue working without modification
12+
3. **Performance-First**: Permissions cached in session to avoid repeated database queries
13+
4. **Simple Yet Flexible**: Resource:action permission model (e.g., "users:read", "posts:write")
14+
5. **Developer-Friendly**: Easy to understand, configure, and use
15+
16+
### Architecture Overview
17+
18+
```
19+
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
20+
│ account-pages │────▶│ user-mgmt │────▶│ session-state │
21+
│ (Frontend) │ │ (Worker) │ │ (Worker) │
22+
└─────────────────┘ └─────────────────┘ └─────────────────┘
23+
│ │
24+
▼ ▼
25+
┌─────────────┐ ┌─────────────┐
26+
│ D1 Database │ │ KV Store │
27+
│ + RBAC Tables│ │ + Permissions│
28+
└─────────────┘ └─────────────┘
29+
```
30+
31+
### Key Components
32+
33+
1. **Environment Variable**: `RBAC_ENABLED=true` to enable the feature
34+
2. **Database Schema**: Four new tables (roles, permissions, user_roles, role_permissions)
35+
3. **Session Enhancement**: Permissions cached in session data for performance
36+
4. **Middleware**: `requirePermission()` middleware for route protection
37+
5. **Default Setup**: Two default roles (SUPER_ADMIN, MEMBER) with predefined permissions
38+
39+
## Implementation Approach
40+
41+
### Phase 1: Database and Core Infrastructure
42+
- Create RBAC database schema with migrations
43+
- Implement core permission checking functions
44+
- Add environment variable support
45+
46+
### Phase 2: Session Integration
47+
- Enhance session creation to include user permissions
48+
- Modify session data structure to cache permissions
49+
- Update session-state worker to handle enhanced sessions
50+
51+
### Phase 3: Authorization Middleware
52+
- Create permission checking middleware
53+
- Add middleware to protect existing endpoints (optional)
54+
- Implement permission utilities
55+
56+
### Phase 4: Management APIs
57+
- Create RBAC management endpoints (/rbac/*)
58+
- Add role assignment functionality
59+
- Implement permission management
60+
61+
### Phase 5: Migration and Documentation
62+
- Create migration scripts for existing users
63+
- Write comprehensive documentation
64+
- Add example implementations
65+
66+
## Detailed Task List
67+
68+
### 1. Database Schema Tasks
69+
- [ ] Create migration file `002-rbac.sql` with RBAC tables
70+
- [ ] Create `roles` table (id, name, description)
71+
- [ ] Create `permissions` table (id, name, description)
72+
- [ ] Create `user_roles` junction table
73+
- [ ] Create `role_permissions` junction table
74+
- [ ] Add default data migration
75+
- [ ] Insert default permissions (admin:all, users:read, users:write, etc.)
76+
- [ ] Insert default roles (SUPER_ADMIN, MEMBER)
77+
- [ ] Assign permissions to default roles
78+
- [ ] Create indexes for performance optimization
79+
80+
### 2. Environment Configuration Tasks
81+
- [ ] Add `RBAC_ENABLED` to user-mgmt `wrangler.toml`
82+
- [ ] Add `SUPER_ADMIN_EMAIL` for bootstrapping first admin
83+
- [ ] Update `Env` interface in TypeScript with new variables
84+
- [ ] Add RBAC configuration to CLAUDE.md
85+
86+
### 3. Type Definition Tasks
87+
- [ ] Create `types/rbac.ts` with RBAC-specific types
88+
- [ ] Define `Role` interface
89+
- [ ] Define `Permission` interface
90+
- [ ] Define `UserRole` interface
91+
- [ ] Update `SessionData` type to include permissions array
92+
- [ ] Add RBAC response types for API endpoints
93+
94+
### 4. Core RBAC Functions
95+
- [ ] Create `src/rbac/permissions.ts`
96+
- [ ] Implement `getUserPermissions(userId)` function
97+
- [ ] Implement `hasPermission(permissions, required)` function
98+
- [ ] Implement `getUserRoles(userId)` function
99+
- [ ] Create `src/rbac/roles.ts`
100+
- [ ] Implement `assignRole(userId, roleId)` function
101+
- [ ] Implement `removeRole(userId, roleId)` function
102+
- [ ] Implement `createRole(name, description)` function
103+
104+
### 5. Session Enhancement Tasks
105+
- [ ] Update session creation in `user-mgmt/src/session.ts`
106+
- [ ] Add permission fetching when RBAC is enabled
107+
- [ ] Include permissions in session data
108+
- [ ] Update session-state worker handlers
109+
- [ ] Ensure permissions are stored in KV
110+
- [ ] Handle larger session payloads
111+
112+
### 6. Middleware Implementation
113+
- [ ] Create `src/middleware/rbac.ts`
114+
- [ ] Implement `requirePermission(permission)` middleware
115+
- [ ] Add support for checking multiple permissions
116+
- [ ] Handle "admin:all" special permission
117+
- [ ] Create `requireAnyPermission(permissions)` for OR logic
118+
- [ ] Create `requireAllPermissions(permissions)` for AND logic
119+
120+
### 7. User Registration Updates
121+
- [ ] Modify registration handler to assign default role
122+
- [ ] Query MEMBER role ID
123+
- [ ] Insert user_roles record on registration
124+
- [ ] Add role assignment to user creation flow
125+
126+
### 8. Management API Endpoints
127+
- [ ] Create `/rbac/roles` endpoints
128+
- [ ] GET /rbac/roles - List all roles
129+
- [ ] POST /rbac/roles - Create new role
130+
- [ ] PUT /rbac/roles/:id - Update role
131+
- [ ] DELETE /rbac/roles/:id - Delete role
132+
- [ ] Create `/rbac/permissions` endpoints
133+
- [ ] GET /rbac/permissions - List all permissions
134+
- [ ] POST /rbac/permissions - Create new permission
135+
- [ ] Create `/rbac/users/:userId/roles` endpoints
136+
- [ ] GET /rbac/users/:userId/roles - Get user's roles
137+
- [ ] POST /rbac/users/:userId/roles - Assign role to user
138+
- [ ] DELETE /rbac/users/:userId/roles/:roleId - Remove role from user
139+
140+
### 9. Existing Endpoint Protection
141+
- [ ] Add optional permission checks to sensitive endpoints
142+
- [ ] DELETE /users/:id - requires "users:delete"
143+
- [ ] PUT /users/:id - requires "users:update" or own user
144+
- [ ] Update load-user endpoint to include roles/permissions when RBAC enabled
145+
146+
### 10. Admin Bootstrapping
147+
- [ ] Create initialization script for first admin
148+
- [ ] Check for SUPER_ADMIN_EMAIL environment variable
149+
- [ ] Assign SUPER_ADMIN role to specified user
150+
- [ ] Add bootstrapping to worker startup (optional)
151+
152+
### 11. Testing Tasks
153+
- [ ] Create test suite for RBAC functions
154+
- [ ] Test permission checking logic
155+
- [ ] Test middleware with various permission scenarios
156+
- [ ] Test session enhancement
157+
- [ ] Test backwards compatibility with RBAC disabled
158+
159+
### 12. Migration Scripts
160+
- [ ] Create script to assign default role to existing users
161+
- [ ] Create script to promote specific users to admin
162+
- [ ] Document migration process for existing deployments
163+
164+
### 13. Documentation Tasks
165+
- [ ] Update README.md with RBAC section
166+
- [ ] Create RBAC.md with detailed documentation
167+
- [ ] Configuration guide
168+
- [ ] Permission format explanation
169+
- [ ] API endpoint documentation
170+
- [ ] Migration guide
171+
- [ ] Add RBAC examples to account-pages
172+
- [ ] Update CLAUDE.md with RBAC information
173+
174+
### 14. Frontend Examples
175+
- [ ] Add permission-based UI elements to account-pages
176+
- [ ] Show/hide admin features based on permissions
177+
- [ ] Display user's roles on profile page
178+
- [ ] Create admin panel example (future enhancement)
179+
180+
### 15. Performance Optimization
181+
- [ ] Add database indexes for permission queries
182+
- [ ] Implement permission caching strategy
183+
- [ ] Monitor and optimize permission query performance
184+
185+
## Migration Strategy
186+
187+
1. **Deploy Code** - Deploy new code with RBAC_ENABLED=false
188+
2. **Run Migrations** - Execute database migrations to create RBAC tables
189+
3. **Assign Roles** - Run script to assign default roles to existing users
190+
4. **Bootstrap Admin** - Assign SUPER_ADMIN role to designated user
191+
5. **Enable RBAC** - Set RBAC_ENABLED=true and redeploy
192+
193+
## Success Criteria
194+
195+
- [ ] Existing deployments work unchanged when RBAC is disabled
196+
- [ ] New deployments can enable RBAC with minimal configuration
197+
- [ ] Permission checks add <5ms latency to protected requests
198+
- [ ] Clear documentation enables developers to implement RBAC quickly
199+
- [ ] Migration path is safe and reversible
200+
201+
## Future Enhancements
202+
203+
1. **Admin UI** - Dedicated Pages application for RBAC management
204+
2. **Dynamic Permissions** - Runtime permission registration
205+
3. **Permission Wildcards** - Support for pattern matching (e.g., "posts:*")
206+
4. **Audit Logging** - Track permission changes and access attempts
207+
5. **Session Revocation** - Immediate permission revocation capability

0 commit comments

Comments
 (0)