@nightnetwork/moonbeam

@nightnetwork/moonbeam

Browser network stack. Wisp relay, virtual LAN, TCP/UDP NAT.

Complete browser-side networking library providing a Wisp v2.1 client, in-page relay with local TCP listener registration, virtual LAN gateway with DHCP, TCP/UDP NAT, configurable egress policy, and QEMU-wasm integration.

Version 1.0.0 · Apache-2.0

---

Features

MoonbeamRelay

In-page Wisp relay endpoint. Accepts Wisp frames from local consumers (Nova, other WASM clients) over MessagePort transports and forwards them through a shared upstream WispClient.

• MessagePort transport — each attached client gets its own MessagePort; no WebSocket per client
• Stream-level pass-through — stream IDs are rewritten to relay-unique IDs before forwarding upstream, rewritten back on the return path
• Local TCP listener registration — registerListener(host, port, handler) intercepts CONNECT requests matching a host:port and routes them to an in-process handler instead of upstream
• Virtual IP pool — each attached client receives a unique 100.64.0.x address from a 254-address CGNAT pool
• Flow control — CONTINUE credit protocol for TCP streams; bounded receive windows for local streams with automatic replenishment
• Client snapshots — clientsSnapshot() and listenersSnapshot() return frozen observability views of all attached clients, their streams, and registered listeners

WispClient

From-scratch Wisp v2.1 protocol client.

• Wisp v2.1 and v1 support — full v2 INFO handshake with extension negotiation; v1 fallback enabled by default (allowV1: true)
• WebSocket transport — single multiplexed WebSocket connection; works in browsers, Web Workers, and Node 22+
• Stream multiplexing — create TCP and UDP streams over one connection with automatic stream ID management
• CONTINUE credit protocol — per-stream TCP backpressure with credit tracking and send queuing
• Dual API — both Streams API (readable/writable) and event API (on('data'), on('close'), etc.) per stream
• Extension negotiation — UDP, Stream Open Confirmation, MOTD, password/pubkey auth detection
• Error codes — E_WISP_HANDSHAKE, E_WISP_V1_UNSUPPORTED, E_WISP_AUTH_REQUIRED, E_WISP_STREAM_ID_EXHAUSTED, E_WISP_UDP_UNSUPPORTED

Gateway

Top-level orchestrator composing a virtual LAN from all subsystems.

• Full virtual LAN — lwIP NetworkStack with Tun, Loopback, and Tap interfaces wired in LIFO order per spec §2.4
• Automatic DHCP — single-client DHCP lease for the VM (configurable or disabled with vmIp: null)
• Soft-router — parallel IP forwarder that intercepts off-subnet guest packets and routes them to the NATs, bypassing lwIP's endpoint-only limitation
• Host-side service bindings — connectTcp(), listenTcp(), openUdp() for host code
• Hot-swap support — setWispClient() atomically swaps the upstream Wisp connection; NATs read the current client via callback
• Lifecycle events — connect, disconnect, error, wisp-changed

TcpNat

Stateful TCP NAT translating guest IPv4/TCP packets into multiplexed Wisp TCP streams.

• NAT transparency — guest sees responses as if from the remote server (src=remote, dst=guest)
• Sequence-number tracking — u32 modular arithmetic per RFC 793; out-of-order packets dropped (guest retransmits)
• MSS chunking — upstream Wisp chunks are segmented to 1460B MSS before delivery to guest (avoids virtio-net oversized frame crashes)
• Swap-in-progress queue — SYNs during Wisp hot-swap are buffered (bounded, default 256) and drained when the new client is live
• Stream Open Confirmation — defers SYN-ACK until upstream confirms (when negotiated), giving the guest ECONNREFUSED semantics
• resetAll() — RST every active flow for hot-swap orchestration

UdpNat

Stateful UDP NAT with per-5-tuple flow tracking.

• LRU eviction — capped at maxFlows (default 1024) with least-recently-used eviction
• Idle sweeper — closes flows idle longer than idleTimeoutMs (default 60s)
• ICMP port-unreachable — synthesized for policy-denied or swap-in-progress datagrams
• Stats — getStats() returns active flows, total created, forwarded, and dropped counts

EgressPolicy

Configurable allow/deny policy for outbound connections.

• Allow tokens — 'public' (excludes all IANA reserved ranges), '*' (everything except loopback unless opted in), or explicit CIDR strings
• Deny list — CIDR-based hard deny (wins over allow)
• Port deny — block specific ports globally
• Loopback guard — allowLoopback: false (default) prevents routing localhost through remote Wisp
• onBlocked callback — receives structured BlockedInfo with IP, port, proto, and reason (rfc1918, cgnat, loopback, multicast, deny-cidr, deny-port, etc.)
• Allocation-free success path — permits() allocates nothing on allow; only the blocked path creates objects

FakeWebSocket

QEMU-wasm WebSocket interception.

• WebSocket-shaped API — extends EventTarget; supports addEventListener, on* setters, send(), close(), readyState, binaryType
• FakeWebSocketHost interface — onConnect, onSend, onClose callbacks route bytes into the in-page lwIP stack
• installFakeWebSocket(Module, host) — patches Emscripten's Module.websocket.WebSocketConstructor and optionally globalThis.WebSocket with sentinel-URL detection; returns an uninstall function
• No globals in workers — auto-detects WorkerGlobalScope and skips the global patch unless forceGlobalPatch: true

Packet helpers

Pure-function codec for Ethernet, IPv4, TCP, UDP, ICMP, and ARP.

• parseIPv4 / buildIPv4Packet
• parseTcp / buildTcpSegment
• parseUdp / buildUdpSegment
• parseEthernet / buildEthernetFrame
• buildIcmpPortUnreachable
• ipToNum / numToIp / parseCidr / isInSubnet / macEquals

---

Installation

npm install @nightnetwork/moonbeam

Requires a modern JS runtime (browser or Node ≥ 20) with EventTarget, Uint8Array, ReadableStream/WritableStream, and WebSocket. Cross-origin isolation (COOP same-origin + COEP require-corp) is needed if callers use SharedArrayBuffer.

---

Quick start

MoonbeamRelay with Nova

import { MoonbeamRelay } from '@nightnetwork/moonbeam';

// Create a relay backed by a Wisp server
const relay = await MoonbeamRelay.create({
  wispUrl: 'wss://your-wisp-server/',
});

// Attach a client — returns a MessagePort to hand to Nova
const port = relay.attach({ label: 'nova-worker' });

// Register a local TCP listener (e.g., for localhost:8080)
const unregister = relay.registerListener('localhost', 8080, (socket) => {
  socket.onData((data) => {
    // Handle incoming data from the client
    socket.send(new TextEncoder().encode('HTTP/1.1 200 OK\r\n\r\nHello'));
    socket.close();
  });
});

// Observability
console.log(relay.clientCount());        // 1
console.log(relay.clientsSnapshot());    // frozen snapshot of all clients + streams
console.log(relay.listenersSnapshot());  // frozen snapshot of registered listeners

// Cleanup
unregister();          // remove the listener
relay.detach(port);    // detach the client
await relay.close();   // tear down relay + upstream WebSocket

Gateway with QEMU-wasm

import {
  Gateway,
  FakeWebSocket,
  installFakeWebSocket,
  type FakeWebSocketHost,
} from '@nightnetwork/moonbeam';

// 1. Create and initialize the gateway
const gateway = new Gateway({
  wispUrl: 'wss://your-wisp-server/',
  egress: { allow: ['public'] },
  gatewayIp: '192.168.127.1/24',
});
await gateway.init();

// 2. Wire QEMU-wasm's networking through the gateway
const tap = gateway.getTap();
const softRouter = gateway.getSoftRouter();

const host: FakeWebSocketHost = {
  onConnect(send) {
    // Pump frames from tap + soft-router to QEMU
    const reader = tap.readable.getReader();
    (async () => {
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        send(value);
      }
    })();
    softRouter.setSend(send);
  },
  onSend(data) {
    // Guest frame → lwIP + soft-router
    const writer = tap.writable.getWriter();
    writer.write(data).then(() => writer.releaseLock());
    softRouter.ingress(data);
  },
  onClose() {
    gateway.destroy();
  },
};

// 3. Install the FakeWebSocket before QEMU boots
const uninstall = installFakeWebSocket(Module, host);

// QEMU's `-netdev socket,connect=ws://wisp-gateway.local/` will be
// intercepted and routed through the in-page gateway.

---

API reference

MoonbeamRelay

class MoonbeamRelay {
  static create(opts: MoonbeamRelayOptions): Promise<MoonbeamRelay>
  attach(metadata?: MoonbeamAttachmentMetadata): MessagePort
  detach(port: MessagePort): void
  registerListener(host: string, port: number, handler: MoonbeamLocalConnectionHandler): () => void
  close(): Promise<void>
  clientCount(): number
  streamCount(): number
  clientsSnapshot(): readonly MoonbeamClientSnapshot[]
  listenerCount(): number
  listenersSnapshot(): readonly MoonbeamListenerSnapshot[]
  isClosed(): boolean
}

Method	Description
create(opts)	Async factory. Connects to the upstream Wisp server and resolves when the handshake completes.
attach(metadata?)	Attach a new client. Returns a MessagePort the client uses to speak Wisp frames. Assigns a virtual IP from the 100.64.0.0/24 pool.
detach(port)	Detach a client by its MessagePort. Closes all streams and reclaims the virtual IP.
registerListener(host, port, handler)	Register a local TCP listener. CONNECT requests matching host:port are routed to handler instead of upstream. Returns an unregister function.
close()	Gracefully shut down: detach all clients, close listeners, close the upstream WispClient.
clientCount()	Number of currently attached clients.
streamCount()	Total open upstream + local streams across all clients.
clientsSnapshot()	Frozen snapshot of all clients and their streams (id, virtualIp, label, connectedAt, streams).
listenerCount()	Number of registered listeners.
listenersSnapshot()	Frozen snapshot of all listeners (host, port, activeStreams).
isClosed()	Whether the relay has been closed.

Gateway

class Gateway {
  constructor(config: GatewayConfig)
  init(): Promise<void>
  destroy(): Promise<void>
  getStack(): NetworkStack
  getTap(): TapInterface
  getTun(): TunInterface
  getSoftRouter(): SoftRouter
  getVmIp(): string
  get wisp(): WispClient
  get swapInProgress(): boolean
  connectTcp(host: string, port: number): Promise<TcpSocket>
  listenTcp(port: number): Promise<TcpListener>
  openUdp(port?: number): Promise<UdpSocket>
  setWispClient(newClient: WispClient): void
  on(event: string, listener: Function): () => void
}

Option	Default	Description
wispUrl	(required)	Wisp v2.1 endpoint URL
egress	{ allow: ['public'] }	Egress policy configuration
gatewayIp	'192.168.127.1/24'	LAN-side gateway IP in CIDR
gatewayMac	'02:00:00:00:00:01'	Gateway MAC address
vmIp	gateway + 1	VM IP for DHCP; null disables DHCP
dnsServer	'1.1.1.1'	DNS advertised via DHCP
dhcpLeaseTime	86400	DHCP lease duration in seconds
tunIp	'240.0.0.1/0'	Tun interface IP (Class E, never-routable)
allowV1	true	Accept Wisp v1 servers
udpAssumedInV1	true	Assume UDP support for v1 servers

---

Architecture overview

┌─────────────────────────────────────────────────────────┐
│  Browser page                                           │
│                                                         │
│  ┌──────────┐     MessagePort      ┌────────────────┐   │
│  │  Nova /  │◄────────────────────►│ MoonbeamRelay  │   │
│  │  WASM    │  Wisp frames         │  (in-page)     │   │
│  └──────────┘                      └───────┬────────┘   │
│                                            │            │
│  ┌──────────┐   FakeWebSocket    ┌─────────▼────────┐   │
│  │  QEMU-   │◄──────────────────►│    Gateway       │   │
│  │  wasm    │  Ethernet frames   │  ┌─────────────┐ │   │
│  └──────────┘                    │  │  lwIP Stack  │ │   │
│                                  │  │  Tap/Tun/Lo  │ │   │
│                                  │  └──────┬──────┘ │   │
│                                  │         │        │   │
│                                  │  ┌──────▼──────┐ │   │
│                                  │  │ SoftRouter   │ │   │
│                                  │  └──┬───────┬──┘ │   │
│                                  │     │       │    │   │
│                                  │  ┌──▼──┐ ┌──▼──┐│   │
│                                  │  │TcpNat│ │UdpNat││   │
│                                  │  └──┬──┘ └──┬──┘│   │
│                                  │     │       │    │   │
│                                  │  ┌──▼───────▼──┐│   │
│                                  │  │ EgressPolicy ││   │
│                                  │  └──────┬──────┘│   │
│                                  └─────────┼───────┘   │
│                                            │            │
│                                     ┌──────▼──────┐     │
│                                     │ WispClient  │     │
│                                     │ (WebSocket) │     │
│                                     └──────┬──────┘     │
└────────────────────────────────────────────┼─────────────┘
                                             │
                                    ┌────────▼────────┐
                                    │  Wisp Server    │
                                    │  (remote)       │
                                    └─────────────────┘

The Gateway path handles full virtual-machine networking: guest Ethernet frames flow through the lwIP stack and soft-router. Off-subnet IP packets are extracted, passed through the TCP/UDP NATs, checked against the egress policy, and forwarded as Wisp streams.

The MoonbeamRelay path is lighter-weight: WASM clients speak Wisp directly over MessagePort. The relay rewrites stream IDs and multiplexes all clients onto a single upstream WispClient. Local TCP listeners allow in-process request interception without hitting the network.

---

Testing

npm test              # 330+ unit tests via Vitest
npm run test:watch    # watch mode
npm run typecheck     # tsc --noEmit (see known issue below)
npm run build         # emit dist/ (tsc + ESM extension fixer)

The test suite covers all components: WispClient handshake (v1 and v2), stream multiplexing, credit protocol, MoonbeamRelay attach/detach/listener lifecycle, TCP NAT connection/data/FIN/RST/swap-queue flows, UDP NAT flow tracking/eviction/ICMP, DHCP DISCOVER/REQUEST/NAK/RELEASE, egress policy allow/deny/CIDR/port/loopback, FakeWebSocket state machine, soft-router MAC learning and IP forwarding, and packet codec round-trips.

Known issue: npm run typecheck currently reports errors due to a rootDir/include contradiction inherited from the original tsconfig. Runtime, build, and tests are unaffected — Vitest uses esbuild and does not hit this path.

---

Browser requirements

• Modern browser or Node ≥ 20
• EventTarget, MessageChannel, MessagePort
• ReadableStream, WritableStream (WHATWG Streams)
• WebSocket (for WispClient; not needed if using _injectWebSocket)
• Uint8Array, DataView, ArrayBuffer
• Cross-origin isolation headers if using SharedArrayBuffer

---

Migration from 0.x

0.x → 1.0.0

• Stable API — all public interfaces are now considered stable. The MoonbeamRelay, WispClient, Gateway, and all NAT/policy/packet APIs have settled.
• MoonbeamRelay — introduced in 0.2, now fully stable with local TCP listener support, virtual IP assignment, and observability snapshots.
• No breaking changes from 0.3 — the 1.0 release is a stability milestone. All existing imports and usage patterns continue to work.
• Package access — published as public on npm (was restricted in 0.x).

---

Contributing

1. Fork & clone
2. npm install
3. npm test — all tests must pass
4. npm run typecheck — note the known tsconfig issue; focus on new code being type-clean
5. Open a PR against main

---

License

Apache-2.0