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

[
  {
    "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:

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