wire-mesh 0.0.0 → 1.0.0

package/README.md

@@ -0,0 +1,54 @@
+# wire-mesh
+
+A self-hostable, no-cloud LAN counterpart to `@exadev/wire-mesh-cloudflare-hub`: the same relay role (device discovery over gossip, pairing `relay-connect` initiators with their target, forwarding `relay-data` both ways), served by a plain Node process instead of a Cloudflare Durable Object. Run it on any machine already reachable on the network — a home server, a laptop on the same Wi-Fi, a container on a LAN — with no Cloudflare account, no deployment step, and no cloud dependency at all.
+
+## Why this exists
+
+`cloudflare-hub` is the always-on, public reference deployment. It needs an account and a deployment pipeline, and it puts every relayed byte through Cloudflare's network. `wire-mesh` is for the opposite case: two devices on the same LAN (or reachable over a VPN/tailnet) that want a relay neither of them has to pay for or deploy anywhere — just `npx wire-mesh` on whichever machine is already running.
+
+## How it maps onto core's ports
+
+The relay/pairing/gossip-registry domain logic itself is not duplicated here — it is `wire-mesh-core`'s `./domain/relay-hub` export, the same module `cloudflare-hub` consumes, proven transport-agnostic by running against core's TCP adapter, `cloudflare-hub`'s WebSocket adapter, and this package's own adapter alike. This package supplies exactly one new thing: a **Connection**/**Transport** port implementation over the `ws` npm package (`src/adapters/node-websocket-transport.ts`) — the same one-CBOR-frame-per-binary-message convention as the hub's and web-console's own WebSocket adapters, but driven through `ws`'s idiomatic Node `EventEmitter` API (`.on`, not `.addEventListener`) rather than the platform `WebSocket` those two wrap. Unlike the browser adapter, whose `listen()` always rejects (a browser tab can never accept inbound connections), and unlike `cloudflare-hub`'s adapter, which has no `listen()` at all (ingress arrives through the Durable Object's own upgrade handling), this adapter's `listen()` is a real implementation: this package's entire reason to exist is being reachable on a LAN.
+
+`src/server.ts` is the CLI entrypoint: it wires `createRelayHub()` over `createNodeWebSocketTransport()`. The same listener answers a browser too: `GET /health` returns a small JSON health response (the same shape `cloudflare-hub`'s own `healthResponse()` returns), and every other request is served from `@exadev/wire-mesh-web-console`'s own built static output — copied into this package's `dist/web-console` at build time (`scripts/copy-web-console-dist.mjs`, run as the second half of the `_build` script), so a self-hosted node has somewhere to point a browser at, not just other wire-mesh peers (wire-mesh#184). An extension-less path that doesn't match a real file falls back to `index.html`, so the console's own client-side routes still resolve.
+
+## Running it
+
+```sh
+npx wire-mesh                       # binds 0.0.0.0:8787, plain ws:// + http://
+npx wire-mesh --bind 0.0.0.0:9000    # a different port
+npx wire-mesh --bind 127.0.0.1:8787  # loopback only, if that's genuinely what you want
+npx wire-mesh --tls-cert cert.pem --tls-key key.pem   # wss:// + https://, cert/key must be given together
+```
+
+or, installed as a dependency:
+
+```sh
+pnpm add wire-mesh
+wire-mesh --bind 0.0.0.0:8787
+```
+
+**Default bind address is `0.0.0.0:8787`, not loopback.** Unlike a typical dev-server tool, whose loopback-only default assumes only the machine itself needs to reach it, this package's whole purpose is LAN reachability — a phone on the same network, a laptop in the next room. `--bind` overrides the address if you want to restrict it (loopback-only, a specific interface, a different port).
+
+Point a browser at the bound address to reach the console, or check its health directly:
+
+```sh
+curl http://<host>:8787/health
+# {"ok":true,"node":"wire-mesh","roles":["relay"]}
+```
+
+**TLS (`wss://`/`https://`)** is opt-in via `--tls-cert`/`--tls-key`, both required together — this package generates no certificate of its own, so bring your own (a real one from a CA, or a self-signed one for a LAN). This matters specifically for wire-mesh#182/#183: an `https://`-served PWA (`mesh.exadev.io`) can only reach a plain `ws://` node if it's literally on `localhost` of the same machine, since browsers block mixed-content WebSocket connections from a secure page to an insecure one — a self-hosted node on someone's LAN, addressed by its own IP, needs to answer `wss://` for that PWA to reach it at all.
+
+**Security note:** this package adds no access control beyond the protocol's own capability tokens (`core/exec`/`core/management` verbs gated by a signed capability, same as any other wire-mesh node) — anyone who can reach the bound address can gossip, relay-connect, and relay-data through it. Bind to a trusted network (a home LAN, a VPN/tailnet) rather than a public interface unless the capability-token story for whatever you're relaying is one you're comfortable exposing to the open internet.
+
+## What is real versus deferred
+
+Real and tested: the Node WebSocket transport adapter (hostile-input behaviour included — undecodable bytes and non-binary messages close the connection; a decodable-but-schema-invalid frame drops without disconnecting), a real loopback round trip (`listen("127.0.0.1:0", ...)` + `connect(...)` against the actual bound address, proving the OS-assigned-port path works), a full relay path verified end to end against real sockets — two genuine WebSocket clients exchanging gossip, relay-connect, relay-inbound, and bidirectional relay-data through a real listener, the in-suite analogue of `cloudflare-hub/scripts/live-check.mjs` for a runtime (plain Node) with no dev-server lifecycle constraints to work around — a real TLS handshake terminating a genuine `wss://` WebSocket connection and an `https://` request against a self-signed fixture certificate, and the console's own static-file routing (root, nested assets, the service worker's required `Service-Worker-Allowed` header, the client-side-route fallback to `index.html`, and a 404 for a genuinely missing file) against a real HTTP server.
+
+Deferred deliberately, matching `cloudflare-hub`'s own list:
+
+- **The announcer role** (`discovery.cddl`'s `mailboxes`) needs a Storage port adapter; none is wired up here yet.
+
+## Type environment
+
+`src/` is plain Node code, typechecked against `@types/node` and `@types/ws` — no DOM lib, no Worker types, matching `wire-mesh-core`'s own type environment exactly (the closest precedent this package's scaffolding mirrors).

package/dist/adapters/node-websocket-transport.cjs

@@ -0,0 +1,183 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_http = require("node:http");
+let node_https = require("node:https");
+let cbor2 = require("cbor2");
+let wire_mesh_core_generated_protocol = require("wire-mesh-core/generated/protocol");
+let ws = require("ws");
+//#region src/adapters/node-websocket-transport.ts
+const CLOSE_NORMAL = 1e3;
+const CLOSE_PROTOCOL_ERROR = 1002;
+const HTTP_NOT_FOUND = 404;
+function hostPortToWsUrl(address) {
+	const { host, port } = parseAddress(address);
+	return `ws://${host}:${String(port)}`;
+}
+function parseAddress(address) {
+	const lastColon = address.lastIndexOf(":");
+	if (lastColon === -1) throw new Error(`expected "host:port", got "${address}"`);
+	return {
+		host: address.slice(0, lastColon),
+		port: Number(address.slice(lastColon + 1))
+	};
+}
+function messageFromFrame(frame) {
+	return new Uint8Array((0, cbor2.encode)(frame, cbor2.cdeEncodeOptions));
+}
+/** A frame that fails schema validation, caught separately from a decode failure so it can be dropped without disconnecting the peer. */
+var SchemaInvalidFrameError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "SchemaInvalidFrameError";
+	}
+};
+/** Decodes one message, distinguishing a decode failure (connection-level) from a schema failure (drop this frame, keep the connection) -- mirroring the other adapters' split between the two. */
+function decodeMessage(data) {
+	let decoded;
+	try {
+		decoded = (0, cbor2.decode)(data, cbor2.cdeDecodeOptions);
+	} catch (error) {
+		throw error instanceof Error ? error : /* @__PURE__ */ new Error(`frame body failed to decode: ${String(error)}`);
+	}
+	const result = wire_mesh_core_generated_protocol.frameSchema.safeParse(decoded);
+	if (!result.success) throw new SchemaInvalidFrameError(result.error.message);
+	return result.data;
+}
+/** Narrows `ws`'s RawData (Buffer | ArrayBuffer | Buffer[]) to a single contiguous, genuinely plain Uint8Array. `ws` only ever delivers an array of buffers when a message arrives fragmented across a stream that itself isn't being reassembled -- doesn't happen for the default (non-streamed) receive path this adapter uses. A Node Buffer IS a Uint8Array subclass, but handing one to cbor2's decode() as-is leaks that subclass into every nested byte-string value decode() returns (it slices the same buffer type it was given); cbor2's encode() then does not recognise a Buffer as a plain byte string and serialises it as a generic object instead, corrupting any value (like a device-id) that round-trips decode -\> store -\> re-encode, as this hub's relay-connect -\> relay-inbound path does. Always copying into a fresh Uint8Array here, the same normalisation the browser/Worker adapters get for free from `new Uint8Array(event.data)` on their own already-ArrayBuffer input, is the fix. */
+function bytesFromRawData(data) {
+	if (Array.isArray(data)) throw new Error("expected a single WebSocket message, got fragments");
+	return new Uint8Array(data);
+}
+/** Wraps an already-open `ws` WebSocket (client or server side) as a Connection, driven through `ws`'s EventEmitter API (`.on`, not `.addEventListener` -- this repo's other Node-native adapter, tcp-transport.ts, uses the same idiomatic-Node style; `.addEventListener` is reserved for the two adapters wrapping an actual platform WebSocket). */
+function wrapNodeWebSocket(ws$1) {
+	const pending = [];
+	const waiters = [];
+	let ended = false;
+	let failure = null;
+	function endAll() {
+		ended = true;
+		for (const waiter of waiters.splice(0)) waiter.resolve({
+			value: void 0,
+			done: true
+		});
+	}
+	function failAll(error) {
+		failure = error;
+		ended = true;
+		for (const waiter of waiters.splice(0)) waiter.reject(error);
+	}
+	ws$1.on("message", (data, isBinary) => {
+		if (!isBinary) {
+			failAll(/* @__PURE__ */ new Error("expected a binary WebSocket message"));
+			ws$1.close(CLOSE_PROTOCOL_ERROR, "protocol error");
+			return;
+		}
+		let frame;
+		try {
+			frame = decodeMessage(bytesFromRawData(data));
+		} catch (error) {
+			if (error instanceof SchemaInvalidFrameError) return;
+			failAll(error instanceof Error ? error : /* @__PURE__ */ new Error(`frame body failed to decode: ${String(error)}`));
+			ws$1.close(CLOSE_PROTOCOL_ERROR, "protocol error");
+			return;
+		}
+		const waiter = waiters.shift();
+		if (waiter) waiter.resolve({
+			value: frame,
+			done: false
+		});
+		else pending.push(frame);
+	});
+	ws$1.on("close", endAll);
+	ws$1.on("error", endAll);
+	const receiveStream = { [Symbol.asyncIterator]() {
+		return { async next() {
+			const next = pending.shift();
+			if (next !== void 0) return {
+				value: next,
+				done: false
+			};
+			if (failure !== null) throw failure;
+			if (ended) return {
+				value: void 0,
+				done: true
+			};
+			return new Promise((resolve, reject) => {
+				waiters.push({
+					resolve,
+					reject
+				});
+			});
+		} };
+	} };
+	return {
+		async send(frame) {
+			if (ended) return Promise.reject(/* @__PURE__ */ new Error("connection is closed"));
+			ws$1.send(messageFromFrame(frame));
+			return Promise.resolve();
+		},
+		receive: () => receiveStream,
+		async close() {
+			ws$1.close(CLOSE_NORMAL);
+			return Promise.resolve();
+		}
+	};
+}
+/** A Node `ws`-based Transport: one CBOR frame per binary WebSocket message, served over a plain `http.Server` this adapter owns, or an `https.Server` when `options.tls` is given. `listen()` is a real implementation (unlike the browser adapter, a client can never accept connections) and supports port 0 for an OS-assigned port, reading the real bound address back the same way core's tcp-transport.ts does. */
+function createNodeWebSocketTransport(options = {}) {
+	return {
+		async connect(address) {
+			const url = /^wss?:\/\/./.test(address);
+			if (!url && !/^[^/]+:\d+$/.test(address)) throw new Error(`expected "host:port" or a ws:// / wss:// URL, got "${address}"`);
+			const target = url ? address : hostPortToWsUrl(address);
+			return new Promise((resolve, reject) => {
+				const ws$2 = new ws.WebSocket(target);
+				ws$2.once("open", () => {
+					resolve(wrapNodeWebSocket(ws$2));
+				});
+				ws$2.once("error", reject);
+			});
+		},
+		async listen(address, onConnection) {
+			const { host, port } = parseAddress(address);
+			return new Promise((resolve, reject) => {
+				const requestHandler = (request, response) => {
+					if (options.onHttpRequest) {
+						options.onHttpRequest(request, response);
+						return;
+					}
+					response.writeHead(HTTP_NOT_FOUND).end();
+				};
+				const httpServer = options.tls ? (0, node_https.createServer)({
+					cert: options.tls.certificatePem,
+					key: options.tls.privateKeyPem
+				}, requestHandler) : (0, node_http.createServer)(requestHandler);
+				const wss = new ws.WebSocketServer({ server: httpServer });
+				wss.on("connection", (ws$3) => {
+					onConnection(wrapNodeWebSocket(ws$3));
+				});
+				httpServer.once("error", reject);
+				httpServer.listen(port, host, () => {
+					const bound = httpServer.address();
+					if (bound === null || typeof bound === "string") {
+						reject(/* @__PURE__ */ new Error("listener did not report a bound address"));
+						return;
+					}
+					resolve({
+						close: async () => new Promise((resolveClose) => {
+							wss.close(() => {
+								httpServer.close(() => {
+									resolveClose();
+								});
+							});
+						}),
+						address: `${bound.address}:${String(bound.port)}`
+					});
+				});
+			});
+		}
+	};
+}
+//#endregion
+exports.createNodeWebSocketTransport = createNodeWebSocketTransport;
+exports.messageFromFrame = messageFromFrame;
+exports.wrapNodeWebSocket = wrapNodeWebSocket;

package/dist/adapters/node-websocket-transport.d.cts

@@ -0,0 +1,18 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+import { Frame } from "wire-mesh-core/generated/protocol";
+import { TlsIdentity } from "wire-mesh-core/adapters/tls-transport";
+import { Connection, Transport } from "wire-mesh-core/ports/transport";
+import { WebSocket } from "ws";
+//#region src/adapters/node-websocket-transport.d.ts
+export declare function messageFromFrame(frame: Frame): Uint8Array<ArrayBuffer>;
+/** Wraps an already-open `ws` WebSocket (client or server side) as a Connection, driven through `ws`'s EventEmitter API (`.on`, not `.addEventListener` -- this repo's other Node-native adapter, tcp-transport.ts, uses the same idiomatic-Node style; `.addEventListener` is reserved for the two adapters wrapping an actual platform WebSocket). */
+export declare function wrapNodeWebSocket(ws: WebSocket): Connection;
+export interface NodeWebSocketTransportOptions {
+  /** Answers a non-Upgrade HTTP request landing on the same listener (e.g. a health check). Requests are 404'd if omitted. */
+  onHttpRequest?: (request: IncomingMessage, response: ServerResponse) => void;
+  /** Serves the listener over TLS (wss://) instead of plain ws:// when given — reusing core's own TlsIdentity shape (already a dependency of this package) rather than a parallel cert/key type for the same concept. Unlike createTlsTransport's mutual-auth model, this adapter never requests a client certificate: a browser's WebSocket client cannot present one, and the whole point of wss:// here is letting an ordinary browser (mesh.exadev.io, wire-mesh#182/#183) reach this node without mixed-content blocking. */
+  tls?: TlsIdentity;
+}
+/** A Node `ws`-based Transport: one CBOR frame per binary WebSocket message, served over a plain `http.Server` this adapter owns, or an `https.Server` when `options.tls` is given. `listen()` is a real implementation (unlike the browser adapter, a client can never accept connections) and supports port 0 for an OS-assigned port, reading the real bound address back the same way core's tcp-transport.ts does. */
+export declare function createNodeWebSocketTransport(options?: Readonly<NodeWebSocketTransportOptions>): Transport;
+//#endregion

package/dist/adapters/node-websocket-transport.d.mts

@@ -0,0 +1,18 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+import { Frame } from "wire-mesh-core/generated/protocol";
+import { WebSocket } from "ws";
+import { TlsIdentity } from "wire-mesh-core/adapters/tls-transport";
+import { Connection, Transport } from "wire-mesh-core/ports/transport";
+//#region src/adapters/node-websocket-transport.d.ts
+export declare function messageFromFrame(frame: Frame): Uint8Array<ArrayBuffer>;
+/** Wraps an already-open `ws` WebSocket (client or server side) as a Connection, driven through `ws`'s EventEmitter API (`.on`, not `.addEventListener` -- this repo's other Node-native adapter, tcp-transport.ts, uses the same idiomatic-Node style; `.addEventListener` is reserved for the two adapters wrapping an actual platform WebSocket). */
+export declare function wrapNodeWebSocket(ws: WebSocket): Connection;
+export interface NodeWebSocketTransportOptions {
+  /** Answers a non-Upgrade HTTP request landing on the same listener (e.g. a health check). Requests are 404'd if omitted. */
+  onHttpRequest?: (request: IncomingMessage, response: ServerResponse) => void;
+  /** Serves the listener over TLS (wss://) instead of plain ws:// when given — reusing core's own TlsIdentity shape (already a dependency of this package) rather than a parallel cert/key type for the same concept. Unlike createTlsTransport's mutual-auth model, this adapter never requests a client certificate: a browser's WebSocket client cannot present one, and the whole point of wss:// here is letting an ordinary browser (mesh.exadev.io, wire-mesh#182/#183) reach this node without mixed-content blocking. */
+  tls?: TlsIdentity;
+}
+/** A Node `ws`-based Transport: one CBOR frame per binary WebSocket message, served over a plain `http.Server` this adapter owns, or an `https.Server` when `options.tls` is given. `listen()` is a real implementation (unlike the browser adapter, a client can never accept connections) and supports port 0 for an OS-assigned port, reading the real bound address back the same way core's tcp-transport.ts does. */
+export declare function createNodeWebSocketTransport(options?: Readonly<NodeWebSocketTransportOptions>): Transport;
+//#endregion

package/dist/adapters/node-websocket-transport.mjs

@@ -0,0 +1,180 @@
+import { createServer } from "node:http";
+import { createServer as createServer$1 } from "node:https";
+import { cdeDecodeOptions, cdeEncodeOptions, decode, encode } from "cbor2";
+import { frameSchema } from "wire-mesh-core/generated/protocol";
+import { WebSocket, WebSocketServer } from "ws";
+//#region src/adapters/node-websocket-transport.ts
+const CLOSE_NORMAL = 1e3;
+const CLOSE_PROTOCOL_ERROR = 1002;
+const HTTP_NOT_FOUND = 404;
+function hostPortToWsUrl(address) {
+	const { host, port } = parseAddress(address);
+	return `ws://${host}:${String(port)}`;
+}
+function parseAddress(address) {
+	const lastColon = address.lastIndexOf(":");
+	if (lastColon === -1) throw new Error(`expected "host:port", got "${address}"`);
+	return {
+		host: address.slice(0, lastColon),
+		port: Number(address.slice(lastColon + 1))
+	};
+}
+function messageFromFrame(frame) {
+	return new Uint8Array(encode(frame, cdeEncodeOptions));
+}
+/** A frame that fails schema validation, caught separately from a decode failure so it can be dropped without disconnecting the peer. */
+var SchemaInvalidFrameError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "SchemaInvalidFrameError";
+	}
+};
+/** Decodes one message, distinguishing a decode failure (connection-level) from a schema failure (drop this frame, keep the connection) -- mirroring the other adapters' split between the two. */
+function decodeMessage(data) {
+	let decoded;
+	try {
+		decoded = decode(data, cdeDecodeOptions);
+	} catch (error) {
+		throw error instanceof Error ? error : /* @__PURE__ */ new Error(`frame body failed to decode: ${String(error)}`);
+	}
+	const result = frameSchema.safeParse(decoded);
+	if (!result.success) throw new SchemaInvalidFrameError(result.error.message);
+	return result.data;
+}
+/** Narrows `ws`'s RawData (Buffer | ArrayBuffer | Buffer[]) to a single contiguous, genuinely plain Uint8Array. `ws` only ever delivers an array of buffers when a message arrives fragmented across a stream that itself isn't being reassembled -- doesn't happen for the default (non-streamed) receive path this adapter uses. A Node Buffer IS a Uint8Array subclass, but handing one to cbor2's decode() as-is leaks that subclass into every nested byte-string value decode() returns (it slices the same buffer type it was given); cbor2's encode() then does not recognise a Buffer as a plain byte string and serialises it as a generic object instead, corrupting any value (like a device-id) that round-trips decode -\> store -\> re-encode, as this hub's relay-connect -\> relay-inbound path does. Always copying into a fresh Uint8Array here, the same normalisation the browser/Worker adapters get for free from `new Uint8Array(event.data)` on their own already-ArrayBuffer input, is the fix. */
+function bytesFromRawData(data) {
+	if (Array.isArray(data)) throw new Error("expected a single WebSocket message, got fragments");
+	return new Uint8Array(data);
+}
+/** Wraps an already-open `ws` WebSocket (client or server side) as a Connection, driven through `ws`'s EventEmitter API (`.on`, not `.addEventListener` -- this repo's other Node-native adapter, tcp-transport.ts, uses the same idiomatic-Node style; `.addEventListener` is reserved for the two adapters wrapping an actual platform WebSocket). */
+function wrapNodeWebSocket(ws) {
+	const pending = [];
+	const waiters = [];
+	let ended = false;
+	let failure = null;
+	function endAll() {
+		ended = true;
+		for (const waiter of waiters.splice(0)) waiter.resolve({
+			value: void 0,
+			done: true
+		});
+	}
+	function failAll(error) {
+		failure = error;
+		ended = true;
+		for (const waiter of waiters.splice(0)) waiter.reject(error);
+	}
+	ws.on("message", (data, isBinary) => {
+		if (!isBinary) {
+			failAll(/* @__PURE__ */ new Error("expected a binary WebSocket message"));
+			ws.close(CLOSE_PROTOCOL_ERROR, "protocol error");
+			return;
+		}
+		let frame;
+		try {
+			frame = decodeMessage(bytesFromRawData(data));
+		} catch (error) {
+			if (error instanceof SchemaInvalidFrameError) return;
+			failAll(error instanceof Error ? error : /* @__PURE__ */ new Error(`frame body failed to decode: ${String(error)}`));
+			ws.close(CLOSE_PROTOCOL_ERROR, "protocol error");
+			return;
+		}
+		const waiter = waiters.shift();
+		if (waiter) waiter.resolve({
+			value: frame,
+			done: false
+		});
+		else pending.push(frame);
+	});
+	ws.on("close", endAll);
+	ws.on("error", endAll);
+	const receiveStream = { [Symbol.asyncIterator]() {
+		return { async next() {
+			const next = pending.shift();
+			if (next !== void 0) return {
+				value: next,
+				done: false
+			};
+			if (failure !== null) throw failure;
+			if (ended) return {
+				value: void 0,
+				done: true
+			};
+			return new Promise((resolve, reject) => {
+				waiters.push({
+					resolve,
+					reject
+				});
+			});
+		} };
+	} };
+	return {
+		async send(frame) {
+			if (ended) return Promise.reject(/* @__PURE__ */ new Error("connection is closed"));
+			ws.send(messageFromFrame(frame));
+			return Promise.resolve();
+		},
+		receive: () => receiveStream,
+		async close() {
+			ws.close(CLOSE_NORMAL);
+			return Promise.resolve();
+		}
+	};
+}
+/** A Node `ws`-based Transport: one CBOR frame per binary WebSocket message, served over a plain `http.Server` this adapter owns, or an `https.Server` when `options.tls` is given. `listen()` is a real implementation (unlike the browser adapter, a client can never accept connections) and supports port 0 for an OS-assigned port, reading the real bound address back the same way core's tcp-transport.ts does. */
+function createNodeWebSocketTransport(options = {}) {
+	return {
+		async connect(address) {
+			const url = /^wss?:\/\/./.test(address);
+			if (!url && !/^[^/]+:\d+$/.test(address)) throw new Error(`expected "host:port" or a ws:// / wss:// URL, got "${address}"`);
+			const target = url ? address : hostPortToWsUrl(address);
+			return new Promise((resolve, reject) => {
+				const ws = new WebSocket(target);
+				ws.once("open", () => {
+					resolve(wrapNodeWebSocket(ws));
+				});
+				ws.once("error", reject);
+			});
+		},
+		async listen(address, onConnection) {
+			const { host, port } = parseAddress(address);
+			return new Promise((resolve, reject) => {
+				const requestHandler = (request, response) => {
+					if (options.onHttpRequest) {
+						options.onHttpRequest(request, response);
+						return;
+					}
+					response.writeHead(HTTP_NOT_FOUND).end();
+				};
+				const httpServer = options.tls ? createServer$1({
+					cert: options.tls.certificatePem,
+					key: options.tls.privateKeyPem
+				}, requestHandler) : createServer(requestHandler);
+				const wss = new WebSocketServer({ server: httpServer });
+				wss.on("connection", (ws) => {
+					onConnection(wrapNodeWebSocket(ws));
+				});
+				httpServer.once("error", reject);
+				httpServer.listen(port, host, () => {
+					const bound = httpServer.address();
+					if (bound === null || typeof bound === "string") {
+						reject(/* @__PURE__ */ new Error("listener did not report a bound address"));
+						return;
+					}
+					resolve({
+						close: async () => new Promise((resolveClose) => {
+							wss.close(() => {
+								httpServer.close(() => {
+									resolveClose();
+								});
+							});
+						}),
+						address: `${bound.address}:${String(bound.port)}`
+					});
+				});
+			});
+		}
+	};
+}
+//#endregion
+export { createNodeWebSocketTransport, messageFromFrame, wrapNodeWebSocket };

package/dist/server.cjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_adapters_node_websocket_transport = require("./adapters/node-websocket-transport.cjs");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+let node_url = require("node:url");
+let wire_mesh_core_domain_relay_hub = require("wire-mesh-core/domain/relay-hub");
+//#region src/static-console.ts
+const CONTENT_TYPES = {
+	".css": "text/css; charset=utf-8",
+	".html": "text/html; charset=utf-8",
+	".ico": "image/x-icon",
+	".js": "application/javascript; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".mjs": "application/javascript; charset=utf-8",
+	".png": "image/png",
+	".svg": "image/svg+xml",
+	".webmanifest": "application/manifest+json; charset=utf-8",
+	".woff2": "font/woff2"
+};
+const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+const INDEX_FILE = "index.html";
+const SERVICE_WORKER_ALLOWED_HEADERS = { "Service-Worker-Allowed": "/" };
+/** Resolves `pathname` (a request URL's raw, still percent-encoded path) to a file under `consoleDir`. Returns undefined for a path that decodes to something outside `consoleDir` (a traversal attempt), a malformed percent-encoding, or a real 404 — an extension-bearing path with no matching file. */
+function resolveConsoleFile(consoleDir, pathname) {
+	let decoded;
+	try {
+		decoded = decodeURIComponent(pathname);
+	} catch {
+		return;
+	}
+	const root = (0, node_path.normalize)(consoleDir);
+	const relative = decoded === "/" ? INDEX_FILE : decoded.replace(/^\/+/, "");
+	let filePath = (0, node_path.normalize)((0, node_path.join)(root, relative));
+	if (!filePath.startsWith(root + node_path.sep) && filePath !== root) return;
+	if (!(0, node_fs.existsSync)(filePath) || !(0, node_fs.statSync)(filePath).isFile()) {
+		if ((0, node_path.extname)(decoded) !== "") return;
+		filePath = (0, node_path.join)(root, INDEX_FILE);
+		if (!(0, node_fs.existsSync)(filePath) || !(0, node_fs.statSync)(filePath).isFile()) return;
+	}
+	const contentType = CONTENT_TYPES[(0, node_path.extname)(filePath)] ?? DEFAULT_CONTENT_TYPE;
+	return {
+		body: (0, node_fs.readFileSync)(filePath),
+		contentType,
+		...filePath.endsWith("sw.js") ? { headers: SERVICE_WORKER_ALLOWED_HEADERS } : {}
+	};
+}
+//#endregion
+//#region src/server.ts
+function healthResponse() {
+	return {
+		ok: true,
+		node: "wire-mesh",
+		roles: ["relay"]
+	};
+}
+const DEFAULT_BIND_ADDRESS = "0.0.0.0:8787";
+const HTTP_OK = 200;
+const HTTP_NOT_FOUND = 404;
+const HEALTH_PATH = "/health";
+const __dirname$1 = (0, node_path.dirname)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href));
+const CONSOLE_DIR = (0, node_path.join)(__dirname$1, "web-console");
+function bindAddressFromArgs(argv) {
+	const flagIndex = argv.indexOf("--bind");
+	return (flagIndex === -1 ? void 0 : argv[flagIndex + 1]) ?? DEFAULT_BIND_ADDRESS;
+}
+/** Reads --tls-cert/--tls-key from argv, required together — a self-hosted node answering wss:// (wire-mesh#184, so an https://-served PWA can reach it without mixed-content blocking) needs an operator-supplied certificate; this package generates none of its own, matching the README's security note. Returns undefined when neither flag is given, the existing plain-ws:// default. */
+function tlsFromArgs(argv) {
+	const certIndex = argv.indexOf("--tls-cert");
+	const keyIndex = argv.indexOf("--tls-key");
+	const certPath = certIndex === -1 ? void 0 : argv[certIndex + 1];
+	const keyPath = keyIndex === -1 ? void 0 : argv[keyIndex + 1];
+	if (certPath === void 0 && keyPath === void 0) return;
+	if (certPath === void 0 || keyPath === void 0) throw new Error("--tls-cert and --tls-key must be given together");
+	return {
+		certPath,
+		keyPath
+	};
+}
+/** Builds the listener's onHttpRequest handler: /health answers the same JSON shape healthResponse() returns, everything else resolves against consoleDir via resolveConsoleFile. Takes consoleDir as a parameter, not a module-level constant, so a test can point it at a temp fixture instead of the real build-time CONSOLE_DIR. */
+function createHttpRequestHandler(consoleDir) {
+	return (request, response) => {
+		const url = new URL(request.url ?? "/", "http://localhost");
+		if (url.pathname === HEALTH_PATH) {
+			response.writeHead(HTTP_OK, { "content-type": "application/json" });
+			response.end(JSON.stringify(healthResponse()));
+			return;
+		}
+		const file = resolveConsoleFile(consoleDir, url.pathname);
+		if (file) {
+			response.writeHead(HTTP_OK, {
+				"content-type": file.contentType,
+				...file.headers
+			});
+			response.end(file.body);
+			return;
+		}
+		response.writeHead(HTTP_NOT_FOUND).end();
+	};
+}
+function logStartup(message) {
+	console.log(message);
+}
+async function main() {
+	const argv = process.argv.slice(2);
+	const tlsFiles = tlsFromArgs(argv);
+	const tls = tlsFiles ? {
+		certificatePem: (0, node_fs.readFileSync)(tlsFiles.certPath, "utf-8"),
+		privateKeyPem: (0, node_fs.readFileSync)(tlsFiles.keyPath, "utf-8")
+	} : void 0;
+	const hub = (0, wire_mesh_core_domain_relay_hub.createRelayHub)();
+	const listener = await require_adapters_node_websocket_transport.createNodeWebSocketTransport({
+		onHttpRequest: createHttpRequestHandler(CONSOLE_DIR),
+		...tls ? { tls } : {}
+	}).listen(bindAddressFromArgs(argv), (connection) => {
+		hub.handleConnection(connection);
+	});
+	logStartup(`wire-mesh listening on ${tls ? "wss" : "ws"}://${listener.address}`);
+}
+const invokedPath = process.argv[1];
+if (invokedPath !== void 0 && require("url").pathToFileURL(__filename).href === `file://${invokedPath}`) main();
+//#endregion
+exports.bindAddressFromArgs = bindAddressFromArgs;
+exports.createHttpRequestHandler = createHttpRequestHandler;
+exports.healthResponse = healthResponse;
+exports.tlsFromArgs = tlsFromArgs;

package/dist/server.d.cts

@@ -0,0 +1,17 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+//#region src/server.d.ts
+export declare function healthResponse(): {
+  ok: true;
+  node: string;
+  roles: string[];
+};
+export declare function bindAddressFromArgs(argv: readonly string[]): string;
+export interface TlsFilePaths {
+  certPath: string;
+  keyPath: string;
+}
+/** Reads --tls-cert/--tls-key from argv, required together — a self-hosted node answering wss:// (wire-mesh#184, so an https://-served PWA can reach it without mixed-content blocking) needs an operator-supplied certificate; this package generates none of its own, matching the README's security note. Returns undefined when neither flag is given, the existing plain-ws:// default. */
+export declare function tlsFromArgs(argv: readonly string[]): TlsFilePaths | undefined;
+/** Builds the listener's onHttpRequest handler: /health answers the same JSON shape healthResponse() returns, everything else resolves against consoleDir via resolveConsoleFile. Takes consoleDir as a parameter, not a module-level constant, so a test can point it at a temp fixture instead of the real build-time CONSOLE_DIR. */
+export declare function createHttpRequestHandler(consoleDir: string): (request: IncomingMessage, response: ServerResponse) => void;
+//#endregion

package/dist/server.d.mts

@@ -0,0 +1,17 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+//#region src/server.d.ts
+export declare function healthResponse(): {
+  ok: true;
+  node: string;
+  roles: string[];
+};
+export declare function bindAddressFromArgs(argv: readonly string[]): string;
+export interface TlsFilePaths {
+  certPath: string;
+  keyPath: string;
+}
+/** Reads --tls-cert/--tls-key from argv, required together — a self-hosted node answering wss:// (wire-mesh#184, so an https://-served PWA can reach it without mixed-content blocking) needs an operator-supplied certificate; this package generates none of its own, matching the README's security note. Returns undefined when neither flag is given, the existing plain-ws:// default. */
+export declare function tlsFromArgs(argv: readonly string[]): TlsFilePaths | undefined;
+/** Builds the listener's onHttpRequest handler: /health answers the same JSON shape healthResponse() returns, everything else resolves against consoleDir via resolveConsoleFile. Takes consoleDir as a parameter, not a module-level constant, so a test can point it at a temp fixture instead of the real build-time CONSOLE_DIR. */
+export declare function createHttpRequestHandler(consoleDir: string): (request: IncomingMessage, response: ServerResponse) => void;
+//#endregion