🔑 KeyLocker — Protocol Files

# KeyLocker — Brief **One-line:** A single-user, self-hosted API key manager for developers who need keys at their fingertips without the friction of a password manager. **The problem:** Developers manage dozens of API keys across multiple providers and applications. Password managers treat keys like passwords — too slow to retrieve mid-flow. Developers resort to `.env` files, unencrypted text files, or memorizing keys, which is insecure and breaks flow. **Core features:** - Add a key in under 10 seconds (name, key, provider, app) - One-click copy + 30-second automatic clipboard clearing - Search and filter by name, provider, application, environment - Direct one-click links to every provider's key management page - AES-256-GCM encryption at rest with Argon2id key derivation - Keyboard-driven interface (Ctrl+N, Ctrl+F, Ctrl+L, Ctrl+K) - Four themes: Dark, Sepia, Slate, Light — switch with `[` / `]` **Success looks like:** A developer can go from "I need my Stripe prod key" to having it pasted in their terminal in under 3 seconds. **Constraints:** - Single-user, single-session (no team features in v1) - No browser extension (webapp first, extension later) - No PWA / offline support in v1 - Self-hosted only — no cloud sync - Encryption is unrecoverable by design — lose the master password, lose everything

Full SPEC.md on GitHub:

https://github.com/mccloudmedia/keylocker/blob/main/SPEC.md

Screens: Lock Screen · Key List · Add/Edit Modal · Command Palette (Ctrl+K)
Data Model: keys (encrypted) · providers · settings
Encryption: Master Password → Argon2id → 256-bit key → AES-256-GCM
Rules: clipboard auto-clear, session, search, provider URLs
Edge cases: 11 scenarios (empty state, duplicate names, lost password, etc.)
Stress test: 12 scenarios × capability matrix
Non-goals: 10 items explicitly excluded from v1

# KeyLocker — Architecture ## Overview Single-user, self-hosted API key management webapp. Server-rendered HTML with a dense TUI-style interface, encrypted at rest, keyboard-driven. Deployed via Docker on vps-apps behind Traefik. ## Tech Stack | Layer | Choice | Rationale | |---|---|---| | Backend | FastAPI (Python) | Lightweight, well-audited crypto | | Frontend | Server-rendered HTML + CSS + JS | No SPA needed | | Database | SQLite (single file) | Zero ops overhead | | Encryption | AES-256-GCM + Argon2id | Battle-tested | | Container | Docker (nginx + gunicorn) | Minimal footprint | | Deploy | vps-apps → `keys.mccloud.media` | Traefik + SSL | ## Encryption Architecture ``` Master Password ↓ Argon2id (salt stored in settings table) ↓ 256-bit derived key (memory only — never stored) ↓ AES-256-GCM encrypt/decrypt each key's `encrypted_key` field ↓ Per-key random 12-byte nonce prepended to ciphertext ``` ## Data Model **keys table:** id, name, encrypted_key, provider, application, environment, expires_at, permissions, notes, provider_url, created_at, updated_at, version **providers table:** id, name, key_url, is_builtin **settings table:** theme, clipboard_clear_seconds, key (salt + params) ## Key Rules - Clipboard auto-clear: 30s (configurable) - Session: until explicit lock (Ctrl+L) - Search: case-insensitive substring on name/provider/application - Master password lost: irrecoverable ## Non-Goals (v1) No multi-user · No browser ext · No CLI · No PWA · No export · No audit log · No mobile

# KeyLocker — Tasks ## Phase 1: Foundation (DONE) - [x] Product ideation & problem definition - [x] SPEC.md written with data model, screens, edge cases, stress test - [x] Tech stack selected (FastAPI + SQLite + AES-256-GCM) - [x] Repo initialized at `/opt/data/keylocker/` ## Phase 2: Backend Core - [ ] Scaffold FastAPI project structure → `app/`, `requirements.txt`, config - [ ] Encryption module → Argon2id KDF + AES-256-GCM encrypt/decrypt - [ ] SQLite schema → `keys`, `providers`, `settings` tables - [ ] First-run setup → create master password, generate salt, initialize DB - [ ] CRUD endpoints for keys → list, create, read, update, delete - [ ] Provider endpoints → list built-in + custom providers - [ ] Settings endpoints → theme, clipboard timer - [ ] Session management → master password auth, lock/unlock ## Phase 3: Frontend - [ ] Lock screen → master password entry - [ ] Main screen → key table with search + filters - [ ] Add/Edit key modal - [ ] Command palette → Ctrl+K - [ ] Copy-to-clipboard with auto-clear - [ ] Theme system → Dark / Sepia / Slate / Light - [ ] Keyboard shortcuts → Ctrl+N, Ctrl+F, Ctrl+L, `[` / `]` - [ ] Provider quick-link submenu ## Phase 4: Polish & Security - [ ] Empty / error / loading states - [ ] Clipboard denied fallback - [ ] Optimistic locking - [ ] Input validation & sanitization - [ ] Secret stripping - [ ] XSS / CSRF protections - [ ] DB file permissions (600) ## Phase 5: Deploy - [ ] Dockerfile → gunicorn + nginx:alpine - [ ] `.dockerignore` - [ ] Docker Compose / docker run + Traefik labels - [ ] Deploy to vps-apps → `keys.mccloud.media` - [ ] Smoke test every flow in production ## Decisions Log | Decision | Rationale | |---|---| | Single-user, Path A | Ship fast, generalize later | | Webapp first, ext later | Immediate value | | Ctrl+L lock, no timeout | Don't break dev flow | | Clipboard auto-clear 30s | Standard security | | TUI-style dense layout | Proven design preference |

# KeyLocker — Deploy ## Target | Thing | Value | |---|---| | Server | vps-apps (72.62.96.149) | | Domain | `keys.mccloud.media` | | Method | Docker + Traefik, SSH via key auth | | Service name | `keylocker` | ## Container Setup Build stage: gunicorn serving FastAPI. Serving stage: nginx:alpine (reverse proxy to gunicorn). ## Traefik Labels ``` traefik.enable=true traefik.http.routers.keylocker-http.rule=Host(`keys.mccloud.media`) traefik.http.routers.keylocker-http.entrypoints=http traefik.http.routers.keylocker.entrypoints=https traefik.http.routers.keylocker.tls=true traefik.http.routers.keylocker.tls.certResolver=letsencrypt ``` ## Volumes - `keylocker-data:/app/data` (persistent SQLite DB) - Docker socket for container management ## Post-Deploy Verification 1. Visit `https://keys.mccloud.media` — lock screen renders 2. Create master password — first-run flow works 3. Add a test key — encrypt and store 4. Lock and re-unlock — session persists 5. Copy a key — clipboard timer counts down