hrynco-kswitcher/LAN-PREVIEW.md

LAN mouse, keyboard and clipboard — v0.6.58 (experimental)

KSwitcher discovers other enabled KSwitcher instances, pairs them with the same code on both computers, and shares mouse and keyboard through a screen edge. The module runs inside the resident process. Multiple paired computers can be arranged on a monitor grid. Mouse and keyboard follow neighboring cells, including A → B → C, without relaying input through B. New text and images are also shared with all online paired computers: history and the active clipboard. File transfer is not implemented by clipboard synchronization.

Set up multiple computers

1. Install the v0.6.58 or newer on every participating PC. Input protocol v2 requires all participants to update; earlier one-pair builds cannot connect. Preserve local data; do not copy pairing identities between PCs.
2. Open Settings → Tools → KSwitcher computers and enable discovery on both PCs. Only running LAN-enabled KSwitcher instances appear, not generic network devices.
3. Match the computer name and instance-ID prefix displayed on the other PC. Select each other, generate one code, enter that same code on both, then click Pair on both within two minutes. Spaces, hyphens and uppercase hex are accepted.
4. Pair each physical input source with every destination it must control. For unrestricted control from any PC, pair every pair of PCs. Drag monitors into neighboring grid cells and arrange the same physical layout relative to each local PC. For A → B → C, A sees B at (1,0), C at (2,0); B sees A at (-1,0), C at (1,0). Enable input sharing on all PCs. The button controls all pairs, independently of the selected list item. Positions save immediately.
5. Stop MWB or another mouse/keyboard router on both computers before trying KSwitcher input sharing, to avoid two tools forwarding the same events.
6. Wait for the authenticated input connection. Move the cursor through the configured outer screen edge with no keys or buttons held. After the other computer acknowledges the handoff, both mouse and keyboard control that PC. Crossing another shared edge switches directly to that neighbor. Crossing back into the source computer restores its cursor at the corresponding edge. Empty cells, diagonal-only neighbors and offline PCs do not transfer control.

The source cursor is parked and hidden beneath a tiny no-activation window. A small banner identifies remote control; no full-screen layered bitmap is retained. The destination uses its own keyboard layout and runs its own hotkeys/snippets. The source suppresses forwarded events before its local hotkeys, snippets and other low-level hook consumers. Received input is marked so it is not forwarded again. Source recent-input tracking and shortcut latches reset when ownership changes.

Ctrl+Alt+Esc is emergency return, not the normal switching mechanism. Local physical input on a remotely controlled PC takes control back as well. Stop input sharing, disabling discovery, forgetting the currently controlled pair, suspension, secure desktop changes and connection loss cancel remote ownership. TCP heartbeat loss is detected after two seconds; a handoff request expires after one second. Held remote keys/buttons are released. Releases blocked by a secure desktop are retried when the ordinary desktop is available. Source key-ups for keys already sent remotely are consumed after return, avoiding stray local modifier events.

Layout and limitations

• Positions are relative to this PC. All peers have independent authenticated connections; a failed peer does not disconnect the others. The physical source uses its own grid to choose every destination. Moving a monitor cancels current control safely and applies the updated layout without dropping all connections. Layouts are not synchronized automatically. One source controls a destination at a time. Each grid tile represents an entire PC, not an individual monitor.
• Geometry uses the virtual desktop's outer bounding rectangle, including negative monitor coordinates. Internal monitor boundaries do not transfer control. Different resolutions map the entry position proportionally. Irregular layouts can have gaps on an outer edge; this is not a per-monitor arrangement editor.
• Transferring while a key or mouse button is held is intentionally blocked. Dragging works within the controlled computer; dragging objects across PCs is not implemented. There is a short return cooldown to avoid bouncing.
• Windows can block SendInput to elevated apps and secure desktops. Run both applications at suitable privilege levels for the target programs. The preview does not install a service, bypass UAC or implement remote Ctrl+Alt+Delete.
• This is Windows input injection, not a virtual USB HID device. Raw-input games, exclusive full-screen applications and special device keys need separate testing.

Network, authentication and storage

Discovery broadcasts on private IPv4 and link-local interfaces using UDP 45883. Input uses TCP 45884. Allow KSwitcher on your private network when Windows asks; the preview does not change firewall rules. Broadcast-blocked networks, separate VLANs, public IPv4 and IPv6-only networks are not supported by discovery yet. A second LAN-enabled KSwitcher cannot use the same ports on one computer.

The instance ID belongs to a data directory, not a hostname/IP address. Discovered names and addresses are untrusted. Pairing uses a generated 128-bit code and mutual HMAC-SHA256 challenge proofs bound to both instance IDs. The code is never transmitted or logged. The pair key is separate from the setup code.

The input channel authenticates both peers with the saved pair key and fresh session challenges. Directional AES-256-GCM session keys bind the identities, nonces and the input protocol domain. Screen positions determine routing after authentication; they are no longer part of the pair channel key. Fixed-size authenticated frames use strict sequence numbers, so tampering, reflection and replay are rejected. Input is not dispatched until authentication succeeds. This PSK channel does not provide forward secrecy. Queues and frame sizes are bounded; overflow disconnects rather than dropping a key-up and leaving a key pressed. The input worker never injects Windows input; the resident's main thread owns the input state and hooks.

Identity, trust, enablement and screen position stay in DPAPI-protected data/lan-pairing.bin, outside settings export and OpenBao sync. Do not clone this file between installations. Forget a pair on both PCs for bilateral removal. Closing the settings window does not cancel pairing or disable sharing.

Disabled discovery has no socket or worker. Input sharing reuses the single LAN worker; there is no extra resident executable or service. The main input timer runs only while sharing is enabled. The existing configurator talks to the resident through local IPC.

Validation

Tests cover pairing, encrypted frames, replay/tamper rejection, actual loopback TCP authentication and bidirectional delivery, all four edges, ownership races, source suppression, scan codes, clicks/wheel, emergency return, held-key release, blocked injection, secure desktop recovery, exact one-pixel movement and timeout. Tests additionally exercise three actual TCP hubs, independent reconnect, A → B → C and back, vertical turns, unavailable neighbors, stale ownership, modifier delivery to only the active destination, and local shortcut recovery. UI tests drag three monitors and check persistence.

Three physical computers still need an end-to-end trial for their adapters, firewalls, displays and application privilege levels. The automated TCP tests use local sockets, and input-state tests use simulated desktop environments; they do not claim a completed three-machine hardware test.

v0.6.58 connection fixes

Saved trust keeps TCP listeners available even when discovery announcements are missed. Working authenticated input sessions no longer depend on discovery presence. Pair saved is distinct from input connected; the list refreshes every second. A changed instance ID requires a new pairing. Keep each PC's own data folder during upgrades. Connection state changes and listener Windows errors are written to the diagnostic log.