generated from coulomb/repo-seed
tegwick
b09290cb83
Implements all requirements from ProductRequirementsDocument.md: - PDF detection via Chrome Downloads API - Secure credential storage with AES-GCM encryption - Binect API integration for PDF uploads - Popup UI with Binect branding - Local transfer tracking (500 entry cap) - Help page with tracking view and CSV export - 60-day credential retention with auto-expiry - Accessibility compliance (WCAG 2.1 AA) Technical implementation: - Chrome Extension Manifest V3 - TypeScript with strict mode - Webpack build system - Jest test suite (22/22 passing) - ESLint configured (0 errors) Build output: 13 KB total (production minified) Test coverage: crypto, pdf-detector, tracker, binect-api Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
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/
|