Links

Encrypted connections between devices

What is a link?

A link is an established encrypted connection between a host and a client. It represents the active session over which RPC calls and events flow.

Link lifecycle

1. Pairing     -- QR scan, identity exchange, SAS verification
2. Connection  -- X25519 key exchange, session key derivation
3. Active      -- RPC calls, events, streaming
4. Disconnect  -- Graceful shutdown or network loss
5. Reconnect   -- Automatic reconnection with backoff

Link states

State	Description
offline	Not connected, no active session
discovering	Looking for the host
pairing	Pairing in progress
connecting	Establishing connection
direct	Active session over LAN or WebRTC, RPC available
turn-relayed	Active session over a TURN relay, RPC available
crosslink-relayed	Active session over the relay service, RPC available
reconnecting	Lost connection, attempting to restore
unauthorized	Host rejected this device
revoked	Device access was revoked
protocol-incompatible	Host/client protocol versions don’t match

Creating a link

From host perspective

// Server automatically manages links
const server = createCrosslinkServer({ /* ... */ });

// Listen for connections
server.typedOn("deviceConnected", ({ deviceId, transport }) => {
  console.log(`Client ${deviceId} connected via ${transport}`);
});

// List paired devices
const devices = server.listDevices();

From client perspective

const client = await CrosslinkClient.create({ /* ... */ });

// Pair and connect
await client.pairFromQr(uri, ["app.control"]);
const rpc = await client.connect(["app.control"]);

// Monitor connection state
client.onStateChange((state) => {
  console.log("State:", state);
});

Multiple links

A host can maintain multiple simultaneous links:

Host
├── Link 1: Client A (phone) -- WebSocket
├── Link 2: Client B (tablet) -- WebRTC
└── Link 3: Client C (laptop) -- relay

Each link has its own:

• Encryption keys
• Granted capabilities
• Sequence counters
• Connection state

Link persistence

Links persist across network interruptions:

• The session key remains valid
• Reconnection uses exponential backoff
• RPC calls queue during disconnection
• Subscriptions restore automatically

Security per link

Each link has independent security:

• Unique session key (forward secrecy)
• Independent capability grants
• Separate sequence counters
• Isolated error handling

Link events

Event	Description
connected	Link established
disconnected	Link closed
error	Link error occurred
reconnecting	Reconnection attempt started
reconnected	Reconnection successful