Architecture

How the pieces fit together

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:
1. IndexedDB + AES-256-GCM (non-extractable WebCrypto key)
2. localStorage            (plaintext fallback)
3. 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