loki-mode 5.42.2 → 5.46.0

package/docs/authorization.md

@@ -0,0 +1,455 @@
+# Authorization Guide
+
+Role-based access control (RBAC) for Loki Mode (v5.37.0).
+
+## Overview
+
+Loki Mode implements a four-tier RBAC system that controls access to dashboard operations, API endpoints, and agent actions. RBAC integrates with both token-based authentication and OIDC/SSO.
+
+## Role Definitions
+
+### Admin
+
+Full access to all operations and configuration.
+
+**Scopes:** `*` (all)
+
+**Permissions:**
+- Start/stop/pause/resume sessions
+- Create/update/delete tasks
+- Modify configuration
+- Generate/revoke tokens
+- View audit logs
+- Manage users and roles
+- Access all API endpoints
+
+**Use Cases:**
+- System administrators
+- DevOps engineers
+- Project owners
+
+### Operator
+
+Day-to-day operations without configuration changes.
+
+**Scopes:** `control`, `read`, `write`
+
+**Permissions:**
+- Start/stop/pause/resume sessions
+- Create/update tasks
+- View dashboard and logs
+- Execute agent actions
+- Access metrics endpoint
+
+**Cannot:**
+- Modify system configuration
+- Manage tokens or users
+- View audit logs (except their own actions)
+
+**Use Cases:**
+- Developers
+- CI/CD pipelines
+- Automated workflows
+
+### Viewer
+
+Read-only access to dashboard and logs.
+
+**Scopes:** `read`
+
+**Permissions:**
+- View dashboard status
+- View task queue
+- View logs and events
+- View metrics
+- View agent activity
+
+**Cannot:**
+- Start/stop sessions
+- Create/modify tasks
+- Access audit logs
+- Modify any state
+
+**Use Cases:**
+- Stakeholders
+- Project managers
+- External observers
+
+### Auditor
+
+Security and compliance monitoring.
+
+**Scopes:** `read`, `audit`
+
+**Permissions:**
+- View dashboard status
+- View task queue and logs
+- Access audit logs
+- View agent action history
+- Export compliance reports
+
+**Cannot:**
+- Start/stop sessions
+- Create/modify tasks
+- Modify configuration
+
+**Use Cases:**
+- Security teams
+- Compliance officers
+- Internal auditors
+
+## Configuration
+
+### Enable RBAC
+
+```bash
+export LOKI_RBAC_ENABLED=true
+loki start ./prd.md
+```
+
+### Assign Roles via Tokens
+
+```bash
+# Generate token with role
+loki enterprise token generate dev-1 --role operator --expires 30
+loki enterprise token generate viewer-1 --role viewer --expires 90
+loki enterprise token generate auditor-1 --role auditor --expires 180
+loki enterprise token generate admin-1 --role admin --expires 365
+```
+
+### Configuration File
+
+```yaml
+# .loki/config.yaml
+enterprise:
+  rbac:
+    enabled: true
+    default_role: viewer  # Default for OIDC users without role mapping
+    enforce_mfa: false    # Require MFA for admin role (future)
+  roles:
+    admin:
+      scopes: ["*"]
+    operator:
+      scopes: ["control", "read", "write"]
+    viewer:
+      scopes: ["read"]
+    auditor:
+      scopes: ["read", "audit"]
+```
+
+### OIDC Role Mapping
+
+Map OIDC claims to Loki roles:
+
+```yaml
+enterprise:
+  rbac:
+    oidc_role_mapping:
+      # Map Google Groups to roles
+      google:
+        admins@example.com: admin
+        devops@example.com: operator
+        viewers@example.com: viewer
+      # Map Azure AD groups to roles
+      azure:
+        12345678-abcd-1234-abcd-123456789abc: admin  # Group Object ID
+        87654321-dcba-4321-dcba-987654321cba: operator
+```
+
+## Scope-Based Access Control
+
+### Scope Hierarchy
+
+```
+* (all)
+├── control
+│   ├── write
+│   │   └── read
+│   └── read
+├── audit
+│   └── read
+└── read
+```
+
+Scopes are additive:
+- `control` automatically includes `write` and `read`
+- `write` automatically includes `read`
+- `audit` requires separate grant (not included in `*`)
+
+### Endpoint Permissions
+
+| Endpoint | Required Scope | Roles with Access |
+|----------|----------------|-------------------|
+| `GET /api/status` | `read` | All roles |
+| `GET /api/tasks` | `read` | All roles |
+| `GET /api/logs` | `read` | All roles |
+| `GET /metrics` | `read` | All roles |
+| `POST /api/tasks` | `write` | Operator, Admin |
+| `PATCH /api/tasks/:id` | `write` | Operator, Admin |
+| `POST /api/control/start` | `control` | Operator, Admin |
+| `POST /api/control/stop` | `control` | Operator, Admin |
+| `GET /api/audit` | `audit` | Auditor, Admin |
+| `POST /api/enterprise/tokens` | `*` | Admin only |
+| `DELETE /api/enterprise/tokens/:id` | `*` | Admin only |
+| `POST /api/config` | `*` | Admin only |
+
+## Custom Roles
+
+Define custom roles for specific use cases:
+
+```yaml
+# .loki/config.yaml
+enterprise:
+  rbac:
+    custom_roles:
+      # Read-only with metrics access
+      metrics_viewer:
+        scopes: ["read"]
+        description: "View metrics and dashboard only"
+
+      # Task management only
+      task_manager:
+        scopes: ["read", "write"]
+        description: "Create and update tasks, no session control"
+
+      # Security analyst
+      security_analyst:
+        scopes: ["read", "audit"]
+        description: "View audit logs and security events"
+```
+
+Generate token with custom role:
+
+```bash
+loki enterprise token generate metrics-bot --role metrics_viewer
+```
+
+## Permission Checks
+
+### CLI
+
+```bash
+# Check current permissions
+loki enterprise rbac check
+
+# Check specific permission
+loki enterprise rbac check --scope control
+
+# List permissions for role
+loki enterprise rbac permissions --role operator
+```
+
+### API
+
+```bash
+# Check token permissions
+curl -H "Authorization: Bearer $LOKI_TOKEN" \
+     http://localhost:57374/api/enterprise/rbac/check
+
+# Response:
+{
+  "role": "operator",
+  "scopes": ["control", "read", "write"],
+  "permissions": {
+    "can_start_session": true,
+    "can_stop_session": true,
+    "can_create_tasks": true,
+    "can_modify_config": false,
+    "can_manage_tokens": false
+  }
+}
+```
+
+## Agent Action Authorization
+
+Control which roles can trigger agent actions:
+
+```yaml
+enterprise:
+  rbac:
+    agent_actions:
+      git_commit:
+        required_scope: control
+      cli_invoke:
+        required_scope: control
+      file_write:
+        required_scope: write
+      file_read:
+        required_scope: read
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOKI_RBAC_ENABLED` | `false` | Enable RBAC system |
+| `LOKI_RBAC_DEFAULT_ROLE` | `viewer` | Default role for OIDC users |
+| `LOKI_RBAC_STRICT_MODE` | `false` | Deny access when role is undefined (vs default to viewer) |
+| `LOKI_RBAC_AUDIT_CHECKS` | `true` | Log all permission checks to audit log |
+
+## Examples
+
+### Multi-Environment Setup
+
+```bash
+# Production - strict RBAC
+export LOKI_RBAC_ENABLED=true
+export LOKI_RBAC_STRICT_MODE=true
+export LOKI_RBAC_DEFAULT_ROLE=viewer
+
+# Development - relaxed RBAC
+export LOKI_RBAC_ENABLED=false
+
+# Staging - moderate RBAC
+export LOKI_RBAC_ENABLED=true
+export LOKI_RBAC_DEFAULT_ROLE=operator
+```
+
+### Team-Based Access
+
+```yaml
+# .loki/config.yaml
+enterprise:
+  rbac:
+    oidc_role_mapping:
+      google:
+        engineering@company.com: operator
+        qa@company.com: operator
+        product@company.com: viewer
+        security@company.com: auditor
+        devops@company.com: admin
+```
+
+### Service Account Tokens
+
+```bash
+# CI/CD pipeline token
+loki enterprise token generate github-actions \
+  --role operator \
+  --scopes "control,read,write" \
+  --expires 365
+
+# Monitoring system token
+loki enterprise token generate datadog \
+  --role viewer \
+  --scopes "read" \
+  --expires 9999
+
+# Security scanner token
+loki enterprise token generate security-scanner \
+  --role auditor \
+  --scopes "read,audit" \
+  --expires 180
+```
+
+## Best Practices
+
+### Principle of Least Privilege
+
+1. Start with minimal permissions (viewer role)
+2. Grant additional scopes only as needed
+3. Use custom roles for specific use cases
+4. Review and audit role assignments quarterly
+5. Remove unused tokens immediately
+
+### Role Assignment
+
+1. Use OIDC role mapping for human users
+2. Use token-based roles for automation
+3. Separate production and development roles
+4. Document role assignments and justifications
+5. Rotate credentials regularly
+
+### Auditing
+
+1. Enable `LOKI_RBAC_AUDIT_CHECKS` to log permission checks
+2. Review audit logs for unauthorized access attempts
+3. Monitor for privilege escalation attempts
+4. Alert on admin role usage in production
+5. Generate compliance reports monthly
+
+## Troubleshooting
+
+### Permission Denied Errors
+
+```bash
+# Check token role and scopes
+loki enterprise token list
+
+# Verify required scope for operation
+loki enterprise rbac permissions --role <your-role>
+
+# Check audit log for denial reason
+loki enterprise audit tail --event permission.denied
+
+# Generate new token with correct role
+loki enterprise token revoke <old-token>
+loki enterprise token generate <name> --role operator
+```
+
+### OIDC Role Mapping Not Working
+
+```bash
+# Verify OIDC claims contain group information
+# Check identity provider configuration
+
+# Test with explicit token role first
+loki enterprise token generate test-admin --role admin
+
+# Check RBAC configuration
+cat .loki/config.yaml | grep -A 10 rbac
+
+# View OIDC claims in audit log
+loki enterprise audit tail --event auth.oidc.success
+```
+
+### Scope Confusion
+
+```bash
+# List all scopes for a role
+loki enterprise rbac permissions --role operator
+
+# Check if scope is implied by hierarchy
+# control -> write -> read
+# audit (separate, not included in control)
+
+# Test specific permission
+curl -H "Authorization: Bearer $TOKEN" \
+     http://localhost:57374/api/enterprise/rbac/check?scope=control
+```
+
+## Migration Guide
+
+### Upgrading from Token-Only to RBAC
+
+1. Enable RBAC in audit mode first:
+```bash
+export LOKI_RBAC_ENABLED=true
+export LOKI_RBAC_STRICT_MODE=false  # Allow during migration
+```
+
+2. Assign roles to existing tokens:
+```bash
+for token in $(loki enterprise token list --format json | jq -r '.[].id'); do
+  loki enterprise token update $token --role operator
+done
+```
+
+3. Test permissions:
+```bash
+loki enterprise rbac check
+```
+
+4. Enable strict mode:
+```bash
+export LOKI_RBAC_STRICT_MODE=true
+```
+
+5. Monitor audit logs for denials and adjust roles as needed.
+
+## See Also
+
+- [Authentication Guide](authentication.md) - Token and OIDC setup
+- [Audit Logging](audit-logging.md) - Track permission checks
+- [Enterprise Features](../wiki/Enterprise-Features.md) - Complete enterprise guide
+- [Network Security](network-security.md) - Additional security controls