binect-chrome/research/chrome-extension-apis.md

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