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 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 SDK, and tracks the document through its Binect lifecycle — storing only metadata, never the PDF itself. See 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 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 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, then 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

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]

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 (zero-retention, explicit intent, no backend); add Binect API coverage upstream in @binect/js; document any permission expansion before adding.