# Chrome Extension Manifest V3 APIs Research

## Key APIs for BinectChrome

### 1. Downloads API
**Purpose**: Detect PDF downloads

**Key Methods**:
- `chrome.downloads.onChanged`: Listen for download state changes
- `chrome.downloads.search()`: Query downloads
- `chrome.downloads.download()`: Programmatically download (not needed for v1)

**Implementation Notes**:
- Listen for completed downloads with `.pdf` extension
- Filter by MIME type `application/pdf`
- Extract original URL for re-fetching

### 2. Storage API
**Purpose**: Store credentials, tracking data, configuration

**Key Methods**:
- `chrome.storage.local.set()`: Store data
- `chrome.storage.local.get()`: Retrieve data
- `chrome.storage.local.remove()`: Delete data
- `chrome.storage.local.clear()`: Clear all data

**Storage Limits**:
- `storage.local`: 10MB (sufficient for credentials + 500 tracking entries)
- Data persists until extension is uninstalled

**Security**:
- Data encrypted at OS level by Chrome
- Accessible only to the extension

### 3. Runtime API
**Purpose**: Extension lifecycle, messaging

**Key Methods**:
- `chrome.runtime.onInstalled`: Initialization on first install
- `chrome.runtime.sendMessage()`: Communication between components
- `chrome.runtime.onMessage`: Receive messages

### 4. Tabs API
**Purpose**: Detect PDF views in browser tabs

**Key Methods**:
- `chrome.tabs.onUpdated`: Detect navigation to PDFs
- `chrome.tabs.query()`: Find tabs with specific URLs

**Implementation Notes**:
- Check for `Content-Type: application/pdf` in tab navigation
- Does not work reliably with blob URLs

### 5. Web Request API
**Purpose**: Inspect HTTP headers for Content-Type detection

**Status**: Limited in Manifest V3
- `declarativeNetRequest` is the v3 replacement
- Cannot inspect response headers dynamically
- **Decision**: Skip advanced PDF detection in v1, rely on Downloads API

### 6. Alarms API
**Purpose**: Check credential expiry (60-day policy)

**Key Methods**:
- `chrome.alarms.create()`: Schedule periodic checks
- `chrome.alarms.onAlarm`: Handle alarm events

**Implementation Notes**:
- Create daily alarm to check last credential use
- Delete credentials if >60 days since last use

## Service Worker Lifecycle

**Key Constraints**:
- Service workers are ephemeral (shut down when idle)
- No persistent state in memory
- All state must be in chrome.storage
- Event-driven architecture required

**Implementation Strategy**:
- Store all state in chrome.storage.local
- Service worker wakes on events (download, alarm, message)
- Popup communicates via chrome.runtime.sendMessage()

## Permissions Required

Minimal set per PRD:
- `downloads`: PDF detection
- `storage`: Credential and tracking storage
- `alarms`: Credential expiry checks (implicit, no permission needed)
- Host permission: `https://api.binect.de/*` for Binect API

## Web Crypto API (for encryption)

**Purpose**: Encrypt credentials at rest

**Key Methods**:
- `crypto.subtle.generateKey()`: Generate AES key
- `crypto.subtle.encrypt()`: Encrypt data
- `crypto.subtle.decrypt()`: Decrypt data
- `crypto.subtle.deriveBits()`: PBKDF2 key derivation

**Algorithm**: AES-GCM (Galois/Counter Mode)
- Authenticated encryption
- Built-in integrity check
- Standard for web encryption

## Testing Considerations

- Use `chrome-mock` or similar for unit tests
- Service worker can be tested with `chrome.test` API
- Integration tests require loading extension in test Chrome instance

## References
- Chrome Extensions Documentation: https://developer.chrome.com/docs/extensions/
- Manifest V3 Migration: https://developer.chrome.com/docs/extensions/migrating/
- Web Crypto API: https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API