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