3.0 KiB
clipsync
LAN clipboard sync between Android and Linux/Windows devices. A device is a participant in a sync mesh; paired devices exchange clipboard changes over an authenticated session.
Identity & Trust
Device ID A stable, install-time unique identifier for a device. Immutable for the life of the install and used as the echo/loop key for clipboard updates. Avoid: device name, peer id (transient)
Identity key A device's long-term key pair. The public half is exchanged at pairing and pinned in the trust record; it authenticates every session. Avoid: public key (ambiguous — could mean ephemeral)
Pairing The one-time process that establishes mutual trust between two devices: an authenticated key-exchange handshake plus verification of a short authentication string derived from the handshake. Produces a pinned trust record on both sides. Avoid: linking, connecting
SAS (Short Authentication String) A human-comparable code both devices derive from the handshake transcript. The user confirms both sides show the same string to defeat a man-in-the-middle. Avoid: PIN, pairing code, OTP
Trust record The persisted per-peer entry proving a completed pairing: peer device ID, pinned identity public key, paired-at time, SAS-verified flag, display name, last-seen time. Avoid: credential, token
Peer A device for which a trust record exists (i.e., already paired). Avoid: client, node, endpoint
Session A single authenticated channel between two paired peers over one TCP connection. Re-established on every (re)connect using the pinned identity keys.
Sync Propagation
Origin device The device that first produced a clipboard change. Immutable as the update is fanned out; used for echo prevention. Avoid: sender (ambiguous — forwarders also send)
Sequence A persistent, monotonic per-device counter tagging each clipboard update. Together with origin device ID it forms the loop-prevention key. Avoid: nonce, index
Fan-out The propagation rule: a device sends each local clipboard change to every currently-connected trusted peer.
Loop prevention Dropping a clipboard update when its origin device ID equals the local device ID, or when its (origin device ID, sequence) pair is not newer than the last-seen pair for that peer.
Ordering
The deterministic total order (timestamp_ms, origin device ID) used to decide
which clipboard update wins when changes conflict; bounded by a clock-skew
guard.
Protocol & Discovery
CLIP_UPDATE A message carrying one clipboard change: origin device ID, content, content type, content hash, sequence, timestamp. Text only in MVP; content type is extensible.
Discovery How unpaired devices find each other: one side announces over UDP and the other listens, with manual IP:port entry as a fallback when announcement is blocked.
Clipboard backend The component that reads and writes the operating-system clipboard on the desktop side; reaches the clipboard through the platform's sanctioned API rather than raw display-server access.