workerdeck 0.0.0 → 0.7.0

package/build/instance-DbIqlX-e.mjs

@@ -0,0 +1,1586 @@
+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, createPrivateKey, randomBytes, sign, timingSafeEqual } from "node:crypto";
+import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { connect } from "node:http2";
+import { homedir } from "node:os";
+import { pathToFileURL } from "node:url";
+//#region src/apns/client.ts
+/**
+* The environment is per *device token*, not per deployment, and that is the
+* single most expensive thing to get wrong here: a build run from Xcode gets a
+* sandbox token, a TestFlight build gets a production one, and the two
+* namespaces do not overlap. Same key, same phone, different token — cross them
+* and Apple answers `BadDeviceToken`. So the app declares which environment it
+* registered in and the forwarder routes each token to its own host.
+*/
+const HOSTS = {
+	development: "https://api.sandbox.push.apple.com",
+	production: "https://api.push.apple.com"
+};
+/**
+* Apple rejects a provider token older than an hour, and rate-limits refreshing
+* one (`TooManyProviderTokenUpdates`) if you re-sign much more often than every
+* twenty minutes. Forty sits in the middle of that window with room for clock
+* skew at both ends — and re-signing per push, the obvious-looking thing, is
+* exactly what the rate limit exists to punish.
+*/
+const TOKEN_TTL_MS = 2400 * 1e3;
+const REQUEST_TIMEOUT_MS = 1e4;
+const base64url = (input) => Buffer.from(input).toString("base64url");
+/**
+* Load and sanity-check the auth key. Done once at startup rather than at the
+* first push, so a mistyped path is a launch error with a clear message instead
+* of a notification that silently never arrives.
+*/
+async function loadApnsKey(keyFile) {
+	let pem;
+	try {
+		pem = await readFile(keyFile, "utf8");
+	} catch (error) {
+		throw new Error(`apns: cannot read the auth key at ${keyFile}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	let key;
+	try {
+		key = createPrivateKey(pem);
+	} catch (error) {
+		throw new Error(`apns: ${keyFile} is not a private key (${error instanceof Error ? error.message : String(error)})`);
+	}
+	if (key.asymmetricKeyType !== "ec") throw new Error(`apns: ${keyFile} is a ${key.asymmetricKeyType ?? "unknown"} key, not EC — an APNs auth key is the .p8 downloaded from Keys in the developer portal, not a certificate`);
+	return key;
+}
+/**
+* A cached provider JWT. The signature is over `{alg:ES256,kid}` + `{iss,iat}`,
+* and JWS wants the raw `r||s` pair — `sign()` produces a DER SEQUENCE unless
+* told otherwise, which Apple rejects with a bare 403 and no explanation.
+*/
+function createProviderToken(key, keyId, teamId) {
+	let cached = null;
+	return {
+		get(now = Date.now()) {
+			if (cached !== null && now - cached.issuedAt < TOKEN_TTL_MS) return cached.token;
+			const signingInput = `${base64url(JSON.stringify({
+				alg: "ES256",
+				kid: keyId
+			}))}.${base64url(JSON.stringify({
+				iss: teamId,
+				iat: Math.floor(now / 1e3)
+			}))}`;
+			const token = `${signingInput}.${base64url(sign("sha256", Buffer.from(signingInput), {
+				key,
+				dsaEncoding: "ieee-p1363"
+			}))}`;
+			cached = {
+				token,
+				issuedAt: now
+			};
+			return token;
+		},
+		invalidate() {
+			cached = null;
+		}
+	};
+}
+/**
+* One long-lived HTTP/2 session per environment, reconnected on demand. APNs
+* sends GOAWAY routinely (it rebalances connections), so a dead session is a
+* normal event and not an error worth surfacing — the next push simply dials
+* again.
+*/
+function createSessionPool(hosts) {
+	const sessions = /* @__PURE__ */ new Map();
+	const failures = /* @__PURE__ */ new Map();
+	const drop = (environment, session) => {
+		if (sessions.get(environment) === session) sessions.delete(environment);
+	};
+	return {
+		get(environment) {
+			const existing = sessions.get(environment);
+			if (existing !== void 0 && !existing.closed && !existing.destroyed) return existing;
+			const session = connect(hosts[environment]);
+			sessions.set(environment, session);
+			failures.delete(environment);
+			session.on("error", (error) => {
+				failures.set(environment, `${error.code ?? "error"}: ${error.message}`);
+				drop(environment, session);
+			});
+			session.on("goaway", (code, _lastStreamId, data) => {
+				const detail = data !== void 0 && data.length > 0 ? `: ${data.toString("utf8").slice(0, 200)}` : "";
+				failures.set(environment, `GOAWAY ${code}${detail}`);
+				drop(environment, session);
+			});
+			session.on("close", () => drop(environment, session));
+			session.setTimeout(5 * 6e4, () => session.close());
+			return session;
+		},
+		lastFailure: (environment) => failures.get(environment),
+		close() {
+			for (const session of sessions.values()) session.close();
+			sessions.clear();
+		}
+	};
+}
+function createApnsClient(config, key, options = {}) {
+	const providerToken = createProviderToken(key, config.keyId, config.teamId);
+	const pool = createSessionPool(options.hosts ?? HOSTS);
+	const post = (request, jwt) => new Promise((resolve) => {
+		const body = Buffer.from(JSON.stringify(request.payload));
+		let stream;
+		try {
+			stream = pool.get(request.environment).request({
+				":method": "POST",
+				":path": `/3/device/${request.deviceToken}`,
+				authorization: `bearer ${jwt}`,
+				"apns-topic": config.topic,
+				"apns-push-type": "alert",
+				"apns-priority": String(request.priority ?? 10),
+				"apns-expiration": String(request.expiration ?? 0),
+				"content-length": String(body.byteLength),
+				...request.collapseId === void 0 ? {} : { "apns-collapse-id": request.collapseId }
+			});
+		} catch (error) {
+			resolve({
+				ok: false,
+				status: 0,
+				reason: error instanceof Error ? error.message : String(error),
+				unregistered: false
+			});
+			return;
+		}
+		let status = 0;
+		let apnsId;
+		const chunks = [];
+		let settled = false;
+		const settle = (result) => {
+			if (settled) return;
+			settled = true;
+			resolve(result);
+		};
+		stream.setTimeout(REQUEST_TIMEOUT_MS, () => {
+			stream.close();
+			settle({
+				ok: false,
+				status: 0,
+				reason: "Timeout",
+				unregistered: false
+			});
+		});
+		stream.on("response", (headers) => {
+			status = Number(headers[":status"] ?? 0);
+			const id = headers["apns-id"];
+			apnsId = typeof id === "string" ? id : void 0;
+		});
+		stream.on("data", (chunk) => chunks.push(chunk));
+		stream.on("error", (error) => {
+			const cause = pool.lastFailure(request.environment);
+			settle({
+				ok: false,
+				status,
+				reason: cause !== void 0 ? `${cause} (stream: ${error.message})` : error.message,
+				unregistered: false
+			});
+		});
+		stream.on("end", () => {
+			if (status === 200) {
+				settle({
+					ok: true,
+					apnsId
+				});
+				return;
+			}
+			let reason = `HTTP ${status}`;
+			try {
+				const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+				if (typeof parsed.reason === "string") reason = parsed.reason;
+			} catch {}
+			settle({
+				ok: false,
+				status,
+				reason,
+				unregistered: reason === "Unregistered" || reason === "BadDeviceToken"
+			});
+		});
+		stream.end(body);
+	});
+	return {
+		async send(request) {
+			const first = await post(request, providerToken.get());
+			if (!first.ok && first.reason === "ExpiredProviderToken") {
+				providerToken.invalidate();
+				return post(request, providerToken.get());
+			}
+			return first;
+		},
+		close: pool.close
+	};
+}
+//#endregion
+//#region src/apns/devices.ts
+const FILENAME = "apns-devices.json";
+/** Apple's tokens are 64 hex chars today. The upper bound is generous because
+* Apple has reserved the right to grow them; the lower one just rejects junk. */
+const TOKEN_PATTERN = /^[0-9a-fA-F]{32,200}$/;
+const MAX_BODY_BYTES = 4096;
+const isEnvironment = (value) => value === "development" || value === "production";
+/**
+* `dir` null keeps the registry in memory: a restart then forgets every token,
+* which is survivable because the app re-registers on launch, but it does mean
+* an instance with no state dir goes quiet until each phone is next opened.
+*/
+async function createDeviceRegistry(options) {
+	const path = options.dir === null ? null : join(options.dir, FILENAME);
+	const devices = /* @__PURE__ */ new Map();
+	if (path !== null) try {
+		const parsed = JSON.parse(await readFile(path, "utf8"));
+		for (const record of parsed.devices ?? []) if (typeof record?.token === "string" && isEnvironment(record.environment)) devices.set(record.token, record);
+	} catch {}
+	const persist = async () => {
+		if (path === null) return;
+		try {
+			await mkdir(options.dir, {
+				recursive: true,
+				mode: 448
+			});
+			await writeFile(path, `${JSON.stringify({ devices: [...devices.values()] }, null, 2)}\n`, { mode: 384 });
+			await chmod(path, 384);
+		} catch (error) {
+			options.onError?.(error, {
+				op: "write",
+				path
+			});
+		}
+	};
+	return {
+		list: () => [...devices.values()],
+		async register(record) {
+			const existing = devices.get(record.token);
+			devices.set(record.token, {
+				...record,
+				updatedAt: Date.now()
+			});
+			if (existing !== void 0 && existing.environment === record.environment && existing.hostId === record.hostId) return;
+			await persist();
+		},
+		async remove(token) {
+			if (!devices.delete(token)) return;
+			await persist();
+		}
+	};
+}
+const respond = (res, status, body) => {
+	res.writeHead(status, {
+		"content-type": "application/json",
+		"cache-control": "no-store"
+	}).end(JSON.stringify(body));
+};
+const readBody = (req) => 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 > MAX_BODY_BYTES) {
+			finish(null);
+			return;
+		}
+		chunks.push(chunk);
+	});
+	req.on("end", () => finish(Buffer.concat(chunks).toString("utf8")));
+	req.on("error", () => finish(null));
+});
+/**
+* `POST /apns/devices` to register a token, `DELETE /apns/devices` to drop one.
+* Returns true when it consumed the request.
+*
+* Deliberately outside `/v1`: this is the forwarder's own surface, not part of
+* the protocol `packages/protocol` defines, and a client that finds a 404 here
+* has simply reached a gateway running without push configured.
+*
+* DELETE exists so removing a gateway from the app can stop its pushes. Without
+* it a forgotten server keeps buzzing a phone that no longer has any way to act
+* on what it says.
+*/
+function createDeviceRoute(registry, authenticate) {
+	return async (req, res) => {
+		let pathname;
+		try {
+			pathname = new URL(req.url ?? "/", "http://internal").pathname;
+		} catch {
+			return false;
+		}
+		if (pathname !== "/apns/devices") return false;
+		if (req.method !== "POST" && req.method !== "DELETE") {
+			res.writeHead(405, { allow: "POST, DELETE" }).end();
+			return true;
+		}
+		if (authenticate(req) === null) {
+			respond(res, 401, { error: "unauthorized" });
+			return true;
+		}
+		const raw = await readBody(req);
+		if (raw === null) {
+			respond(res, 413, { error: "body too large" });
+			res.once("finish", () => req.destroy());
+			return true;
+		}
+		let body;
+		try {
+			body = JSON.parse(raw);
+		} catch {
+			respond(res, 400, { error: "invalid JSON body" });
+			return true;
+		}
+		const token = body.token;
+		if (typeof token !== "string" || !TOKEN_PATTERN.test(token)) {
+			respond(res, 400, { error: "token must be a hex APNs device token" });
+			return true;
+		}
+		if (req.method === "DELETE") {
+			await registry.remove(token);
+			res.writeHead(204).end();
+			return true;
+		}
+		if (!isEnvironment(body.environment)) {
+			respond(res, 400, { error: "environment must be 'development' or 'production'" });
+			return true;
+		}
+		const optionalString = (value) => typeof value === "string" && value.length > 0 && value.length <= 200 ? value : void 0;
+		await registry.register({
+			token,
+			environment: body.environment,
+			hostId: optionalString(body.hostId),
+			bundleId: optionalString(body.bundleId),
+			platform: optionalString(body.platform)
+		});
+		respond(res, 200, {
+			registered: true,
+			environment: body.environment
+		});
+		return true;
+	};
+}
+//#endregion
+//#region src/apns/forwarder.ts
+/**
+* Turns the server's session notifications into APNs pushes.
+*
+* The architectural point, restated because it is easy to erode: session
+* webhooks are the primitive and this is one consumer of them. It hooks
+* `notifications.onNotification` in-process — same process as the gateway, so
+* there is no HTTP hop — but nothing about the server knows that, and the same
+* events can just as well drive Slack or a custom relay. Push credentials live
+* here and nowhere in `packages/server`.
+*/
+/** APNs caps a payload at 4 KB. Staying well under leaves room for the alert
+* dictionary to grow without anyone rediscovering the limit the hard way. */
+const MAX_PAYLOAD_BYTES = 3800;
+const BODY_LIMIT = 300;
+/** Category identifiers are wire contract with the app: it registers the
+* Approve/Deny actions under this exact string, and a mismatch means a
+* notification that arrives with no buttons on it. */
+const CATEGORY = {
+	permission: "PERMISSION_REQUEST",
+	event: "SESSION_EVENT"
+};
+const label = (session) => {
+	const title = session.title?.trim();
+	if (title !== void 0 && title !== "") return title;
+	const leaf = session.cwd.split("/").filter(Boolean).at(-1);
+	return leaf !== void 0 && leaf !== "" ? leaf : session.id;
+};
+const oneLine = (text, limit = BODY_LIMIT) => {
+	const flat = (text ?? "").replace(/\s+/g, " ").trim();
+	return flat.length <= limit ? flat : `${flat.slice(0, limit - 1)}…`;
+};
+/** A collapse id is capped at 64 bytes and a session id has no such bound, so
+* hash rather than truncate — two sessions sharing a prefix must not collapse
+* into each other. */
+const collapseKey = (sessionId) => createHash("sha256").update(sessionId).digest("base64url").slice(0, 32);
+const titleFor = (notification, name) => {
+	switch (notification.type) {
+		case "permission_requested": return `Approval needed — ${name}`;
+		case "turn_completed": return notification.result?.isError === true ? `Turn failed — ${name}` : name;
+		case "session_error": return `Session error — ${name}`;
+		case "session_closed": return `Session ended — ${name}`;
+		default: return name;
+	}
+};
+const bodyFor = (notification) => {
+	const preview = oneLine(notification.preview);
+	if (preview !== "") return preview;
+	switch (notification.type) {
+		case "permission_requested": return "The agent is waiting for your approval.";
+		case "turn_completed": return "The turn finished.";
+		case "session_closed": return `Closed by the ${notification.reason ?? "server"}.`;
+		default: return "Something needs your attention.";
+	}
+};
+/**
+* Build the push for one notification.
+*
+* The payload carries routing and nothing else — `sessionId` to deep-link,
+* `requestId` because a lock-screen Approve has nothing to POST to without it,
+* and `hostId` so a client with two gateways knows which one this came from.
+* Everything else the app fetches over REST the moment it opens; a transcript
+* has no business in a 4 KB envelope.
+*/
+function buildPush(notification, hostId) {
+	const permission = notification.type === "permission_requested";
+	const name = label(notification.session);
+	let body = bodyFor(notification);
+	const build = (text) => ({
+		aps: {
+			alert: {
+				title: titleFor(notification, name),
+				body: text
+			},
+			sound: "default",
+			category: permission ? CATEGORY.permission : CATEGORY.event,
+			"thread-id": notification.sessionId
+		},
+		type: notification.type,
+		sessionId: notification.sessionId,
+		seq: notification.seq,
+		...hostId === void 0 ? {} : { hostId },
+		...notification.request === void 0 ? {} : { requestId: notification.request.id }
+	});
+	let payload = build(body);
+	while (Buffer.byteLength(JSON.stringify(payload)) > MAX_PAYLOAD_BYTES && body.length > 16) {
+		body = oneLine(body, Math.floor(body.length / 2));
+		payload = build(body);
+	}
+	return {
+		payload,
+		priority: permission || notification.type === "session_error" ? 10 : 5,
+		expiration: permission && notification.request?.expiresAt !== void 0 ? Math.floor(notification.request.expiresAt / 1e3) : Math.floor(Date.now() / 1e3) + 3600,
+		...notification.type === "turn_completed" ? { collapseId: `t:${collapseKey(notification.sessionId)}` } : {}
+	};
+}
+async function createApnsForwarder(options) {
+	const warn = options.warn ?? ((message) => process.stderr.write(`[workerdeck] apns: ${message}\n`));
+	const key = await loadApnsKey(options.config.keyFile);
+	const client = createApnsClient(options.config, key);
+	const registry = await createDeviceRegistry({
+		dir: options.stateDir,
+		onError: (error, context) => warn(`device registry ${context.op} failed for ${context.path}: ${error instanceof Error ? error.message : String(error)}`)
+	});
+	const handleRequest = createDeviceRoute(registry, options.authenticate);
+	const fallbackEnvironment = options.config.production === false ? "development" : "production";
+	/** Per-session delivery chain, so a session's pushes arrive in the order the
+	* events happened — which matters precisely because `turn_completed` collapses
+	* and an out-of-order pair would leave the older text on screen. */
+	const chains = /* @__PURE__ */ new Map();
+	const deliver = async (notification) => {
+		const devices = registry.list();
+		if (devices.length === 0) return;
+		await Promise.all(devices.map(async (device) => {
+			const push = buildPush(notification, device.hostId);
+			const result = await client.send({
+				...push,
+				deviceToken: device.token,
+				environment: device.environment ?? fallbackEnvironment
+			});
+			if (result.ok) return;
+			if (result.unregistered) {
+				await registry.remove(device.token);
+				return;
+			}
+			warn(`push to ${device.token.slice(0, 8)}… failed: ${result.reason} (${result.status})`);
+		}));
+	};
+	return {
+		onNotification(notification) {
+			const next = (chains.get(notification.sessionId) ?? Promise.resolve()).then(() => deliver(notification).catch((error) => {
+				warn(error instanceof Error ? error.message : String(error));
+			}));
+			chains.set(notification.sessionId, next);
+			next.then(() => {
+				if (chains.get(notification.sessionId) === next) chains.delete(notification.sessionId);
+			});
+		},
+		handleRequest,
+		deviceCount: () => registry.list().length,
+		close: client.close
+	};
+}
+//#endregion
+//#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: [],
+		fsRoots: [],
+		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 "--fs-root":
+				flags.fsRoots.push(resolve(next(i, arg)));
+				i++;
+				break;
+			case "--fs-write":
+				flags.fsWrite = true;
+				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 envFsRoots = env.WORKERDECK_FS_ROOTS?.split(":").filter(Boolean).map((p) => resolve(cwd, p));
+	const fsRoots = flags.fsRoots.length ? flags.fsRoots : envFsRoots;
+	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, apns: _ap, ...serverOptions } = loaded.options;
+	const options = { ...serverOptions };
+	if (cwdRoots?.length) options.allowedCwdRoots = cwdRoots;
+	if (fsRoots?.length || flags.fsWrite) options.hostFiles = {
+		...loaded.options.hostFiles,
+		...fsRoots?.length ? { roots: fsRoots } : {},
+		...flags.fsWrite ? { write: true } : {}
+	};
+	if (flags.profiles.length) options.profiles = flags.profiles;
+	return {
+		port,
+		host,
+		authKey,
+		auth,
+		stateDir,
+		configPath: loaded.path,
+		hostAuthenticates,
+		generateAuthKey,
+		allowedHosts,
+		webRoot: loaded.options.webRoot,
+		apns: resolveApns(loaded),
+		open: flags.open ?? false,
+		options
+	};
+}
+/**
+* A relative `keyFile` resolves against the config file's own directory, not the
+* cwd — the same convention `defaultStateDir` uses, and the one that makes a
+* deployment directory self-contained. Missing required fields throw here rather
+* than at the first push, since a half-configured forwarder is a notification
+* that silently never arrives.
+*/
+function resolveApns(loaded) {
+	const apns = loaded.options.apns;
+	if (!apns) return void 0;
+	for (const field of [
+		"keyFile",
+		"keyId",
+		"teamId",
+		"topic"
+	]) if (typeof apns[field] !== "string" || apns[field] === "") throw new ConfigError(`apns.${field} is required when apns is configured`);
+	const base = loaded.path ? dirname(loaded.path) : process.cwd();
+	return {
+		...apns,
+		keyFile: resolve(base, apns.keyFile)
+	};
+}
+//#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.
+*
+* The APNs device route sits between auth and assets: it does its own
+* authentication (header only — it is never called by a browser), and it must
+* not fall through to the SPA's catch-all, which would answer a failed
+* registration with a 200 and an HTML document.
+*/
+function createFallback(auth, webRoot, hostAllowed, apnsRoute) {
+	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;
+		if (apnsRoute !== void 0 && await apnsRoute(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 apns = config.apns === void 0 ? void 0 : await createApnsForwarder({
+		config: config.apns,
+		stateDir: config.stateDir,
+		authenticate: (req) => hostAllowed(req) ? auth.authenticate(req) : null
+	});
+	const fallback = createFallback(auth, webRoot, hostAllowed, apns?.handleRequest);
+	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,
+		notifications: apns === void 0 ? config.options.notifications : {
+			...config.options.notifications,
+			onNotification: (notification) => {
+				config.options.notifications?.onNotification?.(notification);
+				apns.onNotification(notification);
+			}
+		},
+		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 (apns) {
+			const count = apns.deviceCount();
+			line(`  push: APNs forwarder on ${config.apns?.topic} — ${count === 0 ? "no devices registered yet" : `${count} device(s)`}`);
+		}
+		if (config.configPath) line(`  config ${config.configPath}`);
+		line("");
+	}
+	return {
+		server,
+		url,
+		port,
+		closed,
+		close: async () => {
+			await server.close();
+			apns?.close();
+			resolveClosed();
+		}
+	};
+}
+//#endregion
+export { createDeviceRegistry as _, ConfigError as a, loadApnsKey as b, isLoopback as c, parseArgs as d, resolveInstanceConfig as f, createApnsForwarder as g, buildPush as h, 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, createDeviceRoute as v, createApnsClient as y };
+
+//# sourceMappingURL=instance-DbIqlX-e.mjs.map