Repository navigation
Pairing and Sync
New-device pairing starts over HTTP. Pairing message exchange and synchronization use WebSocket. Public deployments use HTTPS/WSS. The following diagrams summarize the main steps; the interface reference defines the exact message fields.
sequenceDiagram
actor User as User
participant A as Creator device A
participant R as Relay
participant B as Joining device B
A->>R: POST /v1/pairing/create
R-->>A: Room ID, six-digit code, pairing token, expiry
A-->>User: Display code
User->>B: Share code through a separate authenticated channel
B->>R: POST /v1/pairing/join
R-->>B: Session, peer information, pairing token
A->>R: WebSocket hello / pairing authentication
B->>R: WebSocket hello / pairing authentication
Note over A,B: The relay forwards the messages below
A->>B: SPAKE2 message
B->>A: SPAKE2 message
A->>B: Transcript-bound key_confirm
B->>A: Transcript-bound key_confirm
A->>B: Encrypted device_bind
B->>A: Encrypted device_bind
R-->>A: pairing_complete / device token
R-->>B: pairing_complete / device token
Note over A,B: Persist keys and room state after successful validation
The code remains valid for 120 seconds, and a session accepts one joiner. The six-digit code is used as the SPAKE2 password. The transcript binds the protocol version, session ID, device IDs, and SPAKE2 messages, followed by role-specific HMAC confirmations. An incorrect code or confirmation does not reach the normal credential persistence step.
Device-binding nonce domains are separated by sender role. This prevents different binding messages from reusing a nonce under the same session wrapping key.
Durable key and room-state writes run through spawn_blocking so they do not stall Tokio networking tasks. Individual writes are atomic; the complete set of files is not a transaction. An already-started blocking operation can finish even after its awaiting future is cancelled.
flowchart LR
Read["OS clipboard / manual input"] --> Check["Validate type / size"]
Check --> Encrypt["Encrypt content and manifest"]
Encrypt --> Route["Relay: authentication / limits / forwarding"]
Route --> Verify["Peer: decryption / structure / size / hash checks"]
Verify --> Apply["Apply to clipboard / inbox"]
Apply --> Guard["Update signature and loop suppression state"]
Text travels in an encrypted text_envelope. Images and files use an encrypted manifest and binary chunks. Each transfer's key is derived from the room epoch key and transfer ID. Filenames, MIME types, hashes, and image dimensions remain inside the encrypted manifest; the relay sees routing headers such as room/device/transfer IDs, item kind, and timestamps.
The receiver checks chunk counts, indices, duplicates, total sizes, manifest consistency, and hashes. Received filenames are sanitized to safe basenames before files are written to the inbox. After applying a remote clipboard item, the engine updates its signature and loop suppression state to reduce repeated transmission of the same content between peers.
The daemon retries connections after session failures. Previously paired devices perform a Noise_KK_25519_AESGCM_SHA256 handshake using their long-term X25519 device keys. Payload encryption continues to use the current room epoch key, so a Noise reconnection does not provide forward secrecy for stored payloads.
The relay can keep one latest encrypted text item per recipient in memory for up to 60 seconds. Images and files are forwarded while the peer is online; the server does not assemble them into files or persist them to disk. The reconnect queue is not a long-term inbox.
| Item | Limit |
|---|---|
| Pairing | 120 seconds, at most 3 attempts, 1 joiner |
| Text | 256 KiB |
| Image | 16 MiB |
| Files | 64 MiB per file, at most 16 files, 128 MiB total |
| Plaintext chunk | 256 KiB |
| WebSocket frame | 384 KiB |
| Message TTL | 60 seconds by default, protocol maximum of 300 seconds |
The current sending implementation uses a 60-second TTL. room create --ttl does not extend the pairing code's 120-second lifetime. Manual push through daemon IPC currently records the item locally and should not be interpreted as a peer receipt. Automatic live sending uses the clipboard-watch path.
Sources: pairing coordinator, sync engine, protocol reference, limit constants, and current interface behavior.
Baseline: source 76c63f9 · 2026-11-16 · Wiki home · Source repository. The wiki is a separate Git repository and is not synchronized with product sources automatically.