hrynco-kswitcher/LAN-PREVIEW.md

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.