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)

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)

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

From source

# 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:

# 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

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 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

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:

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

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

Development

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