OpenSpeak/openspec/specs/002-authentication.md

# Feature Specification: Authentication & Authorization

**ID:** AUTH-001
**Version:** 1.0
**Status:** Planned
**Priority:** Critical

## Overview
Authentication and authorization system for user login, token validation, and access control to server resources and channels.

## Authentication System (Phase 1)

### Admin Token Authentication
Initial implementation uses admin tokens stored locally on the server.

**Token Format:**
- Length: 32 alphanumeric characters (random)
- Storage: Plain text in `config/admin_tokens.txt` or environment variable
- Transmission: HTTPS/TLS only
- Lifetime: Configurable TTL (default: no expiration for MVP)

**Token Generation:**
```
Server generates random 32-char alphanumeric token
Operator stores token securely (1Password, environment variable, etc.)
Client uses token for all API calls
```

**Validation Flow:**
```
Client sends token in gRPC metadata
    ↓
Server validates token exists and is not expired
    ↓
Grant access to requested resource
    ↓
OR reject with 401 Unauthorized
```

### Token Storage
- **Location:** `/etc/openspeak/admin_tokens.json` or environment
- **Format:** JSON array of token objects
```json
[
  {
    "token": "abcd1234efgh5678ijkl9012mnop3456",
    "name": "admin",
    "created": "2024-01-01T00:00:00Z",
    "expires": null,
    "permissions": ["admin", "create_channel", "manage_users"]
  }
]
```
- **Permissions:** Read-only, write by authorized admin only

## Authentication System (Phase 2 - Future)

### User Accounts
Once infrastructure is ready, support proper user accounts:
- Username/email + password authentication
- Password hashing (bcrypt, Argon2)
- Optional 2FA via TOTP
- Session tokens with expiration
- Refresh token mechanism

## Authorization (Access Control)

### Permission Model
**Roles:**
- `admin`: Full server access, user/channel management
- `user`: Normal user access, join public channels
- `guest`: Limited access, listen-only mode (future)

**Resource Permissions:**
- `channels:create`: Create new voice channels
- `channels:delete`: Delete voice channels
- `channels:manage`: Modify channel settings
- `channels:join`: Join voice channels
- `users:list`: View list of online users
- `users:manage`: Manage user permissions
- `server:admin`: Server administration

### Channel Access Control
**Channel Properties:**
- Public/Private flag
- Whitelist of users (for private channels)
- Role-based access (future)
- Age restriction (future)

**Access Check:**
```
User requests to join channel
    ↓
Check: Is user authenticated? → NO: Reject
    ↓
Check: Is channel public? → YES: Allow
    ↓
Check: Is user in whitelist? → YES: Allow, NO: Reject
```

## Implementation Details

### gRPC Authentication Interceptor
All gRPC calls validated with metadata:
```protobuf
message AuthRequest {
  string token = 1;
}

metadata: "authorization: Bearer <token>"
```

**Interceptor Behavior:**
- Extract token from metadata
- Validate against stored tokens
- Attach user context to request
- Allow call to proceed or reject with Unauthenticated error

### Token Refresh (Phase 2)
- Short-lived access tokens (15 minutes)
- Long-lived refresh tokens (7 days)
- Client automatically refreshes before expiration
- Revoked tokens invalidated immediately

### Logout
- Client disconnects (implicit logout)
- Server cleans up user session
- Voice stream terminated gracefully
- User marked as offline

## Security Requirements
- All authentication traffic over TLS (mandatory)
- Tokens never logged in plaintext
- Tokens not transmitted over unencrypted connections
- Token rotation capability
- Audit logging of authentication attempts
- Rate limiting on authentication attempts (phase 2)

## Configuration
- Admin token list location
- Token expiration policy
- Password requirements (phase 2)
- Session timeout duration
- Max failed login attempts (phase 2)

## Error Handling
- Invalid token: Return 401 Unauthorized with clear message
- Expired token: Return 401 Unauthorized (client should refresh)
- Missing token: Return 401 Unauthorized
- Insufficient permissions: Return 403 Forbidden
- Rate limited: Return 429 Too Many Requests (phase 2)

## Testing Strategy
- Unit tests for token validation
- Unit tests for permission checking
- Integration tests for gRPC authentication
- Security tests for token extraction from metadata
- Tests for expired token handling
- Audit log verification tests