# Credential Vault System - Technical Specification **Version**: 1.0 **Date**: 2025-10-21 **Status**: Implementation Ready **Solution**: KeePassXC (Option A - Industry Standard) --- ## Executive Summary Multi-project credential management system using KeePassXC as the secure vault backend with custom HTML UI for per-project credential access. Implements defense-in-depth security with encrypted storage, automated backups, and integration with existing development workflows. **Key Decision**: KeePassXC chosen over Bitwarden for local-first architecture, simpler backups, and better CLI automation. --- ## 1. Requirements ### Functional Requirements **FR1: Multi-Project Support** - Support 4 projects: tractatus, family-history, passport-consolidated, sydigital - Organize credentials by project in vault structure - Separate HTML interface per project **FR2: Credential Types** - API Keys: Stripe (live + test), Anthropic, ProtonBridge - Cloud Services: OVHCloud - Backup Services: BorgBackup - Database: MongoDB credentials - SSH: Deployment keys - JWT: Application secrets **FR3: 2FA/TOTP Support** - Store TOTP secrets in KeePassXC - Generate 2FA codes via keepassxc-cli - Display codes in HTML UI with countdown timer **FR4: Secure Access** - Master password protection (KeePassXC database) - Key file optional (additional security layer) - Auto-lock after inactivity **FR5: Backup Strategy** - Local backup: External SSD card - Remote backup: OVHCloud (encrypted) - Automated daily backups - Retention: 30 days local, 90 days remote ### Non-Functional Requirements **NFR1: Security (Defense-in-Depth)** - Layer 1: KeePassXC AES-256 encryption - Layer 2: File system permissions (600) - Layer 3: Encrypted backups (GPG + borg) - Layer 4: Audit logging (who accessed what) - Layer 5: Auto-lock on inactivity **NFR2: Usability** - HTML UI accessible via browser (localhost only) - Single-click credential copy to clipboard - Visual 2FA code display with countdown - Project-specific landing pages **NFR3: Integration** - Populate .env files from vault - Update credentials across all projects - Verification after credential rotation **NFR4: Reliability** - Backup verification (restore test monthly) - Multiple backup locations (SSD + OVHCloud) - Corruption detection (checksums) --- ## 2. Architecture ### System Components ``` ┌─────────────────────────────────────────────────────────┐ │ User Interface Layer │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │ │ HTML UI │ │ CLI Tool │ │ Integration │ │ │ │ (Browser) │ │ (Scripts) │ │ Scripts │ │ │ └─────────────┘ └─────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Application Layer │ │ ┌──────────────────────────────────────────────────┐ │ │ │ keepassxc-cli (Command Line Interface) │ │ │ │ - Read credentials │ │ │ │ - Generate TOTP codes │ │ │ │ - Export to .env format │ │ │ └──────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Storage Layer │ │ ┌──────────────────────────────────────────────────┐ │ │ │ KeePassXC Database (.kdbx) │ │ │ │ Location: ~/Documents/credentials/vault.kdbx │ │ │ │ Encryption: AES-256, Argon2 KDF │ │ │ │ Structure: │ │ │ │ /tractatus/ │ │ │ │ /family-history/ │ │ │ │ /passport-consolidated/ │ │ │ │ /sydigital/ │ │ │ │ /shared/ │ │ │ └──────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Backup Layer │ │ ┌──────────────────┐ ┌────────────────────┐ │ │ │ Local SSD │ │ OVHCloud │ │ │ │ /media/ssd/ │ │ via borg backup │ │ │ │ Daily backup │ │ Encrypted remote │ │ │ └──────────────────┘ └────────────────────┘ │ └─────────────────────────────────────────────────────────┘ ``` ### File Structure ``` ~/Documents/credentials/ ├── vault.kdbx # Master KeePassXC database ├── vault.kdbx.key # Optional key file (recommended) ├── backups/ │ ├── vault-YYYY-MM-DD.kdbx # Local daily backups (30 days) │ └── checksums.txt # SHA256 checksums for verification ├── logs/ │ └── access-log.txt # Audit log (who accessed what) └── scripts/ ├── backup-vault.sh # Automated backup script ├── populate-env.sh # Populate project .env files └── rotate-credential.sh # Credential rotation helper ~/projects/tractatus/ ├── .credential-vault/ # Project-specific vault UI │ ├── index.html # Credential management interface │ ├── vault-ui.js # UI logic (uses keepassxc-cli) │ └── vault-ui.css # Styling └── scripts/ └── get-credentials.sh # Project integration script ``` --- ## 3. Database Structure (KeePassXC) ### Organization Hierarchy ``` vault.kdbx ├── tractatus/ │ ├── Anthropic API Key │ │ ├── Username: family-history-ocr │ │ ├── Password: sk-ant-api03-NEW_KEY_HERE │ │ ├── URL: https://console.anthropic.com │ │ └── Notes: Used for tractatus AI governance │ ├── MongoDB Production │ │ ├── Username: tractatus_user │ │ ├── Password: uV6IajYK7pdrqY1uGad... │ │ └── URL: mongodb://localhost:27017/tractatus_prod │ ├── JWT Secret │ │ ├── Password: [256-bit hex secret] │ │ └── Notes: Rotate quarterly │ └── OVHCloud SSH Key │ ├── Username: ubuntu │ ├── Password: [private key path] │ └── Attachment: tractatus_deploy.key │ ├── family-history/ │ ├── Anthropic API Key │ │ └── Password: sk-ant-api03-... │ ├── Stripe Live Keys │ │ ├── Secret Key: sk_live_... │ │ ├── Publishable Key: pk_live_... │ │ └── TOTP: [Enable 2FA secret] │ └── ProtonBridge │ ├── Username: [email] │ └── Password: [bridge password] │ ├── passport-consolidated/ │ ├── Database Credentials │ └── API Keys │ ├── sydigital/ │ ├── OVHCloud API │ │ ├── Application Key: [key] │ │ ├── Application Secret: [secret] │ │ ├── Consumer Key: [key] │ │ └── TOTP: [2FA secret] │ └── Domain Registrar │ └── TOTP: [2FA secret] │ └── shared/ ├── BorgBackup Passphrase │ ├── Password: [passphrase] │ └── Notes: Used for all borg repositories ├── OVHCloud Account │ ├── Username: [account] │ ├── Password: [password] │ └── TOTP: [2FA secret] └── SSH Master Key └── Attachment: id_ed25519 (master key) ``` ### Entry Template (JSON representation) ```json { "title": "Anthropic API Key (Tractatus)", "username": "family-history-ocr", "password": "sk-ant-api03-NEW_KEY_HERE", "url": "https://console.anthropic.com/settings/keys", "notes": "Created: 2025-10-21\nPurpose: Tractatus AI governance framework\nRotate: When compromised\nLast rotated: 2025-10-21", "totp": "", "tags": ["api-key", "anthropic", "production"], "expires": "Never", "custom_fields": { "project": "tractatus", "env_var": "CLAUDE_API_KEY", "key_id": "5043628", "key_name": "tractatus-production" } } ``` --- ## 4. HTML UI Design ### Project Landing Page (tractatus example) **File**: `~/projects/tractatus/.credential-vault/index.html` **Features**: - Display all credentials for current project - Copy to clipboard functionality - TOTP code generation with countdown - Credential search/filter - Recent access log - Quick links to populate .env files **Security**: - Localhost only (127.0.0.1:8888) - Requires master password on first access - Auto-lock after 15 minutes inactivity - No credential storage in browser (fetch via keepassxc-cli) ### UI Mockup ``` ┌────────────────────────────────────────────────────────────┐ │ 🔐 Tractatus Credential Vault [Lock] │ ├────────────────────────────────────────────────────────────┤ │ Search: [________________] Filter: [All] [API] [DB] │ ├────────────────────────────────────────────────────────────┤ │ │ │ 📦 Anthropic API Key [Show] │ │ ├─ Key ID: 5043628 │ │ ├─ Name: tractatus-production │ │ ├─ Key: sk-ant-api03-•••••••••••••••• [Copy] │ │ └─ Last rotated: 2025-10-21 │ │ │ │ 📦 MongoDB Production [Show] │ │ ├─ Connection: mongodb://localhost:27017/... [Copy] │ │ ├─ Username: tractatus_user [Copy] │ │ ├─ Password: •••••••••••••••••• [Copy] │ │ └─ Last accessed: 2 hours ago │ │ │ │ 📦 JWT Secret [Show] │ │ ├─ Secret: •••••••••••••••••• [Copy] │ │ └─ ⚠️ Rotate quarterly (Next: 2026-01-21) │ │ │ │ 📦 Stripe Live Keys [Show] │ │ ├─ Secret Key: sk_live_•••••••••••••• [Copy] │ │ ├─ Publishable: pk_live_•••••••••••••• [Copy] │ │ ├─ 2FA Code: 123 456 (expires in 18s) ⏱️ [Copy] │ │ └─ Dashboard: https://dashboard.stripe.com [Open] │ │ │ ├────────────────────────────────────────────────────────────┤ │ Quick Actions: │ │ [Populate .env] [Rotate All] [Backup Now] [Audit Log] │ └────────────────────────────────────────────────────────────┘ ``` --- ## 5. Integration Scripts ### populate-env.sh **Purpose**: Populate project .env files from KeePassXC vault **Usage**: ```bash cd ~/projects/tractatus ./scripts/get-credentials.sh --populate-env ``` **Functionality**: 1. Prompts for master password (or uses gpg-agent cache) 2. Reads credentials from KeePassXC database 3. Creates/updates .env file with format: ``` # Auto-generated from KeePassXC vault # Generated: 2025-10-21 12:34:56 # DO NOT COMMIT THIS FILE CLAUDE_API_KEY=sk-ant-api03-NEW_KEY_HERE MONGODB_URI=mongodb://tractatus_user:PASSWORD@localhost:27017/tractatus_prod JWT_SECRET=256_BIT_HEX_SECRET ``` 4. Sets file permissions to 600 5. Logs access to audit log ### rotate-credential.sh **Purpose**: Rotate a credential across all projects **Usage**: ```bash ./scripts/rotate-credential.sh --credential "Anthropic API Key" --new-value "sk-ant-api03-NEW_KEY" ``` **Functionality**: 1. Updates credential in KeePassXC database 2. Updates .env files in all projects using this credential 3. Creates backup of old credential 4. Logs rotation event 5. Verifies new credential works (optional test command) --- ## 6. Backup Strategy ### Local Backup (SSD) **Location**: `/media/[username]/SSD_CARD/credential-backups/` **Schedule**: Daily at 02:00 (via cron) **Script**: `~/Documents/credentials/scripts/backup-vault.sh` **Process**: 1. Create timestamped copy: `vault-YYYY-MM-DD.kdbx` 2. Calculate SHA256 checksum 3. Copy to SSD with rsync 4. Verify copy integrity (checksum match) 5. Rotate old backups (keep 30 days) 6. Log backup result **Cron entry**: ```bash 0 2 * * * /home/theflow/Documents/credentials/scripts/backup-vault.sh >> /home/theflow/Documents/credentials/logs/backup.log 2>&1 ``` ### Remote Backup (OVHCloud via Borg) **Repository**: `ssh://ubuntu@vps-93a693da.vps.ovh.net/var/backups/credential-vault` **Schedule**: Daily at 03:00 (after local backup) **Encryption**: Borg encryption + GPG for extra layer **Process**: 1. Create borg backup of `~/Documents/credentials/` 2. Borg handles deduplication and compression 3. Encrypt with borg passphrase (stored in vault!) 4. Keep 90 days of backups 5. Monthly restore test (automated verification) **Retention Policy**: - Keep all backups for last 7 days - Keep 1 backup per week for last 4 weeks - Keep 1 backup per month for last 3 months --- ## 7. Security Implementation ### Encryption Layers **Layer 1: KeePassXC Database Encryption** - Algorithm: AES-256-CBC or ChaCha20 - KDF: Argon2 (memory-hard, GPU-resistant) - Iterations: 10 rounds (balance security vs performance) - Key file: Optional additional entropy **Layer 2: File System Permissions** ```bash chmod 600 ~/Documents/credentials/vault.kdbx chmod 700 ~/Documents/credentials/ chmod 600 ~/projects/*/env ``` **Layer 3: Backup Encryption** - Borg backup uses separate passphrase - GPG encryption for critical exports - SSD backup on encrypted filesystem (LUKS) **Layer 4: Network Security** - HTML UI on localhost only (no remote access) - SSH key authentication for OVHCloud (no passwords) - Borg backup over SSH tunnel ### Access Control **Master Password Requirements**: - Minimum 20 characters - Mix of uppercase, lowercase, numbers, symbols - NOT derived from dictionary words - NOT reused from other services - Stored ONLY in memory (never written to disk) **Auto-lock Settings**: - Lock database after 15 minutes inactivity - Lock immediately on system sleep/suspend - Clear clipboard after 30 seconds ### Audit Logging **Log Location**: `~/Documents/credentials/logs/access-log.txt` **Format**: ``` 2025-10-21 12:34:56 | READ | tractatus/Anthropic API Key | populate-env.sh | SUCCESS 2025-10-21 12:35:12 | COPY | tractatus/MongoDB Production | vault-ui.js | SUCCESS 2025-10-21 14:22:33 | UPDATE | tractatus/JWT Secret | rotate-credential.sh | SUCCESS ``` **Retention**: 90 days, then archive to borg backup --- ## 8. Implementation Phases ### Phase 1: Foundation (Day 1) **Deliverables**: - ✅ KeePassXC installed (already complete) - Create master database with initial structure - Add existing credentials from current .env files - Enable TOTP for services that support it - Test CLI access (keepassxc-cli) **Time Estimate**: 2-3 hours ### Phase 2: Automation (Day 2-3) **Deliverables**: - `populate-env.sh` script for each project - `backup-vault.sh` with SSD and OVHCloud targets - Cron jobs for automated backups - Test credential rotation workflow **Time Estimate**: 4-6 hours ### Phase 3: HTML UI (Day 4-5) **Deliverables**: - HTML interface for tractatus (template) - JavaScript integration with keepassxc-cli - TOTP code display with countdown - Copy-to-clipboard functionality - Replicate for other 3 projects **Time Estimate**: 6-8 hours ### Phase 4: Integration & Testing (Day 6-7) **Deliverables**: - Test credential population in all 4 projects - Verify backup/restore procedures - Security audit (file permissions, encryption) - Documentation and user guide - Training on credential rotation workflow **Time Estimate**: 4-6 hours --- ## 9. Migration Plan ### Current State → Future State **Current** (INSECURE): ``` tractatus/.env (credentials in plaintext) family-history/.env (credentials in plaintext) passport-consolidated/.env (credentials in plaintext) sydigital/.env (credentials in plaintext) ``` **Future** (SECURE): ``` ~/Documents/credentials/vault.kdbx (encrypted master vault) ↓ (keepassxc-cli) tractatus/.env (generated from vault, gitignored) family-history/.env (generated from vault, gitignored) passport-consolidated/.env (generated from vault, gitignored) sydigital/.env (generated from vault, gitignored) ``` ### Migration Steps 1. **Audit Current Credentials** (CRITICAL - do first!) ```bash # Collect all credentials from existing .env files grep -h "^[A-Z_]*=" ~/projects/*/.env | sort | uniq > current-credentials.txt ``` 2. **Create KeePassXC Database** - Master password: Generate strong 24+ character passphrase - Key file: Generate additional entropy file - Save both securely (write down master password, store key file separately) 3. **Import Credentials** - Manually add each credential to vault with proper metadata - Organize by project (4 folders) - Add TOTP secrets for services with 2FA - Tag with custom fields (env_var name, project, purpose) 4. **Verify Population** - Run populate-env.sh for each project - Compare generated .env with original - Test each project starts correctly with new .env 5. **Setup Backups** - Run initial backup to SSD - Run initial borg backup to OVHCloud - Verify restore from both sources 6. **Secure Old Credentials** - Create encrypted archive of old .env files (for reference) - Remove plaintext credentials from old .env files - Update .gitignore to ensure .env never committed 7. **Document & Train** - Create user guide for credential access - Document rotation procedures - Test emergency recovery (SSD + OVHCloud) --- ## 10. Operational Procedures ### Daily Operations **Access Credential**: 1. Open project HTML UI: `http://localhost:8888/.credential-vault/` 2. Enter master password (first access only, cached for 15 min) 3. Search/filter for credential 4. Click [Show] to reveal 5. Click [Copy] to copy to clipboard (auto-clears after 30s) **Generate 2FA Code**: 1. Navigate to credential with TOTP 2. View auto-generated code with countdown timer 3. Click [Copy] to copy code 4. Code refreshes every 30 seconds ### Weekly Operations **Credential Rotation** (as needed): ```bash # Rotate specific credential ./scripts/rotate-credential.sh \ --credential "JWT Secret" \ --project tractatus \ --generate # Auto-generate new secure value # Verify rotation ./scripts/populate-env.sh --project tractatus cd ~/projects/tractatus && npm test ``` ### Monthly Operations **Backup Verification**: ```bash # Test SSD restore ./scripts/test-restore.sh --source ssd # Test OVHCloud restore ./scripts/test-restore.sh --source ovhcloud # Both should succeed and produce identical vault.kdbx ``` **Security Audit**: ```bash # Check file permissions ./scripts/security-audit.sh # Review access logs cat ~/Documents/credentials/logs/access-log.txt | tail -100 # Check for unauthorized access attempts grep FAILED ~/Documents/credentials/logs/access-log.txt ``` ### Quarterly Operations **Comprehensive Rotation**: - Rotate all HIGH_RISK credentials (API keys, JWT secrets) - Update 2FA recovery codes - Test emergency recovery procedures - Review and update this specification --- ## 11. Emergency Procedures ### Scenario 1: Lost Master Password **Recovery Options**: 1. **If you have key file**: Master password + key file both required - Key file alone cannot decrypt - Must remember/reset master password 2. **If backup exists on SSD/OVHCloud**: - Restore from last known-good backup - May lose credentials added since backup 3. **If both lost**: - ⚠️ VAULT IS UNRECOVERABLE - this is by design (strong encryption) - Must manually recreate all credentials - Rotate ALL credentials (assume compromise) **Prevention**: - Write master password on paper, store in physical safe - Keep key file on separate USB drive (not in same location as SSD backup) - Test recovery annually ### Scenario 2: Corrupted Database **Symptoms**: - KeePassXC cannot open vault.kdbx - Checksum mismatch - File size incorrect **Recovery**: 1. DO NOT overwrite corrupted file 2. Restore from most recent backup (SSD or OVHCloud) 3. Compare checksums to verify integrity 4. Identify when corruption occurred (check access logs) 5. If recent backup corrupted, restore from older backup ### Scenario 3: Credential Compromise **If ANY credential is compromised**: 1. **Immediate**: Revoke/rotate compromised credential 2. **Within 1 hour**: Update credential in vault 3. **Within 4 hours**: Populate new credential to all projects using it 4. **Within 24 hours**: Audit access logs for suspicious activity 5. **Within 1 week**: Review security procedures, identify breach vector **Rotation Script** (emergency): ```bash # Emergency rotation of Anthropic API key ./scripts/rotate-credential.sh \ --credential "Anthropic API Key" \ --emergency \ --revoke-old # Calls Anthropic API to revoke old key ``` --- ## 12. Testing & Validation ### Unit Tests **Test 1: Database Access** ```bash # Can open database with master password? echo "master_password" | keepassxc-cli ls vault.kdbx / # Expected: List of folders (tractatus, family-history, etc.) ``` **Test 2: Credential Retrieval** ```bash # Can retrieve specific credential? echo "master_password" | keepassxc-cli show vault.kdbx /tractatus/Anthropic\ API\ Key # Expected: Display entry details ``` **Test 3: TOTP Generation** ```bash # Can generate 2FA code? echo "master_password" | keepassxc-cli totp vault.kdbx /shared/OVHCloud\ Account # Expected: 6-digit code (e.g., 123456) ``` ### Integration Tests **Test 4: .env Population** ```bash # Can populate .env file from vault? cd ~/projects/tractatus ./scripts/get-credentials.sh --populate-env # Expected: .env file created with correct credentials # Can start server with generated .env? npm start # Expected: Server starts without errors ``` **Test 5: Backup & Restore** ```bash # Create backup ./scripts/backup-vault.sh --destination ssd # Simulate disaster (rename original) mv ~/Documents/credentials/vault.kdbx ~/Documents/credentials/vault.kdbx.disaster # Restore from backup ./scripts/restore-vault.sh --source ssd # Verify checksums match sha256sum vault.kdbx vault.kdbx.disaster # Expected: Identical checksums ``` ### Security Tests **Test 6: File Permissions** ```bash # Vault should be 600 (user read/write only) ls -l ~/Documents/credentials/vault.kdbx # Expected: -rw------- (600) # .env files should be 600 ls -l ~/projects/*/env # Expected: All -rw------- (600) ``` **Test 7: Auto-lock** ```bash # Open vault, wait 15 minutes, attempt access # Expected: Prompts for password again ``` --- ## 13. Maintenance Schedule | Frequency | Task | Owner | Automation | |-----------|------|-------|------------| | **Daily** | Backup to SSD | System | Cron (02:00) | | **Daily** | Backup to OVHCloud | System | Cron (03:00) | | **Weekly** | Review access logs | Human | Manual | | **Weekly** | Verify backups exist | System | Cron (Sunday) | | **Monthly** | Test SSD restore | Human | Script | | **Monthly** | Test OVHCloud restore | Human | Script | | **Monthly** | Rotate high-risk credentials | Human | Manual | | **Quarterly** | Full security audit | Human | Checklist | | **Quarterly** | Review this specification | Human | Calendar | | **Annually** | Test emergency recovery | Human | Drill | --- ## 14. Success Criteria ### Phase 1 Success (Foundation) - ✅ KeePassXC database created and accessible - ✅ All existing credentials migrated from .env files - ✅ TOTP configured for services with 2FA - ✅ CLI access working (keepassxc-cli) ### Phase 2 Success (Automation) - ✅ populate-env.sh works for all 4 projects - ✅ Automated backups running (SSD + OVHCloud) - ✅ Restore tested from both backup sources - ✅ Audit logging functional ### Phase 3 Success (HTML UI) - ✅ HTML interface accessible for all projects - ✅ TOTP codes display with countdown - ✅ Copy-to-clipboard works - ✅ Auto-lock after 15 minutes ### Phase 4 Success (Integration) - ✅ All 4 projects start with vault-generated .env - ✅ Credential rotation tested end-to-end - ✅ Security audit passes (permissions, encryption) - ✅ Emergency recovery tested successfully --- ## 15. Future Enhancements ### Version 2.0 Features (Future) **Multi-User Support**: - Share specific credentials with team members - Role-based access (read-only vs full access) - Separate audit logs per user **Browser Extension**: - Auto-fill credentials in browser - Detect credential forms, offer vault integration - TOTP auto-copy on 2FA pages **Mobile Access**: - KeePassXC mobile app (iOS/Android) - Sync vault via Syncthing or Nextcloud - Secure mobile backup strategy **Advanced Rotation**: - Auto-rotate credentials via API (Stripe, Anthropic) - Scheduled rotation reminders - Automatic testing after rotation **Compliance**: - PCI DSS compliance for Stripe credentials - SOC 2 audit trail - FIPS 140-2 encryption modules --- ## 16. References **KeePassXC Documentation**: - Official docs: https://keepassxc.org/docs/ - CLI guide: https://keepassxc.org/docs/KeePassXC_UserGuide.html#_command_line_interface - TOTP guide: https://keepassxc.org/docs/KeePassXC_GettingStarted.html#_adding_totp_to_an_entry **Security Best Practices**: - OWASP Secrets Management: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html - NIST Password Guidelines: https://pages.nist.gov/800-63-3/sp800-63b.html **Backup Strategies**: - Borg Backup docs: https://borgbackup.readthedocs.io/ - 3-2-1 Backup Rule: 3 copies, 2 different media, 1 offsite --- **END OF SPECIFICATION** **Next Steps**: Proceed with Phase 1 implementation (create database, migrate credentials)