Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.
NectarLink Protocol, version 0 (draft)
Status: draft for Phase 0. Breaking changes are allowed until v1. License: CC BY 4.0. Anyone may implement this protocol.
This document specifies how two NectarLink devices find each other, pair, connect and exchange messages. Version 0 covers the Phase 0 scope: identity, pairing, the session handshake, capabilities, heartbeat and the first events (device info, battery, ping). Feature services are specified in separate documents that build on this one: notifications, clipboard, files, media, actions and remote so far; mirroring follows.
Key words MUST, SHOULD and MAY are used as in RFC 2119.
1. Concepts
| Term | Meaning |
|---|---|
| Device | One installation of NectarLink (a phone, a PC). |
| Device key | An Ed25519 key pair generated on first launch. Never leaves the device. |
| Device ID | The Ed25519 public key (32 bytes). Equal to the iroh EndpointId. Displayed as lowercase z-base-32. |
| Pairing | A one-time ceremony after which each device stores the other's Device ID as trusted. |
| Session | One authenticated QUIC connection between two paired devices. |
| Service | A feature area (e.g. notifications, transfer) that owns its own streams and messages. |
2. Transport
All traffic runs over QUIC via iroh. TLS 1.3 with raw public keys authenticates both ends by Device ID. There is no other encryption layer and no unencrypted mode.
Two ALPN values are defined:
ALPN Purpose Who may connect nectarlink/0Normal sessions Paired devices only nectarlink-pair/0Pairing ceremony Anyone, but only while the receiving device is in pairing mode A device MUST close a
nectarlink/0connection immediately (application errorUNPAIRED, see §8) if the peer's Device ID is not in its trust store.A device MUST reject
nectarlink-pair/0connections when it is not in pairing mode, and MUST leave pairing mode after a successful pairing or a timeout (default 5 minutes).
2.1 Address discovery
Devices locate each other by Device ID. Implementations use, in order of preference (iroh races them):
- Local-network discovery (mDNS address lookup).
- Last known direct addresses, cached per paired device.
- A small UDP beacon on the LAN as a fallback where mDNS is filtered (format to be specified in v0.1).
- Relay servers, only if the user enabled "away from home".
3. Framing
Every QUIC stream carries a sequence of frames:
frame = length (unsigned LEB128, 1 to 4 bytes) || payload (CBOR, `length` bytes)
lengthMUST NOT exceed 1 MiB (1,048,576) for control and RPC streams. Receivers close the stream withFRAME_TOO_LARGEotherwise.- Bulk data (file contents, video) does not use frames. After its header frame, a bulk stream switches to raw bytes as defined by its service.
- All CBOR payloads are maps. Unknown keys MUST be ignored.
3.1 Message envelope
Every frame payload is an envelope:
| Key | Type | Required | Meaning |
|---|---|---|---|
t |
text | yes | Message type, e.g. hello, event.battery |
id |
uint | no | Request ID, unique per stream direction, for messages expecting a reply |
re |
uint | no | The id this message replies to |
b |
map | no | Message body (type-specific) |
A receiver that gets an unknown t carrying an id MUST reply with
error code UNSUPPORTED. Unknown t without an id is silently ignored.
4. Streams
| Stream | Opened by | Kind | Lifetime |
|---|---|---|---|
| Control | The dialing device | Bidirectional | The whole session. Must be the first stream opened |
| RPC / service | Either device | Bidirectional | One operation (a request and its response, or a service sub-session) |
| Bulk | Either device | Uni- or bidirectional | One transfer or media session |
| Datagrams | Either device | QUIC datagrams | Loss-tolerant, latency-critical data (pointer motion, input) |
Every non-control stream starts with a stream header frame:
t = "stream"
b = { svc: text, op: text, v: uint }
svc names the service, op the operation, v the operation's version. If
the receiver doesn't support it, it replies error UNSUPPORTED and closes the
stream.
Datagrams start with a one-byte channel tag (assigned per service in the service specs), followed by service-defined bytes.
5. Session handshake
After the QUIC handshake, the dialer opens the control stream and sends
hello. The listener replies with its own hello. The session is
established once both hellos are exchanged and the version check passes.
t = "hello"
b = {
proto: uint, // protocol version spoken (0 for this document)
min: uint, // oldest protocol version this device still accepts
app: text, // app version, e.g. "0.1.0"
device: DeviceInfo,
caps: [text], // capability IDs this device offers (see §6)
power: text, // "basic" | "assist" | "elevated" | "n/a" (desktop); unknown values are treated as "basic"
}
DeviceInfo = {
name: text, // user-visible name, e.g. "Pixel 9" (receivers keep 64 chars)
kind: text, // "phone" | "tablet" | "desktop" | "laptop"
os: text, // "android" | "windows" | "macos" (32 chars)
os_ver: text, // "16" / "10.0.26200" (32 chars)
model: text?, // e.g. "Google Pixel 9" (64 chars)
accent: uint?, // optional ARGB seed color (Material You sync)
screen: ScreenShape?, // optional measured front-screen geometry (phones/tablets)
}
ScreenShape = {
aspect: float, // upright display width / height (0.25..=2.5)
corners: ScreenCorners?, // per-corner radii as fractions of upright screen width (0.0..=0.5)
cutouts: [ScreenRect]?, // up to 4 front cutout bounding boxes in 0.0..=1.0 upright screen coords
cutout_path: text?, // optional normalized SVG path (<= 512 chars, M/L/H/V/C/Q/Z in 0.0..=1.0)
}
ScreenCorners = { tl: float, tr: float, br: float, bl: float }
ScreenRect = { x: float, y: float, w: float, h: float }
Version negotiation: the session uses min(proto_a, proto_b). If that is
below either side's min, the side that detects it sends error VERSION_TOO_OLD and closes the connection, and both UIs tell the user which
side needs an update.
Either device may send an updated hello.update on the control stream at any
time (for example when the power level or capabilities change):
t = "hello.update"
b = { caps: [text]?, power: text?, device: DeviceInfo? }
6. Capabilities
A capability ID is a lowercase dotted string ([a-z0-9._-], at most 64
bytes) naming something a device can offer. Receivers ignore malformed and
unknown IDs and anything beyond 256 entries. Examples:
| Capability | Offered by | Meaning |
|---|---|---|
core.ping |
both | Responds to ping |
device.battery |
both | Sends battery events |
notify.mirror |
phone | Can forward notifications |
notify.sensitive |
phone | Can forward sensitive (OTP) notifications |
clip.read.auto |
phone | Can read the clipboard in the background |
mirror.input |
phone | Accepts input while mirrored (Assist and up) |
Capabilities describe what the device can do right now given its power
level, OS version, permissions and add-ons. Each app combines both devices'
capabilities with its own local state to compute the capability matrix
that drives the UI (see docs/architecture/capabilities.md). The full
registry of capability IDs lives in docs/protocol/capabilities.md and grows
with each service.
7. Messages in v0
7.1 Heartbeat
QUIC keep-alives keep NAT bindings open. In addition, either side MAY send on the control stream:
t = "ping" id = n b = { ts: uint } // sender's monotonic ms
t = "pong" re = n b = { ts: uint } // echoes ts
A session with no traffic for 45 s SHOULD send a ping. Implementations
measure round-trip time from ping/pong for the connection-health indicator.
7.2 Events
Events are one-way notifications on the control stream. Their type starts
with event..
t = "event.battery"
b = {
level: uint (0 to 100),
charging: bool,
plugged: text? ("ac"|"usb"|"wireless"),
full_in: uint? (estimated minutes until full, 1 to 1440, when charging and known),
cell_bars: uint? (0 to 4, cellular signal strength in bars, when known),
cell_type: text? (cellular network generation/type, e.g. "5G", "LTE", "4G", "3G", "2G"),
wifi_bars: uint? (0 to 4, Wi-Fi signal strength in bars, when connected to Wi-Fi and known),
}
t = "event.device"
b = DeviceInfo // name, accent or screen shape changed
7.3 Find my device
t = "device.ring" id = n b = { on: bool } // start or stop ringing
t = "ok" re = n
7.4 Errors
t = "error" re = n? b = { code: text, msg: text? }
8. Error codes
| Code | Meaning |
|---|---|
UNSUPPORTED |
Unknown message type, service or operation version |
UNPAIRED |
Peer is not in the trust store (also used as the QUIC close reason) |
VERSION_TOO_OLD |
Protocol version below the receiver's minimum |
FRAME_TOO_LARGE |
Frame exceeds the size limit |
BAD_MESSAGE |
Malformed CBOR or missing required fields |
DENIED |
The user or a per-device permission denied the operation |
BUSY |
Temporarily unable; retry later |
INTERNAL |
Unexpected failure on the receiver |
NOT_FOUND |
The thing the request names no longer exists (e.g. a dismissed notification) |
9. Pairing (nectarlink-pair/0)
Pairing establishes mutual trust between two Device IDs. Two flows are
defined. Both run over a nectarlink-pair/0 QUIC connection, so the TLS layer
already authenticates the raw public keys; the ceremony proves that the
human intended this peer.
9.1 QR flow (primary)
The PC enters pairing mode, generates a random 128-bit pairing secret
S, and shows a QR code containing a pairing URI:nectarlink://pair?v=0&id=<pc device id, z-base-32>&s=<S, base64url>&n=<pc name, percent-encoded>[&a=<ip:port>,...]The phone scans it and dials the PC's Device ID with ALPN
nectarlink-pair/0.The phone sends:
t = "pair.request" id = 1 b = { device: DeviceInfo, proof: bytes } // HMAC-SHA256(S, "nectarlink-pair-v0" || phone_id || pc_id)The PC verifies
proofagainst the phone's TLS-authenticated Device ID. On success it replies:t = "pair.accept" re = 1 b = { device: DeviceInfo }On failure it replies
error DENIEDand leaves pairing mode after 5 failed attempts.The ceremony finishes as described in §9.4, after which the phone opens a normal
nectarlink/0session.
Because the phone learned the PC's Device ID from the QR code and the PC
verifies knowledge of S, both directions are authenticated with no codes to
compare.
9.2 Nearby flow (numeric comparison)
Used when the user picks a discovered device instead of scanning. The initiator is A, the responder B.
A → B:
pair.commit { device, c }wherec = SHA-256(nA)andnAis a random 16-byte nonce.B → A:
pair.nonce { device, nB }with a random 16-byte noncenB.A → B:
pair.reveal { nA }. B checksSHA-256(nA) == c.Both compute the short authentication string:
sas = uint32(HMAC-SHA256(nA || nB, "nectarlink-sas-v0" || idA || idB)[0..4]) mod 1,000,000shown as a 6-digit code on both screens.
The user confirms the codes match on both devices. A sends
pair.confirmas soon as its user confirms. B repliespair.confirmonly after both its own user and A confirmed, so B always sends the last message. A decline on either side is sent aserror DENIEDand ends the ceremony immediately.The ceremony finishes as described in §9.4.
The commitment in step 1 prevents an attacker from choosing a nonce to force a matching code; a man-in-the-middle would have different Device IDs on each side and therefore different codes.
9.3 USB flow
When an ADB connection exists, the PC can exchange Device IDs with the phone app over ADB directly. Specified in v0.1 together with the ADB integration.
9.4 Finishing a ceremony
A QUIC connection close discards data the peer hasn't read yet, so the end of a ceremony is acknowledged explicitly:
- The host (B) sends the last protocol message (
pair.acceptorpair.confirm). - The initiator (A) replies
t = "pair.done"and finishes its stream. - The host, after reading
pair.done, stores the initiator as trusted and closes the connection with application code 0. - The initiator stores the host as trusted only when it observes the close with code 0.
Any failure closes with application code 1 and neither side stores
anything. A host that fails waits briefly (up to 2 s) for the initiator to
close first, so its error message is read before the connection goes away.
9.5 Unpairing
Either device may send pair.revoke on an established session, then deletes
the trust entry. A device receiving it deletes its entry too. Unpairing
locally without notifying the peer is always allowed; the peer will then be
rejected with UNPAIRED on its next connection attempt.
10. Compatibility rules
- Adding a message type, a field, a capability or a service is not a breaking change.
- Removing or changing the meaning of a field, message or operation is
breaking: it requires a new operation version (
v) or a new protocol version. - Every app version MUST keep accepting the previous two protocol versions once v1 ships.
- CI runs the current build against the previous two releases in both directions.
11. Security notes
- Device keys are stored encrypted at rest (DPAPI on Windows, Android Keystore wrapping on Android).
- The pairing secret is single-use, kept only in memory, and expires with pairing mode.
- Implementations MUST NOT log message bodies of notification, message, clipboard or file-name content.
- Frame and message decoders are fuzzed in CI.
12. Continuity Camera (camera.capture.*)
A paired PC that announces camera.continuity can ask a paired phone that
announces camera.capture to open its camera UI and capture either a still
photo ("photo") or a perspective-cropped, contrast-enhanced document scan
("scan"). Continuity Camera is gated by the per-device "photos" toggle on
both ends.
12.1 Control messages
camera.capture.request:{ request_id: text, mode: "photo" | "scan" }, sent by the PC on the control stream (request_idis 1..=64 non-control bytes).camera.capture.ok:{ request_id: text }: sent by the phone when the capture UI has been launched.camera.capture.cancel:{ request_id: text, reason?: text }: sent by either device to cancel an in-flight capture request (or by the phone if"photos"sharing is disabled or the camera UI cannot be launched).
12.2 Result stream (svc = "camera", op = "result", v = 1)
When the user accepts the captured photo or scanned document on the phone:
- The phone opens a bidirectional QUIC stream and sends the stream header:
t = "stream",b = { svc: "camera", op: "result", v: 1 }. - Next, the phone sends a metadata frame:
t = "camera.capture.meta",b = { request_id: text, mode: "photo" | "scan", file_name: text, mime: "image/jpeg" | "image/png", size: uint, width: uint, height: uint }(1 <= size <= 33_554_432bytes,file_nameup to 255 bytes). - Immediately after the metadata frame, the phone writes
sizeraw image bytes and finishes its send side. - The PC saves a copy into its downloads directory, replies
t = "ok"(ort = "error"if denied or malformed), finishes its send side, records aPhotoentry in the local timeline, and surfaces the image to the UI for one-click clipboard copy, Save As, or drag-and-drop.
13. LocalSend v2.1 Interoperability (Optional LAN Interop)
In addition to NectarLink's native QUIC/iroh protocol, any NectarLink node can
optionally enable LocalSend v2.1 interoperability (off by default, stored in
the local settings table as localsend.enabled) to send files to and receive
files from unpaired LocalSend devices (iOS, macOS, Linux, Windows, Android) on
the local network.
13.1 Discovery & Coexistence
- Multicast group: UDP
224.0.0.167:53317(SO_REUSEADDRenabled so multiple listeners can share the multicast group). - HTTP/HTTPS server port: TCP
53317by default (configurable viaNodeConfig::localsend_portorNECTARLINK_LOCALSEND_PORT). The TCP listener peeks at the first byte of each incoming connection (0x16= TLS ClientHello) to serve both HTTPS and plain HTTP on the same socket. - Coexistence: If TCP port
53317is already bound by a standalone LocalSend app on the same machine, NectarLink logs a warning, setslocalsend_receiving() = false(leaving incoming transfers to the standalone LocalSend app), and still joins UDP multicast discovery and supports outgoing transfers to discovered LocalSend peers. - Identity & TLS: NectarLink generates a deterministic self-signed X.509 v3
certificate (Ed25519) from the node's device key and advertises its uppercase
hex SHA-256 DER digest as the LocalSend
fingerprint. If a peer's fingerprint matches a paired NectarLinkDeviceId, it is de-duplicated in favor of the native NectarLink session; otherwise a deterministic syntheticDeviceIdis derived fromBLAKE3("nectarlink-localsend-peer-v1:" || fingerprint_or_addr).
13.2 REST Endpoints (/api/localsend/v2/...)
GET /api/localsend/v2/info(andGET /api/localsend/v1/info): returns{ alias, version: "2.1", deviceModel, deviceType, fingerprint, download: false }.POST /api/localsend/v2/register(andPOST /api/localsend/v1/register): records the announcing peer in the in-memoryLocalSendPeertable and replies with this node's info JSON.POST /api/localsend/v2/prepare-upload: validates the incoming file manifest (up to 1,000 files, valid relative paths with no..traversal), creates a transfer inTransferState::Requested, emitsNodeEvent::TransferUpdated, and waits up to 60 seconds for explicit user consent (accept_transferorcancel_transfer) before returning{ sessionId, files: { fileId: token } }or HTTP403when declined.POST /api/localsend/v2/upload?sessionId=...&fileId=...&token=...: streams the raw request body to a.partfile in the downloads folder, atomically renames it to the final destination path on completion, updatesNodeEvent::TransferUpdated, and records the completed transfer in the timeline and received-files store.POST /api/localsend/v2/cancel?sessionId=...: cancels an in-flight upload session and transitions the transfer toTransferState::Cancelled.