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.
publicis 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-reachhelper serves nothing unless[reach] enabled = true.
Words
- The helper:
vulpine-reach serveon 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
-
The client generates its key and keeps it. Re-pairing means a new invitation; the same key cannot pair twice.
-
It dials the invitation’s address on ALPN
vulpine/pair/1and opens one bidirectional stream. -
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 -
The helper answers one line, then finishes:
ok <label>\n no <word>\n -
The client reads at most 256 bytes and closes the connection with code
0. The helper closes it with0too, 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/2orvulpine-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/1is served.
See also
- API surfaces: this ALPN’s row and its stability label.
- ADR 0053.
- runtime/reach: the helper’s commands, files and config.