my-durable 0.0.6 → 0.0.8

package/README.md

@@ -15,6 +15,12 @@ npm install -g my-durable
 
 dpi hub                 # web UI + device tunnel server  → http://127.0.0.1:4781
 dpi device              # device daemon (pairs to a hub, serves this machine)
+dpi device start        # run it in the background — no terminal needed (log: <home>/device.log)
+dpi device stop|status  # graceful stop (token-authed local API) · health + pairing state
+dpi device install      # OS service: systemd --user + linger (Linux) · LaunchAgent (macOS).
+                        # Windows installs no autostart (like the reference clients) —
+                        # run `dpi device start` after login
+dpi device uninstall
 dpi tui                 # terminal admin client
 dpi --help              # commands, flags and environment variables
 dpi update --check      # is a newer published version available?

package/apps/dpi-backend/src/config.ts

@@ -1,10 +1,11 @@
 // Device configuration: ~/.dpi/backend.env (or $DPI_ENV_FILE) plus CLI flags.
 // Nothing here knows about specific machines; dpi-network.yaml on the operator's laptop
 // writes this env file through `just net up <device>`.
-import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { homedir, hostname } from "node:os";
 import { join, resolve } from "node:path";
+import { writePrivateFileAtomic } from "../../dpi-sdk/src/node/private-file.js";
 
 export interface BackendConfig {
   name: string;
@@ -22,7 +23,7 @@ export interface BackendConfig {
 
 const expand = (p: string) => (p === "~" ? homedir() : p.startsWith("~/") ? join(homedir(), p.slice(2)) : p);
 
-export function loadConfig(argv = process.argv.slice(2), env = process.env): BackendConfig {
+export async function loadConfig(argv = process.argv.slice(2), env = process.env): Promise<BackendConfig> {
   const flag = (key: string, fallback: string) => {
     const i = argv.indexOf(key);
     if (i < 0) return fallback;
@@ -44,7 +45,13 @@ export function loadConfig(argv = process.argv.slice(2), env = process.env): Bac
     token = `dpi_${randomBytes(32).toString("base64url")}`;
     tokenCreated = true;
     if (!existsSync(home)) mkdirSync(home, { recursive: true, mode: 0o700 });
-    appendFileSync(envFile, `DPI_TOKEN=${token}\n`, { mode: 0o600 });
+    // Atomic, content-preserving (orca STA-3941 / paseo writePrivateFileAtomicSync): a
+    // plain append could glue the token onto an unterminated last line or leave a
+    // half-written token if the boot dies mid-write. The shared writer publishes the
+    // new bytes only via rename and also enforces owner-only access on Windows.
+    const prior = existsSync(envFile) ? readFileSync(envFile, "utf8") : "";
+    const glued = prior !== "" && !prior.endsWith("\n") ? "\n" : "";
+    await writePrivateFileAtomic(envFile, `${prior}${glued}DPI_TOKEN=${token}\n`);
   }
   const config: BackendConfig = {
     name: flag("--name", env.DPI_DEVICE_NAME ?? hostname().replace(/\.local$/, "")),

package/apps/dpi-backend/src/daemon.ts

@@ -0,0 +1,422 @@
+/**
+ * `dpi device start|stop|status|install|uninstall` — run the device daemon
+ * WITHOUT a terminal. The reference clients keep their daemon alive through a
+ * desktop supervisor and spawn it detached (paseo `spawnDetached`: detached +
+ * stdio redirect + unref + stripped Electron env). We are headless, so the OS
+ * supervisor replaces the desktop app:
+ *
+ *   start    detached spawn, logs to <home>/device.log (paseo-style hygiene)
+ *   stop     graceful: token-authed POST /v1/shutdown, pid kill as fallback
+ *   status   health + pid + pairing state
+ *   install  linux: systemd --user unit (+ enable-linger so logout keeps it)
+ *            macOS: LaunchAgent plist
+ *            windows: hidden Startup-folder VBS (no console flash at logon)
+ *
+ * DPI_TOKEN never lands in any unit/plist/script — it lives in the env file
+ * the daemon bootstraps from.
+ */
+import { spawn, execFile } from "node:child_process";
+import { openSync, closeSync, existsSync, readFileSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export type DeviceSub = "run" | "start" | "stop" | "status" | "install" | "uninstall";
+
+/** First argv word decides: a subcommand runs and exits, anything else = foreground daemon. */
+export function parseDeviceSub(argv: string[]): { sub: DeviceSub; rest: string[] } {
+  const subs: DeviceSub[] = ["start", "stop", "status", "install", "uninstall"];
+  const [first, ...rest] = argv;
+  return subs.includes(first as DeviceSub)
+    ? { sub: first as DeviceSub, rest }
+    : { sub: "run", rest: argv };
+}
+
+const expand = (p: string) => (p === "~" ? homedir() : p.startsWith("~/") ? join(homedir(), p.slice(2)) : p);
+
+export interface DaemonPaths {
+  home: string;
+  pid: string;
+  log: string;
+}
+
+/** Same home rule as loadConfig: $DPI_HOME or ~/.dpi. */
+export function daemonPaths(env: { DPI_HOME?: string } = {}): DaemonPaths {
+  const home = expand(env.DPI_HOME ?? join(homedir(), ".dpi"));
+  return { home, pid: join(home, "device.pid"), log: join(home, "device.log") };
+}
+
+/** Knobs a service file may carry. The token is deliberately absent — it stays in the env file. */
+export function serviceEnv(env: Record<string, string | undefined>): Record<string, string> {
+  const keys = [
+    "DPI_HOME",
+    "DPI_HUB_URL",
+    "DPI_HUB_CA",
+    "DPI_PROVIDER",
+    "DPI_START_DIRS",
+    "DPI_HOST",
+    "DPI_PORT",
+    "DPI_DEVICE_NAME",
+    "DPI_DATA_DIR",
+    "DPI_ENV_FILE",
+  ];
+  const out: Record<string, string> = {};
+  for (const k of keys) if (env[k]) out[k] = env[k] as string;
+  return out;
+}
+
+/** The env the detached child inherits: drop the Electron-node hazards (paseo lesson). */
+export function cleanChildEnv(env: Record<string, string | undefined>): NodeJS.ProcessEnv {
+  const out: NodeJS.ProcessEnv = { ...env };
+  delete out.ELECTRON_RUN_AS_NODE;
+  delete out.ELECTRON_NO_ATTACH_CONSOLE;
+  return out;
+}
+
+const q = (s: string) => `"${s.replaceAll('"', "")}"`;
+
+export function systemdUnit(o: { node: string; dpi: string; env: Record<string, string> }): string {
+  const envLines = Object.entries(o.env)
+    .map(([k, v]) => `Environment="${k}=${v.replaceAll('"', "")}"`)
+    .join("\n");
+  return `[Unit]
+Description=Durable Pi device daemon
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${q(o.node)} ${q(o.dpi)} device
+${envLines}
+Restart=on-failure
+RestartSec=2
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export function launchdPlist(o: {
+  node: string;
+  dpi: string;
+  env: Record<string, string>;
+  log: string;
+}): string {
+  const envXml = Object.entries(o.env)
+    .map(([k, v]) => `        <key>${k}</key><string>${v.replaceAll("&", "&amp;").replaceAll("<", "&lt;")}</string>`)
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key><string>io.durable-pi.device</string>
+    <key>ProgramArguments</key><array><string>${o.node}</string><string>${o.dpi}</string><string>device</string></array>
+    <key>EnvironmentVariables</key>
+    <dict>
+${envXml}
+    </dict>
+    <key>RunAtLoad</key><true/>
+    <key>StandardOutPath</key><string>${o.log}</string>
+    <key>StandardErrorPath</key><string>${o.log}</string>
+  </dict>
+</plist>
+`;
+}
+
+// ---------------------------------------------------------------- command IO
+
+export interface RunOpts {
+  env?: Record<string, string | undefined>;
+  platform?: NodeJS.Platform;
+  uid?: number;
+  fetchImpl?: typeof fetch;
+  execImpl?: (cmd: string, args: string[]) => Promise<{ ok: boolean; output: string; code: number }>;
+  writeFileImpl?: (path: string, body: string) => Promise<void>;
+  killImpl?: (pid: number) => boolean;
+  print?: (line: string) => void;
+  quiet?: boolean;
+}
+
+interface Io {
+  env: Record<string, string | undefined>;
+  platform: NodeJS.Platform;
+  uid: number;
+  fetchImpl: typeof fetch;
+  exec: (cmd: string, args: string[]) => Promise<{ ok: boolean; output: string; code: number }>;
+  writeFile: (path: string, body: string) => Promise<void>;
+  kill: (pid: number) => boolean;
+  print: (line: string) => void;
+}
+
+const execDefault = (cmd: string, args: string[]) =>
+  new Promise<{ ok: boolean; output: string; code: number }>((resolve) => {
+    execFile(cmd, args, { timeout: 30_000 }, (error, stdout, stderr) => {
+      const code = (error as { code?: number } | null)?.code ?? 0;
+      resolve({ ok: !error, output: String(stdout ?? "") + String(stderr ?? ""), code });
+    });
+  });
+
+const delay = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+function ioOf(opts: RunOpts): Io {
+  return {
+    env: opts.env ?? process.env,
+    platform: opts.platform ?? process.platform,
+    uid: opts.uid ?? (typeof process.getuid === "function" ? process.getuid() : 0),
+    fetchImpl: opts.fetchImpl ?? fetch,
+    exec: opts.execImpl ?? execDefault,
+    writeFile:
+      opts.writeFileImpl ??
+      (async (path, body) => {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, body, { mode: 0o644 });
+      }),
+    kill:
+      opts.killImpl ??
+      ((pid) => {
+        try {
+          process.kill(pid, "SIGTERM");
+          return true;
+        } catch {
+          return false;
+        }
+      }),
+    print: opts.print ?? ((line) => !opts.quiet && console.log(line)),
+  };
+}
+
+function portOf(io: Io): number {
+  return Number(io.env.DPI_PORT ?? "4780");
+}
+
+/** Token for the local API: env first, then the env file the daemon bootstrapped from. */
+function tokenOf(io: Io, paths: DaemonPaths): string {
+  if (io.env.DPI_TOKEN) return io.env.DPI_TOKEN;
+  const envFile = expand(io.env.DPI_ENV_FILE ?? join(paths.home, "backend.env"));
+  try {
+    const m = readFileSync(envFile, "utf8").match(/^DPI_TOKEN=(.+)$/m);
+    if (m) return m[1].trim();
+  } catch {
+    /* no env file yet */
+  }
+  return "";
+}
+
+async function health(io: Io): Promise<Response | undefined> {
+  try {
+    return await io.fetchImpl(`http://127.0.0.1:${portOf(io)}/healthz`, {
+      signal: AbortSignal.timeout(800),
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+async function waitHealthDown(io: Io, ms: number): Promise<boolean> {
+  const end = Date.now() + ms;
+  while (Date.now() < end) {
+    const r = await health(io);
+    if (!r || !r.ok) return true;
+    await delay(200);
+  }
+  return false;
+}
+
+async function waitHealthUp(io: Io, ms: number): Promise<boolean> {
+  const end = Date.now() + ms;
+  while (Date.now() < end) {
+    const r = await health(io);
+    if (r?.ok) return true;
+    await delay(200);
+  }
+  return false;
+}
+
+function pidFrom(paths: DaemonPaths): number | undefined {
+  try {
+    const n = Number(readFileSync(paths.pid, "utf8").trim());
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------- commands
+
+async function cmdStart(io: Io, rest: string[]): Promise<number> {
+  const paths = daemonPaths(io.env);
+  if ((await health(io))?.ok) {
+    io.print(`already running (pid ${pidFrom(paths) ?? "?"}) on port ${portOf(io)}`);
+    return 0;
+  }
+  const dpi = io.env.DPI_BIN ?? (process.argv[1]?.endsWith(".mjs") ? process.argv[1] : "");
+  if (!dpi || !existsSync(dpi))
+    return io.print("start needs the dpi launcher (run via `dpi device start`)"), 1;
+  mkdirSync(paths.home, { recursive: true, mode: 0o700 });
+  const fd = openSync(paths.log, "a");
+  const child = spawn(process.execPath, [dpi, "device", ...rest], {
+    detached: true,
+    stdio: ["ignore", fd, fd],
+    env: cleanChildEnv(io.env),
+    cwd: dirname(dpi),
+  });
+  child.unref();
+  closeSync(fd);
+  io.print(`starting dpi device … (log: ${paths.log})`);
+  if (await waitHealthUp(io, 20_000)) {
+    io.print(`running on http://127.0.0.1:${portOf(io)} (pid ${pidFrom(paths) ?? "?"})`);
+    io.print(`stop: dpi device stop    survive logon: dpi device install`);
+    return 0;
+  }
+  io.print(`did not come up within 20s — tail the log: tail -50 ${paths.log}`);
+  return 1;
+}
+
+async function cmdStop(io: Io): Promise<number> {
+  const paths = daemonPaths(io.env);
+  const live = (await health(io))?.ok;
+  const pid = pidFrom(paths);
+  if (!live) {
+    if (pid) rmSync(paths.pid, { force: true });
+    io.print("not running");
+    return 0;
+  }
+  const token = tokenOf(io, paths);
+  if (token) {
+    try {
+      const r = await io.fetchImpl(`http://127.0.0.1:${portOf(io)}/v1/shutdown`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(3_000),
+      });
+      if (r.ok && (await waitHealthDown(io, 10_000))) {
+        rmSync(paths.pid, { force: true });
+        io.print(`stopped (graceful http shutdown, pid ${pid ?? "?"})`);
+        return 0;
+      }
+    } catch {
+      /* fall through to the pid kill */
+    }
+  }
+  if (pid && io.kill(pid) && (await waitHealthDown(io, 10_000))) {
+    rmSync(paths.pid, { force: true });
+    io.print(`stopped (SIGTERM pid ${pid})`);
+    return 0;
+  }
+  io.print(`still answering on port ${portOf(io)} — kill the process manually (pid ${pid ?? "?"})`);
+  return 1;
+}
+
+async function cmdStatus(io: Io): Promise<number> {
+  const paths = daemonPaths(io.env);
+  const pid = pidFrom(paths);
+  const h = await health(io);
+  if (!h?.ok) {
+    io.print(`not running (pid file: ${pid ?? "none"})`);
+    return 1;
+  }
+  io.print(`running  pid ${pid ?? "?"}  http://127.0.0.1:${portOf(io)}`);
+  const token = tokenOf(io, paths);
+  if (!token) return 0;
+  try {
+    const auth = { authorization: `Bearer ${token}` } as Record<string, string>;
+    const device = (await (await io.fetchImpl(`http://127.0.0.1:${portOf(io)}/v1/device`, { headers: auth })).json()) as {
+      name?: string;
+      uid?: string;
+      provider?: string;
+    };
+    io.print(`device   ${device.name ?? "?"} (${device.uid ?? "?"})  provider ${device.provider ?? "?"}`);
+    const pairing = (await (
+      await io.fetchImpl(`http://127.0.0.1:${portOf(io)}/v1/pairing`, { headers: auth })
+    ).json()) as { state?: string; hubOrigin?: string | null; fingerprint?: string };
+    io.print(`pairing  ${pairing.state ?? "?"}${pairing.hubOrigin ? ` → ${pairing.hubOrigin}` : ""}`);
+    if (pairing.fingerprint) io.print(`  fingerprint ${pairing.fingerprint}`);
+  } catch {
+    io.print("(local API not reachable with the saved token)");
+  }
+  return 0;
+}
+
+async function cmdInstall(io: Io): Promise<number> {
+  const env = serviceEnv(io.env);
+  const p = io.platform;
+  if (p === "win32") {
+    // The reference clients register NO OS autostart either: their daemon lives
+    // inside a desktop app the user opens by hand. We are a console daemon with
+    // no GUI host, so the honest equivalent on Windows is `dpi device start`
+    // after login — no hidden scripts, no registry entries, nothing to forget
+    // about at uninstall time.
+    io.print("Windows: no OS autostart is installed (the reference clients install none either).");
+    io.print("Start the daemon after login with:  dpi device start");
+    io.print("Stop it with:                       dpi device stop");
+    return 0;
+  }
+  const node = process.execPath;
+  const dpi = io.env.DPI_BIN ?? "";
+  if (!dpi || !existsSync(dpi)) return io.print("install needs the dpi launcher (run via `dpi device install`)"), 1;
+  if (!env.DPI_HOME) env.DPI_HOME = daemonPaths(io.env).home;
+  if (p === "linux") {
+    const unit = join(homedir(), ".config/systemd/user/dpi-device.service");
+    await io.writeFile(unit, systemdUnit({ node, dpi, env }));
+    await io.exec("systemctl", ["--user", "daemon-reload"]);
+    const enable = await io.exec("systemctl", ["--user", "enable", "--now", "dpi-device.service"]);
+    if (!enable.ok) {
+      io.print(`systemctl enable failed: ${enable.output}`);
+      return 1;
+    }
+    // Logout would otherwise stop a user service; linger keeps it. Best-effort:
+    // on locked-down hosts the operator adds it once by hand.
+    const linger = await io.exec("loginctl", ["enable-linger", String(io.uid)]);
+    io.print(`installed systemd user service (${unit})`);
+    io.print(linger.ok ? "linger enabled — the daemon survives logout and starts at boot" : "note: enable-linger was refused; the service still starts at every login");
+    io.print(`check: systemctl --user status dpi-device`);
+    return 0;
+  }
+  if (p === "darwin") {
+    const paths = daemonPaths(io.env);
+    const plist = join(homedir(), "Library/LaunchAgents/io.durable-pi.device.plist");
+    await io.writeFile(plist, launchdPlist({ node, dpi, env, log: paths.log }));
+    let boot = await io.exec("launchctl", ["bootstrap", `gui/${io.uid}`, plist]);
+    if (!boot.ok) boot = await io.exec("launchctl", ["load", "-w", plist]);
+    if (!boot.ok) {
+      io.print(`launchctl failed: ${boot.output}`);
+      return 1;
+    }
+    await io.exec("launchctl", ["enable", `gui/${io.uid}/io.durable-pi.device`]);
+    io.print(`installed LaunchAgent (${plist}) — starts at login`);
+    return 0;
+  }
+  io.print(`no service installer for platform ${p} — use \`dpi device start\` after login`);
+  return 1;
+}
+
+async function cmdUninstall(io: Io): Promise<number> {
+  await cmdStop(io);
+  const p = io.platform;
+  if (p === "linux") {
+    await io.exec("systemctl", ["--user", "disable", "--now", "dpi-device.service"]);
+    const unit = join(homedir(), ".config/systemd/user/dpi-device.service");
+    if (existsSync(unit)) rmSync(unit);
+    await io.exec("systemctl", ["--user", "daemon-reload"]);
+    await io.exec("loginctl", ["disable-linger", String(io.uid)]);
+    io.print("removed systemd user service");
+  } else if (p === "darwin") {
+    const plist = join(homedir(), "Library/LaunchAgents/io.durable-pi.device.plist");
+    let boot = await io.exec("launchctl", ["bootout", `gui/${io.uid}/io.durable-pi.device`]);
+    if (!boot.ok) await io.exec("launchctl", ["unload", "-w", plist]);
+    if (existsSync(plist)) rmSync(plist);
+    io.print("removed LaunchAgent");
+  } else if (p === "win32") {
+    io.print("Windows installs nothing at the OS level — only the daemon was stopped");
+  }
+  return 0;
+}
+
+export async function runDeviceCommand(sub: DeviceSub, rest: string[], opts: RunOpts = {}): Promise<number> {
+  const io = ioOf(opts);
+  if (sub === "start") return cmdStart(io, rest);
+  if (sub === "stop") return cmdStop(io);
+  if (sub === "status") return cmdStatus(io);
+  if (sub === "install") return cmdInstall(io);
+  if (sub === "uninstall") return cmdUninstall(io);
+  return 0;
+}

package/apps/dpi-backend/src/main.ts

@@ -1,7 +1,9 @@
 // dpi-backend: one device of the Durable Agent Network.
 import express from "express";
+import type { Request, Response, NextFunction } from "express";
 import { assertLimitsConfig } from "../../dpi-sdk/src/protocol/limits.js";
 import { createServer } from "node:http";
+import { writeFileSync, rmSync } from "node:fs";
 import { networkInterfaces } from "node:os";
 import { loadConfig } from "./config.js";
 import { Store } from "./store.js";
@@ -10,10 +12,19 @@ import { errorMiddleware } from "./errors.js";
 import { v1 } from "./routes.js";
 import { DevicePairing } from "./pairing.js";
 import { DeviceConnector, readCaPem } from "./tunnel.js";
+import { PAIR_PAGE_HTML } from "./pair-page.js";
+import { parseDeviceSub, runDeviceCommand, daemonPaths } from "./daemon.js";
+
+// `dpi device start|stop|status|install|uninstall` manage a background daemon
+// and exit; everything else (bare `dpi device` or flags) runs the daemon here.
+{
+  const { sub, rest } = parseDeviceSub(process.argv.slice(2));
+  if (sub !== "run") process.exit(await runDeviceCommand(sub, rest));
+}
 
 assertLimitsConfig();
 
-const config = loadConfig();
+const config = await loadConfig();
 const store = await Store.open({
   dataDir: config.dataDir,
   startDirs: config.startDirs,
@@ -44,24 +55,149 @@ const connector = new DeviceConnector(
     onRevoked: (epoch, reason) => pairing.markRevoked(reason, epoch),
     onRotated: (file) => pairing.markRotated(file),
   },
-  { baseUrl: `http://${config.host === "0.0.0.0" ? "127.0.0.1" : config.host}:${config.port}`, token: config.token },
+  {
+    baseUrl: `http://${config.host === "0.0.0.0" ? "127.0.0.1" : config.host}:${config.port}`,
+    token: config.token,
+  },
 );
 connector.start();
-app.use("/v1", bearerAuth(config.token), express.json({ limit: "256kb" }), v1(store, pairing, connector));
-app.use((_req, res) => res.status(404).json({ error: { code: "not_found", message: "Route not found" } }));
+// GET /pair + /v1/pair-enroll — the device-side browser enrollment surface
+// (gap #4). Unauthenticated BUT narrow: the custom x-dpi-pair header forces a
+// CORS preflight on every foreign origin (a drive-by page cannot POST), the
+// POST only runs while UNPAIRED (a paired device re-pairs through the TUI's
+// token-authed route with force), and the status view carries no secrets.
+const pairEnrollGuard = (req: Request, res: Response, next: NextFunction) => {
+  if (req.get("x-dpi-pair") !== "1")
+    return res
+      .status(403)
+      .json({ error: { code: "forbidden", message: "missing x-dpi-pair header" } });
+  next();
+};
+app.get("/pair", (_req, res) => res.type("html").send(PAIR_PAGE_HTML));
+app.get("/v1/pair-enroll", pairEnrollGuard, (_req, res) => {
+  const s = pairing.status();
+  res.json({
+    state: s.state,
+    deviceName: s.deviceName,
+    fingerprint: s.fingerprint,
+    hubOrigin: s.hubOrigin ?? s.pending?.hubOrigin,
+    lastError: s.lastError,
+  });
+});
+app.post("/v1/pair-enroll", pairEnrollGuard, express.json({ limit: "8kb" }), (req, res) => {
+  void (async () => {
+    const s = pairing.status();
+    if (s.state === "paired")
+      return res
+        .status(409)
+        .json({
+          error: {
+            code: "paired",
+            message:
+              "this device is already paired; re-pairing runs in the TUI (dpi tui) so it stays operator-driven",
+          },
+        });
+    if (s.state === "pairing")
+      return res
+        .status(409)
+        .json({
+          error: {
+            code: "busy",
+            message: "a pairing operation is already running — watch its status below",
+          },
+        });
+    const pairUrl = (req.body as { pairUrl?: unknown } | null)?.pairUrl;
+    if (typeof pairUrl !== "string" || pairUrl.length === 0 || pairUrl.length > 4096)
+      return res
+        .status(400)
+        .json({
+          error: {
+            code: "invalid",
+            message: "body: { pairUrl: string } — the offer link from the hub",
+          },
+        });
+    try {
+      await pairing.start({ code: "", pairUrl });
+      const after = pairing.status();
+      res.json({
+        state: after.state,
+        deviceName: after.deviceName,
+        fingerprint: after.fingerprint,
+        hubOrigin: after.pending?.hubOrigin,
+        lastError: after.lastError,
+      });
+    } catch (e) {
+      res.status((e as { status?: number }).status ?? 400).json({
+        error: { code: (e as { code?: string }).code ?? "invalid", message: (e as Error).message },
+      });
+    }
+  })();
+});
+app.use(
+  "/v1",
+  bearerAuth(config.token),
+  express.json({ limit: "256kb" }),
+  v1(store, pairing, connector, () => void shutdown()),
+);
+app.use((_req, res) =>
+  res.status(404).json({ error: { code: "not_found", message: "Route not found" } }),
+);
 app.use(errorMiddleware);
 
 const server = createServer(app);
 server.keepAliveTimeout = 65_000;
 server.listen(config.port, config.host, () => {
-  console.log(`dpi-backend "${config.name}" (uid ${store.uid}) on http://${config.host}:${config.port}`);
+  // Pid file for `dpi device stop/status` (written fresh every boot).
+  try {
+    writeFileSync(daemonPaths(process.env).pid, String(process.pid));
+  } catch {
+    /* read-only home: stop falls back to the HTTP shutdown */
+  }
+  console.log(
+    `dpi-backend "${config.name}" (uid ${store.uid}) on http://${config.host}:${config.port}`,
+  );
   if (config.tokenCreated)
     console.log(`first run: created DPI_TOKEN in ${config.envFile} — keep this file private`);
-  console.log(`data: ${config.dataDir}  start dirs: ${config.startDirs.join(", ")}  provider: ${config.provider}`);
+  console.log(
+    `data: ${config.dataDir}  start dirs: ${config.startDirs.join(", ")}  provider: ${config.provider}`,
+  );
   if (config.host === "0.0.0.0")
     for (const addresses of Object.values(networkInterfaces()))
       for (const a of addresses ?? [])
-        if (a.family === "IPv4" && !a.internal) console.log(`LAN: http://${a.address}:${config.port}`);
+        if (a.family === "IPv4" && !a.internal)
+          console.log(`LAN: http://${a.address}:${config.port}`);
+  console.log(`background: dpi device start | stop | status | install (service)`);
+
+  // Enrollment guidance: an unpaired machine must be told exactly what to do,
+  // and — when a hub is configured — it asks for a code ITSELF so the operator
+  // reads this machine's identity in the hub's approval list (no secret to carry).
+  const boot = pairing.status();
+  if (boot.state === "unpaired") {
+    const hubOrigin = process.env.DPI_HUB_URL;
+    console.log("");
+    console.log(`unpaired: open http://${config.host === "0.0.0.0" ? "127.0.0.1" : config.host}:${config.port}/pair`);
+    if (hubOrigin) {
+      console.log(`requesting a pairing code from ${hubOrigin} …`);
+      void pairing
+        .start({ hub: hubOrigin })
+        .then((s) => {
+          if (s.state !== "pairing") return;
+          console.log("");
+          console.log(`  APPROVE THIS MACHINE ON THE HUB (${s.pending?.hubOrigin ?? hubOrigin}):`);
+          console.log(`    device    ${s.deviceName}`);
+          console.log(`    fingerprint ${s.fingerprint}`);
+          console.log("  Compare that fingerprint with the hub's approval card, then approve there.");
+          console.log("  This command keeps running; the credential is saved automatically.");
+        })
+        .catch((e: Error) => {
+          console.log(`pairing request failed: ${e.message}`);
+          console.log(`retry from the TUI (dpi tui, then /pair --hub ${hubOrigin}) or open /pair`);
+        });
+    } else {
+      console.log(`  then pair from the hub wizard, or run: dpi tui  →  /pair <code> --hub <origin>`);
+      console.log("  set DPI_HUB_URL=<https origin> to let this machine request a code by itself");
+    }
+  }
 });
 
 let closing = false;
@@ -72,6 +208,11 @@ const shutdown = async () => {
   server.close();
   server.closeAllConnections();
   await store.close();
+  try {
+    rmSync(daemonPaths(process.env).pid, { force: true });
+  } catch {
+    /* nothing to clean */
+  }
   process.exit(0);
 };
 process.on("SIGTERM", () => void shutdown());