workerdeck 0.0.0 → 0.6.0

package/build/instance-kupxU5UD.mjs

@@ -0,0 +1,1019 @@
+import { createReadStream, existsSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { createFileSessionStore, createWorkerServer } from "@workerdeck/server";
+import { dashboardDir } from "@workerdeck/web";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { pathToFileURL } from "node:url";
+//#region src/auth-key.ts
+/** 48 hex chars — far past `createCliAuth`'s 12-char floor, and header-safe. */
+const generateKey = () => randomBytes(24).toString("hex");
+/** A stored key must be one printable-ASCII line long enough to be a secret:
+* both transports (HTTP header, login form) choke on anything else, and a
+* truncated or garbage file should regenerate, not crash or half-work. */
+const usableStoredKey = (raw) => {
+	const line = raw.split("\n", 1)[0]?.trim() ?? "";
+	return line.length >= 12 && /^[\x21-\x7e]+$/.test(line) ? line : null;
+};
+async function materializeAuthKey(stateDir, options = {}) {
+	const warn = options.warn ?? ((message) => process.stderr.write(`[workerdeck] ${message}\n`));
+	if (stateDir === null) return {
+		key: generateKey(),
+		source: "ephemeral",
+		path: null
+	};
+	const path = join(stateDir, "auth-key");
+	let raw = null;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch {
+		raw = null;
+	}
+	if (raw !== null) {
+		const key = usableStoredKey(raw);
+		if (key !== null) {
+			try {
+				const { mode } = await stat(path);
+				if ((mode & 63) !== 0) warn(`auth key file ${path} is readable by other users (mode ${(mode & 511).toString(8)}) — run: chmod 600 ${path}`);
+			} catch {}
+			return {
+				key,
+				source: "stored",
+				path
+			};
+		}
+	}
+	const key = generateKey();
+	await mkdir(stateDir, {
+		recursive: true,
+		mode: 448
+	});
+	await writeFile(path, `${key}\n`, { mode: 384 });
+	await chmod(path, 384);
+	return {
+		key,
+		source: "created",
+		path
+	};
+}
+//#endregion
+//#region src/auth.ts
+const MIN_SECRET_LENGTH = 12;
+const DEFAULT_COOKIE_NAME = "workerdeck_session";
+const DEFAULT_TTL_MS = 10080 * 60 * 1e3;
+const DEFAULT_THROTTLE_WINDOW_MS = 900 * 1e3;
+const DEFAULT_MAX_FAILURES_PER_IP = 10;
+const DEFAULT_MAX_FAILURES_GLOBAL = 100;
+/** Only successful logins insert, so this cap only fences the secret-holder's
+* own memory use (every login within the ttl is a live entry). Oldest goes. */
+const MAX_SESSIONS = 100;
+const MAX_LOGIN_BODY_BYTES = 4096;
+const SAFE_METHODS = new Set([
+	"GET",
+	"HEAD",
+	"OPTIONS"
+]);
+const sha256 = (value) => createHash("sha256").update(value).digest();
+function createCliAuth(options = {}) {
+	const { secret } = options;
+	const enabled = secret !== void 0;
+	if (secret !== void 0 && secret.length < MIN_SECRET_LENGTH) throw new Error(`createCliAuth: secret must be at least ${MIN_SECRET_LENGTH} characters — use a long random value, or leave it unset to run without auth on loopback`);
+	const cookieName = options.cookieName ?? DEFAULT_COOKIE_NAME;
+	const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+	if (!(ttlMs > 0)) throw new Error("createCliAuth: ttlMs must be positive");
+	const trustProxy = options.trustProxy === true;
+	const windowMs = options.throttle?.windowMs ?? DEFAULT_THROTTLE_WINDOW_MS;
+	const maxFailuresPerIp = options.throttle?.maxFailuresPerIp ?? DEFAULT_MAX_FAILURES_PER_IP;
+	const maxFailuresGlobal = options.throttle?.maxFailuresGlobal ?? DEFAULT_MAX_FAILURES_GLOBAL;
+	const allowedOrigins = new Set((options.allowedOrigins ?? []).map((entry) => {
+		try {
+			return new URL(entry).origin;
+		} catch {
+			throw new Error(`createCliAuth: allowedOrigins entry is not a valid origin: ${JSON.stringify(entry)}`);
+		}
+	}));
+	/** Both the raw secret and session tokens are compared as fixed-length SHA-256
+	* digests via timingSafeEqual / digest-keyed lookup, so no code path compares
+	* secret material byte-by-byte with early exit — and unequal input lengths
+	* leak nothing either. */
+	const secretDigest = secret === void 0 ? void 0 : sha256(secret);
+	const secretMatches = (candidate) => secretDigest !== void 0 && timingSafeEqual(sha256(candidate), secretDigest);
+	/**
+	* Browser sessions are a server-side table, not signed tokens: logout must
+	* actually invalidate, and a stateless HMAC token stays valid until expiry no
+	* matter what the server thinks. This is one long-lived process (multi-node
+	* is a non-goal), so "table" means one Map — the cost is that a restart signs
+	* every browser out, which for an operator dashboard one secret away from
+	* re-login is the right trade. Keys are token digests: recovering an entry's
+	* token from lookup timing would need a SHA-256 preimage.
+	*/
+	const sessions = /* @__PURE__ */ new Map();
+	const tokenKey = (token) => sha256(token).toString("hex");
+	const createSession = () => {
+		if (sessions.size >= MAX_SESSIONS) {
+			const oldest = sessions.keys().next().value;
+			if (oldest !== void 0) sessions.delete(oldest);
+		}
+		const token = randomBytes(32).toString("base64url");
+		sessions.set(tokenKey(token), { expiresAt: Date.now() + ttlMs });
+		return token;
+	};
+	const cookieToken = (req) => {
+		const header = req.headers.cookie;
+		if (typeof header !== "string") return void 0;
+		for (const part of header.split(";")) {
+			const eq = part.indexOf("=");
+			if (eq === -1) continue;
+			if (part.slice(0, eq).trim() === cookieName) return part.slice(eq + 1).trim();
+		}
+	};
+	const hasSession = (req) => {
+		const token = cookieToken(req);
+		if (token === void 0 || token === "") return false;
+		const key = tokenKey(token);
+		const entry = sessions.get(key);
+		if (entry === void 0) return false;
+		if (entry.expiresAt <= Date.now()) {
+			sessions.delete(key);
+			return false;
+		}
+		return true;
+	};
+	/** Last value of a possibly comma-joined forwarded header — the one appended
+	* (or set) by the trusted proxy; every earlier position is client-writable. */
+	const forwardedLast = (value) => {
+		if (value === void 0) return void 0;
+		const last = (Array.isArray(value) ? value.join(",") : value).split(",").at(-1)?.trim();
+		return last === "" ? void 0 : last;
+	};
+	const isSecure = (req) => {
+		if (req.socket.encrypted === true) return true;
+		return trustProxy && forwardedLast(req.headers["x-forwarded-proto"])?.toLowerCase() === "https";
+	};
+	/** The origin this server believes it is being served as, from the request's
+	* own Host (or the proxy's forwarded host) — the only self-knowledge we have. */
+	const expectedOrigin = (req) => {
+		const host = (trustProxy ? forwardedLast(req.headers["x-forwarded-host"]) : void 0) ?? req.headers.host;
+		if (host === void 0 || host === "") return null;
+		try {
+			return new URL(`${isSecure(req) ? "https" : "http"}://${host}`).origin;
+		} catch {
+			return null;
+		}
+	};
+	/**
+	* The CSRF core. `SameSite=Lax` alone is not enough for two reasons: same
+	* *site* is not same *origin* (another port on localhost — any other local
+	* web app — is same-site, cookies attach), and the WS handshake is exempt
+	* from CORS, so a foreign page that gets the cookie attached can read the
+	* stream. So the Origin header is checked explicitly, against the request's
+	* own origin (full scheme + authority: an http:// page on the same host must
+	* not drive the https:// dashboard) or the operator's allowlist. `Origin:
+	* null` and unparseable values are foreign. Verdicts are tri-state because
+	* absence means different things per call site: every current browser sends
+	* Origin on cross-site POSTs and every WS handshake, so absence means a
+	* non-browser client — which carries no ambient cookie and gets to decide
+	* per-endpoint below.
+	*/
+	const originVerdict = (req) => {
+		const raw = req.headers.origin;
+		if (raw === void 0) return "absent";
+		let origin;
+		try {
+			origin = new URL(raw).origin;
+		} catch {
+			return "foreign";
+		}
+		if (allowedOrigins.has(origin)) return "ok";
+		const expected = expectedOrigin(req);
+		return expected !== null && origin === expected ? "ok" : "foreign";
+	};
+	const headerSecret = (req) => {
+		const key = req.headers["x-workerdeck-key"];
+		if (typeof key === "string" && key !== "") return key;
+		const authorization = req.headers.authorization;
+		if (typeof authorization === "string") {
+			const match = /^Bearer\s+(.+)$/i.exec(authorization);
+			if (match !== null) return match[1];
+		}
+	};
+	const openPrincipal = {
+		via: "open",
+		canManageProfiles: true
+	};
+	const authenticate = (req) => {
+		if (!enabled) return openPrincipal;
+		const provided = headerSecret(req);
+		if (provided !== void 0) return secretMatches(provided) ? {
+			via: "header",
+			canManageProfiles: true
+		} : null;
+		if (!hasSession(req)) return null;
+		const verdict = originVerdict(req);
+		if (verdict === "foreign") return null;
+		const upgrade = req.headers.upgrade;
+		const isUpgrade = typeof upgrade === "string" && upgrade.toLowerCase().includes("websocket");
+		const unsafe = !SAFE_METHODS.has((req.method ?? "GET").toUpperCase());
+		if ((isUpgrade || unsafe) && verdict !== "ok") return null;
+		return {
+			via: "cookie",
+			canManageProfiles: true
+		};
+	};
+	/**
+	* Login throttle: the secret is the only factor and the endpoint is reachable
+	* by anyone who can reach the port, so guessing must be rate-limited. Failed
+	* attempts count per client IP inside a fixed window, with a global cap
+	* behind it so rotating IPs (trivial over IPv6) buys an attacker nothing.
+	* Only wrong secrets count — malformed requests and foreign-Origin posts are
+	* refused earlier precisely so a hostile page cannot burn a victim IP's
+	* budget cross-site. The global cap also bounds this map's size: expired
+	* entries are swept once it grows past a nominal size.
+	*/
+	const failures = /* @__PURE__ */ new Map();
+	const globalFailures = {
+		count: 0,
+		windowStart: 0
+	};
+	const clientIp = (req) => (trustProxy ? forwardedLast(req.headers["x-forwarded-for"]) : void 0) ?? req.socket.remoteAddress ?? "unknown";
+	const blockedMs = (entry, max, now) => entry !== void 0 && entry.count >= max && now - entry.windowStart < windowMs ? entry.windowStart + windowMs - now : 0;
+	const loginBlockedMs = (ip, now) => Math.max(blockedMs(failures.get(ip), maxFailuresPerIp, now), blockedMs(globalFailures, maxFailuresGlobal, now));
+	const recordFailure = (ip, now) => {
+		if (failures.size > 256) {
+			for (const [key, entry] of failures) if (now - entry.windowStart >= windowMs) failures.delete(key);
+		}
+		const entry = failures.get(ip);
+		if (entry === void 0 || now - entry.windowStart >= windowMs) failures.set(ip, {
+			count: 1,
+			windowStart: now
+		});
+		else entry.count += 1;
+		if (now - globalFailures.windowStart >= windowMs) {
+			globalFailures.count = 1;
+			globalFailures.windowStart = now;
+		} else globalFailures.count += 1;
+	};
+	const cookieAttributes = (req) => {
+		const attrs = [
+			"Path=/",
+			"HttpOnly",
+			"SameSite=Lax"
+		];
+		if (isSecure(req)) attrs.push("Secure");
+		return attrs;
+	};
+	const setCookieValue = (token, req) => [
+		`${cookieName}=${token}`,
+		`Max-Age=${Math.ceil(ttlMs / 1e3)}`,
+		...cookieAttributes(req)
+	].join("; ");
+	const clearCookieValue = (req) => [
+		`${cookieName}=`,
+		"Max-Age=0",
+		...cookieAttributes(req)
+	].join("; ");
+	const respondJson = (res, status, body, headers) => {
+		res.writeHead(status, {
+			"content-type": "application/json",
+			"cache-control": "no-store",
+			...headers
+		}).end(JSON.stringify(body));
+	};
+	const respondRedirect = (res, location, headers) => {
+		res.writeHead(303, {
+			location,
+			"cache-control": "no-store",
+			...headers
+		}).end();
+	};
+	/** JSON responses when the client asks for them, 303 redirects otherwise —
+	* so a dependency-free `<form method="post">` login page works without JS,
+	* and a fetch()-based one gets real status codes. */
+	const wantsJson = (req) => (req.headers.accept ?? "").includes("application/json");
+	const readBody = (req, maxBytes) => new Promise((resolve) => {
+		const chunks = [];
+		let size = 0;
+		let settled = false;
+		const finish = (value) => {
+			if (!settled) {
+				settled = true;
+				resolve(value);
+			}
+		};
+		req.on("data", (chunk) => {
+			size += chunk.length;
+			if (size > maxBytes) {
+				finish(null);
+				return;
+			}
+			chunks.push(chunk);
+		});
+		req.on("end", () => finish(Buffer.concat(chunks).toString("utf8")));
+		req.on("error", () => finish(null));
+	});
+	const handleLogin = async (req, res) => {
+		const json = wantsJson(req);
+		if (!enabled) {
+			respondJson(res, 409, { error: "auth is disabled: no secret is configured" });
+			return;
+		}
+		if (originVerdict(req) === "foreign") {
+			respondJson(res, 403, { error: "origin not allowed" });
+			return;
+		}
+		const ip = clientIp(req);
+		const blocked = loginBlockedMs(ip, Date.now());
+		if (blocked > 0) {
+			const retryAfter = String(Math.ceil(blocked / 1e3));
+			if (json) respondJson(res, 429, { error: "too many failed attempts" }, { "retry-after": retryAfter });
+			else respondRedirect(res, "/?auth=throttled", { "retry-after": retryAfter });
+			return;
+		}
+		const body = await readBody(req, MAX_LOGIN_BODY_BYTES);
+		if (body === null) {
+			respondJson(res, 413, { error: "body too large" });
+			res.once("finish", () => req.destroy());
+			return;
+		}
+		const contentType = (req.headers["content-type"] ?? "").split(";")[0].trim().toLowerCase();
+		let candidate;
+		if (contentType === "application/x-www-form-urlencoded") candidate = new URLSearchParams(body).get("secret");
+		else if (contentType === "application/json") try {
+			candidate = JSON.parse(body).secret;
+		} catch {
+			respondJson(res, 400, { error: "invalid body" });
+			return;
+		}
+		else {
+			respondJson(res, 415, { error: "expected application/x-www-form-urlencoded or application/json" });
+			return;
+		}
+		if (typeof candidate !== "string" || candidate === "") {
+			respondJson(res, 400, { error: "missing secret" });
+			return;
+		}
+		if (!secretMatches(candidate)) {
+			recordFailure(ip, Date.now());
+			if (json) respondJson(res, 401, { error: "invalid secret" });
+			else respondRedirect(res, "/?auth=failed");
+			return;
+		}
+		failures.delete(ip);
+		const cookie = setCookieValue(createSession(), req);
+		if (json) res.writeHead(204, {
+			"set-cookie": cookie,
+			"cache-control": "no-store"
+		}).end();
+		else respondRedirect(res, "/", { "set-cookie": cookie });
+	};
+	const handleLogout = (req, res) => {
+		const json = wantsJson(req);
+		if (enabled) {
+			if (originVerdict(req) === "foreign") {
+				respondJson(res, 403, { error: "origin not allowed" });
+				return;
+			}
+			const token = cookieToken(req);
+			if (token !== void 0 && token !== "") sessions.delete(tokenKey(token));
+		}
+		const cookie = clearCookieValue(req);
+		if (json) res.writeHead(204, {
+			"set-cookie": cookie,
+			"cache-control": "no-store"
+		}).end();
+		else respondRedirect(res, "/", { "set-cookie": cookie });
+	};
+	const handleAuthRoute = async (pathname, req, res) => {
+		if (pathname === "/auth/status") {
+			if (req.method !== "GET") respondJson(res, 405, { error: "method not allowed" }, { allow: "GET" });
+			else respondJson(res, 200, {
+				enabled,
+				authenticated: enabled ? hasSession(req) : true
+			});
+			return;
+		}
+		if (pathname === "/auth/login") {
+			if (req.method !== "POST") respondJson(res, 405, { error: "method not allowed" }, { allow: "POST" });
+			else await handleLogin(req, res);
+			return;
+		}
+		if (pathname === "/auth/logout") {
+			if (req.method !== "POST") respondJson(res, 405, { error: "method not allowed" }, { allow: "POST" });
+			else handleLogout(req, res);
+			return;
+		}
+		respondJson(res, 404, { error: "not found" });
+	};
+	const handleAuthRequest = (req, res) => {
+		let pathname;
+		try {
+			pathname = new URL(req.url ?? "/", "http://internal").pathname;
+		} catch {
+			return false;
+		}
+		if (pathname !== "/auth" && !pathname.startsWith("/auth/")) return false;
+		return handleAuthRoute(pathname, req, res).then(() => true);
+	};
+	const loginPage = (req) => {
+		let reason = null;
+		try {
+			reason = new URL(req.url ?? "/", "http://internal").searchParams.get("auth");
+		} catch {
+			reason = null;
+		}
+		return {
+			action: "/auth/login",
+			field: "secret",
+			error: reason === "failed" ? "Invalid access key. Try again." : reason === "throttled" ? "Too many failed attempts. Wait a few minutes, then try again." : void 0
+		};
+	};
+	return {
+		enabled,
+		authenticate,
+		handleAuthRequest,
+		hasValidSession: (req) => enabled ? hasSession(req) : true,
+		loginPage
+	};
+}
+//#endregion
+//#region src/config.ts
+/**
+* The config surface has to be JavaScript, not JSON: the two options a real
+* deployment always needs — `authenticate` and `buildRunnerConfig` — are
+* functions. So the file default-exports `WorkerServerOptions` (optionally as a
+* function, sync or async, for config that has to await something), and flags
+* and env cover the cases that fit on a command line.
+*
+* Precedence, narrowest wins: flags > env > config file > defaults. A config
+* file that sets `authenticate` itself opts out of the built-in shared-secret
+* auth entirely — see `resolveInstanceConfig`.
+*/
+const CONFIG_BASENAMES = [
+	"workerdeck.config.mjs",
+	"workerdeck.config.js",
+	"workerdeck.config.cjs"
+];
+var ConfigError = class extends Error {};
+function parsePort(raw, source) {
+	const port = Number(raw);
+	if (!Number.isInteger(port) || port < 0 || port > 65535) throw new ConfigError(`${source}: not a valid port: ${raw}`);
+	return port;
+}
+/**
+* Hand-rolled rather than a dependency: the CLI's whole value is that `npx
+* workerdeck` pulls down a small tree, and an arg parser is a hundred lines
+* of it.
+*/
+function parseArgs(argv) {
+	const flags = {
+		profiles: [],
+		cwdRoots: [],
+		allowedOrigins: [],
+		allowedHosts: [],
+		insecureHosts: []
+	};
+	const next = (i, name) => {
+		const value = argv[i + 1];
+		if (value === void 0 || value.startsWith("-")) throw new ConfigError(`${name} requires a value`);
+		return value;
+	};
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		switch (arg) {
+			case "-h":
+			case "--help":
+				flags.help = true;
+				break;
+			case "-v":
+			case "--version":
+				flags.version = true;
+				break;
+			case "-c":
+			case "--config":
+				flags.config = next(i, arg);
+				i++;
+				break;
+			case "-p":
+			case "--port":
+				flags.port = parsePort(next(i, arg), arg);
+				i++;
+				break;
+			case "--host":
+				flags.host = next(i, arg);
+				i++;
+				break;
+			case "--auth-key":
+				flags.authKey = next(i, arg);
+				i++;
+				break;
+			case "--profile": {
+				const raw = next(i, arg);
+				i++;
+				const eq = raw.indexOf("=");
+				if (eq <= 0) throw new ConfigError(`--profile expects name=dir, got: ${raw}`);
+				const name = raw.slice(0, eq);
+				const dir = raw.slice(eq + 1);
+				if (!dir) throw new ConfigError(`--profile ${name}= is missing a directory`);
+				flags.profiles.push({
+					name,
+					configDir: resolve(dir)
+				});
+				break;
+			}
+			case "--cwd-root":
+				flags.cwdRoots.push(resolve(next(i, arg)));
+				i++;
+				break;
+			case "--allowed-origin":
+				flags.allowedOrigins.push(next(i, arg));
+				i++;
+				break;
+			case "--allowed-host":
+				flags.allowedHosts.push(next(i, arg));
+				i++;
+				break;
+			case "--insecure-host":
+				flags.insecureHosts.push(next(i, arg));
+				i++;
+				break;
+			case "--trust-proxy":
+				flags.trustProxy = true;
+				break;
+			case "--state-dir":
+				flags.stateDir = resolve(next(i, arg));
+				i++;
+				break;
+			case "--no-parking-store":
+				flags.parking = false;
+				break;
+			case "--insecure":
+				flags.insecure = true;
+				break;
+			case "--open":
+				flags.open = true;
+				break;
+			default: throw new ConfigError(`unknown option: ${arg}`);
+		}
+	}
+	return flags;
+}
+/**
+* Explicit `--config` must exist — a typo that silently starts a default
+* instance is worse than a failure. An implicit one is looked up in cwd only:
+* walking parent directories would make what a given command does depend on
+* where it was run from.
+*/
+async function loadConfigFile(explicit, cwd = process.cwd()) {
+	let path = null;
+	if (explicit) {
+		path = isAbsolute(explicit) ? explicit : resolve(cwd, explicit);
+		if (!existsSync(path)) throw new ConfigError(`no config file at ${path}`);
+	} else path = CONFIG_BASENAMES.map((name) => join(cwd, name)).find((p) => existsSync(p)) ?? null;
+	if (!path) return {
+		path: null,
+		options: {}
+	};
+	let mod;
+	try {
+		mod = await import(pathToFileURL(path).href);
+	} catch (error) {
+		throw new ConfigError(`failed to load ${path}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const exported = mod.default;
+	if (exported === void 0) throw new ConfigError(`${path} has no default export (expected WorkerServerOptions)`);
+	const options = typeof exported === "function" ? await exported() : exported;
+	if (typeof options !== "object" || options === null) throw new ConfigError(`${path} default export is not an options object`);
+	return {
+		path,
+		options
+	};
+}
+const LOOPBACK = new Set([
+	"127.0.0.1",
+	"::1",
+	"localhost",
+	"::ffff:127.0.0.1"
+]);
+function isLoopback(host) {
+	return LOOPBACK.has(host);
+}
+/**
+* Durable parking is on by default because this is a long-lived instance: a
+* turnkey tool that silently drops parked work on every restart is the wrong
+* default. The store writes whole transcripts in plaintext, so it goes beside
+* the config file (or under the home directory) rather than anywhere temporary,
+* and one directory serves exactly one instance — the store is single-process
+* by design, which the single-port model already implies.
+*/
+function defaultStateDir(configPath) {
+	return configPath ? join(dirname(configPath), ".workerdeck") : join(homedir(), ".workerdeck");
+}
+/** Hostname out of a Host header, minus the port and any IPv6 brackets. */
+function hostnameOf(hostHeader) {
+	try {
+		return new URL(`http://${hostHeader}`).hostname.replace(/^\[|\]$/g, "").toLowerCase();
+	} catch {
+		return "";
+	}
+}
+/** 127.0.0.0/8, ::1, and the names that mean them. */
+function isLoopbackHostname(hostname) {
+	if (LOOPBACK.has(hostname)) return true;
+	return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname);
+}
+/**
+* An `insecureHosts` entry names a host, never an endpoint: it is compared
+* against the bind host and against Host headers, and both are portless by the
+* time they are compared. An entry carrying a port would therefore never match
+* anything — a gate that looks armed and is not — so it is rejected loudly, as
+* is anything that does not parse as a host name or address. Bare IPv6 is
+* bracketed before parsing (WHATWG URL requires that), and the result is
+* lowercased to match `hostnameOf`'s normal form.
+*/
+function normalizeInsecureHost(raw) {
+	const entry = raw.trim();
+	const looksLikeNamePort = /^[^:]+:\d+$/.test(entry);
+	const candidate = entry.includes(":") && !entry.startsWith("[") && !looksLikeNamePort ? `[${entry}]` : entry;
+	let url;
+	try {
+		url = new URL(`http://${candidate}`);
+	} catch {
+		throw new ConfigError(`not a host name or address in insecureHosts: ${JSON.stringify(raw)}`);
+	}
+	if (url.port !== "") throw new ConfigError(`insecureHosts entry ${JSON.stringify(raw)} carries a port — name the host alone; the bind host and the Host header are both compared portless`);
+	return url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+}
+function resolveInstanceConfig(flags, loaded, env = process.env, cwd = process.cwd()) {
+	const envPort = env.WORKERDECK_PORT ? parsePort(env.WORKERDECK_PORT, "WORKERDECK_PORT") : void 0;
+	const port = flags.port ?? envPort ?? loaded.options.port ?? 8787;
+	const host = flags.host ?? env.WORKERDECK_HOST ?? loaded.options.host ?? "127.0.0.1";
+	const authKey = flags.authKey || env.WORKERDECK_AUTH_KEY || loaded.options.auth?.secret || void 0;
+	const hostAuthenticates = typeof loaded.options.authenticate === "function";
+	const insecureHosts = new Set([...flags.insecureHosts, ...loaded.options.insecureHosts ?? []].map(normalizeInsecureHost));
+	/** The bind host in the same normal form the entries were put in. It never
+	* carries a port — that is a separate flag — so only brackets and case vary. */
+	const bindHost = host.trim().replace(/^\[|\]$/g, "").toLowerCase();
+	const generateAuthKey = !authKey && !hostAuthenticates && !loaded.options.allowUnauthenticated && !isLoopback(host) && !flags.insecure && !insecureHosts.has(bindHost);
+	const stateDir = flags.parking === false || loaded.options.stateDir === null ? null : flags.stateDir ?? env.WORKERDECK_STATE_DIR ?? loaded.options.stateDir ?? defaultStateDir(loaded.path);
+	const envCwdRoots = env.WORKERDECK_CWD_ROOTS?.split(":").filter(Boolean).map((p) => resolve(cwd, p));
+	const cwdRoots = flags.cwdRoots.length ? flags.cwdRoots : envCwdRoots;
+	const auth = {
+		...loaded.options.auth,
+		secret: authKey,
+		trustProxy: flags.trustProxy ?? loaded.options.auth?.trustProxy,
+		allowedOrigins: [...loaded.options.auth?.allowedOrigins ?? [], ...flags.allowedOrigins]
+	};
+	const allowedHosts = Boolean(authKey) || hostAuthenticates || generateAuthKey ? null : new Set([
+		...LOOPBACK,
+		...[...flags.allowedHosts, ...loaded.options.allowedHosts ?? []].map((name) => name.toLowerCase()),
+		...insecureHosts
+	]);
+	const { port: _p, host: _h, auth: _a, stateDir: _s, allowedHosts: _ah, insecureHosts: _ih, webRoot: _w, ...serverOptions } = loaded.options;
+	const options = { ...serverOptions };
+	if (cwdRoots?.length) options.allowedCwdRoots = cwdRoots;
+	if (flags.profiles.length) options.profiles = flags.profiles;
+	return {
+		port,
+		host,
+		authKey,
+		auth,
+		stateDir,
+		configPath: loaded.path,
+		hostAuthenticates,
+		generateAuthKey,
+		allowedHosts,
+		webRoot: loaded.options.webRoot,
+		open: flags.open ?? false,
+		options
+	};
+}
+//#endregion
+//#region src/login-page.ts
+const escapeHtml = (value) => value.replace(/[&<>"']/g, (c) => ({
+	"&": "&amp;",
+	"<": "&lt;",
+	">": "&gt;",
+	"\"": "&quot;",
+	"'": "&#39;"
+})[c] ?? c);
+function renderLoginPage(options) {
+	const { action, field, error, redirectTo, redirectField } = options;
+	const hidden = redirectField && redirectTo ? `<input type="hidden" name="${escapeHtml(redirectField)}" value="${escapeHtml(redirectTo)}">` : "";
+	const alert = error ? `<p class="error" role="alert">${escapeHtml(error)}</p>` : "";
+	return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>workerdeck</title>
+<style>
+  :root {
+    color-scheme: light dark;
+    --bg: #fbfaf9; --fg: #1c1917; --muted: #78716c;
+    --card: #ffffff; --border: #e7e5e4; --accent: #c2410c; --error: #b91c1c;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #1c1917; --fg: #fafaf9; --muted: #a8a29e;
+      --card: #292524; --border: #44403c; --accent: #fb923c; --error: #fca5a5;
+    }
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; min-height: 100dvh; display: grid; place-items: center; padding: 1.5rem;
+    background: var(--bg); color: var(--fg);
+    font: 15px/1.5 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  }
+  form {
+    width: 100%; max-width: 22rem; background: var(--card);
+    border: 1px solid var(--border); border-radius: 12px; padding: 1.75rem;
+  }
+  h1 { margin: 0 0 .25rem; font-size: 1.05rem; letter-spacing: -0.01em; }
+  p.sub { margin: 0 0 1.25rem; color: var(--muted); font-size: .875rem; }
+  label { display: block; font-size: .8125rem; font-weight: 500; margin-bottom: .375rem; }
+  input[type=password] {
+    width: 100%; padding: .5rem .625rem; font: inherit; color: inherit;
+    background: var(--bg); border: 1px solid var(--border); border-radius: 7px;
+  }
+  input[type=password]:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
+  button {
+    width: 100%; margin-top: 1rem; padding: .5rem .75rem; font: inherit; font-weight: 500;
+    color: var(--bg); background: var(--fg); border: 0; border-radius: 7px; cursor: pointer;
+  }
+  button:hover { opacity: .9; }
+  .error { margin: 0 0 1rem; color: var(--error); font-size: .8125rem; }
+</style>
+</head>
+<body>
+  <form method="post" action="${escapeHtml(action)}">
+    <h1>workerdeck</h1>
+    <p class="sub">This instance is protected. Enter its access key to continue.</p>
+    ${alert}
+    <label for="key">Access key</label>
+    <input id="key" name="${escapeHtml(field)}" type="password" autocomplete="current-password"
+           autofocus required spellcheck="false">
+    ${hidden}
+    <button type="submit">Sign in</button>
+  </form>
+</body>
+</html>
+`;
+}
+//#endregion
+//#region src/static.ts
+/**
+* Static file serving for the bundled dashboard. Deliberately policy-free: what
+* counts as a document, and whether an unauthenticated visitor gets the app or a
+* login page, is decided by the caller (see `instance.ts`). This module only
+* answers "is there such a file, and what headers does it want".
+*/
+const CONTENT_TYPES = {
+	".html": "text/html; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".mjs": "text/javascript; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".map": "application/json; charset=utf-8",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".webp": "image/webp",
+	".avif": "image/avif",
+	".ico": "image/x-icon",
+	".woff": "font/woff",
+	".woff2": "font/woff2",
+	".ttf": "font/ttf",
+	".wasm": "application/wasm",
+	".txt": "text/plain; charset=utf-8"
+};
+function contentTypeFor(pathname) {
+	const dot = pathname.lastIndexOf(".");
+	if (dot < 0) return "application/octet-stream";
+	return CONTENT_TYPES[pathname.slice(dot).toLowerCase()] ?? "application/octet-stream";
+}
+/** A request for a file rather than an app route: anything with a known extension. */
+function looksLikeAsset(pathname) {
+	const dot = pathname.lastIndexOf(".");
+	if (dot < 0) return false;
+	return pathname.slice(dot).toLowerCase() in CONTENT_TYPES;
+}
+/**
+* Resolve `pathname` inside `root`, or null if it escapes. Vite emits every
+* asset under a content-hashed name, so the only paths that ever reach here are
+* ones the app itself generated — but this server is reachable by anything that
+* can open a socket, and `..` in a URL is the oldest trick there is.
+*/
+function resolveWithinRoot(root, pathname) {
+	let decoded;
+	try {
+		decoded = decodeURIComponent(pathname);
+	} catch {
+		return null;
+	}
+	if (decoded.includes("\0")) return null;
+	const candidate = resolve(join(root, decoded));
+	const base = resolve(root);
+	if (candidate !== base && !candidate.startsWith(base + sep)) return null;
+	return candidate;
+}
+function sendHtml(req, res, status, html, cache) {
+	const body = Buffer.from(html, "utf8");
+	res.writeHead(status, {
+		"content-type": "text/html; charset=utf-8",
+		"content-length": body.byteLength,
+		"cache-control": cache,
+		"x-frame-options": "DENY",
+		"x-content-type-options": "nosniff",
+		"referrer-policy": "same-origin"
+	});
+	res.end(req.method === "HEAD" ? void 0 : body);
+}
+/**
+* Stream a file out of `root`. `immutable` is the caller's call, because it is a
+* promise about the URL, not the file: Vite's hashed assets can be cached
+* forever, but index.html must be revalidated every time or a deployed update
+* never reaches a browser that already has the old one.
+*/
+async function serveFile(req, res, filePath, options = {}) {
+	if (req.method !== "GET" && req.method !== "HEAD") return "method-not-allowed";
+	let size;
+	try {
+		const info = await stat(filePath);
+		if (!info.isFile()) return "not-found";
+		size = info.size;
+	} catch {
+		return "not-found";
+	}
+	res.writeHead(200, {
+		"content-type": contentTypeFor(filePath),
+		"content-length": size,
+		"cache-control": options.immutable ? "public, max-age=31536000, immutable" : "no-cache, must-revalidate",
+		"x-content-type-options": "nosniff"
+	});
+	if (req.method === "HEAD") {
+		res.end();
+		return "served";
+	}
+	await new Promise((resolvePromise) => {
+		const stream = createReadStream(filePath);
+		stream.on("error", () => {
+			res.destroy();
+			resolvePromise();
+		});
+		stream.on("end", () => resolvePromise());
+		stream.pipe(res);
+	});
+	return "served";
+}
+//#endregion
+//#region src/instance.ts
+/**
+* The dashboard comes from `@workerdeck/web`, which ships it prebuilt and
+* exports the path to it. Depending on the package rather than vendoring a copy
+* means one dashboard, versioned in lockstep with everything else.
+*
+* In a checkout that directory only exists once the app has been built — dev
+* never builds — so the miss is worth a real message rather than a stack trace
+* from the static host.
+*/
+function resolveWebRoot() {
+	if (existsSync(join(dashboardDir, "index.html"))) return dashboardDir;
+	throw new Error(`no dashboard build at ${dashboardDir}\n  in a checkout: pnpm --filter @workerdeck/web run build`);
+}
+/**
+* The Host-header gate for an unauthenticated instance. `allowedHosts` is null
+* whenever auth is on, and then this is the identity function — with a
+* credential in play a rebound origin holds no cookie and fails `authenticate`
+* anyway. Loopback *names* are what's checked, not the socket: the attacker in
+* this scenario controls DNS, so the connection genuinely arrives on 127.0.0.1;
+* what they cannot control is the name the victim's browser writes into Host.
+*/
+function createHostGuard(allowedHosts) {
+	if (allowedHosts === null) return () => true;
+	return (req) => {
+		const header = req.headers.host;
+		if (header === void 0) return true;
+		const hostname = hostnameOf(header);
+		if (hostname === "") return false;
+		return isLoopbackHostname(hostname) || allowedHosts.has(hostname);
+	};
+}
+/**
+* Everything outside `/v1`. Order matters: the auth endpoints first (they are
+* how a browser gets a session in the first place), then assets, which stay
+* ungated — they are the app's own code, hold no secrets, and gating them would
+* only mean the login page could not be styled by the app it gates. Documents
+* come last, and that is the single place the auth decision is made.
+*/
+function createFallback(auth, webRoot, hostAllowed) {
+	return async (req, res) => {
+		if (!hostAllowed(req)) {
+			res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
+			res.end("unrecognised Host header.\n\nThis instance runs without auth, so it only answers to loopback host names and the ones it was told to expect. Declare this name with --insecure-host <name> (which also lets it be bound without a key) or --allowed-host <name>, or set --auth-key.\n");
+			return;
+		}
+		if (await auth.handleAuthRequest(req, res)) return;
+		const pathname = new URL(req.url ?? "/", "http://internal").pathname;
+		if (looksLikeAsset(pathname)) {
+			const filePath = resolveWithinRoot(webRoot, pathname);
+			if (!filePath) {
+				res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+				res.end("bad request");
+				return;
+			}
+			const result = await serveFile(req, res, filePath, { immutable: pathname.startsWith("/assets/") });
+			if (result === "served") return;
+			if (result === "method-not-allowed") {
+				res.writeHead(405, { allow: "GET, HEAD" });
+				res.end();
+				return;
+			}
+			res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+			res.end("not found");
+			return;
+		}
+		if (req.method !== "GET" && req.method !== "HEAD") {
+			res.writeHead(405, { allow: "GET, HEAD" });
+			res.end();
+			return;
+		}
+		if (auth.enabled && !auth.hasValidSession(req)) {
+			sendHtml(req, res, 401, renderLoginPage(auth.loginPage(req)), "no-store");
+			return;
+		}
+		if (await serveFile(req, res, join(webRoot, "index.html"), { immutable: false }) !== "served") {
+			res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+			res.end("dashboard build is missing its entry document");
+		}
+	};
+}
+async function startInstance(config, options = {}) {
+	const webRoot = config.webRoot ?? resolveWebRoot();
+	const generated = config.generateAuthKey && !config.hostAuthenticates ? await materializeAuthKey(config.stateDir) : null;
+	const auth = createCliAuth(config.hostAuthenticates ? {
+		...config.auth,
+		secret: void 0
+	} : generated ? {
+		...config.auth,
+		secret: generated.key
+	} : config.auth);
+	if (config.allowedHosts === null && !config.hostAuthenticates && !auth.enabled) throw new Error("refusing to serve: the resolved config expects auth but no shared secret was materialized — this instance would be open while believing itself authenticated");
+	const hostAllowed = createHostGuard(config.allowedHosts);
+	const fallback = createFallback(auth, webRoot, hostAllowed);
+	const parking = { ...config.options.parking };
+	if (config.stateDir && !parking.store) parking.store = createFileSessionStore({
+		dir: join(config.stateDir, "parked"),
+		onError: (error, context) => {
+			process.stderr.write(`[workerdeck] parked-session store ${context.op} failed for ${context.path}: ${error instanceof Error ? error.message : String(error)}\n`);
+		}
+	});
+	const server = createWorkerServer({
+		...config.options,
+		checkCredentials: config.options.checkCredentials ?? true,
+		parking,
+		fallback,
+		authenticate: config.hostAuthenticates ? (req) => hostAllowed(req) ? config.options.authenticate(req) : null : (req) => hostAllowed(req) ? auth.authenticate(req) : null
+	});
+	const { port } = await server.listen(config.port, config.host);
+	const displayHost = config.host === "0.0.0.0" || config.host === "::" ? "localhost" : config.host;
+	const url = `http://${displayHost.includes(":") ? `[${displayHost}]` : displayHost}:${port}`;
+	let resolveClosed = () => {};
+	const closed = new Promise((r) => {
+		resolveClosed = r;
+	});
+	if (!options.quiet) {
+		const line = (text) => void process.stdout.write(`${text}\n`);
+		line("");
+		line(`  workerdeck  ${url}`);
+		if (config.hostAuthenticates) line("  auth: the config file supplies its own `authenticate`");
+		else if (generated?.source === "created") {
+			line(`  auth: generated key  ${generated.key}`);
+			line(`        stored in ${generated.path} — later starts reuse it without printing it`);
+		} else if (generated?.source === "ephemeral") {
+			line(`  auth: generated key  ${generated.key}`);
+			line("        ephemeral — no state dir to keep it, so the next start mints a new one");
+		} else if (generated?.source === "stored") line(`  auth: shared key from ${generated.path}`);
+		else if (auth.enabled) line("  auth: shared key — browsers sign in, services send a header");
+		else line("  NO AUTH — anyone who can reach this port gets a session");
+		line(config.stateDir ? `  parked sessions persist in ${join(config.stateDir, "parked")}` : "  parked sessions are in memory only — a restart drops them");
+		if (config.configPath) line(`  config ${config.configPath}`);
+		line("");
+	}
+	return {
+		server,
+		url,
+		port,
+		closed,
+		close: async () => {
+			await server.close();
+			resolveClosed();
+		}
+	};
+}
+//#endregion
+export { ConfigError as a, isLoopback as c, parseArgs as d, resolveInstanceConfig as f, renderLoginPage as i, isLoopbackHostname as l, materializeAuthKey as m, resolveWebRoot as n, defaultStateDir as o, createCliAuth as p, startInstance as r, hostnameOf as s, createHostGuard as t, loadConfigFile as u };
+
+//# sourceMappingURL=instance-kupxU5UD.mjs.map