Part I • Mobile & Foldable Application Guide

1. Mobile & Foldable Application (com.asai.lankinetix v2.4.5+2451)

The LanKinetix Android & Foldable app is organized into 4 primary workspaces accessible from the bottom navigation bar (on compact phones and folded cover displays) or the adaptive side navigation rail (on unfolded foldables and tablets ≥ 600dp). Bottom modal sheets automatically clear Android 3-button and gesture navigation bars using an extra viewPadding.bottom + 24dp safety inset.

The 4 Primary Workspaces & Top-Right Action Bar
Workspace / Control Primary Purpose Key Tools Included
1. Scanner Live /24 + Guest VLAN host discovery, network identity management, and per-host forensic inspection. Centered Network Identity Header, Manage Network & Location modal, 4-Layer Consensus Host Cards, Deep Host Inspector (L2 / L3 / L4 / mDNS / UPnP), and Network Timeline Log.
2. Topology Spatial Layer-2 topology visualization, physical room-by-room signal surveys, and RF channel engineering. 2A. Directed Spanning Tree & Mesh Map (1x–5x pinch-zoom), 2B. 1 Hz Live Wi-Fi Walk-Test Meter, and 2C. 2.4 / 5 / 6 GHz RF Spectrum Equalizer.
3. Security Wireless airspace diagnostics, L2-isolated guest station detection, and IoT endpoint discovery. Passive Multicast & Broadcast Monitor, Gateway & ARP Integrity + Rogue AP Verification, On-Demand 802.11 Airspace Diagnostics, and IoT, ONVIF Camera & BLE Device Discovery.
4. SysAdmin Active throughput benchmarking, remote power control, advisory ACL export, and WAN privacy gating. 240° 3-Zone Glowing WAN Speedometer & Dual-Channel Oscilloscope, 2-Tier WAN Privacy Gate, Wake-on-LAN (UDP :9), Live Ping/Port Sweeper, Advisory Quarantine Export, and Signed Webhooks.
Top-Right Bar (QR Icon & ?) Instant access to Companion L2 Bridge pairing and the built-in offline manual. P2P Bridge & QR Pairing Modal (Camera QR Scanner, Handoff QR, URI Paste, Manual IP/Token) and the searchable 7-tab In-App Help Center.

1.1 Network Identity Header, On-Device GPS City & Custom Network Profiles

At the top of the Scanner workspace, LanKinetix displays a centered Network Identity Header (23sp bold) showing your active network name, a Manage Network & Location pill button, and a 2-column LOCATION | ISP PROVIDER status strip underneath.

  • Why Local On-Device GPS Geocoding Is Used: Public IP GeoIP databases (speed.cloudflare.com/meta, ipwho.is) frequently resolve UK and European residential broadband connections to a distant ISP core PoP city (for example, reporting London when you are physically in Huddersfield). When location permission is granted, LanKinetix queries Android's on-device LocationManager + Geocoder (gpsCity / gpsAddress) to display your real physical town/city without transmitting GPS coordinates off-device.
  • Fing-Style Manage Network & Location Modal: Tap Manage Network & Location to set a persistent per-network override keyed by your network's BSSID/Gateway IP:
    • Custom Network Name (e.g., Home Office Fibre or Huddersfield Studio LAN)
    • Location / City Override (e.g., Huddersfield, West Yorkshire)
    • Street Address / Site Notes (e.g., Floor 2 Comms Rack — VLAN 10)
    • Reset to Auto restores automatic SSID and on-device GPS city detection immediately.

1.2 4-Layer Consensus Discovery Engine & Cross-Subnet Guest VLANs

When you tap Scan Network, LanKinetix sweeps all 254 addresses in your active /24 subnet using a bounded 128-worker asynchronous pool and reconciles identity across four independent layers:

  • L1 ARP & Ping: Sends native ICMP Echo requests, multi-port TCP SYN reachability probes (including TCP 62078 for iOS Wi-Fi Lockdown), and a 2-Stage UDP DTIM Wake-Up burst (spaced across UDP ports 5353 and 33434 in 16-host batches) so sleeping iOS/Android phones wake their Wi-Fi radios on the next beacon and reply at Layer 2.
  • L2 mDNS / Bonjour: Multicasts queries for _services._dns-sd._udp.local (UDP :5353) to harvest Apple, Chromecast, Matter, HomeKit, and Linux Avahi service records and TXT attributes.
  • L3 UPnP / SSDP & NetBIOS + Guest VLAN PTR Sweep: Queries UDP :1900 SSDP root XML descriptions, UDP :137 NetBIOS Node Status (NBSTAT), and sweeps the primary gateway's DNS PTR cache (UDP :53) across both your primary /24 and candidate adjacent Guest VLAN /24 prefixes (192.168.1.x, 192.168.2.x, etc. via Ipv4.candidateGuestSlash24Prefixes).
  • L4 TLS / HTTP / Banner: Extracts X.509 Certificate Subject Alternative Name (SAN) / Common Name (CN), HTTP Server headers, and SSH/RTSP banners on safe ports.

1.3 MAC Address Provenance Badges (MacProvenance)

LanKinetix never fabricates or guesses MAC addresses. Every host card and Deep Host Inspector sheet displays an explicit provenance badge showing exactly how that hardware MAC was obtained:

MAC Provenance Values & Engineering Meaning
Provenance Badge Source Layer How It Is Resolved
ARP_bridge Companion L2 Desktop Bridge Authoritative Layer-2 hardware MAC read directly from the desktop OS kernel neighbor table (arp -an / ip neigh / arp -a) or router attach_dev table over TLS-pinned /api/arp.
Gateway_Guest_Table Router DHCP / DNS Cache Harvested from the primary gateway's cross-subnet DNS PTR cache or router attached-device table (gatewayGuestClients) for hosts on an isolated Guest VLAN subnet (e.g., 192.168.2.x).
Radiotap_80211 802.11 Monitor-Mode Airspace Captured directly from cleartext IEEE 802.11 Layer-2 frame headers (QoS Data, Null (Power-Save), Probe Request) via the Desktop Bridge's GET /api/airspace endpoint.
NetBIOS_NBSTAT Standalone Mobile (L7 UDP :137) Extracted from the 6-byte Unit ID trailer inside a Windows/Samba/NAS NetBIOS Node Status (NBSTAT) response.
UPnP_UUID Standalone Mobile (L7 UPnP XML) Extracted from the 48-bit IEEE 802 node field of a time-based RFC 4122 Version 1 UUID inside a UPnP root description XML document.
mDNS_TXT Standalone Mobile (L7 mDNS :5353) Parsed from explicit MAC/device-ID keys advertised in Bonjour/mDNS TXT records (such as deviceid=, mac=, or id=).
Local_OS_ARP Standalone Mobile (Pre-Android 10) Read from the local device's OS neighbor table where permitted by the operating system.
Unresolved_Standalone Standalone Mobile (Android 10–15) The host replied at L3/L4 (ICMP/TCP), but Android 10+ blocks /proc/net/arp and the host did not expose a MAC in L7 payloads. Pair the Companion L2 Desktop Bridge to upgrade this to ARP_bridge.

1.4 Hardware Safe-Mode Guard (Printer & Payment Terminal Protection)

Zero Paper-Vomit Guarantee: Connecting to raw JetDirect or thermal receipt printer sockets (TCP 9100–9102, 8080, 8081) and sending HTTP/TLS banner probes causes legacy printers to print pages of garbage characters. LanKinetix automatically quarantines ports 8080, 8081, 9100, 9101, and 9102 whenever a printer OUI (Epson, Star Micronics, Zebra, Brother, HP, Canon, Bixolon) or JetDirect listener is detected, using a silent 0-byte TCP connect/close and tagging the host Safe-Mode: Deep Banner Probes Skipped.

1.5 Workspace 2A — 3-Tier Spanning Tree Topology & Hysteresis Pinch-Zoom

Switch to Topology → Directed Spanning Tree & Mesh to view your network's physical hierarchy:

  • 3-Tier Hierarchy:
    • Tier 0 (Center Core): Default Gateway / Router (isGateway == true).
    • Tier 1 (Infrastructure Ring): Managed Switches, Wi-Fi Range Extenders / Mesh Nodes (isExtender), the Companion L2 Bridge host (isBridge), and any detected Virtual Guest AP Node (rendered with a dashed link when Ipv4.isVirtualGuestBssidOf detects a Locally Administered 0x02 BSSID sharing bytes 1..4 with your main router radio).
    • Tier 2 (Outer Orbit): Connected Child Endpoints placed under their true Layer-2 parent (upstreamIp) when paired with the Desktop Bridge.
  • Staged 1.0x–5.0x Pinch-Zoom with 0.1 Hysteresis: Pinch-zoom smoothly scales the canvas while keeping node radii and stroke widths crisp (radius / scale). Semantic label detail transitions across 3 stages with a ±0.1 hysteresis band at the 1.5x and 3.0x boundaries (computeTopologyZoomLevel) so labels never flicker while your fingers hold near a threshold:
    • Overview (< 1.5x): Compact bracket-safe short names (mapNodeShortName, max 2 words / 18 chars) with greedy collision culling (cullTopologyLabels) so Tier-0/Tier-1 labels always take priority and never overlap.
    • Standard (1.5x – 3.0x): Full device name + IPv4 address pill.
    • Forensic Detail (≥ 3.0x): Multi-line forensic badge with full hostname, IPv4, OUI vendor, and MAC provenance.

1.6 Workspaces 2B & 2C — 1 Hz Walk-Test Meter & 2.4/5/6 GHz RF Equalizer

  • 1 Hz Live Wi-Fi Signal Walk-Test Meter (2B): Samples your phone's own hardware Wi-Fi radio once per second (1000 ms) to drive a 180° radial dBm gauge, a 60-second scrolling sparkline, a BSSID roam counter, and a 24-zone Room Coverage Logger (Strong ≥ -60 dBm, Good -61 to -70 dBm, Weak -71 to -78 dBm, Dead Spot < -78 dBm). Even when paired with the Desktop Bridge, Walk-Test stays locked to your handheld phone radio so room measurements reflect where you are standing.
  • 2.4 / 5 / 6 GHz RF Spectrum & Channel Equalizer (2C): Computes co-channel and adjacent-channel sideband overlap across 2.4 GHz (Ch 1–13), 5 GHz (UNII-1 to UNII-3), and 6 GHz Wi-Fi 6E/7 PSC channels, recommends the cleanest channel with estimated dB improvement, and provides a 1-tap Mask Neighbor SSIDs toggle (Neighbor-AP #N [Redacted]) for privacy-safe screenshots.

1.7 Workspace 3 — Gateway & ARP Integrity, Rogue AP Verification & 802.11 Airspace Diagnostics

  • Auditable 3-Tier Rogue AP & BSSID Consistency Verification: Compares every visible BSSID broadcasting your SSID and prints raw OUI vendor strings, RSN cipher suites, and ΔRSSI dB:
    • CRITICAL — RSN CIPHER DOWNGRADE: Your SSID is broadcast simultaneously with encrypted (WPA2/WPA3) and OPEN security.
    • MODERATE — BSSID OUI MISMATCH: Unrecognized mixed hardware OUI vendors broadcasting your SSID with matching encryption.
    • INFO — KNOWN EXTENDER MESH OUI & VIRTUAL GUEST WLAN: Verified LAN radios, extender proxy-MAC groups, and Locally Administered (0x02 bit-unmasked via Ipv4.clearLocallyAdministeredBit) Virtual Guest BSSIDs are attributed as Your Guest / Virtual WLAN instead of triggering false-positive Rogue AP alerts.
  • On-Demand 802.11 Airspace Client Station Radar (Scan 802.11 Stations): Consumer routers isolate Guest Wi-Fi clients at Layer 2 so they cannot be pinged from the main LAN. When paired with the Desktop Bridge, tapping Scan 802.11 Stations invokes GET /api/airspace (tcpdump -I monitor-mode capture) to display active 802.11 client stations, their OUI vendor, associated BSSID (tagged GUEST WLAN, YOUR AP, or EXT BSSID), radiotap dBm, frame types (QoS Data, Null (Power-Save), Probe Request), and any cross-matched LAN IP/hostname.

1.8 Workspace 4 — 3-Zone Glowing WAN Speedometer & 2-Tier WAN Privacy Gate

  • Centered 240° 3-Zone Glowing WAN Speedometer: Tapping Start Live Test launches a multi-stream Cloudflare TLS benchmark (10 MB + 15 MB + 25 MB parallel download workers + 128 KB upload slices) with a non-linear 0 → 1G dial, an unobstructed glowing center hub, a status/tier pill positioned cleanly underneath the dial, and a real-time Dual-Channel Throughput Oscilloscope below:
    • Slow Zone (0 – 25 Mbps): Glowing Deep Fiery Orange (#FF6B00 → #FF9500)
    • Good Zone (25 – 100 Mbps): Glowing Deep Electric Blue (#0072FF → #00C8FF)
    • Great / Optimal Zone (100 Mbps – 1 Gbps): Vibrant Neon Green (#00E676 → #39FF14)
  • 2-Tier WAN Privacy Gate:
    • Default (Opt-In: Resolve Public IP / ASN = OFF): ISP identification runs 100% locally via inferLocalGatewayIsp (matching gateway IEEE OUI, gateway hostname, and SSID prefix) with zero external WAN packets.
    • Strict LAN-Only Mode: Software-blocks all non-RFC1918 WAN sockets and disables the WAN Speed Test button (Disabled (LAN-Only)).
Part II • Command-Line Interface (CLI) Reference

2. CLI Reference (bin/lankinetix_desktop_bridge.dart)

The LanKinetix Desktop Bridge is a pure-Dart command-line daemon (v3.0.0, protocol lankinetix.bridge.v3) that runs on macOS, Linux, and Windows. It has zero Flutter UI dependencies and can be run interactively in a terminal or headless on a home server / workstation.

2.1 Prerequisites & Native OS Utilities

Platform Requirements & Native OS Inspection Commands Executed by the CLI
Platform Neighbor / ARP & Route Commands Wi-Fi & 802.11 Station Radar Commands TLS Certificate Generation
macOS (macos) arp -an, route -n get default, netstat -rn -f inet airport -I / -s, system_profiler SPAirPortDataType, tcpdump -I -i en0 -n -e -tt -c 200 (with local arp -an fallback) openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 (pre-installed via LibreSSL/OpenSSL)
Linux (linux) ip -4 neigh show, /proc/net/arp, ip -4 route show default nmcli / iw dev scan, tcpdump -I -n -e -tt -c 200 openssl (standard system package)
Windows (windows) arp -a, route print -4 netsh wlan show networks mode=bssid openssl (via Git for Windows / Winget, or pass --allow-plaintext-lan if unavailable)

2.2 Complete CLI Flags & Options Reference

Every flag below is parsed by runBridgeCli in lib/bridge/bridge_cli.dart. Options that accept values support both space-separated (--port 8787) and equals-separated (--port=8787) syntax.

Command-Line Options for dart run bin/lankinetix_desktop_bridge.dart
Flag / Option Default Validation & Exact Behavior
-h, --help — Prints the brand banner and CLI usage help to stdout and exits immediately with code 0.
-v, --version — Prints LanKinetix Desktop Bridge v3.0.0 (protocol lankinetix.bridge.v3) and exits with code 0.
--bind <ip> 0.0.0.0 IPv4 address to bind the HTTPS/WSS server to. Must be a valid IPv4 address (e.g., 0.0.0.0, 127.0.0.1, or a specific LAN interface IP like 192.168.0.50); otherwise exits with code 2.
--port <1..65535> 8787 TCP port for the HTTPS (or HTTP) and WebSocket server. Must be an integer in 1..65535; otherwise exits with code 2.
--udp-port <0..65535> 8786 UDP port for the zero-secret auto-relocation responder (LANKINETIX_DISCOVER_BRIDGE). Passing --udp-port 0 completely disables UDP listening so the bridge emits zero UDP packets.
--config-dir <path> OS Config Path Overrides the directory where bridge_token, cert.pem, key.pem, pairing_uri.txt, and quarantine.json are stored. Enforces 0700 directory permissions on POSIX systems.
--rotate-token false Regenerates a fresh 128-bit CSPRNG bridge_token and a fresh self-signed EC P-256 TLS certificate before starting. Previously paired phones will require re-pairing via the new QR code.
--allow-plaintext-lan false (TLS Required) Explicit opt-in to run over unencrypted HTTP/WS if openssl is unavailable. Note: HMAC-SHA256 request signing and anti-replay nonces remain strictly enforced even in plaintext mode.
--no-qr false Suppresses printing the 100-column intro banner, ISO/IEC 18004 QR matrix, and raw lankinetix://bridge URI to the terminal (protecting against shoulder-surfing). Still writes pairing_uri.txt with mode 0600.

2.3 POSIX Exit Codes

Deterministic CLI Exit Codes
Exit Code Meaning Trigger Conditions
0 Clean Exit --help, --version, or graceful daemon shutdown via SIGINT (Ctrl+C) / SIGTERM.
1 Runtime / Security Error Unsafe config directory permissions (refuses symlink or non-owner directory), missing openssl when --allow-plaintext-lan is not set, or port already in use.
2 CLI Usage Error Unknown flag, missing flag value, invalid IPv4 address for --bind, or out-of-range port number.

2.4 Copy-Ready CLI Recipes

1. Standard Interactive Launch (Recommended — TLS + QR Code + Auto-Discovery)
cd LanKinetix
dart run bin/lankinetix_desktop_bridge.dart
2. Launch with Full 802.11 Monitor-Mode Capture Privileges (macOS / Linux)
# Grants bpf / monitor-mode access so GET /api/airspace (tcpdump -I) captures raw 802.11 stations
sudo dart run bin/lankinetix_desktop_bridge.dart --config-dir "$HOME/.config/lankinetix"
3. Rotate Credentials & Lock Down for Headless / Zero-UDP Operation
# Regenerates 128-bit secret + EC P-256 cert, disables UDP :8786, and hides terminal QR
dart run bin/lankinetix_desktop_bridge.dart --rotate-token --udp-port 0 --no-qr

2.5 Startup Sequence & Credential Files (0700 / 0600)

When you run dart run bin/lankinetix_desktop_bridge.dart, the CLI performs five deterministic steps:

  1. Credential & TLS Provisioning: Creates ~/.config/lankinetix/ on macOS/Linux (or %APPDATA%\LanKinetix\ on Windows) with mode 0700, loads or generates the 32-hex (128-bit) bridge_token and self-signed EC P-256 TLS certificate (cert.pem + key.pem) bound to your advertised LAN IP via Subject Alternative Name (IP:<advertisedIp>,DNS:localhost,IP:127.0.0.1).
  2. OUI Database & Initial /24 Enrichment Sweep: Loads all 40,399 IEEE OUI vendor prefixes into memory and performs an initial ARP + safe-port TCP/UPnP/mDNS enrichment sweep of your active subnet and any router-reported Guest VLAN hosts.
  3. 100-Column Retro-Cyber Banner & Live Host Table: Prints the LanKinetix × ASAI retro-cyber terminal banner, server status summary (Bind Address, Advertised LAN IP, Default Gateway, Certificate SHA-256 Pin, Token Fingerprint), and the list of discovered active LAN and Guest VLAN hosts.
  4. ISO/IEC 18004 Terminal QR Code: Renders a scannable Unicode half-block QR code (Error Correction Level M) and writes the pairing URI to pairing_uri.txt (mode 0600).
  5. 5-Second Snapshot Push Loop: Refreshes the OS neighbor table every 5 seconds and pushes updated snapshots to all connected WebSocket clients (max 8 concurrent clients).
Part III • L2 Bridge Companion & Protocol Specification

3. L2 Bridge Companion Daemon (lankinetix.bridge.v3)

Starting with Android 10 (API 29+), non-rooted mobile apps are blocked by SELinux from reading the kernel /proc/net/arp neighbor table and are throttled to 4 Wi-Fi scans every 2 minutes. The LanKinetix L2 Bridge Companion runs on any computer on your LAN to supply authoritative kernel ARP tables, true Layer-2 parent topology (upstreamIp), unthrottled 802.11 RF scans, and 802.11 monitor-mode station radar to your phone over TLS-pinned HTTPS and WebSockets.

3.1 Step-by-Step Pairing & Main ↔ Guest Wi-Fi Roaming

A
Method A — Scan the Terminal QR Code with Your Phone Camera (Fastest)

1. Run dart run bin/lankinetix_desktop_bridge.dart on your computer.
2. On your phone, tap the QR / Bridge icon in the top-right header bar to open P2P Bridge & QR Pairing.
3. Tap Scan Laptop Terminal QR with Camera and point your camera at the terminal QR code. The app parses lankinetix://bridge?ip=...&port=8787&token=...&cert=..., pins the EC P-256 SHA-256 certificate fingerprint in Android Keystore (and Apple Keychain on macOS / planned iOS builds), and connects immediately.

B
Method B — Paste lankinetix://bridge URI or Scan 2nd-Device Handoff QR

Copy the single-line URI from ~/.config/lankinetix/pairing_uri.txt (or %APPDATA%\LanKinetix\pairing_uri.txt) into the Paste Pairing URI field in the app. Already paired on one phone? Tap Show Handoff QR on that phone to render a high-contrast QR code on screen for a second phone or tablet to scan.

C
Automatic Relocation Across DHCP Changes & Guest Wi-Fi Switching

If your computer's DHCP IP changes—or if you switch your phone from your Main Wi-Fi (192.168.0.x) onto your Guest Wi-Fi (192.168.1.x / 192.168.2.x) to walk-test or audit guest isolation—LanKinetix automatically relocates the bridge via UDP :8786 discovery and direct gateway/subnet candidate probing while still enforcing your pinned tokenFingerprint and certSha256.

3.2 Cryptographic Authentication & Anti-Replay Specification

Every HTTP request (GET or POST) and every WebSocket upgrade (GET /ws) to the Desktop Bridge must include three cryptographic headers computed using the 128-bit bridge_token (which is never transmitted on the wire):

Canonical HMAC-SHA256 Signature Formula (BridgeProtocol.signRequest)
CanonicalPayload = METHOD + "|" + PATH + "|" + TIMESTAMP_MS + "|" + NONCE_HEX + "|" + SHA256_HEX(BODY_BYTES)
SignatureHex     = HMAC_SHA256_HEX(key: UTF8(bridge_token), message: UTF8(CanonicalPayload))

Required HTTP Headers:
  X-LanKinetix-Bridge-Timestamp : <Unix epoch milliseconds; must be within ±30,000 ms of server clock>
  X-LanKinetix-Bridge-Nonce     : <16–64 lowercase hex chars (128-bit CSPRNG single-use nonce)>
  X-LanKinetix-Bridge-Signature : <64 lowercase hex chars (256-bit HMAC-SHA256 digest, constant-time verified)>
  • Constant-Time Verification: Both BridgeProtocol.constantTimeEquals (for HMAC signatures) and BridgeProtocol.certMatchesPin (for TLS X.509 DER SHA-256 fingerprints) use bitwise XOR accumulation to prevent timing side-channel attacks.
  • Bounded Fail-Closed Replay Cache (BridgeNonceReplayGuard): Tracks single-use nonces for 60,000 ms in a bounded 2,048-entry map. If an attacker floods the bridge with 2,048 fresh nonces within 60 seconds, the guard fails closed (401 UNAUTHORIZED) rather than evicting unexpired nonces or exhausting RAM.

3.3 Complete REST, WebSocket & UDP Endpoint Reference

All Endpoints Exposed by LanKinetix Desktop Bridge (lankinetix.bridge.v3)
Method & Path / Port Auth & Rate Limit Description & Response Contract
GET /api/status HMAC Signed • 120 req / 10s Lightweight health, version, and TLS verification check. Returns {ok: true, protocol, bridgeVersion, bridgeHostname, bridgePlatform, hostCount, tls, quarantineCount}.
GET /api/arp HMAC Signed • 120 req / 10s Returns the full Layer-2 kernel ARP snapshot including hosts[] (with realHardwareMac, upstreamIp, l2ClientCount, isExtender, UPnP/mDNS metadata) and cross-subnet guestVlanHosts[].
GET /api/wifi HMAC Signed • 20s Cache TTL Triggers or returns a cached native desktop 802.11 BSSID scan (wifiSpectrum[]) including channel frequency, bandwidth, security cipher, RSSI (dBm), and hardware noise floor (noiseDbm).
GET /api/airspace HMAC Signed • On-Demand Runs a bounded tcpdump -I -n -e -tt -c 200 802.11 monitor-mode capture (with local neighbor fallback) to enumerate active wireless client stations (stations[]) including L2-isolated Guest Wi-Fi clients, radiotap dBm, frame types, and OUI vendor.
GET /api/quarantine HMAC Signed • 120 req / 10s Returns active advisory quarantine entries from quarantine.json (automatically pruning expired timers).
POST /api/quarantine HMAC Signed (Body Hash) • Max 16 KB Adds or removes an advisory quarantine entry ({"action": "add"|"remove", "ip": "...", "mac": "...", "expiresAt": "..."}). Enforces 403 PROTECTED_INFRASTRUCTURE if the target IP matches the gateway or bridge host.
GET /ws HMAC Signed Upgrade • Max 8 Clients Upgrades to a TLS-pinned WebSocket that pushes full snapshot JSON payloads every 5 seconds and replies to {"type":"ping"} with {"type":"pong","ts":ms}.
UDP :8786 Zero-Secret • 5 replies / 10s per IP Listens for {"type":"LANKINETIX_DISCOVER_BRIDGE","protocol":"lankinetix.bridge.v3"} and replies unicast with LANKINETIX_BRIDGE_HERE containing bridgeIp, httpPort, tokenFingerprint, and certSha256 (never the secret token).

3.4 Exact JSON Payload Schemas

GET /api/arp & WebSocket Snapshot Schema
{
  "type": "snapshot",
  "protocol": "lankinetix.bridge.v3",
  "bridgeVersion": "3.0.0",
  "bridgeIp": "192.168.0.50",
  "bridgeHostname": "Patricks-MacBook-Pro",
  "bridgePlatform": "macos",
  "gatewayIp": "192.168.0.1",
  "generatedAt": "2026-10-27T15:00:00.000Z",
  "hostCount": 2,
  "wifiSupported": true,
  "hosts": [
    {
      "ip": "192.168.0.20",
      "mac": "B0:BE:76:AA:11:22",
      "interface": "en0",
      "vendor": "TP-Link Systems Inc",
      "hostname": "RE700X-Mesh",
      "isExtender": true,
      "l2ClientCount": 4
    },
    {
      "ip": "192.168.0.88",
      "mac": "B2:BE:76:CC:33:44",
      "realHardwareMac": "DC:A6:32:CC:33:44",
      "upstreamIp": "192.168.0.20",
      "interface": "en0",
      "vendor": "Raspberry Pi Trading",
      "hostname": "octopi.local",
      "linkType": "Wi-Fi 5GHz"
    }
  ],
  "guestVlanHosts": [
    {
      "ip": "192.168.2.104",
      "mac": "F0:18:98:44:55:66",
      "vendor": "Apple, Inc.",
      "hostname": "Guest-iPad",
      "linkType": "Guest Wi-Fi (Isolated VLAN)"
    }
  ]
}
GET /api/airspace (802.11 Station Radar Schema)
{
  "ok": true,
  "supported": true,
  "source": "macos_tcpdump_80211+arp",
  "scannedAt": "2026-10-27T15:00:04.000Z",
  "stationCount": 1,
  "stations": [
    {
      "mac": "F0:18:98:44:55:66",
      "bssid": "8E:9A:8F:AA:00:02",
      "rssiDbm": -58,
      "frameCount": 14,
      "frameTypes": ["QoS Data", "Null (Power-Save)"],
      "probedSsids": [],
      "vendor": "Apple, Inc.",
      "isLocallyAdministered": false
    }
  ]
}

3.5 Deterministic HTTP Error Code Reference

Every rejected request returns a JSON body of the form {"ok": false, "error": "<CODE>"} with Cache-Control: no-store and X-Content-Type-Options: nosniff:

HTTP Status & Error Codes Returned by BridgeServer
HTTP Status Error Code Cause & Resolution
401 UNAUTHORIZED / CLOCK_SKEW Missing/invalid HMAC signature, reused nonce, or phone/desktop clock difference exceeds ±30,000 ms. Sync NTP time or re-scan the bridge QR code if --rotate-token was used.
403 PROTECTED_INFRASTRUCTURE / FORBIDDEN_SOURCE Attempted to quarantine the default gateway IP, bridge IP, or loopback/link-local address, or request originated from a non-RFC1918 public IP.
400 BODY_NOT_JSON / IP_INVALID / MAC_INVALID / EXPIRES_IN_PAST Malformed JSON body or invalid IPv4/MAC/expiration timestamp in POST /api/quarantine.
413 / 429 PAYLOAD_TOO_LARGE / RATE_LIMITED Request body exceeded 16,384 bytes (413) or client exceeded 120 HTTP requests / 10s (429).
503 / 507 TOO_MANY_WEBSOCKETS / QUARANTINE_LIST_FULL More than 8 simultaneous /ws clients connected (503) or quarantine.json reached its 256-entry cap (507).