dsh-foreman-node 0.1.1 → 0.2.0

package/lib/index.js

@@ -1,5 +1,10 @@
 import { FrameDedupe, encodeFrame, parseFrame } from "./protocol.js";
 import s from "@deepseek-ai/schemastery";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { connect } from "node:net";
 import { MessageId, freezeMessage } from "@deepseek-ai/dsh-llm";
 // src/client.ts
 /**
@@ -187,6 +192,531 @@ var NodeClient = class {
 		this.log(`dsh-foreman-node reconnecting in ${wait} ms`);
 	}
 };
+// src/config.ts
+/** The SSH defaults, spread over whatever the host hands in, so a partial block is still complete. */
+const SSH_DEFAULTS = {
+	enabled: false,
+	host: "",
+	port: 22,
+	user: "",
+	keyPath: "",
+	remotePort: 8790,
+	localPort: 8790
+};
+/** A volatile field arrives wrapped; this reads it either way, so callers do not have to know which. */
+const valueOf = (field, fallback) => {
+	if (field === void 0) return fallback;
+	if (typeof field === "object" && field !== null && "get" in field && typeof field.get === "function") return field.get();
+	return field;
+};
+/**
+* Unwrap a whole configuration: every field may be a volatile wrapper, a plain value, or absent.
+*
+* `Config` already applies defaults, so `apply` sees a complete object. This is for the paths that do not go through
+* the schema: the configuration page's read, and a `cordis.patch.yml` written before a field existed.
+*/
+/**
+* Unwrap the `ssh` block.
+*
+* Its fields are volatile for the same reason the top level is, so each may arrive wrapped. Reading them all through
+* `valueOf` keeps one unwrapping rule instead of two, and it means a plain partial block (an older patch file) works
+* just as well as a wrapped one.
+*/
+function unwrapSsh(block) {
+	if (block === null || typeof block !== "object") return {};
+	const source = block;
+	return {
+		enabled: valueOf(source["enabled"], SSH_DEFAULTS.enabled),
+		host: valueOf(source["host"], SSH_DEFAULTS.host),
+		port: valueOf(source["port"], SSH_DEFAULTS.port),
+		user: valueOf(source["user"], SSH_DEFAULTS.user),
+		keyPath: valueOf(source["keyPath"], SSH_DEFAULTS.keyPath),
+		remotePort: valueOf(source["remotePort"], SSH_DEFAULTS.remotePort),
+		localPort: valueOf(source["localPort"], SSH_DEFAULTS.localPort)
+	};
+}
+function configured(config) {
+	const source = config ?? {};
+	return {
+		url: valueOf(source["url"], ""),
+		deviceId: valueOf(source["deviceId"], ""),
+		token: valueOf(source["token"], ""),
+		roots: valueOf(source["roots"], []),
+		heartbeatMs: valueOf(source["heartbeatMs"], 15e3),
+		reconnectMs: valueOf(source["reconnectMs"], 1e3),
+		ssh: {
+			...SSH_DEFAULTS,
+			...unwrapSsh(source["ssh"])
+		}
+	};
+}
+// src/keys.ts
+/**
+* The SSH keys this machine already has, named so a person can pick one.
+*
+* A browser cannot list `~/.ssh`: the page runs in the DSH web UI, which has no filesystem. The device process does,
+* so the listing happens here and the page renders it. Nothing on this path reads a private key: the answer is a
+* filename, a path, and the comment from the public half, which is enough to tell one key from another and is all a
+* page needs.
+*/
+/** The `.pub` file that sits beside a private key. */
+const publicOf = (path) => `${path}.pub`;
+/**
+* Lists the usable private keys in a directory.
+*
+* A key counts as usable only when its public half is beside it: that is how `ssh-keygen` writes them, and a private
+* key without one is either half-deleted or was never finished, so offering it would only fail later at the tunnel.
+* Anything unreadable is skipped rather than thrown, because a permissions problem on one file must not empty the list.
+*/
+function listKeys(directory) {
+	let names;
+	try {
+		names = readdirSync(directory);
+	} catch {
+		return [];
+	}
+	const keys = [];
+	for (const name of names.sort()) {
+		if (!name.startsWith("id_") || name.endsWith(".pub")) continue;
+		const path = join(directory, name);
+		if (!existsSync(publicOf(path))) continue;
+		let comment = "";
+		try {
+			comment = readFileSync(publicOf(path), "utf8").trim().split(/\s+/).slice(2).join(" ");
+		} catch {
+			comment = "";
+		}
+		keys.push({
+			name: basename(name),
+			path,
+			comment
+		});
+	}
+	return keys;
+}
+// src/routes.ts
+/** How long one authentication test may take before it is reported as a timeout. */
+const TEST_TIMEOUT_MS = 15e3;
+/**
+* The argv of an authentication test.
+*
+* It asks for a command that does nothing (`true`) rather than opening a forward, because the question is only
+* "does this key authenticate", and `BatchMode=yes` keeps it from stopping to ask for a passphrase nobody can type.
+*/
+function testArgs({ host, port, user, keyPath }) {
+	return [
+		"ssh",
+		"-o",
+		"BatchMode=yes",
+		"-o",
+		"ConnectTimeout=8",
+		"-o",
+		"StrictHostKeyChecking=accept-new",
+		"-p",
+		String(port),
+		"-i",
+		keyPath,
+		`${user}@${host}`,
+		"true"
+	];
+}
+/** The default runner: a real ssh, resolving to its exit status either way. */
+const realRun = (argv) => new Promise((resolve) => {
+	const child = spawn(argv[0], argv.slice(1), {
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		windowsHide: true
+	});
+	let output = "";
+	const collect = (chunk) => {
+		output = (output + chunk.toString("utf8")).slice(-2048);
+	};
+	child.stdout.on("data", collect);
+	child.stderr.on("data", collect);
+	const timer = setTimeout(() => {
+		output = `${output}\n(timed out after ${TEST_TIMEOUT_MS / 1e3}s)`.trim();
+		child.kill("SIGKILL");
+	}, TEST_TIMEOUT_MS);
+	child.on("error", (error) => {
+		clearTimeout(timer);
+		resolve({
+			code: -1,
+			output: `could not start ssh: ${error.message}`
+		});
+	});
+	child.on("exit", (code) => {
+		clearTimeout(timer);
+		resolve({
+			code,
+			output: output.trim()
+		});
+	});
+});
+/** Writes one JSON answer. */
+function json(res, status, value) {
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"cache-control": "no-store",
+		"x-content-type-options": "nosniff"
+	});
+	res.end(JSON.stringify(value));
+}
+/** Reads a JSON body, refusing anything larger than a form would send. */
+async function body(req, maxBytes = 16384) {
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of req) {
+		const bytes = Buffer.from(chunk);
+		size += bytes.length;
+		if (size > maxBytes) throw new Error(`request exceeds ${maxBytes} bytes`);
+		chunks.push(bytes);
+	}
+	try {
+		return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+	} catch {
+		throw new Error("the request body is not JSON");
+	}
+}
+/**
+* The same-origin guard the hub uses, for the same reason.
+*
+* The marker header alone proves nothing: any local process can send it. What the browser will not let another origin
+* do is send it *with* its own `Origin` intact, so an `Origin` that is present must be this page's. A request with no
+* `Origin` at all (a local tool, a test) is allowed and the marker still has to be there.
+*/
+/** The loopback names a host header may carry; DSH's desktop build normalizes`::1` and `localhost` to each other. */
+const LOOPBACK = [
+	"127.0.0.1",
+	"localhost",
+	"::1",
+	"[::1]"
+];
+function sameOrigin(req, port, protocol = "http:") {
+	const host = req.headers.host;
+	if (host === void 0) return false;
+	const match = /^(\[[^\]]+\]|[^:]+):(\d+)$/.exec(host);
+	if (match === null) return false;
+	const [, name, seen] = match;
+	if (!LOOPBACK.includes(name) || Number(seen) !== port) return false;
+	return req.headers["x-orchestrator-request"] === "1" && (req.headers.origin === void 0 || req.headers.origin === `${protocol}//${host}`);
+}
+/** The prefix both routes live under; it never collides with the hub's `/orchestrator`. */
+const NODE_PREFIX = "/foreman-node";
+/**
+* Registers the routes and returns their disposer.
+*
+* `listKeys` and `run` are injectable so tests can answer without a filesystem or a child process; production passes
+* a directory and the real runner.
+*/
+function registerNodeRoutes(host, directory, run = realRun) {
+	return host.register({
+		kind: "prefix",
+		path: NODE_PREFIX,
+		handler: async (req, res) => {
+			if (!sameOrigin(req, host.port, host.protocol)) {
+				json(res, 403, { error: "Same-origin request required" });
+				return;
+			}
+			const url = new URL(req.url ?? "/", "http://localhost");
+			const method = req.method ?? "GET";
+			try {
+				if (url.pathname === `/foreman-node/api/keys` && method === "GET") {
+					json(res, 200, {
+						keys: listKeys(directory),
+						directory
+					});
+					return;
+				}
+				if (url.pathname === `/foreman-node/api/test` && method === "POST") {
+					const input = await body(req);
+					if (typeof input.host !== "string" || input.host.trim() === "" || typeof input.user !== "string" || input.user.trim() === "" || typeof input.keyPath !== "string" || input.keyPath.trim() === "") {
+						json(res, 400, { error: "host, user and keyPath are required" });
+						return;
+					}
+					const port = typeof input.port === "number" && Number.isInteger(input.port) && input.port > 0 && input.port <= 65535 ? input.port : 22;
+					const keyPath = input.keyPath.trim();
+					if (listKeys(directory).find((key) => key.path === keyPath) === void 0) {
+						json(res, 400, { error: `no key at ${keyPath}; the page lists the ones this machine has` });
+						return;
+					}
+					const result = await run(testArgs({
+						host: input.host.trim(),
+						port,
+						user: input.user.trim(),
+						keyPath
+					}));
+					json(res, 200, {
+						ok: result.code === 0,
+						output: result.output
+					});
+					return;
+				}
+				json(res, 404, { error: "Unknown operation" });
+			} catch (error) {
+				json(res, 400, { error: error instanceof Error ? error.message : String(error) });
+			}
+		}
+	});
+}
+// src/tunnel.ts
+/**
+* The device's own tunnel to a hub it cannot reach directly.
+*
+* The hub listens on loopback only, on purpose: its ledger is the one thing worth protecting, and a publicly bound
+* port would make the device token the only thing between it and the internet. So a device on another machine
+* reaches it by opening a local port that `ssh -L` forwards to the hub's own loopback port.
+*
+* This class owns exactly one child process and nothing else. It does not know what the hub is for, does not build
+* frames, and does not retry the connection inside the tunnel — the NodeClient above it does that. Its whole job is
+* "there is a port on localhost that reaches the hub, and it stays that way", reported as a state a page can show.
+*/
+/** How long to wait for the local port to start answering before calling the attempt a failure. */
+const READY_TIMEOUT_MS = 1e4;
+/** How often to ask whether the port answers yet. */
+const READY_POLL_MS = 200;
+/** How long a stopped process may take to honour SIGTERM before it is killed. */
+const STOP_GRACE_MS = 2e3;
+/** `-N` forks no command, `-T` allocates no terminal: this process exists only to carry the forward. */
+const TUNNEL_FLAGS = ["-N", "-T"];
+/**
+* The options that make a failure a failure.
+*
+* `BatchMode=yes` refuses to prompt, because nothing is there to answer and a prompt would hang forever.
+* `ExitOnForwardFailure=yes` makes a forward that cannot be set up kill the process instead of leaving a live ssh
+* that forwards nothing — the failure that would otherwise only show up as "the hub is offline".
+* The keepalives let a dead link be noticed rather than waiting for a TCP timeout nobody is watching.
+*/
+const TUNNEL_OPTIONS = [
+	"-o",
+	"BatchMode=yes",
+	"-o",
+	"ExitOnForwardFailure=yes",
+	"-o",
+	"ServerAliveInterval=30",
+	"-o",
+	"ServerAliveCountMax=3"
+];
+/** The argv of the forwarding process, in order, exactly as the tests pin it. */
+function tunnelArgs(ssh) {
+	return [
+		"ssh",
+		...TUNNEL_FLAGS,
+		...TUNNEL_OPTIONS,
+		"-p",
+		String(ssh.port),
+		"-i",
+		ssh.keyPath,
+		"-L",
+		`${ssh.localPort}:127.0.0.1:${ssh.remotePort}`,
+		`${ssh.user}@${ssh.host}`
+	];
+}
+/**
+* Turns ssh's own words into something a person can act on.
+*
+* Both of these would otherwise read as a bare "the tunnel stopped", and both have a specific fix. Reprinting the
+* ssh text is not enough: it names the mechanism, not the move.
+*/
+function explain(ssh, stderr) {
+	const said = stderr.trim().split("\n").slice(-3).join(" ").trim();
+	const tail = said === "" ? "" : ` (ssh said: ${said})`;
+	if (/Permission denied \(publickey/.test(stderr)) return `the hub refused this key; if it has a passphrase, add it to ssh-agent or pick a key without one${tail}`;
+	if (/Address already in use|bind \[.*\]:\d+: Address already in use|Could not request local forwarding/.test(stderr)) return `local port ${ssh.localPort} is already in use; close whatever holds it, or set a different localPort${tail}`;
+	if (/Could not resolve hostname/.test(stderr)) return `the hub machine ${ssh.host} could not be resolved; check the host name${tail}`;
+	if (/Host key verification failed/.test(stderr)) return `the hub machine's host key is not in this machine's known_hosts; connect once from a terminal to accept it${tail}`;
+	return `the tunnel to ${ssh.host} stopped${said === "" ? "" : `: ${said}`}`;
+}
+/** The default spawn: a real ssh, with stderr piped because that is where the reason lives. */
+const realSpawn = (argv) => spawn(argv[0], argv.slice(1), {
+	stdio: [
+		"ignore",
+		"ignore",
+		"pipe"
+	],
+	windowsHide: true
+});
+/** The default probe: can something be connected to on this local port right now? */
+const realProbe = (port) => new Promise((resolve) => {
+	const socket = connect({
+		host: "127.0.0.1",
+		port
+	});
+	const done = (result) => {
+		socket.destroy();
+		resolve(result);
+	};
+	socket.setTimeout(2e3, () => done(false));
+	socket.once("connect", () => done(true));
+	socket.once("error", () => done(false));
+});
+/**
+* Keeps one forwarding process alive, reporting what it is doing.
+*
+* A retry is always a *new* process: an ssh that exited cannot be revived, and reusing the object would report a
+* state no process is in. `stop()` is idempotent and leaves nothing behind, including a pending retry timer.
+*/
+var Tunnel = class {
+	input;
+	current = "idle";
+	lastFailure;
+	child;
+	timer;
+	/** The pending escalation from SIGTERM to SIGKILL after `stop()`. */
+	killTimer;
+	/** Whether the local port was free when the current attempt spawned; only then can an answer be our own forward. */
+	portWasFree = false;
+	/**
+	* The child that has actually exited, if any.
+	*
+	* `ChildProcess.killed` means "a signal was sent", not "the process is gone", so it cannot answer "is it still
+	* running" — and using it that way makes the SIGKILL escalation unreachable. The exit event is the only truth.
+	*/
+	exitedChild;
+	/** A generation counter, so a late callback from a superseded attempt cannot overwrite the current state. */
+	generation = 0;
+	retryMs;
+	maxRetryMs;
+	spawn;
+	probe;
+	constructor(input) {
+		this.input = input;
+		this.spawn = input.spawn ?? realSpawn;
+		this.probe = input.probe ?? realProbe;
+		this.retryMs = input.retryMs ?? 1e3;
+		this.maxRetryMs = input.maxRetryMs ?? 6e4;
+	}
+	state() {
+		return this.current;
+	}
+	/** Why the last attempt failed, already rewritten into something a person can act on. */
+	failure() {
+		return this.lastFailure;
+	}
+	/** Start the first attempt, or do nothing if one is already running. */
+	start() {
+		if (this.current === "connecting" || this.current === "connected") return;
+		this.attempt();
+	}
+	/**
+	* End the process and any pending retry; safe to call more than once.
+	*
+	* SIGTERM first, then SIGKILL: an ssh that ignores or is slow to handle the polite signal would otherwise outlive
+	* the plugin, keep `localPort` bound, and make the next activation's first attempt fail on a port it still owns.
+	*/
+	stop() {
+		this.generation++;
+		if (this.timer !== void 0) {
+			clearTimeout(this.timer);
+			this.timer = void 0;
+		}
+		if (this.killTimer !== void 0) {
+			clearTimeout(this.killTimer);
+			this.killTimer = void 0;
+		}
+		const child = this.child;
+		this.child = void 0;
+		this.set("idle");
+		if (child === void 0 || this.exitedChild === child) return;
+		child.kill("SIGTERM");
+		this.killTimer = setTimeout(() => {
+			if (this.exitedChild !== child) child.kill("SIGKILL");
+		}, STOP_GRACE_MS);
+		this.killTimer.unref?.();
+	}
+	/** One attempt: check the port is free, spawn, wait for the local port, then either stay connected or fail. */
+	async attempt() {
+		const generation = ++this.generation;
+		this.set("connecting");
+		const startedFree = !await this.probe(this.input.ssh.localPort);
+		if (generation !== this.generation) return;
+		this.portWasFree = startedFree;
+		const argv = tunnelArgs(this.input.ssh);
+		let stderr = "";
+		let settled = false;
+		let child;
+		try {
+			child = this.spawn(argv);
+		} catch (error) {
+			this.fail(generation, `could not start ssh: ${String(error)}`);
+			return;
+		}
+		this.child = child;
+		const collect = (chunk) => {
+			stderr = (stderr + chunk.toString("utf8")).slice(-2048);
+		};
+		child.stderr?.on("data", collect);
+		child.on("error", (error) => {
+			if (!settled) {
+				settled = true;
+				this.fail(generation, `could not start ssh: ${error.message}`);
+			}
+		});
+		child.on("exit", (code) => {
+			this.exitedChild = child;
+			if (settled || generation !== this.generation) return;
+			settled = true;
+			this.fail(generation, code === null || code === 0 ? `the tunnel to ${this.input.ssh.host} closed` : explain(this.input.ssh, stderr));
+		});
+		this.waitReady(generation, startedFree, () => settled, () => {
+			settled = true;
+		});
+	}
+	/**
+	* Poll the local port until it answers or the attempt is superseded; a first answer means the forward works.
+	*
+	* Reaching `connected` deliberately does NOT mark the attempt settled. The process is still running, and it is
+	* exactly the exit that follows a working tunnel — a dropped link, a restarted hub — that has to reach `fail` and
+	* schedule a retry. Marking it settled here would leave a device that connects once and then silently stops
+	* taking work, which is the hardest failure to notice.
+	*/
+	async waitReady(generation, startedFree, settled, markSettled) {
+		const deadline = Date.now() + READY_TIMEOUT_MS;
+		while (Date.now() < deadline) {
+			if (generation !== this.generation || settled()) return;
+			if (await this.probe(this.input.ssh.localPort)) {
+				if (generation !== this.generation || settled()) return;
+				if (!startedFree) {
+					markSettled();
+					this.fail(generation, `local port ${this.input.ssh.localPort} was already in use before this attempt, so the device cannot tell its own tunnel from whatever owns that port; close it or set a different localPort`);
+					return;
+				}
+				this.retryMs = this.input.retryMs ?? 1e3;
+				this.lastFailure = void 0;
+				this.set("connected");
+				return;
+			}
+			await new Promise((resolve) => setTimeout(resolve, READY_POLL_MS));
+		}
+		if (generation !== this.generation || settled()) return;
+		markSettled();
+		this.fail(generation, `the tunnel to ${this.input.ssh.host} did not start listening on port ${this.input.ssh.localPort} within ${READY_TIMEOUT_MS / 1e3} seconds`);
+	}
+	/** Record a failure, release the process, and schedule the next attempt with a growing delay. */
+	fail(generation, message) {
+		if (generation !== this.generation) return;
+		this.lastFailure = message;
+		const child = this.child;
+		this.child = void 0;
+		if (child !== void 0 && !child.killed) child.kill("SIGKILL");
+		this.set("failed", message);
+		this.input.log?.(`dsh-foreman-node tunnel: ${message}; retrying in ${Math.round(this.retryMs / 1e3)}s`);
+		const delay = this.retryMs;
+		this.retryMs = Math.min(this.retryMs * 2, this.maxRetryMs);
+		this.timer = setTimeout(() => {
+			this.timer = void 0;
+			if (generation !== this.generation) return;
+			this.attempt();
+		}, delay);
+		this.timer.unref?.();
+	}
+	set(state, failure) {
+		this.current = state;
+		this.input.onState?.(state, failure);
+	}
+};
 // src/report-tool.ts
 /**
 * The `foreman_report` tool a device registers on a job Session.
@@ -473,28 +1003,41 @@ var JobSessions = class {
 };
 // src/index.ts
 /** Version reported in the hello, so the hub can tell which device build is talking. */
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 /**
-* Configuration of one device, from the `dsh-foreman-node` entry in the profile's patch.
-*
-* Everything is optional on purpose. A bundle patch inserts this row the moment the package is added to a profile,
-* so `apply` runs before anyone has filled the values in — and a schema that demanded them would turn the whole
-* profile red with "invalid config" on a fresh install. `apply` treats a blank address as "not configured yet":
-* it says what is missing and stops, instead of dialling nowhere or refusing to activate.
+* The schema, asserted rather than annotated.
 *
-* The annotation names the schema type through the global `Schemastery` namespace rather than letting it be inferred:
-* an inferred type here names a `cosmokit` symbol the emitted declaration cannot reference portably.
+* An annotation makes the declaration portable but cannot express what a volatile field does to a field's type, so the
+* mismatch moves into the annotation. The assertion keeps the published `.d.ts` free of `schemastery` internals and
+* puts the shape in one place; `configured()` is what re-establishes the real types at every read.
 */
-const Config = s.object({
-	url: s.string().default("").description("The hub's address, such as wss://foreman.example.com. The device dials out to it."),
-	deviceId: s.string().default("").description("This device's id, as registered on the hub with `Devices.add`."),
-	token: s.string().default("").role("secret").description("This device's token; it is sent in the hello frame and nowhere else."),
+const Typed = s.object({
+	url: s.string().default("").volatile().description("The hub's address, such as wss://foreman.example.com. The device dials out to it."),
+	deviceId: s.string().default("").volatile().description("This device's id, as registered on the hub with `Devices.add`."),
+	token: s.string().default("").role("secret").volatile().description("This device's token; it is sent in the hello frame and nowhere else."),
 	roots: s.array(s.object({
 		project: s.string().required(),
 		path: s.string().required()
-	})).default([]).description("Projects this device can work on: a logical name and this machine's own absolute path, kept verbatim."),
-	heartbeatMs: s.natural().default(15e3).description("How often to tell the hub this device is alive, in milliseconds."),
-	reconnectMs: s.natural().default(1e3).description("Delay before the first reconnect attempt, in milliseconds.")
+	})).default([]).volatile().description("Projects this device can work on: a logical name and this machine's own absolute path, kept verbatim."),
+	heartbeatMs: s.natural().default(15e3).volatile().description("How often to tell the hub this device is alive, in milliseconds."),
+	reconnectMs: s.natural().default(1e3).volatile().description("Delay before the first reconnect attempt, in milliseconds."),
+	ssh: s.object({
+		enabled: s.boolean().default(false).volatile().description("Reach the hub through an SSH tunnel this device starts itself."),
+		host: s.string().default("").volatile().description("The hub machine, such as 203.0.113.10 or its ~/.ssh/config alias."),
+		port: s.natural().min(1).max(65535).default(22).volatile().description("The hub machine's SSH port."),
+		user: s.string().default("").volatile().description("The SSH user on the hub machine."),
+		keyPath: s.string().default("").volatile().description("The private key this device authenticates with; the page lists these from ~/.ssh."),
+		remotePort: s.natural().min(1).max(65535).default(8790).volatile().description("The port the hub listens on, on the hub machine."),
+		localPort: s.natural().min(1).max(65535).default(8790).volatile().description("The local port the tunnel listens on; the device dials this.")
+	}).default({
+		enabled: false,
+		host: "",
+		port: 22,
+		user: "",
+		keyPath: "",
+		remotePort: 8790,
+		localPort: 8790
+	}).description("How to reach the hub when it is not directly reachable: a tunnel this device opens and keeps open.")
 });
 /**
 * What this configuration still needs before the device can dial its hub, or undefined when it is complete.
@@ -502,9 +1045,23 @@ const Config = s.object({
 * A missing value is reported by name so an operator can fill it in without reading the source; a value that is only
 * whitespace counts as missing, because a device that dials a blank address retries forever and looks merely offline.
 */
+/**
+* The address this device dials.
+*
+* With the tunnel on, that is the local end of it: `url` names the hub at its own address, which the tunnel exists to
+* make reachable, so dialling `url` would bypass the tunnel entirely and look like an offline device. Keeping the two
+* cases in one function is what stops `apply` from picking the wrong one.
+*/
+function hubUrlOf(config) {
+	return config.ssh.enabled ? `ws://127.0.0.1:${config.ssh.localPort}` : config.url;
+}
 function missingConfiguration(config) {
 	const missing = [];
-	if (config.url.trim() === "") missing.push("url");
+	if (config.ssh.enabled) {
+		if (config.ssh.host.trim() === "") missing.push("ssh.host");
+		if (config.ssh.user.trim() === "") missing.push("ssh.user");
+		if (config.ssh.keyPath.trim() === "") missing.push("ssh.keyPath");
+	} else if (config.url.trim() === "") missing.push("url");
 	if (config.deviceId.trim() === "") missing.push("deviceId");
 	if (config.token.trim() === "") missing.push("token");
 	if (missing.length === 0) return void 0;
@@ -530,7 +1087,12 @@ const inject = [
 * The plugin returns once the connection is attempted, not once it succeeds: a device must boot and stay usable
 * while its hub is unreachable, and the client keeps retrying in the background.
 */
-async function apply(ctx, config) {
+async function apply(ctx, raw) {
+	const config = configured(raw);
+	ctx.inject(["webServer"], (child) => {
+		const host = child.webServer;
+		child.effect(() => registerNodeRoutes(host, sshDirectory()));
+	});
 	const missing = missingConfiguration(config);
 	if (missing !== void 0) {
 		ctx.logger.info("%s", missing);
@@ -538,7 +1100,7 @@ async function apply(ctx, config) {
 	}
 	const jobs = new JobSessions(ctx);
 	const client = new NodeClient({
-		url: config.url,
+		url: hubUrlOf(config),
 		deviceId: config.deviceId,
 		token: config.token,
 		version: VERSION,
@@ -554,11 +1116,25 @@ async function apply(ctx, config) {
 			receive(ctx, jobs, client, frame);
 		}
 	});
-	client.start();
+	const tunnel = config.ssh.enabled ? new Tunnel({
+		ssh: config.ssh,
+		log: (text) => ctx.logger.warn("%s", text),
+		onState: (state, failure) => {
+			ctx.logger.info("dsh-foreman-node tunnel: %s", failure === void 0 ? state : `${state} (${failure})`);
+			if (state === "connected") client.start();
+		}
+	}) : void 0;
+	if (tunnel === void 0) client.start();
+	else tunnel.start();
 	ctx.effect(() => () => {
+		tunnel?.stop();
 		client.stop();
 	});
-	ctx.logger.info("dsh-foreman-node %s is dialling %s as %s", VERSION, config.url, config.deviceId);
+	ctx.logger.info("dsh-foreman-node %s is dialling %s as %s", VERSION, hubUrlOf(config), config.deviceId);
+}
+/** The directory the key list reads; `~/.ssh` on a machine where the current user is the one configuring it. */
+function sshDirectory() {
+	return join(homedir(), ".ssh");
 }
 /**
 * Handle one frame from the hub.
@@ -598,4 +1174,4 @@ async function receive(ctx, jobs, client, frame) {
 		});
 	}
 }
-export { Config, JobSessions, NodeClient, REPORT_STATES, VERSION, apply, foremanReportTool, inject, missingConfiguration, name };
+export { Typed as Config, JobSessions, NodeClient, REPORT_STATES, SSH_DEFAULTS, Tunnel, VERSION, apply, configured, foremanReportTool, hubUrlOf, inject, listKeys, missingConfiguration, name, registerNodeRoutes, sshDirectory, testArgs, tunnelArgs };