keyvault-cli/README.md

Secure API key management CLI tool

# KeyVault CLI

🔐 **Enterprise-grade API key management from your terminal**

A powerful command-line interface for secure API key management with zero-trust encryption, team collaboration, and comprehensive security scanning.

## 🚀 Installation

```bash
npm install -g keyvault-cli
```

**System Requirements:**
- Node.js 16+ 
- npm 8+
- Supported OS: macOS, Linux, Windows

## ⚡ Quick Start

```bash
# 1. Register a new account
keyvault register

# 2. Login to your account  
keyvault login

# 3. Scan your codebase for exposed secrets
keyvault scan

# 4. Create your first team
keyvault team create "My Development Team"

# 5. Check current security status
keyvault check
```

## 📖 Command Reference

### 🔐 Authentication & Account Management

| Command | Description | Example |
|---------|-------------|---------|
| `register` | Create new account with email/password | `keyvault register` |
| `login` | Login to your account | `keyvault login` |
| `logout` | Logout and clear local session | `keyvault logout` |
| `whoami` | Show current user information | `keyvault whoami` |
| `forgot-password` | Request password reset email | `keyvault forgot-password` |
| `reset-password` | Reset password with token | `keyvault reset-password --token <token>` |

### 🔍 Security Scanning & Analysis

| Command | Description | Options |
|---------|-------------|---------|
| `scan` | Scan directory for exposed secrets | `-d <dir>` `-o <file>` `-f <format>` |
| `check` | Quick security check of current directory | |
| `init` | Initialize project configuration | |

**Scan Options:**
- `-d, --directory <path>` - Target directory (default: current)
- `-o, --output <file>` - Save results to file
- `-f, --format <type>` - Output format: `text`, `json`, `csv`

### 👥 Team Management

| Command | Description | Example |
|---------|-------------|---------|
| `team create <name>` | Create a new team | `keyvault team create "Frontend Team"` |
| `team list` | List all your teams | `keyvault team list` |
| `team switch <name>` | Switch to team context | `keyvault team switch "Backend Team"` |
| `team current` | Show current team context | `keyvault team current` |

## 🏗️ Global Configuration System

KeyVault CLI uses a **global configuration** approach for storing authentication tokens and encryption keys in `~/.keyvault/config.json`:

```json
{
  "apiUrl": "https://1pass.vercel.app",
  "token": "jwt-auth-token",
  "email": "user@example.com",
  "activeTeamId": "team-uuid",
  "personalKeys": {
    "address": "0x...",
    "publicKey": "encryption-public-key",
    "privateKey": "encryption-private-key",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "teamKeys": {
    "team-name": {
      "address": "0x...",
      "publicKey": "team-encryption-public-key", 
      "privateKey": "team-encryption-private-key",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  }
}
```

**Note**: This config file stores **encryption keys** and authentication tokens, not your actual API keys. Your API keys are stored encrypted on the KeyVault servers and decrypted locally using these encryption keys.

### 🔄 Migration from v1.0.x

If you're upgrading from CLI v1.0.x, your existing `.keyvault-keys.json` files will be automatically migrated to the global configuration on first run.

## 💼 Advanced Usage Examples

### 🔍 Comprehensive Security Scanning

```bash
# Scan entire project with detailed output
keyvault scan -d ./my-project -f json -o security-audit.json

# Quick check current directory
keyvault check

# Scan multiple formats
keyvault scan -f csv -o secrets-report.csv
keyvault scan -f text -o human-readable.txt
```

### 👥 Team Collaboration Workflow

```bash
# Set up team environment
keyvault team create "Production Environment"
keyvault team switch "Production Environment"

# All subsequent operations use team context
keyvault scan -d ./production-app

# Switch back to personal context
keyvault team switch personal
```

### 🔐 Security Best Practices

```bash
# Regular security audits
keyvault scan -d . -f json -o "audit-$(date +%Y%m%d).json"

# Check before commits
git add . && keyvault check && git commit -m "feature: add new endpoint"

# Team-specific scans
keyvault team switch "Security Team"
keyvault scan -d ./critical-services -o security-report.txt
```

## 🔧 Integration Examples

### 🔄 CI/CD Pipeline Integration

```yaml
# GitHub Actions example
- name: Security Scan
  run: |
    npm install -g keyvault-cli
    echo "$KEYVAULT_TOKEN" | keyvault login --token
    keyvault scan -f json -o security-scan.json
    # Fail build if secrets found
    if [ -s security-scan.json ]; then exit 1; fi
```

### 🐳 Docker Integration

```dockerfile
# Multi-stage build with security scanning
FROM node:18-alpine AS security-scan
RUN npm install -g keyvault-cli
COPY . .
RUN keyvault check || exit 1

FROM node:18-alpine AS production
COPY --from=security-scan /app .
# ... rest of your build
```

### 🔗 Shell Integration

```bash
# Add to your .bashrc/.zshrc
alias kscan='keyvault scan'
alias kcheck='keyvault check'
alias kteam='keyvault team'

# Pre-commit hook
echo "keyvault check" > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```

## 🛡️ Security Architecture

### 🔐 Encryption Details
- **Algorithm:** AES-256-GCM with client-side encryption
- **Key Derivation:** Deterministic key generation from user credentials
- **Encryption Keys:** User-specific and team-specific encryption keys
- **Zero Trust:** API keys are encrypted before being sent to server

### 🔒 Data Protection
- All API keys encrypted client-side before transmission to server
- Encryption keys stored locally in `~/.keyvault/config.json`
- Team encryption keys provide additional isolation
- Server stores only encrypted API keys, never plaintext

### 🎯 Threat Model Protection
- **Credential Leakage:** Detects exposed API keys, tokens, passwords
- **Team Isolation:** Team data encrypted separately
- **Local Security:** Config files have restricted permissions
- **Network Security:** TLS 1.3 for all communications

## 🎛️ Configuration Options

### Environment Variables

```bash
# Override default API endpoint
export KEYVAULT_API_URL="https://your-instance.com/api"

# Enable debug logging
export KEYVAULT_DEBUG=true

# Custom config directory
export KEYVAULT_CONFIG_DIR="/custom/path"
```

### Project-Specific Settings

Create `.keyvault.json` in your project root:

```json
{
  "scanExcludes": [
    "node_modules/**",
    "dist/**",
    "*.log"
  ],
  "teamContext": "Production Team",
  "autoScan": true
}
```

## 🚨 Troubleshooting

### Common Issues

**🔑 Authentication Problems**
```bash
# Clear corrupted auth data
keyvault logout
rm -rf ~/.keyvault
keyvault login
```

**📁 Config File Issues**
```bash
# Reset configuration
rm ~/.keyvault/config.json
keyvault login
```

**🔍 Scan Performance Issues**
```bash
# Exclude large directories
keyvault scan -d . --exclude "node_modules,dist,logs"
```

**👥 Team Access Problems**
```bash
# Verify team membership
keyvault team list
keyvault whoami

# Re-sync team data
keyvault team switch "Team Name"
```

### Debug Mode

```bash
# Enable verbose logging
KEYVAULT_DEBUG=true keyvault scan

# Check configuration
keyvault whoami --verbose
```

## 📊 Output Formats

### JSON Format
```json
{
  "timestamp": "2024-01-15T10:30:00Z",
  "scanPath": "/path/to/project",
  "findings": [
    {
      "file": "config/database.js",
      "line": 15,
      "type": "api_key",
      "severity": "high",
      "pattern": "sk_live_...",
      "context": "const stripeKey = 'sk_live_123...'"
    }
  ],
  "summary": {
    "filesScanned": 245,
    "secretsFound": 1,
    "highRisk": 1,
    "mediumRisk": 0,
    "lowRisk": 0
  }
}
```

### CSV Format
```csv
File,Line,Type,Severity,Pattern,Context
config/database.js,15,api_key,high,sk_live_...,const stripeKey = 'sk_live_123...'
```

## 🔗 Ecosystem Integration

### Related Tools
- **[KeyVault Web App](https://1pass.vercel.app)** - Web-based management interface
- **[KeyVault SDK](https://www.npmjs.com/package/keyvault-api-sdk)** - Programmatic API access
- **[KeyVault VS Code Extension](https://marketplace.visualstudio.com/items?itemName=keyvault.vscode)** - IDE integration

### API Compatibility
This CLI is fully compatible with:
- KeyVault Web Application
- KeyVault SDK v1.1.0+
- KeyVault REST API v1

## 📈 Performance & Limits

### Scanning Performance
- **Small Projects** (<1000 files): ~2-5 seconds
- **Medium Projects** (1000-10000 files): ~10-30 seconds  
- **Large Projects** (>10000 files): ~1-5 minutes

### Rate Limits
- Authentication: 10 requests/minute
- Team operations: 30 requests/minute
- Scanning: No limits (offline processing)

## 🔄 Changelog

### v1.0.13 (Latest)
- 📖 **Documentation Fixes:** Corrected config file structure examples
- 🔐 **Security Clarifications:** Better explanation of encryption vs API key storage
- 🏗️ **Config Structure:** Accurate representation of actual config file format
- ✅ **Technical Accuracy:** Fixed misleading examples in README

### v1.0.12
- ✨ **Global Configuration System:** Centralized config in `~/.keyvault/`
- 🔄 **Automatic Migration:** Seamless upgrade from project-specific configs
- 👥 **Enhanced Team Management:** Improved team switching and context
- 🔐 **Better Encryption:** Enhanced key storage and security
- 🚀 **Performance Improvements:** Faster scanning and authentication
- 📖 **Comprehensive Documentation:** Enterprise-grade README with examples

### v1.0.11
- 🔄 Migration system implementation
- 🔐 Security improvements

### v1.0.10
- 🔍 Multiple output formats (JSON, CSV, text)
- 👥 Team management commands
- 🔐 Enhanced security scanning

## 🆘 Support & Community

- **📖 Documentation:** [Complete Guide](https://github.com/sserkanyilmaz/1pass/tree/main/docs)
- **🐛 Issues:** [GitHub Issues](https://github.com/sserkanyilmaz/1pass/issues)
- **💬 Discussions:** [GitHub Discussions](https://github.com/sserkanyilmaz/1pass/discussions)
- **📧 Email:** support@keyvault.dev

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

**Built with ❤️ by the KeyVault Team**

*Secure by design, simple by choice.*