@stim-cli/transport-local 0.0.0-stage → 1.29.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Janic Duplessis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @stim-cli/transport-local
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The local network transport for stim-server. It listens on the private IPv4 addresses the machine setting
+`server.lanAddresses` names, each an address or a network interface name such as `en0`, so machines and phones on the
+same network reach stim-server without Tailscale. It implements the [`@stim-cli/transport`](../transport/README.md)
+contract.
+
+- **Off by default.** With `server.lanAddresses` empty, stim-server listens on no local network address. Wildcard
+  (`0.0.0.0`), loopback, public and IPv6 addresses are refused.
+- **Plain WebSocket, no TLS.** Every connection runs stim-server's protocol 2 Noise handshake before any request, which
+  authenticates both sides by their keys and encrypts the connection. A network address never identifies a client.
+- **Live.** The setting and the interfaces are read again every 5 seconds, so a changed setting or a new DHCP lease
+  applies without a restart.
+
+stim-server depends on it and loads it at start.

package/dist/index.d.mts

@@ -0,0 +1,37 @@
+import { NetworkInterfaceInfo } from "node:os";
+import { TRANSPORT_API_VERSION, Transport, TransportInput } from "@stim-cli/transport";
+//#region index.d.ts
+declare const apiVersion: typeof TRANSPORT_API_VERSION;
+declare const id = "local";
+type Interfaces = NodeJS.Dict<NetworkInterfaceInfo[]>;
+/** What `server.lanAddresses` names now: the addresses to listen on, and why each other entry is left out. */
+interface LanAddresses {
+  addresses: string[];
+  problems: string[];
+}
+/**
+ * The private IPv4 addresses that `entries` name on this machine's interfaces now. An entry is an IPv4 address or an
+ * interface name such as `en0`; an interface contributes each private IPv4 address it has. Wildcard, loopback, public
+ * and IPv6 addresses are refused, and an address no interface holds now is left out until one does.
+ */
+declare function resolveLanAddresses(entries: readonly string[], interfaces: Interfaces): LanAddresses;
+/** The local network transport, plus the reasons stim-server cannot listen on some of the entries it was given. */
+interface LocalTransport extends Transport {
+  id: typeof id;
+  lan(): LanAddresses;
+  bindAddresses(): string[];
+  watch(listener: () => void): () => void;
+}
+/**
+ * Listens on the local network addresses `entries` names, read again on every poll so a changed setting or a new
+ * DHCP lease applies without a restart. It carries plain WebSocket: stim-server's Noise handshake authenticates every
+ * client by its key and encrypts the connection, so the transport needs no TLS and never identifies anyone.
+ */
+declare function localTransport({ entries, interfaces, pollMs }: {
+  entries: () => readonly string[];
+  interfaces?: () => Interfaces;
+  pollMs?: number;
+}): LocalTransport;
+declare function createTransport({ options }: TransportInput): LocalTransport;
+//#endregion
+export { LanAddresses, LocalTransport, apiVersion, createTransport, id, localTransport, resolveLanAddresses };

package/dist/index.mjs

@@ -0,0 +1,96 @@
+import { isIPv4 } from "node:net";
+import { networkInterfaces } from "node:os";
+import { TRANSPORT_API_VERSION } from "@stim-cli/transport";
+//#region index.ts
+const apiVersion = TRANSPORT_API_VERSION;
+const id = "local";
+const POLL_MS = 5e3;
+/** RFC 1918 and link-local IPv4 addresses: a local network, never the public internet or a loopback. */
+function isPrivateIPv4(address) {
+	const [a = 0, b = 0] = address.split(".").map(Number);
+	return a === 10 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a === 169 && b === 254;
+}
+/**
+* The private IPv4 addresses that `entries` name on this machine's interfaces now. An entry is an IPv4 address or an
+* interface name such as `en0`; an interface contributes each private IPv4 address it has. Wildcard, loopback, public
+* and IPv6 addresses are refused, and an address no interface holds now is left out until one does.
+*/
+function resolveLanAddresses(entries, interfaces) {
+	const held = new Set(Object.values(interfaces).flatMap((each) => (each ?? []).filter((info) => info.family === "IPv4")));
+	const addresses = /* @__PURE__ */ new Set();
+	const problems = [];
+	for (const raw of entries) {
+		const entry = raw.trim();
+		if (isIPv4(entry)) {
+			if (!isPrivateIPv4(entry)) problems.push(`${entry} is not a private local network address (10/8, 172.16/12, 192.168/16 or 169.254/16)`);
+			else if (![...held].some((info) => info.address === entry)) problems.push(`no network interface has ${entry} now`);
+			else addresses.add(entry);
+			continue;
+		}
+		const named = interfaces[entry];
+		if (!/^[A-Za-z][A-Za-z0-9._-]*$/.test(entry)) problems.push(`${entry} is neither an IPv4 address nor a network interface name`);
+		else if (!named) problems.push(`no network interface is named ${entry} now`);
+		else {
+			const found = named.filter((info) => info.family === "IPv4" && !info.internal && isPrivateIPv4(info.address));
+			if (!found.length) problems.push(`${entry} has no private IPv4 address now`);
+			for (const info of found) addresses.add(info.address);
+		}
+	}
+	return {
+		addresses: [...addresses],
+		problems
+	};
+}
+/**
+* Listens on the local network addresses `entries` names, read again on every poll so a changed setting or a new
+* DHCP lease applies without a restart. It carries plain WebSocket: stim-server's Noise handshake authenticates every
+* client by its key and encrypts the connection, so the transport needs no TLS and never identifies anyone.
+*/
+function localTransport({ entries, interfaces = networkInterfaces, pollMs = POLL_MS }) {
+	const read = () => {
+		try {
+			return resolveLanAddresses(entries(), interfaces());
+		} catch (error) {
+			return {
+				addresses: [],
+				problems: [`could not read the local network addresses: ${error instanceof Error ? error.message : String(error)}`]
+			};
+		}
+	};
+	const timers = /* @__PURE__ */ new Set();
+	return {
+		id,
+		traits: {
+			privateNetwork: false,
+			tls: "none",
+			peerIdentity: false
+		},
+		lan: read,
+		bindAddresses: () => read().addresses,
+		watch(listener) {
+			let last = JSON.stringify(read());
+			const timer = setInterval(() => {
+				const next = JSON.stringify(read());
+				if (next === last) return;
+				last = next;
+				listener();
+			}, pollMs);
+			timer.unref();
+			timers.add(timer);
+			return () => {
+				clearInterval(timer);
+				timers.delete(timer);
+			};
+		},
+		close() {
+			for (const timer of timers) clearInterval(timer);
+			timers.clear();
+		}
+	};
+}
+function createTransport({ options }) {
+	const addresses = (Array.isArray(options.addresses) ? options.addresses : []).filter((entry) => typeof entry === "string");
+	return localTransport({ entries: () => addresses });
+}
+//#endregion
+export { apiVersion, createTransport, id, localTransport, resolveLanAddresses };

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@stim-cli/transport-local",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.29.0",
+  "description": "Local network transport for stim-server: plain WebSocket on chosen private addresses, protected by Stim's Noise session.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appandflow/stim.git",
+    "directory": "packages/transport-local"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "module-sync": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "@stim-cli/transport": "1.29.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
 }