Room authentication#

room_hello is the only message PacketRelay authenticates. A member signs a canonical byte string with an ECDSA P-256 identity key, the relay verifies that signature, binds the member_id to the key on first use, and refuses any later join for that slot that presents a different key or a nonce it has already seen. This page enumerates every rule that governs that exchange: the four checks and their order, the canonicalization contract, the wire encodings, the reject reasons and the residual risks.

Rows follow source order in src/room_auth.rs and src/protocol.rs, not alphabetical order, because the checks are order-dependent and reading them in any other sequence misrepresents them.

The four checks, in order#

RoomAuthStore::verify is a pure read — it mutates nothing, so a rejected hello leaves no pin and no nonce high-water behind (src/room_auth.rs:157-203). The checks short-circuit: the first failure returns and nothing after it runs.

Only check 4 takes a lock. The first three are pure computation over the hello's own fields, so a hello that fails any of them is refused without touching shared state at all. Check 3 is skipped entirely for member ids that carry no fingerprint prefix, which is where the residual risk documented at the end of this page comes from.

The signing payload#

The canonicalization is a cross-repository contract. Four Room clients — the desktop pair client, desktop presence, desktop chat JS and mobile chat JS — must produce identical bytes, and the relay verifier must reproduce them exactly (src/protocol.rs:11-12).

Fields are joined by the single byte 0x1F (ASCII Unit Separator), the constant ROOM_HELLO_SEP (src/protocol.rs:18). There is no separator before the domain and none after the nonce, and no field is length-prefixed, escaped or trimmed. The separator was chosen because it is disjoint from the base64 alphabet, from hostnames and from the member_id charset, so the delimited fields are unambiguous without escaping.

The layout, as the source states it (src/protocol.rs:22-25):

ROOM_HELLO_SIG_DOMAIN ‹0x1F› session_id ‹0x1F› member_id ‹0x1F› pubkey ‹0x1F› nonce(decimal)

The string actually fed to sign and verify is not those bytes. It is their standard base64 encoding, as an ASCII string (src/protocol.rs:63-73). That extra hop exists because the clients sign through &str crypto APIs — CryptoService::{sign,verify} on desktop, Web Crypto on mobile — and the canonical bytes contain 0x1F, which does not survive a string round-trip intact. Base64 makes the payload printable ASCII, so it passes through those APIs unchanged.

Pair frames use a different domain, jarvis-pair-sig-v1 (src/protocol.rs:9). The two spaces are disjoint, so a room-hello signature cannot be cross-presented to a pair-frame verifier that shares the same identity key.

Golden vector#

This constant is the conformance anchor. The JS conformance tests in the mobile and desktop client repositories assert that btoa(canonical("sid","m1","pk",42)) equals the same string, so any drift in the domain separator or the field separator fails the build on at least one side (src/room_auth.rs:799-812):

const GOLDEN_PAYLOAD_SID_M1_PK_42: &str = "amFydmlzLXJvb20taGVsbG8tdjEfc2lkH20xH3BrHzQy";

The vector deliberately uses pk, which is not a real base64 SPKI key, because it pins the string canonicalization — a stage that runs before any key is decoded. A client whose canonicalizer passes this vector has the field order, the separator and the encoding right, whatever key it goes on to use.

Wire formats#

All five fields are required. There is no deny_unknown_fields, so unknown extra fields in a hello are silently ignored, but a hello missing pubkey, nonce or sig fails deserialization outright and the connection is dropped with no error frame (src/protocol.rs:76-109, src/connection.rs:491-546).

Base64 appears in exactly three places — src/protocol.rs:68-72, src/room_auth.rs:300-304 and src/room_auth.rs:336-346 — and every one of them uses the standard alphabet with padding. There is no URL-safe variant and no unpadded variant anywhere in the relay, so a client that emits URL-safe or unpadded base64 fails with MalformedCrypto.

The SHA-256 prehash is internal to p256::ecdsa: verify is called with the raw payload bytes and the crate hashes them (src/room_auth.rs:348). A client must not pre-hash the payload itself.

Fingerprint binding#

The check is narrow on purpose: it fires only for ids that actually embed a fingerprint, because making member_id == fingerprint(pubkey) for every client would change all four id formats and sever the member_id to user_id linkage that presence rosters, DM channel names and pair-frame from fields depend on (src/room_auth.rs:20-33).

Pins and nonce monotonicity#

commit re-checks under the write lock what verify already checked under the read lock, because two concurrent valid hellos for the same slot could otherwise race a replay through the gap between the two. The loser's slot is torn down and the loser is given the reject message (src/connection.rs:217-242).

The freshness window and the monotonic check do different jobs. The ±30 s window is a sanity bound on how far in the past or future a first, slot-pinning hello may be dated; the real anti-replay guarantee is the strictly monotonic per-slot nonce, which is what stops a hello captured inside the window from evicting the live connection holding the slot (src/room_auth.rs:47-53). A genuine reconnect naturally carries a higher unix-millis nonce and is accepted.

Reject reasons#

Source order, as declared in RoomHelloRejectReason (src/room_auth.rs:82-99).

StaleNonce covers both the stale case and the replay case as a single coarse reason; the logs carry which one it was (src/room_auth.rs:86-92).

The two client-facing messages#

The messages are deliberately coarse so they do not leak which check failed beyond what an attacker can already infer (src/room_auth.rs:103-105). A prober who learns that a signature was structurally fine but the nonce was stale learns that the slot is live and pinned; a prober who learns the fingerprint check specifically failed learns the id's format. The precise reason is logged server-side instead (src/connection.rs:128-133).

This is a genuine cost, and it lands on legitimate clients: a member with a skewed clock and a member with a broken canonicalizer receive the same sentence. Debugging one of these needs relay logs, not the error frame.

The relay never signs anything#

Signature verification is one-directional. The relay holds no private key, issues no credential and produces no signed response.

The ecdh feature is dead weight in the dependency graph, not a hint of an unimplemented key-exchange path. Nothing in the relay derives a shared secret, and the relay does not encrypt payloads at all — end-to-end encryption is a client responsibility (src/main.rs:4-5).

Residual first-mover risk on unfingerprinted ids#

Two of the four client id formats carry no relationship to the signing key: the pair client's random_alnum(16) and presence's raw UUIDv4 (src/room_auth.rs:20-33). For those, check 3 does not fire, and the only binding is trust on first use.

The consequence is narrow but real: for an unfingerprinted id, the first valid signer to present it owns it for the life of the room, and the legitimate holder is then refused with member id bound to a different identity. The attacker still needs the room session_id, which is a capability secret, and still needs a valid signature over the canonical payload — but not the member's key. The risk is recorded as open in the repository's roadmap and backlog (BACKLOG.md:124-131).

Because pins are dropped when a room empties (src/room_auth.rs:248-250) and lost entirely on restart, the window resets every time the last member leaves. That bounds the damage and also means a pin is never a durable identity claim.

What the tests pin#

Twenty unit tests in src/room_auth.rs:351 cover the rules on this page: the nonce window boundaries at exactly ±30 s, first pin, same-key reconnect, a squatter presenting a different key, a bad signature, a forgery where the presented pubkey is not the signing key, reconnect with a different key, independent pins per member, a stale nonce, a replayed identical nonce, an older nonce, a strictly newer reconnect, a malformed pubkey, forget_session, the guarantee that verify leaves no pin, both commit-race guards, a fingerprinted id matching, a fingerprinted id mismatching before any pin exists, fingerprint_prefix recognition, and the golden payload vector.

cargo test --locked    # the whole suite; 53 tests, none in a tests/ directory

Nothing here is covered by an end-to-end listener test — the auth tests drive RoomAuthStore directly, and the acknowledged coverage gap for socket-level room behaviour is at BACKLOG.md:101-111.

Related#

• Authenticated rooms — the join procedure, event ordering and frame attribution.
• Message reference — the full envelope catalogue for all three protocols.
• Security model — what the other three hellos do not authenticate.
• Troubleshooting — mapping an error frame back to a cause.
• Invariants & tripwires — the rules a change here must not break.
• Build & test — running the suite and the local gate ladder.