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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.6.3-rc.2",
+  "version": "0.6.3-rc.4",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/api-modules-ops.test.ts

@@ -70,6 +70,36 @@ async function mintBearer(h: Harness, scopes: string[]): Promise<string> {
   return signed.token;
 }
 
+/**
+ * Mint a host-admin bearer at a chosen `iss` (hub#516). The CLI presents the
+ * operator token on loopback; after `expose` its `iss` is the public origin
+ * while the loopback request resolves the loopback issuer.
+ */
+async function mintBearerAtIssuer(h: Harness, scopes: string[], iss: string): Promise<string> {
+  const signed = await signAccessToken(h.db, {
+    sub: h.userId,
+    scopes,
+    audience: "operator",
+    clientId: "parachute-hub",
+    issuer: iss,
+    ttlSeconds: 3600,
+  });
+  recordTokenMint(h.db, {
+    jti: signed.jti,
+    createdVia: "operator_mint",
+    subject: "operator",
+    clientId: "parachute-hub",
+    scopes,
+    expiresAt: signed.expiresAt,
+  });
+  return signed.token;
+}
+
+/** The hub's public origin after `expose` — what the operator token's `iss` becomes. */
+const PUBLIC_ORIGIN = "https://parachute.taildf9ce2.ts.net";
+/** A foreign origin the hub never answers on. */
+const FOREIGN_ORIGIN = "https://evil.example.com";
+
 function postReq(path: string, headers: Record<string, string>): Request {
   return new Request(`http://localhost${path}`, { method: "POST", headers });
 }
@@ -967,6 +997,97 @@ describe("POST /api/modules/:short/stop", () => {
   });
 });
 
+/**
+ * hub#516 — the module-ops `authorize` accepts the operator token's `iss`
+ * against the SET of origins the hub answers on (knownIssuers), not just the
+ * single per-request issuer. Exercised through `handleStop` (the simplest sync
+ * op that goes through `authorize`). The per-request `issuer` here is loopback
+ * (mirroring a loopback CLI request); `knownIssuers` carries loopback + the
+ * public expose-state origin.
+ */
+describe("operator-token iss validation against knownIssuers (hub#516)", () => {
+  let h: Harness;
+  beforeEach(async () => {
+    h = await makeHarness();
+    _resetOperationsRegistryForTests();
+  });
+  afterEach(() => h.cleanup());
+
+  // The live repro: operator token's iss = PUBLIC origin, loopback request
+  // (per-request issuer = loopback), knownIssuers includes the public origin
+  // → ACCEPTED. Was rejected (`unexpected "iss" claim value`) pre-fix.
+  test("live repro: public-iss operator token on a loopback request → ACCEPTED", async () => {
+    const { supervisor } = makeIdleSupervisor();
+    const bearer = await mintBearerAtIssuer(h, [API_MODULES_OPS_REQUIRED_SCOPE], PUBLIC_ORIGIN);
+    const res = await handleStop(
+      postReq("/api/modules/vault/stop", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      {
+        db: h.db,
+        issuer: ISSUER, // loopback per-request issuer
+        knownIssuers: [ISSUER, "http://localhost:1939", PUBLIC_ORIGIN],
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        supervisor,
+      },
+    );
+    // Not a 401 — authorize passed. (stopped:false because nothing's running.)
+    expect(res.status).toBe(200);
+  });
+
+  test("loopback-iss operator token, loopback knownIssuers → accepted (unchanged)", async () => {
+    const { supervisor } = makeIdleSupervisor();
+    const bearer = await mintBearerAtIssuer(h, [API_MODULES_OPS_REQUIRED_SCOPE], ISSUER);
+    const res = await handleStop(
+      postReq("/api/modules/vault/stop", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      {
+        db: h.db,
+        issuer: ISSUER,
+        knownIssuers: [ISSUER, "http://localhost:1939"],
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        supervisor,
+      },
+    );
+    expect(res.status).toBe(200);
+  });
+
+  test("FOREIGN-iss operator token → 401 (no widening to arbitrary issuers)", async () => {
+    const { supervisor } = makeIdleSupervisor();
+    const bearer = await mintBearerAtIssuer(h, [API_MODULES_OPS_REQUIRED_SCOPE], FOREIGN_ORIGIN);
+    const res = await handleStop(
+      postReq("/api/modules/vault/stop", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      {
+        db: h.db,
+        issuer: ISSUER,
+        knownIssuers: [ISSUER, "http://localhost:1939", PUBLIC_ORIGIN],
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        supervisor,
+      },
+    );
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error_description: string };
+    expect(body.error_description).toMatch(/unexpected "iss" claim value/);
+  });
+
+  test("knownIssuers absent → falls back to strict per-request issuer (back-compat)", async () => {
+    const { supervisor } = makeIdleSupervisor();
+    // Public-iss token, loopback per-request issuer, NO knownIssuers wired →
+    // the strict single-issuer fallback rejects (the pre-fix behavior the
+    // non-HTTP install path relies on).
+    const bearer = await mintBearerAtIssuer(h, [API_MODULES_OPS_REQUIRED_SCOPE], PUBLIC_ORIGIN);
+    const res = await handleStop(
+      postReq("/api/modules/vault/stop", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      { db: h.db, issuer: ISSUER, manifestPath: h.manifestPath, configDir: h.dir, supervisor },
+    );
+    expect(res.status).toBe(401);
+  });
+});
+
 describe("POST /api/modules/:short/restart", () => {
   let h: Harness;
   beforeEach(async () => {

package/src/__tests__/api-modules.test.ts

@@ -63,6 +63,32 @@ async function mintBearer(h: Harness, scopes: string[]): Promise<string> {
   return signed.token;
 }
 
+/** The hub's public origin after `expose` — what the operator token's `iss` becomes (hub#516). */
+const PUBLIC_ORIGIN = "https://parachute.taildf9ce2.ts.net";
+/** A foreign origin the hub never answers on (hub#516). */
+const FOREIGN_ORIGIN = "https://evil.example.com";
+
+/** Mint a host-admin (operator-shaped) bearer at a chosen `iss` (hub#516). */
+async function mintBearerAtIssuer(h: Harness, scopes: string[], iss: string): Promise<string> {
+  const signed = await signAccessToken(h.db, {
+    sub: h.userId,
+    scopes,
+    audience: "operator",
+    clientId: "parachute-hub",
+    issuer: iss,
+    ttlSeconds: 3600,
+  });
+  recordTokenMint(h.db, {
+    jti: signed.jti,
+    createdVia: "operator_mint",
+    subject: "operator",
+    clientId: "parachute-hub",
+    scopes,
+    expiresAt: signed.expiresAt,
+  });
+  return signed.token;
+}
+
 function writeManifest(path: string, services: unknown[]): void {
   writeFileSync(path, JSON.stringify({ services }));
 }
@@ -147,6 +173,47 @@ describe("GET /api/modules", () => {
     expect(body.error).toBe("insufficient_scope");
   });
 
+  // hub#516: `parachute status` reads /api/modules on loopback presenting the
+  // operator token, whose `iss` is the PUBLIC origin after `expose`. The
+  // host-admin bearer's iss is validated against `knownIssuers` (loopback ∪
+  // expose-state public ∪ env), not the single per-request loopback issuer.
+  test("live repro: public-iss operator token on a loopback request → 200 (hub#516)", async () => {
+    const bearer = await mintBearerAtIssuer(h, [API_MODULES_REQUIRED_SCOPE], PUBLIC_ORIGIN);
+    const res = await handleApiModules(getReq({ authorization: `Bearer ${bearer}` }), {
+      db: h.db,
+      issuer: ISSUER, // loopback per-request issuer
+      knownIssuers: [ISSUER, "http://localhost:1939", PUBLIC_ORIGIN],
+      manifestPath: h.manifestPath,
+      fetchLatestVersion: async () => null,
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("FOREIGN-iss operator token → 401 (no widening) (hub#516)", async () => {
+    const bearer = await mintBearerAtIssuer(h, [API_MODULES_REQUIRED_SCOPE], FOREIGN_ORIGIN);
+    const res = await handleApiModules(getReq({ authorization: `Bearer ${bearer}` }), {
+      db: h.db,
+      issuer: ISSUER,
+      knownIssuers: [ISSUER, "http://localhost:1939", PUBLIC_ORIGIN],
+      manifestPath: h.manifestPath,
+      fetchLatestVersion: async () => null,
+    });
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error_description: string };
+    expect(body.error_description).toMatch(/unexpected "iss" claim value/);
+  });
+
+  test("knownIssuers absent → strict per-request issuer fallback rejects public-iss (hub#516)", async () => {
+    const bearer = await mintBearerAtIssuer(h, [API_MODULES_REQUIRED_SCOPE], PUBLIC_ORIGIN);
+    const res = await handleApiModules(getReq({ authorization: `Bearer ${bearer}` }), {
+      db: h.db,
+      issuer: ISSUER, // no knownIssuers → falls back to [issuer]
+      manifestPath: h.manifestPath,
+      fetchLatestVersion: async () => null,
+    });
+    expect(res.status).toBe(401);
+  });
+
   test("200 + curated list on fresh container (empty services.json)", async () => {
     // The v0.6 hot path: brand-new Render container, no services.json
     // yet. UI must render "install vault / scribe" cards even though

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

@@ -0,0 +1,218 @@
+/**
+ * hub#516 — `validateHostAdminToken` accepts the operator / SPA host-admin
+ * token's `iss` against the SET of origins the hub answers on (loopback ∪
+ * expose-state public ∪ env/platform), not the single per-request issuer, so
+ * the loopback CLI works on an exposed box. OAuth-token validation
+ * (`validateAccessToken` with a pinned `expectedIssuer`) is NOT touched — see
+ * the strict-iss regression at the bottom of this file.
+ */
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { validateHostAdminToken } from "../host-admin-token-validation.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { recordTokenMint, signAccessToken, validateAccessToken } from "../jwt-sign.ts";
+import { rotateSigningKey } from "../signing-keys.ts";
+import { createUser } from "../users.ts";
+
+const LOOPBACK = "http://127.0.0.1:1939";
+const PUBLIC_TS = "https://parachute.taildf9ce2.ts.net";
+const FOREIGN = "https://evil.example.com";
+
+interface H {
+  db: ReturnType<typeof openHubDb>;
+  userId: string;
+  cleanup: () => void;
+}
+
+async function makeH(): Promise<H> {
+  const dir = mkdtempSync(join(tmpdir(), "phub-host-admin-tok-"));
+  const db = openHubDb(hubDbPath(dir));
+  rotateSigningKey(db);
+  const user = await createUser(db, "owner", "pw");
+  return {
+    db,
+    userId: user.id,
+    cleanup: () => {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+/** Mint an operator-shaped token (aud: "operator", host:admin) at `iss`. */
+async function mintOperatorAt(h: H, iss: string): Promise<string> {
+  const signed = await signAccessToken(h.db, {
+    sub: h.userId,
+    scopes: ["parachute:host:admin", "parachute:host:auth"],
+    audience: "operator",
+    clientId: "parachute-hub",
+    issuer: iss,
+    ttlSeconds: 3600,
+  });
+  recordTokenMint(h.db, {
+    jti: signed.jti,
+    createdVia: "operator_mint",
+    subject: "operator",
+    clientId: "parachute-hub",
+    scopes: ["parachute:host:admin", "parachute:host:auth"],
+    expiresAt: signed.expiresAt,
+  });
+  return signed.token;
+}
+
+describe("validateHostAdminToken (hub#516)", () => {
+  // The live repro: operator token minted with the PUBLIC origin as `iss`,
+  // presented on a LOOPBACK request (known-origins set built from the loopback
+  // per-request issuer + the expose-state public origin) → ACCEPTED.
+  test("live repro: public-iss operator token accepted when public origin is in the known set", async () => {
+    const h = await makeH();
+    try {
+      const token = await mintOperatorAt(h, PUBLIC_TS);
+      const knownIssuers = [LOOPBACK, "http://localhost:1939", PUBLIC_TS];
+      const { payload } = await validateHostAdminToken(h.db, token, knownIssuers);
+      expect(payload.iss).toBe(PUBLIC_TS);
+      expect(payload.sub).toBe(h.userId);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("loopback-iss operator token, loopback known set → accepted (unchanged)", async () => {
+    const h = await makeH();
+    try {
+      const token = await mintOperatorAt(h, LOOPBACK);
+      const { payload } = await validateHostAdminToken(h.db, token, [
+        LOOPBACK,
+        "http://localhost:1939",
+      ]);
+      expect(payload.iss).toBe(LOOPBACK);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("FOREIGN iss → REJECTED (no widening to arbitrary issuers)", async () => {
+    const h = await makeH();
+    try {
+      // A token the hub itself signed but whose iss is NOT one of its known
+      // origins. The signature verifies, but the belt-and-suspenders iss ∈
+      // known-origins check must still reject it.
+      const token = await mintOperatorAt(h, FOREIGN);
+      const knownIssuers = [LOOPBACK, "http://localhost:1939", PUBLIC_TS];
+      await expect(validateHostAdminToken(h.db, token, knownIssuers)).rejects.toThrow(
+        /unexpected "iss" claim value/,
+      );
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("empty known-origins set rejects every token (fails closed)", async () => {
+    const h = await makeH();
+    try {
+      const token = await mintOperatorAt(h, LOOPBACK);
+      await expect(validateHostAdminToken(h.db, token, [])).rejects.toThrow(
+        /unexpected "iss" claim value/,
+      );
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("expose-state absent (loopback-only set): public-iss token rejected; loopback-iss accepted", async () => {
+    const h = await makeH();
+    try {
+      // Before `expose`, the known set is loopback-only — a public-iss token
+      // shouldn't exist yet, and if presented, it's not in the set → reject.
+      const publicTok = await mintOperatorAt(h, PUBLIC_TS);
+      const loopbackOnly = [LOOPBACK, "http://localhost:1939"];
+      await expect(validateHostAdminToken(h.db, publicTok, loopbackOnly)).rejects.toThrow(
+        /unexpected "iss" claim value/,
+      );
+
+      const loopbackTok = await mintOperatorAt(h, LOOPBACK);
+      const { payload } = await validateHostAdminToken(h.db, loopbackTok, loopbackOnly);
+      expect(payload.iss).toBe(LOOPBACK);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("signature still enforced: a token signed by an unknown key is rejected", async () => {
+    const h = await makeH();
+    try {
+      // Mint against a SECOND hub's key, then try to validate against the
+      // first hub's JWKS. The known-origins set includes the iss, but the
+      // signature check (step 1) must reject it before iss is even considered.
+      const other = await makeH();
+      try {
+        const foreignSigned = await mintOperatorAt(other, PUBLIC_TS);
+        await expect(validateHostAdminToken(h.db, foreignSigned, [PUBLIC_TS])).rejects.toThrow();
+      } finally {
+        other.cleanup();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  // Host-injection defense, made explicit. Simulate an attacker who got their
+  // own issuer into the known-issuers set via a forged Host header (the set is
+  // built from the per-request Host-derived issuer, so `iss ∈ knownIssuers`
+  // holds). They present a token signed by a DIFFERENT hub's key whose `iss`
+  // is exactly that injected origin. It is STILL REJECTED — the signature /
+  // JWKS check (step 1) fails before the `iss ∈ knownIssuers` check (step 2)
+  // is ever reached. This pins that known-issuers acceptance can never bypass
+  // the signature gate: membership in the set is necessary but not sufficient.
+  test("Host-injection: foreign-signed token with iss IN knownIssuers is STILL rejected (signature gate is first)", async () => {
+    const h = await makeH();
+    try {
+      const other = await makeH();
+      try {
+        // Token minted + signed by the OTHER hub at PUBLIC_TS.
+        const foreignSigned = await mintOperatorAt(other, PUBLIC_TS);
+        // The attacker's iss IS in our known set (e.g. injected via Host), yet
+        // validation against OUR JWKS must reject it on the signature check.
+        const knownIssuers = [LOOPBACK, "http://localhost:1939", PUBLIC_TS];
+        expect(knownIssuers).toContain(PUBLIC_TS); // precondition: iss ∈ knownIssuers
+        await expect(validateHostAdminToken(h.db, foreignSigned, knownIssuers)).rejects.toThrow();
+      } finally {
+        other.cleanup();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  // Pin the invariant: OAuth/access-token validation stays STRICT per-request
+  // issuer. The relaxation lives only in validateHostAdminToken; the core
+  // primitive validateAccessToken(db, token, expectedIssuer) still rejects a
+  // mismatched iss. (Mirrors jwt-sign.test.ts's defense-in-depth test; kept
+  // here so the hub#516 guard travels with the relaxation.)
+  test("OAuth-token validation UNCHANGED: validateAccessToken pins iss strictly", async () => {
+    const h = await makeH();
+    try {
+      // A vault-aud OAuth-shaped token minted at the public origin.
+      const signed = await signAccessToken(h.db, {
+        sub: h.userId,
+        scopes: ["vault:read"],
+        audience: "vault.default",
+        clientId: "some-mcp-client",
+        issuer: PUBLIC_TS,
+        ttlSeconds: 3600,
+      });
+      // Strict per-request validation against a DIFFERENT (loopback) issuer
+      // still rejects — the relaxation must NOT leak to this path.
+      await expect(validateAccessToken(h.db, signed.token, LOOPBACK)).rejects.toThrow(
+        /unexpected "iss" claim value/,
+      );
+      // And it accepts when the issuer matches (sanity).
+      const { payload } = await validateAccessToken(h.db, signed.token, PUBLIC_TS);
+      expect(payload.aud).toBe("vault.default");
+    } finally {
+      h.cleanup();
+    }
+  });
+});

package/src/__tests__/managed-unit.test.ts

@@ -429,10 +429,13 @@ describe("buildHubManagedUnit — §4.1 hub-unit shape", () => {
     expect(() => hubUnit(f.deps)).toThrow(/'bun' not found on PATH/);
   });
 
-  test("env carries the 4 vars and INTENTIONALLY OMITS PARACHUTE_HUB_ORIGIN", () => {
+  test("env carries the 5 vars and INTENTIONALLY OMITS PARACHUTE_HUB_ORIGIN", () => {
     const f = fakeDeps({ platform: "linux" });
     const unit = hubUnit(f.deps);
     expect(unit.env).toEqual({
+      // Forced loopback (security): a self-hosted supervised hub must NOT inherit
+      // serve.ts's container-first 0.0.0.0 default and bare-serve all-interfaces.
+      PARACHUTE_BIND_HOST: "127.0.0.1",
       PARACHUTE_HOME: "/home/op/.parachute",
       PORT: "1939",
       PATH: "/home/op/.bun/bin:/usr/local/bin:/usr/bin:/bin",
@@ -441,6 +444,17 @@ describe("buildHubManagedUnit — §4.1 hub-unit shape", () => {
     expect(unit.env.PARACHUTE_HUB_ORIGIN).toBeUndefined();
   });
 
+  test("env forces PARACHUTE_BIND_HOST=127.0.0.1 (loopback trust model — never 0.0.0.0)", () => {
+    const f = fakeDeps({ platform: "linux" });
+    const unit = hubUnit(f.deps);
+    // The whole point of the fix: the supervised hub unit binds loopback, NOT
+    // the serve.ts container-first 0.0.0.0 default. Covers both init + migrate
+    // (both route through buildHubManagedUnit) and both platforms (the env is
+    // platform-agnostic; systemd/launchd render shapes are asserted below).
+    expect(unit.env.PARACHUTE_BIND_HOST).toBe("127.0.0.1");
+    expect(unit.env.PARACHUTE_BIND_HOST).not.toBe("0.0.0.0");
+  });
+
   test("PARACHUTE_HOME is the captured param, NOT the default (§4.2)", () => {
     const f = fakeDeps({ platform: "linux" });
     const unit = buildHubManagedUnit({
@@ -468,11 +482,14 @@ describe("buildHubManagedUnit — §4.1 hub-unit shape", () => {
     expect(unit.env.PORT).toBe("2939");
   });
 
-  test("rendered systemd SYSTEM unit: 4 Environment= vars, User= present, StartLimit present", () => {
+  test("rendered systemd SYSTEM unit: 5 Environment= vars, User= present, StartLimit present", () => {
     const f = fakeDeps({ platform: "linux", getuid: () => 0, userName: () => "op" });
     const unit = renderManagedSystemdUnit(hubUnit(f.deps), { root: true, userName: "op" });
     expect(unit).toContain("Description=Parachute hub (serve + supervisor)");
     expect(unit).toContain("User=op");
+    // Forced loopback bind (security): the supervised hub must bind 127.0.0.1.
+    expect(unit).toContain("Environment=PARACHUTE_BIND_HOST=127.0.0.1");
+    expect(unit).not.toContain("PARACHUTE_BIND_HOST=0.0.0.0");
     expect(unit).toContain("Environment=PARACHUTE_HOME=/home/op/.parachute");
     expect(unit).toContain("Environment=PORT=1939");
     expect(unit).toContain("Environment=PATH=/home/op/.bun/bin:/usr/local/bin:/usr/bin:/bin");
@@ -494,7 +511,7 @@ describe("buildHubManagedUnit — §4.1 hub-unit shape", () => {
     expect(unit).toContain("WantedBy=default.target");
   });
 
-  test("rendered launchd plist: EnvironmentVariables dict (4 vars) + ThrottleInterval + abs ProgramArguments", () => {
+  test("rendered launchd plist: EnvironmentVariables dict (5 vars) + ThrottleInterval + abs ProgramArguments", () => {
     const f = fakeDeps({ platform: "darwin" });
     const plist = renderManagedLaunchdPlist(hubUnit(f.deps));
     expect(plist).toContain("<key>Label</key>\n  <string>computer.parachute.hub</string>");
@@ -502,6 +519,9 @@ describe("buildHubManagedUnit — §4.1 hub-unit shape", () => {
     expect(plist).toContain("<string>/home/op/parachute-hub/src/cli.ts</string>");
     expect(plist).toContain("<string>serve</string>");
     expect(plist).toContain("<key>EnvironmentVariables</key>");
+    // Forced loopback bind (security): the supervised hub must bind 127.0.0.1.
+    expect(plist).toContain("<key>PARACHUTE_BIND_HOST</key>\n    <string>127.0.0.1</string>");
+    expect(plist).not.toContain("<string>0.0.0.0</string>");
     expect(plist).toContain("<key>PARACHUTE_HOME</key>\n    <string>/home/op/.parachute</string>");
     expect(plist).toContain("<key>PORT</key>\n    <string>1939</string>");
     expect(plist).toContain("<key>BUN_INSTALL</key>\n    <string>/home/op/.bun</string>");

package/src/__tests__/migrate-cutover.test.ts

@@ -122,6 +122,12 @@ function makeFakeCutover(over: Partial<CutoverDeps> = {}): FakeCutover {
         messages: ["started unit"],
       };
     },
+    // Hermetic default: the stale-unit disable is a no-op (no real
+    // systemctl/launchctl). Tests that exercise #522 override this to trace + act.
+    disableStaleModuleUnits: () => {
+      trace.push("disableStaleUnits");
+      return { actions: [] };
+    },
     ...over,
   };
   // Expose the world via closure for tests that want to manipulate it.
@@ -184,6 +190,43 @@ describe("cutoverToSupervised — happy path (§7.1)", () => {
     }
   });
 
+  test("#522: stale-unit disable runs in the STOP phase — after detached stop, before unit start", async () => {
+    const h = makeHarness();
+    try {
+      seedManifest(h.manifestPath, [{ name: "vault", port: 1940 }]);
+      const fc = makeFakeCutover();
+      const w = getWorld(fc.deps);
+      w.listening.add(1939);
+      w.listening.add(1940);
+      w.alivePids.add(5555);
+      writePid("vault", 5555, h.configDir);
+      const baseKill = fc.deps.kill;
+      fc.deps.kill = (pid, signal) => {
+        baseKill?.(pid, signal);
+        if (pid === 5555) getWorld(fc.deps).listening.delete(1940);
+      };
+      const result = await cutoverToSupervised({
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        deps: fc.deps,
+        log: () => {},
+        pollMs: 0,
+      });
+      expect(result.outcome).toBe("migrated");
+      const stopIdx = fc.trace.indexOf("stopHub");
+      const disableIdx = fc.trace.indexOf("disableStaleUnits");
+      const startIdx = fc.trace.indexOf("startUnit");
+      // The disable runs AFTER the detached stop and BEFORE the unit start, so a
+      // KeepAlive/Restart=always unit can't re-grab the port between freeing it
+      // and the supervised module binding it.
+      expect(disableIdx).toBeGreaterThanOrEqual(0);
+      expect(stopIdx).toBeLessThan(disableIdx);
+      expect(disableIdx).toBeLessThan(startIdx);
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("verify-ports-free runs before start (start never races a held port)", async () => {
     const h = makeHarness();
     try {
@@ -443,6 +486,7 @@ describe("cutoverToSupervised — fail-safe recovery states", () => {
 describe("teardownHubUnit (§7.4)", () => {
   test("removes the hub unit (idempotent success path)", () => {
     let removeArgs: { launchdLabel: string; systemdUnitName: string } | undefined;
+    let staleCalled = false;
     const log: string[] = [];
     const res = teardownHubUnit({
       log: (l) => log.push(l),
@@ -450,21 +494,36 @@ describe("teardownHubUnit (§7.4)", () => {
         removeArgs = { launchdLabel: opts.launchdLabel, systemdUnitName: opts.systemdUnitName };
         return { removed: true, messages: [opts.removedSystemdMessage(opts.systemdUnitName)] };
       },
+      // Hermetic stub — no real systemctl/launchctl.
+      disableStaleModuleUnits: () => {
+        staleCalled = true;
+        return { actions: [] };
+      },
     });
     expect(res.removed).toBe(true);
     expect(removeArgs?.launchdLabel).toBe("computer.parachute.hub");
     expect(removeArgs?.systemdUnitName).toBe("parachute-hub.service");
+    // #522: teardown also runs the stale-per-module-autostart disable.
+    expect(staleCalled).toBe(true);
     // Surfaces the fallback hint.
     expect(log.join("\n")).toContain("parachute serve");
   });
 
-  test("no unit installed → no-op, friendly message", () => {
+  test("no unit installed → no-op, friendly message (still runs the stale-unit disable)", () => {
+    let staleCalled = false;
     const log: string[] = [];
     const res = teardownHubUnit({
       log: (l) => log.push(l),
       remove: (): ManagedUnitRemoveResult => ({ removed: false, messages: [] }),
+      disableStaleModuleUnits: () => {
+        staleCalled = true;
+        return { actions: [] };
+      },
     });
     expect(res.removed).toBe(false);
+    // #522: a leftover module autostart must be cleaned even when the hub unit was
+    // never installed (a partial / never-migrated box rolling back).
+    expect(staleCalled).toBe(true);
     expect(log.join("\n")).toContain("nothing to tear down");
   });
 });