binect-chrome/SCOPE.md

# SCOPE

> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not. It draws the **operational
> boundary** of what BinectChrome does and does not cover, as currently built;
> [`INTENT.md`](INTENT.md) records *why* the project exists and the principles
> it must uphold. A feature request is answered first by checking it here.
> Reflects the state of the code at the 2026-06 lifecycle reconciliation.

---

## One-liner

A Chrome (MV3) extension that detects a PDF in the browser, sends it to Binect for physical mail, and tracks that document through its Binect lifecycle — backend-free and with zero stored document content.

---

## Core Idea

Sending a cloud-app PDF as physical mail normally means download → re-upload into Binect. BinectChrome collapses that into one click from the browser: it detects the PDF, re-fetches the bytes using the user's own session, uploads via the [`@binect/js`](../binect-js) SDK, and tracks the document through its Binect lifecycle — storing only metadata, never the PDF itself. See [`INTENT.md`](INTENT.md) for the full intent and inviolable principles.

---

## In Scope

- **PDF detection (`src/utils/pdf-detector.ts`)** — completed PDF downloads via the Chrome Downloads API (`.pdf`/`application/pdf`), recent-download scan on popup open, best-effort current-tab detection, and re-fetch of PDF bytes from the original URL with `credentials: 'include'`.
- **Document proxy queue & lifecycle (`src/utils/pdf-queue.ts`)** — metadata-only `DocumentProxy` records (never PDF content), dedup by filename + content hash, lifecycle `pending → uploading → in_basket → ordering → in_production → sent` (+ `failed`/`canceled`), live vs. archived views, and server sync/reconciliation.
- **Binect API operations (`src/utils/binect-api.ts`, via `@binect/js`)** — `uploadPDF`, `shipDocument`, `getDocumentStatus`, `listServerDocuments`, `deleteDocument`, `testConnection`, with structured error mapping. All Binect access delegated 1:1 to the SDK.
- **Authentication & credentials (`src/utils/crypto.ts`, `storage.ts`)** — username + password (HTTP Basic), AES-GCM (256-bit) encryption at rest via Web Crypto, 60-day inactivity expiry, manual wipe, self-deleting corrupted ciphertext.
- **UI (`src/popup/`, `src/tracking/`)** — login + lifecycle-grouped document list with send/order/refresh/archive/restore/delete actions, toolbar badge, and a tracking/help page.
- **Local tracking (`src/tracking/tracker.ts`)** — append-only, local-only transfer log (~500 cap), summary counts, CSV export, email-draft feedback.
- **Service worker & platform** — MV3 service worker message router, `chrome.alarms` for expiry/cleanup ticks, permissions `downloads`/`storage`/`alarms`/`activeTab` + host access.
- **Supporting material** — Jest tests (`@binect/js` mocked), TypeScript + Webpack build, ESLint, docs/ADRs.

---

## Out of Scope

- Storing, viewing, editing, or inspecting PDF content — zero-retention; proxies hold metadata only.
- Any server-side / backend component — the extension talks directly to Binect.
- Automatic or background sending, ordering, or deleting — every dispatch is explicit user intent.
- PDF generation, layout, or transformation — the user brings a finished PDF.
- Reinterpreting or extending the Binect API — delegated 1:1 to `@binect/js`; new coverage belongs upstream.
- Cross-browser support, credential federation/SSO/token auth, telemetry/analytics, and rule-based automation / multi-profile destinations (PRD future considerations, not built).

---

## Relevant When

- You want to send a PDF from any web app to Binect for physical mail without a manual download/upload round-trip.
- You need a browser-only, backend-free path to Binect with no document content leaving the user's control.
- You want to track documents through the Binect lifecycle (basket → order → production → sent) from the toolbar.

---

## Not Relevant When

- You need server-side queueing, persistence, or automated/scheduled sending.
- You need a non-Chrome browser (Firefox/Edge) — Chromium MV3 only in v1.
- You need to create, render, or edit the PDF itself — that is the source app's job.
- You are integrating Binect from Node or a non-browser context — use [`@binect/js`](../binect-js) directly.

---

## Current State

- Status: active
- Implementation: substantial — detection, lifecycle queue, API ops, credentials, UI, and tracking all built
- Stability: evolving — pre-Chrome-Web-Store; `<all_urls>` host permission is a known review cost
- Usage: internal / pre-release

---

## How It Fits

- Upstream dependencies: the Binect REST API (third-party service; see `tpsc.yaml`) and the [`@binect/js`](../binect-js) SDK (local `file:` dependency — sibling repo must be present to build).
- Downstream consumers: end users (the published Chrome extension).
- Often used with: cloud apps that produce PDFs (the detection source).

---

## Terminology

- Preferred terms: **proxy** (metadata-only record of a detected/sent PDF), **basket** (Binect shippable state), **order** (the explicit dispatch step), **transfer log** (local tracking).
- Also known as: "score" for the local tracking view.
- Potentially confusing terms: *uploaded ≠ sent* — upload places a document in the basket; physical dispatch is a separate confirmed order. `computeMD5` is a sampled non-cryptographic dedup hash, not true MD5.

---

## Related / Overlapping

- `binect-js` — the SDK this extension consumes for all Binect API access; API coverage belongs there, not here.
- `email-connect` — adjacent communication-domain delivery channel (email vs. physical mail); no code overlap.

---

## Getting Oriented

- Start with: [`INTENT.md`](INTENT.md), then [`README.md`](README.md) and `DEVELOPMENT.md`.
- Key files / directories: `src/utils/pdf-detector.ts`, `src/utils/pdf-queue.ts`, `src/utils/binect-api.ts`, `src/utils/crypto.ts`, `src/popup/`, `src/tracking/`, `src/background/service-worker.ts`, `public/manifest.json`.
- Entry points: the MV3 service worker (`src/background/service-worker.ts`) and the popup (`src/popup/`).

---

## Provided Capabilities

```capability
type: api
title: Browser PDF-to-physical-mail (BinectChrome extension)
description: Chrome MV3 extension that detects PDFs in the browser and sends them to Binect for physical mail, tracking each document through its lifecycle. Backend-free, zero document retention.
keywords: [chrome-extension, mv3, binect, physical-mail, pdf, browser, zero-retention]
```

```capability
type: security
title: Encrypted at-rest browser credential store
description: AES-GCM (256-bit) Web Crypto credential storage with 60-day inactivity expiry and manual wipe, for authenticating browser-side calls to a third-party API without a backend.
keywords: [aes-gcm, web-crypto, credentials, chrome-storage, basic-auth]
```

---

## Notes

- Uploaded ≠ sent: dispatch is a separate, explicitly confirmed order step.
- `<all_urls>` host permission is required to re-fetch PDFs from arbitrary source domains using the user's session; it is a known Chrome Web Store review cost and should be justified or narrowed, not silently expanded.
- Two capped stores: lifecycle proxies (~100, ~30-day archive aging) are distinct from the transfer log (~500 events).
- Scope-change process: confirm against [`INTENT.md` §4](INTENT.md) (zero-retention, explicit intent, no backend); add Binect API coverage upstream in `@binect/js`; document any permission expansion before adding.