rose_cat707/CookieBridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: implement M4 self-hosting, Docker & documentation
Some checks failed
CI / test (22) (push) Has been cancelled
Details
CI / docker (push) Has been cancelled
Details
CI / extension (push) Has been cancelled
Details

Browse Source 
- 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>
This commit is contained in:
徐枫
2026-03-17 18:34:53 +08:00
parent f39ff8c215
commit b6fbf7a921
9 changed files with 676 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
docs/architecture.md Normal file
View File

@@ -0,0 +1,139 @@
# CookieBridge Architecture
## Overview
CookieBridge is a cross-device cookie sync system built on a zero-knowledge relay architecture. The relay server transports and stores encrypted cookie blobs but cannot decrypt them. All cryptographic operations happen client-side.
## Components
### Relay Server (`src/relay/`)
A plain Node.js HTTP + WebSocket server. No frameworks — just `http`, `ws`, and `sodium-native`.
- **server.ts** — Routes HTTP requests and upgrades WebSocket connections. Single entry point for all API traffic.
- **connections.ts** — Manages active WebSocket connections. Maps device IDs to sockets for real-time push.
- **auth.ts** — Two auth methods:
- **Token auth**: Bearer tokens issued at device registration. Used for HTTP and WebSocket.
- **Challenge-response**: Server sends random bytes, client signs with Ed25519. Used for WebSocket upgrade.
- **store.ts** — In-memory encrypted cookie blob storage. Keyed by `(deviceId, domain, cookieName, path)`. Limit: 10,000 cookies per device.
- **tokens.ts** — Device and agent registries. Tracks device metadata, pairing relationships, and agent access grants.
### Cryptography (`src/crypto/`)
All crypto uses libsodium via `sodium-native` (server) or `libsodium-wrappers-sumo` (extension).
| Operation | Algorithm | Purpose |
|-----------|-----------|---------|
| Encryption | XChaCha20-Poly1305 | Cookie payload encryption (AEAD) |
| Signing | Ed25519 | Message authentication, device identity |
| Key exchange | X25519 | Deriving shared secrets between paired devices |
| Key derivation | BLAKE2b (generic hash) | Deriving encryption keys from ECDH output |
### Sync Engine (`src/sync/`)
- **envelope.ts** — Wire format for WebSocket messages. Each message is signed and encrypted.
- **conflict.ts** — Last-writer-wins (LWW) conflict resolution. Uses Lamport clock timestamps. Ties broken by lexicographic device ID comparison.
### Browser Extension (`extension/`)
Single TypeScript codebase compiled per-browser via esbuild.
- **service-worker.ts** — Extension lifecycle, device registration, pairing orchestration, sync triggers.
- **api-client.ts** — HTTP client for relay server REST API.
- **connection.ts** — WebSocket manager with auto-reconnect and exponential backoff.
- **crypto.ts** — Client-side encryption/decryption using libsodium-wrappers-sumo.
- **sync.ts** — Processes incoming cookie updates, applies them via `chrome.cookies` API.
- **compat.ts** — Cross-browser abstraction layer for Chrome, Firefox, Edge, Safari API differences.
## Data Flow
### Device Registration
```
Extension Relay Server
│ │
│ POST /api/devices/register │
│ { deviceId, name, platform, │
│ encPub } │
│──────────────────────────────────▶│
│ │
│ { token, deviceId, ... } │
│◀──────────────────────────────────│
```
### Pairing
```
Device A Relay Server Device B
│ │ │
│ POST /api/pair │ │
│ { deviceId, x25519Pub,│ │
│ pairingCode } │ │
│──────────────────────▶│ │
│ │ │
│ │ POST /api/pair/accept │
│ │ { deviceId, x25519Pub,│
│ │ pairingCode } │
│ │◀──────────────────────│
│ │ │
│ { peerX25519PubKey } │ { peerX25519PubKey } │
│◀──────────────────────│──────────────────────▶│
│ │ │
│ derive shared secret │ derive shared secret │
│ (X25519 ECDH) │ (X25519 ECDH) │
```
### Cookie Sync (WebSocket)
```
Device A Relay Server Device B
│ │ │
│ cookie_sync envelope │ │
│ (signed + encrypted) │ │
│──────────────────────▶│ │
│ │ store encrypted blob │
│ │ │
│ │ forward envelope │
│ │──────────────────────▶│
│ │ │
│ │ decrypt│
│ │ apply │
│ ack │ │
│◀──────────────────────│◀──────────────────────│
```
### Cookie Sync (HTTP Polling)
```
Device Relay Server
│ │
│ POST /api/cookies │
│ { encrypted blob } │
│───────────────────────────────▶│
│ │
│ GET /api/cookies/updates │
│ ?since=<timestamp> │
│───────────────────────────────▶│
│ │
│ [ encrypted blobs ] │
│◀───────────────────────────────│
```
## Storage
All storage is **in-memory**. The relay server does not persist data to disk. Restarting the server clears all registrations, pairings, and stored cookies. Devices re-register and re-sync automatically on reconnection.
This is intentional for the current version — the server is a transient relay, not a database. Persistent storage may be added in a future milestone.
## Protocol Constants
| Constant | Value | Purpose |
|----------|-------|---------|
| `PROTOCOL_VERSION` | `2.0.0` | Wire protocol version |
| `MAX_STORED_COOKIES_PER_DEVICE` | 10,000 | Per-device cookie limit |
| `PAIRING_CODE_LENGTH` | 6 digits | Pairing code size |
| `PAIRING_TTL_MS` | 5 minutes | Pairing session expiry |
| `NONCE_BYTES` | 24 | XChaCha20 nonce size |
| `PING_INTERVAL_MS` | 30 seconds | WebSocket keepalive |
| `PONG_TIMEOUT_MS` | 10 seconds | Pong deadline |
| `POLL_INTERVAL_MS` | 5 seconds | HTTP polling default |

115
docs/security.md Normal file
View File

@@ -0,0 +1,115 @@
# CookieBridge Security Model
## Design Principles
1. **Zero-knowledge relay** — The server stores and forwards encrypted blobs. It never possesses decryption keys and cannot read cookie data.
2. **Client-side crypto only** — All encryption, decryption, signing, and key exchange happen in the browser extension or agent client.
3. **Minimal trust surface** — The server is trusted only for availability and message delivery, not confidentiality.
## Cryptographic Primitives
| Primitive | Algorithm | Library |
|-----------|-----------|---------|
| Symmetric encryption | XChaCha20-Poly1305 (AEAD) | libsodium |
| Digital signatures | Ed25519 | libsodium |
| Key exchange | X25519 (ECDH) | libsodium |
| Key derivation | BLAKE2b (generic hash) | libsodium |
| Random nonces | 24-byte crypto random | libsodium |
All algorithms are from the libsodium suite (`sodium-native` on the server, `libsodium-wrappers-sumo` in the extension).
## Identity
Each device generates two keypairs at first launch:
- **Ed25519** — Signing keypair. The public key (hex) serves as the `deviceId`. Used to sign all WebSocket messages and authenticate via challenge-response.
- **X25519** — Encryption keypair. Used in ECDH key exchange during pairing to derive a shared secret.
Keys are stored in `chrome.storage.local` (extension) and never leave the device except for public key exchange during registration and pairing.
## Authentication
### Token Auth (HTTP)
On device registration, the server issues a random Bearer token. This token authenticates all subsequent HTTP requests. Tokens are stored server-side in memory and associated with the device ID.
### Challenge-Response (WebSocket)
1. Server sends a random challenge (32 bytes, hex).
2. Client signs the challenge with its Ed25519 private key.
3. Server verifies the signature against the registered Ed25519 public key.
This proves the client possesses the private key corresponding to the registered device ID.
## Pairing Security
1. Device A creates a pairing session and generates a 6-digit code.
2. The code must be communicated out-of-band (e.g., user reads it from one device and types it on another).
3. Device B submits the code along with its X25519 public key.
4. The server brokers the exchange — both devices receive each other's X25519 public key.
5. Each device derives the shared secret locally via X25519 ECDH + BLAKE2b key derivation.
**Mitigations:**
- Pairing sessions expire after 5 minutes (`PAIRING_TTL_MS`).
- Codes are 6 digits (1M combinations). Rate limiting should be applied in production.
- The server sees the X25519 public keys but not the derived shared secret.
## Encryption
Cookie data is encrypted with XChaCha20-Poly1305 before leaving the extension:
1. A fresh 24-byte random nonce is generated per message.
2. The cookie payload is encrypted with the shared secret derived from pairing.
3. The nonce and ciphertext are sent to the server.
4. The server stores the encrypted blob without the ability to decrypt it.
**AEAD properties:**
- Confidentiality: only holders of the shared secret can decrypt.
- Integrity: any tampering with the ciphertext is detected.
- Nonce uniqueness: random 24-byte nonces provide negligible collision probability.
## Message Signing
Every WebSocket message is signed with the sender's Ed25519 private key. The recipient verifies the signature against the sender's registered public key before processing. This prevents message forgery even if the server is compromised.
## Threat Model
### What the server knows
- Device IDs (Ed25519 public keys), device names, platform strings.
- Pairing relationships (which devices are paired).
- Cookie metadata: domain, cookie name, path (stored in plaintext for query routing).
- Encrypted cookie values (ciphertext — cannot decrypt).
- Timing: when cookies are synced, update frequency.
### What the server does NOT know
- Cookie values (encrypted end-to-end).
- Shared secrets (derived client-side via ECDH).
- Private keys (never transmitted).
### Threats and Mitigations
| Threat | Mitigation |
|--------|-----------|
| Server compromise | Zero-knowledge design. Attacker gets encrypted blobs and metadata, but not cookie values. |
| Man-in-the-middle on pairing | Pairing code is out-of-band. ECDH prevents passive eavesdroppers. Active MITM requires server collusion — mitigated by self-hosting. |
| Replay attacks | Each message has a unique nonce. Lamport clocks provide causal ordering. |
| Message forgery | Ed25519 signatures on all WebSocket messages. |
| Cookie metadata leakage | Domain and cookie names are plaintext on the server. Self-hosting eliminates third-party access to this metadata. |
| Brute-force pairing code | 6-digit code with 5-minute TTL. Apply rate limiting in production (not yet implemented). |
### Current Limitations
- **In-memory storage** — Server restart clears all data. No persistence layer.
- **No rate limiting** — Pairing endpoint and registration are not rate-limited. Deploy behind a reverse proxy with rate limiting for production use.
- **Plaintext metadata** — Domain names, cookie names, and paths are stored unencrypted for query routing. A future version may support encrypted metadata queries.
- **No TLS termination** — The relay server is plain HTTP. Run behind a TLS-terminating reverse proxy (nginx, Caddy, Cloudflare Tunnel) for production.
## Self-Hosting Security Checklist
1. **TLS** — Place the relay behind a reverse proxy with TLS (e.g., Caddy with automatic HTTPS).
2. **Rate limiting** — Configure rate limiting on `/api/pair`, `/api/devices/register`, and `/ws` endpoints.
3. **Firewall** — Restrict access to the relay port. Only allow traffic from your devices/networks.
4. **Updates** — Watch for CookieBridge releases and update promptly.
5. **Monitoring** — Use the `/health` endpoint for uptime monitoring.