52 lines
2.1 KiB
Markdown
52 lines
2.1 KiB
Markdown
|
# 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/
|