OpenSpeak/openspec/changes/add-authentication/authentication.md

# Spec Delta: Authentication & Authorization

**Change ID:** `add-authentication`
**Capability:** Authentication & Authorization
**Type:** NEW

## ADDED Requirements

### Admin Token Authentication

#### Requirement: Server shall validate admin tokens on all requests

**Description:** Every gRPC request must include a valid admin token. Server shall validate token exists, is not revoked, and not expired before processing request.

**Priority:** Critical
**Status:** Proposed

**Scenarios:**

#### Scenario: Valid token grants access
```
Given: Client has valid admin token
When: Client sends gRPC request with token in metadata
Then: Server validates token
And: Request is processed successfully
And: User context attached to request
```

#### Scenario: Invalid token rejected
```
Given: Client sends request with invalid token
When: Server receives request
Then: Server rejects with 401 Unauthorized
And: Error message returned to client
And: Request not processed
```

#### Scenario: Expired token rejected
```
Given: Token TTL is configured to 1 hour
And: Token was created 2 hours ago
When: Client sends request with expired token
Then: Server rejects with 401 Unauthorized
And: Client should refresh/re-login
```

### Permission-Based Access Control

#### Requirement: Server shall enforce permission-based access control

**Description:** Users have roles and permissions that control what actions they can perform (create channels, manage users, etc).

**Priority:** Critical
**Status:** Proposed

**Details:**
- Roles: admin, user, guest (future)
- Permissions: channels:create, channels:delete, users:manage, etc
- Check permission before allowing action

**Scenarios:**

#### Scenario: Admin creates channel
```
Given: User has admin role
When: User requests CreateChannel
Then: Permission check passes
And: Channel is created
```

#### Scenario: Regular user denied admin action
```
Given: User has 'user' role (not admin)
When: User requests DeleteChannel
Then: Permission check fails
And: Request rejected with 403 Forbidden
And: User not allowed to delete channels
```

### Authentication Interceptor

#### Requirement: All gRPC services use authentication interceptor

**Description:** Central authentication interceptor validates tokens for all RPC calls before routing to handlers.

**Priority:** Critical
**Status:** Proposed

**Scenarios:**

#### Scenario: Interceptor validates all service methods
```
Given: Client calls any gRPC method
When: Request arrives at server
Then: Authentication interceptor intercepts
And: Token extracted from metadata
And: Token validated
And: User context attached to request
And: Request forwarded to handler
```

#### Scenario: Missing token rejected immediately
```
Given: Client sends request without token
When: Request arrives at server
Then: Interceptor detects missing token
And: Request rejected with 401 Unauthorized
And: No handler invoked
```

### Token Management

#### Requirement: Admin tokens shall be managed securely

**Description:** Tokens stored in secure configuration, never logged in plaintext, rotatable, and revocable.

**Priority:** High
**Status:** Proposed

**Details:**
- Storage: `/etc/openspeak/admin_tokens.json`
- Format: JSON array of token objects
- Never logged: Tokens excluded from logs
- Rotatable: New tokens can be generated
- Revocable: Tokens can be marked revoked

**Scenarios:**

#### Scenario: Token stored securely
```
Given: Admin creates new token
When: Token is stored
Then: Token stored in secure file with 0600 permissions
And: Token not stored in logs
And: Token not visible in debug output
```

#### Scenario: Token rotation
```
Given: Current token is compromised
When: Admin generates new token
And: Old token marked revoked
Then: Old token rejected on next request
And: New token accepted
```

## ACCEPTANCE CRITERIA

- [ ] All RPC methods require and validate token
- [ ] Invalid tokens return 401 Unauthorized
- [ ] Expired tokens return 401 Unauthorized
- [ ] Permission checks prevent unauthorized actions
- [ ] Tokens never logged in plaintext
- [ ] Token validation latency <10ms
- [ ] Unit test coverage >80%
- [ ] Security review passes

## TESTING STRATEGY

### Unit Tests
- Test token validation logic
- Test permission checking
- Test expired token handling
- Test permission combinations

### Integration Tests
- Test authentication interceptor on all services
- Test end-to-end request with valid/invalid tokens
- Test permission enforcement on different service methods

### Security Tests
- Attempt requests without token
- Attempt requests with malformed token
- Attempt token reuse after revocation
- Verify tokens not logged