This is the binding wire contract for every Doriterm package. Each rule below is the current one; the change log at the end records what each revision changed.
Layering, outermost first:
- WebSocket, binary messages only, permessage-deflate off. The only text messages are the ones listed under "Relay text messages".
- Relay routing header (relay path only, between relay and host; clients never see it).
- Noise record layer (E2EE,
@doriface/crypto): one WebSocket message = one Noise message. - Plaintext = a chunk of herdr-core's raw
hc connectbyte stream (JSON-RPC lines, then frames). The host never parses it; it pipes it tohc connect.
- Host signing key: Ed25519 (
@noble/curves/ed25519).hostId= lowercase base32 (RFC 4648, no padding) of the first 16 bytes of SHA-256(signPub) -> 26 chars. - Host Noise static key: X25519.
- Client device static key: X25519, generated once per device. The web generates it as a non-extractable WebCrypto X25519
CryptoKeystored in IndexedDB, and usessubtle.deriveBitsfor the static DHs. When WebCrypto has no X25519 (feature check), it falls back to raw key bytes in IndexedDB. Ephemeral DHs always use@noble/curves. So@doriface/cryptotakes the local static DH as an async functiondh(pub): Promise<Uint8Array>. - What a non-extractable key protects: same-origin script can still use the key while the page is open, but it cannot copy the key bytes out. The raw-bytes fallback offers no such protection.
- Host fingerprint shown to people: the first 20 bytes of SHA-256(noiseStaticPub) (160 bits), uppercase hex, as 10 groups of 4 characters (
3FA9 4C0E ...).doriface-host pairanddoriface-host fingerprintprint it in that form. - Pairing secrets, one set per pairing offer: the 8-character typed code (25 secret bits, used only as a CPace password) and a 32-byte random link secret (carried only in the pairing URL fragment). Neither is ever used directly as a key. Typed-code pairing binds
hostId, the host Noise static key and the slot into the PAKE, so a code typed for one host cannot be used against another. - Mesh id: lowercase base32 (RFC 4648, no padding) of the first 16 bytes of SHA-256 of the mesh's founding record body (26 characters).
- Mesh signatures, all Ed25519 by a host signing key: records over
doriface-mesh/1|| SHA-256(body); member cards, by the card's subject, overdoriface-mesh/1 card|| SHA-256(body). With the relay'sdoriface-relay-v1, the three prefixes keep the uses apart.
doriface-host pairopens one pairing offer (replacing any pending one) and prints a QR code, the link, the typed code, the fingerprint, the hostId and the expiry. Without--web-origin, the link is the desktop app's deep linkdoriface://pair#h=<hostId>&k=<noiseStaticPub b64url>&s=<signPub b64url>&p=<link secret b64url>&r=<relay url>(exactly these five keys, once each), and the printed text says it opens in the desktop app. With--web-origin <url>, the link is<web origin>/pair#h=…&k=…&s=…&p=…&r=…and the printed text says it opens in a browser. The QR code is for a phone, which has no app fordoriface://, so it always encodes the web form with the same fragment:<web origin>/pair#…, onhttps://app.doriterm.com(the hosted web app, #700, #747) unless--web-originnames another. The desktop app's offer (GET/POST /v1/pairon the loopback gateway) carries the same pair aslinkandphoneLink, and its dialog's QR code encodesphoneLink. Both forms carry the same fragment, anddoriface-host connectandmesh joinaccept either. The fragment never reaches a server. The link secret is 32 random bytes (43 base64url characters without padding). The desktop app opens the deep link form and keeps a click on its web origin's pairing page (https://app.doriterm.com/pair#…) inside the app; every client moves the fragment into memory and out of the URL and history before it renders or dials anything.doriface-host mesh pairopens the same kind of offer for a machine join: its link adds&m=1(the web form with--web-origin, otherwise the samedoriface://pair#…deep link), and the offer admits a host into the mesh (see "Mesh") instead of pairing a device. The printed text says the link is amesh joinargument, not a page to open. A device pairing on a mesh offer, or a join on a device offer, is closed with 4401 before any answer. A typed-code join the host refuses before any answer for any other reason (no live offer, an expired one, a slot that is not the offer's, or the plan's refusal) is closed with 4411 instead, so a joiner holding a typed code, which cannot say which offer it opens, pairs as a device only on that 4401 (#1492). On a mesh offer, success stores no device: the inviting member shows the joiner's name, hostId and fingerprint and admits it only after approval on that member (its terminal, or a client device paired to it), unless the offer was opened with--auto.- A paired-device store never holds a key that belongs to a mesh member or a revoked mesh member (their Noise key or the device key their card names).
- An offer lives 10 minutes and is single use: the first pairing that completes, by either path, burns the code and the link secret together.
- Typed code: 8 characters from the Crockford base32 alphabet
0123456789ABCDEFGHJKMNPQRSTVWXYZ, displayed asXXXX XXXX. Input is normalized: uppercase, spaces and-dropped,Oread as0,IandLread as1. The first 3 characters are the relay pairing slot; the last 5 are the secret (2^25 values), which never leaves the two devices and is never sent in any form an observer can test offline. - While the typed code is open, the host's relay uplink registers the slot with a PAIR_SLOT control frame (see "Relay"). A client that has only the typed code calls
GET /v1/pair/<slot>and gets{hostId, noiseStaticPub, signPub, expiresAt, slotSig}:hostIdis the 26-character lowercase base32 string defined above, the two public keys andslotSigare base64url strings without padding, andexpiresAtis the offer's expiry in ms since the epoch (a JSON integer, at mostNumber.MAX_SAFE_INTEGER).slotSigis the host's Ed25519 signature, bysignPub, over the slot statement"doriface-pair-slot-v1" || slot (3 ASCII) || noiseStaticPub (32) || expiresAt (u64 BE)(v1.9, #22). That answer is untrusted; the client checks thathostIdmatchessignPub, thatslotSigverifies for the slot of the code it typed, and thatexpiresAtlies between its own clock minus 10 minutes and its own clock plus the offer TTL plus 10 minutes, then the person confirms the fingerprint, and the PAKE below authenticates it. A v1.9 client refuses an answer withoutexpiresAtandslotSig("this host did not sign its pairing key: it or its relay is older than v1.9"), and one with only one of them, or either out of shape, as malformed; the QR code and link still pair. The relay answers each PAIR_SLOT with a PAIR_SLOT_ACK (see "Relay"); on a collision the host draws a new code and registers again. A QR/URL pairing already carries hostId and keys, so it skips the slot lookup. - Failed typed-code attempts: the host counts every typed-code attempt it answers (see "Session kinds" below) and persists the count with the offer. After 10 answered attempts it retires the typed code: it clears its relay slot and answers no further typed-code attempt (4429). The link secret stays valid until the offer expires. Each answered attempt tests exactly one guess, so an attacker's chance to learn a code is at most 10 in 2^25 per offer, whatever the relay does. Attempts that the host refuses before answering are not counted. Anyone who can make 10 answered attempts (through the relay's budget below) can retire a code but cannot learn it; the remedy is the QR/link or a new code.
- On success the host appends
{clientStaticPub, name, pairedAt}to its paired-devices store and burns the offer. The offer is burned before the device is stored, so a failed store never leaves it usable. - Revoking a device removes it from the store and closes its live sessions.
The app that runs a host asks it for the offer it would otherwise print (v1.9.5), so a person can pair a phone without a terminal. These two routes sit on the host's plaintext listener beside /v1/hc, behind the same per-launch token presented as Authorization: Bearer <token>; a request without it is answered 401 and nothing else. The LAN listener does not serve them: it serves only /healthz and /v1/e2ee. A host started without a state directory (no identity, no pairing store) serves neither route.
-
GET /v1/devicesanswers this computer's paired devices in the shape the pair route names one with:{"devices":[{"name":"…","id":"…","pairedAt":"…"}]}, and{"devices":[]}when none is paired. -
DELETE /v1/devices/<id>revokes the device whose 8-character id this is (v1.9.6) and answers{"revoked":[{"name":"…","id":"…","pairedAt":"…"}]}. It is the same act asdoriface-host devices revoke: the device leaves the store, its live sessions close with 4401, its push subscription is dropped, and its key is refused on every path from then on. An id no device has is answered 404 with{"error":"…"}, and an id two devices share is answered 409 with the same shape and the instruction to revoke one by its full fingerprint from the terminal (this route takes the short id only). Both routes sit behind the same per-launch token as/v1/pair, and the LAN listener serves neither. -
POST /v1/pairopens one offer, replacing any pending one, and answers it:{"state":"pending","offer":{…}}. -
GET /v1/pairanswers what stands: the samependingshape,{"state":"paired","device":{"name":"…","id":"…","pairedAt":"…"}}(or"device": nullwhen the store names none),{"state":"expired"}, or{"state":"none"}when this host opened none since it started. -
The offer is
doriface-host pair's, unchanged:codeis the 8 characters unformatted,linkandopensare the artifact the form above describes (a deep link reads"desktop", a<web origin>/pair#…link reads"web"),hostIdis the 26 characters,fingerprintis the 10 groups of 4, andexpiresAtis the offer's expiry in ms since the epoch.slotis the typed code's relay slot as the host knows it (pending,registeredorunavailable), andcodeUsableis false once that code is retired or has no slot, which leaves the link and QR code working. -
A live offer reads
pending. An offer that disappeared before its expiry was burned by a completed pairing (see "On success"), so it readspairedand names the newest device recorded since that offer opened; itsidis the 8 uppercase hex characters thedevicescommands accept. Nothing new is written to decide this, and no route here changes the handshake, the relay or an offer's lifetime.
The first message a client sends on every session (relay or direct) starts with one kind byte:
| kind | Name | Rest of the first message | Noise protocol | Prologue |
|---|---|---|---|---|
0x01 |
session | Noise message 1 | Noise_IK_25519_ChaChaPoly_BLAKE2s |
doriface/1 || hostId || 0x01 |
0x02 |
pair-code | sid (16) || Ya (32) || Noise message 1 |
Noise_IKpsk2_25519_ChaChaPoly_BLAKE2s |
doriface/1 || hostId || 0x02 || sid || Ya |
0x03 |
pair-link | Noise message 1 | Noise_IKpsk2_25519_ChaChaPoly_BLAKE2s |
doriface/1 || hostId || 0x03 |
doriface/1 is its 10 UTF-8 bytes and hostId its 26 ASCII characters. Any other kind byte, or a first message outside its kind's size bounds, is closed with 4400 and never answered. The host's first message is Noise message 2, preceded for kind 0x02 by the host's CPace share Yb (32 bytes). The client's first transport record after message 2 has an empty plaintext; it confirms the keys, and the host stores a paired device, or releases IK early data, only after decrypting it. lv_cat and prepend_len are as in draft-irtf-cfrg-cpace-21 section 6.3 and Appendix A.1: each field is prefixed with its length in LEB128 and the results are concatenated.
A v1.2 first message is never answered. It has no kind byte, so its first byte is the first byte of a random ephemeral key: an unknown kind, or a message outside the kind's size bounds, is closed before any crypto; a v1.2 message that passes the size bounds of kind 0x02 or 0x03 fails message-1 authentication under the v1.3 prologue; one that starts with 0x01 fails message 1 because the IK prologue now ends in 0x01. Each is closed with 4400.
- Session (
0x01): withstreamabsent or"hc", the host admits a current mesh member's Noise static key (an hc line; every hchello'score.idmust be that member's cardhcId) or a key in its paired-devices store, checked in that order. It refuses a key of a revoked mesh member, and on the device path any device session whose hchelloclaims a member'shcId(4401). The host reads the plain hc lines of these sessions until thehellothat switches the connection to frames, and nothing after it: each line must be a JSON-RPC 2.0 request of at most 4096 bytes including its LF, using only well-formed strings and integer literals of at most 15 digits, the first line must be ahellowith anid, and ahello'sparamsmust be valid for hc (generationabsent,nullor1); otherwise the session is closed with 4400. Withstream:"mesh"it admits only a current mesh member (4401). These sessions are accepted on the direct path too. A relay session opened with?paircarries only pairing; kind0x01on it is 4401. - Pair-link (
0x03, the QR/URL path): psk = HKDF-SHA512(ikm = link secret, salt = empty, info = lv_cat(doriface/1.3 pair-link psk, UTF-8 hostId, noiseStaticPub), 32 bytes). The client dials an ordinary relay session (no?pair), or the direct path. - Pair-code (
0x02, the typed path): CPace, cipher suite CPACE-RISTR255-SHA512 of draft-irtf-cfrg-cpace-21 (section 8.3), initiator-responder mode with the client as initiator A and the host as responder B:- PRS = UTF-8 of the 8 normalized code characters.
- CI = lv_cat(
doriface/1.3 CPace pair-code,A=device,B=host, UTF-8 hostId, noiseStaticPub, UTF-8 slot). - sid = 16 random bytes chosen by the client per attempt; ADa = ADb = empty; transcript = transcript_ir. Because the client chooses sid, an attacker can precompute the generators of every code for a sid of its choice; that makes each online attempt cheaper to compute but adds no attempt and allows no offline test.
- Generator, scalar sampling (32 random bytes, the top 4 bits cleared, zero redrawn),
scalar_mult_vfy(an invalid or identity encoding aborts) and ISK are exactly as the draft specifies. K is never exposed. - psk = HKDF-SHA512(ikm = ISK, salt = empty, info =
doriface/1.3 pair-code psk, 32 bytes), used as the IKpsk2 psk, which Noise mixes after thesetoken of message 2. - The host accepts kind
0x02only on a relay session opened with?pair=<slot>whose slot belongs to its live, unretired offer. On the direct path or on an ordinary relay session it closes with 4401 without answering; for another slot it closes without answering with 4401, or with 4411 for a refused mesh join (see Pairing). Before answering it checksYaand message 1, then records the attempt durably. If the host cannot record the attempt it closes with 1011 and answers nothing. Reaching 10 retires the code for new attempts; sessions the host has already answered may still complete.
Message sizes: a client's first message is at most 4449 bytes for kind 0x01, 401 for 0x02 and 353 for 0x03. The host's first message is at most 304 bytes (336 for 0x02).
- Every handshake payload starts with one JSON line: a UTF-8 JSON object followed by LF (0x0A), at most 256 bytes including the LF, whose
vmember is the number1. Receivers ignore unknown members. A payload that breaks a rule below fails the handshake with 4400. - Message 1 may carry
stream. On a session (0x01): absent or"hc"(the plaintext after the handshake is thehc connectbyte stream; up to 4096 early stream bytes),"mesh"(the mesh stream; no early bytes, else 4400) or"push"(a device's push stream, see "Push stream"; no early bytes, else 4400). On a pairing (0x02,0x03): absent (a device pairing) or"mesh"(a machine join). Any other value, or"hc"or"push"on a pairing, is 4400. - Message 1 of a pairing:
{"v":1,"name":"<name>"}or{"v":1,"name":"<mesh name>","stream":"mesh"}and nothing after the line. A device name is checked after trimming leading and trailing white space (ECMAScriptString.prototype.trim): the trimmed name is 1 to 64 UTF-16 code units, well-formed (no lone surrogates), and contains no character of the Unicode categories Cc, Cf, Zl or Zp, otherwise the handshake fails with 4400. The host stores the trimmed name. A mesh name follows herdr-core's machine-name rule: 1 to 32 characters ofa-z,0-9,-,_,., starting with a letter or digit, and not shaped like a terminal id (tfollowed by1-9and then only0123456789bcdfghjkmnpqrstvwxyz). - Message 2 (every kind):
{"v":1,"lan":[...]}and nothing after the line.lanholds at most 8 strings, eachws://<IPv4 literal or bracketed IPv6 literal>:<port 1-65535>/v1/e2eethat parses as a WHATWG URL; never a host name. The host sends the longest leading run of its LAN URLs that keeps the line within 256 bytes. A client refuses the whole reply if any entry breaks this rule. - A handshake that has not completed within 10 s is closed with 4408, and so is one that buffers more than 4 MiB of unread bytes.
| Path | Where the client gets the host's static key | What a malicious relay can do |
|---|---|---|
QR / URL (0x03) |
the URL fragment, which never reaches a server | Nothing beyond sizes and timing. It cannot read message 1 (it is encrypted to the real host key), and the psk comes from a 256-bit secret it never sees, so it has nothing to test, online or offline. |
Typed code (0x02), honest lookup |
the relay's GET /v1/pair/<slot> answer |
It sees the slot, sid, both CPace shares and the Noise ciphertexts. None of them depends on the code except through the CPace key, which needs a Diffie-Hellman value the relay cannot compute, so it cannot test a guess offline. Sessions it opens itself each give it one online guess per answer the host sends, and the host answers at most 10 per offer. |
Typed code (0x02), lying lookup |
the relay's GET /v1/pair/<slot> answer |
It cannot substitute its own Noise static key under the real hostId and signPub: the host's slotSig covers the slot and that key (v1.9). It can still answer with a complete identity of its own (its own hostId, signPub, Noise key and signature); then it can read message 1 (the device name and the device's public static key) and gets one online guess per attempt the person makes. It cannot pass the attempt on to the real host, because the PAKE is bound to the host identity and slot the client was given, and the fingerprint check, which stays, shows the person a key that is not their host's. |
So message 1 carries nothing secret, every code guess costs an answer from the real host, and the typed-code UI keeps the fingerprint confirmation step.
Residual risk: a lookup answered with a relay's own complete identity is caught only by the fingerprint check, as before v1.9; the slotSig removes only the variant that keeps the real hostId and signPub with a substituted Noise key (#22). A replayed signed answer names the real host's Noise key, so it gives the relay nothing unless that key was compromised and later rotated, within the expiresAt window. Rollback is asymmetric: reverting the relay to a build before v1.9 while v1.9 clients are out denies typed-code pairing to everyone (the QR code and link still pair), so the relay rolls back only together with those clients, or after them.
- Noise transport messages use ChaCha20-Poly1305 (
@noble/ciphers, synchronous) with 64-bit counter nonces as the Noise spec defines. - Maximum plaintext per message: 65519 bytes. The sender chunks larger stream writes; the receiver concatenates in order.
- Rekey (Noise
REKEY()) every 2^20 messages per direction. The noncenis not reset at rekey. - Any decryption failure closes the socket with code 4400. No reordering is tolerated, because WebSocket is ordered.
- A client whose socket dropped resumes its session over a new socket when both sides still hold its position (see "Session resume"); otherwise a reconnect runs a fresh IK handshake (1 RTT; msg1 may carry the first stream bytes).
- API:
secureLink(link: ByteLink, opts): Promise<SecureLink>for the initiator and responder roles.ByteLinkis@doriface/client's interface (send(bytes),onData(cb),onClose(cb),close()), andSecureLinkis aByteLinkthat also exposes the authenticated remote static key.
A session outlives the socket it runs on. Each side counts the transport records it has sent and opened since the handshake, and keeps the records it sent in a ring of at most 1 MiB. When a session's socket closes with anything but a close its peer meant (a normal close, 1000, or going away, 1001, which a host sends as it shuts down), and the session's owner allows it, the session detaches instead of ending: the host keeps the session and its hc connect for 120 s after it noticed the drop, and the client dials the host's path again (the relay, or the direct address) for up to 60 s.
- Identity:
id (16) || mac key (32)= HKDF-BLAKE2s(salt = handshake hash, ikm =doriface-resume-v1, 64 bytes), the id being the first 16 bytes of the first output. Only the two ends know the handshake hash, so only they can name or prove the session; the relay sees the id in the clear and can therefore tell that a new session continues an earlier one, which it could already mostly tell from the source and the timing. - Request (the client's first message on the new socket, in place of a handshake):
0x04 || id (16) || sent (u32 LE) || received (u32 LE) || HMAC-BLAKE2s(mac key, "resume-request" || id || sent || received)= 57 bytes.sentandreceivedare the client's record counters.0x04is not a session kind: a handshake that starts with it is refused as an unknown kind, as before. - Answer (the host's first message, which makes the relay session active):
0x04 || sent (u32 LE) || received (u32 LE) || HMAC-BLAKE2s(mac key, "resume-answer" || id || client sent || client received || host sent || host received)= 41 bytes, the host's own counters, bound to the request. Then the host sends the records numbered from the client'sreceivedon, and the client, once it has checked the answer, the records numbered from the host'sreceivedon. Each side opens them with the same transport state as before: the same keys, the same nonces, so a record delivered twice or out of order fails as it always did (4400). - A side joins the other's position only when the other has sent at least what this side opened, has opened no more than this side sent, and what it opened is still in this side's ring. Otherwise the host refuses (it closes the new socket with 4413 and answers nothing; the session stays as it was) or the client gives the session up (it closes the new socket with 4413), and the client opens a new session with a fresh handshake at once, as a drop did before v1.11: 4413 is final for that session, since another dial meets the same position. A host from before v1.11 knows no
0x04and closes the request with 4400, as it closes any unknown session kind; the client takes 4400 as final too and opens a new session at once, as a drop did before. - The host accepts a resume while its side of the old socket is still open (a client whose socket died under it without the relay noticing): it closes the old socket with 1000 and carries on over the new one. A session ends with 4408 when a record it sent while detached leaves its ring, since the peer can never have opened that record and the session can no longer be resumed exactly. Older records leaving the ring end nothing: once a session has sent more than its ring holds, every record it sends pushes one out, and those the peer opened before the drop are not needed; the resume exchange checks the peer's position against what the ring still holds. A session's owner that never allowed a resume (the mesh and push streams, a pairing) keeps v1.10 behaviour: a dropped socket ends it.
- What a resumed client sees: nothing happened. Its
terminal.attachstreams, feeds and calls are the same ones, so no screen is reset or replayed; output the host produced meanwhile arrives as the records it missed, in order, once. What it sends while detached (keys typed) goes out in order once the session is carried on. - The relay needs no change: the request is a pending session's first message, well under the 64 KiB a pending session may send, and the answer is the host's first DATA on it.
- Default public relay:
https://relay-doriface.omo.dev. The relay implementation is a separate private service; this section is its public contract, and any server that implements it can stand in. GET /healthz->{ok:true, version}; a v1.6 relay addspasses("on","off"or"misconfigured") and, when on,kidandaccepted.- Host uplink:
GET /v1/host/<hostId>(WebSocket). The relay sends a 32-byte random challenge as the first binary message. The host answers withsignPub(32) || Ed25519-signature(64)over"doriface-relay-v1" || relayOrigin || hostId || challenge, whererelayOriginis the exactwss://host[:port]the host dialed. The relay rebuildsrelayOriginfrom its own request URL and checks the signature and thathostIdmatches signPub; otherwise it closes with 4403. Binding the origin stops a second relay from replaying a challenge from this one. One uplink per hostId; a newer authenticated uplink replaces the old one, which the relay closes with 4409, and the old uplink's client sessions are closed with 4404. - Client:
GET /v1/client/<hostId>(WebSocket). There is no relay-level auth (E2EE authenticates). An offline host closes the socket with 4404. A typed-code pairing session adds?pair=<slot>: the relay charges it to that slot's pairing budget, refuses it with 4410 when the slot is not registered to this hostId, and sends the host an OPEN whose payload is the 3 slot characters (an ordinary OPEN has no payload). A QR/URL pairing is an ordinary session. - A client may open up to 3 sockets for one session at once and keep the nearest (#1351): it sends each a
pingas soon as it opens, keeps the socket whosepongcame back soonest, and closes the others with 1000 before sending them anything, so no Noise message ever reaches more than one. The relay needs no change: each socket is an ordinary pending session (an OPEN, then a CLOSE, sent to the host) and counts against the pending cap and the per-source upgrade rate until it closes. Pairing sessions (?pair) and dials that carry a proof open one socket, because their upgrades are charged to a slot or a key; so do sessions that carry one request and close (a push request, a pairing by link, a mesh join). To a relay on the default HTTPS port the second and third sockets dial ports 8443 and 2053, which the edge serves the same way: a browser opens a WebSocket to an address and port only once the one before it to the same address and port has finished connecting, so on one port the three would open in turn and the later ones would miss the race (#1418). A relay self-hosted on port 443 should serve those two ports too, or refuse them (a reset, not a silent drop); a socket still opening is waited for only 150 ms past the first socket's answer or refusal, so a dropped port costs a session at most that (#1437). - Session admission: a client session counts against the 32-session cap only after the host has sent its first DATA on it. Before that it is pending: at most 8 pending sessions per host, with 10 s to the host's first DATA (else close 4408). When the pending cap is full, the relay evicts the pending socket from the source IP that holds the most pending sockets. The host enforces both caps on its uplink too, whatever the relay sends: it answers an OPEN with CLOSE 4429 while 8 of its sessions are pending, and that session allocates nothing; a pending session whose first DATA would be a 33rd active one is closed with 4429 instead of sending it. Connections are also rate limited per source: 60 WebSocket upgrades that carry no valid pass proof (host uplinks and client sessions together) per source per minute, the 61st refused with 4429 (an upgrade with a valid proof is charged to its host key instead; see "Relay passes"), and 20
GET /v1/pair/<slot>lookups per source per minute, the 21st refused with HTTP 429. - One Durable Object per hostId (
idFromName(hostId)), using the WebSocket Hibernation API. Socket attachments carry{role, sessionId}. - Relay <-> host multiplexing frame:
[type u8][sessionId u32 LE][payload].- 1 OPEN: no payload, or the 3 slot characters for a pairing session.
- 2 DATA: opaque bytes.
- 3 CLOSE: payload = u16 LE close code.
- 4 PAIR_SLOT (host to relay only, sessionId 0): payload =
slot (3 ASCII) || noiseStaticPub (32)= 35 bytes, or (v1.9) the signed formslot || noiseStaticPub || expiresAt (u64 BE, ms, at most 2^53 - 1) || slotSig (64)= 107 bytes; any other length, or a largerexpiresAt, is malformed (status 2). A payload whose first 3 bytes do not spell a slot (Crockford base32,[0-9A-HJKMNP-TV-Z]), including one shorter than 3 bytes, has no slot to name in an ACK, so the relay closes the uplink with 4402 instead. The relay storesexpiresAtandslotSigas sent, without verifying them, and returns them in the lookup; for a 35-byte registration it omits both fields. A v1.9 host sends every registration in the signed form first, and when the relay answers status 2 it sends that one request again in the 35-byte form, so a relay updated later gets the signed form at the host's next registration. An empty payload clears the host's slot: the relay releases it and answers PAIR_SLOT_ACK status 0 with the released slot's characters (a clear when the host has no registered slot gets no PAIR_SLOT_ACK, since there is no slot to name); the host sends it when the offer ends and when it retires the typed code, and waits up to 10 s for that ACK before its next PAIR_SLOT, as it does for a registration. - 5 PAIR_SLOT_ACK (relay to host only, sessionId 0): payload =
status u8(0 registered, 1 slot taken by another host, 2 malformed) followed by the 3 slot characters. A host that gets status 1 draws a new code and sends PAIR_SLOT again. - 7 PASS (sessionId 0, only on an uplink that dialed
?pass=1): relay to host,relayNowMs u64 BEfollowed by a 58-byte pass, or the 8-byte clock alone when the relay has no pass to give; host to relay, an empty payload (a pass request). See "Relay passes". - 6 CREDIT (both ways, only on an uplink that dialed
?credit=1): payload = u32 LE count of that session's bytes the sender's consumer took since its last CREDIT. See "Session credit".
- The relay assigns sessionIds. Client <-> relay messages are the raw opaque bytes, with no header.
- Pairing budget: at most 10
GET /v1/pair/<slot>and 10 pairing sessions (client connections with?pair=<slot>) per slot per 10 minutes (429 / 4429 beyond). Ordinary sessions are never charged to a slot. - Per-source pairing quota: each source IP may make at most 3
GET /v1/pair/<slot>lookups and open at most 3 pairing sessions per slot per 10 minutes; a refused lookup gets HTTP 429 and a refused session is closed with 4429, the same responses as the slot budget. The slot's session budget is charged only when the host has answered the session's pairing message (its first DATA on that session); a session the host closes without answering is not charged. A single source therefore cannot drain either budget alone. Many independent sources still can, which denies typed-code pairing for that code but never reveals the secret, so the remedy is the QR/link or a new code. The host's own limit of 10 answered attempts per offer (see "Pairing") holds even against a relay that ignores these budgets. - Source: the relay takes a connection's source address from the
cf-connecting-iprequest header (Cloudflare sets it; a stand-in must honour it, because the public suites send it to act as distinct sources). The source key is the IPv4 address itself (an IPv4-mapped IPv6 address::ffff:a.b.c.dcounts asa.b.c.d) and the /64 prefix of an IPv6 address, however the address is written, so one IPv6 subscriber cannot mint a fresh bucket per address. An address that does not parse is keyed as given. A request without the header is keyed asunknown, so all such requests share one bucket of every per-source limit. Every per-source limit and quota above uses this key. - The relay never decrypts, never logs payloads, enforces a 1 MiB message cap, and forwards immediately with no batching.
Any number of hosts may share one source address; a host's relay upgrades are limited per host key, never per address.
- Getting a pass: a host dials its uplink with
?pass=1. With passes enabled, the relay's first frame after a successful challenge, before any OPEN, CREDIT or PAIR_SLOT_ACK, is one PASS frame:relayNowMs u64 BE || pass(66 bytes), orrelayNowMsalone (8 bytes) when its key store did not answer. A relay that does not serve passes ignores?pass=1and sends none. The host sends a pass request (an empty PASS) only on an uplink that has already received a PASS frame of either form; the relay answers with a PASS frame at most once per 60 s per uplink. A PASS frame on an uplink that did not dial?pass=1, or a non-empty request, is 4402. - Pass (58 bytes):
version u8 (1) || kid u8 || issuedAt u32 BE (unix s) || expiresAt u32 BE (unix s) || hostIdHash (16) || mac (32), wherehostIdHashisSHA-256(signPub)[0..16]andmacis the relay's HMAC-SHA256 over"doriface-relay-pass-v1" || relayOrigin || pass[0..26]with a key only the relay holds.expiresAtis 30 days afterissuedAt. Hosts read the fields; the MAC is opaque to them. - The host checks every PASS frame (length, version,
hostIdHashequal to its own,expiresAtafterrelayNowMs), keeps the newest pass per relay origin in its state dir withoffsetMs = relayNowMs - localNow, asks for a new one when it has none or its pass is older than 24 h (retrying every 65-75 s while it has none), and presents a pass only while it has more than 60 s left. - Proof: every relay upgrade by a host holding a pass adds
?proof=<base64url, no padding>ofversion u8 (1) || pass (58) || signPub (32) || ts u64 BE (relay ms, localNow + offsetMs) || nonce (16) || signature (64). The signature is Ed25519 by the host key over"doriface-relay-proof-v1" || relayOrigin || 0x00 || role || 0x00 || target || 0x00 || proof[0..115], whereroleishost(uplink) orclient(session) andtargetis the hostId in the path; forhostit must be the prover's own hostId. - The relay checks, before any Durable Object: length and versions, an accepted kid,
now < expiresAt,|ts - now| <= 120 s, the MAC,hostIdHash, the signature, and that the proof was not seen before (per target, for at least 360 s). A valid proof is charged to a per-key limit (60 upgrades per minute per host key, both roles) instead of the per-source one, and a proven host uplink still answers its challenge. Any failed check closes the upgrade with 4412 and charges the source one per-source token; the close code never depends on that budget. A relay whose key store does not answer treats the proof as absent. - On 4412 the host marks its pass unusable and asks its uplink for a new one; a session dial waits up to 2 s for it and redials once under the same dial-budget grant, with a proof if one arrived. A refusal of an older pass, one the host no longer holds because a newer pass arrived while that dial was open, marks nothing and asks for nothing: the dial redials at once with a proof built from the newer pass, so it costs no wait and stays on the per-key limit. A 4412, and a 4429 on that unproven redial, are no gate and no halving for the dial budget. An uplink that got 4412 reconnects at once without a proof. A 4429 on an uplink attempt without a proof (a brand-new host whose address is busy) waits 30-60 s. Refusals of the same pass count once; after 3 consecutive refusals of freshly received passes a host stops presenting proofs to that relay for 10 minutes. A 4412 on an upgrade that carried no proof is not a pass refusal: an ordinary failure, nothing marked, no redial.
- Pending eviction groups a proven session by its host key and any other session by its source, so an unproven flood from a member's own address evicts the flood. The per-source pairing quotas stay per source.
- What this adds to what the relay sees: for a proven session, the dialing host's hostId (so the relay can see which host dials which). Web clients and device sessions send no proof and stay as anonymous as before. A relay that logs request URLs would log proofs; the reference relay does not, and its own log lines carry a pseudonym of the source, never a proof, a pass or an address. The reference relay keeps anonymous daily counts and, as its only per-host rows, each month's mesh pool pseudonyms until day 7 of the following month (below): it adds each authenticated hostId, each hostId that gets a client session, and the source address (IPv4, or IPv6 /64) of each session dialed without a proof to a HyperLogLog sketch as an HMAC under a monthly salt. It never writes a key, a hostId or an address, destroys each salt with its sketches on day 7 of the following month, and keeps only the daily, weekly and monthly totals. Someone holding the relay's store could still test whether a hostId or address they already know was seen on one of the last 7 days, or at all in a given month until day 7 of the second month after it (about 5 weeks after that month ends); once the salt is gone, nothing links the totals to anyone. It also groups keyed hosts into mesh pools: when a proven session joins two hosts, both become pseudonyms (an HMAC of the hostId under the month's salt) in one group, and the pair itself is not kept. Those groups are deleted with the month's salt, and only counts leave them: the number of pools of two or more hosts, single-host pools, pools with a host seen in the last 7 days, hosts in pools and all keyed hosts, the minimum, median and maximum hosts per pool, and how many pools have 2, 3, 4, 5 to 9, and 10 or more hosts. A month's pool rows are deleted with that month's salt on day 7 of the following month, about 1 week after the month ends (sooner than the sketches above, which a later month's shadow sketch keeps testable for about 5 weeks). Until then, someone holding the relay's store can also tell whether two hostIds they already know were in the same pool that month, and, for the last 7 days only, the first and last day each was seen; they cannot learn which host dialed which, or in what order. The reference relay sends its daily totals, pool counts included, to its operator's product analytics (PostHog) as one event per day with a fixed relay identity, numbers only: no key, hostId, address, pseudonym or device name.
These four text messages are the only ones allowed on relay sockets (c: only toward a client that dialed ?credit=1); everything else must be binary:
| Message | Sender | Meaning |
|---|---|---|
ping |
client or host, every 30 s | keepalive |
pong |
the relay, via setWebSocketAutoResponse (no Durable Object wake-up) |
keepalive reply |
a:<total bytes received> |
the receiver of relay traffic (client or host uplink), every 64 KiB | flow-control acknowledgement |
c:<bytes> |
the relay, to a client that dialed ?credit=1 |
the host consumed this many more of the session's bytes |
- Backpressure: the Durable Object keeps
sent - ackedper socket in its attachment and closes the sending side with 4408 when it exceeds 4 MiB. On a host uplink (v1.7.2) that 4 MiB holds DATA only: the relay's own frames (the challenge, OPEN, CLOSE, CREDIT, PAIR_SLOT_ACK) may use 64 KiB more, so sessions filling the window can never make the relay close the uplink. DATA that does not fit ends only its session with 4408, and that session's CLOSE still reaches the host. One session cannot take the window from the others (v1.7.3): a session is light while its DATA unacked on the uplink, the message in hand included and each frame counted with its 5-byte header, is at most 16 KiB, and a light message may use the whole 4 MiB. A heavier message may fill the window only to 4 MiB minus 16 KiB for each other session open on the uplink (at least one), so a keystroke from another session is never refused because one session filled the window. An uplink that leaves even those 64 KiB unacked is closed with 4408. Acknowledgements are cumulative and must be monotonic: ana:<n>that is not a decimal integer, is smaller than the last acknowledgement, or is larger than the bytes actually sent to that socket is a protocol error and closes the socket with 4402, so a peer cannot ack bytes it never received to make the relay buffer without bound. - Per-session bounds on the uplink (v1.7.2): a session the host has not answered yet may send at most 64 KiB of DATA (its first message is Noise message 1 with at most a 256-byte line and 4 KiB of early bytes); a byte more ends that session with 4408. A session where both ends asked for credit is ended with 4408 when it sends past its credit: more than the 512 KiB window uncredited by the host, beyond the one message a sender may send while less than one 64 KiB step is uncredited. Both are counted in DATA payload bytes, and both stop a session before it can fill the uplink's shared window; a client that keeps to its credit, and every peer without credit, is unaffected.
- Host uplink flow control: the uplink carries every session of the host, so the host acks each frame when it arrives, whether or not that session's reader has taken it. Withholding acks for one slow session would stall the whole uplink and make the relay close it, and with it every other client's session, with 4408. Each session instead bounds its own undelivered bytes: once more than 4 MiB of one session's DATA payload is waiting for its reader (exactly 4 MiB is allowed), the host closes only that session with CLOSE 4408 and drops its later DATA, still acking it. The host therefore buffers at most 4 MiB per session, so at most (32 active + 8 pending) x 4 MiB = 160 MiB per uplink; the host's own session caps (see "Session admission") keep that bound against a relay that ignores its caps.
- Session credit (v1.4): v1.3.1 keeps one slow session from stalling the uplink, but a sender still cannot see how far behind its peer's reader is, so a bulk transfer (a large
file.write, a terminal printing fast) reaches a 4 MiB bound and loses the session to 4408: the host's per-session bound one way, the relay's per-socket cap toward the client the other. Credit lets each sender keep within what the far reader has taken. The unit is a session's DATA payload bytes: the bytes a client message carries, and a host DATA frame without its 5-byte header.- Opt-in: a host uplink opts in by dialing
/v1/host/<hostId>?credit=1, a client by dialing/v1/client/<hostId>?credit=1(with&pair=<slot>when pairing). A relay that serves credit sends a credit uplink a zero CREDIT for each session right after its OPEN; that is how the host learns credit flows on that session. It sends a credit clientc:0right after accepting it, but only when the host is a credit uplink too. - Host to client: the host reports, as CREDIT frames, the DATA payload bytes its reader took, once at least 64 KiB has accumulated. The relay passes the host's credit on to a credit client as
c:<bytes>, coalesced: it sends onec:once at least 64 KiB of credit is pending, or once the host has credited every byte the relay forwarded on that session. A non-credit client gets noc:texts. - Client to host: the client's
a:<n>acknowledgements (sent at least every 64 KiB of received bytes) reach a credit uplink as CREDIT for that session, whether or not the client itself asked for credit. The relay coalesces them (v1.7.2): it sends a session's CREDIT once at least 64 KiB of acknowledged bytes have accumulated, or once the client has acknowledged everything sent to it, so a client acknowledging a byte at a time cannot fill the uplink with CREDIT frames. - The window: a sender that has seen credit start keeps at most 512 KiB of a session in flight, that is, sent and not yet credited. It holds later sends, in order, until credit returns, except that a send always goes while less than 64 KiB is in flight. Up to 64 KiB - 1 bytes may stay uncredited forever (reports come in 64 KiB steps), so a message of any allowed size (up to 1 MiB - 5 bytes) still goes. In-flight data is therefore at most max(512 KiB, 64 KiB - 1 + one message).
- Errors: a host CREDIT for more bytes than the relay forwarded on that session, or any CREDIT from an uplink that did not dial
?credit=1, closes the uplink with 4402. A credit client that receives ac:<n>for more than it has in flight closes its own socket with 4402. A malformedc:text is also 4402; any other text a client does not expect is 1003. - Bounds: credit adds no buffer anywhere. The host still acks on arrival and keeps v1.3.1's 4 MiB per-session bound, which a client that ignores its window (or does not opt in) can still reach; a client that honours credit keeps that session's backlog at most max(512 KiB, 64 KiB - 1 + one message). The relay keeps the 4 MiB cap on every socket, credit uplinks included, so the bounds stay 160 MiB per uplink on the host and 4 MiB per socket on the relay.
- Opt-in: a host uplink opts in by dialing
- Keepalive: an alarm reaps sockets whose auto-response timestamp is more than 90 s old, with 4408.
- Direct path: there is no relay, so the host itself answers each text
pingwith a textpong, and closes a/v1/e2eesocket with 4408 when it has received nothing (no record and noping) for 90 s. Clients sendpingevery 30 s on the direct path too.
The suites in tests/relay check a relay against this section. They start it with wrangler dev --ip 127.0.0.1 --port <port> --inspector-port <port> --local-upstream 127.0.0.1:<port> --persist-to <dir> in the relay's directory (DORIFACE_RELAY_DIR), and wait for its Ready on http://... line. The mesh suites instead pass -c <config>, a copy of the directory's wrangler.jsonc with its routes removed and main made absolute. So a stand-in is in effect a wrangler project: DORIFACE_RELAY_DIR holds a wrangler.jsonc with a main entry, and wrangler installed at node_modules/.bin/wrangler, which needs Node 22 or newer. Timeout tests start another instance with --var NAME:<milliseconds> overrides, which a stand-in must accept:
| Variable | Default | Meaning |
|---|---|---|
PENDING_TIMEOUT_MS |
10000 | a pending session's time to the host's first DATA (4408) |
IDLE_TIMEOUT_MS |
90000 | a socket with no ping for this long is reaped (4408) |
AUTH_TIMEOUT_MS |
10000 | an uplink's time to answer its challenge (4403) |
Relay passes (v1.6) are optional for a stand-in: one that ignores ?pass=1 and proof is conformant, and hosts behave as against a v1.5 relay. A conformance check can feature-detect them: dial ?pass=1, answer, send a PAIR_SLOT right behind the answer, and when the PAIR_SLOT_ACK comes with no PASS frame before it, treat the relay as v1.5. A stand-in that serves passes accepts these --var overrides, each clamped to its default as a maximum so it can only shorten:
| Variable | Default | Meaning |
|---|---|---|
PASS_TTL_S |
2592000 | a pass's lifetime; 0 issues passes already expired |
PROOF_WINDOW_S |
120 | how far a proof's ts may sit from the relay clock |
PASS_REQUEST_S |
60 | at most one PASS frame per uplink per this long |
PASS_KEYS_UNAVAILABLE |
unset | 1: every key read fails (the key-store outage path) |
- The host also serves
GET /v1/e2ee(WebSocket) on its LAN listener, speaking the same record layer without the relay header. Because every byte is authenticated, this endpoint may bind non-loopback. The plaintext/v1/hcstays loopback-only. It accepts session kinds0x01and0x03; it closes kind0x02(typed-code pairing, which needs the relay's budget) with 4401 without answering. - The direct path is off by owner decision (#2070, v1.10.3): every shipped client (web, PWA, desktop) reaches every remote host through the relay, nothing in a client names or offers a direct address, and no shipped launcher gives the host a
--lan-listen. The mechanism stays in the contract and in the code behind one internal switch, so a later decision can turn it on in one place; the next line describes that mechanism, not shipped behaviour. - The mechanism: a client may try direct (when a LAN URL is known and reachable within 300 ms) and the relay in parallel. The relay is the default; once a direct session's handshake completes, it is preferred. The session swap reattaches terminals with
resumed: true. - Before the decision, no shipped client dialed the direct path either: the Direct address setting was hidden with #458, and v0.1.0-v0.1.2 were the only releases that offered it.
A mesh is a set of hosts that trust each other fully: a host admitted by any member is reached by every member, and each member's core adds every other member as a herdr machine on its own. Mesh traffic is ordinary sessions between hosts; the relay keeps nothing about a mesh beyond its anonymous daily counts and its monthly pool pseudonyms (see Relay passes) and needs no mesh-specific behaviour.
- A mesh is a grow-only set of records
{body, sig}.bodyis an I-JSON (RFC 7493) object of at most 2048 bytes, signed and hashed as the exact bytes its signer produced; its hash is base64url (no padding) of SHA-256(body). - Body:
v(2),mesh(the mesh id;"-"only in the founding record),type(found,admit,revoke,name,rekey,ack),by(the signer's signPub),n(the signer's counter: 1 for its first record; every other record of the signer has the signer's recordn - 1in its past and no record of the signer with a counter ofnor more),prev(1 to 64 hashes of the signer's heads; empty only infound),subject, and optionallyat(display only).found,admitandrekeyembed a member card;revokenames 1 to 16 distinct signPubs;namenames a member and a mesh name. - A member card is
{body, sig}signed by its subject:{"v":1,"mesh","inviter","nonce","hostId","signPub","noisePub","devicePub"?,"name","hcId"}. In anadmit, the card names this mesh and the admitting member; in arekey, the signer's own new Noise key. A card's nonce admits once. - A host stores a record only if it is well formed and verifies, its card verifies under its subject and matches the record, its signer is a key the set admits, and it belongs to this mesh. A record whose past is incomplete waits (at most 256); a mesh holds at most 4096 records.
- On merging an
admit,revokeorrekeysigned by another member, a member signs anack(prev = its heads) in the same step.
The view of a record set is computed by the algorithm below. It reads only views of strictly smaller sets and the order of the records, so every set has exactly one view, whatever order its records arrived in. No clock takes part.
Notation. The input S is a past-closed record set containing exactly one found F. past(x) is every record reachable from x through prev. a ∥ b (concurrent) means neither is in the other's past. The canonical order is Kahn's topological order of S, smallest hash first among ready records. view(T) is this algorithm applied to the past-closed set T, and members(V) and revoked(V) are its member and revoked sets. M(x) = members(view(past(x))). gov(k in V) is k's governing admission in view V. pred(x) is the signer's record with counter x.n - 1 in past(x); where the signer merged its own fork and past(x) holds more than one, valid(pred(x)) holds only if every one of them is valid. A lineage walk that comes back to a key it already passed never reaches a stop: it is not clean (clean0 is false), it does not silence, and it excludes no voter. Comments that mention "revision 2" are informative: they name the draft rule a line was carried over from.
# Structure (revision 2, plus one line)
valid(x) = x.by ∈ M(x) and type_ok(x) and own_chain(x)
and (x.n == 1 or valid(pred(x))) # the own chain is a chain of VALID records
C(v, x) = past(v) ∩ past(x); CM(v, x) = members(view(C(v, x))) # the common past and its members
lineage(k, V, C) = the admissions on k's admitter chain in view V that lie outside C
(stop at a member of view(C), at an admission inside C, or at the found record)
# Level 0: every structurally valid concurrent revoke accuses (revision 2's accusers)
accusers0(x) = { v ∈ S : v.type == revoke, x.by ∈ v.subjects, v ∥ x, valid(v) }
voters(v, x) = CM(v, x) \ {x.by, v.by}
\ { g.by : g ∈ lineage(x.by, view(past(x)), C) ∪ lineage(v.by, view(past(v)), C) }
# the common past only (nobody can pad it); neither party, nor whoever admitted either party
# after the fork (the minter of v.by is a voter in name only: P13)
silences0(r, w) = r.by ∉ revoked(view(past(w))) and accusers0(r) = ∅
and ∀ g ∈ lineage(r.by, view(past(r)), C(r, w)): accusers0(g) = ∅ # the WHOLE lineage (P3)
testifies0(w) = valid(w) and ¬∃ r ∈ accusers0(w): silences0(r, w)
support0, saw0 = as revision 2, with testifies0
defeats0(v, x) = forks(v, x) or support0(v, x) > support0(x, v)
# Standing: a revoke may accuse only if its signer's provenance survives level 0
clean0(r, C) = ∀ g ∈ lineage(r.by, view(past(r)), C): ¬∃ u ∈ accusers0(g): defeats0(u, g)
standing(v, x) = clean0(v, C(v, x)) and ¬∃ u ∈ accusers0(v): clean0(u, C(u, v)) and defeats0(u, v)
# Level 1: what the view uses
accusers(x) = { v ∈ accusers0(x) : standing(v, x) }
voters1(v, x) = voters(v, x) \ v.subjects # a batch's mates do not vote on the batch
silences(r, w) = accusers(r) = ∅ and ∀ g ∈ lineage(r.by, view(past(r)), C(r, w)): accusers(g) = ∅
# no "r.by already revoked in past(w)" escape: the attacker makes that true itself
testifies(w) = valid(w) and ¬∃ r ∈ accusers(w): silences(r, w)
verdict(v, x) = defeated if forks(v, x) or support(v, x) > support(x, v)
= tie if x.type ≠ revoke and support(v, x) = support(x, v) = 0 # fail closed
= stands otherwise
own(x) = invalid if ¬valid(x); defeated if ∃ v ∈ accusers(x): verdict(v, x) = defeated;
tie if ∃ v: verdict(v, x) = tie; else clear
status(x), in canonical order:
found → eff
own(x) ∈ {invalid, defeated} → void
x.type == revoke → void unless every g ∈ lineage(x.by, view(past(x)), ∅) has own(g) ∈ {clear, tie}
# a revocation survives uncertainty on its lineage; a defeated lineage voids it
otherwise → void unless status(gov(x.by in view(past(x)))) == eff
else → tie if own(x) == tie, else eff
eff = { x : status(x) == eff }; return membership(S, eff) # membership() as revision 2
# Unchanged from revision 2
forks(v, x) = some counter n names one record of x.by in {x} ∪ past(x) and another in past(v)
own_chain(x) = every record of x.by in past(x) has a counter < x.n, and x.n - 1 is one of them (x.n = 1: none)
saw(p, a, b) = ∃ w ∈ S, w.by == p, a ∈ past(w), b ∉ past(w), testifies(w) # saw0: with testifies0
support(a, b) = |{ p ∈ pool : saw(p, a, b) and not saw(p, b, a) }|
# pool = voters1(v, x) of the conflict at level 1, voters(v, x) at level 0 (same pool both ways)
type_ok(x, V) = admit: (subject ∉ V.members, or the card's noisePub == V.noise[subject])
and the card's noisePub ≠ V.noise[k] for every k ∈ V.members, k ≠ subject
name: subject ∈ V.members
rekey: by == subject, and the card's noisePub ≠ V.noise[k] for every k ∈ V.members, k ≠ subject
revoke: every subject is the subject of some found/admit in past(x)
ack: true
membership(S, eff):
for each key k admitted in S:
gov(k) = the first record in canonical order among eff found/admit of k
that has every eff revoke of k in its past # re-admission follows every revoke
members = keys with a gov, ordered by the canonical position of gov; every one is a member
(no member cap since v1.10; the 4096-record log bounds the set)
revoked = keys with no gov and at least one eff revoke
noise[k] = the card of the latest eff rekey by k with gov(k) in its past, else gov(k)'s card
(latest = no other such record in its future; ties: smallest hash)
name[k] = the latest eff name about k with gov(k) in its past, else gov(k)'s card name;
then, in member order, a name already taken gets the section 7.4 fallback
admitter[k] = gov(k).by # lineage (H2)
- Both directions of one conflict use the same pool, the voters of (accuser v, accused x):
votersat level 0 andvoters1at level 1. The revoke lineage walk instatusis taken hop by hop: it starts at the governing admission of the revoke's signer inview(past(x)), and each later hop looks up the governing admission of the previous admission's signer in the view of that admission's own past (view(past(g)), the view it was written under), not in one fixed view. A key with no governing admission on the way voids the revoke, and the walk goes all the way to the founding record. - A conflict that no independent member present at the revoked key's last own record can decide is resolved fail-closed: the revoked key's admits and other non-revokes fall, and its revokes stand.
- A member's Noise key comes from its admission's card or a later
rekeyit signed; an admit never changes a current member's key, and no admit or rekey takes another current member's key (a twin). Twins written in concurrent branches both passtype_ok; a host resolves them when it authorizes: a Noise key that the effective cards of more than one signing key name (two members, a revoked member's card from before its revoke, or another member's superseded key) authorizes nobody; a card the view ignores (void, or signed after its signer's revoke) contests no key, and an inviter refuses a new signing key that presents such a key. A member's governing admission is the first effective one, in canonical order, that follows every effective revoke of it. Its admitter is that admission's signer (the lineage). At most 12 members: members past the twelfth in canonical order are over-cap, are not dialed and cannot sign. - Upgrading to a host that enforces the twin rule (#90): a twin admit or rekey stored before the upgrade (an honest host has written none since #56; before it, only with hand-edited host keys) is void from the first write after it, and, as for any void record, so is every later record of its signer. A host that signer admitted after its twin is then no longer a member and joins again through another member.
doriface-host mesh join <url|code>runs the pairing handshake as the client with the host's own Noise key andstream:"mesh"; the member sends{"t":"offer","mesh","inviter","nonce"}, the joiner answers{"t":"card",...}, the member admits after approval and sends the whole set asrecordslines of at most 256 KiB and a final{"t":"done","mesh"}. A host that is already a member with the same Noise key gets the welcome only, from any member; with another Noise key it is refused. The joiner checks the founding record against the mesh id, that the member it dialed is in the view with the key it authenticated, and that it is itself a member of the view with its current Noise key (whoever admitted it), before it stores anything.- Sync sessions (
0x01,stream:"mesh") are opened on demand (to push, after this host's own outage, and every 10 minutes as a safety net) and closed after 60 s idle. Lines:hello(heads and counters),want,records,done; at most 256 KiB each. Each side answers everyhellowith the records the hello's heads lack and adone, even when it sends no records. After sayinghello, a side closes the session with 4400 when 30 s pass without arecordsordoneline from the peer; an answer that keeps delivering is never cut. - Every mesh stream line is one UTF-8 JSON object with a string member
t, terminated by LF and at most 256 KiB including the LF. A receiver ignores a line whosetit does not know. A line that is longer, is not a JSON object with a stringt, or lacks a member its knowntrequires closes the session with 4400, and so does a line of a knowntthat the receiver's step does not take (during a join, the member takes onlycard, thenrefused; the joiner onlyofferorrefused, thenrecords,doneorrefused) and a reader more than 256 lines or 4 MiB behind. A joiner closes with 4400 a welcome of more than 4096 records or more than 8 MiB of record bytes. A host that refuses a join, a member card or a mesh stream from another mesh first sends{"t":"refused","reason":"<text>"}(the reason is for display only) and then closes with 4401. - Every member's core adds every other member with
machine.add --via '<doriface-host> connect --mesh --state-dir <dir> <hostId>'; the running host dials each such line with its own Noise key. A host keepsmachine.listequal to the view and handles herdr'sname_takenwith the fallback names<name cut to 31-k>-<first k hostId characters>, k = 4, 8, 12. - Dialing: a host starts at most 12 relay upgrades per 60 s for the mesh (sessions on the direct path are not counted), does not redial a member that answered 4404 until that member shows presence (any authenticated session from it) or a probe is due (30 s doubling to 5 minutes), jitters additions and presence dials, and after its own uplink returns waits 10-20 s before dialing members that have not shown presence. A 4429 halves the budget for 10 minutes. The budget is per host and never depends on the address: with relay passes (v1.6) every one of these upgrades carries a proof and is charged to the host's key, not to its address, so any number of hosts behind one address each keep the full budget. A 4412 (refused pass) is no gate and no halving (see "Relay passes"). A
machine.addtakes its two upgrades (herdr's probe and the line) together: it waits, like a line, until the window has room for both, so a probe is never charged for a line the window then refuses. What the add leaves undialed (it failed, or herdr asked for no line within 30 s) goes back to the window at once, since an undialed token was no upgrade. A host joining a mesh of N - 1 members thus starts exactly 3N - 3 upgrades (its pairing dial, N - 2 ack pushes, and two for each of the N - 1 machines it adds), and every member's core lists it within ceil((3N - 3) / 12) windows of 60 s: 60 s up to 5 members, 120 s up to 9, 180 s up to 12. A member that this host reached and has not gated offline since is reconnecting rather than offline when it refuses: it is retried 2 s after its first refusal and once more when 5 s have passed since that refusal, and gated offline only if it still refuses; a 4401 (it refuses this host as revoked) gets no such retries. A member this host has revoked that answers but refuses the handshake is tried again only when its own backoff is due, 1 hour doubling to 6 hours, and that refusal is logged once.
doriface-host mesh revoke <member>signs arevoke;--compromisednames the member and everyone it admitted, transitively, in one record. Every member closes the revoked keys' sessions (4401): inbound ones at once, and a sync session it dialed to a revoked member within 60 s, so the revoked host still learns its revoke and the acks after it. It removes the machine, removes the keys from its paired-devices store and the hostId from its known hosts, and refuses those keys on every path.mesh leavesigns a revoke of the leaving host first. A host acts on its own revocation only when its computed view says so, and stays read-only for 7 days.- Compromise of any member's keys, of a device paired to any member, or of an open offer is compromise of the mesh until revoked; the records name who did what.
mesh.json(in the host's state directory, readable only by its owner) holds the stored records, the dangling pool (at most 256 records whose past or whose signer's admission has not arrived; the oldest is dropped first), agenerationincremented on every write, and the host's own counterself.n. The counter is written before a record is signed with the next number, and a host signs nothing of its own, its automatic acks, theadmitof a join it approves (mesh pair,mesh approve) and the operator'smesh rename,mesh revokeandmesh leaveincluded, while a higher counter of its own key appears in its records or is claimed in a peer'shello; such a command, or the join, is refused with the claiming peer, the claimed counter and this host's own (the joiner getsrefusedand 4401), and signs when run again once those records arrived or the claim lapsed. Its own records that arrive moveself.nup to them in the same merge. Such a claim belongs to the peer, not to the session: it ends when the host holds its own records up to the claimed counter, and it lapses 30 s after the claim unless that peer delivers more of them, each delivery starting the 30 s again. Ending, replacing or re-greeting the session does not end or renew it, and neither does adone, records the host signs itself, or its own records delivered by another member. When a claim lapses, that peer's claims are ignored for 10 minutes; an automatic ack held back by a claim is signed once no claim stands. An answer to ahellosends the hello sender's own records first, in lines of their own with their past, so an honest claimer's first line already moves its claim. A claim also makes the peer owe adone, so 30 s without a non-emptyrecordsline ordonecloses the session with 4400. The 30 s is a safety net with a stated trade-off: a restored host whose next missing own record takes longer than 30 s to arrive from the claimer (a long past ahead of it, or one 256 KiB line on a link below about 9 kB/s) stops waiting and may then sign a record that forks its own chain; a longer limit would let a hostile member hold back this host's signing, and with it amesh revokeof that member, for longer. Trust comes from the records alone; every other field is a cache or display state.line.sockis a Unix socket (0600) in the host's state directory.doriface-host connect --mesh <hostId>connects to it and sends{"v":1,"hostId":"<hostId>"}; the running host answers{"ok":true}and dials that member with its own Noise key, or{"ok":false,"code":<close code>,"reason":"..."}when the hostId is not a current member or the dialing rules hold the dial back. Afterokthe connection is a byte pipe to the member's hc line.doriface-host mesh status [--json]shows, from this host's view, each member's name, hostId, Noise fingerprint, admitter and line state, the revoked keys, the new-member notices, pending joins awaiting approval, each member's revoke-time witness pool, and the sync state.doriface-host mesh rename <member> <name>signs anamerecord about a current member. The name follows the mesh-name rule above; when two members end up with the same name, the later one in member order takes the first free fallback name.- One-line Add a machine (v1.9.7, #668): a client writes
{"request": <nonce>}to thedoriface-mesh-offerherdr document of the core it reaches. The host whose core it is answers in the same document with{"request", "link", "expiresAt"}: a single-use mesh offer (asmesh pair --auto, admitting without asking until it expires) and itsdoriface://pair#…&m=1link, or{"request", "error"}. When a machine joins on that offer the host writes{"request", "joined": {"name", "hostId"}}in place of the link, and an offer that expires unused leaves{"request", "expired": true}. A request already answered opens nothing again. Anyone who can write this core's documents already reaches its shells, so the request grants nothing they lack. - The
doriface-meshstatus document (v: 1) is read forward compatibly, so readers and hosts can ship apart (#728): a reader drops any key it does not know, at the top level and inside every member, notice and reason, and checks every key it knows for its exact form. A key it knows that is missing refuses the document, except the ones it reads as optional: a member'slastSessionAtand a pending join'scodeandjoinerConfirmed. A field may therefore be added to a version without a newvonly as an optional one: a host built before the field keeps writing documents without it, so a reader that knows the field reads its absence as not said instead of refusing the document. The form of an existing field never changes within one version: that, a field every document must carry, or a field a reader must not ignore, is a newv, and a reader refuses avit does not know. A new field is written only once readers that drop it have shipped. A closed set is read the same way (#1139), so a value may be added to one without a newv: a string a reader does not know in a member'sline, a replaced machine'skindor a revoke'sreasonreads asunknown, and a STUCK reason of akindit does not know reads as{"kind": "unknown"}without its other keys and may stand for a host outside its own view. A dial gate of akindit does not know reads as no gate, and a pending join of akindit does not know is left out, because approving a join grants what its kind says. A host never writesunknown. A value of another JSON type is another form and still refuses the document, andsyncstaysokorstuck: another value is a newv. - New-member notice: for 7 days after it merges a member's admission, every member shows "
<name>joined via<inviting member>, admitted by<admitter>, fingerprint<fingerprint>" inmesh statusand in itsdoriface-meshherdr document, so an admission written with a compromised member's key is visible on every member.
- Which hostIds open sessions to which, from which addresses, and when; not the records, names or rules, and nothing it can forge, replay or splice.
- What the reference relay keeps of that: for each month, until day 7 of the following month, which proven hosts are in the same pool (not which pairs connected, or when), as salted pseudonyms deleted with that month's salt, and the daily pool counts it sends to its operator's product analytics (see Relay passes).
Web push notices (v1.7). The relay is not on the push path and does not change: stream sits inside the Noise payload.
- A session (
0x01) withstream:"push"admits only a key in the paired-devices store that is no mesh member's key (4401 otherwise). The loopback plaintext path serves the same stream at/v1/push, behind the same token subprotocol as/v1/hc. - Its plaintext is UTF-8 JSON lines, each one object with a string member
tand at most 4096 bytes including the LF. The host answers each client line with exactly one line, in order. A line that is longer or not such an object closes the session with 4400; an unknowntis answered{"t":"error"}. - Client lines:
hello;subscribe(subscription: the browser's endpoint and itsp256dhandauthkeys,events,muted);prefs;unsubscribe;test;focus(terminalor null: the pane this device shows focused and visible);notice(id);answer(id,answer:"allow"or"deny"). Host lines:ready(vapidKey, the subscription it holds for this device and endpoint, if any),ok,notice(terminalor null),answeredorstale(terminal),error(reason). - Subscriptions belong to the session's device key; revoking the device removes them. The host sends each push straight to the subscription's push service (RFC 8291
aes128gcm, RFC 8292 VAPID with a host-held P-256 key) and only tohttpsendpoints of known push services. A push payload is exactly{"v":1,"n":"<notice id>","k":"input"|"permission"|"done"|"error"|"test","h":"<hostId>"}, zero-padded to one 128-byte record (RFC 8188) so its size does not tell the kind; the notice id is 22 base64url characters from 16 random bytes and maps to a terminal only on the host, for 24 h. - An
answergoes through the rule the in-app permission banner uses (#192,answerApproval): one claim per prompt in the terminal's approval document across every client, then a fresh read of the live terminal (promptStillThere: the sameblocked/permissionrecord,status_ms, turn and dialog as when the notice was made), and only then the agent's own key from its dialog (Claude Code1or Esc, Codexyor Esc). Otherwise the reply isstaleand nothing is sent. A notification's Allow is never sent by the service worker: it opens the app on the pane, and the page sends the answer once it is visible; Deny may be sent by the worker. - A device whose push stream is open and reports
focuson a terminal gets no push about that terminal. - Native apps (#705): the iOS and Android apps subscribe with an endpoint on Doriterm's push bridge,
https://push-doriface.omo.dev/v1/apns/<device token>,/v1/apns-sandbox/<device token>or/v1/fcm/<registration token>, and their own P-256 key and auth secret. The host treats it as any other push service. The bridge checks the request (oneaes128gcmrecord from a P-256 sender, at most 1024 bytes; a VAPID token for its own origin that has not expired) and forwards the body unchanged, base64url in the memberp: to APNs as an alert withmutable-contentand a fixed text the app's Notification Service Extension replaces, to FCM as a data-only message. It answers 201 when APNs or FCM took the push, 410 when the token is unregistered (the host drops the subscription), 429 when throttled, and 502 or 503 otherwise. It holds no key that opens a notice.
- Each doriface-host writes the herdr document
doriface-hoston its own core at start:{"v":1,"os":"darwin"|"linux"|"win32"}, itsprocess.platform. A host on any other OS writes none. It reads the document first and writes only when the OS differs, at the version it read; onconflictit reads and writes once more. - A client reads it with hc's own
doc.get:{name:"doriface-host"}for a terminal on the core it is connected to,{name:"doriface-host", on:<machine>}for one on a machine that core added (a mesh member or any machine running doriface-host). hc's frames pass through unchanged; nothing is added to them. - A reader takes
v:1andos, and ignores members it does not know, so a later host may add some. No document, anotherv, an unknownos, or a failed read (an offline machine) means the host did not say: the phone key bar then guesses from the core's or machine's name, as before. - The phone key bar shows Command only on a
darwinhost's terminal, and its paste chord is cmd+v there and ctrl+shift+v elsewhere. - The document is advisory and never used for security. hc's
doc.settakeson, so a core that added machine X, or any client of X's core, can overwrite X'sdoriface-hostdocument until X's host restarts and writes it again. The effect is limited to X's key bar: whether it shows Command and which paste chord it sends.
- 4400: crypto failure, including an unknown session kind, a malformed first message, an invalid CPace share, or a key confirmation that does not decrypt; an unknown or misplaced
stream, early bytes on a mesh session, a malformed or oversize mesh stream line, a sync peer that sends norecordsordoneline for 30 s after ahello, a mesh name that breaks the mesh-name rule, or an hc line before the framedhellothat breaks the rule under Session kinds - 1011: the host failed internally (for example it could not record a typed-code attempt); nothing was answered
- 4401: unknown device, or a pairing the host does not accept here: no live offer, an offer already used, a typed-code pairing on the direct path or without
?pair, a slot that is not the offer's, or a session kind0x01on a?pairsession; a device pairing on a mesh offer or a join on a device offer, a mesh stream from another mesh, a refused member card, a revoked mesh member, or an hchellowhosecore.iddoes not match - 4402: relay protocol error (for example an invalid
a:<n>acknowledgement, credit for bytes never sent, or a malformedc:) - 4403: relay auth failed
- 4404: host offline
- 4408: idle or backpressure timeout, a handshake that did not finish within 10 s, or a relay session whose undelivered bytes on the host exceeded 4 MiB
- 4409: uplink replaced by a newer authenticated uplink for this hostId; the replaced host must not reconnect
- 4410: pairing slot not registered to this host (expired, retired or never opened)
- 4411: a typed-code mesh join refused before any answer for any reason but a device offer (which stays 4401): no live offer, an expired one, a slot that is not the offer's, or the plan's refusal (v1.10.3)
- 4412: relay pass refused: the upgrade's proof was malformed, forged, expired, stale or replayed, or its key id is no longer accepted; dial again without it (never final)
- 4413 (v1.11): resume refused: the host does not hold the session the request names, or one side cannot join the other's position; final for that session, the client opens a new one with a fresh handshake
- 4429: rate limited, including a typed code whose 10 answered attempts are spent
- v1.11.1 (relay behaviour, no wire change): the reference relay counts mesh pools from proven sessions between hosts, as monthly HMAC pseudonyms grouped per pool and deleted with the month's salt, and sends its daily totals and pool counts to its operator's product analytics as numbers only (see Relay passes).
- v1.11: session resume (#1995). A session counts the records it sent and opened and keeps a 1 MiB ring of the sent ones; a socket that drops with anything but a close its peer meant (1000, or 1001 going away) detaches the session instead of ending it (the host keeps it and its
hc connectfor 120 s, the client dials again for up to 60 s), and the client's first message on the new socket is a 57-byte resume request (0x04, an id and a MAC derived from the handshake hash, its counters) that the host answers with its own counters, after which each side sends only the records the other never opened. No handshake, no newterminal.attach, no screen reset or replay; output the host made meanwhile arrives once, in order. A position the other side cannot join is refused with the new close code 4413, final for that session, and the client falls back to a fresh handshake at once, as before. No relay change: the relay passes any close code from 3000 to 4999. - v1.10.3 (host behaviour, no relay change): close code 4411 for a typed-code mesh join the host refuses before any answer, where it sent 4401, so 4401 on such a join means only a device offer and a joiner pairs as a device on that alone (#1492). The relay forwards it like any host close code. A joiner still reads 4401 from an older host as a device offer, and an older joiner shows 4411 as an unknown close.
- v1.10.3 (documentation and host help, no wire change): the direct path is off by owner decision (#2070). The "Direct path" section says so and keeps the mechanism's description as a description;
doriface-host --helplabels--lan-listenand--no-relayas test knobs and no longer offers "reach this host only directly" as a way to run the host (#2075). - v1.10.2 (reader behaviour, no wire change): a value the
doriface-meshstatus document's reader does not know in a closed set no longer refuses the whole document. A member's line state, a STUCK reason's kind, a replaced machine's kind and a revoke's reason read asunknown, a dial gate of an unknown kind reads as none, and a pending join of an unknown kind is left out, so a host that adds such a value is still read by an older web app or CLI (#1139). - v1.10.1 (documentation, no wire change): the
doriface-meshstatus document's forward-compatibility rule names the optional field. A reader refuses a document that lacks a key it knows unless it reads that key as optional, so a field added within a version is optional and its absence reads as not said; a field every document must carry is a newv(#1137). - v1.10 (mesh rule, no relay or wire change): a mesh has no member cap (#806).
membership()makes every key with a governing admission a member, where it made only the first 12 members and the rest over-cap (not dialed, unable to sign), and an inviting member no longer refuses a join as "the mesh is full" (a plan'smachineslimit, when a policy names one, still applies). Admitting a member still needs a current member's signedadmitafter the owner's approval, and every authorization rule is unchanged. What bounds a mesh is what bounds its log: 4096 records at the door, a welcome of at most 4096 records and 8 MiB, mesh lines of at most 256 KiB, a dangling pool of 256, and the per-host dial budget of 12 upgrades per 60 s, none of which counts machines. A host older than v1.10 keeps the 12-member view, so in a mesh past 12 it refuses the 13th member onward and ignores their records: upgrade every member before growing past 12. Thedoriface-meshdocument keepsoverCap, written false, for readers that require it. - v1.9.9 (reader behaviour, no wire change): the
doriface-meshstatus document's readers drop a key they do not know inside every object, as they already did at its top level, so a host that adds a field is still read by an older web app or CLI (#728). - v1.9.8 (relay behaviour, no wire change): the reference relay keeps anonymous daily counts of hosts and keyless client addresses, as HyperLogLog sketches under a monthly salt it destroys, and never writes a key, a hostId or an address (see Relay passes) (#788).
- v1.9.7 (host behaviour, no relay change): the
doriface-mesh-offerdocument, a client's request for a single-use mesh offer that the host answers with the link and then with who joined (#668). - v1.9.6 (host behaviour, no relay change): the plaintext listener's
/v1/devices,GETto list this computer's paired devices andDELETE /v1/devices/<id>to revoke one, behind the same per-launch bearer token as/v1/hcand never on the LAN listener, so the desktop app revokes a phone from the computer it was paired to without a terminal (#709). - v1.9.5 (host behaviour, no relay change): the plaintext listener's
/v1/pairpair,POSTto open this host's offer andGETto read what stands, behind the same per-launch bearer token as/v1/hcand never on the LAN listener, so the desktop app shows this computer's code, QR code, link, fingerprint and expiry without a terminal (#614). - v1.9.4 (host behaviour, no wire change):
doriface-host pairprints the desktop app'sdoriface://pair#…deep link, and the QR code encodes it, unless--web-originnames a web app (<web origin>/pair#…); the printed text says which one opens the link.mesh pairprints the same deep link with&m=1, andconnectandmesh joinaccept either form.DEFAULT_WEB_ORIGINis gone: no dead web origin is advertised by default (#594). - v1.9.3 (documentation, no wire change): rules the relay already enforced, so a stand-in built from this section matches it (#45): a clear of a registered slot is acknowledged with PAIR_SLOT_ACK status 0 and the released slot, which the host waits for; a PAIR_SLOT whose first 3 bytes are not a slot closes the uplink with 4402 rather than status 2; a request without
cf-connecting-ipis keyed asunknown, one shared bucket; and a stand-in is in effect a wrangler project (wrangler.jsonc,node_modules/.bin/wrangler, Node 22 or newer). - v1.9.2 (host behaviour, no wire change): a
machine.addreserves its two upgrades together and gives back what it leaves undialed, so the join bound holds at every mesh size: within ceil((3N - 3) / 12) windows of 60 s (#106, M-E3). - v1.9.1 (documentation, no wire change): the mesh join bound per mesh size (#106, M-E3): within 60 s up to 5 members; above 5 not yet guaranteed (see Dialing).
- v1.9: the host signs its pairing slot (#22). PAIR_SLOT gains the 107-byte signed form; the lookup answer gains
expiresAtandslotSig, which the relay stores without verifying and omits for an unsigned registration; clients verify the signature for the typed code's slot with bounds onexpiresAtboth ways, and refuse an unsigned answer. A host falls back to the 35-byte form per request against an older relay. - v1.8: the
doriface-hostdocument ("Host info"), the host's OS on its own core; no relay or wire change. - v1.7.1 (no wire change): the host enforces the session caps itself (32 active, 8 pending), refusing an OPEN past 8 pending or a first DATA past 32 active with CLOSE 4429.
- v1.7.2 (relay behaviour, no wire change): on a host uplink the relay's own frames get 64 KiB of room above the 4 MiB DATA window, so one session's or a burst's DATA can end those sessions but never closes the uplink; a client's acknowledgements reach a credit uplink as CREDIT a 64 KiB step at a time (or once it has acknowledged everything sent); a pending session may send at most 64 KiB, and a credit session is ended once it sends past its credit, each with 4408 and alone.
- v1.7: the push stream (
stream:"push",/v1/pushon loopback) and web push notices sent by the host; no relay change. - v1.6: relay passes. A host whose uplink passed its challenge gets a relay-made pass (PASS frame, type 7, on an uplink dialed with
?pass=1), and every later upgrade carries a fresh signed proof (?proof=) that skips the per-source upgrade limit and is charged to a per-key limit instead, so any number of hosts behind one address keep their full dial budget. Close code 4412 refuses a bad proof. Pending eviction groups proven sessions by host key. Old hosts and old relays ignore all of it. - v1.5: a machine mesh over the relay with no relay change. Membership is a grow-only set of signed, hash-linked, per-signer-chained records (
found,admit,revoke,name,rekey,ack) whose admissions embed the subject's self-signed card; the view is a total function of the set (rule R3, two levels), conflicts between a record and a concurrent revoke of its signer are decided by the signed testimony (automatic acks) of the members of their common past who are neither party nor a party's post-fork admitter, only revokes with standing may accuse, an undecidable conflict fails closed, and every set has exactly one view. A host joins through the existing pairing flow against one member, with that member's fingerprint confirmation, and is then trusted by every member, which shows a new-member notice. Gossip runs over on-demand sync sessions; each core adds every other member throughdoriface-host connect --mesh, dialed by the host with its own key, under a per-host dial budget sized for the relay's per-address limit. Revocation from any member, including--compromisedsubtree revocation, closes sessions with 4401 and removes the member from every paired-devices store. New: thestreampayload member,&m=1, the mesh stream lines,mesh.json,line.sock, the 12-member cap and themesh pair|join|status|revoke|rename|leavecommands. - v1.4 (documentation, no wire change): the relay section now states rules the relay already enforced and the public suites check, so another server can stand in: the per-source rates (60 upgrades, 20 lookups per minute), the
cf-connecting-ipsource and its IPv4 / IPv6 /64 key, the 4404 for a replaced uplink's sessions, no PAIR_SLOT_ACK for a clear without a slot, and the test-only timeout variables. - v1.4: end-to-end session credit on top of v1.3.1: the
?credit=1opt-in, the CREDIT mux frame (type 6) and the relay's coalescedc:<bytes>text, with a 512 KiB per-session window that always lets a send go below one 64 KiB credit step. The host still acks the uplink on arrival and keeps the 4 MiB per-session bound and its 4408; credit only keeps a cooperating client below that bound, so the 160 MiB per-uplink and 4 MiB per-socket bounds are unchanged. Peers without the opt-in keep v1.3.1 exactly. - v1.3.1: the host uplink acks each relay frame on arrival and bounds each session's undelivered bytes at 4 MiB, closing only that session with 4408 (at most 160 MiB per uplink); acks no longer wait for a session's reader, so one slow session cannot stall the uplink.
- v1.3: typed-code pairing uses CPace (CPACE-RISTR255-SHA512, draft-irtf-cfrg-cpace-21) bound to hostId, the host Noise static key, the slot and a per-attempt session id; its key is the IKpsk2 psk, so every code guess costs one answer from the real host and no relay or observer can test a guess offline (v1.2 let one message 2 test every code). The pairing URL carries a 32-byte link secret (
p=) instead of the code. Every session's first message starts with a kind byte (0x01session,0x02pair-code,0x03pair-link), bound into the prologue. The host retires a typed code after 10 answered attempts per offer and refuses typed-code pairing on the direct path. The handshake payload rules ("v":1, the message 2lanreply, the 256-byte line, the 64-unit name and the 4096-byte early data) and the empty key-confirmation record are now written down. v1.2 pairing and session messages are refused. - v1.2.1: close code 4409 (uplink replaced), which the relay already sends when a newer uplink authenticates for the same hostId.
- v1.2: pending-session admission; the
a:<n>backpressure acknowledgement; the relay origin in the uplink signature; non-extractable device keys with a raw fallback;ping/pongkeepalive; the pairing budget moved to the relay, with codes burned only on success or expiry (replacing "burn after 3 failed handshakes"); PAIR_SLOT carrying the Noise static key, acknowledged by PAIR_SLOT_ACK; pairing sessions marked with?pair=<slot>; monotonic acknowledgements, rejected with 4402 when out of range; per-source quotas on pairing lookups and sessions, with the slot's session budget charged only after the host answers; close codes 4402 and 4410; direct-path keepalive; pinned prologue, payload and nonce rules. Resume without a repaint is deferred. - v1.1: the 8-character typed code with a relay pairing slot; the SHA-256 hex fingerprint; the
doriface-host pairanddoriface-host fingerprintcommand names. - v1: initial contract.