documentation

docs/adr/0001-noise-transport.md

@@ -0,0 +1,8 @@
+# Transport security uses Noise, not TLS
+
+We secure the session with the Noise protocol (an `XX` handshake) using each
+device's long-term identity key, rather than mutual TLS with per-device certs.
+Noise avoids a CA/cert machinery on a peer-to-peer LAN, maps cleanly onto the
+SAS pairing flow, and is light enough for the Odin daemon and Android
+(Conscrypt). The pinned trust record and the session key are the *same* key,
+simplifying the model.

docs/adr/0002-fanout-topology.md

@@ -0,0 +1,7 @@
+# Sync topology is fan-out to all trusted peers
+
+A clipboard change is sent to every currently-connected paired peer, not just
+one. The trust store already models a list of peers, and restricting to 1:1
+later would be a painful product reversal. Fan-out makes the system
+many-to-many by construction; correctness then rests entirely on loop
+prevention (see ADR-0003).

docs/adr/0003-loop-prevention-key.md

@@ -0,0 +1,9 @@
+# Loop prevention keys on (origin device ID, sequence), not content hash
+
+The original protocol draft used `content_hash` recent-history dedup as the
+loop breaker. That is wrong for many-to-many: two different devices pasting
+the same text are falsely dropped as echoes, and the hash is optional so the
+gate is bypassable. The loop breaker is now the immutable origin device ID plus
+a per-peer monotonic sequence: ignore updates whose `(origin, sequence)` is not
+newer than the last-seen pair, and drop any update whose origin is the local
+device. `content_hash` is retained only for integrity/diagnostics.

docs/adr/0004-key-mismatch-repair.md

@@ -0,0 +1,8 @@
+# Pinned-key mismatch forces a full re-pair
+
+If a peer reconnects with a static key different from the pinned one, the
+session is rejected and the peer is treated as unpaired; a fresh handshake plus
+SAS verification is required before the pinned key is updated. Silently
+accepting a changed key would void the entire purpose of SAS verification (a
+LAN MITM who knows the peer's device ID could swap the key). Reinstalling an
+app therefore means a new identity and a new pairing.

docs/adr/0005-android-accessibility-read.md

@@ -0,0 +1,8 @@
+# Android reads the background clipboard via AccessibilityService
+
+Android 10+ blocks background apps from reading the primary clip, which breaks
+the "send local copy to desktop" half of bidirectional sync. We use an
+AccessibilityService to read the clipboard in the background; if the user denies
+it, the app degrades gracefully to receive-only plus manual send (share/quick
+tile). Applying a received clip via `setPrimaryClip` needs no extra permission
+and always works.

docs/adr/0006-desktop-portal-clipboard.md

@@ -0,0 +1,9 @@
+# Desktop clipboard uses the xdg-desktop-portal Clipboard API
+
+The desktop daemon reaches the clipboard through `xdg-desktop-portal` rather
+than native X11 calls. Wayland — the default session on modern Fedora/Ubuntu —
+exposes no direct clipboard access, so an X11-only daemon is broken for most
+Linux users. Consequence: on Wayland the daemon cannot passively poll; an active
+portal session started by a user gesture is required, so "enable clipboard
+sync" is an explicit action (trivial no-op grant on X11). Windows uses the
+Win32 clipboard API.