# 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