@stim-cli/transport 0.0.0-stage → 1.21.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,29 @@
-# Temporary Holding Version
+# @stim-cli/transport
 
-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 contract between stim-server and the transports that carry phones and other machines to it. A transport
+package exports `apiVersion`, `id` and `createTransport()`, and stim-server loads it with `loadTransport()`:
+
+```ts
+import { loadTransport } from '@stim-cli/transport';
+
+const loaded = await loadTransport({
+  reference: '@stim-cli/transport-tailscale',
+  load: () => import('@stim-cli/transport-tailscale'),
+  input: { env: process.env, options: {} },
+});
+if ('unavailable' in loaded) console.error(loaded.unavailable);
+```
+
+`loadTransport()` never throws. A missing package, a different `apiVersion`, a failing `createTransport()` or a
+load that takes longer than 10 seconds comes back as `unavailable` with the reason.
+
+A transport declares its `traits` and implements the capabilities it has:
+
+- `bindAddresses()`: the addresses stim-server listens on, besides loopback, for the clients it carries.
+- `watch(listener)`: called when those addresses or the transport's state may have changed.
+- `identify({ address, request })`: the machine a connection comes from. stim-server binds a device token to it at
+  pairing and refuses the token from any other machine.
+- `close()`: stops any background work.
+
+The design and the capabilities still to come are in
+[docs/specs/2026-10-13-pluggable-transports-design.md](../../docs/specs/2026-10-13-pluggable-transports-design.md).

package/dist/index.d.mts

@@ -0,0 +1,59 @@
+import { IncomingMessage } from "node:http";
+//#region index.d.ts
+declare const TRANSPORT_API_VERSION: 1;
+interface TransportTraits {
+  /** Traffic stays on a private overlay whose source addresses identify the sending machine. */
+  privateNetwork: boolean;
+  /** Where TLS ends: on this machine, at a provider's edge, or nowhere. */
+  tls: "end-to-end" | "edge" | "none";
+  /** `identify` names the machine a connection comes from, so a device token can be bound to it. */
+  peerIdentity: boolean;
+}
+/** The machine a connection comes from, as the transport identifies it. `id` stays the same across renames. */
+interface TransportIdentity {
+  id: string;
+  name: string;
+  user: string;
+}
+interface TransportPeer {
+  /** The connection's source address as stim-server sees it, after any proxy the transport runs. */
+  address: string;
+  request: IncomingMessage;
+}
+interface Transport {
+  id: string;
+  traits: TransportTraits;
+  /** The addresses stim-server listens on, besides loopback, for clients this transport carries. */
+  bindAddresses?(): string[];
+  /** Calls `listener` whenever `bindAddresses` or the transport's state may have changed. */
+  watch?(listener: () => void): () => void;
+  identify?(peer: TransportPeer): Promise<TransportIdentity | null>;
+  close?(): void;
+}
+interface TransportInput {
+  env: NodeJS.ProcessEnv;
+  options: Record<string, unknown>;
+}
+interface TransportModule {
+  apiVersion: typeof TRANSPORT_API_VERSION;
+  id: string;
+  createTransport(input: TransportInput): Transport | Promise<Transport>;
+}
+type LoadTransportResult = {
+  transport: Transport;
+} | {
+  unavailable: string;
+};
+/**
+ * Imports the transport module `reference` with `load` and creates its transport. Never throws: a missing module, a
+ * wrong `apiVersion`, a failing factory, or a load that takes longer than `timeoutMs` comes back as `unavailable`
+ * with the reason.
+ */
+declare function loadTransport({ reference, load, input, timeoutMs }: {
+  reference: string;
+  load: () => Promise<unknown>;
+  input: TransportInput;
+  timeoutMs?: number;
+}): Promise<LoadTransportResult>;
+//#endregion
+export { LoadTransportResult, TRANSPORT_API_VERSION, Transport, TransportIdentity, TransportInput, TransportModule, TransportPeer, TransportTraits, loadTransport };

package/dist/index.mjs

@@ -0,0 +1,69 @@
+//#region index.ts
+const TRANSPORT_API_VERSION = 1;
+const LOAD_TIMEOUT_MS = 1e4;
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function reason(error) {
+	return (error instanceof Error ? error.message : String(error)).split("\n")[0] ?? "";
+}
+function hasFactory(value) {
+	return typeof value.createTransport === "function";
+}
+const CAPABILITIES = [
+	"bindAddresses",
+	"watch",
+	"identify",
+	"close"
+];
+function isTransport(value) {
+	return isRecord(value) && typeof value.id === "string" && isRecord(value.traits) && CAPABILITIES.every((name) => value[name] === void 0 || typeof value[name] === "function");
+}
+function moduleCandidate(namespace) {
+	if (!isRecord(namespace)) return namespace;
+	return "apiVersion" in namespace ? namespace : namespace.default;
+}
+async function importTransport(reference, load, input) {
+	let namespace;
+	try {
+		namespace = await load();
+	} catch (error) {
+		return { unavailable: `${reference} is not installed: ${reason(error)}` };
+	}
+	const candidate = moduleCandidate(namespace);
+	if (!isRecord(candidate) || candidate.apiVersion !== 1) {
+		const found = isRecord(candidate) ? candidate.apiVersion : candidate;
+		return { unavailable: `${reference}: expected apiVersion 1, found ${JSON.stringify(found)}` };
+	}
+	if (!hasFactory(candidate)) return { unavailable: `${reference} does not export createTransport()` };
+	let transport;
+	try {
+		transport = await candidate.createTransport(input);
+	} catch (error) {
+		return { unavailable: `${reference}: createTransport() failed: ${reason(error)}` };
+	}
+	if (!isTransport(transport)) return { unavailable: `${reference}: createTransport() did not return a transport` };
+	return { transport };
+}
+/**
+* Imports the transport module `reference` with `load` and creates its transport. Never throws: a missing module, a
+* wrong `apiVersion`, a failing factory, or a load that takes longer than `timeoutMs` comes back as `unavailable`
+* with the reason.
+*/
+async function loadTransport({ reference, load, input, timeoutMs = LOAD_TIMEOUT_MS }) {
+	let timer;
+	const expired = new Promise((resolve) => {
+		timer = setTimeout(() => resolve("timeout"), timeoutMs);
+	});
+	const loading = importTransport(reference, load, input).catch((error) => ({ unavailable: reason(error) }));
+	try {
+		const result = await Promise.race([loading, expired]);
+		if (result !== "timeout") return result;
+		loading.then((late) => "transport" in late ? late.transport.close?.() : void 0);
+		return { unavailable: `${reference} did not load within ${timeoutMs}ms` };
+	} finally {
+		clearTimeout(timer);
+	}
+}
+//#endregion
+export { TRANSPORT_API_VERSION, loadTransport };

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@stim-cli/transport",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.21.0",
+  "description": "Transport contract for stim-server: how phones and other machines reach it.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appandflow/stim.git",
+    "directory": "packages/transport"
+  },
+  "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"
+    }
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
 }