@edgehero/pi-dispatch 5.0.0 → 5.1.0

package/src/console-devices.mjs

@@ -0,0 +1,372 @@
+/**
+ * The console's remembered devices (issue #849): what lets a browser stay signed in across idle periods and console restarts.
+ *
+ * ONE FILE PER DEVICE, in `console-devices/` beside the tokens file (0700), named by the sha256 of the device's secret and holding that
+ * device's record (0600). Not one file with a list: the console writes during requests while the CLI writes too, and a list's
+ * compare-then-rename can lose a revocation between the two, which is the one write this store may never lose. It also means one bad record
+ * stops one device, not all of them.
+ *
+ * ONLY THE HASH IS ON DISK, so a copy of this directory signs nobody in. The secret exists in the browser's cookie and, once, in the
+ * process that made it.
+ *
+ * A RECORD IS NOT DELETED WHEN A DEVICE ENDS. It keeps `ended: {reason, at}` for `ENDED_RETENTION_MS`, because a browser presenting the
+ * cookie later has to be told the true reason (issue acceptance 6), including after a restart. A name keeps only its newest dead records (see
+ * `MAX_DEVICES_PER_NAME`), so a very busy name can lose an older reason sooner than that. A dead secret's hash is not sensitive, and the
+ * reason is shown only to whoever presents that cookie. A tombstone stops nothing for whoever can write this folder: they could remove `ended`,
+ * or plant a record outright. That boundary is the folder being owner-only and guarded, not the record's shape. REJECTED: a keyed MAC over each
+ * record, which would need a key kept beside what it protects.
+ *
+ * LAST USE IS THE FILE'S MTIME, set at most daily. A touch changes no content, so it can never overwrite the `ended` a revocation just wrote.
+ * REJECTED: a `lastUsedAt` field, which needs a read-modify-write on the hottest path, exactly the race the per-device file exists to remove.
+ *
+ * THREE ANSWERS, NOT TWO. `readDevice` says a record is here, is absent, or could not be judged. The third matters: a bad store must never
+ * end a session the way a revocation does, and must never pass one as live.
+ *
+ * WHAT MAY BE COPIED FROM `login-codes.mjs` AND WHAT MUST NOT. Its `dirProblem` idea is here, with an owner check it lacks. Its `take` unlinks
+ * on read and its `reap` deletes anything without a future `expiresAt`, which is every record in this directory. The fix sentence for an
+ * unsafe store is "remove", not `chmod`: tightening a directory another account could write would make whatever it planted good.
+ */
+import * as nodeFs from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { basename, dirname, join } from "node:path";
+import { TOKEN_NAME_RE } from "./console-tokens.mjs";
+
+/** The directory's name, beside the tokens file. */
+export const CONSOLE_DEVICES_DIRNAME = "console-devices";
+
+/** The roles a device may be remembered for. An allowlist, so a role added later is not remembered until someone decides it should be. */
+export const REMEMBER_ROLES = Object.freeze(["operator", "viewer"]);
+
+/** How long a dead record is kept to say why. */
+export const ENDED_RETENTION_MS = 90 * 24 * 3600 * 1000;
+
+/**
+ * The most devices one token may have remembered, and the most dead records kept for it: a remember-then-end loop would otherwise grow this folder
+ * without bound, and every remember scans it. Losing an old dead record costs only the sentence saying why.
+ */
+export const MAX_DEVICES_PER_NAME = 32;
+
+/** How often last-use is written. A day is enough for "last used" to mean something, and keeps a request's work to a read. */
+export const TOUCH_INTERVAL_MS = 24 * 3600 * 1000;
+
+/** The most a record can be. Far above a real one, and it stops a planted file being read whole on every listing. */
+const RECORD_MAX_BYTES = 64 * 1024;
+
+/** How old a leftover temporary file must be before it is removed: older than any write in progress. */
+const STALE_TEMP_MS = 3600 * 1000;
+
+/** Why a device stopped being trusted. Each one is a reason the console can word for the person holding the cookie. */
+export const DEVICE_END_REASONS = Object.freeze(["signed-out", "removed", "revoked", "role", "all", "replaced"]);
+
+/** The closed word list a label is built from: never User-Agent bytes, which are attacker-chosen and would end up on a page. */
+export const DEVICE_BROWSERS = Object.freeze(["Chrome", "Edge", "Firefox", "Safari", "Browser"]);
+export const DEVICE_SYSTEMS = Object.freeze(["macOS", "Windows", "Linux", "iPhone", "iPad", "Android", "this system"]);
+
+const HASH_RE = /^[0-9a-f]{64}$/;
+// Either case: on a case-insensitive volume an uppercase name is the same file a lowercase hash opens, so a listing must see it (and report it).
+const RECORD_FILE_RE = /^[0-9a-fA-F]{64}\.json$/;
+const TEMP_FILE_RE = /^\.[0-9a-f]{64}\.[0-9a-f]{16}\.tmp$/;
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+export const DEVICE_SECRET_RE = /^[A-Za-z0-9_-]{43}$/;
+
+const errCode = (e) => (typeof e?.code === "string" ? e.code : "error");
+
+/** A shape alone admits `2026-99-99T99:99:99.999Z`, which reads as NaN and would look very old to a sweep. */
+const isoIsReal = (text) => typeof text === "string" && ISO_RE.test(text) && Number.isFinite(Date.parse(text)) && new Date(text).toISOString() === text;
+
+export function consoleDevicesDir(tokensPath) {
+	return join(dirname(tokensPath), CONSOLE_DEVICES_DIRNAME);
+}
+
+/**
+ * The cookie's name for this deployment. Cookies ignore ports, so two deployments on one loopback address would otherwise overwrite each
+ * other's remembered device, and the person would simply find they had to sign in again with nothing to say why.
+ */
+export function deviceCookieName(tokensPath) {
+	return `pdc_device_${createHash("sha256").update(String(tokensPath)).digest("hex").slice(0, 10)}`;
+}
+
+export function newDeviceSecret(random = randomBytes) {
+	return random(32).toString("base64url");
+}
+
+export function hashDeviceSecret(secret) {
+	return createHash("sha256").update(String(secret)).digest("hex");
+}
+
+/** What a list shows and a command takes: enough to tell devices apart, and useless for finding a record's secret. */
+export function deviceIdOf(hash) {
+	return String(hash).slice(0, 12);
+}
+
+/** A label from closed word lists, for telling devices apart on a page. Anything unrecognised is the plain fallback, never the header's bytes. */
+export function deviceLabelOf(userAgent) {
+	const ua = typeof userAgent === "string" ? userAgent : "";
+	const browser = /Edg\//.test(ua) ? "Edge" : /Firefox\//.test(ua) ? "Firefox" : /Chrome\//.test(ua) ? "Chrome" : /Safari\//.test(ua) ? "Safari" : "Browser";
+	const system = /iPhone/.test(ua) ? "iPhone" : /iPad/.test(ua) ? "iPad" : /Android/.test(ua) ? "Android" : /Mac OS X/.test(ua) ? "macOS" : /Windows/.test(ua) ? "Windows" : /Linux/.test(ua) ? "Linux" : "this system";
+	return `${browser} on ${system}`;
+}
+
+const labelIsClosed = (label) => typeof label === "string" && DEVICE_BROWSERS.some((b) => DEVICE_SYSTEMS.some((s) => label === `${b} on ${s}`));
+
+function validRecord(r) {
+	if (r === null || typeof r !== "object" || Array.isArray(r)) return false;
+	if (r.version !== 1 || typeof r.name !== "string" || !TOKEN_NAME_RE.test(r.name) || !REMEMBER_ROLES.includes(r.role)) return false;
+	if (typeof r.tokenHash !== "string" || !HASH_RE.test(r.tokenHash) || !Number.isSafeInteger(r.generation) || r.generation < 0) return false;
+	if (!isoIsReal(r.createdAt) || !labelIsClosed(r.label)) return false;
+	if (r.ended !== undefined) {
+		if (r.ended === null || typeof r.ended !== "object" || !DEVICE_END_REASONS.includes(r.ended.reason) || !isoIsReal(r.ended.at)) return false;
+	}
+	return true;
+}
+
+/**
+ * What is wrong with the directory, or null: a symlink, anything but a directory, any group or world bit, or another account's. With `create`,
+ * a missing one is made 0700, chmod'd exactly since mkdir's mode is masked by the umask. `{absent: true}` for a missing one without `create`.
+ */
+export function devicesDirProblem(dir, { fs = nodeFs, uid = process.geteuid?.(), create = false, platform = process.platform } = {}) {
+	// Node reports group and other bits on every Windows folder, so the mode check below could only ever refuse, and a folder made first would
+	// then be one doctor fails on from that day on. Said once, here, and nothing is made.
+	if (platform === "win32" && create) return { problem: "remembering a device does not work on a Windows host, because Windows reports every folder as open to other accounts; paste a token instead" };
+	let st;
+	try {
+		st = fs.lstatSync(dir);
+	} catch (e) {
+		if (e?.code !== "ENOENT") return { problem: `the remembered-device folder ${dir} could not be inspected (${errCode(e)}); check its parent's permissions` };
+		if (!create) return { absent: true };
+		try {
+			// Tolerated: two first remembers racing is no fault, and the checks below judge whichever folder won.
+			try { fs.mkdirSync(dir, { mode: 0o700 }); fs.chmodSync(dir, 0o700); }
+			catch (e2) { if (e2?.code !== "EEXIST") throw e2; }
+			st = fs.lstatSync(dir);
+		} catch (e2) {
+			return { problem: `the remembered-device folder ${dir} could not be created (${errCode(e2)}); check that the tokens file's folder exists and belongs to this account` };
+		}
+	}
+	const remove = `remove the folder (\`rm -r ${JSON.stringify(dir)}\`); every browser then signs in again`;
+	if (st.isSymbolicLink()) return { problem: `the remembered-device folder ${dir} is a symbolic link, and the console uses only a real folder; ${remove}` };
+	if (!st.isDirectory()) return { problem: `${dir} is not a folder; ${remove}` };
+	if (uid !== undefined && st.uid !== uid) return { problem: `the remembered-device folder ${dir} belongs to another account, so what it holds cannot be trusted; ${remove}` };
+	if ((st.mode & 0o077) !== 0) return { problem: `the remembered-device folder ${dir} can be reached by other accounts (mode ${(st.mode & 0o777).toString(8).padStart(3, "0")}), so what it holds cannot be trusted; ${remove}` };
+	// Readable but not writable would pass every read and then fail the one write that must work, a revocation.
+	if ((st.mode & 0o700) !== 0o700) return { problem: `the remembered-device folder ${dir} cannot be written by its owner (mode ${(st.mode & 0o777).toString(8).padStart(3, "0")}), so a device could not be removed; restore it with \`chmod u+rwx ${JSON.stringify(dir)}\`, which is safe here because it gives nobody else anything` };
+	return null;
+}
+
+/** The record at `path`, read through one no-follow descriptor: `{record, mtimeMs}`, `{absent}` or `{unjudged}`. */
+function readRecordFile(path, { fs, uid }) {
+	let fd;
+	try {
+		fd = fs.openSync(path, nodeFs.constants.O_RDONLY | nodeFs.constants.O_NOFOLLOW | nodeFs.constants.O_NONBLOCK);
+	} catch (e) {
+		if (e?.code === "ENOENT") return { absent: true };
+		return { unjudged: `the record could not be opened (${errCode(e)})` };
+	}
+	try {
+		const st = fs.fstatSync(fd);
+		if (!st.isFile()) return { unjudged: "the record is not a regular file" };
+		if (uid !== undefined && st.uid !== uid) return { unjudged: "the record belongs to another account" };
+		if ((st.mode & 0o077) !== 0) return { unjudged: "the record can be reached by other accounts" };
+		// A second name could sit anywhere and be edited there. Backups that hard-link fail closed, which is the right way to fail.
+		// `> 1`, not `!== 1`: a file just renamed over reads 0 to whoever still holds it, and those bytes are whole.
+		if (st.nlink > 1) return { unjudged: "the record has more than one name" };
+		if (st.size > RECORD_MAX_BYTES) return { unjudged: "the record is too large to be one of this console's" };
+		let record;
+		try { record = JSON.parse(fs.readFileSync(fd, "utf8")); } catch { return { unjudged: "the record is not valid JSON" }; }
+		if (!validRecord(record)) return { unjudged: "the record is not one this console can read" };
+		return { record, mtimeMs: st.mtimeMs };
+	} catch (e) {
+		return { unjudged: `the record could not be read (${errCode(e)})` };
+	} finally {
+		try { fs.closeSync(fd); } catch { /* the answer above stands */ }
+	}
+}
+
+/**
+ * One device, by the hash of its secret: `{record, mtimeMs}`, `{absent: true}` when the store holds no such device, or `{unjudged}` when
+ * nothing can be said (the folder gone or unsafe, the record corrupt or unsafe). A missing folder is unjudged rather than absent on purpose:
+ * a repointed `PI_CONSOLE_TOKENS_FILE` must not read as every device having been revoked.
+ */
+export function readDevice({ dir, hash, fs = nodeFs, uid = process.geteuid?.() }) {
+	if (typeof hash !== "string" || !HASH_RE.test(hash)) return { absent: true };
+	const problem = devicesDirProblem(dir, { fs, uid });
+	if (problem?.absent) return { unjudged: "the remembered-device folder does not exist" };
+	if (problem) return { unjudged: problem.problem };
+	const path = join(dir, `${hash}.json`);
+	/** On a case-insensitive volume an uppercase name opens as this one, so the name on disk has to be looked at too, whichever read found it. */
+	const named = (found) => {
+		if (found.record === undefined) return found;
+		try {
+			const onDisk = (fs.realpathSync?.native ?? fs.realpathSync)?.(path);
+			return typeof onDisk !== "string" || basename(onDisk) === `${hash}.json` ? found : { unjudged: "the record's name is not one this console writes" };
+		} catch (e) {
+			return { unjudged: `the record could not be looked at (${errCode(e)})` };
+		}
+	};
+	const read = readRecordFile(path, { fs, uid });
+	if (!read.absent) return named(read);
+	// A folder that went away between the check and the open says nothing about this device, and must not read as a revocation.
+	const after = devicesDirProblem(dir, { fs, uid });
+	if (after !== null) return { unjudged: after.problem ?? "the remembered-device folder does not exist" };
+	// Looked at once more: a folder that left and came back around the open would otherwise read as this device being gone.
+	return named(readRecordFile(path, { fs, uid }));
+}
+
+/** Write `record` for `hash` so a crash leaves the old bytes or the new ones, never half of either: a private temporary, fsync, rename, fsync of the folder. */
+function writeRecord({ dir, hash, record, fs, random }) {
+	const temp = join(dir, `.${hash}.${random(8).toString("hex")}.tmp`);
+	const fd = fs.openSync(temp, "wx", 0o600);
+	try {
+		try {
+			fs.writeFileSync(fd, `${JSON.stringify(record)}\n`);
+			fs.fsyncSync(fd);
+		} finally {
+			fs.closeSync(fd);
+		}
+	} catch (e) {
+		try { fs.unlinkSync(temp); } catch { /* it may be gone already */ }
+		throw e;
+	}
+	try {
+		// The create's mode is masked by the umask; set it exactly.
+		fs.chmodSync(temp, 0o600);
+		fs.renameSync(temp, join(dir, `${hash}.json`));
+	} catch (e) {
+		try { fs.unlinkSync(temp); } catch { /* it may be gone already */ }
+		throw e;
+	}
+	const dirFd = fs.openSync(dir, "r");
+	try { fs.fsyncSync(dirFd); } finally { fs.closeSync(dirFd); }
+}
+
+/** Every record file here: `{records: [{hash, record?, mtimeMs?, unjudged?}]}`, read without stopping at a bad one. */
+function allRecords(dir, { fs, uid }) {
+	return fs.readdirSync(dir).filter((name) => RECORD_FILE_RE.test(name)).map((name) => {
+		const hash = name.slice(0, -".json".length);
+		if (hash !== hash.toLowerCase()) return { hash, unjudged: "the record's name is not one this console writes" };
+		return { hash, ...readRecordFile(join(dir, name), { fs, uid }) };
+	});
+}
+
+/**
+ * Remember a device: `{secret, hash, record}`, or `{refusal}` saying what stands in the way. The binding (`name`, `role`, `tokenHash`, `generation`) is
+ * what lets every existing way of ending a sign-in also end this: revoke and rotate change the hash, a role change the role, `sessions end-all` the
+ * generation. The caller judges a record against the tokens file at each use. `tokenCreatedAt` is the entry's own `createdAt`: a device older than the
+ * entry cannot belong to it, which is the only way to order a hash, so a caller holding a stale entry cannot end a newer device.
+ */
+export function rememberDevice({ dir, name, role, tokenHash, generation, tokenCreatedAt = null, label = "Browser on this system", fs = nodeFs, uid = process.geteuid?.(), now = Date.now, random = randomBytes }) {
+	if (!REMEMBER_ROLES.includes(role)) return { refusal: `a ${String(role).slice(0, 32)} token cannot be remembered on a device` };
+	if (typeof name !== "string" || !TOKEN_NAME_RE.test(name) || typeof tokenHash !== "string" || !HASH_RE.test(tokenHash) || !Number.isSafeInteger(generation) || generation < 0) return { refusal: "this sign-in cannot be remembered: its token entry is not one the store accepts" };
+	const problem = devicesDirProblem(dir, { fs, uid, create: true });
+	if (problem) return { refusal: problem.problem };
+	try {
+		const mine = allRecords(dir, { fs, uid }).filter((row) => row.record?.name === name);
+		// A device bound to a token entry that has since been rotated or ended can never sign in again, so it holds no place under the cap and ages out.
+		for (const row of mine) {
+			if (row.record.ended !== undefined) continue;
+			// The true reason, since this is what the browser holding that cookie will be told. Only ever downward: an entry that may be stale must not end a newer device.
+			const reason = row.record.generation < generation ? "all" : row.record.role !== role && row.record.generation === generation && row.record.tokenHash === tokenHash ? "role" : row.record.tokenHash !== tokenHash && typeof tokenCreatedAt === "string" && row.record.createdAt < tokenCreatedAt ? "revoked" : null;
+			if (reason === null) continue;
+			if (endDevice({ dir, hash: row.hash, reason, fs, uid, now, random }).ok) row.record.ended = { reason, at: new Date(now()).toISOString() };
+		}
+		const live = mine.filter((row) => row.record.ended === undefined).length;
+		// `full` lets a page say what a person can do about it (remove one), where every other refusal is the operator's to fix.
+		if (live >= MAX_DEVICES_PER_NAME) return { refusal: `"${name}" already has ${live} remembered devices, the most one sign-in may have; remove one first`, full: true };
+		const dead = mine.filter((row) => row.record.ended !== undefined).sort((a, b) => Date.parse(b.record.ended.at) - Date.parse(a.record.ended.at));
+		for (const row of dead.slice(MAX_DEVICES_PER_NAME - 1)) {
+			try { fs.unlinkSync(join(dir, `${row.hash}.json`)); } catch { /* the next remember */ }
+		}
+		const secret = newDeviceSecret(random);
+		const hash = hashDeviceSecret(secret);
+		const record = { version: 1, name, role, tokenHash, generation, createdAt: new Date(now()).toISOString(), label: labelIsClosed(label) ? label : "Browser on this system" };
+		writeRecord({ dir, hash, record, fs, random });
+		return { secret, hash, record };
+	} catch (e) {
+		return { refusal: `this device could not be remembered (${errCode(e)}); check the folder ${dir}` };
+	}
+}
+
+/**
+ * End a device, durably: `{ok: true}`, `{ok: true, already: true}` for one already ended, `{absent: true}` for none, or `{problem}`. Rewrites the
+ * record rather than removing it (see the header). Sequential ends keep the first reason. Ends that truly race both answer `ok` and one reason stays:
+ * the device is ended either way, and only the sentence shown can differ. REJECTED: an exclusive claim to close that, since it would add a way for a
+ * revocation to fail in order to protect a sentence.
+ */
+export function endDevice({ dir, hash, reason, fs = nodeFs, uid = process.geteuid?.(), now = Date.now, random = randomBytes }) {
+	if (!DEVICE_END_REASONS.includes(reason)) throw new RangeError(`endDevice: a reason is one of ${DEVICE_END_REASONS.join(", ")}, not ${JSON.stringify(reason)}`);
+	const read = readDevice({ dir, hash, fs, uid });
+	if (read.absent) return { absent: true };
+	if (read.unjudged) return { problem: read.unjudged };
+	if (read.record.ended !== undefined) return { ok: true, already: true };
+	try {
+		const { mtimeMs } = read;
+		writeRecord({ dir, hash, record: { ...read.record, ended: { reason, at: new Date(now()).toISOString() } }, fs, random });
+		// Last use is the file's mtime, and the rename above has just reset it to the moment of the end.
+		try { fs.utimesSync(join(dir, `${hash}.json`), mtimeMs / 1000, mtimeMs / 1000); } catch { /* the end is durable, and that was only its last-used time */ }
+		return { ok: true };
+	} catch (e) {
+		return { problem: `the device could not be ended (${errCode(e)})` };
+	}
+}
+
+/** Move a device's last-use forward, at most daily. Best effort and changes no content, so it can be lost freely and can never lose an end. */
+export function touchDevice({ dir, hash, mtimeMs, fs = nodeFs, now = Date.now }) {
+	if (typeof hash !== "string" || !HASH_RE.test(hash)) return false;
+	if (typeof mtimeMs === "number" && now() - mtimeMs < TOUCH_INTERVAL_MS) return false;
+	try {
+		const seconds = now() / 1000;
+		// `lutimes`: a link planted at the name must not have some other file's time moved.
+		fs.lutimesSync(join(dir, `${hash}.json`), seconds, seconds);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Every device: `{devices, unreadable}` (newest first), or `{problem}`. A missing folder is simply no devices here: this is a listing, not a judgement. */
+export function listDevices({ dir, fs = nodeFs, uid = process.geteuid?.() }) {
+	const problem = devicesDirProblem(dir, { fs, uid });
+	if (problem?.absent) return { devices: [], unreadable: 0, unreadableIds: [] };
+	if (problem) return { problem: problem.problem };
+	try {
+		const rows = allRecords(dir, { fs, uid });
+		const devices = rows.filter((row) => row.record).map((row) => ({ id: deviceIdOf(row.hash), hash: row.hash, name: row.record.name, role: row.record.role, label: row.record.label, createdAt: row.record.createdAt, lastUsedAt: new Date(row.mtimeMs).toISOString(), ...(row.record.ended ? { ended: { reason: row.record.ended.reason, at: row.record.ended.at } } : {}) }));
+		devices.sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0));
+		const bad = rows.filter((row) => row.unjudged);
+		return { devices, unreadable: bad.length, unreadableIds: bad.map((row) => deviceIdOf(row.hash)) };
+	} catch (e) {
+		return { problem: `the remembered-device folder ${dir} could not be read (${errCode(e)})` };
+	}
+}
+
+/** Remove dead records past retention and temporaries a crash left. Nothing it cannot read and nothing live: only the operator decides those. Returns how many went. */
+export function reapDevices({ dir, fs = nodeFs, uid = process.geteuid?.(), now = Date.now }) {
+	const problem = devicesDirProblem(dir, { fs, uid });
+	if (problem) return 0;
+	let removed = 0;
+	const t = now();
+	try {
+		for (const row of allRecords(dir, { fs, uid })) {
+			if (row.record?.ended === undefined || !(t - Date.parse(row.record.ended.at) > ENDED_RETENTION_MS)) continue;
+			try { fs.unlinkSync(join(dir, `${row.hash}.json`)); removed += 1; } catch { /* the next sweep */ }
+		}
+		for (const name of fs.readdirSync(dir)) {
+			if (!TEMP_FILE_RE.test(name)) continue;
+			try {
+				const path = join(dir, name);
+				if (t - fs.lstatSync(path).mtimeMs > STALE_TEMP_MS) { fs.unlinkSync(path); removed += 1; }
+			} catch { /* the next sweep */ }
+		}
+	} catch { /* a folder that went away has nothing left to sweep */ }
+	return removed;
+}
+
+/** What doctor says of the store: `{absent}`, `{problem}`, or `{live, unreadable}`. */
+export function devicesState({ dir, fs = nodeFs, uid = process.geteuid?.(), platform = process.platform }) {
+	const problem = devicesDirProblem(dir, { fs, uid, platform });
+	if (problem?.absent) return { absent: true };
+	if (problem) return { problem: problem.problem };
+	const listed = listDevices({ dir, fs, uid });
+	if (listed.problem) return { problem: listed.problem };
+	return { live: listed.devices.filter((d) => d.ended === undefined).length, unreadable: listed.unreadable, unreadableIds: listed.unreadableIds };
+}

package/src/console-install.mjs

@@ -0,0 +1,239 @@
+/**
+ * `npx @edgehero/pi-dispatch up --console` in an empty folder (issue #849): turn three install lines into one.
+ *
+ * A worker running from npm's execution cache can never become a service: the cache is disposable, so a unit pointing into it would
+ * break whenever npm prunes it (`setup-host-entry.mjs`). That refusal stays. What changes is the cache path's answer: rather than tell
+ * the person to run three more commands, it runs them, with the same exact pins the README and the wizard use, and hands over to the
+ * binary it just installed in the folder. Everything after the handover is the ordinary durable path, so nothing the cache run did can
+ * become a service.
+ *
+ * ORDER IS THE CONTRACT. Every refusal that needs nothing installed runs first, then the one question, and only then does anything
+ * touch the folder, so a refusal leaves no `node_modules` (`REQ-BROWSER-FIRST-RUN-SETUP`).
+ *
+ * THE INSTALL HAPPENS IN A STAGING FOLDER and is moved into place only after npm exits 0. npx looks in the current folder first: if a
+ * stopped install left the worker package here without its bin, npx would try to run a bin that does not exist, this code would never
+ * start, and the same command could never recover. REJECTED: cleaning up after a non-zero exit, which a Ctrl-C or the timeout's SIGKILL
+ * never reaches.
+ *
+ * THE ENVIRONMENT IS CLEANED, not inherited. npx exports `npm_config_*` values of its own run (the package it fetched, its prefix) and
+ * puts its cache's `.bin`, every ancestor folder's `node_modules/.bin` and npm's `node-gyp-bin` first on PATH. An install or a service
+ * that inherited those would be describing the cache, and a folder's `.bin` on PATH would let a planted `launchctl` run before the person
+ * has answered anything. A registry or proxy the person set themselves is not on the list and survives.
+ */
+import * as nodeFs from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { installedUnitPaths } from "./service.mjs";
+import { setupCachePath, trustedSetupFile } from "./setup-host-entry.mjs";
+import { askFirstRun, attachedCommand, commandsHere, deploymentPreflight, ensureConsoleShortcut, flagValue, newOperatorNameProblem, operatorChoiceProblem, serviceManagerAnswers, tightenedUmask } from "./console-bootstrap.mjs";
+import { VALKEY_PASSWORD_KEY } from "./valkey-auth.mjs";
+import { EXACT_VERSION_RE } from "./package-names.mjs";
+import { readUnitSeam } from "./service.mjs";
+
+/** How long the install may take. A bound, so a stalled registry ends in a refusal rather than a terminal that hangs forever. */
+export const INSTALL_TIMEOUT_MS = 10 * 60_000;
+
+/** The name of the private `package.json`, which also marks it as ours. */
+const DEPLOYMENT_PACKAGE_NAME = "pi-dispatch-deployment";
+
+/** Where the install is built before it is moved into place. What a stopped install left here is removed before the next one. */
+const STAGING_DIR = ".pi-dispatch-install";
+
+/** Names a folder may hold and still count as empty: files that say nothing about what the folder is for. */
+const IGNORABLE = new Set([".DS_Store", ".git", ".gitignore", STAGING_DIR]);
+
+/**
+ * What a folder may hold and still be a deployment: what `init` scaffolds (a test holds this to a real run of `init`) and what the
+ * console and this tooling add there. Anything else is someone's project, whatever else sits beside it.
+ */
+export const DEPLOYMENT_FILES = new Set([".env", "triggers.json", "pause-windows.json", "pi-packages.json", "subscriptions.json", "scoped-limits.json", "projects.json", "egress-allowlist.conf", "model-endpoints.conf", "model-endpoints.json", "deploy", "console-tokens.json", "console-login-codes", "console-devices", "pi-dispatch", ".pi-dispatch-setup.lock"]);
+
+/** What only npx puts in the environment. An allowlist of npm's own exports, so a person's `npm_config_registry` is left alone. */
+const NPX_ENV_RE = /^(?:INIT_CWD|NODE|npm_(?:command|execpath|node_execpath|lifecycle_\w+|package_\w+|config_(?:call|cache|global_prefix|globalconfig|ignore_scripts|init_module|local_prefix|node_gyp|noproxy|npm_version|package|prefix|user_agent|userconfig|yes)))$/;
+
+/** This package's own version and the exact pi it was built against, read from its own `package.json`, never from a flag. */
+export function ownPackageVersions({ path = fileURLToPath(new URL("../package.json", import.meta.url)), fs = nodeFs } = {}) {
+	const pkg = JSON.parse(fs.readFileSync(path, "utf8"));
+	return { version: pkg.version, piVersion: pkg.dependencies?.["@earendil-works/pi-ai"] };
+}
+
+/**
+ * The npm argv for the durable install. The same packages and flags as the wizard's `browserInstallArgs` (the admin workspace's test
+ * holds the two equal), written out here because the worker cannot import from the admin package it is about to install.
+ */
+export function selfInstallArgs({ version, piVersion }) {
+	return ["install", `@edgehero/pi-dispatch-admin@${version}`, `@earendil-works/pi-coding-agent@${piVersion}`, "--save-exact", `@edgehero/pi-dispatch@${version}`, "--omit=dev", "--omit=optional", "--ignore-scripts", "--no-audit", "--no-fund", "--loglevel=error"];
+}
+
+/** Is this PATH entry something npx put there? Narrower than `setupCachePath`, so a person's own `~/.cache/foo/bin` stays. */
+const npxPathEntry = (part) => /(?:^|[/\\])_npx(?:[/\\]|$)/.test(part) || /(?:^|[/\\])node_modules[/\\]\.bin[/\\]?$/.test(part) || /[/\\]node-gyp-bin[/\\]?$/.test(part);
+
+/** `env` without what npx added: its exports, and what it put on PATH. */
+export function cleanedNpxEnv(env) {
+	const out = {};
+	for (const [key, value] of Object.entries(env)) if (!NPX_ENV_RE.test(key)) out[key] = value;
+	// env-internal PATH: an environment passed through, with only what npx added taken out.
+	if (typeof env.PATH === "string") out.PATH = env.PATH.split(":").filter((part) => !npxPathEntry(part)).join(":");
+	return out;
+}
+
+/**
+ * A private root `package.json`, so npm cannot settle on some project higher up the tree (the wizard's own guard). `wx`: a name that is
+ * a dangling link was missed by the folder check's `exists`, and must not be written through.
+ */
+function ensureDeploymentPackageJson(fs, dir) {
+	const path = join(dir, "package.json");
+	if (!fs.existsSync(path)) fs.writeFileSync(path, `${JSON.stringify({ name: DEPLOYMENT_PACKAGE_NAME, private: true }, null, 2)}\n`, { flag: "wx" });
+}
+
+/** Is there a symlink here, even one that points nowhere? `existsSync` follows the link and says no to a dangling one. */
+function isLink(fs, path) {
+	try { return fs.lstatSync(path).isSymbolicLink(); } catch { return false; }
+}
+
+/** Do the folder and every parent belong to this account or root, and are they closed to others? `trustedSetupFile` asks this after the install; asking it now means a refusal leaves nothing behind. */
+function folderChainTrusted(fs, dir, uid) {
+	for (let parent = dirname(dir); ; parent = dirname(parent)) {
+		const st = fs.statSync(parent);
+		if (!st.isDirectory() || (st.uid !== uid && st.uid !== 0) || ((st.mode & 0o022) && !(st.mode & 0o1000))) return false;
+		if (parent === dirname(parent)) return true;
+	}
+}
+
+/**
+ * Is the `package.json` here exactly what this tooling writes? A failed install leaves it behind, and a re-run must not be refused for it.
+ * The exact keys matter: `overrides` or `dependencies` under our name would redirect what the pinned install resolves.
+ */
+function ourPackageJson(fs, dir) {
+	try {
+		const pkg = JSON.parse(fs.readFileSync(join(dir, "package.json"), "utf8"));
+		return Object.keys(pkg).sort().join(",") === "name,private" && pkg.name === DEPLOYMENT_PACKAGE_NAME && pkg.private === true;
+	} catch { return false; }
+}
+
+/** Does `.env` hold a key `init` writes? `.env` alone is in every other web project, and is no evidence of a deployment. */
+function initWroteEnv(fs, dir) {
+	try { return new RegExp(`^${VALKEY_PASSWORD_KEY}=`, "m").test(fs.readFileSync(join(dir, ".env"), "utf8")); } catch { return false; }
+}
+
+/** Is this folder empty, or already a deployment? Anything else is someone's project, and installing into it would be a surprise. */
+function folderProblem(fs, dir, home, uid) {
+	let isHome = false;
+	try { isHome = dir === fs.realpathSync(home); } catch { /* an unreadable home is simply not this folder */ }
+	if (isHome) return "this is your home folder. Make a new folder for the deployment and run this there.";
+	if (setupCachePath(dir)) return "this folder is inside a cache, which can be emptied at any time. Make a folder somewhere that will stay and run this there.";
+	if (!folderChainTrusted(fs, dir, uid)) return "a folder above this one can be written by another account, so what is installed here could not be trusted. Make a folder somewhere only you can write and run this there.";
+	// The real path, so a `.bin` planted beside our own package.json counts as the leftover it is, not as an installation to send someone to.
+	let installed = false;
+	try { installed = fs.realpathSync(join(dir, "node_modules", ".bin", "pi-dispatch")) === join(dir, "node_modules", "@edgehero", "pi-dispatch", "src", "cli.mjs"); } catch { /* no bin, so no installation */ }
+	if (installed) return "this folder already has pi-dispatch installed. Run its own: ./node_modules/.bin/pi-dispatch up --console";
+	const ours = ourPackageJson(fs, dir);
+	const names = fs.readdirSync(dir).filter((name) => !IGNORABLE.has(name) && !(ours && (name === "package.json" || name === "node_modules")));
+	if (names.length === 0) return null;
+	const foreign = names.find((name) => !DEPLOYMENT_FILES.has(name));
+	const isDeployment = names.includes("triggers.json") || (names.includes(".env") && initWroteEnv(fs, dir));
+	if (foreign !== undefined || !isDeployment) return `this folder already holds other files (${foreign ?? names.join(", ")}) and is not a deployment. Make a new empty folder and run this there.`;
+	return null;
+}
+
+export async function runSelfInstall(argv, deps) {
+	const { fs, env, cwd, platform, euid: uid, home, out, prompt, consoleCommand: run, refuse } = deps;
+	let own;
+	try { own = (deps.ownPackage ?? ownPackageVersions)(); } catch { return refuse("this package's own version could not be read, so nothing can be pinned; nothing was changed."); }
+	if (!EXACT_VERSION_RE.test(String(own.version)) || !EXACT_VERSION_RE.test(String(own.piVersion))) return refuse("this package does not name exact versions to install, so nothing can be pinned; nothing was changed.");
+
+	// The folder before the preflight's mode check, so a folder that holds someone's project under a loose umask is told that, not about its mode.
+	// Only on a platform that can run this: the platform refusal below is the better sentence on the others.
+	if (["linux", "darwin"].includes(platform)) {
+		let problem;
+		try { problem = folderProblem(fs, fs.realpathSync(cwd), home, uid); } catch { return refuse("the deployment folder could not be read; nothing was changed."); }
+		if (problem) return refuse(problem);
+	}
+	const pre = deploymentPreflight({ fs, env, cwd, platform, uid, refuse, consoleTokensPath: deps.consoleTokensPath, readTokens: deps.readTokens, looseEmptyIgnoring: IGNORABLE });
+	if (pre.refused !== undefined) return pre.refused;
+	const { dir, existing } = pre;
+	// Free, and the installed binary would refuse it after the install otherwise.
+	const operators = existing?.tokens.filter((entry) => entry.role === "operator") ?? [];
+	const choice = operatorChoiceProblem(flagValue(argv, "--name"), operators);
+	if (choice) return refuse(choice);
+	if (operators.length > 1 && flagValue(argv, "--name") === null && !(deps.isTTY ?? Boolean(process.stdin.isTTY))) return refuse("there are several operators and no terminal to ask on, so name one with --name; nothing was changed.");
+	if (operators.length === 0) {
+		const nameProblem = newOperatorNameProblem(flagValue(argv, "--name") ?? "operator", existing);
+		if (nameProblem) return refuse(nameProblem);
+	}
+	// A console unit is account-wide. The installed binary would refuse a foreign one after the install; refusing here leaves no node_modules.
+	const unit = installedUnitPaths(platform, home).find((row) => row.which === "console" && fs.existsSync(row.path));
+	if (unit) {
+		let owner = null;
+		try { owner = readUnitSeam(fs.readFileSync(unit.path, "utf8"), platform).deployDir; } catch { /* the path alone still says which service */ }
+		const there = owner ? commandsHere(owner, fs, { from: dir }).worker : "pi-dispatch";
+		return refuse(`this account already has a console service (${unit.path})${owner ? `, for ${owner}` : ""}. Run ${there} up --console for that deployment, or ${there} service uninstall --console there first; nothing was changed.`);
+	}
+	// The cleaned PATH: a planted `launchctl` in some folder's `node_modules/.bin` must not run, and this probe comes before any answer.
+	const clean = cleanedNpxEnv(env);
+	if (!(await serviceManagerAnswers({ run, platform, uid, dir, env: clean }))) return refuse("the account's user service manager did not answer. Start it before console bootstrap.");
+
+	const installLine = `npm ${selfInstallArgs(own).join(" ")}`;
+	// One question only for a new deployment, as in `runConsoleUp`: on one in use, `--yes` can restart a live queue.
+	const isNew = !fs.existsSync(join(dir, ".env"));
+	const decision = argv.includes("--yes") ? "yes" : argv.includes("--ask-each") || !isNew ? "each" : await askFirstRun({ dir, installing: true, prompt, out });
+	if (decision === "no") { out("Console bootstrap declined; nothing was changed.\n"); return 0; }
+	out(`  ${installLine}\n`);
+	if (decision === "each" && !/^y(es)?$/i.test(String(await prompt("Run that in this folder? [y/N] ")).trim())) { out("Console bootstrap declined; nothing was changed.\n"); return 0; }
+
+	// Under a umask like Ubuntu's 002 npm writes group-writable files, which the durable checks then rightly refuse, after all the work.
+	// Set here, so the install and the handed-over child both inherit it.
+	(deps.tightenUmask ?? (() => process.umask(tightenedUmask(process.umask()))))();
+	const staging = join(dir, STAGING_DIR);
+	try {
+		const st = fs.statSync(dir);
+		if (st.mode & 0o022) {
+			fs.chmodSync(dir, st.mode & ~0o022 & 0o7777);
+			// Looked at again now that nobody else can add to it: the check before the question was only true then, and it may have waited a long time.
+			if (fs.readdirSync(dir).some((name) => !IGNORABLE.has(name))) return refuse("files appeared in this folder while it was open to other accounts, so nothing was installed. Make a new folder and run this there.");
+		}
+		// The retries are for an interrupted npm, which goes on writing here for about a second after Ctrl-C has returned the prompt.
+		// NOT under the deployment's setup lock, though two runs at once in one folder would share this name: a Ctrl-C would leave that lock
+		// behind, and a lock nobody may remove would bring back the dead end this staging folder exists to prevent.
+		fs.rmSync(staging, { recursive: true, force: true, maxRetries: 8, retryDelay: 250 });
+		fs.mkdirSync(staging, { mode: 0o700 });
+		ensureDeploymentPackageJson(fs, staging);
+	} catch { return refuse("the deployment folder could not be prepared; an earlier install may still be stopping, so wait a moment and run this again. Nothing else was changed."); }
+	const install = deps.npmInstall ?? ((args, options) => attachedCommand("npm", args, { ...options, stdio: ["ignore", "inherit", "inherit"], timeout: INSTALL_TIMEOUT_MS }));
+	const code = await install(selfInstallArgs(own), { cwd: staging, env: clean });
+	if (code !== 0) return refuse("npm could not install the packages. Fix what it printed above and run this again.");
+	try {
+		// Whatever appeared while npm ran is someone's, and the renames below would replace it without a word.
+		if ((fs.existsSync(join(dir, "package.json")) && !ourPackageJson(fs, dir)) || fs.existsSync(join(dir, "package-lock.json"))) return refuse("this folder changed while it was being set up, so nothing was installed. Run this again in an empty folder.");
+		// What an earlier install left. Only reached beside our own `package.json`, read again here because the question may have waited a long
+		// time. A symlink is removed, not followed.
+		const leftover = join(dir, "node_modules");
+		if (fs.existsSync(leftover) || isLink(fs, leftover)) {
+			if (!ourPackageJson(fs, dir)) return refuse("this folder changed while it was being set up, so nothing was installed. Run this again in an empty folder.");
+			out("  removing what an earlier install left in node_modules\n");
+			fs.rmSync(leftover, { recursive: true, force: true });
+		}
+		// node_modules first. If anything stops between these, what is here is complete and the next run uses it.
+		fs.renameSync(join(staging, "node_modules"), leftover);
+		for (const name of ["package.json", "package-lock.json"]) if (fs.existsSync(join(staging, name))) fs.renameSync(join(staging, name), join(dir, name));
+		fs.rmSync(staging, { recursive: true, force: true });
+	} catch { return refuse("the installed packages could not be moved into this folder; run this again."); }
+
+	const entry = join(dir, "node_modules", "@edgehero", "pi-dispatch", "src", "cli.mjs");
+	const metadata = join(dirname(dirname(entry)), "package.json");
+	try {
+		const trust = deps.trustedFile ?? ((path) => trustedSetupFile(path, { uid, stat: fs.statSync, realpath: fs.realpathSync }));
+		const pkg = JSON.parse(fs.readFileSync(metadata, "utf8"));
+		if (!trust(entry) || !trust(metadata) || pkg.name !== "@edgehero/pi-dispatch" || pkg.version !== own.version) return refuse("the installed package could not be trusted or is not the expected version; nothing was started.");
+	} catch { return refuse("the installed package could not be validated; nothing was started."); }
+	// Straight away, so that if the steps after this fail (Docker not running is the likely one) the way to retry exists and can be named.
+	const shortcut = ensureConsoleShortcut(dir, fs);
+
+	// The answer crosses the handover as a flag, so the person is never asked the same thing twice.
+	const rest = argv.filter((arg) => arg !== "--yes" && arg !== "--ask-each" && arg !== "--console");
+	const handed = await (deps.handOver ?? attachedCommand)(process.execPath, [entry, "up", "--console", decision === "yes" ? "--yes" : "--ask-each", ...rest], { cwd: dir, env: clean });
+	const retry = `${shortcut ? "./pi-dispatch" : "./node_modules/.bin/pi-dispatch"} up --console`;
+	if (typeof handed !== "number") return refuse(`the installed pi-dispatch could not be started. Run this in this folder: ${retry}`);
+	if (handed !== 0) out(`Fix what is printed above, then run this in this folder: ${retry}\n`);
+	return handed;
+}