generated from coulomb/repo-seed
Release 0.1: Complete BinectChrome implementation
Implements all requirements from ProductRequirementsDocument.md: - PDF detection via Chrome Downloads API - Secure credential storage with AES-GCM encryption - Binect API integration for PDF uploads - Popup UI with Binect branding - Local transfer tracking (500 entry cap) - Help page with tracking view and CSV export - 60-day credential retention with auto-expiry - Accessibility compliance (WCAG 2.1 AA) Technical implementation: - Chrome Extension Manifest V3 - TypeScript with strict mode - Webpack build system - Jest test suite (22/22 passing) - ESLint configured (0 errors) Build output: 13 KB total (production minified) Test coverage: crypto, pdf-detector, tracker, binect-api Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
265
specs/BrandBook.md
Normal file
265
specs/BrandBook.md
Normal file
@@ -0,0 +1,265 @@
|
||||
BrandBook
|
||||
|
||||
*Binect Innovation Branding*
|
||||
|
||||
# Binect Futuristic Innovation BrandBook
|
||||
|
||||
**Binect Branding für Binect Innovation Projekt auf CoulombSocial**
|
||||
|
||||
---
|
||||
|
||||
## 1. Zweck & Anwendungsbereich
|
||||
|
||||
Dieses BrandBook definiert eine **futuristische, innovationsorientierte Markenvariation** von Binect für:
|
||||
|
||||
* Innovations- & Explorationsprojekte
|
||||
* Prototypen, Piloten, Labs, Spikes
|
||||
* Coulomb-Spaces, Projektkacheln, Konzepte, Architektur-Artefakte
|
||||
* Präsentationen, Poster, Onepager, Demo-Visuals
|
||||
|
||||
**Nicht ersetzt:**
|
||||
Das bestehende Binect Corporate Design für Produktmarketing, Vertrieb, Vertragsunterlagen oder reguläre Kundenkommunikation.
|
||||
|
||||
**Ziel:**
|
||||
|
||||
> Zukunft sichtbar machen, ohne Vertrauen, Klarheit und Professionalität aufzugeben.
|
||||
|
||||
---
|
||||
|
||||
## 2. Brand-Essenz
|
||||
|
||||
### Kernversprechen
|
||||
|
||||
**Exploration ohne Chaos.**
|
||||
|
||||
Binect Innovation steht für:
|
||||
|
||||
* kontrollierte Neugier
|
||||
* technologische Reife
|
||||
* klare Grenzen zwischen Experiment und Betrieb
|
||||
* Sicherheit als inhärente Eigenschaft, nicht als Zusatz
|
||||
|
||||
### Leitwerte
|
||||
|
||||
* **Clarity-first**
|
||||
* **Secure-by-design**
|
||||
* **Flow & Automation**
|
||||
* **Human-friendly Technology**
|
||||
|
||||
---
|
||||
|
||||
## 3. Visuelle Identität
|
||||
|
||||
### 3.1 Zentrale Metaphern
|
||||
|
||||
* **Flow & Pipelines** – Prozesse in Bewegung
|
||||
* **Orbit & Kern** – Entscheidungen, Systeme, APIs als stabiler Mittelpunkt
|
||||
* **Netzwerke & Knoten** – Integration statt Silos
|
||||
* **Rahmen & Grenzen** – Sicherheit, Policies, Governance
|
||||
|
||||
Die Bildsprache ist **abstrakt, ruhig und strukturiert**, niemals verspielt oder chaotisch.
|
||||
|
||||
---
|
||||
|
||||
### 3.2 Farbwelt
|
||||
|
||||
#### Core Palette (verbindlich)
|
||||
|
||||
* **Binect Blue (Core)** – Primärfarbe
|
||||
* **Binect Blue (Deep)** – Dark UI, Kontrast, Fokus
|
||||
* **Neutral Ink** – Text, Linien, Struktur
|
||||
* **Paper / Light UI** – Hintergründe, Karten
|
||||
|
||||
Diese Farben tragen die visuelle Identität und müssen dominieren.
|
||||
|
||||
#### Innovation Accents (sparsam)
|
||||
|
||||
* **Signal Green** – Markierung, Status, Erfolg
|
||||
* **Cyan / Mint** – Flow, Aktivität, Fokus
|
||||
* **Violet** – Innovation, Abgrenzung
|
||||
* **Red** – Warnung, Grenze, „Red Lines“
|
||||
|
||||
**Grundregel:**
|
||||
|
||||
> Akzentfarben unterstreichen – sie tragen keine alleinige Bedeutung.
|
||||
|
||||
---
|
||||
|
||||
### 3.3 Gradients & Effekte
|
||||
|
||||
* Gradients nur als **Hintergrund oder dekorative Ebene**
|
||||
* Leichte **Glow-Effekte** ausschließlich für Fokus oder Hervorhebung
|
||||
* Keine visuelle Unruhe, kein „Cyberpunk“
|
||||
|
||||
---
|
||||
|
||||
## 4. Typografie
|
||||
|
||||
### Prinzipien
|
||||
|
||||
* Hohe Lesbarkeit vor Stil
|
||||
* Moderne, sachliche Sans-Serif
|
||||
* Klare Hierarchien
|
||||
|
||||
### Einsatz
|
||||
|
||||
* **Headlines:** prägnant, sachlich, ruhig
|
||||
* **Fließtext:** neutral, erklärend, strukturiert
|
||||
* **Technische Inhalte:** Monospace erlaubt, zurückhaltend eingesetzt
|
||||
|
||||
### Sprachstil
|
||||
|
||||
* kurze, präzise Sätze
|
||||
* erklärend statt werblich
|
||||
* Fachbegriffe bewusst und konsistent
|
||||
|
||||
---
|
||||
|
||||
## 5. Layout & Komponenten
|
||||
|
||||
### 5.1 Grundlayout
|
||||
|
||||
* viel Weißraum
|
||||
* klare Sektionen
|
||||
* horizontale und vertikale Ausrichtung strikt eingehalten
|
||||
|
||||
### 5.2 Cards & Container
|
||||
|
||||
* abgerundete Ecken (modern, freundlich)
|
||||
* klare Trennung von Inhaltsebenen
|
||||
* ruhige Schatten, keine Tiefen-Effekthascherei
|
||||
|
||||
### 5.3 Interaktive Elemente
|
||||
|
||||
* Buttons, Links, Controls eindeutig identifizierbar
|
||||
* Interaktionen vorhersehbar, konsistent
|
||||
|
||||
---
|
||||
|
||||
## 6. Illustration & Bildstil
|
||||
|
||||
### Stil
|
||||
|
||||
* abstrakt, technisch, erklärend
|
||||
* Linien, Knoten, Orbits, Flows
|
||||
* ruhige Hintergründe
|
||||
|
||||
### Einsatz
|
||||
|
||||
* Ein zentrales Thema pro Visual
|
||||
* Text im Bild nur, wenn notwendig
|
||||
* Illustrationen unterstützen Verständnis, nicht Dekoration
|
||||
|
||||
---
|
||||
|
||||
## 7. Coulomb-spezifische Anwendung
|
||||
|
||||
### 7.1 Projektkacheln
|
||||
|
||||
Pflichtelemente:
|
||||
|
||||
* Projektname
|
||||
* Kurzbeschreibung
|
||||
* Status (Concept / Pilot / Beta / Production)
|
||||
* Kategorie / Fokus
|
||||
|
||||
Optional:
|
||||
|
||||
* Trust-Marker
|
||||
* Technology-Tag
|
||||
|
||||
### 7.2 Architektur & Konzepte
|
||||
|
||||
* Entscheidungen klar benannt
|
||||
* Abhängigkeiten sichtbar
|
||||
* Zustände und Übergänge explizit
|
||||
|
||||
---
|
||||
|
||||
## 8. Tonalität & Kommunikation
|
||||
|
||||
### Stimme
|
||||
|
||||
* ruhig
|
||||
* kompetent
|
||||
* offen für Exploration
|
||||
* transparent über Reifegrad
|
||||
|
||||
### Statuskommunikation
|
||||
|
||||
Begriffe wie *Pilot*, *Beta*, *Experiment* werden **explizit erklärt**, nicht impliziert.
|
||||
|
||||
---
|
||||
|
||||
# 9. Accessibility & Regulatorische Konformität
|
||||
|
||||
*(BFSG / WCAG 2.1 – AA)*
|
||||
|
||||
Dieser Abschnitt bündelt **alle verbindlichen Anforderungen**.
|
||||
Er dient als **Checkliste für Design, Review und Abnahme**.
|
||||
|
||||
---
|
||||
|
||||
## 9.1 Wahrnehmbarkeit
|
||||
|
||||
* Textkontrast:
|
||||
|
||||
* normaler Text ≥ **4.5 : 1**
|
||||
* großer Text ≥ **3.0 : 1**
|
||||
* UI-Elemente & Icons ≥ **3.0 : 1**
|
||||
* Keine Information ausschließlich über Farbe
|
||||
* Texte nicht direkt auf Gradients ohne geprüften Kontrast
|
||||
|
||||
---
|
||||
|
||||
## 9.2 Bedienbarkeit
|
||||
|
||||
* Alle interaktiven Elemente per Tastatur erreichbar
|
||||
* Sichtbarer Fokuszustand
|
||||
* Klick- und Touch-Flächen ≥ **44 × 44 px**
|
||||
* Keine Hover-only-Informationen
|
||||
|
||||
---
|
||||
|
||||
## 9.3 Verständlichkeit
|
||||
|
||||
* Klare Sprache
|
||||
* Konsistente Begriffe
|
||||
* Fachbegriffe erklärt
|
||||
* Status & Risiken explizit benannt
|
||||
|
||||
---
|
||||
|
||||
## 9.4 Robustheit
|
||||
|
||||
* Semantisch korrekte Struktur (HTML, Rollen, Labels)
|
||||
* Icons mit zugänglichem Namen
|
||||
* Bilder mit sinnvollen Alt-Texten
|
||||
|
||||
* dekorativ → leerer Alt-Text
|
||||
* informativ → beschreibend
|
||||
|
||||
---
|
||||
|
||||
## 9.5 Bilder & Diagramme
|
||||
|
||||
* Jedes Diagramm mit textlicher Kurzbeschreibung
|
||||
* Komplexe Grafiken zusätzlich erläutert
|
||||
* Keine Bedeutung nur durch Linienfarbe oder Form
|
||||
|
||||
---
|
||||
|
||||
## 9.6 Verbindliche Grundregel
|
||||
|
||||
> **Innovation ohne Zugänglichkeit gilt bei Binect nicht als fertig.**
|
||||
|
||||
Accessibility ist:
|
||||
|
||||
* Qualitätsmerkmal
|
||||
* Skalierungsfaktor
|
||||
* regulatorische Absicherung
|
||||
* Ausdruck technischer Reife
|
||||
|
||||
|
||||
|
||||
xxx
|
||||
311
specs/ProductRequirementsDocument.md
Normal file
311
specs/ProductRequirementsDocument.md
Normal file
@@ -0,0 +1,311 @@
|
||||
BinectChromePrd
|
||||
|
||||
*Product Requirements Document*
|
||||
|
||||
# **Product Requirements Document (PRD)**
|
||||
|
||||
## **Project: BinectChrome**
|
||||
|
||||
---
|
||||
|
||||
## 1. Product Overview
|
||||
|
||||
### 1.1 Purpose
|
||||
|
||||
**BinectChrome** is a Google Chrome extension that enables users to send PDF documents generated in arbitrary cloud applications directly to Binect for physical printing and postal delivery.
|
||||
|
||||
It eliminates the manual **download → upload** workflow by adding a lightweight, privacy-preserving integration layer in the browser — without requiring changes to the originating application (A).
|
||||
|
||||
---
|
||||
|
||||
### 1.2 Problem Statement
|
||||
|
||||
Users frequently generate PDF documents (letters, invoices, notices) in cloud applications that are **not integrated** with postal mail services.
|
||||
|
||||
Today, the workflow requires:
|
||||
|
||||
1. Downloading the PDF from application A
|
||||
2. Uploading the PDF to application B (Binect)
|
||||
3. Repeating this for every document
|
||||
|
||||
This causes friction, errors, and unnecessary time loss.
|
||||
|
||||
---
|
||||
|
||||
### 1.3 Solution Summary
|
||||
|
||||
BinectChrome:
|
||||
|
||||
* Detects PDF downloads (and supported in-browser PDF views)
|
||||
* Offers a **“Send PDF to Binect”** action
|
||||
* Securely transfers the PDF to Binect via its API
|
||||
* Requires explicit user intent
|
||||
* Stores no PDF content
|
||||
* Tracks transfers locally for transparency and support
|
||||
|
||||
---
|
||||
|
||||
## 2. Goals & Non-Goals
|
||||
|
||||
### 2.1 Goals
|
||||
|
||||
* Reduce friction when sending PDFs to physical mail
|
||||
* Require **no integration changes** in source systems (A)
|
||||
* Preserve user privacy and trust
|
||||
* Be simple, reliable, and auditable
|
||||
* Minimize permissions and attack surface
|
||||
|
||||
### 2.2 Non-Goals
|
||||
|
||||
* No automation or RPA of third-party websites
|
||||
* No shared identity or credential federation
|
||||
* No document content storage or analysis
|
||||
* No backend relay service
|
||||
* No multi-browser support in v1 (Chrome only)
|
||||
|
||||
---
|
||||
|
||||
## 3. Target Users
|
||||
|
||||
* Business users producing PDFs in cloud applications
|
||||
* Office workers sending recurring physical mail
|
||||
* Compliance-conscious users who require explicit control
|
||||
* Chrome-based desktop workflows
|
||||
|
||||
---
|
||||
|
||||
## 4. Functional Requirements
|
||||
|
||||
### 4.1 PDF Detection
|
||||
|
||||
#### 4.1.1 PDF Downloads (MUST)
|
||||
|
||||
* Detect completed PDF downloads using Chrome Downloads API
|
||||
* Identification via:
|
||||
|
||||
* `.pdf` filename extension
|
||||
* or response headers (`Content-Type: application/pdf`)
|
||||
|
||||
#### 4.1.2 PDF Viewed in Browser (SHOULD)
|
||||
|
||||
* Detect navigation to resources with `Content-Type: application/pdf`
|
||||
* Applies when PDFs are loaded as normal URLs
|
||||
|
||||
**Accepted limitation:**
|
||||
PDFs rendered via blob URLs or complex JavaScript viewers may not be detectable or retrievable.
|
||||
|
||||
---
|
||||
|
||||
### 4.2 User Interaction & Sending
|
||||
|
||||
#### 4.2.1 Toolbar & Popup (MUST)
|
||||
|
||||
* Chrome toolbar icon opens popup
|
||||
* Popup shows:
|
||||
|
||||
* Last detected PDF (filename, size, timestamp, source domain)
|
||||
* Primary action: **Send PDF to Binect**
|
||||
|
||||
#### 4.2.2 Explicit User Intent (MUST)
|
||||
|
||||
* PDFs are only sent after a deliberate user click
|
||||
* No automatic sending by default
|
||||
|
||||
---
|
||||
|
||||
### 4.3 PDF Transfer
|
||||
|
||||
#### 4.3.1 PDF Acquisition (MUST for downloads)
|
||||
|
||||
* Extension retrieves PDF bytes for transfer:
|
||||
|
||||
* Prefer re-fetching from original URL using user session
|
||||
* Fallback mechanisms may be implemented as needed
|
||||
|
||||
#### 4.3.2 Upload to Binect (MUST)
|
||||
|
||||
* Transfer PDF to Binect via official API
|
||||
* Show clear progress and result states:
|
||||
|
||||
* Uploading
|
||||
* Success
|
||||
* Failure (with actionable error message)
|
||||
|
||||
---
|
||||
|
||||
### 4.4 Authentication & Credential Handling
|
||||
|
||||
#### 4.4.1 Authentication Method (MUST)
|
||||
|
||||
* Username + password authentication to Binect API
|
||||
|
||||
#### 4.4.2 Secure Storage (MUST)
|
||||
|
||||
* Credentials stored encrypted at rest in extension storage
|
||||
* Decrypted credentials only held in memory during use
|
||||
|
||||
#### 4.4.3 Retention Policy (MUST)
|
||||
|
||||
* Credentials retained for **60 days since last successful use**
|
||||
* “Use” = successful authentication or successful send
|
||||
* After 60 days of inactivity:
|
||||
|
||||
* Credentials are automatically deleted
|
||||
* User must re-enter credentials
|
||||
|
||||
#### 4.4.4 Manual Controls (MUST)
|
||||
|
||||
* User can manually wipe stored credentials at any time
|
||||
* Optional “Lock now” to clear decrypted credentials from memory
|
||||
|
||||
---
|
||||
|
||||
### 4.5 Privacy & Data Handling
|
||||
|
||||
#### 4.5.1 PDF Content (MUST)
|
||||
|
||||
* Extension never stores PDF files
|
||||
* Extension never reports PDF content
|
||||
* PDFs are only transmitted to Binect upon explicit send
|
||||
|
||||
#### 4.5.2 Metadata Minimization (MUST)
|
||||
|
||||
* No content inspection
|
||||
* No filename persistence required
|
||||
* Only filesize and technical metadata are tracked
|
||||
|
||||
---
|
||||
|
||||
### 4.6 Local Tracking (“Score”)
|
||||
|
||||
#### 4.6.1 Tracking Scope (MUST)
|
||||
|
||||
Tracking data stored **locally only**:
|
||||
|
||||
* Timestamp
|
||||
* Source A identifier (URL or domain)
|
||||
* Destination B URL
|
||||
* PDF filesize
|
||||
* Result (success / failure + error class)
|
||||
|
||||
#### 4.6.2 Tracking Access (MUST)
|
||||
|
||||
* Tracking view accessible via **“?” Info/Help** link in popup
|
||||
* Shows:
|
||||
|
||||
* Summary counts
|
||||
* Chronological list of transfers
|
||||
|
||||
#### 4.6.3 Retention (SHOULD)
|
||||
|
||||
* Cap number of entries (e.g. last 500 events)
|
||||
* Prevent unbounded growth
|
||||
|
||||
---
|
||||
|
||||
### 4.7 Feature Requests & Feedback
|
||||
|
||||
#### 4.7.1 Feedback Mechanism (MUST)
|
||||
|
||||
* “Request features / report issue” link
|
||||
* Opens email draft to:
|
||||
**[bernd.worsch@binect.de](mailto:bernd.worsch@binect.de)**
|
||||
|
||||
#### 4.7.2 Tracking Export (MUST)
|
||||
|
||||
* Tracking data prepared as CSV
|
||||
* CSV data:
|
||||
|
||||
* Embedded in email body and/or
|
||||
* Copied to clipboard automatically
|
||||
* Optional “Download CSV” button
|
||||
|
||||
**Note:**
|
||||
Direct file attachments via `mailto:` are not reliably supported by browsers and are therefore not required.
|
||||
|
||||
---
|
||||
|
||||
## 5. Installation & Distribution
|
||||
|
||||
### 5.1 Distribution Channel (MUST)
|
||||
|
||||
* Automated publication via **Chrome Web Store**
|
||||
|
||||
### 5.2 Installation Requirements
|
||||
|
||||
* Chrome browser (desktop)
|
||||
* User installs extension from Chrome Web Store
|
||||
* User grants required permissions explicitly
|
||||
|
||||
### 5.3 Permissions (Principle of Least Privilege)
|
||||
|
||||
Expected permissions include:
|
||||
|
||||
* `downloads`
|
||||
* `storage`
|
||||
* `activeTab` (optional)
|
||||
* Host permission for Binect API endpoint
|
||||
|
||||
---
|
||||
|
||||
## 6. Deinstallation & Cleanup
|
||||
|
||||
### 6.1 User-Initiated Deinstallation (MUST)
|
||||
|
||||
* When extension is removed:
|
||||
|
||||
* All stored credentials are deleted
|
||||
* All local tracking data is deleted
|
||||
* No data remains outside the browser
|
||||
|
||||
### 6.2 No External State (MUST)
|
||||
|
||||
* No server-side state tied to installation
|
||||
* No orphaned accounts or tokens
|
||||
|
||||
---
|
||||
|
||||
## 7. Technical Constraints
|
||||
|
||||
* Chrome Extension Manifest V3
|
||||
* No background persistence beyond service worker lifecycle
|
||||
* No external backend services
|
||||
* No cross-browser guarantees in v1
|
||||
|
||||
---
|
||||
|
||||
## 8. Security Considerations
|
||||
|
||||
* Encrypted credential storage
|
||||
* No silent background transfers
|
||||
* Clear user confirmation before sending
|
||||
* No hidden data flows
|
||||
* Minimal permissions to pass Chrome Web Store review
|
||||
|
||||
---
|
||||
|
||||
## 9. Success Metrics
|
||||
|
||||
* Reduction in manual upload steps
|
||||
* Successful sends per active user
|
||||
* Low error rate
|
||||
* No privacy or security incidents
|
||||
* Positive user feedback via feature request channel
|
||||
|
||||
---
|
||||
|
||||
## 10. Future Considerations (Out of Scope for v1)
|
||||
|
||||
* Multi-profile destinations
|
||||
* Rule-based automation (opt-in)
|
||||
* Multi-browser support (Firefox, Edge)
|
||||
* Token-based authentication (if API evolves)
|
||||
* Organization-level deployment policies
|
||||
|
||||
---
|
||||
|
||||
**BinectChrome** is intentionally modest in scope:
|
||||
a focused, trustworthy bridge between modern cloud software and physical mail — implemented where the user already works: the browser.
|
||||
|
||||
|
||||
xxx
|
||||
74
specs/binect-api.md
Normal file
74
specs/binect-api.md
Normal file
@@ -0,0 +1,74 @@
|
||||
# Binect API Specification
|
||||
|
||||
## Overview
|
||||
This document specifies the Binect API endpoints used by BinectChrome extension.
|
||||
|
||||
## Base URL
|
||||
```
|
||||
https://api.binect.de
|
||||
```
|
||||
|
||||
## Authentication
|
||||
Username/password authentication using HTTP Basic Auth or JSON payload.
|
||||
|
||||
### Endpoint: Login
|
||||
```
|
||||
POST /auth/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"username": "string",
|
||||
"password": "string"
|
||||
}
|
||||
|
||||
Response 200 OK:
|
||||
{
|
||||
"token": "string",
|
||||
"expiresAt": "ISO8601 timestamp"
|
||||
}
|
||||
|
||||
Response 401 Unauthorized:
|
||||
{
|
||||
"error": "Invalid credentials"
|
||||
}
|
||||
```
|
||||
|
||||
## PDF Upload
|
||||
|
||||
### Endpoint: Upload PDF
|
||||
```
|
||||
POST /documents/upload
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: multipart/form-data
|
||||
|
||||
Form fields:
|
||||
- file: PDF file (binary)
|
||||
- filename: string (optional)
|
||||
|
||||
Response 200 OK:
|
||||
{
|
||||
"documentId": "string",
|
||||
"status": "received",
|
||||
"uploadedAt": "ISO8601 timestamp"
|
||||
}
|
||||
|
||||
Response 400 Bad Request:
|
||||
{
|
||||
"error": "Invalid file format"
|
||||
}
|
||||
|
||||
Response 401 Unauthorized:
|
||||
{
|
||||
"error": "Authentication required"
|
||||
}
|
||||
|
||||
Response 413 Payload Too Large:
|
||||
{
|
||||
"error": "File size exceeds limit"
|
||||
}
|
||||
```
|
||||
|
||||
## Notes
|
||||
- API may evolve - this is v1 specification
|
||||
- For actual implementation, verify with Binect API documentation
|
||||
- Rate limits may apply
|
||||
Reference in New Issue
Block a user