Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.
Security Model
NectarLink uses an end-to-end encrypted, mutually authenticated peer-to-peer security model with no central user accounts and no cloud storage. Every connection is authenticated at the transport layer by static Ed25519 device identities and authorized at the application layer by per-device capability toggles and interactive runtime consent gates.
For the full audit record and vulnerability remediation history, see docs/SECURITY-REVIEW.md.
Threat Model
| Adversary / Environment | Assumed Capabilities | Mitigations |
|---|---|---|
| Untrusted LAN / Public Wi-Fi | Can eavesdrop, replay, inject, or MITM UDP/TCP packets; can broadcast spoofed mDNS records | QUIC + TLS 1.3 (iroh) with mutual Ed25519 certificate verification; pairing requires either an out-of-band 128-bit QR secret (HMAC-SHA256) or a commitment-bound 6-digit SAS confirmed on both screens |
Compromised Relay Server (Connect over mobile data / away_mode) |
Can observe outer UDP packet sizes/timing and drop traffic | End-to-end TLS 1.3 termination between peer DeviceId keys; relay never possesses session keys; high-risk capabilities (storage without remote_files) are blocked on ConnectionPath::Relay |
| Malicious Web Page on Local PC | Can send cross-origin fetch / XMLHttpRequest / WebSocket requests to 127.0.0.1:53320 |
Local HTTP API is disabled by default; requires a 256-bit Bearer token in Authorization header (constant-time verified) and rejects any request carrying an Origin header or Sec-Fetch-Mode: cors / no-cors |
| Unprivileged Local App on Android | Can attempt to connect to local ports or read app storage | Elevated helper (InputServer) binds 127.0.0.1:<ephemeral_port> and requires a 192-bit (24-byte / 48-hex-char) per-session SecureRandom token on the first line, verified in constant time (MessageDigest.isEqual) before accepting any commands |
Another App Reaching NectarLink's Shizuku Service (Elevated through Shizuku, elevated/ShizukuShell.kt) |
Gets hold of the Binder of the process Shizuku runs for NectarLink, as the shell user, and asks it to run commands | Shizuku hands that Binder only to NectarLink, and ShizukuShell answers only NectarLink's own UID and Shizuku's. It runs nothing it's given as a command line: only the grants Elevated needs for NectarLink's own package (pm grant, appops set … allow, `cmd notification allow_listener |
| Offline Disk Inspection | Read access to %LOCALAPPDATA%\Nectarlink or Android app data directory |
Private identity key (identity.key) and clipboard vault (clipboard_history.enc, clipboard_images/*.enc) are sealed using Windows DPAPI (CryptProtectData, tied to the Windows user logon credential) or Android Keystore AES-256-GCM (hardware-backed when supported by the device) |
| Paired Device Exceeding Intended Access | Attempts to invoke disabled capabilities, traverse outside shared paths, or start silent screen/input capture | Inbound dispatch enforces CapabilityMatrix::is_allowed per peer, canonicalizes file paths, and gates sensitive sessions (pc_mirror, remote_input, first-time storage, webcam) behind explicit user confirmation |
Cryptographic Device Identity
Implemented in core/nectarlink-core/src/identity.rs.
- Each installation generates a 32-byte Ed25519 secret key (
iroh::SecretKey) using the OS CSPRNG (rand::rng()). - The corresponding 32-byte Ed25519 public key (
iroh::EndpointId) serves as the canonicalDeviceId(rendered in logs and URIs as z-base-32, with a 16-charactershort()prefix for UI display). - On disk,
identity.keyis stored with a 5-byte header:- Bytes
0..4: SignatureNLK1(b"NLK1"). - Byte
4:KeyProtectorID (0=PlainKeyProtectorfor headless CLI/tests,1= OS key protector). - Bytes
5..: Sealed ciphertext.
- Bytes
- Windows OS Account Protection (
DpapiKeyProtector): Calls Win32CryptProtectDataandCryptUnprotectData(CRYPTPROTECT_UI_FORBIDDEN) bound to the current Windows user logon credential with domain separation entropyb"nectarlink/identity/v1". - Android Keystore Protection (
KeystoreKeyProtector.kt): Generates a non-exportable 256-bit AES-GCM key (alias = "nectarlink.identity.v1") insideAndroidKeyStore(PURPOSE_ENCRYPT | PURPOSE_DECRYPT,BLOCK_MODE_GCM,ENCRYPTION_PADDING_NONE, which may be hardware-backed on devices with StrongBox or TEE) and seals secrets as12-byte IV || ciphertext || 128-bit auth tag. - On Windows and Android, file permissions are restricted to the owner immediately upon creation. Legacy raw 32-byte key files are transparently migrated into
NLK1sealed format on first load.
Pairing Protocols (ALPN_PAIR = "nectarlink-pair/0")
Implemented in core/nectarlink-protocol/src/pairing.rs and core/nectarlink-core/src/pairing.rs. Pairing runs over a dedicated QUIC ALPN (nectarlink-pair/0) and enforces a 5-minute expiration (PAIRING_TTL = 300s) and a maximum of 5 failed attempts (MAX_FAILED_ATTEMPTS = 5) before invalidating the pairing session.
1. QR Code Pairing Flow
Host (displays QR) Joiner (scans QR)
------------------ -----------------
Generates 128-bit secret S (16 bytes)
Encodes nectarlink://pair?v=0&id=<host_id>&s=<base64url_S>&n=<name>&a=<ip:port>
◄─── QUIC + TLS 1.3 (ALPN: nectarlink-pair/0) ───
◄─── pair.request { id, name, kind, proof } ─────
where proof = HMAC-SHA256(S,
"nectarlink-pair-v0" || joiner_id || host_id)
Verifies TLS peer == joiner_id
Verifies HMAC proof in constant time
──── pair.accept { id, name, kind } ────────────►
◄─── pair.done ──────────────────────────────────
Persists peer to SQLite Persists peer to SQLite
Closes with CLOSE_PAIRED (0)
- Because the 128-bit secret
Sis transferred optically via the QR code (sencoded in URL-safe base64 without padding) and the HMAC binds bothjoiner_idandhost_idverified against the TLS 1.3 peer certificates, an active network attacker cannot forgepair.requestor substitute their ownDeviceId.
2. Nearby Discovery and 6-Digit Code Flow
When pairing via mDNS discovery or manual IP without scanning a QR code, both devices execute a commitment-based Short Authentication String (SAS) ceremony:
- Initiation: Joiner sends
pair.requestwithproof: None. - Commitment Exchange:
- Joiner (initiator
A) generates a 128-bit random noncenAand sendspair.commit { commit: SHA-256(nA) }. - Host (responder
B) generates a 128-bit random noncenBand replies withpair.nonce { nonce: nB }. - Joiner reveals
pair.reveal { nonce: nA }. - Host verifies
SHA-256(nA) == commitin constant time (subtle::ConstantTimeEq).
- Joiner (initiator
- SAS Calculation: Both sides compute a 6-digit numeric code:
SAS = (u32_be(HMAC-SHA256(nA || nB, "nectarlink-sas-v0" || idA || idB)[0..4]) & 0x7fff_ffff) mod 1,000,000(whereidAis the initiator's 32-byte Ed25519 public key andidBis the responder's 32-byte Ed25519 public key;derive_sas_boundalso supports binding the TLS 1.3 session exporterEXPORTER-nectarlink-pair-v0).
- Two-Sided User Confirmation: Both devices display the 6-digit code and require explicit user approval (
pair.confirm { accept: true }). Neither side writes the peer to SQLite untilpair.donecompletes the two-phase commit.
Session Authentication (ALPN_SESSION = "nectarlink/0")
Every operational session connects over ALPN_SESSION ("nectarlink/0"):
- During the QUIC + TLS 1.3 handshake,
irohcryptographically verifies that the remote peer holds the private key for its claimedEndpointId(DeviceId). - Immediately upon connection acceptance (
node.rs), the node looks up the remoteDeviceIdin the SQLitepeerstable (store.is_paired(&peer_id)). - If the
DeviceIdis not present inpeers, the connection is immediately terminated with application close codeCLOSE_UNPAIRED(1) before any control stream or capability handler is invoked.
Authorization and the CapabilityMatrix
Implemented in core/nectarlink-core/src/features.rs. Every paired device has an independent set of 18 feature toggles stored in the peer_toggles SQLite table (DEVICE_TOGGLES).
Default-On vs Opt-In Toggles
| Category | Toggle Keys | Default State |
|---|---|---|
| Standard Continuity (13) | notifications, messages, calls, contacts, clipboard, files, media, photos, recordings, toggles, pc_actions, mirroring, webcam |
Enabled (true) upon pairing |
| High-Sensitivity / Opt-In (5) | storage, pc_mirror, remote_input, commands, remote_files |
Disabled (false) upon pairing; must be explicitly enabled by the user |
Inbound Enforcement
CapabilityMatrix::is_allowed(peer, capability) maps every incoming wire capability (cap::SMS, cap::STORAGE, cap::MIRROR_PC, cap::REMOTE_INPUT, cap::COMMANDS, etc.) to its governing toggle key (feature_for_capability) and checks the peer's persisted policy before executing any handler. Outbound operations similarly call check_toggle before opening streams.
Relay Restrictions (Connect over mobile data / away_mode)
When a session is connected over ConnectionPath::Relay (Connect over mobile data / away_mode), Node applies additional transport-aware authorization:
- Remote file system browsing and downloads (
storage.v0) are blocked on relay connections unless the user has enabled both thestoragetoggle and the opt-inremote_filestoggle for that peer. - Relay discovery and relay servers remain completely disabled (
RelayMode::Disabled) unless the user explicitly turns on Connect over mobile data (away_mode).
Runtime Consent Gates
Even when a capability toggle is enabled, sensitive operations require interactive user confirmation:
- Reverse PC Screen Mirroring (
mirror.pc.v0): When a phone requests to view the PC screen, the desktop app emitsNodeEvent::PcMirrorRequestedand blocks streaming until the user approves the prompt (set_pc_mirror_session_allowed). While active, the desktop displays a persistent top banner with a one-click Stop Sharing button (stop_pc_mirror). - Remote Input Control (
remote.input.v0): Synthesizing mouse and keyboard input on the PC requires both the opt-inremote_inputtoggle and interactive session approval (NodeEvent::RemoteInputRequested). - Phone Storage Browser (
storage.v0): First-time remote browsing of phone shared storage triggers an on-phone confirmation prompt (storage_promptedstate) in addition to Android's systemMANAGE_EXTERNAL_STORAGEpermission. - Phone-as-Webcam (
webcam.v0): Starting a camera stream from the PC notifies the phone and allows the phone user to stop or flip the camera at any time. - LocalSend Incoming Files (
localsend.v2): Unauthenticated LAN LocalSend peers never bypass pairing; every incoming LocalSend offer entersTransferState::Requestedand waits for explicit user acceptance before writing files to the Downloads directory.
File System and Path Traversal Protections
- Incoming Transfers (
core/nectarlink-core/src/transfer.rs):sanitize_relative_pathstrips leading slashes, drive prefixes,.components, and rejects any path containing..(Component::ParentDir), confining all writes to<download_dir>and<data_dir>/incoming/<peer>/<transfer_id>/. - Storage Browser (
android/app/.../StorageHelper.kt): Resolves every requested path viaFile(root, rel).canonicalFileand verifies thatcanonical.pathstarts with the canonical/storage/emulated/0root prefix, blocking symlink escapes into/data/data/app.nectarlink.android.
Automatic Updates and Release Verification
Implemented in desktop/app/src/updater.rs (win/http.rs), desktop/installer/nectarlink.nsi (the task's definition) and android/app/src/main/kotlin/app/nectarlink/android/update/AppUpdater.kt.
- Endpoint: Both apps query
https://api.github.com/repos/thtbee/nectarlink/releases/latestover HTTPS with the OS TLS stack (WinHTTP,HttpURLConnection). Onlyhttps://URLs are fetched, redirects stay on HTTPS, and responses are size-capped while they are read. No device identifiers or telemetry are sent. - What is accepted: a published release (not a draft or pre-release) whose version is newer than the running one, with an installer named
Nectarlink-*-x64-setup.exe(Windows, a plain file name) or*-android.apk, and aSHA256SUMS.txtthat lists it. The download is rejected unless its SHA-256 matches. Android additionally refuses an APK not signed with the app's own key. - Windows, installing without a prompt: the app is installed per machine, so installing needs administrator rights. The installer registers the scheduled task Nectarlink Update, which runs
nectarlink-desktop.exe --update-serviceas SYSTEM. Its security descriptor gives SYSTEM and Administrators full control and authenticated users read and execute only, so a signed-in user can start it but not change what it runs. The task takes no arguments or input from the user: it fetches the latest release itself and applies the checks above. When the user clicks Update, the app first downloads the installer itself (resumable, with progress) into%ProgramData%\Nectarlink\updatesand checks it against the sums. The task copies that file into a new randomly named folder inC:\Windows\SystemTemp(writable only by SYSTEM and administrators) and checks the copy against the sums it fetched itself, so a file planted in the shared folder can only ever be the official installer. When there is no matching file, it downloads the installer into that folder itself. It then runs the installer with/Sand logs toupdate.login the install folder. The worst a user can do by starting it is install the latest official release early. - Windows, a folder outside Program Files (
win/install_dir.rs): the task, and the installer closing the old copy, runnectarlink-desktop.exefrom the install folder with full rights, so they only do so where nobody else can swap it. Setup creates the install folder, and any folder above it that's missing, one level at a time, and locks each like Program Files (owner Administrators; SYSTEM and Administrators full control, Users and app packages read and execute; refused unless empty after locking, so nothing planted before stays). A folder above that a normal user can rename would still let them put a folder of the same name in its place, so the setup window reads the owner and permissions of every existing folder up to the drive's root. When none can be deleted, renamed or re-permissioned by anyone but SYSTEM, Administrators or TrustedInstaller, the installer gets/ADMINONLY=1and registers the task; otherwise there's no task, the installer doesn't run the old copy (it ends it withtaskkill), and updates use the UAC prompt. The result is kept inHKLM\Software\Nectarlink\AdminOnlyFolderfor later updates. Only USB, network and non-NTFS/ReFS drives are refused outright. - Windows, when: with Install updates automatically on, the app starts the task once nobody has used the PC for 10 minutes and nothing would be interrupted (mirroring, an app window, a transfer, a call, screen sharing, the webcam). It first starts a hidden relauncher, which reopens the app once the new version's
DisplayVersionis in the uninstall key and the installer has exited, then quits. Without the task (copies installed before it existed) Update runs the installer with the usual UAC prompt. - Android: with Install updates automatically on, the connection service checks in the background at most once a day and installs through
PackageInstallerwithUSER_ACTION_NOT_REQUIRED(Android 12+,UPDATE_PACKAGES_WITHOUT_USER_ACTION). Android skips the prompt only when NectarLink installed the current version itself; otherwise the user confirms from a notification. - Opt-out: Check for updates and Install updates automatically in Settings on both apps. With checks off, nothing is fetched.
- Not yet: release binaries are not code-signed (Authenticode) yet, so trust rests on HTTPS to GitHub and the release's checksums.
Localhost HTTP API Isolation
Implemented in desktop/app/src/local_api.rs.
- Default State: Disabled (
local_api_enabled: false). - Network Binding: Binds strictly to
127.0.0.1:53320(DEFAULT_API_PORT), never0.0.0.0. - Token Authentication: Generates a 32-byte (64-hex-char) random token from the system CSPRNG (WinRT
CryptographicBuffer, falling back to CNGBCryptGenRandom; the API stays off if neither answers) stored in<data_dir>/api-token.json. Every request must supplyAuthorization: Bearer <token>or?token=<token>, checked using a constant-time byte comparison (constant_time_eq). - Browser Drive-By Defense:
has_browser_origininspects HTTP headers before routing and returns403 Forbiddenif eitherOriginis present orSec-Fetch-Modeiscorsorno-cors, preventing websites opened in a local browser from probing or invoking the API.