@openparachute/hub 0.7.5 → 0.7.6-rc.3

package/package.json

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

package/src/__tests__/admin-module-token.test.ts

@@ -7,7 +7,7 @@
  *   - 401 when the cookie names a deleted session.
  *   - 405 on POST.
  *   - 200 + JWT carrying `aud: "<short>"` and `<short>:admin` for known modules
- *     (scribe / runner / surface).
+ *     (scribe / surface / agent).
  *   - 400 for `vault` (per-instance — points at /admin/vault-admin-token/<name>).
  *   - 404 for an unknown short.
  *   - First-admin gate: 403 for a signed-in non-first-admin (friend).
@@ -111,8 +111,10 @@ describe("handleModuleToken", () => {
   });
 
   // The known single-audience modules the generic mint serves. Each gets
-  // `<short>:admin` with `aud: <short>`.
-  for (const short of ["scribe", "runner", "surface", "agent"]) {
+  // `<short>:admin` with `aud: <short>`. (runner left this set with its
+  // 2026-07-01 registry removal — a LEGACY install still mints via the
+  // self-registration gate, pinned below.)
+  for (const short of ["scribe", "surface", "agent"]) {
     test(`200 mints a JWT carrying aud:${short} + ${short}:admin`, async () => {
       const { cookie, userId } = await withSession();
       rotateSigningKey(harness.db);
@@ -201,6 +203,41 @@ describe("handleModuleToken", () => {
     return dir;
   }
 
+  test("200 mints for a LEGACY runner install via the self-registration gate (registry removal 2026-07-01)", async () => {
+    // runner is no longer a known short, so path 2 (bootstrap registry) is
+    // gone — but an existing install that self-registered (row + module.json)
+    // keeps minting `runner:admin` through path 1, exactly like a third-party
+    // module. Its config UI keeps working post-removal.
+    const { cookie } = await withSession();
+    rotateSigningKey(harness.db);
+    const installDir = writeManifestDir("parachute-runner");
+    try {
+      const services: ServiceEntry[] = [
+        {
+          name: "parachute-runner",
+          port: 1945,
+          paths: ["/runner"],
+          health: "/runner/healthz",
+          version: "0.2.0",
+          installDir,
+        },
+      ];
+      // The row matches by its literal services.json name (the third-party
+      // convention) — `runner` the bare short no longer resolves anywhere.
+      const req = new Request(urlFor("parachute-runner"), { headers: { cookie } });
+      const res = await handleModuleToken(req, "parachute-runner", depsWith(services));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { scopes: string[] };
+      expect(body.scopes).toEqual(["parachute-runner:admin"]);
+      // The bare `runner` short 404s — nothing known + no row named "runner".
+      const bareReq = new Request(urlFor("runner"), { headers: { cookie } });
+      const bareRes = await handleModuleToken(bareReq, "runner", depsWith(services));
+      expect(bareRes.status).toBe(404);
+    } finally {
+      rmSync(installDir, { recursive: true, force: true });
+    }
+  });
+
   test("200 mints for a self-registered third-party module (row + readable module.json)", async () => {
     const { cookie, userId } = await withSession();
     rotateSigningKey(harness.db);

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

@@ -218,9 +218,9 @@ describe("parseModulesPath", () => {
       short: "agent",
       rest: "install",
     });
-    // Other known modules (runner / surface) resolve too.
-    expect(parseModulesPath("/api/modules/runner/install")).toEqual({
-      short: "runner",
+    // Other known modules (surface) resolve too.
+    expect(parseModulesPath("/api/modules/surface/install")).toEqual({
+      short: "surface",
       rest: "install",
     });
   });
@@ -231,6 +231,11 @@ describe("parseModulesPath", () => {
     // module-ops switch never acts on them.
     expect(parseModulesPath("/api/modules/hub/install")).toBeUndefined();
     expect(parseModulesPath("/api/modules/random/install")).toBeUndefined();
+    // runner left the registries on 2026-07-01 — module-ops no longer
+    // addresses it by short, same as any third-party module. (A legacy
+    // install still boots under `parachute serve` via its installDir; see
+    // serve-boot tests.)
+    expect(parseModulesPath("/api/modules/runner/install")).toBeUndefined();
   });
 
   test("rejects malformed paths", () => {

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

@@ -222,10 +222,11 @@ describe("GET /api/modules", () => {
     // by the UNION of the bootstrap registries (KNOWN_MODULES ∪
     // FIRST_PARTY_FALLBACKS), NOT a curated whitelist. Every known module
     // surfaces — core (vault/scribe/surface) in the headline tier, agent as
-    // `experimental`, and notes/runner as `deprecated` (2026-06-25, still
+    // `experimental`, and notes as `deprecated` (2026-06-25, still
     // resolvable but not offered for fresh installs) — so the agent-not-installed
     // class (running but invisible) can't recur while deprecated modules stop
-    // being pushed on a fresh box.
+    // being pushed on a fresh box. runner left the registries entirely on
+    // 2026-07-01 and must NOT surface on a fresh catalog.
     const bearer = await mintBearer(h, [API_MODULES_REQUIRED_SCOPE]);
     const res = await handleApiModules(getReq({ authorization: `Bearer ${bearer}` }), {
       db: h.db,
@@ -250,31 +251,31 @@ describe("GET /api/modules", () => {
     // ahead of every experimental module, which lead the deprecated ones.
     expect(shorts.indexOf("vault")).toBeLessThan(shorts.indexOf("scribe"));
     expect(shorts.indexOf("scribe")).toBeLessThan(shorts.indexOf("agent"));
-    // agent (experimental) sorts ahead of notes/runner (deprecated).
-    expect(shorts.indexOf("agent")).toBeLessThan(shorts.indexOf("runner"));
+    // agent (experimental) sorts ahead of notes (deprecated).
     expect(shorts.indexOf("agent")).toBeLessThan(shorts.indexOf("notes"));
     // Every known module is discoverable — vault/scribe/surface (core),
-    // agent (experimental), notes/runner (deprecated).
-    for (const s of ["vault", "scribe", "surface", "agent", "runner", "notes"]) {
+    // agent (experimental), notes (deprecated). runner is gone (2026-07-01
+    // registry removal) — a fresh box never sees it.
+    for (const s of ["vault", "scribe", "surface", "agent", "notes"]) {
       expect(shorts).toContain(s);
     }
+    expect(shorts).not.toContain("runner");
+    expect(shorts).not.toContain("parachute-runner");
     // Focus tier resolves from the default map.
     const byShort = new Map(body.modules.map((m) => [m.short, m]));
     expect(byShort.get("vault")?.focus).toBe("core");
     expect(byShort.get("scribe")?.focus).toBe("core");
     expect(byShort.get("surface")?.focus).toBe("core");
     expect(byShort.get("agent")?.focus).toBe("experimental");
-    expect(byShort.get("runner")?.focus).toBe("deprecated");
     expect(byShort.get("notes")?.focus).toBe("deprecated");
     // `available` stays true for every known module (re-installable), but the
     // fresh-install OFFER (`available_to_install`) drops the deprecated tier —
-    // notes/runner aren't pushed on a fresh box; agent (experimental) still is.
+    // notes isn't pushed on a fresh box; agent (experimental) still is.
     expect(body.modules.every((m) => m.available)).toBe(true);
     expect(byShort.get("vault")?.available_to_install).toBe(true);
     expect(byShort.get("scribe")?.available_to_install).toBe(true);
     expect(byShort.get("surface")?.available_to_install).toBe(true);
     expect(byShort.get("agent")?.available_to_install).toBe(true);
-    expect(byShort.get("runner")?.available_to_install).toBe(false);
     expect(byShort.get("notes")?.available_to_install).toBe(false);
     expect(body.modules.every((m) => !m.installed)).toBe(true);
     expect(body.modules.every((m) => m.latest_version === "0.9.9")).toBe(true);
@@ -282,11 +283,13 @@ describe("GET /api/modules", () => {
     expect(body.supervisor_available).toBe(false);
   });
 
-  test("an installed deprecated module (runner) still surfaces for management but is not offered for fresh install (2026-06-25)", async () => {
-    // A legacy operator with runner on disk: the row must remain visible
-    // (installed: true) + manageable, in the `deprecated` tier — but
-    // `available_to_install` is false so the SPA's install catalog won't push
-    // it. Mirrors the notes-daemon back-compat posture.
+  test("an installed LEGACY runner row still surfaces as a third-party row post-registry-removal (2026-07-01)", async () => {
+    // A legacy operator with runner on disk: post-removal the row no longer
+    // resolves to a known short, so it surfaces under its own manifest name
+    // (`parachute-runner`) exactly like a third-party module — visible
+    // (installed: true), never offered (`available` false: no install package
+    // known to the hub), and NEVER crashes the catalog. This is the graceful
+    // existing-install posture the removal preserves.
     writeManifest(h.manifestPath, [
       {
         name: "parachute-runner",
@@ -313,13 +316,18 @@ describe("GET /api/modules", () => {
         available_to_install: boolean;
       }>;
     };
-    const runner = body.modules.find((m) => m.short === "runner");
+    // No known short resolves anymore — the row surfaces under its own
+    // manifest name, the third-party fallback convention.
+    expect(body.modules.find((m) => m.short === "runner")).toBeUndefined();
+    const runner = body.modules.find((m) => m.short === "parachute-runner");
     expect(runner).toBeDefined();
     expect(runner?.installed).toBe(true);
     expect(runner?.installed_version).toBe("0.2.0");
-    expect(runner?.focus).toBe("deprecated");
-    // Still hub-installable (re-install path) but NOT offered fresh.
-    expect(runner?.available).toBe(true);
+    // Unlisted shorts default to the experimental tier (no special-casing
+    // survives the removal).
+    expect(runner?.focus).toBe("experimental");
+    // No install package known to the hub → not installable, never offered.
+    expect(runner?.available).toBe(false);
     expect(runner?.available_to_install).toBe(false);
   });
 

package/src/__tests__/connections-store.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Tests for the connections registry store (`connections.json`,
+ * `connections-store.ts`). The store's behavior is otherwise exercised
+ * indirectly through `admin-connections.test.ts`; this file pins the on-disk
+ * shape directly — specifically the `version` field added 2026-07-01 (the
+ * future-migration seam) and the legacy-file tolerance that makes it safe.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  CONNECTIONS_FILE_VERSION,
+  type ConnectionRecord,
+  getConnection,
+  putConnection,
+  readConnections,
+  removeConnection,
+} from "../connections-store.ts";
+
+let dir: string;
+let storePath: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "phub-connections-store-"));
+  storePath = join(dir, "connections.json");
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function rec(over: Partial<ConnectionRecord> = {}): ConnectionRecord {
+  return {
+    id: over.id ?? "conn-1",
+    source: over.source ?? { module: "vault", vault: "default", event: "note.created" },
+    sink: over.sink ?? { module: "agent", action: "message.deliver" },
+    provisioned: over.provisioned ?? { type: "vault-trigger", triggerName: "t1", vault: "default" },
+    createdAt: over.createdAt ?? "2026-07-01T00:00:00.000Z",
+  };
+}
+
+describe("file versioning (2026-07-01 — future-migration seam)", () => {
+  test("every write stamps version: 1 and put → read round-trips", () => {
+    putConnection(storePath, rec());
+    const onDisk = JSON.parse(readFileSync(storePath, "utf8")) as { version?: unknown };
+    expect(onDisk.version).toBe(CONNECTIONS_FILE_VERSION);
+    expect(onDisk.version).toBe(1);
+    const back = readConnections(storePath);
+    expect(back).toHaveLength(1);
+    expect(back[0]).toEqual(rec());
+    // Rewrites (upsert + remove) keep stamping it.
+    putConnection(storePath, rec({ id: "conn-2" }));
+    removeConnection(storePath, "conn-1");
+    const after = JSON.parse(readFileSync(storePath, "utf8")) as {
+      version?: unknown;
+      connections: unknown[];
+    };
+    expect(after.version).toBe(1);
+    expect(after.connections).toHaveLength(1);
+  });
+
+  test("a LEGACY file without version loads fine (treated as v1)", () => {
+    const legacy = rec();
+    writeFileSync(storePath, JSON.stringify({ connections: [legacy] }));
+    const back = readConnections(storePath);
+    expect(back).toHaveLength(1);
+    expect(back[0]).toEqual(legacy);
+    expect(getConnection(storePath, legacy.id)?.id).toBe(legacy.id);
+    // First write-through upgrades the file to the versioned shape without
+    // losing the legacy record.
+    putConnection(storePath, rec({ id: "conn-2" }));
+    const upgraded = JSON.parse(readFileSync(storePath, "utf8")) as {
+      version?: unknown;
+      connections: unknown[];
+    };
+    expect(upgraded.version).toBe(1);
+    expect(upgraded.connections).toHaveLength(2);
+  });
+
+  test("a missing or garbage file still reads as empty (fresh hub)", () => {
+    expect(readConnections(storePath)).toEqual([]);
+    writeFileSync(storePath, "not-json{");
+    expect(readConnections(storePath)).toEqual([]);
+  });
+});

package/src/__tests__/doctor.test.ts

@@ -753,3 +753,134 @@ describe("doctor --fix — canonical-port repair (confirm-gated, idempotent, non
     }
   });
 });
+
+describe("doctor — loopback-hijack check (hub#737)", () => {
+  test("no hub-instance.json → PASS (benign; the Hub check owns 'down') — #717", async () => {
+    const h = makeHarness();
+    try {
+      seedCurrentManifest(h.manifestPath);
+      seedOperatorToken(h.configDir);
+      // No instance file seeded, no seams overridden — defaults read the empty
+      // sandbox and short-circuit before any real network/lsof.
+      const { code, checks } = await runDoctor(h, healthyDeps());
+      expect(byName(checks, "loopback-hijack")?.status).toBe("pass");
+      expect(code).toBe(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("loopback nonce matches ours + single listener → PASS", async () => {
+    const h = makeHarness();
+    try {
+      seedCurrentManifest(h.manifestPath);
+      seedOperatorToken(h.configDir);
+      const { code, checks } = await runDoctor(
+        h,
+        healthyDeps({
+          readInstanceRecord: () => ({ instance: "n1", pid: 1, port: 1939, startedAt: "" }),
+          probeLoopbackInstance: async () => ({ reachable: true, status: 200, instance: "n1" }),
+          countHubListeners: () => 1,
+        }),
+      );
+      const c = byName(checks, "loopback-hijack");
+      expect(c?.status).toBe("pass");
+      expect(c?.detail).toContain("instance nonce");
+      expect(code).toBe(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("loopback nonce MISMATCH → FAIL with lsof/orb remediation + incident ref", async () => {
+    const h = makeHarness();
+    try {
+      seedCurrentManifest(h.manifestPath);
+      seedOperatorToken(h.configDir);
+      const { code, checks } = await runDoctor(
+        h,
+        healthyDeps({
+          readInstanceRecord: () => ({ instance: "ours", pid: 1, port: 1939, startedAt: "" }),
+          probeLoopbackInstance: async () => ({
+            reachable: true,
+            status: 200,
+            instance: "rogue-hub",
+          }),
+          countHubListeners: () => 2,
+        }),
+      );
+      const c = byName(checks, "loopback-hijack");
+      expect(c?.status).toBe("fail");
+      expect(c?.detail).toContain("rogue-hub");
+      expect(c?.detail).toContain("2 listeners");
+      expect(c?.detail).toContain("hub#737");
+      expect(c?.fix).toContain("lsof -nP -iTCP:1939 -sTCP:LISTEN");
+      expect(c?.fix).toContain("orb list");
+      expect(code).toBe(1);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("foreign process answering with NO nonce → FAIL (the OrbStack container-hub shape)", async () => {
+    const h = makeHarness();
+    try {
+      seedCurrentManifest(h.manifestPath);
+      seedOperatorToken(h.configDir);
+      const { checks } = await runDoctor(
+        h,
+        healthyDeps({
+          readInstanceRecord: () => ({ instance: "ours", pid: 1, port: 1939, startedAt: "" }),
+          probeLoopbackInstance: async () => ({ reachable: true, status: 200 }),
+          countHubListeners: () => undefined, // lsof indeterminate — still FAILs on the nonce alone
+        }),
+      );
+      const c = byName(checks, "loopback-hijack");
+      expect(c?.status).toBe("fail");
+      expect(c?.detail).toContain("foreign process");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("nonce matches but a SECOND listener exists → WARN (latent shadow, not FAIL)", async () => {
+    const h = makeHarness();
+    try {
+      seedCurrentManifest(h.manifestPath);
+      seedOperatorToken(h.configDir);
+      const { code, checks } = await runDoctor(
+        h,
+        healthyDeps({
+          readInstanceRecord: () => ({ instance: "n1", pid: 1, port: 1939, startedAt: "" }),
+          probeLoopbackInstance: async () => ({ reachable: true, status: 200, instance: "n1" }),
+          countHubListeners: () => 2,
+        }),
+      );
+      const c = byName(checks, "loopback-hijack");
+      expect(c?.status).toBe("warn");
+      expect(c?.detail).toContain("2 listeners");
+      // WARN never fails the exit code.
+      expect(code).toBe(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("record present but loopback unreachable → PASS (defers to the Hub check)", async () => {
+    const h = makeHarness();
+    try {
+      seedCurrentManifest(h.manifestPath);
+      seedOperatorToken(h.configDir);
+      const { checks } = await runDoctor(
+        h,
+        healthyDeps({
+          readInstanceRecord: () => ({ instance: "n1", pid: 1, port: 1939, startedAt: "" }),
+          probeLoopbackInstance: async () => ({ reachable: false }),
+        }),
+      );
+      expect(byName(checks, "loopback-hijack")?.status).toBe("pass");
+    } finally {
+      h.cleanup();
+    }
+  });
+});

package/src/__tests__/git-notify.test.ts

@@ -2,7 +2,13 @@ import { describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { notifySurfacePushed } from "../git-notify.ts";
+import { REGISTERED_MINT_TTL_THRESHOLD_SECONDS } from "../admin-connections.ts";
+import {
+  NOTIFY_TTL_SECONDS,
+  PULL_TTL_SECONDS,
+  assertUnregisteredMintTtl,
+  notifySurfacePushed,
+} from "../git-notify.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { validateAccessToken } from "../jwt-sign.ts";
 import { rotateSigningKey } from "../signing-keys.ts";
@@ -37,6 +43,28 @@ function fetchSpy(status = 200, body = '{"ok":true}') {
   return { impl, calls };
 }
 
+describe("unregistered-mint TTL policy guard", () => {
+  test("the shipped TTLs sit strictly under the registered-mint threshold", () => {
+    // The import of git-notify.ts at the top of this file already ran the
+    // module-load asserts — reaching here means they passed. Pin the values
+    // explicitly too, so a bumped TTL fails with a readable diff.
+    expect(NOTIFY_TTL_SECONDS).toBeLessThan(REGISTERED_MINT_TTL_THRESHOLD_SECONDS);
+    expect(PULL_TTL_SECONDS).toBeLessThan(REGISTERED_MINT_TTL_THRESHOLD_SECONDS);
+  });
+
+  test("the guard throws at/above the threshold and passes just under it", () => {
+    expect(() =>
+      assertUnregisteredMintTtl("PULL_TTL_SECONDS", REGISTERED_MINT_TTL_THRESHOLD_SECONDS),
+    ).toThrow(/registered-mint/);
+    expect(() =>
+      assertUnregisteredMintTtl("PULL_TTL_SECONDS", REGISTERED_MINT_TTL_THRESHOLD_SECONDS + 1),
+    ).toThrow(/PULL_TTL_SECONDS/);
+    expect(() =>
+      assertUnregisteredMintTtl("NOTIFY_TTL_SECONDS", REGISTERED_MINT_TTL_THRESHOLD_SECONDS - 1),
+    ).not.toThrow();
+  });
+});
+
 describe("notifySurfacePushed", () => {
   test("no surface module installed → no-op, no fetch", async () => {
     const h = makeHarness();

package/src/__tests__/grants-store.test.ts

@@ -7,11 +7,12 @@
  * the lenient-read posture.
  */
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   type ConnectionSpec,
+  GRANTS_FILE_VERSION,
   type GrantRecord,
   connectionKey,
   getGrant,
@@ -93,6 +94,37 @@ describe("round-trip", () => {
   });
 });
 
+describe("file versioning (2026-07-01 — future-migration seam)", () => {
+  test("every write stamps version: 1 and a rewrite preserves it", () => {
+    putGrant(storePath, rec());
+    const first = JSON.parse(readFileSync(storePath, "utf8")) as { version?: unknown };
+    expect(first.version).toBe(GRANTS_FILE_VERSION);
+    expect(first.version).toBe(1);
+    // Round-trip through the store API keeps stamping it.
+    putGrant(storePath, rec({ id: "second", agent: "agent2" }));
+    const second = JSON.parse(readFileSync(storePath, "utf8")) as { version?: unknown };
+    expect(second.version).toBe(1);
+    expect(readGrants(storePath)).toHaveLength(2);
+  });
+
+  test("a LEGACY file without version loads fine (treated as v1)", () => {
+    const legacy = rec();
+    writeFileSync(storePath, JSON.stringify({ grants: [legacy] }));
+    const back = readGrants(storePath);
+    expect(back).toHaveLength(1);
+    expect(back[0]).toEqual(legacy);
+    // First write-through upgrades the file to the versioned shape without
+    // losing the legacy record.
+    putGrant(storePath, rec({ id: "new-row", agent: "agent2" }));
+    const upgraded = JSON.parse(readFileSync(storePath, "utf8")) as {
+      version?: unknown;
+      grants: unknown[];
+    };
+    expect(upgraded.version).toBe(1);
+    expect(upgraded.grants).toHaveLength(2);
+  });
+});
+
 describe("0600 perms (the file holds secrets)", () => {
   test("the store file is created mode 0600", () => {
     putGrant(