@byokit/relay weekly downloads statistics

<h1 align="center">@byokit/relay</h1> <p align="center"> <a href="https://www.npmjs.com/package/@byokit/relay"><img alt="npm" src="https://img.shields.io/npm/v/@byokit/relay?style=flat&label=npm" /></a> <a href="https://github.com/umeranjum17/byokit/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/umeranjum17/byokit/ci.yml?style=flat&branch=main" /></a> <a href="LICENSE"><img alt="Apache 2.0" src="https://img.shields.io/badge/license-Apache--2.0-666?style=flat" /></a> <img alt="Node | device side anywhere" src="https://img.shields.io/badge/platform-Node%20%7C%20device%20side%20anywhere-666?style=flat" /> </p> <p align="center"><strong>A blind relay for <a href="../pair"><code>@byokit/pair</code></a>: the home computer dials out, phones reach it through the relay.</strong><br/> The home computer (the <b>host</b>) needs no open port. The relay routes pair's encrypted frames by host address and cannot read them. It also keeps what a sleeping phone needs (push notifications), a short code a person can type to find a host, and the owner's list of which hosts may use it. For apps that pair a phone or browser with a computer over pair and want to reach it away from home.</p>

The one exception to "cannot read": push notification text. The relay can read the title and any content the host explicitly includes.

Node only (the device side, @byokit/relay/device, runs anywhere: no Node APIs, so browsers and React Native too). Depends on @byokit/pair (see package.json for the version); it doesn't change its wire format or crypto.

Install

npm install @byokit/relay @byokit/pair

· Latest release · All releases

Quickstart

npm install @byokit/relay @byokit/pair

A relay on loopback with its state in memory, a link host registering through RelayClient, and a device that finds the host by short code and pairs with it:

import { createServer } from 'node:http';
import { Host, keyPair, pairWithCode, DeviceLink } from '@byokit/pair';
import { Relay, RelayClient, type RelayState } from '@byokit/relay';
import { findHost } from '@byokit/relay/device';

// The relay: loopback, state kept in memory.
let saved: RelayState | undefined;
const relay = await Relay.open({ store: { load: () => saved, save: (s) => { saved = s; } } });
const server = createServer();
relay.attach(server);
await new Promise<void>((r) => server.listen(7300, '127.0.0.1', r));

// The host: a link Host that dials out to the relay.
const host = await Host.open({
  keys: keyPair(), name: 'Kitchen computer',
  confirm: () => true, handle: (req) => ({ pong: req.op }),
});
await relay.admit(host.keys.publicKey, 'Kitchen computer');
const client = new RelayClient(host, { url: 'ws://127.0.0.1:7300/relay/v1/host', onStatus: (s) => console.log('host:', s) });
const { code: short } = await client.code();
const { code } = host.code({ role: 'control' });
console.log('short code:', short, ' link code:', code);

// The device: types both codes.
const url = await findHost('http://127.0.0.1:7300', short);
console.log('findHost:', url);
const grant = await pairWithCode(url, code, { name: 'Pixel 9', onWords: (w) => console.log('verify words:', w) });
const link = new DeviceLink(grant);
console.log('reply:', await link.request('ping'));

link.stop(); client.stop(); host.close(); relay.close(); server.closeAllConnections(); server.close();

Real output (codes, host id and words differ on each run):

host: online
short code: RMWWK7  link code: 8Y75-TSWX-9BH9
findHost: ws://127.0.0.1:7300/link/v1/GG0AKCQjt_SpiZKdG129tg
verify words: galaxy creek
reply: { pong: 'ping' }

API at a glance

Export	What it does
Relay	The relay server: Relay.open(options), attach(server) (or upgrade / request), admit, enrolment, hosts, revoke, count, close
RelayClient	The host's side: one outbound socket that proves the host's key and reconnects; code, subscribe, unsubscribe, notify, revoke, pending, self, leave, stop
ownerClient	The owner's HTTP API: hosts, enrolment, revoke; accepts an injected fetch
claimProvision	A new computer's app: grants the phone key a provisioning token bound, through link's own durable grants
RelayOwnerError	HTTP refusal with a numeric status and a code: forbidden (403), not-found (404), or request-failed
RelayLookupError	A host lookup the relay refused or did not answer: a code of wrong-code, unreachable or timeout
findHost	The device's side: a short code → the link address to dial, bounded by timeoutMs (default 8 s; also from @byokit/relay/device)
linkUrl	A relay URL and known host id → the link address to dial (also from @byokit/relay/device)
JobChannel	Host-owned bounded job history: create, follow, drop; replays ordered frames after a cursor
readJobStream	Portable ordered text/image/usage/end reader (also from @byokit/relay/device)
LIMITS	Per-client-address limits per minute
CLOSE	WebSocket close codes the relay uses (replaced, not enrolled, bad proof, enrolment, revoked, too many)
isAllowedEndpoint, isExpoToken	Checks for Web Push endpoints and Expo push tokens
MAX_ACTION_REPLY	The most UTF-8 bytes a notification action's sealed reply may carry (8192)
Types	RelayOptions, RelayStore, RelayState, HostRecord, Enrolment, ProvisionBinding, RelayClientOptions, RelayStatus, PushAction, Notification, PushRecord, Subscription, WebSubscription

Relay

import { createServer } from 'node:http';
import { Relay } from '@byokit/relay';…