moshcode 0.24.0

package/src/console.mjs

@@ -0,0 +1,244 @@
+// `moshcode console` — a browser terminal on this box, gated by moshcode login.
+//
+// Rather than reimplement a terminal in the session mirror (xterm.js, keystroke
+// relay, cursor addressing), run ttyd — which is already a terminal — and put an
+// authenticating reverse proxy in front of it. You get arrow keys, history, and
+// full-screen TUIs because it is a real pty on the other end, not a log view.
+//
+// WHY THE GATEWAY RUNS HERE, not in apps/pwa: the hosted app is on Railway and
+// the shell you want is on this machine. A proxy inside apps/pwa would have to
+// reach back across the internet to a port on the dev box, which means exposing
+// that port — the exact thing worth avoiding. So the box serves its own gateway
+// and asks app.moshcode.sh only "is this token yours?".
+//
+// SECURITY: everything behind this is a shell. ttyd itself MUST stay bound to
+// loopback (`ttyd -i 127.0.0.1`); the only way in is a valid moshcode token,
+// which is exchanged once for a short-lived HMAC cookie. Binding the gateway to
+// a tailnet address instead of 0.0.0.0 is strictly better and is what the docs
+// recommend.
+import http from "node:http";
+import net from "node:net";
+import crypto from "node:crypto";
+
+import { loadCreds } from "./auth.mjs";
+
+export const DEFAULT_TTYD = "127.0.0.1:7681";
+const COOKIE = "moshcode_console";
+const SESSION_TTL_MS = 12 * 60 * 60 * 1000; // re-auth twice a day
+
+/** Split "host:port" into the pieces net/http want. Defaults to ttyd's port. */
+export function parseTarget(target = DEFAULT_TTYD) {
+  const raw = String(target || DEFAULT_TTYD).trim() || DEFAULT_TTYD;
+  const url = new URL(raw.includes("://") ? raw : `http://${raw}`);
+  const host = url.hostname.replace(/^\[|\]$/g, "");
+  return { host, port: Number(url.port || 7681) };
+}
+
+export function parseConsolePort(input) {
+  const raw = String(input ?? "").trim();
+  if (!/^\d+$/.test(raw)) return null;
+  const port = Number(raw);
+  return Number.isSafeInteger(port) && port >= 1 && port <= 65535 ? port : null;
+}
+
+const targetHostHeader = ({ host, port }) =>
+  `${host.includes(":") ? `[${host}]` : host}:${port}`;
+
+/** Cookies from a raw header — cookie-parser is an express thing and the
+ *  websocket upgrade never reaches express. */
+export function parseCookies(header = "") {
+  const out = {};
+  for (const part of String(header).split(";")) {
+    const eq = part.indexOf("=");
+    if (eq < 0) continue;
+    const k = part.slice(0, eq).trim();
+    if (!k) continue;
+    const raw = part.slice(eq + 1).trim();
+    // A cookie value is whatever the client chose to send, and decodeURIComponent
+    // throws on a stray "%". This runs before any auth check, in an async request
+    // handler and in an `upgrade` listener — a throw in either takes the whole
+    // gateway down, so an unauthenticated client must not be able to cause one.
+    // Falling back to the raw value is what the `cookie` package does too.
+    try { out[k] = decodeURIComponent(raw); } catch { out[k] = raw; }
+  }
+  return out;
+}
+
+/**
+ * A signed, expiring session value. HMAC over the payload with a per-process
+ * secret, so a cookie cannot be forged and does not survive a restart.
+ */
+export function mintCookie(secret, { user = "", now = Date.now(), ttlMs = SESSION_TTL_MS } = {}) {
+  // base64url, not percent-encoding: the field is dot-delimited and an email
+  // ("a@profullstack.com") is full of dots that encodeURIComponent leaves alone.
+  const payload = `${Buffer.from(String(user)).toString("base64url")}.${now + ttlMs}`;
+  const mac = crypto.createHmac("sha256", secret).update(payload).digest("base64url");
+  return `${payload}.${mac}`;
+}
+
+/** Verify a cookie minted above. Returns the user, or null when invalid/expired. */
+export function readCookie(secret, value, now = Date.now()) {
+  const parts = String(value || "").split(".");
+  if (parts.length !== 3) return null;
+  const [user, expiry, mac] = parts;
+  const payload = `${user}.${expiry}`;
+  const expected = crypto.createHmac("sha256", secret).update(payload).digest("base64url");
+  // timingSafeEqual throws on length mismatch, so compare lengths first.
+  const a = Buffer.from(mac);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return null;
+  if (!Number(expiry) || Number(expiry) < now) return null;
+  return Buffer.from(user, "base64url").toString("utf8");
+}
+
+/**
+ * Ask the moshcode app whether this token is a real login. The gateway trusts
+ * the app for identity rather than keeping its own user list.
+ */
+export async function verifyToken(api, token, fetchImpl = fetch) {
+  if (!token) return null;
+  try {
+    const r = await fetchImpl(`${api.replace(/\/+$/, "")}/api/me`, {
+      headers: { authorization: `Bearer ${token}` },
+    });
+    if (!r.ok) return null;
+    const body = await r.json().catch(() => ({}));
+    return body?.user?.email || body?.email || body?.user?.id || "authenticated";
+  } catch {
+    return null;
+  }
+}
+
+const DENIED = `<!doctype html><meta charset="utf-8"><title>moshcode console</title>
+<body style="background:#070806;color:#edf2e4;font-family:monospace;padding:14vh 24px;text-align:center">
+<h1 style="color:#a6ff1a">🔒 not logged in</h1>
+<p>this terminal is gated by your moshcode login.</p>
+<p style="color:#8a8f80">run <code>moshcode console</code> on a machine where you have run <code>moshcode login</code>.</p>
+</body>`;
+
+/** Copy a client request through to ttyd and stream the answer back. */
+function proxyHttp(req, res, target) {
+  const upstream = http.request(
+    { host: target.host, port: target.port, method: req.method, path: req.url, headers: { ...req.headers, host: targetHostHeader(target) } },
+    (up) => { res.writeHead(up.statusCode || 502, up.headers); up.pipe(res); },
+  );
+  upstream.on("error", () => {
+    if (!res.headersSent) res.writeHead(502, { "content-type": "text/plain" });
+    res.end("console backend unreachable — is ttyd running?");
+  });
+  req.pipe(upstream);
+}
+
+/**
+ * Hand the websocket over at the socket level. ttyd's terminal is a websocket,
+ * and an upgrade cannot be proxied with http.request — we replay the handshake
+ * onto a raw connection and then just let the two sockets talk.
+ */
+function proxyUpgrade(req, socket, head, target) {
+  const upstream = net.connect(target.port, target.host, () => {
+    const lines = [`${req.method} ${req.url} HTTP/1.1`];
+    for (const [k, v] of Object.entries(req.headers)) {
+      for (const one of Array.isArray(v) ? v : [v]) lines.push(`${k}: ${one}`);
+    }
+    upstream.write(`${lines.join("\r\n")}\r\n\r\n`);
+    if (head?.length) upstream.write(head);
+    socket.pipe(upstream);
+    upstream.pipe(socket);
+  });
+  const bail = () => { try { socket.destroy(); } catch { /* already gone */ } };
+  upstream.on("error", bail);
+  socket.on("error", () => { try { upstream.destroy(); } catch { /* already gone */ } });
+}
+
+/**
+ * The gateway. `?token=<moshcode token>` authenticates once and is swapped for
+ * the cookie, so the token never has to appear again (or sit in browser history
+ * for the rest of the session — the handshake redirects it away).
+ */
+export function createConsoleServer({
+  ttyd = DEFAULT_TTYD,
+  api = "https://app.moshcode.sh",
+  secret = crypto.randomBytes(32).toString("hex"),
+  verify = verifyToken,
+} = {}) {
+  const target = parseTarget(ttyd);
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, "http://localhost");
+    const cookies = parseCookies(req.headers.cookie);
+    if (readCookie(secret, cookies[COOKIE])) return proxyHttp(req, res, target);
+
+    const token = url.searchParams.get("token");
+    const user = token ? await verify(api, token) : null;
+    if (!user) {
+      res.writeHead(401, { "content-type": "text/html" });
+      return res.end(DENIED);
+    }
+    // Drop the token from the URL so it stops travelling with every request.
+    url.searchParams.delete("token");
+    res.writeHead(302, {
+      "set-cookie": `${COOKIE}=${mintCookie(secret, { user })}; HttpOnly; SameSite=Lax; Path=/`,
+      location: `${url.pathname}${url.search}`,
+    });
+    res.end();
+  });
+
+  server.on("upgrade", (req, socket, head) => {
+    // The websocket carries the terminal itself; an unauthenticated upgrade
+    // would hand out a shell regardless of how well the page is guarded.
+    if (!readCookie(secret, parseCookies(req.headers.cookie)[COOKIE])) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+      return socket.destroy();
+    }
+    proxyUpgrade(req, socket, head, target);
+  });
+
+  return server;
+}
+
+/** The URL to hand a browser: this box's gateway, carrying a one-time token. */
+export function consoleUrl(base, token) {
+  const u = new URL(String(base));
+  if (token) u.searchParams.set("token", token);
+  return u.toString();
+}
+
+/** `moshcode console` — print (and optionally serve) the browser terminal. */
+export async function consoleCommand(args = []) {
+  const serve = args.includes("serve");
+  const flag = (name, fallback) => {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
+  };
+  const creds = loadCreds();
+  const api = creds?.api || "https://app.moshcode.sh";
+
+  if (!serve) {
+    const base = flag("url", process.env.MOSHCODE_CONSOLE_URL);
+    if (!base) {
+      console.error("usage: moshcode console serve [--port 7682] [--ttyd 127.0.0.1:7681] [--bind 127.0.0.1]\n"
+        + "       moshcode console --url https://dev.example.com/   (open an existing gateway)");
+      return 1;
+    }
+    if (!creds?.token) { console.error("not logged in — run: moshcode login"); return 1; }
+    console.log(consoleUrl(base, creds.token));
+    return 0;
+  }
+
+  const rawPort = flag("port", "7682");
+  const port = parseConsolePort(rawPort);
+  if (port === null) {
+    console.error(`--port needs a decimal integer from 1 to 65535, got ${JSON.stringify(rawPort)}`);
+    return 1;
+  }
+  const bind = flag("bind", "127.0.0.1");
+  const ttyd = flag("ttyd", DEFAULT_TTYD);
+  const server = createConsoleServer({ ttyd, api });
+  await new Promise((resolve) => server.listen(port, bind, resolve));
+  console.log(`🖥  moshcode console gateway on http://${bind}:${port} → ttyd ${ttyd}`);
+  console.log(`   auth: moshcode login tokens verified against ${api}`);
+  if (bind === "0.0.0.0") {
+    console.log("   ! bound to every interface — prefer a tailnet address or a reverse proxy with TLS");
+  }
+  return new Promise(() => {}); // serve until killed
+}

package/src/dns-system.mjs

@@ -0,0 +1,404 @@
+// Routing Moshpit TLDs to the local bridge, on whatever OS this is.
+//
+// Every supported system has a way to send *one suffix* to a different
+// nameserver without becoming the resolver for everything else, and this uses
+// that mechanism on each rather than the blunt one. Replacing the machine's
+// nameserver would mean every lookup on the box depends on this bridge being
+// alive; routing only `.moshpit` and friends means the worst failure is that
+// Moshpit names stop working, which is exactly the blast radius it should have.
+//
+//   macOS    /etc/resolver/<tld>       one file per TLD, read per query
+//   Linux    systemd-resolved drop-in  DNS= + Domains=~tld routing-only domains
+//   Linux    dnsmasq                   server=/tld/host#port
+//   Windows  NRPT rule per namespace   Add-DnsClientNrptRule -Namespace .tld
+//
+// The functions here return a *plan* — a list of steps as data — instead of
+// running anything. Everything that edits system DNS wants to be inspectable
+// before it runs (`--dry-run` prints the plan verbatim), and a plan is testable
+// on any OS without touching that OS's resolver.
+
+/**
+ * Windows NRPT rules name a server but have nowhere to put a port, so on
+ * Windows the bridge has to be on 53 or the rule cannot point at it. macOS and
+ * systemd-resolved both accept a port, which is why the default elsewhere is an
+ * unprivileged one.
+ */
+export const WINDOWS_REQUIRED_PORT = 53;
+
+export function detectPlatform(platform = process.platform) {
+  if (platform === "darwin") return "macos";
+  if (platform === "win32") return "windows";
+  if (platform === "linux") return "linux";
+  return null;
+}
+
+/** A step is either a file to write, a file to remove, or a command to run. */
+const write = (path, content, why) => ({ kind: "write", path, content, why });
+const remove = (path, why) => ({ kind: "remove", path, why });
+const run = (command, args, why) => ({ kind: "run", command, args, why });
+
+/**
+ * What it would take to route `tlds` at `host:port` on this platform.
+ *
+ * `linuxBackend` picks between the two Linux mechanisms. systemd-resolved is
+ * the default because it is what Ubuntu ships; dnsmasq is for the machines that
+ * do not run it.
+ */
+export function enablePlan({
+  platform,
+  tlds,
+  host = "127.0.0.1",
+  port = 5354,
+  linuxBackend = "systemd-resolved",
+  // Catch-all routing is opt-in and conditional, never assumed. Sending every
+  // lookup on the machine to the bridge is only safe if the bridge can forward
+  // the ones that are not ours — so the caller passes the upstreams it found,
+  // and an empty list keeps the per-ending routing that cannot break anything
+  // beyond Moshpit names. Getting this backwards takes the whole box offline.
+  upstreams = [],
+}) {
+  const catchAll = Array.isArray(upstreams) && upstreams.length > 0;
+  const clean = [...new Set((tlds || []).map((t) => String(t).replace(/^\.+/, "").toLowerCase()).filter(Boolean))];
+  if (!clean.length) throw new Error("no TLDs to route");
+
+  if (platform === "macos") {
+    // One file per TLD. macOS reads /etc/resolver/<name> per query, so there is
+    // nothing to restart and nothing else on the machine is affected.
+    return {
+      platform,
+      elevated: true,
+      port,
+      steps: clean.map((tld) =>
+        write(
+          `/etc/resolver/${tld}`,
+          `# Written by \`moshcode dns enable\`.\nnameserver ${host}\nport ${port}\n`,
+          `send .${tld} to the local bridge`,
+        ),
+      ),
+      notes: ["macOS reads /etc/resolver per query — nothing to restart."],
+    };
+  }
+
+  if (platform === "linux" && linuxBackend === "dnsmasq") {
+    return {
+      platform,
+      elevated: true,
+      port,
+      steps: [
+        write(
+          "/etc/dnsmasq.d/moshpit.conf",
+          catchAll
+            ? [
+              "# Written by `moshcode dns enable`.",
+              "# no-resolv so dnsmasq does not also inherit upstreams that point back here.",
+              "no-resolv",
+              `server=${host}#${port}`,
+              "",
+            ].join("\n")
+            : ["# Written by `moshcode dns enable`.", ...clean.map((t) => `server=/${t}/${host}#${port}`), ""].join("\n"),
+          catchAll ? "send every lookup to the bridge, which forwards what is not ours" : "route the Moshpit TLDs",
+        ),
+        run("systemctl", ["restart", "dnsmasq"], "dnsmasq reads its config at start"),
+      ],
+      notes: [],
+    };
+  }
+
+  if (platform === "linux") {
+    // `~tld` is a routing-only domain: it sends that suffix here without making
+    // this the default resolver for anything else.
+    return {
+      platform,
+      elevated: true,
+      port,
+      steps: [
+        write(
+          "/etc/systemd/resolved.conf.d/moshpit.conf",
+          catchAll
+            ? [
+              "# Written by `moshcode dns enable`. Sends every lookup to the local",
+              "# bridge, which answers claimed Moshpit endings and forwards the rest",
+              "# upstream untouched.",
+              "#",
+              "# Naming each ending instead does not survive the registry growing:",
+              "# systemd-resolved caps how many search domains it accepts and drops",
+              "# the remainder with no error a caller can see.",
+              "[Resolve]",
+              `DNS=${host}:${port}`,
+              "Domains=~.",
+              "",
+            ].join("\n")
+            : [
+              "# Written by `moshcode dns enable`. Routes Moshpit TLDs to the local",
+              "# bridge; every other name keeps using your normal resolver.",
+              "[Resolve]",
+              `DNS=${host}:${port}`,
+              `Domains=${clean.map((t) => `~${t}`).join(" ")}`,
+              "",
+            ].join("\n"),
+          catchAll
+            ? "send every lookup to the bridge, which forwards what is not ours"
+            : "route the Moshpit TLDs, and nothing else",
+        ),
+        run("systemctl", ["restart", "systemd-resolved"], "drop-ins are read at start"),
+      ],
+      notes: [],
+    };
+  }
+
+  if (platform === "windows") {
+    // An NRPT rule has no port field, so the bridge must be on 53 for Windows
+    // to be able to reach it at all. Caught here rather than at runtime, where
+    // the symptom would be every Moshpit name silently failing.
+    if (port !== WINDOWS_REQUIRED_PORT) {
+      throw new Error(
+        `Windows NRPT rules cannot carry a port, so the bridge must listen on ${WINDOWS_REQUIRED_PORT} ` +
+          `(asked for ${port}). Re-run with --port ${WINDOWS_REQUIRED_PORT}, as Administrator.`,
+      );
+    }
+    return {
+      platform,
+      elevated: true,
+      port,
+      steps: clean.map((tld) =>
+        run(
+          "powershell",
+          ["-NoProfile", "-Command", `Add-DnsClientNrptRule -Namespace ".${tld}" -NameServers "${host}"`],
+          `send .${tld} to the local bridge`,
+        ),
+      ),
+      notes: [`NRPT carries no port, so the bridge runs on ${WINDOWS_REQUIRED_PORT} here.`],
+    };
+  }
+
+  throw new Error(`unsupported platform: ${platform}`);
+}
+
+/**
+ * Undo it.
+ *
+ * Deliberately not derived from the enable plan: a machine may have been
+ * enabled with a TLD list that has since changed, and a disable that only
+ * removed what it currently knows about would strand the rest. On macOS and
+ * Windows the removal is therefore by pattern, not by list.
+ */
+export function disablePlan({ platform, tlds = [], linuxBackend = "systemd-resolved" }) {
+  const clean = [...new Set((tlds || []).map((t) => String(t).replace(/^\.+/, "").toLowerCase()).filter(Boolean))];
+
+  if (platform === "macos") {
+    return {
+      platform,
+      elevated: true,
+      steps: clean.map((tld) => remove(`/etc/resolver/${tld}`, `stop routing .${tld}`)),
+      notes: clean.length
+        ? []
+        : ["No TLDs known — nothing removed. Delete /etc/resolver/<tld> by hand if any remain."],
+    };
+  }
+
+  if (platform === "linux" && linuxBackend === "dnsmasq") {
+    return {
+      platform,
+      elevated: true,
+      steps: [
+        remove("/etc/dnsmasq.d/moshpit.conf", "stop routing Moshpit TLDs"),
+        run("systemctl", ["restart", "dnsmasq"], "pick up the removal"),
+      ],
+      notes: [],
+    };
+  }
+
+  if (platform === "linux") {
+    return {
+      platform,
+      elevated: true,
+      steps: [
+        remove("/etc/systemd/resolved.conf.d/moshpit.conf", "stop routing Moshpit TLDs"),
+        run("systemctl", ["restart", "systemd-resolved"], "pick up the removal"),
+      ],
+      notes: [],
+    };
+  }
+
+  if (platform === "windows") {
+    // Matched on the comment we stamp rather than on a TLD list, so a rule
+    // survives us forgetting which TLDs were routed.
+    return {
+      platform,
+      elevated: true,
+      steps: [
+        run(
+          "powershell",
+          [
+            "-NoProfile",
+            "-Command",
+            "Get-DnsClientNrptRule | Where-Object { $_.NameServers -contains '127.0.0.1' } | Remove-DnsClientNrptRule -Force",
+          ],
+          "remove every NRPT rule pointing at the local bridge",
+        ),
+      ],
+      notes: [],
+    };
+  }
+
+  throw new Error(`unsupported platform: ${platform}`);
+}
+
+/** The plan as something a person can read before agreeing to run it. */
+export function describePlan(plan) {
+  const lines = [];
+  for (const step of plan.steps) {
+    if (step.kind === "write") {
+      lines.push(`write   ${step.path}    # ${step.why}`);
+      for (const l of step.content.trimEnd().split("\n")) lines.push(`          ${l}`);
+    } else if (step.kind === "remove") {
+      lines.push(`remove  ${step.path}    # ${step.why}`);
+    } else {
+      lines.push(`run     ${step.command} ${step.args.join(" ")}    # ${step.why}`);
+    }
+  }
+  for (const note of plan.notes || []) lines.push(`note    ${note}`);
+  return lines.join("\n");
+}
+
+/**
+ * The port the bridge must listen on for this platform's routing to reach it.
+ *
+ * Only Windows constrains it, but asking here rather than special-casing at
+ * every call site keeps the one platform quirk in one place.
+ */
+export function requiredPort(platform, preferred = 5354) {
+  return platform === "windows" ? WINDOWS_REQUIRED_PORT : preferred;
+}
+
+/* ------------------------------------------------------- running the plan */
+
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+
+/**
+ * Carry out a plan.
+ *
+ * Every step is attempted and reported; one failure does not abort the rest.
+ * A half-applied routing config is a real state a machine can end up in — the
+ * user hit Ctrl-C, or one write needed a directory that did not exist — and
+ * telling them which steps landed is what makes it recoverable. Stopping at the
+ * first error would leave them guessing.
+ */
+export async function applyPlan(plan, { runner = defaultRunner, dryRun = false } = {}) {
+  const results = [];
+  for (const step of plan.steps) {
+    if (dryRun) {
+      results.push({ step, ok: true, skipped: true });
+      continue;
+    }
+    try {
+      if (step.kind === "write") {
+        await mkdir(dirname(step.path), { recursive: true });
+        await writeFile(step.path, step.content);
+      } else if (step.kind === "remove") {
+        await rm(step.path, { force: true });
+      } else {
+        await runner(step.command, step.args);
+      }
+      results.push({ step, ok: true });
+    } catch (error) {
+      results.push({ step, ok: false, error: error.message });
+    }
+  }
+  return { results, ok: results.every((r) => r.ok) };
+}
+
+function defaultRunner(command, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: "ignore" });
+    child.on("error", reject);
+    child.on("exit", (code) =>
+      code === 0 ? resolve() : reject(new Error(`${command} exited ${code}`)),
+    );
+  });
+}
+
+/* ------------------------------------------------------------- the daemon */
+
+/**
+ * Where the running bridge records itself.
+ *
+ * Under the user's own directory rather than /var/run: the bridge does not need
+ * root to listen on 5354, and requiring it to write a pidfile somewhere
+ * privileged would make the whole daemon need privileges it otherwise does not.
+ */
+export function pidfilePath() {
+  const base = process.env.XDG_RUNTIME_DIR || join(homedir(), ".moshcode") || tmpdir();
+  return join(base, "moshpit-dns.pid");
+}
+
+export async function readPid(path = pidfilePath()) {
+  try {
+    const pid = Number((await readFile(path, "utf8")).trim());
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Is that pid actually ours and alive? A stale pidfile must not read as running. */
+export function isAlive(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function daemonStatus(path = pidfilePath()) {
+  const pid = await readPid(path);
+  if (!pid) return { running: false, pid: null, stale: false };
+  if (isAlive(pid)) return { running: true, pid, stale: false };
+  // The file outlived the process — a crash or a reboot. Reported rather than
+  // cleaned up silently, because "it says it is on but it is not" is the state
+  // that makes Moshpit names fail with routing still in place.
+  return { running: false, pid, stale: true };
+}
+
+/**
+ * Start the bridge detached, so the shell that launched it can exit.
+ *
+ * Not a systemd unit / launchd job / Windows service yet, which means it does
+ * not survive a reboot. `moshcode dns status` says so plainly rather than
+ * letting someone discover it when their names stop resolving.
+ */
+export async function startDaemon({ port, registryBase, path = pidfilePath(), entry }) {
+  const existing = await daemonStatus(path);
+  if (existing.running) return { started: false, pid: existing.pid, alreadyRunning: true };
+
+  await mkdir(dirname(path), { recursive: true });
+  const args = [entry, "dns", "start", "--port", String(port)];
+  if (registryBase) args.push("--registry", registryBase);
+
+  const child = spawn(process.execPath, args, { detached: true, stdio: "ignore" });
+  child.unref();
+  await writeFile(path, `${child.pid}\n`);
+  return { started: true, pid: child.pid, alreadyRunning: false };
+}
+
+export async function stopDaemon(path = pidfilePath()) {
+  const status = await daemonStatus(path);
+  if (!status.pid) return { stopped: false, reason: "not running" };
+  if (status.running) {
+    try {
+      process.kill(status.pid, "SIGTERM");
+    } catch (error) {
+      return { stopped: false, reason: error.message };
+    }
+  }
+  await rm(path, { force: true });
+  return { stopped: status.running, reason: status.stale ? "cleared a stale pidfile" : null };
+}
+
+export { existsSync as _existsSync };