auth
This commit is contained in:
192
doc/auth.md
Normal file
192
doc/auth.md
Normal file
@@ -0,0 +1,192 @@
|
||||
# Authentication & Secrets Management Guide
|
||||
|
||||
## Overview
|
||||
|
||||
Your system now has a complete encrypted secrets management solution with WebSocket authentication. All secrets (like API keys) are stored in an encrypted file, protected by a master password that users enter when connecting.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Backend Components
|
||||
|
||||
1. **Secrets Store** (`backend/src/secrets_manager/`)
|
||||
- `crypto.py` - Argon2id password hashing + Fernet (AES-256) encryption
|
||||
- `store.py` - SecretsStore class for managing encrypted secrets
|
||||
- `cli.py` - Command-line interface for secrets management
|
||||
|
||||
2. **Encrypted Storage**
|
||||
- `backend/data/secrets.enc` - Encrypted secrets file
|
||||
- `backend/data/.master.key` - Salt + verification hash (never stores actual password)
|
||||
- Both files are created with 0600 permissions (owner-only access)
|
||||
|
||||
3. **WebSocket Authentication** (`backend/src/main.py`)
|
||||
- First message must be `auth` message
|
||||
- On first use: requires password + confirmation → initializes secrets store
|
||||
- Subsequent uses: requires password → unlocks secrets store
|
||||
- Failed auth closes connection immediately
|
||||
|
||||
### Frontend Components
|
||||
|
||||
1. **Login Screen** (`web/src/components/LoginScreen.vue`)
|
||||
- Shows before WebSocket connection
|
||||
- Detects first-time setup and shows confirmation field
|
||||
- Displays error messages for failed authentication
|
||||
|
||||
2. **WebSocket Manager** (`web/src/composables/useWebSocket.ts`)
|
||||
- Updated to send auth message on connect
|
||||
- Returns auth result (success/failure)
|
||||
- Prevents reconnection on auth failure
|
||||
|
||||
3. **App Integration** (`web/src/App.vue`)
|
||||
- Shows login screen until authenticated
|
||||
- Initializes state sync only after successful auth
|
||||
|
||||
## Security Features
|
||||
|
||||
✓ **Password-based encryption** - Argon2id (OWASP recommended)
|
||||
✓ **AES-256 encryption** - Industry-standard Fernet cipher
|
||||
✓ **Salted passwords** - Unique salt per installation
|
||||
✓ **No plaintext storage** - Master password never stored
|
||||
✓ **Restricted permissions** - Secrets files are 0600 (owner-only)
|
||||
✓ **Constant-time verification** - Prevents timing attacks
|
||||
✓ **Auto-lock on disconnect** - Secrets cleared from memory
|
||||
|
||||
## Usage
|
||||
|
||||
### First Time Setup
|
||||
|
||||
1. Start backend: `cd backend && python -m uvicorn src.main:app --reload --port 8080`
|
||||
2. Start frontend: `cd web && npm run dev`
|
||||
3. Open browser - you'll see "Welcome" screen
|
||||
4. Create a master password (with confirmation)
|
||||
5. System automatically migrates `ANTHROPIC_API_KEY` from `.env` to encrypted store
|
||||
|
||||
### Subsequent Logins
|
||||
|
||||
1. Start backend and frontend
|
||||
2. Enter your master password
|
||||
3. System unlocks and connects
|
||||
|
||||
### Managing Secrets (CLI)
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# List all secrets
|
||||
python -m secrets_manager.cli list
|
||||
|
||||
# Add a new secret
|
||||
python -m secrets_manager.cli set MY_SECRET "secret-value"
|
||||
|
||||
# Get a secret
|
||||
python -m secrets_manager.cli get ANTHROPIC_API_KEY
|
||||
|
||||
# Change master password
|
||||
python -m secrets_manager.cli change-password
|
||||
|
||||
# Backup secrets (encrypted)
|
||||
python -m secrets_manager.cli export backup.enc
|
||||
|
||||
# Migrate from .env file
|
||||
python -m secrets_manager.cli migrate-from-env
|
||||
```
|
||||
|
||||
### Managing Secrets (Python)
|
||||
|
||||
```python
|
||||
from secrets_manager import SecretsStore
|
||||
|
||||
# Initialize (first time)
|
||||
store = SecretsStore()
|
||||
store.initialize("my-password")
|
||||
|
||||
# Unlock (subsequent times)
|
||||
store = SecretsStore()
|
||||
store.unlock("my-password")
|
||||
|
||||
# Use secrets
|
||||
api_key = store.get("ANTHROPIC_API_KEY")
|
||||
store.set("NEW_SECRET", "value")
|
||||
store.delete("OLD_SECRET")
|
||||
|
||||
# Change password
|
||||
store.change_master_password("old-password", "new-password")
|
||||
```
|
||||
|
||||
## Protocol
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
```
|
||||
Client → Server: { type: "auth", password: "...", confirm_password: "..." }
|
||||
Server → Client: { type: "auth_response", success: true, message: "..." }
|
||||
|
||||
# If initialization needed:
|
||||
Client → Server: { type: "auth", password: "...", confirm_password: "..." }
|
||||
Server → Client: { type: "auth_response", success: false, needs_confirmation: true, ... }
|
||||
Client → Server: { type: "auth", password: "same", confirm_password: "same" }
|
||||
Server → Client: { type: "auth_response", success: true, message: "Initialized" }
|
||||
|
||||
# After successful auth, normal protocol continues:
|
||||
Client → Server: { type: "hello", seqs: {...} }
|
||||
Server → Client: { type: "snapshot", ... }
|
||||
```
|
||||
|
||||
### Error Codes
|
||||
|
||||
- `1008` - Authentication failed (invalid password)
|
||||
- `1011` - Internal error during authentication
|
||||
|
||||
## Migration from .env
|
||||
|
||||
The system automatically migrates `ANTHROPIC_API_KEY` from `.env` when you first initialize the secrets store through the web interface. You can also use the CLI:
|
||||
|
||||
```bash
|
||||
python -m secrets_manager.cli migrate-from-env
|
||||
# This will ask if you want to delete .env after migration
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Master Password Strength** - Use a strong password (8+ characters recommended)
|
||||
2. **Backup** - Export encrypted backups regularly: `python -m secrets_manager.cli export backup.enc`
|
||||
3. **Environment** - Can still fall back to `.env` if secrets store not unlocked (for development)
|
||||
4. **Transport** - Use HTTPS/WSS in production (currently using HTTP/WS for development)
|
||||
|
||||
## File Locations
|
||||
|
||||
```
|
||||
backend/
|
||||
├── data/
|
||||
│ ├── secrets.enc # Encrypted secrets (created on first auth)
|
||||
│ ├── .master.key # Salt + verification (created on first auth)
|
||||
│ └── checkpoints.db # Agent state (existing)
|
||||
└── src/
|
||||
└── secrets/ # Secrets management module
|
||||
├── __init__.py
|
||||
├── crypto.py # Cryptographic primitives
|
||||
├── store.py # SecretsStore class
|
||||
└── cli.py # Command-line interface
|
||||
|
||||
web/
|
||||
└── src/
|
||||
├── components/
|
||||
│ └── LoginScreen.vue # Authentication UI
|
||||
└── composables/
|
||||
└── useWebSocket.ts # Updated with auth support
|
||||
```
|
||||
|
||||
## Development Tips
|
||||
|
||||
1. **Testing First-Time Setup**: Delete `backend/data/.master.key` to simulate first-time setup
|
||||
2. **Reset Password**: Delete both `.master.key` and `secrets.enc`, then reconnect
|
||||
3. **Debug Auth**: Check backend logs for authentication attempts
|
||||
4. **Bypass Auth (Dev)**: Set `ANTHROPIC_API_KEY` in `.env` and don't initialize secrets store
|
||||
|
||||
## Next Steps
|
||||
|
||||
Consider adding:
|
||||
- [ ] Password reset mechanism (security questions or backup codes)
|
||||
- [ ] Session timeout / auto-lock
|
||||
- [ ] Multi-user support with different passwords
|
||||
- [ ] Secret versioning / audit log
|
||||
- [ ] Integration with external secret managers (Vault, AWS Secrets Manager)
|
||||
Reference in New Issue
Block a user