# Authentication & Authorization System

## Overview

The J4F Assistant features a comprehensive, enterprise-grade authentication and authorization system built on **OpenID Connect (OIDC)** with **Keycloak** integration and **Role-Based Access Control (RBAC)**. This system provides secure, scalable user management with granular permission controls.

## 🔐 Key Features

### Enterprise Authentication
- **OIDC/Keycloak Integration**: Industry-standard authentication protocol
- **Single Sign-On (SSO)**: Seamless authentication across services
- **Token-Based Security**: JWT tokens with automatic refresh
- **Session Management**: Persistent, secure session handling

### Role-Based Access Control (RBAC)
- **Hierarchical Roles**: Five-tier role system with clear responsibilities
- **Granular Permissions**: Fine-grained permission controls
- **Dynamic Authorization**: Real-time permission checking
- **Secure API Access**: Protected endpoints with role validation

### Multi-Tier Role System
- **TheDude**: Superuser access (full system control)
- **Lead**: Team/project leadership (advanced features)
- **Dev**: Developer access (development tools)
- **Admin**: Community administration (J4F features)
- **User**: Standard user (basic assistant features)

## 🏗️ Architecture Components

### Core Authentication Modules

#### Permission System (`src/auth/PermissionSystem.js`)
```javascript
export class PermissionSystem {
    static getUserPermissions(roles) {
        // Maps roles to specific permissions
        // Supports multiple roles per user
        // Returns consolidated permission set
    }
}
```

**Role-Permission Mapping:**

| Role | Permissions |
|------|-------------|
| **TheDude** | All permissions (superuser) |
| **Lead** | Advanced features, no user management |
| **Dev** | Development tools, model management |
| **Admin** | Community features, basic admin |
| **User** | Basic chat and conversation features |

#### RBAC Middleware (`src/auth/RBACMiddleware.js`)
```javascript
export class RBACMiddleware {
    static requireRole(role)        // Single role requirement
    static requireAnyRole(roles)    // Multiple role options
    static requirePermission(perm)  // Specific permission check
}
```

### Authentication Flow

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│     Client      │───▶│    Keycloak     │───▶│   J4F Backend   │
│   (Frontend)    │    │     Server      │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                        │                        │
         │     1. Login Request   │                        │
         │◄──────────────────────►│                        │
         │                        │                        │
         │     2. OIDC Token      │                        │
         │◄───────────────────────│                        │
         │                                                 │
         │     3. API Request + JWT Token                  │
         │────────────────────────────────────────────────▶│
         │                                                 │
         │     4. Token Validation & Role Check            │
         │                                                 │
         │     5. Authorized Response                      │
         │◄────────────────────────────────────────────────│
```

## 🔑 Permission Categories

### Chat & Conversation Management
```javascript
'chat:send'              // Send chat messages
'chat:clear'             // Clear chat history
'conversations:list'     // List user conversations
'conversations:save'     // Save conversations
'conversations:load'     // Load conversations
'conversations:delete'   // Delete conversations
```

### Model & Provider Management
```javascript
'models:list'            // List available models
'models:download'        // Download new models
'models:delete'          // Delete models
'providers:ollama'       // Access Ollama provider
'providers:anthropic'    // Access Anthropic provider
'providers:openai'       // Access OpenAI provider
```

### Advanced Features
```javascript
'workspaces:list'        // List workspaces
'workspaces:switch'      // Switch workspaces
'terminal:create'        // Create terminal sessions
'terminal:execute'       // Execute terminal commands
'terminal:kill'          // Kill terminal sessions
'prompt_orders:list'     // List prompt orders
'prompt_orders:save'     // Save prompt orders
```

### Administrative Functions
```javascript
'audit:view'             // View audit logs
'system:info'            // Access system information
'user:management'        // User management (TheDude only)
```

## 🛡️ Security Implementation

### JWT Token Validation
```javascript
// Automatic token validation on every request
app.use(auth({
    issuerBaseURL: process.env.OIDC_ISSUER_BASE_URL,
    baseURL: process.env.OIDC_BASE_URL,
    clientID: process.env.OIDC_CLIENT_ID,
    clientSecret: process.env.OIDC_CLIENT_SECRET,
    secret: process.env.OIDC_SECRET
}));
```

### Route Protection Examples
```javascript
// Require specific role
app.get('/api/admin/*', RBACMiddleware.requireRole('Admin'));

// Require any of multiple roles
app.get('/api/dev/*', RBACMiddleware.requireAnyRole(['Dev', 'Lead', 'TheDude']));

// Require specific permission
app.post('/api/models/download', RBACMiddleware.requirePermission('models:download'));
```

### Pipeline Integration
All streaming and pipeline operations include user context:
```javascript
// Pipeline operations include user_id and conversation_uuid
await PipelineManager.runPipelineForConversation(
    modelStream, 
    conversationUuid, 
    userId,     // From authenticated token
    pipeline
);
```

## 🚀 API Integration

### Authentication Headers
```javascript
// Frontend automatically includes auth headers
headers: {
    'Authorization': `Bearer ${keycloakToken}`,
    'Content-Type': 'application/json'
}
```

### User Context in Requests
```javascript
// All API requests include user context
{
    "message": "Hello",
    "user_id": "user-123",
    "conversation_uuid": "conv-456",
    // ... other parameters
}
```

### Protected Endpoints

#### Conversation Management
- `GET /api/conversations` - List user conversations
- `POST /api/conversations/save` - Save conversation
- `POST /api/conversations/load` - Load conversation
- `DELETE /api/conversations/:id` - Delete conversation

#### Model Management
- `GET /api/models` - List available models
- `POST /api/models/download` - Download model
- `DELETE /api/models/:name` - Delete model

#### Streaming & Pipeline
- `POST /api/message/stream` - Streaming chat
- `POST /api/unified/stream` - Advanced streaming pipeline
- `POST /api/markdown/stream` - Markdown-specific streaming

## 🔧 Configuration

### Environment Variables
```bash
# OIDC/Keycloak Configuration
OIDC_ISSUER_BASE_URL=https://your-keycloak.com/realms/j4f
OIDC_BASE_URL=https://your-j4f-assistant.com
OIDC_CLIENT_ID=j4f-assistant
OIDC_CLIENT_SECRET=your-secret
OIDC_SECRET=your-session-secret

# Enable authentication
AUTH_ENABLED=true
```

### Role Assignment
Users are assigned roles in Keycloak:
1. **Keycloak Admin Console** → Realm → Users
2. **Select User** → Role Mappings
3. **Assign Roles**: User, Admin, Dev, Lead, TheDude

## 📊 Usage Examples

### Frontend Authentication Check
```javascript
// Check if user is authenticated
if (oidc.isAuthenticated()) {
    const userRoles = oidc.user.roles;
    const userPermissions = PermissionSystem.getUserPermissions(userRoles);
    
    // Show/hide features based on permissions
    if (userPermissions.includes('models:download')) {
        showModelDownloadButton();
    }
}
```

### Backend Route Protection
```javascript
// Protect admin endpoints
app.use('/api/admin/*', RBACMiddleware.requireAnyRole(['Admin', 'Lead', 'TheDude']));

// Protect development features
app.use('/api/terminal/*', RBACMiddleware.requirePermission('terminal:execute'));
```

### Pipeline User Context
```javascript
// Include user context in all pipeline operations
const context = {
    conversation_id: userId,
    conversation_uuid: conversationUuid,
    user_permissions: getUserPermissions(userRoles)
};

await this.assistant.processMessageStreamWithNatsPipeline(
    message, userId, prompt, onChunk, onComplete, onError, context
);
```

## 🔍 Security Monitoring

### Audit Logging
- **Authentication Events**: Login, logout, token refresh
- **Authorization Failures**: Access denied events
- **Permission Changes**: Role/permission modifications
- **Sensitive Operations**: Model downloads, terminal access

### Session Management
- **Token Expiration**: Automatic token refresh
- **Session Timeout**: Configurable session timeouts
- **Concurrent Sessions**: Multi-device session handling
- **Secure Logout**: Complete session cleanup

## 🚀 Future Enhancements

### Planned Features
- [ ] **Multi-Factor Authentication (MFA)**: Additional security layer
- [ ] **Organization Management**: Multi-tenant support
- [ ] **Custom Roles**: User-defined role creation
- [ ] **OAuth2 Providers**: Google, GitHub, Microsoft integration
- [ ] **API Key Management**: Service-to-service authentication

### Advanced RBAC
- [ ] **Dynamic Permissions**: Runtime permission modification
- [ ] **Resource-Based Access**: File/workspace-specific permissions
- [ ] **Time-Based Access**: Temporary permission grants
- [ ] **Audit Dashboard**: Real-time security monitoring

## Related Documentation

- [Backend Overview](../backend/Overview.md)
- [API Reference](../api/Reference.md)
- [Security Overview](../security/CommandExecution.md)
- [Deployment Guide](../structure/Architecture.md)

### Role System

| Role | Permissions | Description |
|------|-------------|-------------|
| `TheDude` | All permissions including user management | Highest-level superuser with full system access |
| `Lead` | All features except user management | Team/project lead with advanced access |
| `Dev` | Development tools and most features | Developer access without admin functions |
| `Admin` | J4F community features, no system admin | Community admin with limited system access |
| `User` | Basic chat and conversation management | Standard user with core features |

### Integration Status

- ✅ Frontend Authentication UI
- ✅ Backend OIDC Setup  
- ✅ API Client Integration
- ✅ Permission System
- ✅ Route Protection
- ✅ Graceful Fallback
- 🔄 Single User Mode (planned)

### Next Steps

1. **Test with Real OIDC Provider**: Configure with Keycloak, Auth0, or similar
2. **Single User Mode**: Add bypass for single-user deployments
3. **Enhanced UI**: Improve authentication status displays
4. **Advanced Permissions**: Add more granular permission controls
- How will audit logging be implemented for sensitive actions?

---

See additional documents in this folder for detailed implementation guides and decisions.