87 lines
3.0 KiB
Markdown
87 lines
3.0 KiB
Markdown
# 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.
|