@openparachute/hub 0.6.4-rc.8 → 0.6.4-rc.9

package/package.json

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

package/src/__tests__/expose-cloudflare.test.ts

@@ -1464,6 +1464,109 @@ describe("exposeCloudflareOff", () => {
     }
   });
 
+  test("clears stale PARACHUTE_HUB_ORIGIN from vault/.env on last-tunnel down (#503)", async () => {
+    const env = makeEnv();
+    try {
+      // Seed the stale public origin the up-path persisted into vault/.env.
+      // After teardown the hub is loopback-only, so leaving this would pin a
+      // public expected issuer and 401 every request on the next vault restart.
+      const vaultEnvPath = join(env.configDir, "vault", ".env");
+      require("node:fs").mkdirSync(join(env.configDir, "vault"), { recursive: true });
+      writeFileSync(vaultEnvPath, "PARACHUTE_HUB_ORIGIN=https://vault.example.com\n");
+
+      writeCloudflaredState(
+        {
+          version: 2,
+          tunnels: {
+            parachute: {
+              pid: 55557,
+              tunnelUuid: "ffffffff-0000-0000-0000-000000000006",
+              tunnelName: "parachute",
+              hostname: "vault.example.com",
+              startedAt: "2026-04-22T12:00:00.000Z",
+              configPath: env.configPath,
+            },
+          },
+        },
+        env.statePath,
+      );
+
+      const logs: string[] = [];
+      const code = await exposeCloudflareOff({
+        configDir: env.configDir,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        alive: () => false,
+        kill: () => {},
+        log: (l) => logs.push(l),
+      });
+
+      expect(code).toBe(0);
+      // The stale public origin is gone — vault reverts to its loopback default.
+      expect(readEnvFileValues(vaultEnvPath).PARACHUTE_HUB_ORIGIN).toBeUndefined();
+      // Operator is told what to restart so a running vault picks up the change.
+      expect(logs.join("\n")).toContain("cleared PARACHUTE_HUB_ORIGIN");
+      expect(logs.join("\n")).toContain("parachute restart vault");
+    } finally {
+      env.cleanup();
+    }
+  });
+
+  test("leaves vault/.env untouched while other tunnels survive (#503)", async () => {
+    const env = makeEnv();
+    try {
+      const vaultEnvPath = join(env.configDir, "vault", ".env");
+      require("node:fs").mkdirSync(join(env.configDir, "vault"), { recursive: true });
+      writeFileSync(vaultEnvPath, "PARACHUTE_HUB_ORIGIN=https://vault.example.com\n");
+
+      // Two tunnels; tear down only one by name → the box stays exposed, so the
+      // persisted public origin must remain (clearing it would break the live
+      // tunnel's iss check). Symmetric with the expose-state.json retention.
+      writeCloudflaredState(
+        {
+          version: 2,
+          tunnels: {
+            alpha: {
+              pid: 55558,
+              tunnelUuid: "11111111-0000-0000-0000-000000000007",
+              tunnelName: "alpha",
+              hostname: "alpha.example.com",
+              startedAt: "2026-04-22T12:00:00.000Z",
+              configPath: env.configPath,
+            },
+            beta: {
+              pid: 55559,
+              tunnelUuid: "22222222-0000-0000-0000-000000000008",
+              tunnelName: "beta",
+              hostname: "beta.example.com",
+              startedAt: "2026-04-22T12:00:00.000Z",
+              configPath: env.configPath,
+            },
+          },
+        },
+        env.statePath,
+      );
+
+      const code = await exposeCloudflareOff({
+        configDir: env.configDir,
+        tunnelName: "alpha",
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        alive: () => false,
+        kill: () => {},
+        log: () => {},
+      });
+
+      expect(code).toBe(0);
+      // Beta tunnel survives → public origin stays.
+      expect(readEnvFileValues(vaultEnvPath).PARACHUTE_HUB_ORIGIN).toBe(
+        "https://vault.example.com",
+      );
+    } finally {
+      env.cleanup();
+    }
+  });
+
   test("clears stale state when the process is already gone", async () => {
     const env = makeEnv();
     try {

package/src/__tests__/hub-server.test.ts

@@ -1630,6 +1630,139 @@ describe("hubFetch /vault/<name>/* dynamic proxy (#144)", () => {
     }
   });
 
+  // #525: bare `/vault/<name>` POST (no `/mcp` suffix) half-connects MCP
+  // clients. The fix 308-redirects the bare-path POST to `<mount>/mcp` BEFORE
+  // proxying, so a compliant client re-POSTs to the right endpoint and clients
+  // that don't follow redirects at least get an actionable Location + JSON body
+  // (vs the old opaque vault 405).
+  test("POST to bare /vault/<name> 308-redirects to /vault/<name>/mcp with an actionable body (#525)", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("aaron")] }, h.manifestPath);
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(
+        req("/vault/aaron", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ jsonrpc: "2.0", method: "initialize", id: 1 }),
+        }),
+      );
+      expect(res.status).toBe(308);
+      expect(res.headers.get("location")).toBe("/vault/aaron/mcp");
+      // 308 is permanently cacheable by default — no-store prevents a cached
+      // redirect outliving a remount.
+      expect(res.headers.get("cache-control")).toBe("no-store");
+      const body = (await res.json()) as { error: string; mcp_url: string; message: string };
+      expect(body.error).toBe("missing_mcp_suffix");
+      expect(body.mcp_url).toBe("/vault/aaron/mcp");
+      expect(body.message).toContain("/vault/aaron/mcp");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("bare-path 308 honors a trailing-slash mount: POST /vault/default → /vault/default/mcp (#525)", async () => {
+    // Mounts in services.json sometimes carry a trailing slash (#197). The
+    // redirect target must be built from the *normalized* mount so it stays
+    // `/vault/default/mcp`, never `/vault/default//mcp`.
+    const h = makeHarness();
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault-default",
+              port: 1940,
+              paths: ["/vault/default/"],
+              health: "/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/vault/default", { method: "POST" }));
+      expect(res.status).toBe(308);
+      expect(res.headers.get("location")).toBe("/vault/default/mcp");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("GET to bare /vault/<name> is NOT redirected — proxies through untouched (#525)", async () => {
+    // Only POST (the MCP transport verb) is caught. A browser GET to the bare
+    // path keeps its existing proxy behavior so we don't break any bare-path
+    // GET surface.
+    const h = makeHarness();
+    const upstream = startUpstream("bare-get");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault-aaron",
+              port: upstream.port,
+              paths: ["/vault/aaron"],
+              health: "/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/vault/aaron", { method: "GET" }));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string; method: string; pathname: string };
+      expect(body.tag).toBe("bare-get");
+      expect(body.method).toBe("GET");
+      expect(body.pathname).toBe("/vault/aaron");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("POST to the canonical /vault/<name>/mcp sub-path is NOT redirected — proxies through (#525)", async () => {
+    // The real MCP endpoint must keep working: a POST that already carries the
+    // `/mcp` suffix is a sub-path (not the exact bare mount) and proxies
+    // straight to the vault backend.
+    const h = makeHarness();
+    const upstream = startUpstream("mcp-post");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault-aaron",
+              port: upstream.port,
+              paths: ["/vault/aaron"],
+              health: "/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(
+        req("/vault/aaron/mcp", {
+          method: "POST",
+          body: JSON.stringify({ jsonrpc: "2.0", method: "tools/list", id: 2 }),
+        }),
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string; method: string; pathname: string };
+      expect(body.tag).toBe("mcp-post");
+      expect(body.method).toBe("POST");
+      expect(body.pathname).toBe("/vault/aaron/mcp");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
   test("synthesizes X-Forwarded-Proto when edge didn't set it (direct HTTPS to hub)", async () => {
     // Non-Render shape: hub bound directly to https (e.g. local TLS or a
     // proxy that doesn't set X-Forwarded-Proto). isHttpsRequest sees the

package/src/commands/expose-cloudflare.ts

@@ -53,6 +53,7 @@ import { HUB_UNIT_DEFAULT_PORT } from "../hub-unit.ts";
 import { type AliveFn, defaultAlive } from "../process-state.ts";
 import { readManifestLenient } from "../services-manifest.ts";
 import { type Runner, defaultRunner } from "../tailscale/run.ts";
+import { clearVaultHubOrigin } from "../vault-hub-origin-env.ts";
 import type { VaultAuthStatus } from "../vault/auth-status.ts";
 import { printPublic2FAWarning } from "./expose-2fa-warning.ts";
 import {
@@ -1137,8 +1138,35 @@ export async function exposeCloudflareOff(opts: ExposeCloudflareOpts = {}): Prom
   // downstream consumers stop resolving the now-dead public URL (mirrors the
   // up-path write above + the Tailscale off-path's expose-state teardown). When
   // other tunnels survive we leave it — a later off for the last one clears it.
+  //
+  // TODO(multi-tunnel) #588: with TWO CF tunnels up, tearing down the
+  // last-written-up one (whose hostname is what's in vault's `.env`) while the
+  // other survives leaves `.env` carrying the dead tunnel's origin while the
+  // surviving tunnel serves a different one → stale-iss on the next vault
+  // restart. Retention is still the only SAFE choice here: a single
+  // `PARACHUTE_HUB_ORIGIN` field can't represent "which surviving tunnel wins,"
+  // and clearing it would break the survivor's iss check. Properly fixing it
+  // needs re-resolving the effective origin from the survivor (or multi-origin
+  // issuer acceptance vault-side) — larger than the #503 single-tunnel fix, and
+  // multi-CF-tunnel-on-one-box is rare. See #588.
   if (!state) {
     clearExposeState(r.exposeStatePath);
+    // Drop the persisted PARACHUTE_HUB_ORIGIN from vault's `.env` (#503). With
+    // the last Cloudflare tunnel gone, the hub is loopback-only and mints
+    // loopback-`iss` tokens; a stale public origin left in `vault/.env` would
+    // pin a public expected issuer and 401 every request on the next vault
+    // daemon restart ("not signed in to the hub" — the inverse of the bug
+    // selfHealVaultHubOrigin closed). This mirrors exactly what the Tailscale
+    // off-path does (`exposeOff` in expose.ts) — the Cloudflare path had been
+    // the asymmetric gap. expose-state's own `hubOrigin` is cleared above via
+    // clearExposeState, so hub's per-request `resolveIssuer`/`exposeIssuerOrigin`
+    // (which read expose-state) also stop minting the public iss after teardown.
+    // No restart needed for the gap this closes — the next vault restart picks
+    // up the cleared `.env` — but tell the operator so an already-running vault
+    // doesn't keep validating against the now-dead public origin.
+    if (clearVaultHubOrigin(r.configDir, r.log)) {
+      r.log("  Restart vault to apply the loopback issuer now: `parachute restart vault`.");
+    }
   }
   return failed ? 1 : 0;
 }

package/src/help.ts

@@ -104,7 +104,7 @@ Examples:
   parachute install vault                                   # light: installs + starts vault, points you at the admin UI
   parachute install vault --interactive                     # full interactive vault init (name / MCP / token prompts)
   parachute install surface                                 # installs surface (auto-bootstraps Notes)
-  parachute install notes                                   # back-compat: legacy notes-daemon (Phase 2 deprecating)
+  parachute install notes                                   # legacy notes-daemon — deprecated; use \`parachute install surface\` instead
   parachute install scribe                                  # installs, prompts for provider, starts scribe
   parachute install scribe --scribe-provider groq --scribe-key gsk_…
                                                             # non-interactive scribe setup

package/src/hub-server.ts

@@ -643,6 +643,40 @@ async function proxyToVault(
   ) {
     return new Response("not found", { status: 404 });
   }
+  // Bare `/vault/<name>` POST → point at `/vault/<name>/mcp` (#525). Operators
+  // paste the bare vault URL (no `/mcp` suffix) into MCP clients; OAuth completes
+  // against the bare path (so the client looks "connected") but the JSON-RPC POST
+  // then hits a path vault has no MCP handler for and 405s — a confusing
+  // "connected but erroring" half-state. We catch the bare-path POST here, BEFORE
+  // proxying, and 308-redirect to the canonical `<mount>/mcp`. 308 (vs 307)
+  // signals the redirect is permanent/cacheable, and like 307 it preserves the
+  // method + body, so a spec-compliant MCP client re-POSTs the JSON-RPC payload
+  // to the right endpoint and connects cleanly. Clients that DON'T follow
+  // redirects still get an actionable signal: the Location header + JSON body name
+  // the correct URL (vs the old opaque 405). Only the EXACT bare mount is caught —
+  // any sub-path (`<mount>/mcp`, `<mount>/api/...`, the Notes PWA) proxies through
+  // untouched, and only POST (the MCP transport verb) is redirected so a stray
+  // browser GET to the bare path keeps its existing proxy behavior.
+  if (req.method === "POST" && url.pathname === match.mount) {
+    const mcpUrl = `${match.mount}/mcp`;
+    const body = {
+      error: "missing_mcp_suffix",
+      message: `This is a Parachute vault path, not an MCP endpoint. Use ${mcpUrl} as your MCP server URL.`,
+      mcp_url: mcpUrl,
+    };
+    return new Response(JSON.stringify(body), {
+      status: 308,
+      headers: {
+        location: mcpUrl,
+        "content-type": "application/json",
+        // 308 is permanently cacheable by default; without no-store a client
+        // (or an intermediary) could cache the redirect and keep bouncing the
+        // bare path to `/mcp` even after a remount changes the routing. Same
+        // guard as the force-change-password redirect below.
+        "cache-control": "no-store",
+      },
+    });
+  }
   // Symmetry with proxyToService (#196): honor `stripPrefix` with FIRST_-
   // PARTY_FALLBACKS as a fallback source. No first-party vault fallback
   // declares stripPrefix today (vault expects the full `/vault/<name>/*`

package/src/hub-settings.ts

@@ -13,9 +13,9 @@
  *     client to hit `/oauth/register` *within* that window is auto-approved
  *     (single-use, the value is cleared on consume). Past-due or absent
  *     means the standard pending-approval flow applies. Motivator: a
- *     canonical onboarding (install hub → wizard → install Notes →
- *     authorize) shouldn't bounce the operator through a manual approve
- *     step they just set up the hub for.
+ *     canonical onboarding (install hub → expose → wizard installs
+ *     vault/surface → authorize) shouldn't bounce the operator through a
+ *     manual approve step they just set up the hub for.
  *
  * Schema lives in `hub-db.ts` migration v7. This module is just the typed
  * accessor — single-row reads/writes per key, no joins, no caching. The