documentation

CONTEXT.md

@@ -0,0 +1,86 @@
+# 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.