binect-chrome/SCOPE.md

SCOPE.md

This document defines what BinectChrome does and does not cover, concretely and as currently built. Where INTENT.md records why the project exists and the principles it must uphold, this file draws the operational boundary: which capabilities are implemented, which are explicitly excluded, and where the edges are. A feature request is answered first by checking it against this document. It reflects the state of the code at the 2026-06 lifecycle reconciliation.

1. Scope Statement

BinectChrome covers detecting a PDF in Chrome and sending it to Binect for physical mail, then tracking that document through its Binect lifecycle — entirely from the browser, with no backend and no stored document content. It covers the detection, send, order, status, and local-tracking surface needed for that journey, and a thin credential layer to authenticate. It covers nothing on the server side beyond calling the Binect API, and nothing about creating or editing the documents themselves.

2. In Scope (Implemented)

2.1 PDF Detection (src/utils/pdf-detector.ts)

Capability	Status	Notes
Detect completed PDF downloads via Chrome Downloads API	✅	By .pdf extension or application/pdf MIME.
Scan recent downloads on popup open	✅	getLastPDFDownload / popup checkRecentDownloads.
Detect PDF in the current tab	✅ (best effort)	checkCurrentTabForPDF in popup.
Re-fetch PDF bytes from original URL using the user session	✅	fetchPDFBytes, credentials: 'include'.
Blob-URL / complex-JS-viewer PDFs	❌ (accepted limitation)	Not reliably detectable or retrievable — by design.

2.2 Document Proxy Queue & Lifecycle (src/utils/pdf-queue.ts)

• Proxies: metadata-only records of detected/sent PDFs (DocumentProxy); never contain PDF content.
• Deduplication by filename + content hash (src/utils/hash.ts).
• Lifecycle states: pending → uploading → in_basket → ordering → in_production → sent, plus failed and canceled, mirroring the Binect server status.
• Live vs. archived views; archived proxies age out after ~30 days; queue capped at ~100 entries.
• Server sync / reconciliation: syncFromServer, attachServerDocument, clearServerFields — adopt server-discovered documents, update statuses, and detach proxies for documents deleted upstream.

2.3 Binect API Operations (src/utils/binect-api.ts, via @binect/js)

All Binect access is delegated to the @binect/js SDK; this module is a thin wrapper with extension-friendly types and error mapping.

Operation	Status
uploadPDF — base64 upload, places document in basket	✅
shipDocument — place the print/delivery order	✅
getDocumentStatus — per-document status refresh	✅
listServerDocuments — list documents Binect holds (for sync)	✅
deleteDocument — remove a document server-side	✅
testConnection — credential validation	✅
Structured errors (BinectAPIError, auth/size/4xx mapping)	✅

2.4 Authentication & Credentials (src/utils/crypto.ts, src/utils/storage.ts)

• Username + password (HTTP Basic, per the Binect API).
• AES-GCM (256-bit) encryption at rest via the Web Crypto API; key stored in chrome.storage.local; decrypted only in memory.
• 60-day inactivity expiry: lastUse timestamp refreshed on use; expired credentials auto-deleted on next load and by a daily chrome.alarms check.
• Manual wipe (logout) always available; corrupted ciphertext is self-deleting.

2.5 User Interface (src/popup/, src/tracking/)

• Popup: login view, document list grouped by lifecycle stage (pending / erroneous / basket / production / completed / archived), send / order / refresh / archive / restore / delete actions, password-visibility toggle, badge, first-run pin reminder, auto-refresh.
• Toolbar badge: actionable count, or a • idle indicator (Binect blue).
• Tracking / Help page (src/tracking/): summary counts, chronological transfer list, accessible via the popup "?" link.

2.6 Local Tracking & Feedback (src/tracking/tracker.ts)

• Append-only transfer log (TrackingEntry): timestamp, source, destination, filesize, result/error class; local-only, capped at ~500 events.
• getTrackingSummary for counts; exportAsCSV for export.
• Feedback opens an email draft to bernd.worsch@binect.de; tracking data exportable as CSV (body / clipboard).

2.7 Service Worker & Platform (src/background/service-worker.ts, public/manifest.json)

• Manifest V3 service worker; message router for all popup ↔ background calls.
• chrome.alarms for credential-expiry and queue-cleanup ticks (survives worker suspension).
• Permissions requested: downloads, storage, alarms, activeTab; host access to https://api.binect.de/* and <all_urls>.

2.8 Supporting Material

• Tests (tests/): Jest unit tests for crypto, pdf-detector, binect-api, tracker (@binect/js mocked).
• Build: TypeScript + Webpack (npm run build → dist/); ESLint; tsc type-check.
• Docs: CLAUDE.md, README.md, DEVELOPMENT.md, architecture/ADR-001-credential-encryption.md, detection/testing guides.

3. Out of Scope

Excluded by design. A request requiring any of these is a request for a different product (see INTENT.md §5).

Excluded	Reason
Storing, viewing, editing, or inspecting PDF content	Zero-retention principle; proxies hold metadata only.
Any server-side / backend component	The extension talks directly to Binect; no relay, no install-tied state.
Automatic or background sending, ordering, or deleting	Every dispatch action requires explicit user intent; mail costs money and is irreversible.
PDF generation, layout, or transformation	The user brings a finished PDF; document prep is the source app's job.
Reinterpreting or extending the Binect API	API behavior is delegated 1:1 to @binect/js; new coverage belongs upstream.
Cross-browser support (Firefox, Edge, …)	Chrome / Chromium MV3 only in v1.
Credential federation, SSO, token auth	Username + password only, until the API evolves.
Telemetry / analytics / remote logging	Tracking is local; data leaves only via explicit user feedback email.
Multi-profile destinations, rule-based automation, org policies	Listed as future considerations in the PRD §10, not built.

4. Boundary Cases & Known Edges

• Uploaded ≠ sent. Uploading places a document in the Binect basket (shippable). Physical dispatch is a separate, explicitly confirmed "order" step. Conflating the two would violate the explicit-intent principle.
• <all_urls> host permission. Required so the extension can re-fetch PDFs from arbitrary source domains using the user's session. It is broader than the "minimal permissions" the PRD/INTENT aspire to and is a known Chrome Web Store review cost — it should be justified in the store listing or narrowed, not silently expanded.
• Content hash is a fast non-cryptographic digest (computeContentFingerprint, src/utils/hash.ts) — a sampled rolling fingerprint used only for deduplication, never for security.
• Two capped stores, not one. Lifecycle proxies (~100, ~30-day archive aging) are distinct from the transfer log (~500 events). See PRD §4.6.3.
• @binect/js is a local file dependency (file:../binect-js). The sibling repo must be present to build; it is not yet published to a registry.
• Service-worker lifecycle. All state persists in chrome.storage.local; nothing relies on in-memory background state surviving suspension.

5. Scope Change Process

1. Confirm the change violates no principle in INTENT.md §4 — especially zero-retention, explicit intent, no backend.
2. If it adds Binect API coverage, add it upstream in @binect/js and surface it through the thin wrapper — do not reimplement API logic here.
3. If it expands permissions, document the justification (review impact) before adding.
4. Update this file and, where the boundary genuinely moves, INTENT.md and the PRD together.

6. Related Documents

• INTENT.md — why the project exists and its inviolable principles
• specs/ProductRequirementsDocument.md — full PRD (reconciled with the lifecycle scope)
• architecture/ADR-001-credential-encryption.md — credential encryption decision
• CLAUDE.md — architecture and contributor instructions
• README.md — usage and developer setup