1 files changed, 95 insertions, 0 deletions
diff --git a/docs/adr/005-agent-api-authentication.md b/docs/adr/005-agent-api-authentication.md
new file mode 100644
index 0000000..e64a5a8
--- /dev/null
+++ b/docs/adr/005-agent-api-authentication.md
@@ -0,0 +1,95 @@
+# 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