CookieBridge/README.md

# 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.
- **Admin panel** — Built-in Vue 3 web UI for server management.
- **AI agent API** — Agents can retrieve encrypted cookies with granted access.
- **Conflict resolution** — Last-writer-wins with Lamport clocks.
- **Database options** — In-memory (default), SQLite, or MySQL via setup wizard.
- **Self-hostable** — Docker image or run directly with Node.js.

## Quick Start

### Docker (recommended)

```bash
docker compose up -d
```

The server starts on port 8080 with the admin UI embedded. Override the port with `PORT=3000 docker compose up -d`.

Open `http://localhost:8080` to access the admin panel and run the setup wizard.

### Docker (manual)

```bash
docker build -t cookiebridge .
docker run -d -p 8080:8080 --name cookiebridge cookiebridge
```

### From source

```bash
# Install all dependencies
npm install
cd web && npm install && cd ..

# Build everything (backend + frontend)
npm run build:all

# Start the server (serves API + admin UI)
npm start
```

Requires Node.js 22+. The server listens on `0.0.0.0:8080` by default and serves the admin UI at the root URL.

### Development mode

Run the backend and frontend dev servers separately for hot-reload:

```bash
# Terminal 1: Backend (port 8080)
npm run dev

# Terminal 2: Frontend dev server (port 5173, proxies API to backend)
cd web && npm run dev
```

## 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                 ├── Admin UI (Vue 3 SPA)
     ├── X25519 key exchange             ├── SQLite / MySQL / In-memory
     └── XChaCha20-Poly1305 encryption   └── Setup wizard
                                         │
AI Agent ──Bearer token──────────────────┘
```

The relay server is a plain Node.js HTTP + WebSocket server with no framework dependencies. In production, the server embeds the pre-built admin UI and serves it as static files. 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 |

### Admin Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/admin/setup/init` | Run setup wizard (set password, choose DB) |
| `GET` | `/admin/setup/status` | Check if setup has been completed |
| `POST` | `/admin/login` | Login to admin panel |
| `GET` | `/admin/devices` | List registered devices |
| `GET` | `/admin/connections` | List active WebSocket connections |
| `GET` | `/admin/agents` | List registered agents |
| `GET` | `/admin/stats` | Server statistics |

## Deployment

### Build Pipeline

The Dockerfile uses a multi-stage build:

1. **web-builder** — Installs frontend dependencies and runs `vite build`
2. **builder** — Compiles the TypeScript backend
3. **production** — Copies compiled backend + built frontend into a minimal image

The frontend is served from the `/public` directory inside the container. No separate web server (nginx, etc.) is needed.

### Database Persistence

By default, CookieBridge starts with in-memory storage. On first access, the setup wizard lets you choose:

- **In-memory** — No persistence, data resets on restart
- **SQLite** — File-based, mount a volume for persistence
- **MySQL** — Remote database, provide connection details

For SQLite persistence with Docker:

```bash
docker run -d -p 8080:8080 -v cookiebridge-data:/app/data cookiebridge
```

Database configuration is stored in `data/db-config.json`.

## Development

```bash
npm install
npm run dev          # Start with file watching
npm test             # Run test suite
npm run typecheck    # Type checking only
npm run build:all    # Build backend + frontend
```

## Project Structure

```
src/
  cli.ts             # Server entry point
  relay/
    server.ts        # HTTP + WebSocket server + static file serving
    static.ts        # Static file serving with SPA fallback
    connections.ts   # WebSocket connection manager
    auth.ts          # Token & challenge-response auth
    admin/           # Admin panel API routes
    db/              # Database abstraction (memory, SQLite, MySQL)
  crypto/            # XChaCha20-Poly1305, Ed25519
  pairing/           # Device pairing flow
  sync/              # Sync engine, conflict resolution
  protocol/
    spec.ts          # Protocol types & constants
web/                 # Admin panel (Vue 3 + Vite)
extension/           # Multi-browser extension source
tests/               # Vitest test suite
docs/                # Architecture and security docs
```

## License

MIT