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)

docker compose up -d

The relay server starts on port 8080. Override with PORT=3000 docker compose up -d.

Docker (manual)

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

From source

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

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 for the full design and 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

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