# V-006 MCP OAuth Deserialization Vulnerability Fix

## Summary
Fixed the critical V-006 vulnerability (CVSS 8.8) in MCP OAuth handling that used insecure deserialization, potentially enabling remote code execution.

## Changes Made

### 1. Secure OAuth State Serialization (`tools/mcp_oauth.py`)
- **Replaced pickle with JSON**: OAuth state is now serialized using JSON instead of `pickle.loads()`, eliminating the RCE vector
- **Added HMAC-SHA256 signatures**: All state data is cryptographically signed to prevent tampering
- **Implemented secure deserialization**: `SecureOAuthState.deserialize()` validates structure, signature, and expiration
- **Added constant-time comparison**: Token validation uses `secrets.compare_digest()` to prevent timing attacks

### 2. Token Storage Security Enhancements
- **JSON Schema Validation**: Token data is validated against strict schemas before use
- **HMAC Signing**: Stored tokens are signed with HMAC-SHA256 to detect file tampering
- **Strict Type Checking**: All token fields are type-validated
- **File Permissions**: Token directory created with 0o700, files with 0o600

### 3. Security Features
- **Nonce-based replay protection**: Each state has a unique nonce tracked by the state manager
- **10-minute expiration**: States automatically expire after 600 seconds
- **CSRF protection**: State validation prevents cross-site request forgery
- **Environment-based keys**: Supports `HERMES_OAUTH_SECRET` and `HERMES_TOKEN_STORAGE_SECRET` env vars

### 4. Comprehensive Security Tests (`tests/test_oauth_state_security.py`)
54 security tests covering:
- Serialization/deserialization roundtrips
- Tampering detection (data and signature)
- Schema validation for tokens and client info
- Replay attack prevention
- CSRF attack prevention
- MITM attack detection
- Pickle payload rejection
- Performance tests

## Files Modified
- `tools/mcp_oauth.py` - Complete rewrite with secure state handling
- `tests/test_oauth_state_security.py` - New comprehensive security test suite

## Security Verification
```bash
# Run security tests
python tests/test_oauth_state_security.py

# All 54 tests pass:
# - TestSecureOAuthState: 20 tests
# - TestOAuthStateManager: 10 tests  
# - TestSchemaValidation: 8 tests
# - TestTokenStorageSecurity: 6 tests
# - TestNoPickleUsage: 2 tests
# - TestSecretKeyManagement: 3 tests
# - TestOAuthFlowIntegration: 3 tests
# - TestPerformance: 2 tests
```

## API Changes (Backwards Compatible)
- `SecureOAuthState` - New class for secure state handling
- `OAuthStateManager` - New class for state lifecycle management
- `HermesTokenStorage` - Enhanced with schema validation and signing
- `OAuthStateError` - New exception for security violations

## Deployment Notes
1. Existing token files will be invalidated (no signature) - users will need to re-authenticate
2. New secret key will be auto-generated in `~/.hermes/.secrets/`
3. Environment variables can override key locations:
   - `HERMES_OAUTH_SECRET` - For state signing
   - `HERMES_TOKEN_STORAGE_SECRET` - For token storage signing

## References
- Security Audit: V-006 Insecure Deserialization in MCP OAuth
- CWE-502: Deserialization of Untrusted Data
- CWE-20: Improper Input Validation