Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

Reach: pairing

Every reach ALPN rides iroh =1.4.1: QUIC with TLS 1.3 over raw public keys, dialed by EndpointId, through a relay or on a direct path. A client must speak iroh's wire: link iroh at a version wire-compatible with 1.4.1.

Living doc, checked against the code 2026-11-14

reach-pair.v1 — pairing a new key with a gateway over reach: the invitation, one stream, one answer line

  • Status: accepted; public, built. public is its label in the API catalog.
  • Scope: how a device that holds an iroh key and an invitation becomes a paired key on one gateway. Once paired, the key opens reach-ws.v1 or reach-voice.v1. Roles other than client, key custody and the operator’s commands are out of scope (see runtime/reach).
  • Off by default. The gateway host’s vulpine-reach helper serves nothing unless [reach] enabled = true.

Words

  • The helper: vulpine-reach serve on the gateway’s host. It holds the gateway’s iroh key, its invitations and its paired list.
  • A key: an iroh endpoint key (Ed25519). Its public half, the EndpointId, is the device’s identity. iroh’s QUIC and TLS prove it on every connection, so reach has no token and no API key after pairing.
  • The paired list: the helper’s rows {label, role, grants, …}, one per key. The label is a fleet label (1 to 64 ASCII letters, digits, spaces, -, _ or .), chosen by the operator, never by the device.

The transport

Vulpine’s own client is reach_iroh::helper::pair_attested. The relay sees only ciphertext.

The invitation

The operator mints an invitation (vulpine-reach invite, or the Admin’s Pair a device). It works once and lives 600 seconds. It is text, shown as a QR code or pasted. Keep it out of argv and logs: it is a bearer secret until it is spent.

vulpine-reach:1:<token>:<endpoint id>:<relay url>
vulpine-reach:2:<token>:<endpoint id>:<direct>:<relay url>
field form
<token> 32 random bytes as 64 lowercase hex characters
<endpoint id> the helper’s EndpointId in iroh’s text form
<direct> version 2 only: 1 to 4 private IPv4 addresses (10/8, 172.16/12, 192.168/16) as a.b.c.d-port, joined by ,
<relay url> the helper’s home relay URL, or empty. It is the last field and may itself hold :

Version 2 is minted only when the helper has LAN addresses, so a client on the home network can dial the helper directly. The fleet relay admits only keys on its allow-list, and a new key joins it only once paired. A reader splits at most 3 (version 1) or 4 (version 2) times on :, so the URL stays whole. Any other prefix is not an invitation.

The exchange

  1. The client generates its key and keeps it. Re-pairing means a new invitation; the same key cannot pair twice.

  2. It dials the invitation’s address on ALPN vulpine/pair/1 and opens one bidirectional stream.

  3. It writes the request and finishes its side of the stream:

    bytes what
    32 the token (the raw bytes, not the hex)
    0 or more optional: one attestation (below). Anything after the token that is not exactly one well-formed attestation is read as an invalid one, never as none
  4. The helper answers one line, then finishes:

    ok <label>\n
    no <word>\n
  5. The client reads at most 256 bytes and closes the connection with code 0. The helper closes it with 0 too, after the answer or after 10 seconds, whichever comes first.

On ok, the key is a row on the paired list under <label>. Its role and grants are the ones the invitation was minted with. For a client with no explicit grants they are ws, relay, quic, acp, voice and avatar. The client keeps the gateway’s address: the EndpointId, the relay URL and any direct addresses.

The refusal words

answer meaning
no unknown no live invitation has this token: never minted, already spent, or revoked
no expired the invitation’s 600 seconds are over. A spent or expired token is consumed either way
no already-paired this key is already a row
no store the helper could not write its paired list
no attestation-needed the invitation’s role or grants need an attestation and none came
no attestation-invalid the attestation does not verify over this pairing, or the new key signed itself
no attestation-not-pinned the attesting key is not one of the helper’s [reach] attest_keys

A client must treat any other word as a failed pairing.

The attestation (optional; required for sensitive rows)

A plain client invitation needs none. The helper requires one for the brain and agent-signer roles and for any tcp:<service> grant (ssh), unless the operator turned attestation off. The device’s hardware signs this statement:

"vulpine-reach-attest:1\0" (23 bytes) | new EndpointId (32) | helper EndpointId (32) | BLAKE3(token) (32)

It goes on the stream after the token as kind (1) | key length (1) | public key | signature length (1) | signature:

kind byte public key signature
ed25519 1 32 bytes 64 bytes
p256 2 65 bytes, uncompressed SEC1 (0x04 …) ECDSA with SHA-256, DER, 8 to 72 bytes

After pairing: the accept rule

Every later connection from the key, on any ALPN but vulpine/pair/1, passes the helper’s accept rule after the TLS handshake and before one byte of its protocol is read. A refusal closes the connection with an application code:

code reason when
2 unpaired the key is not on the paired list (or a delegated key’s one admission is spent)
3 revoked the operator revoked the key: its live connections close at once
4 role the key’s row does not grant this ALPN
5 attest the row needs an attestation and has none (a row paired before custody: pair again)

An ALPN the helper does not serve (its switch is off) fails the TLS handshake itself, with no code. Grants are explicit, so a row paired before a grant existed does not gain it: the device pairs again.

Compatibility

  • A change to the request, the answer or the invitation’s version 1 and 2 layouts takes vulpine/pair/2 or vulpine-reach:3:. A new refusal word is a change, because a client reads an unknown word as unreadable.
  • Version 1 invitations stay readable for as long as vulpine/pair/1 is served.

See also

  • API surfaces: this ALPN’s row and its stability label.
  • ADR 0053.
  • runtime/reach: the helper’s commands, files and config.

Was this page helpful?