@openparachute/hub 0.6.3-rc.2 → 0.6.3-rc.4

package/src/__tests__/stale-module-units.test.ts

@@ -0,0 +1,286 @@
+import { describe, expect, test } from "bun:test";
+import type { ManagedUnitDeps, ServiceCommandResult } from "../managed-unit.ts";
+import {
+  disableStaleModuleUnits,
+  moduleLaunchdLabel,
+  moduleSystemdUnitName,
+  targetModuleShorts,
+} from "../stale-module-units.ts";
+
+/**
+ * #522 — migrate/teardown must DETECT + DISABLE any stale per-module autostart
+ * unit (a leftover `parachute-<short>.service` systemd KeepAlive / a
+ * `computer.parachute.<short>` launchd KeepAlive) so it stops respawning an
+ * unsupervised module that fights the supervised hub for the module's port.
+ *
+ * ALL tests run against a stubbed `ManagedUnitDeps.run` — NO real
+ * systemctl/launchctl. Each fake records the commands it received so we can
+ * assert exactly which units were disabled, which were skipped, and that a
+ * disable failure / system-level unit is non-fatal.
+ */
+
+type RunResponder = (cmd: readonly string[]) => ServiceCommandResult;
+
+function ok(stdout = ""): ServiceCommandResult {
+  return { code: 0, stdout, stderr: "" };
+}
+function fail(stderr = "boom", code = 1): ServiceCommandResult {
+  return { code, stdout: "", stderr };
+}
+
+function makeDeps(platform: NodeJS.Platform, respond: RunResponder) {
+  const calls: string[][] = [];
+  const deps: ManagedUnitDeps = {
+    platform,
+    getuid: () => 501,
+    homeDir: () => "/home/op",
+    userName: () => "op",
+    which: (b) => (b === "systemctl" || b === "launchctl" ? `/usr/bin/${b}` : null),
+    run: (cmd) => {
+      calls.push([...cmd]);
+      return respond(cmd);
+    },
+    writeFile: () => {},
+    removeFile: () => {},
+    readFile: () => undefined,
+    exists: () => false,
+  };
+  return { deps, calls };
+}
+
+function joined(calls: string[][]): string[] {
+  return calls.map((c) => c.join(" "));
+}
+
+describe("targetModuleShorts() — known module shorts, never hub/cloudflared", () => {
+  test("includes the canonical module shorts and excludes hub", () => {
+    const shorts = targetModuleShorts();
+    // The canonical knownServices() set: vault / scribe / runner / surface / notes / channel.
+    expect(shorts).toContain("vault");
+    expect(shorts).toContain("scribe");
+    expect(shorts).toContain("surface");
+    expect(shorts).toContain("notes");
+    // hub is the supervised model itself — never a target.
+    expect(shorts).not.toContain("hub");
+    expect(shorts).not.toContain("cloudflared");
+  });
+});
+
+describe("disableStaleModuleUnits — systemd (Linux)", () => {
+  test("a stale ENABLED user unit parachute-vault.service is disabled --now + reported", () => {
+    const { deps, calls } = makeDeps("linux", (cmd) => {
+      const line = cmd.join(" ");
+      // Only vault's USER unit reads enabled; everything else is disabled.
+      if (line === "systemctl --user is-enabled parachute-vault.service") return ok("enabled\n");
+      if (line.startsWith("systemctl --user is-enabled")) return fail("disabled", 1);
+      if (line.startsWith("systemctl is-enabled")) return fail("disabled", 1);
+      if (line === "systemctl --user disable --now parachute-vault.service") return ok();
+      return ok();
+    });
+    const log: string[] = [];
+    const res = disableStaleModuleUnits({ deps, log: (l) => log.push(l) });
+
+    // Exactly one unit acted on: vault, disabled at user scope.
+    expect(res.actions).toHaveLength(1);
+    expect(res.actions[0]).toMatchObject({
+      short: "vault",
+      kind: "systemd-user",
+      unit: "parachute-vault.service",
+      result: "disabled",
+    });
+    // The disable --now command was actually invoked.
+    expect(joined(calls)).toContain("systemctl --user disable --now parachute-vault.service");
+    // The action is reported so the operator sees what changed.
+    expect(log.join("\n")).toContain("Disabled stale parachute-vault.service");
+    expect(log.join("\n")).toContain("vault's port");
+  });
+
+  test("SKIPS the hub unit + cloudflared units — never queried, never disabled", () => {
+    const { deps, calls } = makeDeps("linux", () => fail("disabled", 1));
+    disableStaleModuleUnits({ deps });
+    const lines = joined(calls);
+    // The hub unit is never probed or disabled by this sweep.
+    expect(lines.some((l) => l.includes("parachute-hub.service"))).toBe(false);
+    // No cloudflared connector unit is touched.
+    expect(lines.some((l) => l.includes("parachute-cloudflared"))).toBe(false);
+    // And no disable command runs at all (everything reads disabled).
+    expect(lines.some((l) => l.includes("disable"))).toBe(false);
+  });
+
+  test("a non-matching / arbitrary unit is never touched (only parachute-<known-short> is queried)", () => {
+    const { deps, calls } = makeDeps("linux", () => fail("disabled", 1));
+    disableStaleModuleUnits({ deps });
+    const lines = joined(calls);
+    // Every is-enabled probe targets a parachute-<known-short>.service and nothing else.
+    const probes = lines.filter((l) => l.includes("is-enabled"));
+    expect(probes.length).toBeGreaterThan(0);
+    for (const probe of probes) {
+      const m = probe.match(/is-enabled (parachute-[a-z]+\.service)$/);
+      expect(m).not.toBeNull();
+      const unit = m?.[1] ?? "";
+      // The probed unit must be a known module short, and never the hub/cloudflared.
+      expect(targetModuleShorts().map(moduleSystemdUnitName)).toContain(unit);
+      expect(unit).not.toBe("parachute-hub.service");
+    }
+  });
+
+  test("idempotent: every unit already disabled → clean no-op (no disable, no actions)", () => {
+    const { deps, calls } = makeDeps("linux", () => fail("disabled", 1));
+    const res = disableStaleModuleUnits({ deps });
+    expect(res.actions).toHaveLength(0);
+    expect(joined(calls).some((l) => l.includes("disable"))).toBe(false);
+  });
+
+  test("system-level unit (no --user enabled, system enabled) → WARNS with manual sudo command, doesn't abort, doesn't sudo", () => {
+    const { deps, calls } = makeDeps("linux", (cmd) => {
+      const line = cmd.join(" ");
+      // vault's USER unit is NOT enabled, but the SYSTEM unit IS.
+      if (line === "systemctl --user is-enabled parachute-vault.service")
+        return fail("disabled", 1);
+      if (line === "systemctl is-enabled parachute-vault.service") return ok("enabled\n");
+      if (line.startsWith("systemctl --user is-enabled")) return fail("disabled", 1);
+      if (line.startsWith("systemctl is-enabled")) return fail("disabled", 1);
+      return ok();
+    });
+    const log: string[] = [];
+    const res = disableStaleModuleUnits({ deps, log: (l) => log.push(l) });
+
+    const vaultAction = res.actions.find((a) => a.short === "vault");
+    expect(vaultAction).toMatchObject({ kind: "systemd-system", result: "warn-system" });
+    const out = log.join("\n");
+    // The exact manual command is surfaced.
+    expect(out).toContain("sudo systemctl disable --now parachute-vault.service");
+    // It NEVER attempted a sudo / system disable itself.
+    expect(joined(calls)).not.toContain("systemctl disable --now parachute-vault.service");
+    expect(joined(calls).some((l) => l.startsWith("sudo"))).toBe(false);
+  });
+
+  test("non-fatal: a disable command that fails → warn + continue (the other units are still swept)", () => {
+    const { deps, calls } = makeDeps("linux", (cmd) => {
+      const line = cmd.join(" ");
+      // Both vault + scribe user units read enabled; vault's disable FAILS.
+      if (line === "systemctl --user is-enabled parachute-vault.service") return ok("enabled\n");
+      if (line === "systemctl --user is-enabled parachute-scribe.service") return ok("enabled\n");
+      if (line.startsWith("systemctl --user is-enabled")) return fail("disabled", 1);
+      if (line.startsWith("systemctl is-enabled")) return fail("disabled", 1);
+      if (line === "systemctl --user disable --now parachute-vault.service")
+        return fail("permission denied");
+      if (line === "systemctl --user disable --now parachute-scribe.service") return ok();
+      return ok();
+    });
+    const log: string[] = [];
+    const res = disableStaleModuleUnits({ deps, log: (l) => log.push(l) });
+
+    const vault = res.actions.find((a) => a.short === "vault");
+    const scribe = res.actions.find((a) => a.short === "scribe");
+    // vault's disable failed → warned, not fatal; scribe was still disabled.
+    expect(vault?.result).toBe("failed");
+    expect(scribe?.result).toBe("disabled");
+    // Both disable attempts ran — the failure didn't abort the sweep.
+    expect(joined(calls)).toContain("systemctl --user disable --now parachute-vault.service");
+    expect(joined(calls)).toContain("systemctl --user disable --now parachute-scribe.service");
+    expect(log.join("\n")).toContain("Could not disable");
+  });
+
+  test("no systemctl on the box → clean no-op", () => {
+    const calls: string[][] = [];
+    const deps: ManagedUnitDeps = {
+      platform: "linux",
+      getuid: () => 501,
+      homeDir: () => "/home/op",
+      userName: () => "op",
+      which: () => null, // no systemctl
+      run: (cmd) => {
+        calls.push([...cmd]);
+        return ok();
+      },
+      writeFile: () => {},
+      removeFile: () => {},
+      readFile: () => undefined,
+      exists: () => false,
+    };
+    const res = disableStaleModuleUnits({ deps });
+    expect(res.actions).toHaveLength(0);
+    expect(calls).toHaveLength(0);
+  });
+});
+
+describe("disableStaleModuleUnits — launchd (Mac)", () => {
+  test("a loaded computer.parachute.vault LaunchAgent is booted out + reported", () => {
+    const { deps, calls } = makeDeps("darwin", (cmd) => {
+      const line = cmd.join(" ");
+      // Only vault's label is loaded (print succeeds with content); others print empty.
+      if (line === "launchctl print gui/501/computer.parachute.vault")
+        return ok("com.apple...\nstate = running\n");
+      if (line.startsWith("launchctl print")) return ok(""); // not loaded
+      if (line === "launchctl bootout gui/501/computer.parachute.vault") return ok();
+      return ok();
+    });
+    const log: string[] = [];
+    const res = disableStaleModuleUnits({ deps, log: (l) => log.push(l) });
+
+    expect(res.actions).toHaveLength(1);
+    expect(res.actions[0]).toMatchObject({
+      short: "vault",
+      kind: "launchd",
+      unit: "computer.parachute.vault",
+      result: "disabled",
+    });
+    expect(joined(calls)).toContain("launchctl bootout gui/501/computer.parachute.vault");
+    expect(log.join("\n")).toContain("Disabled stale computer.parachute.vault");
+  });
+
+  test("SKIPS the hub label + cloudflared labels — never printed, never booted out", () => {
+    const { deps, calls } = makeDeps("darwin", () => ok("")); // nothing loaded
+    disableStaleModuleUnits({ deps });
+    const lines = joined(calls);
+    expect(lines.some((l) => l.includes("computer.parachute.hub"))).toBe(false);
+    expect(lines.some((l) => l.includes("computer.parachute.cloudflared"))).toBe(false);
+    // Every print targets a parachute.<known-short> label.
+    const prints = lines.filter((l) => l.startsWith("launchctl print"));
+    for (const p of prints) {
+      const m = p.match(/computer\.parachute\.([a-z]+)$/);
+      expect(m).not.toBeNull();
+      expect(targetModuleShorts()).toContain(m?.[1] ?? "");
+    }
+  });
+
+  test("idempotent: nothing loaded → clean no-op (no bootout, no actions)", () => {
+    const { deps, calls } = makeDeps("darwin", () => ok("")); // print returns empty for all
+    const res = disableStaleModuleUnits({ deps });
+    expect(res.actions).toHaveLength(0);
+    expect(joined(calls).some((l) => l.includes("bootout"))).toBe(false);
+  });
+
+  test("non-fatal: a bootout that fails → warn + continue", () => {
+    const { deps } = makeDeps("darwin", (cmd) => {
+      const line = cmd.join(" ");
+      if (line === "launchctl print gui/501/computer.parachute.vault")
+        return ok("state = running\n");
+      if (line.startsWith("launchctl print")) return ok("");
+      if (line === "launchctl bootout gui/501/computer.parachute.vault")
+        return fail("Operation not permitted");
+      return ok();
+    });
+    const log: string[] = [];
+    const res = disableStaleModuleUnits({ deps, log: (l) => log.push(l) });
+    expect(res.actions.find((a) => a.short === "vault")?.result).toBe("failed");
+    expect(log.join("\n")).toContain("Could not disable the stale LaunchAgent");
+  });
+});
+
+describe("disableStaleModuleUnits — unsupported platform", () => {
+  test("no per-platform manager (e.g. win32) → clean no-op", () => {
+    const { deps, calls } = makeDeps("win32", () => ok());
+    const res = disableStaleModuleUnits({ deps });
+    expect(res.actions).toHaveLength(0);
+    expect(calls).toHaveLength(0);
+  });
+});
+
+describe("unit-name helpers", () => {
+  test("moduleSystemdUnitName / moduleLaunchdLabel build the exact per-module names", () => {
+    expect(moduleSystemdUnitName("vault")).toBe("parachute-vault.service");
+    expect(moduleLaunchdLabel("vault")).toBe("computer.parachute.vault");
+  });
+});

package/src/api-modules-ops.ts

@@ -40,8 +40,8 @@ import { CURATED_MODULES, type CuratedModuleShort } from "./api-modules.ts";
 import { isLinked as defaultIsLinked } from "./bun-link.ts";
 import { PARACHUTE_INSTALL_CHANNEL_ENV } from "./commands/install.ts";
 import { buildModuleSpawnRequest } from "./commands/serve-boot.ts";
+import { validateHostAdminToken } from "./host-admin-token-validation.ts";
 import { getModuleInstallChannel } from "./hub-settings.ts";
-import { validateAccessToken } from "./jwt-sign.ts";
 import { readModuleManifest } from "./module-manifest.ts";
 import { refreshWellKnown, stampInstallDirOnRow } from "./post-install.ts";
 import {
@@ -180,6 +180,21 @@ export interface RunOpts {
 export interface ApiModulesOpsDeps {
   db: Database;
   issuer: string;
+  /**
+   * The SET of origins the hub legitimately answers on — loopback aliases ∪
+   * expose-state public origin ∪ platform/env origin ∪ the per-request
+   * `issuer`. The host-admin bearer's `iss` is validated against THIS set, not
+   * the single per-request `issuer` (hub#516): the CLI drives these endpoints
+   * on loopback presenting the operator token, whose `iss` is the hub's public
+   * origin after `expose`. Built via `buildHubBoundOrigins` at the call site.
+   *
+   * Optional for back-compat with callers that don't construct it (the
+   * first-boot wizard's `runInstall`, tests). When absent, `authorize` falls
+   * back to the single-element `[issuer]` set — i.e. the prior strict
+   * per-request behavior — so the relaxation is opt-in at the HTTP call site
+   * and the non-HTTP install path is unaffected.
+   */
+  knownIssuers?: readonly string[];
   manifestPath: string;
   configDir: string;
   supervisor: Supervisor;
@@ -280,7 +295,18 @@ async function authorize(req: Request, deps: ApiModulesOpsDeps): Promise<Respons
   const bearer = auth.slice("Bearer ".length).trim();
   if (!bearer) return jsonError(401, "unauthenticated", "empty bearer token");
   try {
-    const validated = await validateAccessToken(deps.db, bearer, deps.issuer);
+    // Host-admin (operator / SPA) token validation: accept the `iss` against
+    // the SET of origins the hub answers on, not the single per-request issuer
+    // (hub#516). This surface only ever accepts the hub's own self-issued
+    // host-admin credentials (the `parachute:host:admin` scope below is
+    // non-requestable via OAuth), so the relaxation cannot reach an OAuth
+    // token's validation. Falls back to the strict single-issuer set when
+    // `knownIssuers` isn't wired (non-HTTP install path / tests).
+    const validated = await validateHostAdminToken(
+      deps.db,
+      bearer,
+      deps.knownIssuers ?? [deps.issuer],
+    );
     if (typeof validated.payload.sub !== "string" || validated.payload.sub.length === 0) {
       return jsonError(401, "unauthenticated", "bearer token has no sub claim");
     }

package/src/api-modules.ts

@@ -25,6 +25,7 @@
  */
 
 import type { Database } from "bun:sqlite";
+import { validateHostAdminToken } from "./host-admin-token-validation.ts";
 import {
   type ModuleInstallChannel,
   getModuleInstallChannel,
@@ -116,6 +117,18 @@ export type CuratedModuleShort = (typeof CURATED_MODULES)[number];
 export interface ApiModulesDeps {
   db: Database;
   issuer: string;
+  /**
+   * The SET of origins the hub legitimately answers on — loopback aliases ∪
+   * expose-state public origin ∪ platform/env origin ∪ the per-request
+   * `issuer`. The host-admin bearer's `iss` is validated against THIS set, not
+   * the single per-request `issuer` (hub#516): `parachute status` reads this
+   * endpoint on loopback presenting the operator token, whose `iss` is the
+   * hub's public origin after `expose`. Built via `buildHubBoundOrigins` at the
+   * call site. When absent, falls back to the single-element `[issuer]` set
+   * (the prior strict per-request behavior) so non-HTTP callers / tests are
+   * unaffected.
+   */
+  knownIssuers?: readonly string[];
   manifestPath: string;
   supervisor?: Supervisor;
   /**
@@ -312,10 +325,20 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
     return jsonError(401, "unauthenticated", "empty bearer token");
   }
 
-  // Bearer validation.
+  // Bearer validation. Host-admin (operator / SPA) token: accept the `iss`
+  // against the SET of origins the hub answers on, not the single per-request
+  // issuer (hub#516) — `parachute status` reads this on loopback presenting the
+  // operator token, whose `iss` is the hub's public origin after `expose`. This
+  // surface gates on the non-requestable `parachute:host:auth` scope below, so
+  // the relaxation only ever touches the hub's own self-issued host-admin
+  // credentials and cannot reach an OAuth token's validation.
   let bearerScopes: string[];
   try {
-    const validated = await validateAccessToken(deps.db, bearer, deps.issuer);
+    const validated = await validateHostAdminToken(
+      deps.db,
+      bearer,
+      deps.knownIssuers ?? [deps.issuer],
+    );
     if (typeof validated.payload.sub !== "string" || validated.payload.sub.length === 0) {
       return jsonError(401, "unauthenticated", "bearer token has no sub claim");
     }

package/src/cloudflare/connector-service.ts

@@ -69,10 +69,21 @@ export type ConnectorServiceDeps = ManagedUnitDeps;
 
 export const defaultServiceDeps: ConnectorServiceDeps = defaultManagedUnitDeps;
 
+/**
+ * Reverse-DNS prefix for the launchd label + plist filename. Exported so the
+ * migrate/teardown stale-per-module-autostart sweep (`src/stale-module-units.ts`,
+ * hub#522) can reuse it as a SKIP-list anchor — the connector unit is owned by
+ * the supervised model (`expose off --cloudflare` tears it down), and the sweep
+ * must never touch it. Reusing the constant keeps the skip-list from drifting if
+ * this prefix ever changes.
+ */
+export const CLOUDFLARED_LAUNCHD_LABEL_PREFIX = "computer.parachute.cloudflared";
+/** systemd unit name prefix. Exported for the same skip-list reason as above. */
+export const CLOUDFLARED_SYSTEMD_UNIT_PREFIX = "parachute-cloudflared-";
 /** Reverse-DNS prefix for the launchd label + plist filename. */
-const LAUNCHD_LABEL_PREFIX = "computer.parachute.cloudflared";
+const LAUNCHD_LABEL_PREFIX = CLOUDFLARED_LAUNCHD_LABEL_PREFIX;
 /** systemd unit name prefix. */
-const SYSTEMD_UNIT_PREFIX = "parachute-cloudflared-";
+const SYSTEMD_UNIT_PREFIX = CLOUDFLARED_SYSTEMD_UNIT_PREFIX;
 /** Provenance comment baked into every rendered connector unit file. */
 const CONNECTOR_HEADER = "Generated by parachute expose public --cloudflare — do not edit by hand.";
 

package/src/commands/migrate-cutover.ts

@@ -86,6 +86,11 @@ import { type PortListeningFn, defaultPortListening } from "../port-probe.ts";
 import { type AliveFn, clearPid, readPid } from "../process-state.ts";
 import { shortNameForManifest } from "../service-spec.ts";
 import { type ServiceEntry, readManifestLenient } from "../services-manifest.ts";
+import {
+  type DisableStaleModuleUnitsOpts,
+  type DisableStaleModuleUnitsResult,
+  disableStaleModuleUnits,
+} from "../stale-module-units.ts";
 
 /**
  * Absolute path to this hub checkout's `src/cli.ts` — the entry the hub unit's
@@ -180,6 +185,19 @@ export interface CutoverDeps {
   sleep: (ms: number) => Promise<void>;
   /** The hub-unit deps for install / detect / manager calls. */
   hubUnitDeps: HubUnitDeps;
+  /**
+   * Detect + DISABLE any stale per-module autostart unit (#522 — the load-bearing
+   * fix). A leftover standalone `parachute-<short>.service` (systemd KeepAlive) /
+   * `computer.parachute.<short>` (launchd KeepAlive) from the pre-supervisor era
+   * keeps RESPAWNING an unsupervised module that binds the module's port — the
+   * supervised child then EADDRINUSE-crash-loops. Killing the process is
+   * whack-a-mole (the unit resurrects it); we must disable the UNIT. Run in the
+   * STOP phase (after the per-module detached stop, before the port-free verify)
+   * so the freed port lets the supervised module bind. Ownership-safe (known
+   * module shorts only; hub + cloudflared skipped), idempotent, non-fatal.
+   * Injectable so tests never touch real systemctl/launchctl.
+   */
+  disableStaleModuleUnits: (opts?: DisableStaleModuleUnitsOpts) => DisableStaleModuleUnitsResult;
 }
 
 export interface WriteUnitOpts {
@@ -329,6 +347,7 @@ export const defaultCutoverDeps: CutoverDeps = {
   probeHealth: defaultHubUnitDeps.probeHealth,
   sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
   hubUnitDeps: defaultHubUnitDeps,
+  disableStaleModuleUnits,
 };
 
 export interface CutoverOpts {
@@ -673,6 +692,22 @@ export async function cutoverToSupervised(opts: CutoverOpts = {}): Promise<Cutov
     await stopDetachedModule(target, configDir, deps, timeoutMs, pollMs, log);
   }
 
+  // --- Step 3b (#522): DISABLE stale per-module autostart UNITS. ---
+  // The load-bearing fix for the recurring "port 1940 taken" crash-loop: a
+  // leftover standalone `parachute-<short>.service` (systemd KeepAlive) or
+  // `computer.parachute.<short>` (launchd KeepAlive) from the pre-supervisor era
+  // keeps RESPAWNING an unsupervised module that binds the port — so the
+  // per-module stop above (and the orphan sweep below) is whack-a-mole: the unit
+  // resurrects the process within seconds, serving OLD code. We must DISABLE the
+  // UNIT so the port stays free for the supervised child. MUST run HERE — after
+  // the detached stop, BEFORE the verify-ports-free + unit start — so the freed
+  // port lets the supervised module bind. Ownership-safe (known module shorts
+  // only; hub + cloudflared skipped), idempotent, non-fatal (a failed disable
+  // warns + continues; a system-level unit it can't disable → warn with the
+  // manual sudo command). Every disabled unit is reported.
+  log("Checking for stale per-module autostart units to disable…");
+  deps.disableStaleModuleUnits({ deps: deps.hubUnitDeps, log: (l) => log(l) });
+
   // --- Step 4: §7.2 ORPHAN SWEEP — per services.json port + the hub port. ---
   // The HUB port keeps the pre-existing blind-adopt (mirrors stopHub's 1939
   // orphan-adoption — out of scope for MUST-FIX 2). The MODULE ports get the
@@ -797,6 +832,13 @@ export interface TeardownOpts {
     removedLaunchdMessage: (label: string) => string;
     removedSystemdMessage: (unitName: string) => string;
   }) => ManagedUnitRemoveResult;
+  /**
+   * Test seam: the stale-per-module-autostart disable (#522). Teardown also
+   * disables any leftover standalone module autostart unit so a rollback to
+   * foreground `serve` doesn't leave a competing module respawning at boot.
+   * Injectable so tests never touch real systemctl/launchctl.
+   */
+  disableStaleModuleUnits?: (opts?: DisableStaleModuleUnitsOpts) => DisableStaleModuleUnitsResult;
 }
 
 /**
@@ -815,6 +857,7 @@ export function teardownHubUnit(opts: TeardownOpts = {}): { removed: boolean; me
   const log = opts.log ?? ((line) => console.log(line));
   const deps = opts.deps ?? defaultHubUnitDeps;
   const remove = opts.remove ?? removeManagedUnit;
+  const disableStale = opts.disableStaleModuleUnits ?? disableStaleModuleUnits;
   const res = remove({
     launchdLabel: HUB_LAUNCHD_LABEL,
     systemdUnitName: HUB_SYSTEMD_UNIT_NAME,
@@ -824,6 +867,11 @@ export function teardownHubUnit(opts: TeardownOpts = {}): { removed: boolean; me
     removedSystemdMessage: (unitName) =>
       `Removed systemd unit ${unitName} — the hub no longer starts on boot.`,
   });
+  // #522: also disable any leftover standalone per-module autostart unit so a
+  // rollback to foreground `serve` doesn't leave a competing module respawning at
+  // boot to race whatever the operator brings up next. Ownership-safe (known
+  // module shorts only; hub + cloudflared skipped), idempotent, non-fatal.
+  disableStale({ deps, log });
   if (res.removed) {
     for (const m of res.messages) log(m);
     log("");

package/src/host-admin-token-validation.ts

@@ -0,0 +1,96 @@
+/**
+ * Issuer validation for the hub's OWN host-admin credentials (the operator
+ * token + the SPA host-admin token) on the loopback module-ops surfaces.
+ *
+ * ## Why this is its own helper (hub#516)
+ *
+ * The on-box CLI drives the hub on loopback (`127.0.0.1:1939`) presenting
+ * `~/.parachute/operator.token` — a hub-SELF-issued JWT (`aud: "operator"`,
+ * scope-set carries `parachute:host:admin`). After `parachute expose`, the
+ * operator token's `iss` is the hub's PUBLIC origin (e.g.
+ * `https://parachute.taildf9ce2.ts.net`), because §3.1 self-heals it there so
+ * on-box services validating public-origin bearers accept it.
+ *
+ * But the hub resolves its issuer PER-REQUEST from the Host header
+ * (`resolveIssuer` in hub-server.ts, "closes #245") — so a LOOPBACK request
+ * resolves the issuer to `http://127.0.0.1:1939`. The strict per-request
+ * `validateAccessToken(db, token, <loopback-issuer>)` then rejects the
+ * operator token's PUBLIC `iss` as `unexpected "iss" claim value`. Net:
+ * `parachute status` / `start|stop|restart <svc>` fail on ANY exposed box
+ * (tailnet or Cloudflare), even though the credential is the hub's own,
+ * presented on the hub's own loopback.
+ *
+ * ## The scoped relaxation
+ *
+ * The operator token (and the SPA host-admin token) are SELF-issued — the hub
+ * signs them with its own key, and {@link validateAccessToken} verifies that
+ * signature against the hub's JWKS. The signature already proves provenance:
+ * the only tokens that can verify are ones THIS hub minted. So for these
+ * host-admin credentials, the `iss` claim should be accepted if it matches ANY
+ * origin the hub legitimately answers on — loopback ∪ expose-state public
+ * origin ∪ platform/env origin — not just the single per-request one.
+ *
+ * We deliberately do NOT drop the `iss` check entirely (belt-and-suspenders):
+ * a token whose `iss` is none of the hub's known origins is still rejected,
+ * so a hypothetical hub-signed token minted for a DIFFERENT origin can't be
+ * replayed here.
+ *
+ * ## What this does NOT touch
+ *
+ * OAuth / access-token validation (vault / MCP tokens, `aud: "vault.<name>"`)
+ * stays STRICT per-request-issuer and lives on entirely separate code paths
+ * (the resource servers' own validators, hub's `/api/auth/*`, etc.). This
+ * helper is invoked ONLY from the two loopback host-admin module surfaces
+ * (`/api/modules` GET — the `status` read; `/api/modules/:short/*` POST — the
+ * lifecycle ops), both of which already gate on the non-requestable
+ * `parachute:host:admin` / `parachute:host:auth` scopes that no OAuth token
+ * can carry. The relaxation cannot reach an OAuth token's validation.
+ */
+import type { Database } from "bun:sqlite";
+import { type ValidatedAccessToken, validateAccessToken } from "./jwt-sign.ts";
+
+/**
+ * Validate a host-admin bearer (operator token / SPA host-admin token)
+ * presented on a loopback module surface, accepting its `iss` against the SET
+ * of origins the hub legitimately answers on rather than the single
+ * per-request issuer.
+ *
+ * Verification order:
+ *   1. Signature + `exp` + revocation, via {@link validateAccessToken} WITHOUT
+ *      an `expectedIssuer` — the signature proves the hub minted it (only this
+ *      hub's key can produce a JWS that verifies against its JWKS). A throw
+ *      here (bad/unknown/expired kid, jose `exp`, revoked jti) propagates
+ *      unchanged.
+ *   2. `iss` ∈ `knownIssuers` — belt-and-suspenders. Even though the signature
+ *      proves provenance, we still require the issuer to be one of the hub's
+ *      own origins. A foreign/garbage `iss` throws (matching the per-request
+ *      strict check's message shape so callers' error rendering is unchanged).
+ *
+ * `knownIssuers` is the hub's own valid origin set — typically built from
+ * `buildHubBoundOrigins` (per-request issuer ∪ loopback aliases ∪
+ * expose-state public origin ∪ platform/env origin). Empty/garbage entries are
+ * the caller's responsibility to filter; an empty set rejects every token
+ * (fails closed).
+ *
+ * @throws Error when the signature/exp/revocation check fails, or when `iss`
+ *   is absent / not a string / not in `knownIssuers`.
+ */
+export async function validateHostAdminToken(
+  db: Database,
+  token: string,
+  knownIssuers: readonly string[],
+): Promise<ValidatedAccessToken> {
+  // Step 1: signature + exp + revocation, NOT pinning iss. Provenance is
+  // proved by the signature verifying against the hub's own JWKS.
+  const validated = await validateAccessToken(db, token);
+
+  // Step 2: belt-and-suspenders iss ∈ known-origins. Never widen to arbitrary
+  // issuers — the token's iss must be one of the hub's own legitimate origins.
+  const iss = validated.payload.iss;
+  if (typeof iss !== "string" || !knownIssuers.includes(iss)) {
+    // Mirror jose's wording so the CLI's bearer-invalid error path renders the
+    // same way it did for the strict per-request check.
+    throw new Error('unexpected "iss" claim value');
+  }
+  return validated;
+}

package/src/hub-server.ts

@@ -1783,9 +1783,16 @@ export function hubFetch(
 
     if (pathname === "/api/modules") {
       if (!getDb) return dbNotConfigured();
+      const od = oauthDeps(req);
       const modulesDeps: Parameters<typeof handleApiModules>[1] = {
         db: getDb(),
-        issuer: oauthDeps(req).issuer,
+        issuer: od.issuer,
+        // hub#516: validate the host-admin bearer's `iss` against the SET of
+        // origins the hub answers on (loopback ∪ expose-state ∪ env/platform ∪
+        // per-request issuer), so `parachute status` works on an exposed box
+        // where the operator token carries the public origin but the loopback
+        // request resolves the loopback issuer.
+        knownIssuers: od.hubBoundOrigins(),
         manifestPath: deps?.manifestPath ?? SERVICES_MANIFEST_PATH,
       };
       if (deps?.supervisor !== undefined) modulesDeps.supervisor = deps.supervisor;
@@ -1841,9 +1848,13 @@ export function hubFetch(
       }
       const opId = decodeURIComponent(pathname.slice("/api/modules/operations/".length));
       if (!opId || opId.includes("/")) return new Response("not found", { status: 404 });
+      const od = oauthDeps(req);
       return handleOperationGet(req, opId, {
         db: getDb(),
-        issuer: oauthDeps(req).issuer,
+        issuer: od.issuer,
+        // hub#516: see the `/api/modules` deps note — the CLI polls async ops
+        // on loopback with the operator token (public `iss`).
+        knownIssuers: od.hubBoundOrigins(),
         manifestPath: deps?.manifestPath ?? SERVICES_MANIFEST_PATH,
         configDir: CONFIG_DIR,
         supervisor: deps.supervisor,
@@ -1888,9 +1899,14 @@ export function hubFetch(
       }
       const match = parseModulesPath(pathname);
       if (!match) return new Response("not found", { status: 404 });
+      const od = oauthDeps(req);
       const opsDeps = {
         db: getDb(),
-        issuer: oauthDeps(req).issuer,
+        issuer: od.issuer,
+        // hub#516: the CLI drives start/stop/restart/install/upgrade/uninstall
+        // on loopback with the operator token, whose `iss` is the hub's public
+        // origin after `expose`. Validate against the hub's known-origin set.
+        knownIssuers: od.hubBoundOrigins(),
         manifestPath: deps?.manifestPath ?? SERVICES_MANIFEST_PATH,
         configDir: CONFIG_DIR,
         supervisor: deps.supervisor,