227 lines
6.1 KiB
Markdown
227 lines
6.1 KiB
Markdown
# API Key Management System
|
|
|
|
Secure, centralized API key management for the Trax project and my-ai-projects workspace.
|
|
|
|
## Quick Start
|
|
|
|
### 1. Initial Migration (One-Time Setup)
|
|
|
|
```bash
|
|
# Scan all projects and migrate keys to secure vault
|
|
cd apps/trax
|
|
python3 scripts/migrate_keys.py
|
|
|
|
# Or automatic mode (no prompts)
|
|
python3 scripts/migrate_keys.py --auto --conflict-resolution=newest
|
|
```
|
|
|
|
### 2. Daily Usage
|
|
|
|
```bash
|
|
# List all keys in vault
|
|
python3 scripts/key_vault.py list
|
|
|
|
# Get a specific key
|
|
python3 scripts/key_vault.py get ANTHROPIC_API_KEY
|
|
|
|
# Add a new key
|
|
python3 scripts/key_vault.py add MY_NEW_KEY --category=custom
|
|
|
|
# Export keys for Trax project
|
|
python3 scripts/key_vault.py export .env --project=trax
|
|
|
|
# Sync to all projects
|
|
python3 scripts/key_vault.py sync root trax youtube-summarizer
|
|
```
|
|
|
|
## Features
|
|
|
|
### 🔐 Secure Storage
|
|
- **Encrypted vault** using Fernet (symmetric encryption)
|
|
- **Password-protected** master key with PBKDF2 derivation
|
|
- **File permissions** automatically set to 0600 (owner-only)
|
|
|
|
### 🔍 Key Discovery
|
|
- **Automatic scanning** of all project directories
|
|
- **Conflict detection** when keys have different values
|
|
- **Missing key identification** for standard requirements
|
|
|
|
### 📦 Project Integration
|
|
- **Export filtering** - only export keys needed for each project
|
|
- **Batch sync** to multiple project .env files
|
|
- **Validation** ensures required keys are present
|
|
|
|
## Architecture
|
|
|
|
### Vault Structure
|
|
```
|
|
~/.my-ai-keys/ # Default vault location
|
|
├── vault.enc # Encrypted key storage
|
|
├── metadata.json # Key metadata (categories, timestamps)
|
|
└── .master # Master encryption key (protected)
|
|
```
|
|
|
|
### Key Categories
|
|
- **ai** - AI model API keys (Anthropic, OpenAI, DeepSeek, etc.)
|
|
- **services** - External services (YouTube, Slack, GitHub, etc.)
|
|
- **oauth** - OAuth credentials (Google Client ID/Secret)
|
|
- **database** - Database connection strings
|
|
- **custom** - Project-specific keys
|
|
|
|
## Command Reference
|
|
|
|
### Key Vault (`key_vault.py`)
|
|
|
|
```bash
|
|
# Add/Update Keys
|
|
python3 scripts/key_vault.py add KEY_NAME --value="secret" --category=ai
|
|
python3 scripts/key_vault.py add KEY_NAME # Prompts for value securely
|
|
|
|
# Retrieve Keys
|
|
python3 scripts/key_vault.py get KEY_NAME
|
|
python3 scripts/key_vault.py list
|
|
python3 scripts/key_vault.py list --category=ai
|
|
|
|
# Import/Export
|
|
python3 scripts/key_vault.py import /path/to/.env
|
|
python3 scripts/key_vault.py export output.env
|
|
python3 scripts/key_vault.py export .env --project=trax
|
|
|
|
# Project Management
|
|
python3 scripts/key_vault.py validate trax
|
|
python3 scripts/key_vault.py sync root trax youtube-summarizer
|
|
|
|
# Key Rotation
|
|
python3 scripts/key_vault.py rotate ANTHROPIC_API_KEY
|
|
```
|
|
|
|
### Migration Tool (`migrate_keys.py`)
|
|
|
|
```bash
|
|
# Full migration workflow
|
|
python3 scripts/migrate_keys.py
|
|
|
|
# Scan only (no migration)
|
|
python3 scripts/migrate_keys.py --scan-only
|
|
|
|
# Automatic migration
|
|
python3 scripts/migrate_keys.py --auto --conflict-resolution=newest
|
|
|
|
# Export migration report
|
|
python3 scripts/migrate_keys.py --export-report=migration_report.txt
|
|
```
|
|
|
|
## Standard Keys
|
|
|
|
### AI Models (Required for Trax v2+)
|
|
- `ANTHROPIC_API_KEY` - Claude models (Task Master, Trax v2)
|
|
- `DEEPSEEK_API_KEY` - Transcription enhancement (Trax v2)
|
|
- `PERPLEXITY_API_KEY` - Research features (Task Master)
|
|
|
|
### Services
|
|
- `YOUTUBE_API_KEY` - YouTube Data API (optional)
|
|
- `GITHUB_TOKEN` - GitHub integration
|
|
- `GITEA_TOKEN` - Gitea CI/CD
|
|
|
|
### Google OAuth (Optional)
|
|
- `GOOGLE_CLIENT_ID` - OAuth client
|
|
- `GOOGLE_CLIENT_SECRET` - OAuth secret
|
|
|
|
## Security Best Practices
|
|
|
|
### 1. Vault Protection
|
|
- Store vault in user home directory (`~/.my-ai-keys/`)
|
|
- Never commit vault files to git
|
|
- Use strong master password
|
|
- Regularly rotate sensitive keys
|
|
|
|
### 2. Environment Files
|
|
- Keep `.env` files in `.gitignore`
|
|
- Use `.env.example` for templates
|
|
- Set file permissions to 0600
|
|
- Don't log or print full key values
|
|
|
|
### 3. Key Rotation
|
|
```bash
|
|
# Rotate a compromised key
|
|
python3 scripts/key_vault.py rotate COMPROMISED_KEY
|
|
|
|
# Re-sync to all projects
|
|
python3 scripts/key_vault.py sync root trax youtube-summarizer
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Forgotten Master Password
|
|
The vault uses password-based encryption. If you forget the password:
|
|
1. Keys cannot be recovered
|
|
2. Create new vault: `rm -rf ~/.my-ai-keys`
|
|
3. Re-run migration: `python3 scripts/migrate_keys.py`
|
|
|
|
### Missing cryptography Package
|
|
```bash
|
|
# Install with pip
|
|
pip install cryptography
|
|
|
|
# Or with uv (in Trax)
|
|
uv pip install cryptography
|
|
```
|
|
|
|
### Conflict Resolution
|
|
When keys have different values across projects:
|
|
- **newest** - Use value from most recently modified file
|
|
- **ask** - Prompt for each conflict (default)
|
|
- **skip** - Don't migrate conflicting keys
|
|
|
|
### Validation Errors
|
|
```bash
|
|
# Check which keys are missing
|
|
python3 scripts/key_vault.py validate trax
|
|
|
|
# Add missing keys
|
|
python3 scripts/key_vault.py add MISSING_KEY
|
|
|
|
# Re-export to project
|
|
python3 scripts/key_vault.py export .env --project=trax
|
|
```
|
|
|
|
## Integration with Trax
|
|
|
|
### Automatic Inheritance
|
|
Trax automatically loads keys from:
|
|
1. Local `.env` file (highest priority)
|
|
2. Parent `../../.env` file (workspace root)
|
|
3. Vault export via `key_vault.py export`
|
|
|
|
### Config Access
|
|
```python
|
|
from src.config import config
|
|
|
|
# Direct access
|
|
api_key = config.ANTHROPIC_API_KEY
|
|
|
|
# Check available services
|
|
services = config.get_available_ai_services()
|
|
|
|
# Validate required keys
|
|
config.validate_required_keys(["ANTHROPIC_API_KEY", "DEEPSEEK_API_KEY"])
|
|
```
|
|
|
|
## Workspace-Wide Usage
|
|
|
|
The key vault can manage keys for all projects:
|
|
|
|
```bash
|
|
# Export to specific projects
|
|
python3 scripts/key_vault.py export ~/projects/my-ai-projects/.env --project=root
|
|
python3 scripts/key_vault.py export ~/projects/my-ai-projects/apps/youtube-summarizer/.env --project=youtube-summarizer
|
|
|
|
# Or use sync for batch operations
|
|
python3 scripts/key_vault.py sync root trax youtube-summarizer pdf-translator
|
|
```
|
|
|
|
## Related Documentation
|
|
|
|
- [Trax Configuration](../src/config.py) - Config class implementation
|
|
- [Parent Workspace](../../../CLAUDE.md) - Workspace-wide context
|
|
- [Development Guide](../AGENTS.md) - Development workflows |