binect-chrome/README.md

# BinectChrome

A Chrome extension that enables users to send PDF documents from cloud applications directly to Binect for physical printing and postal delivery.

## Overview

BinectChrome detects PDF downloads in your browser and allows you to send them directly to Binect for physical mail delivery, eliminating the manual download-upload workflow.

## Features

- **PDF Detection**: Automatically detects PDF downloads using Chrome Downloads API
- **Secure Transfer**: Sends PDFs directly to Binect via encrypted connection
- **Credential Encryption**: User credentials stored encrypted with automatic 60-day expiry
- **Local Tracking**: Transfer history stored locally for transparency
- **Privacy-First**: No PDF storage, explicit user consent required
- **Accessible Design**: Follows WCAG 2.1 AA standards with Binect branding

## Development

### Prerequisites

- Node.js 18+ and npm
- Chrome browser for testing

### Setup

```bash
# Install dependencies
npm install

# Run development build with watch mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Type checking
npm run type-check
```

### Project Structure

```
binect-chrome/
├── src/
│   ├── background/         # Service worker (background script)
│   ├── popup/             # Extension popup UI
│   ├── tracking/          # Tracking/help page
│   └── utils/             # Shared utilities
│       ├── crypto.ts      # Encryption utilities
│       ├── storage.ts     # Storage management
│       ├── pdf-detector.ts # PDF detection
│       └── binect-api.ts  # Binect API client
├── public/
│   ├── manifest.json      # Extension manifest
│   ├── icons/             # Extension icons
│   └── _locales/          # Localization
├── tests/                 # Jest tests
├── architecture/          # ADRs (Architecture Decision Records)
├── research/              # Research documentation
└── specs/                 # API specifications
```

### Loading Extension in Chrome

1. Build the extension: `npm run build`
2. Open Chrome and navigate to `chrome://extensions/`
3. Enable "Developer mode" (toggle in top right)
4. Click "Load unpacked"
5. Select the `dist` directory

### Architecture

See [CLAUDE.md](./CLAUDE.md) for detailed architecture documentation.

Key architectural decisions are documented as ADRs in the [architecture/](./architecture/) directory.

## Testing

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch
```

Tests cover:
- Credential encryption/decryption
- PDF detection
- Binect API integration
- Tracking system

## Privacy & Security

- **No PDF Storage**: PDFs are never stored by the extension
- **Encrypted Credentials**: User credentials encrypted at rest using AES-GCM
- **60-Day Expiry**: Credentials automatically expire after 60 days of inactivity
- **Local-Only Tracking**: All tracking data stored locally, never transmitted
- **Explicit Consent**: All transfers require user click

## Requirements

Implements all requirements from [ProductRequirementsDocument.md](./specs/ProductRequirementsDocument.md):

- ✅ PDF detection via Chrome Downloads API
- ✅ Secure credential storage with encryption
- ✅ Binect API integration for PDF upload
- ✅ Popup UI with Binect branding
- ✅ Local transfer tracking (capped at 500 entries)
- ✅ Help page with tracking view
- ✅ CSV export and email feedback mechanism
- ✅ 60-day credential retention policy
- ✅ Manual credential wipe option
- ✅ Accessibility compliance (WCAG 2.1 AA)

## Browser Compatibility

- Chrome 88+ (Manifest V3 support)
- Chromium-based browsers may work but are not officially supported in v1

## Support

For issues, feature requests, or questions:

Email: [bernd.worsch@binect.de](mailto:bernd.worsch@binect.de)

## License

MIT License - see [LICENSE](./LICENSE) file for details

## Version

Current version: 1.0.0