loki-mode 5.42.2 → 5.46.0

package/docs/authentication.md

@@ -0,0 +1,374 @@
+# Authentication Guide
+
+Authentication and access control for Loki Mode dashboard and API.
+
+## Overview
+
+Loki Mode supports two authentication methods:
+
+1. **Token-based authentication** - API tokens with scopes and expiration
+2. **OIDC/SSO integration** (v5.36.0) - Google, Azure AD, Okta
+
+Both methods can be enabled simultaneously and provide access to the dashboard API at `http://localhost:57374` (or `https://` with TLS enabled).
+
+## Token-Based Authentication
+
+### Enable Authentication
+
+```bash
+export LOKI_ENTERPRISE_AUTH=true
+loki start ./prd.md
+```
+
+### Generate Tokens
+
+```bash
+# Basic token
+loki enterprise token generate my-token
+
+# With scopes and expiration
+loki enterprise token generate ci-bot --scopes "read,write" --expires 30
+
+# With role
+loki enterprise token generate admin-bot --role admin --expires 90
+```
+
+Output:
+
+```
+Token generated successfully!
+
+Name:    ci-bot
+ID:      tok-abc123
+Token:   loki_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+Scopes:  read, write
+Expires: 2026-03-15
+
+IMPORTANT: Save this token - it won't be shown again!
+```
+
+### Use Tokens with API
+
+Include the token in the `Authorization` header:
+
+```bash
+curl -H "Authorization: Bearer loki_xxx..." \
+     http://localhost:57374/api/status
+```
+
+### Manage Tokens
+
+```bash
+# List active tokens
+loki enterprise token list
+
+# List all tokens (including revoked)
+loki enterprise token list --all
+
+# Revoke a token
+loki enterprise token revoke ci-bot
+
+# Revoke by token ID
+loki enterprise token revoke tok-abc123
+```
+
+### Token Storage
+
+Tokens are stored securely in `~/.loki/dashboard/tokens.json` with:
+
+- SHA256 hashed token values (plaintext never stored)
+- 0600 file permissions (read/write for owner only)
+- Constant-time comparison to prevent timing attacks
+
+### Token Scopes
+
+| Scope | Description | Included In |
+|-------|-------------|-------------|
+| `*` | All operations | Admin role |
+| `control` | Start/stop sessions, modify tasks | Operator role, Admin role |
+| `write` | Create/update tasks, modify state | Operator role, Admin role |
+| `read` | View dashboard, logs, metrics | All roles |
+| `audit` | View audit logs | Auditor role, Admin role |
+
+Scope hierarchy:
+- `*` includes all scopes
+- `control` includes `write` and `read`
+- `write` includes `read`
+
+### Roles (v5.37.0)
+
+Predefined roles map to common access patterns:
+
+| Role | Scopes | Description |
+|------|--------|-------------|
+| `admin` | `*` | Full access to all endpoints |
+| `operator` | `control`, `read`, `write` | Start/stop sessions, manage tasks |
+| `viewer` | `read` | Read-only dashboard access |
+| `auditor` | `read`, `audit` | Read access plus audit log viewing |
+
+Generate token with role:
+
+```bash
+loki enterprise token generate viewer-bot --role viewer
+```
+
+Generate token with custom scopes:
+
+```bash
+loki enterprise token generate custom-bot --scopes "read,audit" --expires 30
+```
+
+## OIDC/SSO Authentication (v5.36.0)
+
+Enterprise identity provider integration for centralized authentication.
+
+### Enable OIDC
+
+Configure OIDC environment variables for your identity provider:
+
+#### Google Workspace
+
+```bash
+export LOKI_OIDC_ISSUER=https://accounts.google.com
+export LOKI_OIDC_CLIENT_ID=your-client-id.apps.googleusercontent.com
+```
+
+#### Azure AD
+
+```bash
+export LOKI_OIDC_ISSUER=https://login.microsoftonline.com/{tenant}/v2.0
+export LOKI_OIDC_CLIENT_ID=your-application-id
+```
+
+#### Okta
+
+```bash
+export LOKI_OIDC_ISSUER=https://your-org.okta.com
+export LOKI_OIDC_CLIENT_ID=your-client-id
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOKI_OIDC_ISSUER` | - | OIDC issuer URL (required) |
+| `LOKI_OIDC_CLIENT_ID` | - | OIDC client/application ID (required) |
+| `LOKI_OIDC_AUDIENCE` | *(client_id)* | Expected JWT audience claim |
+| `LOKI_OIDC_SCOPES` | `openid,email,profile` | OIDC scopes to request |
+
+### OIDC Flow
+
+1. User navigates to dashboard
+2. Redirect to identity provider login
+3. User authenticates with corporate credentials
+4. Provider redirects back with JWT
+5. Dashboard validates JWT and grants access
+
+OIDC-authenticated users receive full access scopes by default. For fine-grained control, combine OIDC with token-based authorization.
+
+### Mixed Mode
+
+OIDC and token auth can be active simultaneously:
+
+- OIDC for human users (web dashboard)
+- Tokens for automation (CI/CD, scripts, integrations)
+
+```bash
+export LOKI_ENTERPRISE_AUTH=true
+export LOKI_OIDC_ISSUER=https://accounts.google.com
+export LOKI_OIDC_CLIENT_ID=your-client-id
+
+loki start ./prd.md
+```
+
+## Configuration File
+
+Persist authentication settings in `.loki/config.yaml`:
+
+```yaml
+enterprise:
+  auth:
+    enabled: true
+    oidc:
+      issuer: https://accounts.google.com
+      client_id: your-client-id.apps.googleusercontent.com
+      audience: your-client-id.apps.googleusercontent.com
+  tokens:
+    default_expiration_days: 90
+    max_active_per_user: 10
+```
+
+## API Endpoints
+
+### Token Management
+
+```bash
+# Create token
+POST /api/enterprise/tokens
+{
+  "name": "ci-bot",
+  "scopes": ["read", "write"],
+  "expires_days": 30
+}
+
+# List tokens
+GET /api/enterprise/tokens
+
+# Revoke token
+DELETE /api/enterprise/tokens/{token_id}
+```
+
+### OIDC
+
+```bash
+# Initiate OIDC login
+GET /auth/oidc/login
+
+# OIDC callback (handled automatically)
+GET /auth/oidc/callback?code=...
+
+# Logout
+GET /auth/logout
+```
+
+## Security Best Practices
+
+### Token Management
+
+1. Generate separate tokens for each integration
+2. Use minimal scopes (principle of least privilege)
+3. Set expiration dates on all tokens
+4. Revoke unused tokens immediately
+5. Never commit tokens to version control
+6. Rotate tokens regularly (every 90 days recommended)
+7. Use environment variables or secret managers, not hardcoded values
+
+### OIDC
+
+1. Use HTTPS/TLS for all OIDC endpoints
+2. Validate JWT signatures
+3. Check token expiration
+4. Verify audience claim
+5. Use short-lived tokens (15 minutes recommended)
+6. Implement session timeout
+7. Log all authentication events
+
+### General
+
+1. Enable `LOKI_ENTERPRISE_AUTH` in production
+2. Enable `LOKI_TLS_ENABLED` for encrypted connections
+3. Use audit logging to track authentication events
+4. Monitor failed authentication attempts
+5. Implement rate limiting on auth endpoints
+6. Use strong entropy for token generation
+7. Store credentials in secure secrets management (AWS Secrets Manager, HashiCorp Vault)
+
+## Troubleshooting
+
+### Token Authentication Fails
+
+```bash
+# Check token is not expired
+loki enterprise token list
+
+# Verify token format (should start with "loki_")
+echo $LOKI_TOKEN
+
+# Check permissions file exists
+ls -la ~/.loki/dashboard/tokens.json
+
+# Verify scopes
+curl -H "Authorization: Bearer $LOKI_TOKEN" \
+     http://localhost:57374/api/status -v
+```
+
+### OIDC Login Fails
+
+```bash
+# Verify issuer URL is reachable
+curl https://accounts.google.com/.well-known/openid-configuration
+
+# Check client ID is correct
+echo $LOKI_OIDC_CLIENT_ID
+
+# View authentication logs
+loki enterprise audit tail --event auth.fail
+
+# Check redirect URI is whitelisted in identity provider
+# Should be: http://localhost:57374/auth/oidc/callback
+```
+
+### Permissions Denied
+
+```bash
+# Check token scopes
+loki enterprise token list
+
+# Verify required scope for endpoint
+# /api/status -> read
+# /api/control/start -> control
+# /api/tasks/create -> write
+
+# Generate new token with correct scopes
+loki enterprise token generate new-token --scopes "read,write,control"
+```
+
+## Examples
+
+### CI/CD Integration
+
+```yaml
+# .github/workflows/loki.yml
+name: Loki Mode
+on: [push]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run Loki Mode
+        env:
+          LOKI_TOKEN: ${{ secrets.LOKI_TOKEN }}
+        run: |
+          curl -H "Authorization: Bearer $LOKI_TOKEN" \
+               -X POST \
+               -d '{"prd": "./prd.md"}' \
+               http://loki-server:57374/api/control/start
+```
+
+### Python Client
+
+```python
+import requests
+
+class LokiClient:
+    def __init__(self, base_url, token):
+        self.base_url = base_url
+        self.headers = {"Authorization": f"Bearer {token}"}
+
+    def get_status(self):
+        response = requests.get(
+            f"{self.base_url}/api/status",
+            headers=self.headers
+        )
+        return response.json()
+
+    def start_session(self, prd_file):
+        response = requests.post(
+            f"{self.base_url}/api/control/start",
+            json={"prd": prd_file},
+            headers=self.headers
+        )
+        return response.json()
+
+client = LokiClient("http://localhost:57374", "loki_xxx...")
+status = client.get_status()
+print(status)
+```
+
+## See Also
+
+- [Authorization Guide](authorization.md) - RBAC and permissions
+- [Network Security](network-security.md) - TLS/HTTPS setup
+- [Audit Logging](audit-logging.md) - Authentication event tracking
+- [Enterprise Features](../wiki/Enterprise-Features.md) - Complete enterprise guide