diff --git a/docs/BUSINESS_JUSTIFICATION_RBAC.md b/docs/01_BUSINESS_JUSTIFICATION_RBAC.md similarity index 100% rename from docs/BUSINESS_JUSTIFICATION_RBAC.md rename to docs/01_BUSINESS_JUSTIFICATION_RBAC.md diff --git a/docs/FEATURES_OVERVIEW.md b/docs/02_FEATURES_OVERVIEW.md similarity index 100% rename from docs/FEATURES_OVERVIEW.md rename to docs/02_FEATURES_OVERVIEW.md diff --git a/docs/RBAC_AUTHENTIK_ANALYSIS.md b/docs/03_RBAC_AUTHENTIK_ANALYSIS.md similarity index 100% rename from docs/RBAC_AUTHENTIK_ANALYSIS.md rename to docs/03_RBAC_AUTHENTIK_ANALYSIS.md diff --git a/docs/IMPLEMENTATION_STATUS.md b/docs/04_IMPLEMENTATION_STATUS.md similarity index 100% rename from docs/IMPLEMENTATION_STATUS.md rename to docs/04_IMPLEMENTATION_STATUS.md diff --git a/docs/05_BACKEND_IMPLEMENTATION_PLAN.md b/docs/05_BACKEND_IMPLEMENTATION_PLAN.md new file mode 100644 index 0000000..a8c955f --- /dev/null +++ b/docs/05_BACKEND_IMPLEMENTATION_PLAN.md @@ -0,0 +1,478 @@ +# CorradAF RBAC Backend Implementation Plan + +## 🏗️ Architecture Overview + +### **Hybrid Architecture Strategy** +- **Authentik**: User management, authentication, basic groups +- **RBAC Database**: Roles, permissions, applications, resources, business logic +- **Backend API**: Bridge between frontend and both systems + +### **Technology Stack Recommendation** +- **Runtime**: Node.js with TypeScript +- **Framework**: Fastify or Express.js +- **Database**: PostgreSQL with Prisma ORM +- **Authentication**: JWT with Authentik integration +- **Validation**: Zod for type-safe validation +- **Documentation**: OpenAPI/Swagger + +## 📊 Database Schema Design + +### **Core Tables** + +```sql +-- Applications Management +CREATE TABLE applications ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + name VARCHAR(255) NOT NULL, + slug VARCHAR(255) UNIQUE NOT NULL, + description TEXT, + url VARCHAR(500), + provider_type VARCHAR(50) DEFAULT 'oauth2', -- oauth2, saml, proxy + is_active BOOLEAN DEFAULT true, + authentik_application_id VARCHAR(255), -- Reference to Authentik app + oauth_client_id VARCHAR(255), + oauth_client_secret VARCHAR(500), + setup_type VARCHAR(50) DEFAULT 'web-app', -- web-app, api-service, enterprise, custom + created_at TIMESTAMP DEFAULT NOW(), + updated_at TIMESTAMP DEFAULT NOW() +); + +-- Resource Types (Menus, Components, Features) +CREATE TABLE resources ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + application_id UUID REFERENCES applications(id) ON DELETE CASCADE, + name VARCHAR(255) NOT NULL, + key VARCHAR(255) NOT NULL, -- Auto-generated: user-management + type VARCHAR(50) NOT NULL, -- menu, component, feature + path VARCHAR(500), -- For menu resources + description TEXT, + metadata JSONB DEFAULT '{}', -- Flexible additional data + created_at TIMESTAMP DEFAULT NOW(), + + UNIQUE(application_id, key) -- Unique per application +); + +-- Role Templates (Pre-defined permission sets) +CREATE TABLE role_templates ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + name VARCHAR(255) NOT NULL, + description TEXT, + emoji VARCHAR(10) DEFAULT '⚙️', + permission_count INTEGER DEFAULT 0, + permissions JSONB NOT NULL DEFAULT '{"menus": [], "components": [], "features": []}', + is_system BOOLEAN DEFAULT false, -- System templates vs custom + created_at TIMESTAMP DEFAULT NOW(), + updated_at TIMESTAMP DEFAULT NOW() +); + +-- Roles (Application-scoped) +CREATE TABLE roles ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + application_id UUID REFERENCES applications(id) ON DELETE CASCADE, + name VARCHAR(255) NOT NULL, + description TEXT, + priority INTEGER DEFAULT 0, + is_global BOOLEAN DEFAULT false, + template_id UUID REFERENCES role_templates(id), + permissions JSONB NOT NULL DEFAULT '{"menus": [], "components": [], "features": []}', + authentik_group_id VARCHAR(255), -- Reference to Authentik group + created_at TIMESTAMP DEFAULT NOW(), + updated_at TIMESTAMP DEFAULT NOW(), + + UNIQUE(application_id, name) -- Unique per application +); + +-- Permission Mapping (Role -> Resources) +CREATE TABLE role_permissions ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + role_id UUID REFERENCES roles(id) ON DELETE CASCADE, + resource_id UUID REFERENCES resources(id) ON DELETE CASCADE, + actions JSONB DEFAULT '["view"]', -- ["view", "edit", "delete"] + granted_at TIMESTAMP DEFAULT NOW(), + + UNIQUE(role_id, resource_id) +); + +-- User-Role Assignments (Bridge to Authentik users) +CREATE TABLE user_roles ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + authentik_user_id VARCHAR(255) NOT NULL, -- Authentik user ID + role_id UUID REFERENCES roles(id) ON DELETE CASCADE, + application_id UUID REFERENCES applications(id) ON DELETE CASCADE, + assigned_by VARCHAR(255), -- Authentik user ID who assigned + assigned_at TIMESTAMP DEFAULT NOW(), + expires_at TIMESTAMP, -- Optional expiration + + UNIQUE(authentik_user_id, role_id, application_id) +); + +-- Enhanced Groups (Extends Authentik groups) +CREATE TABLE enhanced_groups ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + authentik_group_id VARCHAR(255) UNIQUE NOT NULL, -- Reference to Authentik + name VARCHAR(255) NOT NULL, -- Synced from Authentik + description TEXT, + parent_group_id UUID REFERENCES enhanced_groups(id), + attributes JSONB DEFAULT '{}', -- Custom attributes + department VARCHAR(255), + cost_center VARCHAR(255), + location VARCHAR(255), + manager_email VARCHAR(255), + is_active BOOLEAN DEFAULT true, + created_at TIMESTAMP DEFAULT NOW(), + updated_at TIMESTAMP DEFAULT NOW() +); + +-- Group-Role Assignments +CREATE TABLE group_roles ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + group_id UUID REFERENCES enhanced_groups(id) ON DELETE CASCADE, + role_id UUID REFERENCES roles(id) ON DELETE CASCADE, + application_id UUID REFERENCES applications(id) ON DELETE CASCADE, + assigned_by VARCHAR(255), -- Authentik user ID + assigned_at TIMESTAMP DEFAULT NOW(), + + UNIQUE(group_id, role_id, application_id) +); + +-- Application Access Control +CREATE TABLE application_access ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + application_id UUID REFERENCES applications(id) ON DELETE CASCADE, + group_id UUID REFERENCES enhanced_groups(id) ON DELETE CASCADE, + access_type VARCHAR(50) DEFAULT 'ANY', -- ANY, ALL + created_at TIMESTAMP DEFAULT NOW(), + + UNIQUE(application_id, group_id) +); + +-- Audit Log +CREATE TABLE audit_logs ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + user_id VARCHAR(255) NOT NULL, -- Authentik user ID + action VARCHAR(100) NOT NULL, -- CREATE_USER, ASSIGN_ROLE, etc. + resource_type VARCHAR(50) NOT NULL, -- user, role, group, application + resource_id VARCHAR(255) NOT NULL, + old_values JSONB, + new_values JSONB, + ip_address INET, + user_agent TEXT, + application_id UUID REFERENCES applications(id), + created_at TIMESTAMP DEFAULT NOW() +); + +-- Site Settings +CREATE TABLE site_settings ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + site_name VARCHAR(255) DEFAULT 'CorradAF', + site_description TEXT DEFAULT 'CorradAF RBAC Management System', + site_logo VARCHAR(500), + site_favicon VARCHAR(500), + selected_theme VARCHAR(100) DEFAULT 'biasa', + custom_css TEXT, + custom_theme_file VARCHAR(500), + settings JSONB DEFAULT '{}', -- Additional settings + updated_by VARCHAR(255), -- Authentik user ID + updated_at TIMESTAMP DEFAULT NOW() +); +``` + +### **Database Indexes** +```sql +-- Performance indexes +CREATE INDEX idx_user_roles_user_id ON user_roles(authentik_user_id); +CREATE INDEX idx_user_roles_role_id ON user_roles(role_id); +CREATE INDEX idx_role_permissions_role_id ON role_permissions(role_id); +CREATE INDEX idx_resources_application_type ON resources(application_id, type); +CREATE INDEX idx_enhanced_groups_authentik_id ON enhanced_groups(authentik_group_id); +CREATE INDEX idx_audit_logs_user_id ON audit_logs(user_id); +CREATE INDEX idx_audit_logs_created_at ON audit_logs(created_at); +``` + +## 🚀 API Architecture Design + +### **API Structure** +``` +/api/v1/ +├── auth/ # Authentication endpoints +│ ├── login # Authentik OAuth redirect +│ ├── callback # OAuth callback handler +│ ├── refresh # Token refresh +│ └── logout # Logout handler +├── users/ # User management (Authentik proxy) +│ ├── GET / # List users from Authentik +│ ├── POST / # Create user in Authentik +│ ├── GET /:id # Get user details +│ ├── PUT /:id # Update user +│ ├── DELETE /:id # Delete user +│ ├── POST /bulk # Bulk operations +│ └── POST /sync # Sync with Authentik +├── groups/ # Enhanced group management +│ ├── GET / # List enhanced groups +│ ├── POST / # Create group (Authentik + enhanced) +│ ├── GET /:id # Get group details +│ ├── PUT /:id # Update group +│ ├── DELETE /:id # Delete group +│ └── POST /:id/roles # Assign roles to group +├── roles/ # Role management +│ ├── GET / # List roles +│ ├── POST / # Create role +│ ├── GET /:id # Get role details +│ ├── PUT /:id # Update role +│ ├── DELETE /:id # Delete role +│ ├── POST /:id/permissions # Assign permissions +│ └── POST /from-template # Create role from template +├── role-templates/ # Role template management +│ ├── GET / # List templates +│ ├── POST / # Create template +│ ├── GET /:id # Get template +│ ├── PUT /:id # Update template +│ ├── DELETE /:id # Delete template +│ └── POST /:id/clone # Clone template +├── applications/ # Application management +│ ├── GET / # List applications +│ ├── POST / # Create application +│ ├── GET /:id # Get application +│ ├── PUT /:id # Update application +│ ├── DELETE /:id # Delete application +│ ├── GET /:id/resources # Get app resources +│ └── POST /:id/access # Manage access control +├── resources/ # Resource management +│ ├── GET / # List resources +│ ├── POST / # Create resource +│ ├── GET /:id # Get resource +│ ├── PUT /:id # Update resource +│ ├── DELETE /:id # Delete resource +│ └── GET /by-type/:type # Get by type (menu/component/feature) +├── permissions/ # Permission management +│ ├── POST /check # Check user permissions +│ ├── GET /user/:id # Get user permissions +│ ├── POST /assign # Assign permissions +│ ├── POST /revoke # Revoke permissions +│ └── GET /matrix # Permission matrix +├── rbac/ # RBAC management interface +│ ├── GET /overview # System statistics +│ ├── GET /matrix # Permission matrix +│ ├── POST /bulk-assign # Bulk permission assignment +│ └── GET /audit # Audit trail +├── settings/ # Site settings +│ ├── GET / # Get current settings +│ ├── PUT / # Update settings +│ └── POST /upload # Upload files (logo, favicon) +└── audit/ # Audit logging + ├── GET / # List audit logs + ├── GET /:id # Get specific log + └── GET /export # Export audit data +``` + +## 🔐 Authentication & Authorization + +### **JWT Token Structure** +```typescript +interface JWTPayload { + sub: string; // Authentik user ID + email: string; // User email + name: string; // Full name + groups: string[]; // Authentik group IDs + roles: { // RBAC roles per application + [applicationId: string]: { + roleId: string; + roleName: string; + permissions: string[]; + }[]; + }; + permissions: string[]; // Flattened permission keys + iat: number; // Issued at + exp: number; // Expires at +} +``` + +### **Permission Checking Service** +```typescript +class PermissionService { + async checkPermission( + userId: string, + resourceKey: string, + action: string = 'view', + applicationId?: string + ): Promise { + // 1. Get user roles for application + // 2. Get permissions for those roles + // 3. Check if resourceKey + action is allowed + // 4. Cache result for performance + } + + async getUserPermissions( + userId: string, + applicationId?: string + ): Promise { + // Return flattened list of permission keys + } + + async refreshUserPermissions(userId: string): Promise { + // Refresh cached permissions + } +} +``` + +## 🔄 Authentik Integration Strategy + +### **User Management Integration** +```typescript +class AuthentikService { + async getUsers(params: GetUsersParams): Promise { + // GET /api/v3/core/users/ + } + + async createUser(userData: CreateUserData): Promise { + // POST /api/v3/core/users/ + // Also create enhanced profile in RBAC DB + } + + async updateUser(id: string, userData: UpdateUserData): Promise { + // PATCH /api/v3/core/users/{id}/ + } + + async deleteUser(id: string): Promise { + // DELETE /api/v3/core/users/{id}/ + // Also cleanup RBAC data + } + + async syncUsers(): Promise { + // Sync users between Authentik and RBAC DB + } +} +``` + +### **Group Synchronization** +```typescript +class GroupSyncService { + async syncGroupFromAuthentik(authentikGroupId: string): Promise { + // 1. Get group from Authentik + // 2. Create/update in enhanced_groups table + // 3. Maintain custom attributes + } + + async createGroupInAuthentik(groupData: CreateGroupData): Promise { + // 1. Create in Authentik + // 2. Create enhanced group record + // 3. Return Authentik group ID + } +} +``` + +## 📝 Implementation Strategy + +### **Phase 1: Foundation (Week 1-2)** +1. **Database Setup** + - PostgreSQL database creation + - Prisma schema implementation + - Migration scripts + - Seed data for role templates + +2. **Basic API Structure** + - Express/Fastify setup with TypeScript + - Authentication middleware + - Basic CRUD endpoints + - Error handling + +3. **Authentik Integration** + - OAuth2/OIDC client setup + - JWT token handling + - Basic user endpoint proxy + +### **Phase 2: Core RBAC (Week 3-4)** +1. **Role & Permission System** + - Role management endpoints + - Permission assignment logic + - Role template system + - Permission checking service + +2. **Resource Management** + - Resource CRUD operations + - Auto-key generation + - Application scoping + +3. **Enhanced Groups** + - Group synchronization + - Custom attributes + - Hierarchy management + +### **Phase 3: Advanced Features (Week 5-6)** +1. **Application Management** + - Application setup wizard + - Provider configuration + - Access control policies + +2. **Permission Matrix** + - Complex permission queries + - Bulk operations + - Real-time updates + +3. **Audit System** + - Activity logging + - Export functionality + - Compliance reporting + +### **Phase 4: Performance & Production (Week 7-8)** +1. **Performance Optimization** + - Caching layer (Redis) + - Database query optimization + - Permission checking performance + +2. **Security Hardening** + - Rate limiting + - Input validation + - Security headers + +3. **Production Setup** + - Docker containers + - Environment configuration + - Monitoring and logging + +## 🛠️ Technology Implementation + +### **Recommended Stack** +```json +{ + "runtime": "Node.js 18+", + "framework": "Fastify", + "database": "PostgreSQL 15+", + "orm": "Prisma", + "validation": "Zod", + "authentication": "Authentik OAuth2/JWT", + "caching": "Redis", + "documentation": "Swagger/OpenAPI", + "testing": "Jest + Supertest", + "deployment": "Docker" +} +``` + +### **Key Dependencies** +```json +{ + "dependencies": { + "fastify": "^4.x", + "@fastify/cors": "^8.x", + "@fastify/jwt": "^7.x", + "@fastify/swagger": "^8.x", + "@prisma/client": "^5.x", + "zod": "^3.x", + "axios": "^1.x", + "redis": "^4.x", + "multer": "^1.x", + "winston": "^3.x" + }, + "devDependencies": { + "prisma": "^5.x", + "typescript": "^5.x", + "@types/node": "^20.x", + "jest": "^29.x", + "supertest": "^6.x" + } +} +``` + +This architecture provides a robust, scalable backend that maintains the hybrid approach you want - leveraging Authentik for user management while giving you full control over the RBAC business logic. + +Would you like me to start implementing any specific part of this backend plan? \ No newline at end of file diff --git a/docs/AUTHENTIK_INTEGRATION_IMPLEMENTATION.md b/docs/06_AUTHENTIK_INTEGRATION_IMPLEMENTATION.md similarity index 100% rename from docs/AUTHENTIK_INTEGRATION_IMPLEMENTATION.md rename to docs/06_AUTHENTIK_INTEGRATION_IMPLEMENTATION.md diff --git a/docs/APPLICATION_MANAGEMENT.md b/docs/07_APPLICATION_MANAGEMENT.md similarity index 100% rename from docs/APPLICATION_MANAGEMENT.md rename to docs/07_APPLICATION_MANAGEMENT.md diff --git a/docs/SITE_SETTINGS.md b/docs/08_SITE_SETTINGS.md similarity index 100% rename from docs/SITE_SETTINGS.md rename to docs/08_SITE_SETTINGS.md