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