Clear, operator-ready documentation for all three components of the LanKinetix suite: the Mobile & Foldable Application, the Command-Line Interface (bin/lankinetix_desktop_bridge.dart), and the Companion L2 Bridge Daemon (lankinetix.bridge.v3). Every flag, endpoint, badge, and formula below matches the production codebase verbatim.
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.
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.
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.
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.
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.
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 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.
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)).
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
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
When you run dart run bin/lankinetix_desktop_bridge.dart, the CLI performs five deterministic steps:
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).
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.
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.
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-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
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.
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)
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.
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).
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.