tractatus/docs/CREDENTIAL_VAULT_SPECIFICATION.md

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: [REDACTED]
│   │   └── 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)

{
  "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:

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:

./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:

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

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!)

   # 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):

# 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:

# 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:

# 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):

# 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

# 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

# Can retrieve specific credential?
echo "master_password" | keepassxc-cli show vault.kdbx /tractatus/Anthropic\ API\ Key
# Expected: Display entry details

Test 3: TOTP Generation

# 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

# 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

# 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

# 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

# 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)