Add opt-in KSwitcher LAN discovery and mutual code pairing preview

LAN-PREVIEW.md

@@ -0,0 +1,79 @@
+# LAN discovery and pairing preview
+
+This development branch starts the built-in replacement for Mouse Without Borders.
+It adds discovery and authenticated pairing inside the existing KSwitcher resident
+process. It is **not yet a mouse/keyboard or clipboard transport**. Do not disable
+MWB on the strength of this preview.
+
+## Try it on two Windows computers
+
+1. Run this development build on both computers, on the same private IPv4 subnet.
+2. Open Settings → Tools → KSwitcher computers.
+3. Enable discovery on both. The list contains running LAN-enabled KSwitcher
+   instances, not computers returned by a generic Windows/network scan.
+4. Match the computer name and eight-character instance-ID prefix displayed on
+   the other computer. Select each other in the lists.
+5. Generate a code once. Enter that same 32-character code on both computers,
+   then click Pair on both within two minutes. Spaces, hyphens and uppercase
+   hexadecimal characters are accepted. A different code never establishes trust.
+6. Both sides should report Paired; authenticated presence appears as
+   “Paired / verified”. An offline pair stays listed so it can be forgotten.
+
+Discovery uses UDP 45883 on private IPv4 and link-local interfaces. Windows may
+require an inbound firewall allowance for KSwitcher on the private network; the
+preview does not modify firewall rules. Networks that block broadcasts, separate
+VLANs, public IPv4 and IPv6-only networks are not supported yet. A second build
+cannot listen on the same discovery port on the same computer.
+
+Changes in this window apply immediately. Closing the window does not cancel a
+pending pairing; use Cancel pairing. Disabling discovery stops its worker and
+closes its socket. Forget pair removes local trust; forget it on both computers
+for bilateral removal. No input can be sent or received in this milestone.
+
+## Identity, pairing and storage
+
+An instance ID belongs to a KSwitcher data directory, not a hostname/IP address.
+It persists when the LAN configuration is first saved. Discovery announcements
+contain only protocol/version, instance ID, computer name and a fresh challenge.
+Discovered names and addresses are untrusted; they never authorize input.
+
+The generated code has 128 bits of randomness from Windows CNG. It is deliberately
+not a guessable short PIN. HMAC-SHA256 proofs bind the source/destination IDs and
+fresh nonces; both endpoints confirm the handshake before saving the pair.
+Replayed confirmations cannot complete a new attempt. The shared pair key is
+separate from the setup code. The code is never transmitted or logged.
+
+Local identity, enablement and trust records are stored in DPAPI-protected
+`data/lan-pairing.bin`. They are separate from settings export and OpenBao sync.
+Do not clone this file between installations: each instance needs its own identity.
+Unverified/offline status does not remove a previously saved pair. Discovery is
+bounded to 64 visible instances and stale discoveries expire after 12 seconds.
+A newly started pairing window lasts two minutes. Presence challenges rotate so
+captured replies cannot indefinitely keep a disconnected instance verified.
+
+Disabled discovery starts no worker and opens no sockets. Enabling it adds one
+worker thread within KSwitcher; the existing configurator uses local IPC. There
+is no new executable, service, WebView or runtime dependency.
+
+## Next integration milestone
+
+- An authenticated encrypted input channel using the stored pair key, separate
+  from UDP discovery. Pairing alone must never inject input.
+- Left/right/top/bottom screen placement and cursor crossing at the screen edge
+  from the first input prototype, not hotkey-based normal switching.
+- Reuse the resident low-level hooks. Forwarded keys must not expand snippets or
+  invoke actions on the source PC; received keys run through the destination path.
+- Release pressed keys/buttons and return local control on disconnection, timeout,
+  suspend, lock, disable or process shutdown. Keep an emergency return chord.
+- Text/image clipboard transport with bounded sizes and loop suppression follows
+  reliable input handoff. File transfer and secure-desktop control are later work.
+
+## Validation
+
+`KSwitcherLanTests` covers cryptographic test vectors, wrong codes, identity and
+protocol substitution, mutual confirmation, replay, expiry, DPAPI persistence,
+and no worker while disabled. `--network` additionally exercises real discovery
+start/stop/rebind. Settings UI tests cover the child window, disabled actions,
+empty list, parent reactivation and unchanged Save state. Two physical computers
+are still required to validate discovery across adapters/firewalls and pairing
+under real packet loss; this preview does not claim that validation.