b6fbf7a921
- Dockerfile with multi-stage build (Node 22 Alpine, sodium-native) - docker-compose.yml with health check for easy self-hosting - README with setup guide, API reference, and project overview - Architecture docs (data flow, component breakdown, protocol constants) - Security model docs (threat model, crypto primitives, self-hosting checklist) - GitHub Actions CI pipeline (test, typecheck, Docker smoke test, extension builds) - GitHub Actions release pipeline (GHCR push, extension zip artifacts) - CONTRIBUTING.md with dev setup and code style guidelines Co-Authored-By: Paperclip <noreply@paperclip.ing>
139 lines
4.6 KiB
Markdown
139 lines
4.6 KiB
Markdown
# CookieBridge
|
|
|
|
Cross-device cookie synchronization with end-to-end encryption. Login once, be logged in everywhere.
|
|
|
|
CookieBridge syncs browser cookies across devices through an encrypted relay server. The server stores only encrypted blobs — it cannot read your cookie data. Devices pair using a short code and derive a shared secret locally via X25519 key exchange.
|
|
|
|
## Features
|
|
|
|
- **End-to-end encryption** — XChaCha20-Poly1305 (AEAD). The relay server is zero-knowledge.
|
|
- **Multi-browser support** — Chrome, Firefox, Edge, and Safari extensions.
|
|
- **Real-time sync** — WebSocket transport with HTTP polling fallback.
|
|
- **Device pairing** — 6-digit code, 5-minute TTL, X25519 key exchange.
|
|
- **AI agent API** — Agents can retrieve encrypted cookies with granted access.
|
|
- **Conflict resolution** — Last-writer-wins with Lamport clocks.
|
|
- **Self-hostable** — Docker image or run directly with Node.js.
|
|
|
|
## Quick Start
|
|
|
|
### Docker (recommended)
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
The relay server starts on port 8080. Override with `PORT=3000 docker compose up -d`.
|
|
|
|
### Docker (manual)
|
|
|
|
```bash
|
|
docker build -t cookiebridge .
|
|
docker run -d -p 8080:8080 --name cookiebridge cookiebridge
|
|
```
|
|
|
|
### From source
|
|
|
|
```bash
|
|
npm install
|
|
npm start
|
|
```
|
|
|
|
Requires Node.js 22+. The server listens on `0.0.0.0:8080` by default.
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `PORT` | `8080` | Server listen port |
|
|
| `HOST` | `0.0.0.0` | Server bind address |
|
|
|
|
## Browser Extensions
|
|
|
|
Extensions live in `extension/` and support Chrome, Firefox, Edge, and Safari.
|
|
|
|
### Building
|
|
|
|
```bash
|
|
cd extension
|
|
npm install
|
|
|
|
# Build for a specific browser
|
|
node esbuild.config.mjs --browser=chrome
|
|
node esbuild.config.mjs --browser=firefox
|
|
node esbuild.config.mjs --browser=edge
|
|
node esbuild.config.mjs --browser=safari
|
|
```
|
|
|
|
Output goes to `extension/build/{browser}/`. Load the unpacked extension from there.
|
|
|
|
### Installing
|
|
|
|
- **Chrome**: `chrome://extensions` → Enable Developer Mode → Load unpacked → select `extension/build/chrome`
|
|
- **Firefox**: `about:debugging#/runtime/this-firefox` → Load Temporary Add-on → select `extension/build/firefox/manifest.json`
|
|
- **Edge**: `edge://extensions` → Enable Developer Mode → Load unpacked → select `extension/build/edge`
|
|
- **Safari**: Requires Xcode. Convert with `xcrun safari-web-extension-converter extension/build/safari`
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Browser Extension ──WebSocket/HTTP──▶ Relay Server (stores encrypted blobs)
|
|
│ ▲
|
|
├── Ed25519 signing │
|
|
├── X25519 key exchange │
|
|
└── XChaCha20-Poly1305 encryption │
|
|
│
|
|
AI Agent ──Bearer token──────────────────────┘
|
|
```
|
|
|
|
The relay server is a plain Node.js HTTP + WebSocket server with no framework dependencies. See [docs/architecture.md](docs/architecture.md) for the full design and [docs/security.md](docs/security.md) for the threat model.
|
|
|
|
## API Endpoints
|
|
|
|
| Method | Path | Description |
|
|
|--------|------|-------------|
|
|
| `POST` | `/api/devices/register` | Register a device, receive API token |
|
|
| `POST` | `/api/pair` | Start a pairing session |
|
|
| `POST` | `/api/pair/accept` | Accept pairing with code |
|
|
| `POST` | `/api/cookies` | Push encrypted cookies |
|
|
| `GET` | `/api/cookies` | Pull cookies for a device |
|
|
| `GET` | `/api/cookies/updates` | Poll for updates since timestamp |
|
|
| `DELETE` | `/api/cookies` | Delete a cookie entry |
|
|
| `POST` | `/api/agent/tokens` | Create an agent access token |
|
|
| `POST` | `/api/agent/grant` | Grant agent access to a device |
|
|
| `GET` | `/api/agent/cookies` | Agent retrieves cookies |
|
|
| `GET` | `/health` | Health check |
|
|
| `WebSocket` | `/ws` | Real-time sync channel |
|
|
|
|
## Development
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev # Start with file watching
|
|
npm test # Run test suite
|
|
npm run typecheck # Type checking only
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
cli.ts # Server entry point
|
|
relay/
|
|
server.ts # HTTP + WebSocket server
|
|
connections.ts # WebSocket connection manager
|
|
auth.ts # Token & challenge-response auth
|
|
store.ts # In-memory encrypted cookie storage
|
|
tokens.ts # Device & agent registries
|
|
crypto/ # XChaCha20-Poly1305, Ed25519
|
|
pairing/ # Device pairing flow
|
|
sync/ # Sync engine, conflict resolution
|
|
protocol/
|
|
spec.ts # Protocol types & constants
|
|
extension/ # Multi-browser extension source
|
|
tests/ # Vitest test suite
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|