Protocol

Overview

Crosslink’s wire protocol defines three layers, all JSON-encoded and sent as WebSocket text/binary messages:

Pairing frames — exchanged before any trust exists, to enroll a new device.
The CLX1 handshake — an authenticated ephemeral key exchange that establishes a fresh session between an already-paired device and the host.
Session frames — encrypted application messages (RPC calls, responses, events) once a session is established.

Pairing frames

Frames are plain JSON objects with a kind discriminator (no envelope version field at this layer).

`pair_hello` / `pair_ready`

Sent when pairing happens directly over a socket to the host (no signaling broker) — resolves the scanned 9-digit code to a live session id.

{ "kind": "pair_hello", "code": "483921004" }

{ "kind": "pair_ready", "ps": "<psid>", "app": { "appId": "...", "name": "...", "fingerprint": "...", "pubEdB64": "...", "pubXB64": "..." } }

`pair_claim`

Client sends a signed identity claim.

{
  "kind": "pair_claim",
  "ps": "<psid>",
  "dev": "cd1_...",
  "name": "My Phone",
  "pub_ed": "base64-ed25519-public-key",
  "pub_x": "base64-x25519-public-key",
  "nonce": "base64-32-byte-nonce",
  "caps_req": ["app.control"],
  "sig": "base64-signature"
}

`pair_challenge`

Host replies with its own identity and the capabilities it is willing to grant, signed.

{
  "kind": "pair_challenge",
  "ps": "<psid>",
  "claim_nonce": "...",
  "host_pub_ed": "...",
  "host_pub_x": "...",
  "nonce": "base64-32-byte-nonce",
  "granted_caps": ["app.control"],
  "sig": "..."
}

`pair_complete` / `pair_done`

Client confirms the Short Authentication String (SAS) with the user and sends the completion frame; host acknowledges.

{ "kind": "pair_complete", "ps": "<psid>", "claim_nonce": "...", "challenge_nonce": "...", "sig": "..." }

{ "kind": "pair_done", "ps": "<psid>" }

`pair_error`

{
  "kind": "pair_error",
  "error": { "code": "pairing_invalid", "message": "..." }
}

The CLX1 handshake

Once a device is paired, every reconnect runs a fresh authenticated key exchange (“CLX1”):

client                                          host
------                                          ----
sinit{app, dev, sx, epk, nc, ts, sig}    ->
                                                 look up device record by dev,
                                                 verify sig under the RECORD's
                                                 pinned key (never the wire)
                                          <-     sack{epk, nh, sig}
verify sig under the TRUSTED host key

sinit carries the client’s static X25519 key (sx), a fresh ephemeral X25519 key (epk), a 32-byte nonce (nc), a timestamp, and an Ed25519 signature over the transcript. sack carries the host’s ephemeral key (epk), its own 32-byte nonce (nh), and its signature. A srej { kind: "srej", code, message } frame rejects a handshake outright.

Key derivation

sharedE = X25519(ephemeral_private, peer_ephemeral_public)
sharedS = X25519(static_private,    peer_static_public)
okm     = HKDF-SHA256(sharedE || sharedS, salt = nc || nh, info = "crosslink-session-keys-v1", 64 bytes)
kC (c2h)= okm[0..32]   (client -> host traffic key)
kH (h2c)= okm[32..64]  (host -> client traffic key)

Fresh ephemeral keys on every reconnect give forward secrecy; the static-static term binds the session to the paired identities; signatures over the canonical transcript prevent MITM, cross-application relay, and replay.

Session frames

Once a session’s traffic keys are derived, every application message is sealed independently with XChaCha20-Poly1305.

{ "kind": "enc", "n": 1, "iv": "base64-24-byte-nonce", "ct": "base64-ciphertext+tag" }

Algorithm: XChaCha20-Poly1305 (AEAD; the 16-byte Poly1305 tag is appended to ct)
Nonce (iv): 24 bytes, random per frame
n: a strictly monotonic per-direction counter, starting at 1 — used as part of the AAD, so replay, reordering, and cross-direction substitution all fail authentication

Application messages

The plaintext inside each session frame is one application message, sharing a common envelope: v (protocol version, e.g. "1.0") and t (message type).

`t`	Purpose
`hello` / `hello_ok`	Post-handshake capability/version exchange
`req`	RPC request: `{ v, t: "req", i, m, p?, idem?, ts? }`
`res`	RPC response: `{ v, t: "res", i, p? }`
`err`	RPC error: `{ v, t: "err", i, e: { code, message, data? } }`
`chunk`	Streaming progress chunk: `{ v, t: "chunk", i, n, d }`
`end`	Stream completion: `{ v, t: "end", i, p? }`
`evt`	Event delivery: `{ v, t: "evt", s, e, p? }`
`sub` / `unsub`	Subscribe/unsubscribe to an event: `{ v, t: "sub", s, e }`
`cancel`	Cancel an in-flight request: `{ v, t: "cancel", i }`
`ping` / `pong`	Heartbeat
`bye`	Graceful close: `{ v, t: "bye", code?, reason? }`

i is the request id, m the method name, p the payload, s a subscription id, e an event/method name depending on context. See Error Codes for the values err.e.code may take.

Version negotiation

Current protocol version: 1.0 (PROTOCOL_VERSION). A hello message carries the sender’s supported versions (highest last); the negotiated version is the highest one both sides support. There is no floor below which a connection silently downgrades.

GET STARTED

BUILD

CONCEPTS

CLIENT

CONNECTIONS

SECURITY

GUIDES

REFERENCE

RESOURCES

Overview

Pairing frames

`pair_hello` / `pair_ready`

`pair_claim`

`pair_challenge`

`pair_complete` / `pair_done`

`pair_error`

The CLX1 handshake

Key derivation

Session frames

Application messages

Version negotiation

​Overview

​Pairing frames

​pair_hello / pair_ready

​pair_claim

​pair_challenge

​pair_complete / pair_done

​pair_error

​The CLX1 handshake

​Key derivation

​Session frames

​Application messages

​Version negotiation

Overview

Pairing frames

`pair_hello` / `pair_ready`

`pair_claim`

`pair_challenge`

`pair_complete` / `pair_done`

`pair_error`

The CLX1 handshake

Key derivation

Session frames

Application messages

Version negotiation