# ADR-001: Credential Encryption Strategy

## Status
Accepted

## Context
The PRD requires that user credentials (username/password) be stored encrypted at rest in extension storage, with decryption only in memory during use. Chrome Extension Manifest V3 has specific constraints:
- Service workers are ephemeral and don't persist
- No access to native encryption APIs
- Must use Web Crypto API for cryptographic operations

## Decision
We will use a hybrid encryption approach:

1. **Encryption Key Derivation**:
   - Generate a random encryption key on first credential save
   - Store the encryption key in chrome.storage.local (protected by Chrome's OS-level encryption)
   - Use PBKDF2 with a per-installation salt for additional key strengthening

2. **Credential Encryption**:
   - Use AES-GCM for symmetric encryption (Web Crypto API standard)
   - Encrypt credentials before storing in chrome.storage.local
   - Store encrypted data + IV (initialization vector)

3. **Runtime Handling**:
   - Decrypt credentials only when needed (API calls)
   - Hold decrypted credentials in memory for session duration
   - Implement "lock" function to clear memory on user request

## Consequences

### Positive
- Meets PRD requirement for encrypted at-rest storage
- Uses browser-native Web Crypto API (well-tested, audited)
- Doesn't require external dependencies
- Chrome's storage.local provides additional OS-level encryption layer

### Negative
- Not hardware-backed encryption (acceptable for v1)
- Encryption key stored on same device (mitigated by Chrome's OS protection)
- If device is compromised, encryption can be broken (acceptable trade-off for convenience)

## Alternatives Considered

1. **Password-based encryption (user must enter master password)**: Rejected - too much friction for target users
2. **No encryption, rely only on Chrome's OS protection**: Rejected - doesn't meet PRD explicit requirement
3. **External key management service**: Rejected - violates "no backend" constraint

## References
- Web Crypto API: https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API
- Chrome Storage API: https://developer.chrome.com/docs/extensions/reference/storage/