Architecture

System overview

Crosslink connects two devices through an end-to-end encrypted channel. The system has three layers:

+---------------------+
|   Application Layer |  Your code (RPC, events, permissions)
+---------------------+
|   Transport Layer   |  LAN / relay / WebRTC, auto-fallback
+---------------------+
|   Crypto Layer      |  Ed25519, X25519, XChaCha20-Poly1305
+---------------------+

Component diagram

┌──────────────────────────────────────────────────────────┐
│                     APPLICATION                          │
│  ┌──────────┐              ┌──────────┐                  │
│  │ Host App │              │  Client  │                  │
│  │ (Node.js)│              │ (Browser)│                  │
│  └────┬─────┘              └────┬─────┘                  │
│       │                         │                        │
│  ┌────┴─────┐              ┌────┴─────┐                  │
│  │ Host SDK │              │Client SDK│                  │
│  └────┬─────┘              └────┬─────┘                  │
│       │                         │                        │
│  ┌────┴─────────────────────────┴────┐                   │
│  │          Core Engine              │                   │
│  │  ┌─────────┐ ┌───────┐ ┌──────┐  │                   │
│  │  │ Sessions│ │  RPC  │ │Crypto│  │                   │
│  │  └─────────┘ └───────┘ └──────┘  │                   │
│  └────┬─────────────────────────┬────┘                   │
│       │                         │                        │
│  ┌────┴─────────────────────────┴────┐                   │
│  │        Transport Manager          │                   │
│  │  ┌─────┐  ┌───────┐  ┌────────┐  │                   │
│  │  │ LAN │  │ Relay │  │ WebRTC │  │                   │
│  │  └─────┘  └───────┘  └────────┘  │                   │
│  └───────────────────────────────────┘                   │
└──────────────────────────────────────────────────────────┘

How a connection is established

Phase 1: Pairing

Host                          Signaling                      Client
  |                              |                             |
  |--- generate code ---------> |                             |
  |    (9-digit, TTL 2min)      |                             |
  |                             |<-- resolve code ------------|
  |                             |--- send claim (publicKey) ->|
  |<-- receive claim -----------|                             |
  |                             |                             |
  |--- send challenge --------->|--- forward challenge ------>|
  |                             |<-- send signature -----------|
  |<-- receive signature --------|                             |
  |                             |                             |
  |--- SAS verification ------>|                             |
  |<-- SAS verification --------|                             |
  |                             |                             |
  |=== E2E encrypted session established =========================|

Phase 2: Session establishment

Host                          Client
  |                              |
  |--- ephemeral pubKey ------->|
  |<-- ephemeral pubKey --------|
  |                              |
  |--- HKDF (shared secret) --->|
  |<-- HKDF (shared secret) ----|
  |                              |
  |=== XChaCha20-Poly1305 frames ===|

Phase 3: RPC communication

Host                          Client
  |                              |
  |<-- request (method, args) ---|
  |--- response (result) ------>|
  |                              |
  |<-- subscribe (event) --------|
  |--- event (payload) -------->|
  |--- event (payload) -------->|

Transport layer

The client tries every endpoint the pairing QR advertised, in the order the host listed them (LAN and WAN-direct addresses first, then signaling/relay/tunnel routes). If a webrtc upgrade is configured, the client additionally attempts to upgrade an already-connected session to a direct WebRTC DataChannel, falling back to the existing transport if that fails.

LAN transport

Direct WebSocket between devices
No external services needed
Lowest latency
Works only on same network (or when the host advertises a wan address reachable via a router port mapping)

WebRTC transport

Peer-to-peer data channel, negotiated as an upgrade after an initial connection is established
NAT traversal via STUN/TURN
The relay connection remains as a fallback if the upgrade fails

Relay transport

All traffic routed through the relay service
Highest latency
Works whenever a relay is configured and reachable
Server sees only ciphertext

Secret storage

Host (Node.js)

Backend priority:
1. keytar          (macOS Keychain, Linux libsecret, Windows Credential Vault --
                     only if the host app installs the optional `keytar` package)
2. Electron safeStorage (same vaults via Electron bindings)
3. Encrypted file  (AES-256-GCM, key from CROSSLINK_SECRET_KEY or machine-derived)
4. Plaintext file  (mode-600, requires explicit opt-in)

Client (Browser)

Backend priority:
IndexedDB + AES-256-GCM (non-extractable WebCrypto key)
localStorage            (plaintext fallback)
Memory                  (ephemeral, lost on reload)

Package relationships

@crosslink/sdk-node
  └── @crosslink/core
        ├── @crosslink/protocol
        └── @crosslink/webrtc-adapter (optional)

@crosslink/sdk-browser
  └── @crosslink/core
        ├── @crosslink/protocol
        └── @crosslink/webrtc-adapter (optional)

Key design decisions

Decision	Rationale
Ed25519 for identity	Fast, small keys, widely supported, no legacy baggage
X25519 for key exchange	ECDH on the same curve, forward secrecy
XChaCha20-Poly1305 for framing	Better nonce management than AES-GCM, no hardware dependency
Capability-based permissions	Declarative, host-authored, no runtime checks needed
Transport fallback	Graceful degradation, always connectable
Services as untrusted	Minimizes attack surface, E2E encryption by default

GET STARTED

BUILD

CONCEPTS

CLIENT

CONNECTIONS

SECURITY

GUIDES

REFERENCE

RESOURCES

System overview

Component diagram

How a connection is established

Phase 1: Pairing

Phase 2: Session establishment

Phase 3: RPC communication

Transport layer

LAN transport

WebRTC transport

Relay transport

Secret storage

Host (Node.js)

Client (Browser)

Package relationships

Key design decisions

​System overview

​Component diagram

​How a connection is established

​Phase 1: Pairing

​Phase 2: Session establishment

​Phase 3: RPC communication

​Transport layer

​LAN transport

​WebRTC transport

​Relay transport

​Secret storage

​Host (Node.js)

​Client (Browser)

​Package relationships

​Key design decisions

System overview

Component diagram

How a connection is established

Phase 1: Pairing

Phase 2: Session establishment

Phase 3: RPC communication

Transport layer

LAN transport

WebRTC transport

Relay transport

Secret storage

Host (Node.js)

Client (Browser)

Package relationships

Key design decisions