# 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