coulomb/binect-chrome
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

Add INTENT.md/SCOPE.md, reconcile PRD scope, rename content fingerprint

Browse Source 
- Add INTENT.md (purpose and inviolable principles) and SCOPE.md
  (current operational boundary), matching the binect-js house style.
- Reconcile the PRD with the shipped document-lifecycle scope: add
  ordering/server-sync requirements (4.3a), split the proxy queue vs.
  tracking-log caps (4.6.3), and update the solution summary/closing.
- Rename computeMD5 -> computeContentFingerprint to be honest: it is a
  fast sampled non-cryptographic fingerprint for dedup, not MD5.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2026-06-22 21:42:57 +02:00
parent a1597c23fa
commit 9a42001972
5 changed files with 287 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
INTENT.md Normal file
View File

@@ -0,0 +1,77 @@
# INTENT.md
> The purpose of this document is to capture **why BinectChrome exists and what it must remain**, independent of any specific line of code. Where the [README](README.md) explains *how to use* the extension and [CLAUDE.md](CLAUDE.md) explains *how the code is structured*, this file records the **intent** that all of those serve. The full requirements live in [`specs/ProductRequirementsDocument.md`](specs/ProductRequirementsDocument.md); the concrete delivered surface lives in [`SCOPE.md`](SCOPE.md). If a future change conflicts with what is written here, the change is suspect — not the intent.
## 1. Core Intent
> **Let a user send a PDF produced in *any* cloud application directly to Binect for physical mail — from the browser where they already work, with explicit intent, and without the extension ever holding their documents.**
BinectChrome is a thin, trustworthy bridge between the browser and the [Binect API](https://app.binect.de/index.jsp?id=api). It collapses the manual **download → re-upload** loop into a single deliberate click, and it does so without asking the source application to change anything.
## 2. What Problem This Solves
Users routinely generate PDFs — letters, invoices, notices — in cloud applications that have no connection to a postal-mail service. Today, sending one physically means: download it from application A, upload it to application B (Binect), repeat for every document. This is slow, error-prone, and discouraging at volume.
BinectChrome targets exactly that friction and nothing beyond it: it notices the PDF the user just produced and offers to send it onward for printing and delivery.
## 3. The Core User Journey
This is the path that must always work end-to-end. Everything else is secondary.
1. The user generates or downloads a PDF in some web application.
2. The extension **detects** it and surfaces it — a toolbar badge and a popup entry showing filename, size, source domain, and time.
3. The user opens the popup, reviews the document, and clicks **Send to Binect**.
4. The extension **re-acquires the PDF bytes** (re-fetching from the original URL using the user's session) and **uploads** them to Binect via the official API, showing unambiguous Uploading → Success / Failure states.
5. The transfer is **recorded locally** for transparency; the user can review history, follow the document through its Binect lifecycle, and report issues via feedback.
If this journey breaks, the product is broken.
## 4. Inviolable Principles
These are the boundary conditions that keep BinectChrome *BinectChrome*. They are constraints, not preferences.
| Principle | Meaning | Consequence |
|-----------|---------|-------------|
| **Explicit user intent** | Nothing is ever sent, ordered, or deleted without a deliberate user click. | No automatic or background dispatch, ever. Sending physical mail costs money and is irreversible. |
| **Zero document retention** | The extension never stores or inspects PDF content. | PDF bytes exist in memory only during an active transfer, then are gone. Only technical metadata is tracked. |
| **Local-only data** | Credentials and tracking history live in the browser and nowhere else. | Tracking data leaves the device only when the user explicitly sends a feedback email. No telemetry. |
| **No backend relay** | The extension talks directly to the Binect API. | There is no BinectChrome server, and no server-side state tied to an installation. |
| **Credentials at rest, encrypted and expiring** | Username/password are AES-GCM encrypted at rest, decrypted only in memory, auto-expire after 60 days of inactivity, and are manually wipeable. | "Use" resets the clock; abandonment erases the secret. |
| **Least privilege** | Request only the permissions the journey actually needs, and justify each. | A permission that doesn't serve §3 doesn't belong in the manifest — it is review-cost the user pays for. |
| **Clean removal** | Uninstalling leaves nothing behind. | All state is local, so removal is complete by construction. |
| **Delegate the API, don't reinvent it** | Binect integration goes through the [`@binect/js`](../binect-js) library. | API-shape changes belong upstream; this repo stays a thin wrapper. |
## 5. Explicitly Out of Scope
BinectChrome is deliberately **not**:
- A document store, viewer, editor, or content analyzer.
- A backend relay or any server-side component.
- An automation / RPA tool that drives third-party sites or sends without a click.
- A credential-federation or shared-identity layer.
- A cross-browser product in v1 — Chrome (Chromium-based, Manifest V3) only.
- A telemetry or analytics collector.
When a feature request can only be satisfied by crossing one of these lines, the correct answer is to decline and document why.
## 6. Success Looks Like
- A user sends a freshly generated PDF to physical mail **without leaving the browser or touching a second app**.
- A transfer's progress and outcome are always legible: Uploading, Success, or an actionable Failure.
- A user can see exactly what was sent, where it came from, and what it cost — entirely from local history.
- Credentials are protected at rest and disappear on their own when unused.
- The extension passes Chrome Web Store review on a minimal permission set.
- No privacy or security incident is ever traceable to the extension holding data it shouldn't.
## 7. How to Use This Document
- **Before adding a feature:** confirm it serves §1 and §3 and violates none of §4. If it requires the extension to retain documents, send without intent, or stand up a backend, it does not belong here.
- **When the Binect API evolves:** adapt through `@binect/js`; preserve the intent. Product intent (this file) stays stable even as API details change.
- **When in doubt:** any decision must be explainable as a direct consequence of the Core Intent in §1.
## 8. Related Documents
- [`SCOPE.md`](SCOPE.md) — the concrete, current operational boundary of what is delivered
- [`specs/ProductRequirementsDocument.md`](specs/ProductRequirementsDocument.md) — the full PRD this intent distills
- [`architecture/ADR-001-credential-encryption.md`](architecture/ADR-001-credential-encryption.md) — the credential-encryption decision
- [`CLAUDE.md`](CLAUDE.md) — architecture and operating instructions for contributors
- [`README.md`](README.md) — usage and developer setup