# Epic: Security

## DESCRIPTION
Strong security posture: WireGuard encrypted mesh (Headscale), API key encryption, privacy-aware routing, PII detection, audit logging. Phase 1 is local-only (minimal attack surface). Phase 2+ adds network security for multi-node.

**POST-PIVOT (2026-02-14)**: Replaced OpenZiti with Headscale/WireGuard. See ADR-004 (SUPERSEDED). Phase 1 needs no overlay (single-node CLI). Phase 2 adds Headscale for multi-node. Privacy routing preserved at application layer.

## BACKLOG ITEMS

### SEC-001: API Key Encryption (Local)
- **Priority**: P0
- **Phase**: 1
- **Status**: BACKLOG
- **Description**: Encrypt all stored BYOK API keys at rest using envelope encryption. Keys decrypted only at point of use, never logged.
- **Acceptance**: Keys encrypted in local config. Not readable from config file. Only decrypted during API call.
- **Dependencies**: CF-003 (BYOK)

### SEC-002: Headscale Deployment
- **Priority**: P0
- **Phase**: 2
- **Status**: BACKLOG
- **Description**: Deploy Headscale coordination server (1 Docker container). Pre-auth keys for node auto-join. DERP relay for NAT traversal.
- **Acceptance**: Nodes behind NAT connect via WireGuard mesh. All inter-node traffic encrypted.
- **Dependencies**: Docker infrastructure

### SEC-003: Node Identity & Authentication
- **Priority**: P0
- **Phase**: 2
- **Status**: BACKLOG
- **Description**: Pre-auth keys for node registration with Headscale. Each node gets unique identity on WireGuard mesh.
- **Acceptance**: Only authenticated LLMHosts nodes can join the mesh. Pre-auth keys are single-use.
- **Dependencies**: SEC-002

### SEC-004: mTLS for Service Communication
- **Priority**: P1
- **Phase**: 2
- **Status**: BACKLOG
- **Description**: Mutual TLS between LLMHosts cloud services (API, dashboard backend, Headscale).
- **Acceptance**: All service-to-service communication authenticated and encrypted.
- **Dependencies**: Certificate management

### SEC-005: PII Detection & Privacy Routing
- **Priority**: P1
- **Phase**: 2
- **Status**: BACKLOG
- **Description**: Detect sensitive content (PII, health data, credentials) in requests. PRIVATE requests → local only, NEVER to Hive/cloud. Lightweight: regex + keyword matching for v1, ML classifier for v2.
- **Acceptance**: Prompts with PII never routed externally. Dashboard shows privacy routing decisions.
- **Dependencies**: CB-010 (privacy router)

### SEC-006: Headscale ACLs (Hive Mode)
- **Priority**: P1
- **Phase**: 3
- **Status**: BACKLOG
- **Description**: Headscale ACL rules gate which users' nodes can communicate (Hive membership). `llmhosts hive invite <email>` → friend's nodes get ACL access.
- **Acceptance**: Only Hive members' nodes can route to each other. ACLs managed via Headscale API.
- **Dependencies**: SEC-002, Hive Mode

### SEC-007: Audit Logging
- **Priority**: P0
- **Phase**: 1
- **Status**: BACKLOG
- **Description**: Complete trace of every request: source → routing decision → destination → cost → response. Local SQLite in Phase 1, cloud DB in Phase 2+.
- **Acceptance**: Full audit trail queryable. Searchable in dashboard. Encrypted at rest.
- **Dependencies**: CB-012

### SEC-008: Rate Limiting
- **Priority**: P1
- **Phase**: 2
- **Status**: BACKLOG
- **Description**: Multi-level rate limiting (per user, per key, per tier). Credit-based limiting for free tier.
- **Acceptance**: Rate limits enforced per tier. Clear error messages when limit hit. Upgrade prompts.
- **Dependencies**: Credit system, FE-012

### SEC-009: Security Event Monitoring
- **Priority**: P1
- **Phase**: 2
- **Status**: BACKLOG
- **Description**: Real-time alerting for security events (failed auth, unusual routing, trust violations).
- **Acceptance**: Admin notified of security events. Dashboard shows security posture.
- **Dependencies**: SEC-007, FE-017

### SEC-010: GitHub Repository Setup
- **Priority**: P0
- **Phase**: 1
- **Status**: BACKLOG
- **Description**: Initialize Git repo, push to GitHub. .gitignore (exclude docs/secure/), branch rulesets, labels, milestones, issue templates, PR template, GitHub Project board, Dependabot, secret scanning.
- **Acceptance**: Repo on GitHub with all masterclass setup. docs/secure/ never committed.
- **Dependencies**: None

### SEC-011: CI/CD Pipeline (GitHub Actions)
- **Priority**: P0
- **Phase**: 1
- **Status**: BACKLOG
- **Description**: GitHub Actions: ci.yml (lint/test/build on PR), build.yml (Docker + PyPI publish on tag), security-scan.yml (weekly Trivy).
- **Acceptance**: PRs run tests automatically. Tags publish to PyPI + Docker Hub. Weekly security scans.
- **Dependencies**: SEC-010

### SEC-012: Legal -- Terms of Service & Privacy Policy
- **Priority**: P1
- **Phase**: 3
- **Status**: BACKLOG
- **Description**: Draft ToS, Privacy Policy, Cookie Policy, AUP. Cover: data handling, Hive Mode, BYOK usage, PII routing.
- **Acceptance**: Legal documents published on website. GDPR/CCPA baseline compliance.
- **Dependencies**: None

### SEC-013: Disaster Recovery & Backup
- **Priority**: P2
- **Phase**: 4
- **Status**: BACKLOG
- **Description**: Database backup schedule, user data export, recovery procedures, RTO/RPO targets.
- **Acceptance**: Automated daily backups. User data export API. RTO <4hrs.
- **Dependencies**: Database infrastructure
