binect-chrome/SCOPE.md

# SCOPE.md

> This document defines **what BinectChrome does and does not cover**, concretely and as currently built. Where [`INTENT.md`](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`](../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`](CLAUDE.md), [`README.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](INTENT.md)).

| 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](INTENT.md) — 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`](INTENT.md) and the [PRD](specs/ProductRequirementsDocument.md) together.

## 6. Related Documents

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