# Device Link Worldwide Research Review

Last reviewed: 2026-07-08

## Verdict

The current ZoneGaze Device Link foundation is working for contracts, UI, local state, relay configuration, Android invite handling, Android paired-device state, capability toggles, revocation, and Android same-network discovery boundaries.

It is not yet a complete worldwide device-to-device transport. Shared route/message validation, desktop invite handling, signed relay probes, the first self-hostable relay scaffold, and Mac relay allow-list export are now implemented. Real Iroh endpoints, encrypted application message streams, NAT traversal, Android-native relay allow-list export/signing, and physical two-device relay QA still need to be completed behind the existing contracts.

## Best Commercially Safe Plan

Use Iroh as the transport layer behind ZoneGaze-owned adapters:

- `device-link-core`: identity, pairing, message envelope, capability checks, replay protection, and route selection.
- `device-link-desktop`: macOS/Electron identity storage, local discovery, Iroh endpoint, and platform bridge.
- `device-link-android`: Android Keystore identity, NSD pairing discovery, Iroh Kotlin endpoint, background limits, and platform bridge.
- `zonegaze-relay`: self-hostable relay package for user-owned Mac/NAS/router/home server/VPS.

Keep the product rule unchanged: ZoneGaze does not host user traffic, device directories, TURN services, Firebase coordination, or default cloud rendezvous. Worldwide access after setup requires a reachable user-owned relay/gateway or direct internet path.

## Source Findings

- Iroh is still the best fit: it is designed for dialing endpoints by public key, QUIC connections, and NAT traversal, and its repository is MIT or Apache-2.0 licensed, which is compatible with commercial closed-source use when notices are preserved. Source: https://github.com/n0-computer/iroh
- Iroh NAT traversal establishes direct peer-to-peer connections when possible and falls back to relays for strict networks. The docs state that roughly 9 out of 10 real-world network configurations allow direct connection. Source: https://docs.iroh.computer/concepts/nat-traversal
- Relays are required for reliable worldwide access because they coordinate NAT traversal and provide encrypted fallback when direct connection fails. Public relays are free but rate-limited, shared, and not production-guaranteed; production should use dedicated or self-hosted relays. Source: https://docs.iroh.computer/concepts/relays
- Relay servers cannot read payloads because traffic is end-to-end encrypted, but they can see routing metadata such as endpoint IDs and traffic volume while relaying. Source: https://docs.iroh.computer/about/faq
- Official Iroh language support includes Swift for iOS/macOS and Kotlin for Android/JVM, which fits the MacBook-to-Android requirement. Source: https://docs.iroh.computer/languages
- Android NSD is appropriate for same-network pairing because Android documents it for discovering services on the local network, including peer-to-peer apps. Source: https://developer.android.com/develop/connectivity/wifi/use-nsd
- Apple local network use needs privacy strings and Bonjour service declarations when browsing/registering local services. Source: https://developer.apple.com/documentation/bundleresources/information-property-list/nslocalnetworkusagedescription

## Security Model

- Generate a long-lived cryptographic identity per device.
- Store private identity material in macOS Keychain/Electron safeStorage and Android Keystore.
- Pair devices with a short-lived session and matching verification code.
- Accept messages only from paired public keys.
- Keep a per-device capability allow-list; command execution stays off by default.
- Every message includes version, pair id, sender, sequence number, message id, timestamp, capability, payload, and authentication metadata.
- Reject replayed, expired, unknown-device, revoked-device, and unauthorized-capability messages.

## Route Order

1. Direct LAN through local discovery.
2. Direct internet through Iroh IPv6/NAT traversal.
3. User-owned relay fallback.
4. Offline queue and retry for non-urgent sync.

## Current Repo Evidence

Implemented:

- Shared contracts: `flow/contracts/src/device-link.ts`.
- Route selection, paired-device capability validation, revoked-device rejection, stale-message checks, and replay protection helpers in the shared contracts.
- Matrix Devices UI: `flow/web/src/components/devices/matrix-devices-panel.tsx`.
- Desktop controller and IPC bridge: `platforms/desktop/src/device-link-controller.ts`, `platforms/desktop/src/main.ts`, `platforms/desktop/src/preload.ts`.
- Desktop pairing invite handling through `zonegaze-matrix://device-link/pair`, with relay route probes signed by the local Ed25519 identity.
- Desktop snapshots include a relay allow-list config for the current paired device group, and the Matrix Devices screen can copy it as `groups.json` for the self-hosted relay.
- Android native Devices state, invite handling, NSD discovery, bridge methods, capability update, and revocation: `platforms/android/app/src/main/java/com/zonegazeflow/app/DeviceLinkStore.kt`, `DeviceLinkLocalDiscovery.kt`, `DeviceLinkSection.kt`, and `MatrixAndroidBridge.kt`.
- Architecture doc: `docs/architecture/device-link.md`.
- Self-hostable relay scaffold: `platforms/device-link-relay`.

Still missing:

- Iroh endpoint adapters on macOS and Android.
- Encrypted application message stream.
- Android-native relay allow-list export and signing parity.
- Desktop local discovery equivalent to Android NSD.
- Physical two-device QA across same Wi-Fi, hotspot, different networks, relay online/offline, revoked devices, and two separate users on the same relay.

## Validation Run

Passed on 2026-07-08:

- `npm --prefix flow/contracts run typecheck`
- `npx vitest run flow/contracts/src/device-link.test.ts`
- `npm --prefix flow/web run test -- matrix-devices-panel matrix-main-surface`
- `npm --prefix platforms/desktop run test -- device-link-controller`
- `platforms/android/scripts/gradle-with-android-env.sh :app:testDebugUnitTest --tests com.zonegazeflow.app.AndroidDeviceLinkSourceTest --tests com.zonegazeflow.app.DeviceLinkPairedDevicesTest`

Additional focused validation for the relay/auth slice:

- `npm --prefix platforms/device-link-relay run typecheck`
- `npm --prefix platforms/device-link-relay run test`
- `npm --prefix platforms/desktop run test -- device-link-controller protocol-handler`
- `npx vitest run flow/contracts/src/device-link.test.ts`

## Next Implementation Plan

1. Add Iroh endpoint adapters for desktop and Android behind existing `deviceLink.*` bridge methods.
2. Add same-network Mac discovery so desktop can advertise and resolve the same service as Android.
3. Add Android-native relay allow-list export/signing parity and reachability checks without sending plaintext app data.
4. Wire encrypted application messages for chat context, project context, dictation handoff, file handoff, clipboard, notifications, and command execution with explicit approval.
5. Run physical QA on real MacBook and Android devices across LAN, hotspot, remote networks, relay failover, revoked-device rejection, and multi-user isolation.
