# ADR 005: Agent API Authentication Architecture

## Status
Accepted

## Context
External agents (CLI tools, automation scripts, AI assistants) need secure access to dashboard context without exposing user credentials. Traditional approaches have weaknesses:

- **API Keys**: Long-lived, often stored insecurely, difficult to revoke
- **OAuth2**: Complex setup, overkill for personal dashboard
- **SSH Keys**: Key management burden on user

Requirements:
- User awareness of agent access (no hidden API keys)
- Easy revocation (deny re-auth requests)
- Time-limited sessions to reduce exposure
- Support for both CLI and browser-based agents

## Decision
Implement **notification-based approval flow** with ephemeral sessions.

### Technical Details:

**Identity Model:**
- Agents identified by `name` + `agent_id` (UUID) pair
- Binding persisted on first approval
- Impersonation detected if name/agent_id mismatch

**Trust Levels:**
- `TRUSTED`: Previously approved, auto-approve on re-auth
- `UNKNOWN`: New agent, requires user approval
- `BLOCKED`: Denied agent, reject immediately

**Session Model:**
- 1-hour TTL tokens
- One active session per agent_id
- Session token in Authorization header

**Approval Flow:**
```
Agent                    Dashboard                 Browser
  |                          |                        |
  |-- POST /auth/request --> |                        |
  |                          |-- WebSocket push ----> |
  |                          |                        | (user sees modal)
  |                          |                        |
  |<-- request_token --------|                        |
  |                          |                        |
  |-- GET /auth/poll ------> |                        |
  |   (polling)              |                        |
  |                          | <-- POST /approve ---- |
  |                          |                        |
  |<-- session_token --------|                        |
  |                          |                        |
  |-- GET /context --------> |                        |
  |   (with session_token)   |                        |
```

**Implementation:**
- `internal/handlers/agent.go` - Auth flow handlers (615 LOC)
- `internal/handlers/websocket.go` - Real-time notifications (216 LOC)
- `migrations/010_agent_tables.sql` - Storage schema
- `web/static/js/app.js` - Browser UI for approval modal

**Rate Limiting:**
- 10 requests/minute per IP on auth endpoints
- Prevents brute-force token guessing

## Consequences

**Pros:**
- User-visible agent access (approval modal shows agent name)
- Easy revocation by denying re-auth or blocking agent
- Trust level caching reduces approval fatigue for known agents
- Time-limited sessions reduce credential exposure
- Works for both CLI agents (polling) and browser agents (web endpoints)

**Cons:**
- Requires browser window open for first-time approval
- Poll loop adds latency to auth flow (~1-5 seconds)
- Session expiry interrupts long-running agent tasks (must re-auth)

## Alternatives Considered

**Option A: Traditional API Keys**
- Rejected: Long-lived credentials, no user awareness of access

**Option B: OAuth2 Device Flow**
- Rejected: Complex implementation, requires external auth server setup

**Option C: SSH-style Key Pairs**
- Rejected: Key management burden, harder to revoke

**Option D: Magic Links (email-based)**
- Rejected: Adds email dependency, slower approval flow