API Reference

Complete API reference for all Crosslink packages

Host SDK (@crosslink/sdk-node)

createCrosslinkServer(options)

Creates a new Crosslink host server.

import { createCrosslinkServer } from "@crosslink/sdk-node";

const server = createCrosslinkServer(options);

Options

Property	Type	Required	Description
application.id	string	Yes	Unique application identifier
application.name	string	Yes	Human-readable name
application.version	string	No	Semantic version
capabilities	CapabilityDef[]	No	Declared capabilities
signalingUrl	string	No	Signaling server URL
relayUrl	string	No	Relay server URL
lan	{ enabled?, port?, bind?, host?, httpHandler? }	No	LAN binding options — see Configuration
pairing	{ ttlMs?, autoApprove?, approve?, bootstrapUrl? }	No	Pairing configuration
networkMode	"auto" | "local-only" | "lan-and-relay" | "remote"	No	Which transports the host offers
remote	{ enabled?, externalPort?, lifetimeSeconds?, autoRenew?, portForwarded?, publicHost? }	No	Direct inbound access via router port mapping (PCP/NAT-PMP/UPnP), or a forward you added by hand — see Remote Access
onConsentRequest	ConsentPrompt	No	Asked before each use of a confirmEachUse capability
consent	{ alwaysTtlMs?, sessionTtlMs?, promptTimeoutMs? }	No	How long consent answers are remembered
webrtc	{ createPeer, capability?, maxPending?, timeoutMs? }	No	Accept WebRTC upgrades from paired devices
secrets	{ service?, passphrase?, allowPlaintextFallback?, preferFile? }	No	Secret-store selection and fallbacks
security	{ maxDevices?, maxActivePairingSessions?, pairingRateLimitMs?, localNetworkOnly? }	No	Security hardening
permissions	PermissionPolicy	No	Host-authored capability policy applied before pairing approval
logger	Logger	No	Custom logger

CapabilityDef

interface CapabilityDef {
  id: string;           // e.g., "app.control"
  title: string;        // e.g., "Control the app"
  risk: "low" | "medium" | "high";
  description?: string;
  defaultGranted?: boolean; // granted by default at pairing when requested
  confirmEachUse?: boolean; // require a fresh prompt on every use
}

pairing

{
  ttlMs?: number;
  autoApprove?: boolean; // dev convenience; never for production
  approve?(request: PairingApprovalRequest): PairingApproval | Promise<PairingApproval>;
  bootstrapUrl?: string; // hosted install page for the iOS "Add to Home Screen" flow
}

PairingApproval is boolean | string[] | { approved: boolean; caps?: string[] } — true grants everything requested, false refuses, and an array or { caps } grants only that subset.

PairingApprovalRequest

interface PairingApprovalRequest {
  sas: string;
  deviceName: string;
  deviceId: string;
  requestedCaps: string[];
  requiresExplicitApproval: string[];
  deniedCaps: Array<{ id: string; reason: string }>;
}

Server methods

server.start()

Start listening for connections.

await server.start();

server.stop()

Gracefully shut down.

await server.stop();

server.getPairingCode()

Generate a new pairing code.

const code = await server.getPairingCode();
// code = {
//   psid: "...",
//   code: "123456789",
//   uri: "crosslink://pair?v=2&e=lan~ws%3A%2F%2F...&c=123456789&a=...&n=...&f=...",
//   expiresAt: 1699999999999,
//   qrSvg: "<svg>...</svg>",
//   endpoints: [{ kind: "lan", url: "ws://192.168.1.5:51820" }]
// }

server.expose(method, handler, options?)

Register an RPC method.

server.expose("app.status", () => ({ ok: true }), {
  capability: "app.control"  // Optional capability requirement
});

options also accepts inputSchema (a MiniSchema), validate (a custom validator function), idempotent (safe to auto-retry across reconnects), and timeoutMs. capability may be an array, in which case all of them are required.

The handler receives (input, ctx):

interface RpcContext {
  deviceId: string;      // which paired device is calling
  requestId: string;
  signal: AbortSignal;   // aborts on client cancel or session loss
  log: Logger;           // pre-bound with device, method, request id
  emitProgress(d: Json): void;  // progress events without ending the request
}

See Capabilities and RPC for how to use them.

server.declareEvent(name, options?)

Declare an event that can be emitted. options.capability gates who may subscribe.

server.declareEvent("app.tick");

server.emit(name, payload)

Send an event to all connected clients.

server.emit("app.tick", { t: Date.now() });

server.listDevices()

List all paired devices (not only currently connected ones).

const devices = server.listDevices();
// [{ deviceId, name, caps, addedAt, lastSeen, revokedAt }]

server.revokeDevice(deviceId)

Revoke a paired device’s access and close any of its active sessions. Returns true if the device existed.

server.revokeDevice(deviceId);

server.revokeAllDevices()

Revoke every currently-paired device.

server.revokeAllDevices();

server.setDeviceCaps(deviceId, caps)

Replace a paired device’s granted capability set.

server.setDeviceCaps(deviceId, ["app.control"]);

server.getConnectivity()

A moment-in-time snapshot of how reachable the host is, with a human-readable message.

const status = server.getConnectivity();
// { reach: "local-only" | "relayed" | "offline", lan, relay, signaling, webrtc, message, transports }

server.connectionEndpoints(mode?)

Every route a client could use to reach the host right now, in the order a client should try them. This is the single source of truth for pairing endpoints — it never invents a route, and a wan entry appears only when one genuinely exists.

server.connectionEndpoints();
// [{ kind: "lan", url: "ws://192.168.1.83:57525" },
//  { kind: "wan", url: "ws://203.0.113.9:57525" }]

kind is one of "lan" | "wan" | "sig" | "relay" | "tunnel". Passing mode filters to what that network mode allows, without changing the host’s own mode.

await server.setNetworkMode(mode)

Changes the running host’s actual transport policy. Switching to "local-only" releases router mappings, disconnects signaling and relay services, and reconnects active devices through a permitted local route. Switching back to a remote-capable mode starts its configured transports again.

Use this method for settings UI; changing server.config.networkMode directly does not apply live transport lifecycle changes.

server.enableRemoteAccess()

Opens remote access now, if it is not already open. setNetworkMode("remote") calls it for you; call it directly when a diagnostics UI needs to probe the router without changing the host’s selected mode.

Requires the LAN listener to be bound to all interfaces (lan: { bind: "all" }).

server.status()

A structured snapshot for a diagnostics panel: application info, device id and fingerprint, active transports, network mode, device count, secret-store backend, and the permission policy in force.

const { secrets, transports, networkMode } = server.status();

server.getRemoteDiagnostics()

What the router said about the last port-mapping attempt (protocol tried, public address, CGNAT detection), or null if remote access was never attempted.

server.getInstallHandoff(handoffId)

Resolves a device-link handoff minted over RPC, used by the iOS “Add to Home Screen” flow so an installed PWA inherits trust from the browser tab that paired it. Returns null once it is used or expired.

Server events

Subscribe with server.typedOn(event, callback) or the inherited EventEmitter#on.

Event	Payload	Description
devicePaired	TrustedDeviceRecord	A device completed pairing
deviceRevoked	deviceId: string	A device’s access was revoked
deviceConnected	{ deviceId, transport }	A paired device opened a session
deviceDisconnected	{ deviceId, transport }	A paired device’s session closed
pairingIssued	PairingCodeInfo	A new pairing code was generated
connectivity	ConnectivityStatus	Host reachability changed

---

Client SDK (@crosslink/sdk-browser)

createSecureCrosslinkClient(options?)

The preferred browser entry point. Identity and paired-app records are encrypted at rest under a non-extractable WebCrypto key.

import { createSecureCrosslinkClient } from "@crosslink/sdk-browser";

const client = await createSecureCrosslinkClient({ deviceName: "Phone" });

Accepts allowPlaintextFallback to permit unencrypted storage when WebCrypto/IndexedDB is unavailable.

createCrosslinkClient(options?)

Synchronous factory that defaults storage to localStorage. Use it when you supply your own storage, or need a client without awaiting.

CrosslinkClient.create(options?)

Factory method to create a client whose identity is encrypted at rest with WebCrypto/IndexedDB when available.

import { CrosslinkClient } from "@crosslink/sdk-browser";

const client = await CrosslinkClient.create(options);

create() additionally accepts allowPlaintextFallback (boolean), which lets it fall back to unencrypted storage when WebCrypto/IndexedDB is unavailable.

new CrosslinkClient(options?)

Synchronous constructor for embedders that supply their own storage. Without an explicit storage, identity lives only in memory for the process lifetime — prefer CrosslinkClient.create() in browsers.

const client = new CrosslinkClient(options);

Options

Property	Type	Required	Description
deviceName	string	No	Device name shown to host
storage	SecureStorage	No	Custom storage backend
onStateChange	(state, detail?) => void	No	State change callback
onConfirmPairing	(req) => boolean | Promise<boolean>	No	Pairing confirmation
logger	Logger	No	Custom logger
dialTimeoutMs	number	No	Connection timeout (default: 10000)
relayToken	string	No	Shared secret for a private relay
networkMode	"auto" | "local-only" | "lan-and-relay"	No	Connection candidate preference

Client methods

client.pairFromQr(text, requestedCaps?, codeOverride?)

Applications rarely call this. CrosslinkMobileBootstrap (and therefore mobile.entry) runs pairing, including SAS confirmation, the install handoff and the error states. Call it directly only when you are driving a client with no Crosslink UI — see Custom UI.

Pair with a host via a scanned QR/URI (or a hosted bootstrap link).

const record = await client.pairFromQr(uri, ["app.control"]);

client.connect(appId?)

Connect to a previously paired host. Without appId, connects to the first paired app on record. Returns the RpcClient once connected.

const rpc = await client.connect();

client.close()

Close the current connection.

client.close();

client.forget(appId)

Remove a paired host.

client.forget("com.example.myapp");

client.listApps()

List all paired hosts.

const apps = client.listApps();

client.onStateChange(listener)

Subscribe to connection-state changes; returns an unsubscribe function. This is the only way the client reports connection lifecycle — it is not an event emitter.

const unsubscribe = client.onStateChange((state, detail) => {
  console.log("state:", state, detail);
});

state is one of: "offline", "discovering", "pairing", "connecting", "direct", "turn-relayed", "crosslink-relayed", "reconnecting", "unauthorized", "revoked", "protocol-incompatible".

---

RPC interface

rpc.call(method, args?, options?)

Call an RPC method. options.timeoutMs overrides the default request timeout.

const result = await rpc.call("app.status", { detail: true });

rpc.subscribe(event, callback)

Subscribe to an event. Returns an unsubscribe function.

const unsubscribe = rpc.subscribe("app.tick", (payload) => {
  console.log(payload);
});

rpc.cancel(requestId)

Cancel an in-flight request by id.

RpcClient has no built-in “connected” / “disconnected” / “error” events, and no hasCapability method — capability enforcement happens on the host, and a denied call rejects with a capability_denied error (see Error Codes).

---

Crosslink-owned UI

These are the APIs behind the pairing, bootstrap, install, offline and revoked experiences. You mount them; Crosslink implements them.

createPairingCard(options)

@crosslink/sdk-browser — the canonical desktop pairing UI.

createPairingCard({ target: "#crosslink" });

The card reads the application’s identity and palette from the host’s application block, delivered with every pairing session. The options below are overrides, applied field by field over what the host reported.

Option	Type	Description
target	HTMLElement | string	Where to mount
source	false | true | string | PairingSource	Omit for the canonical /__crosslink source. true is a compatibility alias; a string selects another base path; an object supplies a custom transport; false explicitly selects advanced controlled mode
appName	string	Overrides the host’s application name
appIcon	string	Overrides the host’s icon. Never replaces the Crosslink mark
brand	CrosslinkTheme	accentColor, backgroundColor, textColor, appearance — each overrides the host’s
blurb	string	One sentence about what pairing does
refreshLeadSeconds	number	Headroom before expiry at which a new code is minted (default 15)
onSession	(session) => void	After a session is minted
onDeviceConnected	(deviceId?) => void	When a paired device connects
onError	(error) => void	After the card renders a failure

Methods: refresh(), setNetworkMode(mode), getNetworkMode(), update(state), setBrand(theme), getBrand(), attachSource(source), destroy().

@crosslink/react exports CrosslinkPairingCard, a thin mount around the same implementation.

CrosslinkMobileBootstrap

@crosslink/sdk-browser — the mobile lifecycle: first pair, code entry, SAS confirmation, Add to Home Screen, Continue in Browser, install handoff, offline, reconnecting, revoked, and the handoff into your app.

Constructed for you when the host has mobile.entry. Construct it directly only when serving the page from outside a Crosslink host.

Methods: start(), getState(), getClient(), getEnvironment(), destroy().

describeBootstrapEnvironment()

@crosslink/sdk-browser — what the current origin permits: secureContext, serviceWorkerAvailable, webCryptoAvailable, installable, insecureTransportBlocked, and a limitations[] of plain sentences.

filterEndpointsForOrigin(endpoints, pageOrigin)

@crosslink/core — splits advertised endpoints into usable and blocked for a given page origin. An https page cannot open ws://; this is what reports that as a blocked route with a reason rather than a connection timeout.

---

Host: serving the mobile experience

host.createBootstrapHandler()

An HTTP handler serving your mobile.entry plus the manifest, service worker, icons, browser SDK and install handoff. Mounted automatically on the transport port when mobile.entry is set; call it to mount on a server you already run.

mobile.attribution configures the Crosslink attribution footer the bootstrap mounts on the authorized mobile app shell — color, background, size, offset, className. It participates in normal layout flow and there is no field that removes it. See Mobile bootstrap.

host.createControlHandler(options?)

The loopback-only system endpoints the pairing card consumes: /pairing, /network-mode, /devices, /revoke, /events, /widget.js. Refuses non-loopback peers itself. /pairing answers with the session and the host’s application block, which is how the card renders your name, icon and colours without the page repeating them. options.fallback handles everything outside the Crosslink base path, so your own routes sit behind it.

host.describeMobileDelivery()

A deployment-level diagnostic with mode, directLanTransport, secureWssTransport, dynamicEndpointDiscovery, bootstrapAssetsConfigured, durableOrigin, and the origin capabilities serviceWorkerOriginEligible, offlineShell, installable, and encryptedDeviceIdentity. Its multiline message labels LAN HTTP versus a secure published bootstrap. These are configuration/origin capabilities, not a claim about a particular phone; use describeBootstrapEnvironment() in the page for actual browser runtime support. See Durable Origins.

host.writeStaticBootstrap(outDir, overrides?)

Writes Crosslink’s bootstrap as a static site — index.html, crosslink-sdk.js, crosslink-boot.js, sw.js, manifest.webmanifest, crosslink-mark.svg, two generated PNG icons, .nojekyll, and any explicitly requested assets. All framework links are relative, so ordinary static hosting and GitHub Pages project sites work. It embeds public application branding/capability metadata, not host endpoints, relay credentials, pairing codes, device keys, or trusted device records. See Durable Origins for its traffic, trust, and optional-service boundaries.

host.bootstrapOrigin()

The origin a phone should load the bootstrap from: the configured pairing.bootstrapUrl when set, otherwise the best route this host advertises.