One keyboard and mouse for a Mac and a Windows PC over the local network, in either direction.
The link, wire version 6
How machines running Beamer 1.5.0 and later know each other, open an encrypted link, and hand input from one to another, exactly enough to write a second implementation. Pairing, the exchange that gives two machines their shared token, is in PAIRING.md; this file says what changes in it for 1.5.0 and otherwise leans on it. What the link protects and what it does not is in SECURITY.md.
Version 6 replaces version 5 (1.4.1 to 1.4.3) outright. Version 5 had two machines and two roles, a Mac and a PC; version 6 has any number of machines, each with its own identity, and a platform is something a machine says about itself rather than what it is. There is no fallback: a machine on version 6 refuses a version 5 peer and says which machine to update.
Beamer 1.5.0 is built to it. The last sections list where it departs from version 5 and from its first design, what has been decided, and the questions still open.
Terms
- Machine. One install of Beamer: a desktop app, or later a phone app. Each has an id.
- Peer. A machine this one has paired with. Each peer has its own token.
- Link. One TCP connection between two peers. The machine that opens it is the initiator; the one that accepts it is the responder. Input only ever travels from initiator to responder, so between two desktops that may each drive the other there are two links, one each way, as in version 5. A phone only ever initiates.
- Owner. The machine whose input a responder is injecting now. A responder has at most one owner at a time, or none. The owner is always the initiator of the link the input arrives on.
- Route. A number the owner raises each time it moves its input, so that a late request cannot move input that has already moved.
- Zone. A stretch of a machine's own screen (an edge, part of one, a corner or the notch) that leads to one peer.
Encodings
- Ids. A machine id is 16 bytes from the operating system's secure random source, made once
per install. Sixteen zero bytes is never an id. In JSON and in the settings file it is
PAIRING.md's
b64(URL-safe base64 without padding, 22 characters), with the same rule: decode, encode again, and refuse the text if it differs. A machine id never travels in the clear on a link: the preamble carries the pair's key id instead (section 2). Pairing sends both machines' ids in the clear, once (section 6). - Tokens. A token made by pairing is the
b64of 32 bytes: 43 characters that decode and encode again to themselves. That spelling proves nothing about where a token came from: 43As spell 32 zero bytes, and a user could have typed them. So what links is an entry made by pairing on 1.5.0 or later (from_1_4false) whose token has that spelling. A token migrated from 1.4.x never links, whatever its spelling, and neither does one of any other shape, a typed token (sections 1 and 2). - Messages are UTF-8 JSON objects of the shape
{"type": <string>, "data": <object>}, with no byte order mark. Unknown types are ignored, and so are unknown keys insidedata. - Not a message. A frame's plaintext that is not UTF-8, not JSON, or JSON whose top level is
not an object (
[],"x",1) is not a message at all. It ends the link once the handshake is done (section 2, frames); as the first frame it is answeredinvalid_hello(section 2, step 7). Nothing below applies to it. - Malformed messages. A message is malformed when it has no string
typeor no objectdata, holdsNaNor an infinity, or has a known field whose value is outside what this document allows; section 10's shared values are the one exception, each left out on its own. A field that does not belong to a message, or to that kind of the message, is ignored like an unknown one. A sender never repeats a key; a receiver may refuse a message that does, or keep the last value (Swift's decoders keep the last, Android'sorg.jsonrefuses), and neither may matter to what a correct sender sends. A malformed message is ignored as a whole, with three exceptions: a malformed first frame and a malformedackend the link, and a malformedfocusnaming the receiver is answered withrefuse(section 5). A receiver whose JSON parser refuses outright a text that breaks one of the rules above the parser cannot see past (a byte order mark,NaN, a lone surrogate) may end the link instead of ignoring the message; a correct sender never sends one, and the vectors record what the desktops do, which is to ignore it. - Numbers. "Integer" means a JSON number with no fraction or exponent (
1, never1.0or1e0), and nevertrueorfalse. A parser that turns JSON into a platform number type must check the text, not the value: Swift'sJSONSerializationgivestrueand1.0as numbers that cast to1. "Number" means any finite JSON number. - Strings. Lengths are in Unicode code points unless a limit says bytes, and a string is malformed if it is not valid Unicode (a lone surrogate).
- Names are 1 to 48 code points, cut and checked exactly as PAIRING.md says.
- Platforms are
"macos","windows","linux","ios"and"android". Any other string of 1 to 16 characters froma-z,0-9and_is accepted and treated as"linux"for the key table; anything else is malformed. - Hex in the vectors is bytes in wire order.
1. Identity and the peers list
What each machine keeps
Each app keeps its settings in one JSON file:
| App | File |
|---|---|
| Mac | ~/Library/Application Support/Beamer/settings.json |
| Windows | %LOCALAPPDATA%\Beamer\settings.json |
| Linux | $XDG_CONFIG_HOME/Beamer/settings.json, else ~/.config/Beamer/settings.json |
Beside the machine's other settings, which keep the names 1.4.x gave them, it holds:
| Field | Meaning |
|---|---|
schema |
6 |
machine_id |
this machine's id, b64 |
name |
this machine's name as shown to peers; the computer's name when empty |
port |
the TCP port this machine accepts links on, 24820 unless the user chose another |
shortcut |
whether the switch shortcut is one of this machine's ways across |
peers |
a list of peer entries, below, at most 32 |
zones |
this machine's zones, section 8 |
layout |
this machine's remembered tiles, keyed by machine id; each tile has integer x, y, w and h canvas units |
layout_set_at, layout_by |
the last shared tile picture's independent stamp |
migrated_token_sha256 |
lower-case hex SHA-256 of the UTF-8 of the last 1.4.x auth_token migrated, or "" |
A peer entry:
| Field | Type | Meaning |
|---|---|---|
id |
b64 or "" |
the peer's machine id; "" only for the entry migrated from 1.4.x |
name |
string | the peer's name, from pairing, then from every hello or welcome |
label |
string, optional | this machine's local display name for the peer; trimmed, at most 64 code points; empty clears it |
platform |
string | the peer's platform, from pairing, then from every hello or welcome |
token |
string | the shared token from pairing, never reused for another peer |
host |
string | the IPv4 address to open a link to the peer at; "" for a phone |
host_pinned |
boolean, optional | absent or true preserves the chosen host; false for an address pairing or an incoming link learnt, which may follow discovery |
port |
integer | the peer's own link port; 0 for a phone, which is never dialled |
hw |
string | the peer's hardware address for wake-on-LAN, aa:bb:cc:dd:ee:ff, or "" |
send |
boolean | this machine's input may go to the peer |
allow_drive |
boolean | the peer may drive this machine |
side |
string | which edge of this machine faces the peer (left, right, top, bottom), or "" |
side_set_at |
integer | unix seconds of the last change to side at either end, 0 when never changed |
side_by |
b64 or "" |
the machine that made that change; "" only with side_set_at 0 |
paired_with |
list of b64 |
the ids the peer last said it is paired with (the paired message) |
paired_at |
integer | unix seconds of the pairing, 0 for a migrated entry |
linked |
boolean | a version 6 link with this peer has authenticated at least once |
from_1_4 |
boolean | this entry was migrated from a 1.4.x pairing, and never links |
way_back |
boolean, optional | what the peer last said in arrangement's way_back (section 8): whether one of its zones leads here; absent until it says |
way_back_by |
b64, optional |
what the peer last said in arrangement's way_back_by (section 8): the machine whose zone holds the side it has for this one; absent when it named none |
shortcut_cycle |
boolean, local only | whether this machine is included when shortcut_goes_to is ticked; absent means ticked |
left_out |
boolean, local | whether this peer is left out of this machine's layout; never sent |
left_out_ways |
list of strings, local | the zone kinds to restore when this peer is put back; never sent |
dormant |
boolean, optional, local | whether conclusive link evidence says this peer no longer has the pairing; absent means false; never sent |
dormant_reason |
string, optional, local | wrong_id or forgotten, the evidence that set dormant; absent when dormant is false; never sent |
Rules:
- Two entries never share an id, and no entry has this machine's own id. Pairing refuses both (section 6), and a link that would make either true is refused (section 2).
- Two entries never share a key id (section 2: 16 bytes computed from the token, never stored). Pairing refuses a token whose key id is already an entry's (section 6), and the re-migration below skips one. With tokens from pairing a clash means the same token twice.
- At most one entry has
id: "", and it is the one withfrom_1_4: true. Zones for it name it by"". - An entry migrated from 1.4.x, or with a typed token, is kept and shown, but never linked: it is not dialled, the responder never computes or matches its key id, and Overview asks the user to pair that machine again: "name was paired on Beamer 1.4. Pair the two again to link them on 1.5.0." A new pairing with that machine replaces it (section 6).
- Removing a peer resets a local Match design with selection to None, then deletes its entry and token, closes its links, and ends its ownership if it holds it (section 4). Its next link's key id is unknown here, so it is closed with nothing sent, and the peer says this machine closed the connection (section 2).
- Turning
allow_driveoff ends that peer's ownership at once. Turningsendoff lets go of that peer if this machine's input is on it, and closes the link this machine opened to it. - Writes are atomic: a new file beside the old, then a rename over it.
- The machine id never changes for the life of the settings file. A new file (the user deleted
it, or a fresh install) is a new machine, which every peer must pair with again. A file copied
to a second computer (a restored backup, a migration assistant) makes two machines with one
id and the same tokens: their peers see one machine whose links keep replacing each other.
Deleting
settings.jsonon the copy makes it a new machine.
The migration from 1.4.x
1.4.x keeps its settings in config.json in the same folder, shaped differently on each app.
Each app migrates its own when it starts and finds no settings.json:
- Read
config.json. If it is missing or does not parse, start with defaults and no peers. - Make the machine id.
- Copy every field 1.5.0 still uses under the same name, then move the pairing fields into one
peer entry as the tables below say. When
auth_tokenis empty, there is no peer entry. - Set
migrated_token_sha256fromauth_token(""when it is empty). - Write
settings.jsonatomically. Never writeconfig.jsonagain.
On the Mac:
| 1.4.x field | Becomes |
|---|---|
host |
peers[0].host |
port |
port, and peers[0].port |
auth_token |
peers[0].token |
pc_name |
peers[0].name |
mac_address (the PC's, for wake-on-LAN) |
peers[0].hw |
send_to_windows |
peers[0].send |
allow_windows_to_drive |
peers[0].allow_drive |
crossing.edge |
peers[0].side |
crossing.arrangement_set_at |
peers[0].side_set_at |
crossing.methods, crossing.edge_parts, crossing.corner |
zones, and shortcut (section 8) |
key_map |
kept as it is: a style name, or a map (section 7) |
| — | peers[0]: platform "windows", id "", from_1_4 true, linked false, paired_at 0 |
On Windows:
| 1.4.x field | Becomes |
|---|---|
mac_host |
peers[0].host |
port |
port, and peers[0].port |
auth_token |
peers[0].token |
paired_with |
peers[0].name |
mac_hardware_address |
peers[0].hw |
send_to_mac |
peers[0].send |
allow_mac_to_drive |
peers[0].allow_drive |
mac_return_edge |
peers[0].side |
arrangement_set_at |
peers[0].side_set_at |
crossing_methods, crossing_edge_parts, crossing_corner |
zones, and shortcut (section 8) |
modifier_style |
kept as it is (section 7) |
host (this PC's own address, as shown) |
dropped: the pairing sheet shows the live address |
mac_resistance_px |
dropped: the owner sends its resistance with every focus |
| — | peers[0]: platform "macos", id "", from_1_4 true, linked false, paired_at 0 |
On both, peers[0].side_by is this machine's own id when side_set_at is above 0, else "":
two migrated ends that disagree at the same second then settle by the larger id (section 8).
Every other field (the shortcut key and style, the Design page, pointer and scroll speed, the keys that stay, appearance, update checks, Hide addresses, Same on both machines) keeps its 1.4.x name and value. A field 1.4.x did not have takes its default.
Idempotent. Once settings.json exists, starting again changes nothing in it (unless config.json's
token has changed, below), and
config.json is byte for byte what 1.4.x left. A start that fails before step 5 leaves no
settings.json; the next start migrates again with a new machine id, which no peer has learnt.
Downgrade. Because config.json is never written, installing 1.4.x again finds its own
settings as they were at the upgrade. Changes made under 1.5.0 do not go back with it. Both
machines have to go back, because a 1.4.x machine speaks version 5, which 1.5.0 refuses.
Pairing again under 1.4.x, then upgrading again. On every start that finds settings.json,
if config.json holds a non-empty auth_token whose SHA-256 differs from
migrated_token_sha256, that one pair is migrated again: the from_1_4 entry is replaced (or
added, if the user had removed it, in which case it gets zones from config.json's methods as the first
migration made them, and is not added at all when the list already holds 32), with id "", linked false and paired_with empty; zones
that named the replaced entry name ""; and migrated_token_sha256 is updated. A token that
has not changed is never migrated twice, so a peer the user removed stays removed. A token whose
key id is another entry's already is not migrated, and migrated_token_sha256 is still updated.
A typed token is never refused by that check. Either way the migrated entry never links.
Why a migrated pairing never links. 1.4.x kept one auth_token and nothing about where it
came from: pairing wrote it, and so did the token field on the Mac's Connection page and the
PC's settings, and the name pairing saved beside it stayed when a user typed a new token. A
typed token can be weak, and its key id (section 2), seen on any link, lets someone test guesses
against it offline. The spelling cannot tell the two apart, so the migration keeps the entry to
show the user which machine it was, and the user pairs the two again. The entry keeps id: "",
since 1.4.x never had ids. 1.5.0's first two betas let a migrated token of pairing's spelling
link and learn its peer's id; such an entry keeps that id and does not link either.
2. The link
Who connects to whom
Every desktop listens on its port for links from its peers. It keeps one link open to each
peer with send true, a host and a non-zero port, reconnecting every two seconds while it is
down, as version 5 did for its one peer. A phone listens for nothing; it opens a link to each
desktop it is paired with while its app is open, at once when the app comes to the front and
every two seconds while a link is down.
Version 5's Mac could reach its PC through an SSH tunnel on 127.0.0.1:24822 when macOS 27's
local network rules blocked it. 1.5.0 keeps it for the one peer whose address the tunnel was set
up for; a link that arrives from a loopback address never changes a saved host.
The preamble
Each side's first bytes are a preamble, in the clear:
| Offset | Bytes | Field |
|---|---|---|
| 0 | 5 | BEAMY, ASCII |
| 5 | 1 | the version, 0x06 |
| 6 | 8 | the nonce prefix: random, new for every link |
| 14 | 16 | the pair's key id (below) |
| 30 | 32 | the sender's ephemeral X25519 share: new for every link |
62 bytes in all, the same layout both ways. The key id is in the clear so the responder can
choose the one token to try before anything is decrypted; it belongs to the pair, not to either
machine, so the responder's preamble carries the same key id as the initiator's. Neither
machine's id is in the clear: each travels inside the first frame (hello and welcome) and is
checked there.
key_id = HKDF-SHA-256(ikm = the token as saved, as text, salt = b"beamer-link-v6",
info = b"beamer-key-id", length = 16)
That is the first 16 bytes of HKDF's first block. Every entry's key id is computed from its token when it is needed and never stored. A key id is an offline test of its token, harmless for 256 random bits and fatal for a typed word, and a token's spelling cannot tell the two apart, so a key id is only ever sent or matched for an entry this machine made by pairing on 1.5.0 or later (section 1). Every other entry is never used for a link at all.
The ephemeral share is X25519(secret, 9) (RFC 7748's base point), from 32 bytes of fresh
randomness the side draws for this link alone and forgets once the link's keys are made.
The handshake
The responder:
Holds at most four connections in their handshakes, and at most one from any one address (the source IPv4 address, whatever the port). A new connection from an address that already has one replaces it; a new one from another address when four are held replaces the oldest. An authenticated link never counts against the four. The preamble must arrive within 1 second and the whole handshake within 5 seconds of the connection being accepted. Beside the four slots, at most 32 connections are being dealt with before they authenticate, counting those in a slot, those being answered and drained (step 2) and those whose slot was taken by a newer one but are not yet closed; a connection past the 32 is closed at once, with nothing read or sent.
Reads 6 bytes.
- Not
BEAMY: a Beamer from before version 4, which opened with a cleartext frame. It answers with the version 5 legacy frame, a 4-byte big-endian length then the JSON{"type":"welcome","data":{"version":6,"error":"version_mismatch"}}, and closes. - Any version below 6: reads the 8 bytes left of a 14-byte version 4 or 5 preamble, answers
with the short reply (
BEAMY,0x06, 8 random bytes: 14 bytes, no id), and closes. A version 5 Beamer reads that as a newer peer and says so in its own words. This machine's status names the peer whosehostis the connection's address, if one is. - A version above 6: answers with the short reply and closes.
Wherever it answers and closes, it frees the connection's handshake slot, shuts its sending side, then reads and discards what the peer sends for up to one second, so the answer is not lost to a reset. At most 8 connections drain at once; past that one is closed as soon as its answer is sent, without draining. A draining connection still counts against the 32 of step 1.
- Not
Reads the other 56 bytes, and looks up the entry made by pairing (section 1) whose token has this key id. None: it closes, sending nothing. There is never a second try with another token, and no entry is looked up by anything else.
Draws its own ephemeral secret and share, and computes the shared secret from the initiator's share (below). When the result is 32 zero bytes, or the platform's X25519 refuses the share, it closes, sending nothing.
Draws its own nonce prefix, drawing again while it equals the initiator's, and sends its preamble, with the same key id.
Makes the two keys (below) and reads the first frame, whose length field must be at least 21 and at most 4096; a larger claim is refused before the frame is read. A frame that fails its tag, or whose counter is not 1, closes the link with nothing sent back.
Requires that frame to be a valid
hello(below). Any first frame whose tag checks but which is not a validhello(a plaintext that is not JSON or not an object, anothertype, a malformed field) is answered withwelcomecarrying onlyversion6 anderror: "invalid_hello", and the link is closed. This is the one place a plaintext that is not a JSON object is answered rather than ending the link at once. A paired peer within_useset tofalsereceives this same refusal after its authenticatedhello.Checks the
idinhello. When it is this machine's own, or is not the entry's, it answerswelcomecarrying onlyversion6 anderror: "wrong_id", and closes. Only a holder of the token can read that answer, so it tells nobody else anything. Otherwise it setslinked, and saves what changed.Sends
welcome, then its announcements (section 3).Closes any earlier link it accepted from the same peer id; a link this machine opened to that peer is a separate link and stays. If the closed link's peer was the owner, the ownership ends first (section 4).
The initiator:
- Connects, with a one-second timeout. From the moment the connection is up, the whole handshake must finish within 5 seconds. It dials only an entry made by pairing (section 1).
- Draws its ephemeral secret and share and sends its preamble, with the entry's key id.
- Reads 6 bytes.
- Not
BEAMY: says the peer did not answer as a Beamer, and closes. - A version below 6: reads the 8 bytes left, closes, and says the peer runs an older Beamer, naming it: "Update Beamer on name: it is older than this one."
- A version above 6: closes and says this machine is the older one.
- The connection closes or resets before a byte arrives. A responder that does not know the
key id closes like this, and so does a version 5 responder, after reading 14 of the 62
bytes; on Windows and Linux that close can destroy the version 5 preamble in flight. So:
when the entry has never linked on version 6 (
linkedfalse), "Update Beamer on name to 1.5.0; if it is up to date, pair the two again"; otherwise "name closed the connection: it may have removed this machine, or be too busy to answer". After such closes, and nothing else, for 60 seconds running on an entry that has linked (any other result starts the 60 seconds again), it says "name no longer has this pairing: remove name here and pair the two again", and dials that entry every 30 seconds rather than every 2 until a link is made or the entry changes. - Nothing within the handshake's 5 seconds (the initiator has no separate deadline for the preamble): says the peer is probably running a Beamer from before version 4.
- Not
- Reads the other 56 bytes and checks them: the prefix must differ from its own, and the key id must be the one it sent. It computes the shared secret from the responder's share, which must not give 32 zero bytes or be refused by the platform's X25519. On any failure it closes without sending anything and says a different Beamer answered at that address.
- Makes the two keys, sends
hello, and reads thewelcome, whose length field is also held to 21 to 4096. The key id matched, so the peer holds this token: a failed tag here means something on the path altered the link ("name could not be authenticated"), and a closed connection says what a close in step 3 says, bylinked. - Requires a valid
welcome. One witherror: "invalid_hello"means this app sent something the peer could not read; it says so and closes. One witherror: "wrong_id"means the peer holds this pair's token under another machine's id: it closes, stops dialling that entry until its settings change or the app starts again, and says "name has this pairing under another machine: remove it on both and pair again." Any othererroris awelcomethat is not valid. - Checks the
idinwelcome: not this machine's own, and the entry's. On a failure it closes, sending nothing more, and says a different Beamer answered at that address. Otherwise it setslinked. - Sends its announcements.
The initiator sends hello, and its own id in it, before it has seen the responder's id. Both
are sealed under keys only a holder of the token can make, so only the paired machine, or one
that has its token, ever reads either id.
The keys
shared = X25519(this side's ephemeral secret, the other side's ephemeral share)
key(direction) = HKDF-SHA-256(ikm = the token as saved, as text || shared,
salt = b"beamer-link-v6",
info = b"beamer-frames" || 0x06 || key_id || prefix_I || prefix_R
|| share_I || share_R || direction,
length = 32)
direction = 0x01 for frames the initiator seals, 0x02 for frames the responder seals
prefix_Iandshare_Iare the initiator's,prefix_Randshare_Rthe responder's: the order is fixed by role, not by who is computing.infois always 111 bytes: 13 of label, the version byte, 16 of key id, 8 and 8 of prefix, 32 and 32 of share, and the direction byte.ikmis 75 bytes for a token made by pairing: the token's 43 ASCII characters ofb64, never the 32 bytes they spell, then the 32 bytes ofshared.- HKDF is RFC 5869, and X25519 RFC 7748 (the scalar clamped, bit 255 of the incoming share
ignored). A
sharedof 32 zero bytes ends the handshake, and so does a platform's X25519 that throws on a low-order share (CryptoKit, Node), exactly as PAIRING.md treatsK. The check is on the output: every low-order share gives zeros, and nothing else does. - What the keys bind: the token, the version, both prefixes and both shares in role order, and
the direction. So a recorded link cannot be played into a new one (fresh prefixes and shares
change the keys), frames cannot be reflected back at their sender (the direction byte), and a
link cannot be moved to another pair (the key id and the token). The machine ids are not in
the keys:
helloandwelcomecarry them sealed, and a frame cannot be altered without its tag failing. - Forward secrecy. The shared secret never leaves either side, and both ephemeral secrets are forgotten once the keys are made, so a token that leaks later does not open a recording of a link made before. It still lets its holder open new links as either machine, until the pair is removed.
Frames
As version 5:
frame = length (4 bytes, big-endian) || counter (4 bytes, big-endian) || ciphertext || tag (16 bytes)
length = 4 + len(plaintext) + 16, at least 21 (the ciphertext is as long as the plaintext)
nonce = the sealing side's prefix (8 bytes) || counter (the frame's 4 counter bytes, big-endian, as sent)
AEAD = ChaCha20-Poly1305 (RFC 8439), no associated data
- Each side counts its own frames from 1. A receiver refuses any counter that is not one more than the last it accepted. The last frame a side may send carries 2^32 - 1; a sender that needs another closes the link and reconnects.
- The plaintext is one message. A frame may claim at most 16 MiB, except the first each way.
- A frame begins when its first length byte arrives, by a monotonic clock, and must arrive whole within 30 seconds of that byte, whatever its size; one still arriving after that ends the link. Between its bytes the link's liveness still holds (section 3).
- Only a
clipboardis ever larger than 64 KiB of plaintext, and a receiver parses such a frame only where it would take that clipboard: a responder from its owner, an initiator from a peer it let go of no more than 10 seconds before the frame began (section 5, the clipboard). Any other plaintext over 64 KiB is authenticated, so its counter is spent, and dropped unparsed; the link stays up. - Anything that fails (the tag, the counter, a length out of range, a frame past its 30 seconds, a plaintext that is not a message: Encodings) ends the link.
hello and welcome
hello, the initiator's first frame:
| Field | |
|---|---|
version |
the integer 6 |
id |
the initiator's machine id, b64 |
name |
the initiator's name |
platform |
the initiator's platform |
app |
its app version, such as "1.5.0": 1 to 32 printable ASCII characters (0x20 to 0x7E); shown, never compared |
caps |
capabilities, below: a list of at most 16 strings of 1 to 32 printable ASCII characters; one this machine does not know is ignored, and a repeat means the same as one |
port |
integer 0 to 65535: the port the initiator accepts links on, 0 when it accepts none |
hw |
optional: its hardware address on the interface this link leaves from, six two-digit lower-case hex groups joined by colons |
welcome, the responder's first frame, has version, id (the responder's machine id),
name, platform, app, caps, optionally hw, and:
| Field | |
|---|---|
accepts |
true when this initiator may drive the responder (allow_drive), else false |
error |
only in the invalid_hello and wrong_id answers, which have no other field but version |
Each end updates the peer entry from what the other sent: name and platform always, and hw
when it is present (an absent hw keeps the saved one). The responder also takes port from
hello, and host from the address the link came from when port is not 0 and that address
is neither loopback nor link-local, but only when the saved host is empty or host_pinned is
false. Learning into an empty host sets host_pinned false. Pairing writes it false, so an address pairing learnt still follows discovery; legacy entries
without this field are preserved; editing the destination sets it true. A change is saved.
Capabilities say what a machine does with a message it receives:
| Capability | Means |
|---|---|
clipboard |
it takes clipboard text |
clipboard_image |
it takes clipboard images |
gestures |
it acts on gesture |
media_keys |
it acts on the media key names (section 7) |
text |
it types text |
settings |
it receives Same on all machines (settings) |
design_sync |
with settings, it sends and receives direct Design states (settings.data.design_sync) and can be followed |
layout |
with settings, it sends and receives the shared tile picture (settings.data.layout) |
displays |
with layout, it sends and receives each machine's logical display rectangles and display-targeted edges |
ping_rtt |
it sends and answers response-time probes on ping in both directions |
A sender does not send a message its peer's capabilities do not cover. A receiver that gets one
anyway drops it, and still acknowledges it when it carries a seq.
What it does not do
- The key id is in the clear. It is the same on every link of one pair, so anyone on the path can recognise that pair's links on another network, and anyone who can reach a responder can learn whether a key id it has seen is one of its pairs, because it answers that key id and not others. Nothing in the clear links one machine's different pairings, and the machine ids are never in the clear. The key id is a test of its token for anyone who sees it, which is why only tokens made by pairing (256 random bits) are used.
- Handshakes can be crowded out. Anyone who can reach the port can keep the four slots busy, and one who has seen a pair's key id holds a slot for the whole 5 seconds and costs an X25519 each time. Replacing the oldest means a real peer's next try still gets in unless the flood comes from several addresses at once; something on the LAN that can do that can deny service in simpler ways. Two peers behind one address (a NAT) take turns, and the one replaced retries two seconds later.
- A token holder is trusted. Forward secrecy protects recordings from a token that leaks later; it does not stop the holder of a leaked token opening a new link as either machine, or sitting between the two on the path and reading what passes.
- The address is not authenticated. A peer's
hostcomes from pairing, a beacon, a QR, or the source of an authenticated link. Something on the path can point a machine at the wrong address; it cannot read or forge a link, whose keys come from the token.
3. Messages
Initiator to responder:
type |
data |
Carries seq |
|---|---|---|
hello |
section 2 | no |
ping |
{}, or probe or echo (one positive integer identifier, at most 2^31 - 1) |
no |
focus |
section 5 | no |
keydown, keyup |
key, optional us (section 7) |
yes |
mousemove |
dx, dy |
yes |
mousedown, mouseup |
button: left, right, middle, back or forward |
yes |
scroll |
dy, dx, mode |
yes |
gesture |
name: swipe_up, swipe_down, swipe_left, swipe_right, spread or pinch |
yes |
text |
text (section 10) |
yes |
Responder to initiator:
type |
data |
|---|---|
welcome |
section 2 |
ack |
seq, held_us, optional locked (section 9) |
accept |
route (section 5) |
refuse |
route, why (section 5) |
accepts |
accepts (section 4) |
switch |
section 5 |
Either way:
type |
data |
|---|---|
clipboard |
optional text; optional image (standard base64 with padding, of a PNG) with image_format: "png" |
arrangement |
edge, set_at, by (section 8) |
settings |
section 10 |
paired |
ids: list of b64, at most 32 |
seqis indata: an integer from 1 to 2^53 - 1 that each initiator counts from 1 on every new link (and from 1 again on a reconnect) and raises by one per input message. The responder acknowledges the highestseqit has dealt with, whether it injected the message, used it at an edge, or dropped it (section 4). No other message carries aseq.mousemove:dxanddyare integers from -65535 to 65535, relative motion in the sender's logical pixels (points on a Mac) after its own acceleration; positivedyis down. The sender keeps the fractions and sends whole pixels. A phone sends its own points after its acceleration curve. To a peer with themotion_pathcapability, moves merged while the link is behind carrysamples, at most 64[dx, dy]pairs summing todxanddy; past 64 the path collapses to the latest position, one pair. A receiver replays at most four samples near a wall or along a bent drag and moves a longer path in at most two steps, the second from the first wall it reaches.scroll:dyanddxare numbers from -65535 to 65535;modeis"pixel"for a trackpad's continuous delta in points, or"line"for whole wheel notches. Both are in the Mac's convention, as version 5 sends them:dyanddxare Core Graphics' scroll axes 1 and 2 as a Mac reports them, the user's scrolling direction already applied, and a Mac receiver posts them as they stand. Positivedymoves the view up and positivedxmoves it left, measured on macOS 27. A Windows receiver takes positivedyas its wheel's positive and positivedxas its horizontal wheel's negative, since that wheel's positive moves the view right; X11 and libei turndxround the same way, and a Windows or Linux sender turns its horizontal wheel round before sending. Any other sender, a phone included, sends what a Mac would for the same movement. A sender always sends all three; a receiver takes a missingdxas 0 and a missingmodeas"line", as version 5 did.Clipboard limits: text at most 256 KiB as UTF-8. An image at most 8 MiB before base64, and a PNG a receiver can decode without the file deciding how much memory that takes, checked from its bytes before anything decodes it:
- the PNG signature, then an
IHDRchunk of 13 bytes, whose width and height are each 1 to 16384 and whose product is at most 2^25 (33,554,432 pixels: an 8K screen is 33,177,600); - every chunk (4-byte big-endian length, type, data, CRC) inside the file, up to
IEND; bytes afterIENDare ignored, and CRCs are not checked; - a still with one header: no second
IHDR, and none of APNG'sacTL,fcTLorfdAT; - what a decoder inflates besides the pixels, the zlib streams of
iCCP,zTXtand aniTXtwhose compression flag is 1, at most 4 MiB inflated in all. Each stream must be one whole zlib stream ending where its chunk ends: one that is not zlib, is cut short or has bytes after its end counts as over, and so does aniTXtwhose compression flag is neither 0 nor 1, or any of the three without the null bytes that end its keyword (and, iniTXt, its language and translated keyword, when it is compressed).
A few megabytes of PNG can otherwise claim gigabytes once decoded. A sender never sends an image outside these limits, and a receiver drops one, without decoding it. Over any limit, that part is dropped and the rest of the message stands.
- the PNG signature, then an
Liveness. An initiator sends
pingwhen it has sent nothing for a second; a responder'sackheartbeat does the same the other way (section 9). A side that receives no byte at all for 2.5 seconds (a responder) or 2 seconds (an initiator) ends the link. Any byte counts, so a large clipboard frame arriving slowly keeps the link alive while it comes. An initiator also ends a link when its oldest unacknowledged input is older than 1.5 seconds, even if heartbeatacks continue to arrive; phone ports must keep this input-acknowledgement rule in parity.Response time. Only when both identities announce
ping_rtt, each end sends apingwith a freshprobeabout once a second, including during input, and answers aprobewith onepingcarrying itsecho. A ping has at most one of these fields; an echo is never echoed. Empty pings remain valid and compatible with older peers. The sender starts its local monotonic timer when the writer begins sending the probe and accepts only the matching echo on that link. The most recent round trip is available for three seconds; no peer clock is used. This measurement does not change the inputacksamples or watchdog.pairedlists the ids of every desktop peer the sender has in use and not dormant, less the receiver's. A machine sends it only to peers it may send input to (sendtrue), since those are the ones whose Crossing page needs it: after the handshake and again whenever its list changes. The receiver stores it inpaired_with(section 5, the Crossing page).Announcements. After the handshake each end sends
pairedwhen the rule above allows,arrangementwhen this pair has a side, andsettingswhen the other's capabilities listsettings, except for a zero-port phone: phones never take part in shared settings or Match design.Which link. Between two desktops with a link each way,
arrangement,settingsandpairedgo on the link this machine opened when it is up, else on the other. When neither machine may send to the other there is no link, and nothing passes until one exists.
4. Input ownership
A responder has one owner or none. Only the owner's input is injected.
Taking input. An initiator asks for input with a focus whose target is the
responder's own id. The responder decides under one lock, in this order:
- The
routeis not higher than the last this link had accepted: ignored, no answer. The owner has already moved on. - Fields other than
routeandtargetmalformed:refuse {why: "malformed"}. allow_drivefalse for this initiator:refuse {why: "not_allowed"}.- This machine's own input is on another machine:
refuse {why: "busy"}. A machine never drives and is driven at once. - This machine sent this initiator home, or ended its ownership by force, less than 5 seconds
ago:
refuse {why: "sent_home"}. - Another peer is the owner and has sent input within the last 3 seconds, or this is a
stay:refuse {why: "owned"}. - A
stayfrom an initiator that is not the owner:refuse {why: "malformed"}. - Otherwise it accepts, and the initiator is the owner. When it already was, the
focusmoves the pointer or re-arms the zones in place.
The answer, accept {route} or refuse {route, why}, is sent the moment the decision is made,
before the pointer is placed, an arrival plays or a lock screen is dealt with. A focus naming
this machine whose route or target is itself malformed cannot be answered with its route and
is ignored; the owner's wait for an answer (section 5) covers it.
An idle owner can be taken over by a new take at or after 3 seconds without valid input
received from that owner. The responder measures this with its own monotonic clock, starting
when ownership begins. Re-arms, clipboard messages and heartbeats do not renew activity.
It sends the old owner switch {route, next: old owner, taken_over_by: new owner}, ends the
old ownership and releases held input before accepting the new owner. Late input and let-go
messages from the old owner cannot affect the new ownership. The old owner is refused
sent_home for 5 seconds, as with an ordinary send-home.
What a non-owner's messages do:
| Message | From the owner | From anyone else |
|---|---|---|
input (seq messages) |
injected | dropped, acknowledged |
clipboard |
set on this machine | dropped |
focus naming this machine |
as above | as above |
focus naming another machine |
the owner lets go | ignored |
ping, arrangement, paired |
handled | handled |
settings |
handled if its caps list settings |
the same |
Ownership ends when the owner sends a focus naming another target; when its link ends for
any reason or is replaced by another from the same peer; when the user removes the peer or turns
its allow_drive off; and by force, when this machine sent the owner home and it has not let go
within 1 second; or when another peer takes over the idle owner. Every time it ends, the responder:
- releases every key and button it injected for that owner, before injecting anything else;
- drops its armed zones;
- on a let-go
focusonly, sends the owner its own clipboard when something other than aclipboardmessage changed it while that owner drove (section 5, the clipboard); - when it ended in any way but a let-go
focusor an idle takeover and the link is still up, sendsrefuse {route, why}on it (not_allowedwhenallow_drivewas turned off,sent_homewhen it was ended by force), and from then on drops that link's input, still acknowledging it, until afocusof its is accepted again.
The owner, for its part, sends keyup and mouseup for everything it pressed and has not
released on that link before the focus that lets go, and swallows the physical releases that
follow. The other way round, a key or button pressed on the owner while its input was at home is
released at home: its release, and nothing else of it, stays there when it comes after the input
has left. The responder's release is the backstop for a link that dies or an owner that misbehaves.
Per link. Each responder link keeps its own seq count, its own ACK timer, its own last
accepted route, and its own record of keys and buttons held. Each initiator link keeps its own
seq count, its own unacknowledged sends and round-trip samples, and its own record of keys held
down on that peer. A machine's route counter is one.
accepts, responder to initiator, {accepts: bool}: sent whenever allow_drive for that
initiator changes, so an owner or a phone knows at once rather than at its next link.
A machine that is driven does not drive. When a desktop that is owned is asked to send its
own input elsewhere (its shortcut, its edge, a menu), it sends its owner home (section 5) and
waits up to 1 second for the owner to let go, ending the ownership by force if it does not; then
the move it was asked for goes ahead. A desktop whose own input is on another machine refuses to
be taken (busy), counting from the moment it sends a taking focus until that take is refused,
times out or is let go. Two desktops that try to take each other at the same moment are both refused
and both stay at home, and the next try works.
5. Routing
focus, accept, refuse and switch
focus, owner to responder:
| Field | |
|---|---|
route |
integer, 1 to 2^53 - 1 |
target |
b64: where input is going. The responder's own id means here; any other id means the responder is being let go |
edge, offset |
where to land the pointer: left, right, top or bottom, and how far along that edge of the responder, any number, which the receiver clamps to 0.0 to 1.0 (never malformed for its range) |
display, side |
optional pair naming the responder's display key and the side to land on; an unknown display falls back to edge and offset |
resistance_px |
integer 0 to 1000: how far the owner's hand must push through a zone on the responder |
reach |
list of b64, at most 32, no repeats: the peers the owner can send input to now, less the owner and the responder |
stay |
true: re-arm in place; land nothing, play nothing |
Which fields each kind of focus has:
| Kind | edge, offset |
resistance_px |
reach |
stay |
|---|---|---|---|---|
| take, by a zone | both | yes | yes | absent |
| take, by the shortcut or a menu | neither | yes | yes | absent |
| re-arm in place | neither | yes | yes | true |
let go (target another machine) |
neither | absent | absent | absent |
A take without resistance_px uses 120, and a phone, which has no hand at an edge, may leave it
out. A take or re-arm without reach has an empty one. A reach that names the owner or the
responder has those ignored. edge without offset, offset without edge, or stay with
anything but true, is malformed; on a re-arm edge and offset do not belong and are ignored.
display and side must appear together; display is 1 to 64 ASCII letters, digits, _, ., :
or -, and side is one of the four edge names. Older peers ignore both optional members.
accept, responder to the initiator whose taking focus it accepted: route.
refuse, responder to an initiator whose taking focus it did not accept: route, and why,
one of "owned", "not_allowed", "busy", "sent_home" and "malformed". A valid route is
all a refuse needs: one whose why is missing, not a string, or another string is not
malformed, and the initiator acts on it at once as a refusal it cannot name.
A refuse may also carry other, a machine id: with owned, the owner that holds the
responder; with busy, the machine the responder's own input is on. The responder includes it
whenever it knows that machine's id, and never with any other why. It is there so the initiator
can say which machine is in the way ("Can't cross to Bee: it is being driven from Sea"); the
initiator names it by its own peer entry for that id, and as another machine when it has none, or
when other is not a valid id or is the initiator's own, in which case it is ignored and the
refusal still stands. A version 6 machine from before 1.5.0-beta.5 ignores it, as it ignores any
unknown key (Encodings).
switch, responder to its owner only:
| Field | |
|---|---|
route |
the last route the responder accepted from this owner |
next |
b64: where input should go. The owner's own id means home |
edge, offset |
where to arrive on next, both or neither, as in focus (offset clamped, never malformed for its range) |
display, side |
optional pair naming next's display key and the side to arrive at; an unknown display falls back to edge and offset |
taken_over_by |
optional machine id on a switch home: the new driver that took over the responder after the old driver became idle |
Older peers ignore taken_over_by and obey the switch home as usual. New peers use a valid
id only on a switch home to say " took over " through their usual
notice; an unknown machine is named "Another machine". An invalid optional id is ignored.
The route
The owner keeps one route number for all its links, 0 when it starts. It raises it by one every
time it moves its input or re-arms in place, and every focus of that move carries the new
number: the focus letting go of the machine it leaves and the focus taking the machine it
goes to carry the same route. The owner remembers which machine its input is on (none, when at
home), the current route, and the reach it last sent there.
The owner acts on a switch only when it comes from the machine its input is on and carries the
current route. Anything else is ignored: it was sent before a move that has already happened, so
acting on it would move input a second time. One exception: a switch whose next is the owner,
from the machine its input is on, is honoured when its route is at least that of the take that
began the current visit, so a machine that sends its owner home while a re-arm is crossing it is
not left holding the input, and a send-home left over from an earlier visit still is not obeyed.
What the owner does with a next it cannot follow is below.
The responder ignores a focus whose route is not higher than the last it accepted on that
link (section 4). Routes on different links are not compared.
Input comes home
One procedure, used everywhere below: the owner raises the route, sends the machine its input
was on focus {route, target: owner} if that link is still up, leaves its own pointer where it
was captured unless an edge and offset say where to land it, and swallows the releases of
keys it had sent there. A phone simply stops driving. It is used when:
- a
switchnames the owner; - the owner's own shortcut, menu or edge brings it home;
- a
refusearrives for the current route from the machine its input is on, or a take from home has had no answer for 1 second; - the link to that machine ends for any reason, a send that fails included, or its watchdog fires (no byte for 2 seconds).
Each says why, naming the machine: "name is being driven from another machine", "name does not accept input from this one", "name is driving another machine", "name sent the input back", "Lost the link to name".
Moving input
From the owner's own screen, from home, or by its own shortcut or menu. A desktop's pointer
pushes through one of its zones (section 8) to peer P, or the shortcut or a menu picks P, whether
the input is at home or on another machine B. The owner raises the route. When the input is on
B, it first lets go of B: B's releases, then focus {route, target: P} to B. Then it sends P the
taking focus, then its clipboard, then input, without waiting: a refusal sends the input home,
not back to B, and whatever reached P in the meantime was dropped there. No answer within 1
second also sends it home. A phone picking a machine does the same.
Onward from the machine being driven. While owned, a responder watches its own pointer, as
version 5's return edge did. It arms each of its own zones whose peer is the owner or is in the
owner's latest reach, at the owner's resistance_px, and nothing else. When the pointer pushes
through a zone to peer N, it sends the owner switch {route, next: N, edge, offset}, with edge
and offset where that zone lands the pointer on N. It then disarms its zones and waits; input
that arrives in the meantime is injected. The zones cannot tell the owner's motion from the
machine's own mouse, so a local push through a zone sends the owner onward too, as in version 5.
What the owner does with that switch, input being on B:
nextis the owner: input comes home, landing atedgeandoffset.nextis a peer N that was in thereachlast sent to B, and the owner still has a live link to N and may send to it: the owner raises the route and sends N the takingfocus. It holds its input, sending it nowhere, until N answers. B is not let go yet, so it keeps the input if N does not take it.- On
accept, it sends Bfocus {route, target: N}, then N its clipboard and the held input. - On
refuse, or no answer within 1 second, it raises the route again, sends Bfocus {route, target: B, stay: true, resistance_px, reach}with a freshreachthat leaves N out for the next 3 seconds, sends B the held input, and says N could not be reached. - Anything else that moves the input while it waits (a send-home from B, a lost link to B, the owner's own shortcut or menu) ends the wait and cancels its timer.
- A take given up closes N's link. When the wait ends with no answer from N, by its 1
second or by anything above, the owner closes the link it opened to N before it sends
anything else, then goes on as that event says. N may have accepted already with its
acceptheld up on the path; the close ends that ownership (section 4), so N is never left owned by an owner that drives elsewhere. N is out ofreachuntil its link is up again, and the owner acts on nothing more that arrives on the closed link, anacceptit had already read included. The one exception is the owner's own shortcut or menu picking N itself: that take follows the first on the same link, and its answer is the one awaited. - It ignores an
acceptwhose route is not that of a take it sent. Anacceptfor a take from home or by the shortcut that comes after its wait ended is answered with a let-gofocuscarrying the owner's current route and naming wherever its input is now (its own id when home); that take's own let-go has gone on the same link already, so this one changes nothing.
- On
nextis anything else (outside thatreach, or a link that has dropped since): the same as a refusal from N, without asking N.
Keeping reach true. When the set of peers the owner can send to changes while its input is
on a machine (a link comes up or drops, an accepts arrives, or a peer left out after a hand-over
that failed has had its 3 seconds), it raises the route and sends that machine a stay with the
new reach. While it waits on a hand-over it sends none; the stay or the take that ends the
wait carries the reach as it is then, and one more stay follows an accept if the reach for
the new machine changed during the wait.
Sent home from the driven machine. A responder's own user can always send the owner home:
its shortcut, a menu, a direction switch turned off, or Windows locking (as version 5). It
disarms its zones and sends switch {route, next: the owner} without edge or offset, and the
owner's input comes home. If the owner has not let go within 1 second, the ownership ends by
force (section 4).
Chains need a direct link from the input to every machine
A to B to C works like this, with the keyboard on A: A drives B; B's pointer reaches B's zone for
C; B sends switch {next: C} to A; A takes C and lets go of B. A needs its own link to C. B never
relays A's input: it would sit in the path of every keystroke meant for C and would need a second
layer of encryption. So a chain is a full mesh of pairings from wherever the input is: three
desktops take three pairings, and a phone that drives all three takes three more.
Because each machine configures only its own zones, and each zone names only the peer beyond it,
no machine needs the whole layout. The owner follows switch and needs no model of the screens,
which is what lets a phone drive a chain.
What the Crossing page may offer
A machine M can offer a zone to peer P when M is paired with P. It can check the rest from the
paired lists it holds: for each machine that may hold input while M is driven (M itself, and
every peer with allow_drive true), whether it is paired with P. The first design let M offer
a zone only when every one of them is. That is open question 3, built as its recommendation in
1.5.0: reach already stops a zone firing for an owner that could not follow it, so the zone is
offered, and the page names each machine that may drive M, has linked, and is not paired with P.
A zone never leads to a phone.
Which machine the shortcut picks
The shortcut, a Send button and a menu's own item with no machine named send input to the machine it was last on, while that one can take it (its link is up and it accepts input); else to the first in the list of peers that can; else to the first this machine sends to at all, so the refusal or the wake names it. Never to a phone, or to an entry with no id yet. A menu item that names a machine sends input there, from home or straight from the machine it is on.
The clipboard follows the input
- When an owner takes a machine, it sends its own clipboard after the taking
focus(in a chain, after theaccept) and before any input, unless that machine is known to hold it already: the clipboard went there or came from there, and has not changed here or come from another peer since. So something copied on B and brought home reaches C when C is taken next, and is never sent back to B. - When a machine is let go by a
focus, it sends its clipboard to the owner only when something other than aclipboardmessage changed it while that owner drove, so what the owner brought is never echoed back. It never sends one otherwise, so a paired device cannot collect a clipboard by taking and letting go of an idle machine. - An initiator takes a clipboard only from a machine it has let go of, once per let-go, when its frame begins (its first length byte arrives, section 2) within 10 seconds of that let-go; any other is dropped. Like any frame it then has 30 seconds to arrive whole. A later move (a refusal from the next machine, say) does not cost the machine let go its one clipboard. It sets it on itself (a desktop) or keeps it (a phone), and sends it on to the machine its input is on now, if any. That is how something copied on B reaches C in a chain, through A, and it leaves it on A's clipboard, as it would if the input had come home.
- In a chain, B's clipboard reaches C a round trip after C was taken, so a paste in that moment gets C's older clipboard. Holding the input for it would add that round trip to every crossing in a chain; version 6 does not.
- Version 5 sent the clipboard before
focus. Version 6 sends it after, because a responder takes a clipboard only from its owner; the input that follows it on the same link is still behind it.
A phone
- A phone is an initiator only. A desktop's entry for a phone has
port0,host""andsendfalse, and is never dialled; itsallow_driveis the switch that lets the phone drive. - A phone has no side, zones, jump key or wake-on-LAN address. Desktops ignore its
arrangementandsettingsmessages, even if it advertisessettingsordesign_sync. - A phone's entries for desktops have
sendtrue andallow_drivefalse. It learns from eachwelcome'sacceptswhich desktops it may drive, and leaves the others out ofreach. - A
switchwhosenextis the phone means stop: the phone lets go withfocus {target: phone}and drives nothing until the user picks a machine.edgeis ignored. - A phone may leave
resistance_pxout; the desktop's zones then push at 120. - A phone that cannot hear beacons finds a desktop whose address changed by scanning its QR again (section 6).
6. Pairing in 1.5.0 (pairing version 3)
The exchange is PAIRING.md's, CPace with the code as the password, with these changes:
Version and labels. Beacons say
pairing: 3,pair_startsaysv: 3, CI isb"beamer-pair-v3", and the token's HKDF info isb"beamer-pair-token-v3". The rest of the computation, the four messages, rules 1 to 10 and the encodings are PAIRING.md's.Identities. Each side's identity is its 16-byte machine id:
requester_idin ADa andhost_idin ADb. Apair_startorpair_answerwhoseidis not exactly 16 bytes, or is all zero, is refused.What the exchange proves.
pair_startandpair_answereach gainplatformandport(the sender's link port, 0 for a phone), and both go into the associated data:ADa = lv_cat(b"requester", requester_id, requester_name as UTF-8, requester_platform as ASCII, requester_port as 2 bytes big-endian) ADb = lv_cat(b"host", host_id, host_name as UTF-8, host_platform as ASCII, host_port as 2 bytes big-endian)So everything pairing saves about the other machine is proved, except its address.
Checking the identity received, as the CPace draft's section 10.1.1 requires:
- The requester, once
Tbchecks out, refuses when the host's id is its own or belongs to any of its peers, except as the replacement below allows. It sendspair_confirmwithtag: ""anderror: "known", once, stores nothing, and says the machine is already paired, naming the entry and when it was paired. - The host, once
Tachecks out, refuses the same way:pair_donewithok: falseanderror: "known", and the code is dropped. Apair_confirmcarryingerror: "known"is unauthenticated, so it cannot be told from a wrong code ended the same way; the host's window says "That machine may already be paired here, or the code was wrong." - An entry that has never linked (
linkedfalse), was made by pairing less than 10 minutes before, and has the same name and platform as the new pairing proves, is replaced by it rather than refused, so a pairing whosepair_donewas lost can be done again at once. Any other match isknown. - The entry migrated from 1.4.x (
from_1_4true), which never links (section 1), is replaced by a pairing that proves its id, when an earlier beta linked it and so learnt one; and, when it hasid: "", by a pairing that completes with the machine at its savedhost(the addresspair_startcame from, for the host; the address it reached, for the requester), or that proves itsnameandplatform. It is replaced, never counted, under the rule in item 5. A pairing with the machine at its savedhostthat proves the entry'splatformtakes over itsside,side_set_at,side_byand zones: every 1.4.x upgrader pairs again, since no 1.4.x token migrates, and is at the screen pairing that machine on purpose, so the arrangement should not have to be set twice. A match by name alone takes nothing, and the entry's zones go with it: pairing proves the code, not which machine that entry was, and anyone who saw the code can claim a name, which is safe only because the entry never links and nothing of it carries over. - To pair two linked machines afresh, the user removes each from the other's list first. Re-pairing never replaces a linked peer's token.
- An id proves only that it arrived unaltered, not that the machine sending it owns it.
Someone who sees a code can pair under another machine's id and name, which that machine's
own pairing will then find
known. The window naming the entry and its date is how the user tells.
- The requester, once
Storing. The host writes the new peer entry before it sends
pair_done, and sendsok: falsewitherror: "refused"if the write fails, soTdnow proves the host saved the token. The requester writes its entry afterTdchecks out. Each side first computes the new token's key id (section 2): when it is already one of its entries' key ids, the host sendsok: falsewitherror: "refused"and the requester stores nothing and says pairing failed. With a fresh 256-bit token that never happens; the check keeps key ids unique whatever the entries hold. A clash the requester finds afterTdleaves the host holding an entry that never links, which is the lost-pair_donecase above: pairing again within 10 minutes replaces it.Beacons. A beacon carries
platform, and carriesid(b64) only while a code is up, so a machine does not broadcast a stable id on every network it joins.The QR's secret. With every code it shows, the host draws 16 random bytes, the code's QR secret, shown only inside the QR (below) and dropped with the code. A requester that read the code from a QR sends
qr: 1inpair_start, and a requester that was typed the code sends noqr. The host takes the password frompair_startalone:pair_startPRS no qrthe code, six ASCII digits (6 bytes, as PAIRING.md) qr: 1the code's six ASCII digits followed by the QR secret's 16 raw bytes (22 bytes) qrwith any value but the integer1makespair_startmalformed. Nothing else changes: the generator's zero padding follows PRS's length by PAIRING.md's formula (zis 95 for the 22-byte form), andqris not in ADa, since aqrstripped or added on the path makes the two passwords differ and the exchange fail atTaorTb, which costs the code (rule 1) and nothing else.What it buys: an exchange that uses the QR secret gives someone on the path no useful guess, where the code alone gives one in a million a side. It does not close the typed path: while a code is up, anyone who guesses it may still try one
pair_startwithoutqr, with the same one in a million as before, and rule 1 then drops the code.
New errors:
error |
In | When |
|---|---|---|
known |
pair_done, pair_confirm |
the other side's id is already one of this machine's peers' (bar the replacement in item 4), or this machine's own |
full |
pair_answer |
the host reached 32 peers while this code was up; the code is dropped |
A host with 32 peers shows no code, and a requester with 32 does not start. That holds when one
of the 32 is an entry a new pairing would replace (a lost pair_done, or the one migrated from
1.4.x): the user removes a peer first. A known limit, left as it is. Pairing versions 2
and 3 never pair: a 1.5.0 requester shown a pairing: 2 beacon says the other machine runs an
older Beamer before sending anything; a 1.5.0 host answers a v: 2 pair_start with version
and drops its code; a 1.4.3 requester shown a pairing: 3 beacon says the versions differ. This
protects a 1.4.3 machine from having its one pairing overwritten by a 1.5.0 requester that could
not then use it.
After pairing, each side's peer entry holds the other's id, name, platform and port as
the exchange proved them, the token, paired_at, linked false, send and allow_drive true
(for a phone, as section 5 says), side empty, and host: the requester saves the address it
reached the host at, and the host the address pair_start came from, unless the requester's
port is 0.
Either end
Every desktop both announces and discovers. Each sends a beacon every 2 seconds to UDP 24821
while it runs, with pair and id only while a code is up, and each keeps the list of machines
it hears. Any desktop can show a code (and be the host) or enter one (and be the requester).
Finding a peer whose address changed. Only entries with host_pinned false follow beacons.
A chosen address, including a legacy saved address whose provenance is unknown, is never
replaced automatically. If it changes, edit the destination or pair again.
When the link to an eligible peer with send true has been down
for 10 seconds, a desktop tries a link at the source address of a beacon carrying that peer's
exact name, at the peer's saved port, and saves the address only once that link authenticates.
It never tries a beacon with another name, nor one whose id is not the peer's; one at another
paired machine's saved address it tries after the rest, since two machines may have swapped
addresses. With several such beacons it tries them in turn. It tries at most one address per peer every 30 seconds,
and shows nothing when a try fails. A forged beacon can therefore cost one failed connection attempt every 30 seconds, never
a saved address and never a message that prompts the user to pair again.
Pairing over TCP, from a code
Broadcast does not cross subnets or VPNs, and an iPhone needs an entitlement Apple grants on application to send or receive it. So a host also accepts the exchange over TCP, on port 24821, while a code is up and only then.
- Framing. Each message is a 4-byte big-endian length, 1 to 1024, then the same JSON object a
datagram would carry,
beamy: 1included. The desktops write it compact, with every character outside ASCII escaped as\uXXXX; a receiver accepts any spelling of the same JSON, since the exchange binds the decoded name and id, never these bytes. - Order. The requester connects. The host sends its
beaconat once (withpairandid); the requester checks it sayspairing: 3and sendspair_startwith thatpair; the host answerspair_answer; the requester sendspair_confirm; the host sendspair_doneand closes. A side that refuses sends its refusal first (pair_answerorpair_donewithok: false, orpair_confirmwithtag: ""), then closes. Anything out of order, or a secondpair_start, closes the connection with nothing sent. - Limits. A connection has 10 seconds from being accepted to finish. The host holds at most four such connections at once and one per address, on the same terms as the link's handshakes. The requester's connect times out after 3 seconds.
- One exchange per code, across both transports. The UDP and TCP paths share the one pairing
host, so rule 1 holds whichever way the first
pair_startcame. Rules 2 to 10 hold unchanged; the requester's memory of failed codes (rule 3) covers codes it sent either way. - The exchange under way is left alone. Once a
pair_starthas bound the code, the host takespair_confirmonly from the address thatpair_startcame from (over TCP, only on its connection), and ignores any other without an answer; and the connection that bound the code is never the one a new connection replaces. - Checking and storing are one step. A machine may host one pairing and request another at
once. Each side makes its
known, key id and 32-peer checks and writes its entry under one lock shared by both roles, so two pairings finishing together cannot pass 32 peers or leave two entries with one id. The host answers a count reached sincepair_startwithpair_done,ok: false,refused. - The fixed answer time of 50 milliseconds applies as it does over UDP.
The code on the screen. While a code is up, each desktop's pairing sheet shows it as six digits with this machine's address, and as a QR code of this text:
beamer://pair?host=<address>&port=<port>&code=<code>&k=<secret>
hostis a dotted IPv4 address, since the link is IPv4 only: the machine's address in a private range (10/8, 172.16/12, 192.168/16) when it has one, preferring the interface of its default route, and otherwise the default route's.portis 24821 in decimal. It is carried so a later version can move it. A number has one spelling, decimal digits with no sign and no leading zero, and so has each octet ofhost.codeis the six digits.kis the code's QR secret asb64: exactly 22 characters, one spelling (Encodings).- The four keys come in that order, lower case, each once, with nothing else. A reader refuses
any other text, a QR without
kincluded. The text is read as it is, with no percent-decoding. The pairing sheet never showskas text.
A desktop can pair the same way by typing an address and a code: "Pair by address". That path
has no QR secret and sends no qr.
A phone that scans the QR of a desktop it is already paired with (the id in the host's TCP
beacon is a peer's) does not pair: it closes the pairing connection, tries its link at that
address, and saves the address once the link authenticates. That needs someone at the desktop to
show a code; finding a moved desktop without that (Bonjour, say) is left to the phone apps.
7. Keys
Names
A key travels as key, a name, in keydown and keyup:
A character key sends the character its layout types, as a string of exactly one code point, with Shift applied:
"A"with Shift down,"a"without. While Command, Control or Alt (not Shift) is held, it sends the key's own unshifted character from its layout instead, so Option-V on a Mac is"v"and not"√", and a German keyboard's Command-Z is"z". Numpad keys use the separate keypad names below. When Windows cannot compose a dead key and the next character into one code point, it sends the visible sequence throughtextinstead; a held base key repeats its character astextand its physical key-up remains swallowed.usis sent beside a character: the unshifted, lower-case character the same key position types on a US layout, for a receiver whose layout cannot typekey. A key with no US character (on a JIS keyboard, say) sends none.Any other key sends one of these names:
Group Names Modifiers shift,shift_r,ctrl,ctrl_r,alt,alt_r,cmd,cmd_r,caps_lockInput method hangul,hanjaEditing and movement backspace,tab,enter,esc,space,delete,insert,home,end,page_up,page_down,left,right,up,downFunction f1tof24Windows keys menu,print_screen,pause,num_lock,scroll_lock,browser_back,browser_forward,browser_refresh,browser_stop,browser_search,browser_favourites,browser_home,mail,media_select,launch_app1,launch_app2Media ( media_keys)volume_mute,volume_down,volume_up,media_next,media_prev,media_stop,media_play_pause,brightness_up,brightness_down,mic_muteSystem actions search,spotlight,dictationKeypad keys use
numpad_0throughnumpad_9,numpad_decimal,numpad_add,numpad_subtract,numpad_multiply,numpad_divide,numpad_enter,numpad_equalandnumpad_separator. These preserve physical identity, including with Num Lock off; the receiving machine's lock state determines the key's action. Both peers need the keypad fix; older receivers drop these unknown names. Main Return remainsenter.hangulandhanjaare HID Lang1 and Lang2. On a JIS Mac they share the Kana (0x68) and Eisu (0x66) keycodes; on Windows they share VK_KANA and VK_KANJI. A Japanese keyboard's Kana key therefore travels ashangul, which is accepted because it lands on the same Windows VK.keyupcarries the samekeyandusas thekeydownit releases, even if Shift changed in between. Auto-repeat is morekeydowns with nokeyupbetween them.caps_lockis sent as akeydownand akeyuptogether on each press.hangulandhanjause the same tap rule: each physical press sends both messages, and the physical release sends nothing.On the receiver,
ctrlis Control,altis Option or Alt, andcmdis Command on a Mac, the Windows key on Windows and Super on Linux. It types a character as given, pressing or releasing Shift around it as its own layout needs, and falls back touswhen its layout has no key for the character. A name it cannot press is dropped; a receiver withouthangulorhanjadrops them in the same way as any unknown name.A phone has no physical keys to map. It shows a modifier row named for the platform it is driving and sends names directly: Command-C to a Mac is
keydown cmd,keydown "c"withus"c",keyup "c",keyup cmd.
Which physical key sends which name
The machines fall in two families: the Mac (macos, ios), and the PC (windows, linux,
android, and any unknown platform). Between two machines of the same family every key goes out
as itself. Between the two families, the sender applies its user's saved style:
| Physical key on the sender | Same family | Across, Semantic (the default) | Across, Positional | Across, Mac keyboard layout (PC sender only) |
|---|---|---|---|---|---|
| Mac Control | ctrl | cmd | ctrl | — |
| Mac right Control | ctrl_r | cmd | ctrl | — |
| Mac Command | cmd | ctrl | cmd | — |
| Mac right Command | cmd_r | ctrl | cmd | — |
| Mac Option | alt | alt | alt | — |
| Mac right Option | alt_r | alt | alt | — |
| PC Control | ctrl | cmd | ctrl | ctrl |
| PC right Control | ctrl_r | cmd_r | ctrl_r | ctrl_r |
| PC Windows or Super | cmd | ctrl | cmd | alt |
| PC right Windows or Super | cmd_r | ctrl_r | cmd_r | alt_r |
| PC Alt | alt | alt | alt | cmd |
| PC right Alt or AltGr | alt_r | alt_r | alt_r | cmd_r |
- Semantic makes the everyday shortcuts line up: Command-C on a Mac arrives as Control-C on a PC, and Control-C on a PC as Command-C on a Mac. Positional keeps each key in its place. Mac keyboard layout maps a PC keyboard's modifiers to the corresponding Mac keys by their positions.
- The Mac's rows across families are 1.4.x's
DEFAULT_KEY_MAPandLEGACY_POSITIONAL_KEY_MAPas they stand, sides folded. The PC's are Windows' capture names and 1.4.x'sPOSITIONAL_SWAP. Same family is new: the Mac as itself with its sides kept (the first design named the folded positional map), and Windows' capture swapped back, since the Windows receiver presses the Windows key forcmd. - The saved style is the Mac's
key_map(a style name, or a map a user wrote by hand, which applies across families only) and Windows'modifier_style. Both survive the migration. A Linux app keepsmodifier_styleas Windows does. - The PC keeps
modifier_stylelocally; it is not sent to peers or shared by Same on all machines. Key messages contain only the resulting key names, which older peers already understand. A settings file without this field defaults to Semantic. - A Linux sender reads keys by evdev code:
KEY_LEFTCTRLandKEY_RIGHTCTRLare PC Control,KEY_LEFTMETAandKEY_RIGHTMETAWindows or Super,KEY_LEFTALTAlt andKEY_RIGHTALTright Alt or AltGr. A Linux receiver presses the same codes for the same names.
8. Zones
A zone is part of this machine's screen that leads to one peer:
{"peer": "<b64>", "kind": "edge"}
{"peer": "<b64>", "kind": "part", "parts": ["start", "middle"]}
{"peer": "<b64>", "kind": "corner", "corner": "top_right", "edge": "right"}
{"peer": "<b64>", "kind": "notch"}
Any zone may also carry "off": true, which keeps it in the list and out of use. peer is ""
only for the entry migrated from 1.4.x, which never links. A zone never names a phone.
- Which edge a zone crosses. An
edgezone is the whole of its peer'sside, and apartzone is some of its thirds (start,middleandend, top to bottom or left to right), so changing the side moves them. Acornerzone names its corner and the edge it counts as crossing, one of the two that corner touches. Anotchzone is the Mac's notch and crosses the top edge. These are 1.4.x's rules: its corner and notch could lead to the PC through an edge other than the one facing it, and a zone keeps that. The migration never changes where a pointer lands, so it writes what 1.4.x did: a Mac's corner zone crosses by the corner's own left or right edge whatever the side (the way home, which is not a zone, uses the side), and a PC's corner zone crosses the side (1.4.x built its corner push with the return edge), or the corner's own left or right edge while no side is set. An app with no control for a corner's edge writes the same again on every save. - Where the pointer lands. At the peer's edge opposite the one crossed, at the fraction along
it where the pointer left. A
cornerzone lands at the end of that edge nearest the corner: 0.0 for a top or left end, 1.0 for a bottom or right one. - What they measure. The thirds and corners are measured as 1.4.x measures them
(
return_edge.py): a third against the display the pointer is on, a corner in an 8-pixel box that wins over the edge it sits in. - Order and overlap. Corners are checked first, then edges, then parts, then the notch, and the
first that holds the pointer wins. Apart from a corner inside an edge, two zones in use never
cover the same stretch: the settings refuse a list where they would, and an
arrangementthat would make two overlap is applied and turns the clashing zones for the senderoff, with a notice naming both machines. The exception is a machine with no link up at that moment, in either direction: its clashing zones are set aside instead (offand"aside": true), with a notice saying it is not connected, and the same holds when the user gives a machine a side or a way on the Crossing page, which then offers no thirds of a side held only by such a machine. A machine that is only asleep must not lose its layout: when it links, a zone set aside is put back in use, unless another zone in use covers that stretch, when it staysofflike any other clash. Only a machine whose link reports that it no longer has this pairing (section 2, initiator step- keeps its zones
offfor good, and the app says so in its window, not only in its log. Any edit of the zone by the user clearsaside. An edge, part or corner zone that the Crossing page turns off also carries"page_off": true, scoped or unscoped; layout compilation keeps the contact off until the page turns that way back on, including when display metadata is absent. The mark leaves with a contact the tile has left. Thirds picked on the page are kept as"page_parts"on the peer's unscopedpartzone, and each contact layout compilation writes keeps the thirds it touches as"contact_parts"; a contact crosses only by the picked thirds it touches, all three being the whole edge. Both are local marks: no new message, capability or protocol version. A zone's stretch is its peer'ssidefor anedgezone, the chosen thirds of it for apartzone, and the corner for acornerzone; thenotchis a stretch of its own, which only anothernotchzone covers: it fires on a dwell and 1.4.x let it stand beside the edge, but a Mac has one notch, so it leads to one machine. 1.4.x let the edge and the thirds both be on, where the edge covered the thirds, so the migration and a save of those methods write the thirdsoff. Two machines may share one side by thirds.
- keeps its zones
- Every machine starts with its whole edge. Pairing gives the new machine an
edgezone, and so does anarrangementfor a machine that has no zone yet, and so does reading a settings file in which a paired desktop has none (pairing made no zones before 1.5.0-beta.5). On a Mac with one desktop machine paired and no side for it, Beamer holdsrightunstamped and with no author, as the Crossing page shows, so the edge crosses from pairing and a side either machine chooses wins over it. Anedgezone whose side another zone in use already covers is writtenoff, so the file stays one the settings accept. A machine with a side and no way in, because another machine holds that side, is named on the Crossing page with the machine that holds it. - A peer with no zones can still be reached by the shortcut and the menus.
- The same list, both ways. A machine's zones are where its own pointer crosses when its own hardware drives, and where a driven pointer is sent onward or home (section 5).
- Never shared. Zones and the direction switches belong to the machine that has them, and no
message carries them. Only a pair's
sideis kept in step between the two, byarrangement.
arrangement says which of the sender's edges faces the receiver: {edge, set_at, by}.
edge is left, right, top or bottom; set_at an integer of unix seconds; by the
machine that made the change. The receiver sets its own side for the sender to the opposite
edge, and stores set_at and by as side_set_at and side_by, when the message is newer
than what it holds: a higher set_at, or the same set_at and the larger by compared as
bytes. It ignores one whose set_at is more than a day ahead of its own clock, or above
2^53 - 2. A change made here is stamped with the current time, and never lower than the stamp
held plus one. A side is never cleared by message. A machine with three peers keeps three sides,
each settled with that one peer.
arrangement may also carry way_back, a boolean: whether the sender has a zone in use, and
able to fire (an edge or part zone of a side that is set, a corner or a notch), that leads
to the receiver. The sender includes it every time it sends an arrangement: when the link comes
up, when it changes that machine's side or zones, and, once it has applied an arrangement from
that machine, in answer, so the machine that set the side learns at once that it was taken but
leads nowhere. The receiver keeps the last one it was told as way_back on the sender's entry,
whether or not the side in the same message was newer, and its Crossing page names the sender as
having no way back while it is false. An answer is sent only after an arrangement that changed
something here, so two machines never answer each other in turn. A version 6 machine from before
1.5.0-beta.5 ignores it, as it ignores any unknown key (Encodings).
With way_back false, arrangement may also carry way_back_by, a machine id: the machine
whose zone in use already covers the sender's side for the receiver, which is why the sender's own
zone there was turned off (Every machine starts with its whole edge, and Order and overlap). The
sender includes it whenever one such machine holds that side, the first in its zone list when
several do, and never with way_back true or absent. The receiver keeps it as way_back_by on the
sender's entry beside way_back, and drops it whenever an arrangement from the sender carries
way_back without it; one that is not a valid id, or is the receiver's own, is ignored as if
absent. With it, the receiver's Crossing page says which machine is in the way ("Bee has Sea on its
left too"), naming it by its own entry for that id and as another machine when it has none. A
version 6 machine from before 1.5.0-beta.5 ignores it, as it ignores any unknown key (Encodings).
From 1.4.x's settings. The migration turns the one pair's ways across into zones for its one
peer, one of each kind, with off set for each method that was not on: an edge zone; a part
zone with the saved thirds, off as well when the edge is on; a corner zone with the saved
corner, crossing the edge the rule above gives; and, on the Mac, a notch zone.
shortcut in the methods sets the machine's shortcut. So the one-machine Crossing page turns a
way across on and off by off, and finds the thirds and corner it had.
9. The round trip
Every ack says how long the responder held it:
| Field | |
|---|---|
seq |
the highest seq dealt with on this link, 0 before any |
held_us |
integer microseconds from dealing with that seq to sending this ack, 0 to 2^31 - 1; the sender clamps to that range |
locked |
true while Windows clears its lock screen and drops input; absent otherwise |
- An initiator ends the link on an
ackthat is malformed, whoseseqgoes backwards, or whoseseqis higher than any it sent: the stream cannot be trusted. - An
ackwhoseseqis higher than the last one gives one sample:round trip = (now - when that seq was sent) - held_us, and 0 if that is below 0. Anackthat repeats aseqgives none, and carriesheld_us: 0. The owner measures every link that carries its input, a phone included. - When the responder acknowledges, timed from the last
ackit sent on that link: input dealt with 15 ms or more after it is acknowledged at once; input dealt with sooner is acknowledged 15 ms after it, in oneackfor everything up to then; and with no input, anackgoes 0.4 seconds after the last, as a heartbeat. 1.4.x held everyack15 ms, so its figure read up to 15 ms high; withheld_usthe figure is the network and the injection, whatever the timer.
The jitter window's inputs. Each initiator link keeps its samples, with the time each was
taken, for the last 30 seconds while it carries input. From them the app shows the median and
the spread and decides on the warning (Open questions, 4). It logs, every 60 seconds while input is
on that link, the count, the median, the 95th percentile, the largest and the mean held_us, so a
report can be read from the log.
10. Text and shared settings
identify_screens briefly labels the recipient's physical displays with the numbers shown
on the sender's Crossing map. Both ends advertise the optional identify_screens capability;
older peers receive no request. Wire version 6 is unchanged.
{"type":"identify_screens","data":{"displays":{"0":2,"1":1}}}
displays contains one to sixteen syntactically valid display keys with unique integer labels
from 1 to 16. Structurally invalid requests are ignored. If the supplied key set differs from
the recipient's current display keys, the recipient replaces the supplied labels with numbers
for all its current displays. Labels use each machine's top-to-bottom, left-to-right map order.
The receiver shows click-through, non-activating overlays for three seconds, without changing
input ownership, saving settings or relaying the request. This is a control message, without
an input sequence number or acknowledgement.
text is a string the receiver types as it stands, for a phone's keyboard, where naming each
key would lose accents and emoji. The receiver advertises text only if it can type any Unicode
text.
- At most 4096 bytes as UTF-8. A longer one is dropped whole, and acknowledged.
\nis typed as Return and\tas Tab. Every other character from U+0000 to U+001F, and U+007F to U+009F, is dropped.- It is typed as characters, not keys, so the receiver's layout and any modifier the sender has
down play no part. A sender does not send
textwhile it holds a modifier on that link. - It carries a
seqand is acknowledged like any input.
settings is Same on all machines: 1.5.0's Same on both machines, extended from one peer to
every peer.
{"type": "settings", "data": {
"on": true, "set_at": 1790000000, "by": "<b64>",
"crossing": {"resistance_px": 120, "block_while_dragging": true, "shortcut": true,
"trigger_key": "alt_r", "shortcut_goes_to": "last", "trigger_style": "double_tap", "double_tap_ms": 300},
"design": {"glow_style": "glow", "glow_colour": "colourful", "effect_length": "normal",
"effect_size": "medium", "effect_pace": 1.0, "effect_size_fraction": 0.045,
"frame_rate": "display", "shortcut_arrival": true, "shortcut_arrival_style": "match"},
"groups": ["crossing", "design", "shortcut", "names"],
"stamps": {"trigger_style": [1789990000, "<b64>"], "glow_colour": [1790000000, "<b64>"]},
"names": {"<id>": {"label": "Studio", "set_at": 1790000000, "by": "<b64>"}}}}
onis a boolean,set_atan integer of unix seconds,bytheb64id of the machine that made the change, or"". A sender always sends all three. A receiver reads a missingbyas"", and also reads abyspelt in standard base64 with padding, as the desktops do; a message missingonorset_at, or with any of the three of the wrong type or not an id, is malformed and ignored whole. The receiver validates this envelope before readingdesign_sync, so a malformed outer field drops the optional Design state with the rest of the message.crossinganddesignare objects, present only whenonis true; one that is absent or is not an object brings no values, and the message stands.groupsis an optional array of"crossing","design","shortcut"and"names". Its order is Crossing, Design, Shortcut, Names. A local group-picker change setsontrue exactly when at least one group is selected. A legacy 1.5.0–1.5.1 state may changeonwhile preserving this machine's group selection; that on/off state is forwarded unchanged. Crossing carries resistance and drag protection; Design carries design values; Shortcut carries the switch, trigger and destination; Names carriesnames. Values for unselected groups are ignored. Withoutgroups, a 1.5.0–1.5.1 state keeps its old on/off behaviour and applies values only to groups selected locally. It never changes a local group selection; with none selected, itsontrue selects every group, as turning it on locally does. Older peers ignoregroupsand continue applying their known Crossing and Design keys.layoutis independent of groups and always travels to peers advertisinglayout.namesis an optional object, present only whenonis true and Names is selected whengroupsis present. Each key is a machine id and each value is{label, set_at, by}:labelis a trimmed string of at most 64 code points, including the empty string;set_atis an integer of unix seconds andbyis theb64id of the machine that changed it. An invalid entry is ignored without dropping other names or settings. Each id's entry is accepted independently when its stamp is newer than the one held for that id: a higherset_at, or the sameset_atand the largerbyas bytes. The clock bounds above apply to each entry. A receiver writes a name for its own id to its localname; another known id updates that peer's optionallabel. Unknown ids are ignored. Withonfalse,namesis ignored. Older peers ignore this optional member.Each value stands alone. Unlike every other message, a value in
crossingordesignoutside the table below, or one this receiver cannot hold (an effect it does not have), is left out and the rest still applied, and the message is not malformed for it; an unknown key is ignored. Whether a message's state is newer is decided byset_atandbyalone, and each value's by its own stamp: one with values left out still wins, takes its stamps, and is sent on as it came.The values:
Key Allowed resistance_pxinteger 0 to 500 block_while_dragging,shortcut,shortcut_arrivalboolean trigger_keya key name from section 7 that is not a character, a media key, browser_back,browser_forward,backspace,tab,enter,esc,spaceorprint_screenshortcut_goes_to"last","next"or"ticked"; absent means"last"trigger_style"double_tap"or"hold"double_tap_msinteger 50 to 2000 glow_style"glow","beam", or an effect id fromeffects.pyglow_colour"signal","colourful","ocean","sunset","mono", or a colour pack id fromeffects.pyeffect_length"short","normal"or"long"effect_size"small","medium"or"large"effect_pacenumber 0.25 to 2.5; when valid it takes precedence over effect_lengtheffect_size_fractionnumber 0.02 to 0.08; when valid it takes precedence over effect_sizeframe_rate"display","half"or"quarter": each machine plays at its own display's refresh, or a half or a quarter of it; 1.5.3 and later, absent from older peers, which leaves the receiver's own; an unknown value is droppedshortcut_arrival_style"match","locator", or an effect id fromeffects.pyThe optional numeric fields are also sent in
design_sync.values. If absent or invalid, a new peer converts the legacy preset to its corresponding slider stop: Short 0.5, Normal 1.0, Long 2.0; Small 0.03, Medium 0.045, Large 0.06. The legacy preset fields always contain the nearest preset for the numeric value, so 1.5.0–1.5.2 peers ignore the new keys and keep a usable setting.Shared: the crossing's feel (resistance, the drag guard, the shortcut, its key and where it goes) and the Design page. Never shared: zones,
side, the direction switches, the Mac's notch look and haptics, and appearance. Version 5'smethods,edge_partsandcornerare zones now and leave the message, and with them goes 1.5.0's mirroring of the corner.shortcut_goes_tois optional. Beamer 1.5.0 to 1.5.2 ignore it and keep Last machine.Newer wins: a higher
set_at, or the sameset_atand the largerbyas bytes. This replaces the Mac winning a tie, since there may be no Mac. Aset_atmore than a day ahead of the receiver's clock, or above 2^53 - 2, is ignored. The outer stamp decidesonandgroups.Each value has its own stamp (1.5.2).
stampsis an optional object, present only whenonis true, with one[set_at, by]per value sent, stamped when a person changed that value on that machine, whether Same was on or off. A receiver takes a value only when its stamp is newer than the one it holds for that key, by the rule above, and keeps that stamp with it. So an edit carries only what was changed, and a value the sender missed or never set cannot overwrite a real choice elsewhere. Before 1.5.2 the whole state travelled under the outer stamp: rc14 (10-10-2026) showed one machine's edit rewriting seven of another's values. A value held without a stamp of its own counts as stamped with the state it came in. That is every value of a peer that sends nostamps, so a 1.5.0 or 1.5.1 peer behaves as it did against its own kind. A fresh machine's values hold[0, ""], so it adopts the group's and never sends its defaults over anyone's. A stamp for a key not sent is ignored; one may be later than the outerset_at, since a value changed while its group was off is stamped then, and is bounded by the same day-ahead rule. The receiver seeds its own unstamped values once, from its outer stamp, and stores them; later changes to the outer stamp (on, off, the groups) never restamp a value.Answering. A receiver that holds a newer value than one in the message sends its own state to its peers, or the sender, having taken nothing from its own message, would never learn it. A receiver that holds no newer value sends nothing back, so the exchange stops. A peer from before 1.5.2 takes only a whole state newer than its own, so it ignores an answer whose outer stamp equals the state it just sent; it learns the newer value at the next change made on a 1.5.2 machine with Same on. A value kept back over a trigger clash is not taken, so a message carrying only that is not sent on.
From and to whom. A machine takes
settingsonly from a peer whose capabilities listsettings, and sends its state to every such peer after each handshake and on every change. One that takes a newer state, or any newer value, sends the message on, unchanged, to every other such peer it has a link to. One that takes nothing does not send it on, so it stops. Turning it off travels the same way.A change made here is stamped with the current time, and never lower than the stamp held plus one, so a change on a machine whose clock is behind still wins.
Each settings file keeps its group selection and one local
same_before_syncsnapshot. Before an accepted incoming update changes local shared values or the selection, save the previous selection and affected values. The snapshot expires after 30 days, is replaced by the next accepted change, and is never sent. Name entries follow the accepted group policy even when an older outer stamp carries newer per-entry names. Updates that change only stamps do not replace the snapshot. Revert restores saved values, clears the snapshot, stamps the restoration as a new local change and announces it under the current group selection, keeping sync on. A selection-only update recordsselection_onlyin the local snapshot: Revert restores the previous selection while keeping the current values. Restored names and direct Design advertisements receive fresh stamps too. Group selection and snapshots are never key-mapping policy; each system keeps its own mapping.
Follow a machine's design. Each machine's Design page has Match design with: None, or one
paired machine advertising both settings and design_sync. The selection is local; there is no
group object and the selection is never sent. Only machines linked now are listed, plus the one
followed while it is away; with none, the page says so in one line. A linked machine that does not
advertise design_sync is shown unavailable with “Needs beta.6 or later”. Eligibility is the
capability alone; the app version string is never compared.
The optional design_sync member is independent of on. A capable machine sends its own current
Design state to each directly linked capable peer after link-up and whenever its Design changes,
even while Same on all machines is off. The state is:
{"type":"settings","data":{"on":false,"set_at":1790000000,"by":"<b64>",
"design_sync":{"set_at":1790000001,"by":"<b64>","values":{
"glow_style":"glow","glow_colour":"colourful","effect_length":"normal",
"effect_size":"medium","effect_pace":1.0,"effect_size_fraction":0.045,"frame_rate":"display",
"shortcut_arrival":true,"shortcut_arrival_style":"match"}}}}
design_sync is a complete independently stamped Design state. Its set_at and by use the
newer-wins ordering and clock bounds above. Values are validated individually; unsupported keys or
values are ignored. Missing effect_size means "medium"; its wire type is string and allowed
values are "small", "medium" and "large". effect_pace and effect_size_fraction are
optional numbers with the bounds and preset fallback described above. Same on all machines has precedence: the follow
selection stays set but does not apply while Same is on. A newer state from the selected machine
applies to this machine's Design only when its stamp is newer than this machine's own Design stamp.
The follower keeps the leader's set_at and by, so an announcement carries the same stamp through
a chain (C follows B, B follows A) and both sides of a mutual follow converge on the newest state
when their initial announcements cross in flight. If applying a state leaves every Design value
identical, it is not a change and nothing is announced; the newer stamp is still kept locally, so an
older state cannot replace it.
While a machine follows another, its followed Design controls (style, landing animation, colour, length and size) are locked, dimmed under a “Following 's design” banner whose Stop following button ends it and keeps the design shown; local controls stay live. Turning off Same on all machines resumes following from the selected machine's latest received state. Removing or unpairing the selected machine resets the selection to None. An offline followed machine leaves the last look in place; the next link-up sends its current state and catches the follower up. Older peers ignore the optional field. A peer that does not send it cannot be followed.
Shared tile picture. The optional layout member is independent of on and carries the
complete machine-id-to-tile map. Its set_at and by use the newer-wins ordering and clock bounds
above; a receiver keeps the newest valid state, compiles its own zones from the picture, and sends
the state on unchanged to other linked peers advertising both settings and layout. Zones and
sides remain local, and arrangement continues to settle sides with peers that do not advertise
layout.
{"type":"settings","data":{"on":false,"set_at":1790000000,"by":"<b64>",
"layout":{"set_at":1790000001,"by":"<b64>","tiles":{
"<machine id>":{"x":0,"y":0,"w":160,"h":100,
"displays":{"0":{"x":-1280,"y":0,"w":1280,"h":800},
"1":{"x":0,"y":0,"w":1920,"h":1080}}}}}}}
tiles has at most 33 entries, keyed by machine id. Each tile has integer x, y, w and h
canvas units, with positive w and h. A tile may also carry name, the machine's advertised
name (up to 64 characters). A map may show this machine, any desktop peer it holds, and a third-party
machine only when an in-use, non-dormant, not-left-out desktop peer lists that id in paired_with
and the third-party tile has a valid name. A phone, dormant, left-out or not-in-use peer cannot
admit a third-party tile. Unnamed third-party tiles and ids outside these rules are dropped.
A tile may also carry displays, a map of 1 to 16 display
keys to {x, y, w, h} logical rectangles in that machine's own display arrangement; x and y
may be negative, and widths and heights are positive. The display rectangles are fitted into the
machine's canvas tile while preserving their arrangement. A tile may also carry display_offsets, a
map from display key to integer {x, y} translations in canvas units. A present offset marks that
display as split from its group; the reported logical rectangle remains unchanged. Omitted offsets
keep the display grouped, and dragging the machine moves the group together. A receiver ignores
malformed layout as a whole. Peers without displays receive the same machine tiles without the
nested display map or its offsets.
Beamer 1.5.0 to 1.5.2 ignore this unknown optional member and keep their existing Crossing page.
Versions
- Wire version 6 is in Beamer 1.5.0 and later. It refuses versions 5 and below, and they refuse it; each side names the other machine to update.
- Pairing version 3 is in 1.5.0 and later, and pairs only with itself.
- 1.4.x's settings are migrated once and kept, so going back to 1.4.x on both machines works.
The vectors
The test vectors for version 6 and pairing version 3 are core/tests/v6_vectors.json, and
version 5's, kept byte for byte, core/tests/v5_vectors.json; the tests beside them replay each
one against the code and against the primitives written out by hand.
Changes from version 5
- The preamble is 62 bytes and carries the pair's key id and an ephemeral X25519 share; the keys
take the X25519 result beside the token and bind the key id, both shares and a direction byte
in place of the prefixes' order, which gives forward secrecy; the salt is
beamer-link-v6. helloandwelcomecarry each machine's id, checked there, and ahellonaming the wrong id is answeredwrong_id; a typed token, and any token migrated from 1.4.x, no longer links.- The handshake is bounded as a whole (5 seconds, the preamble in 1) on both sides, where version 5's initiator bounded each read at 2 seconds; one pending handshake per address.
- A responder keeps one link per peer and at most one owner, where version 5 kept one link and let
the newest replace it.
focusis answered withacceptorrefuse. focusandswitchname machines by id, not"mac"and"windows", and carry a route.focusno longer carriesreturn_edge: the responder's own zones say where its edges lead, and the owner sends only itsresistance_px.hellono longer carriesreturn_edgeandresistance_px; the arrangement travels only asarrangement, which names the sender's edge and aby, notmac_edge.helloandwelcomecarry the name, platform, app version and capabilities; thesettings: 1flag became thesettingscapability.- The clipboard follows
focusinstead of going before it, and goes back only when it changed under the owner that is leaving. ackcarriesheld_us, and the responder acknowledges a lone event at once.- Each initiator counts
seqfrom 1 on every link; version 5's Mac carried it across reconnects. - New messages:
accept,accepts,refuse,paired,text. settingsgains the optionaldesign_syncmember for per-machine Design matches; older betas ignore it, while 1.5 keeps it separate from the existingonswitch.settingsgains the optional independently stampedlayoutmember for the shared tile picture; peers without thelayoutcapability do not receive it.focusandswitchmay carry the optionaldisplayandsidepair for landing on a named display edge; peers without thedisplayscapability receive neither field.
Changes from the first design
- Taking input. The first design let a
focusin when it named "the current owner's own switch request by its route number". Version 6 has no such path: only a machine with no owner, or its own owner, can be taken, and a hand-over is the owner letting go. - Non-owners. The first design dropped a non-owner's
focus,arrangementand settings. Version 6 answers itsfocuswithrefuse, so it can take its input home at once, and handlesarrangementandsettingsfrom any peer, because they are between two paired machines rather than part of driving; dropping them would lose every change made while nobody drives. - The clipboard is one per machine, not one per link; it follows the input through the owner.
- Capabilities gain
clipboard, since a phone may take no clipboard at all. - A driven machine is not taken (
busy): the first design did not say what a machine whose own input is elsewhere does when taken. - Mac to Mac keys keep their sides; the first design named 1.4.x's positional map, which folds them.
- Pairing's associated data gains platform and port, so the pairing code's AD construction changes too, not only the bytes fed in.
- The id in the clear. The first design put the sender's machine id in the preamble and both ids in
the keys. Version 6 puts a per-pair key id there instead, with the ids sealed in
helloandwelcome, and adds forward secrecy (decided 1 and 2). - Pairing by QR carries a second secret (decided 7).
- Design matching is a local choice to follow one machine directly. Applying a newer state republishes the local result so chains carry on; identical values publish nothing, so mutual follows converge without forwarding received state (decided 8).
Decided
Decided on 30-09-2026, 6 on 01-10-2026, and 8 on 02-10-2026. The text above already follows these.
- A per-pair key id in the preamble, not the machine id. The first 16 bytes of
HKDF-SHA-256(token, salt "beamer-link-v6", info "beamer-key-id"); the machine ids travel inhelloandwelcomeand are checked there; there is no empty-id lookup; key ids are unique across entries (section 2). - Forward secrecy in version 6. An ephemeral X25519 share in each preamble, the result in
ikmand both shares ininfo; a zero result ends the handshake (section 2). - No typed tokens, and no migrated ones. Follows from 1: 1.5.0 has no token field, and a key id is an offline test of its token. The first decision let a migrated token of pairing's spelling link; since a typed token can have that spelling and 1.4.x kept no record of which it was, no migrated token links, and Overview asks the user to pair that machine again (sections 1 and 2).
- The QR's extra secret. 16 random bytes per code in the QR as
k;qr: 1inpair_startmakes the password the code followed by those bytes (section 6). - Follow a machine's Design directly. A local selection names at most one paired machine and never goes on the wire. Machines send their own stamped Design to direct capable peers; a follower that changes applies and announces its own resulting state. Identical values announce nothing, so a mutual follow converges. Same on all machines takes precedence (section 10).
Open questions
Open. None touches the wire; the recommendation in each is the design 1.5.0 follows until it is decided.
- The Crossing page and missing pairings. The first design offered a zone to P only when
every machine that may drive this one is paired with P. Adding a phone that is not paired with
P would then take away a zone the desktops use. Recommendation: offer the zone whenever this
machine is paired with P, arm it only for owners whose
reachincludes P (section 5), and have the page name each machine that cannot follow it. - The jitter warning's threshold. Recommendation: warn when, over the last 30 seconds and at least 50 samples, the 95th percentile is 20 ms or more above the median, and show the median and that gap in plain words.
- A peer that is already paired. Pairing refuses a machine already in the list once it has linked, so to pair again after one side has removed the other, the user removes it on both. Recommendation: keep the refusal; the window says exactly which machine still has it.