@openparachute/hub 0.5.13-rc.23 → 0.5.13-rc.34

package/README.md

@@ -24,11 +24,14 @@ One-click Render deploy via the `render.yaml` Blueprint in this repo. Provisions
 
 **Want pre-release / rc modules?** Set `PARACHUTE_INSTALL_CHANNEL=rc` in your Render dashboard env vars (useful for dev/testing against the rc release line).
 
-After deploy:
+After deploy completes:
 
-1. Open your Render service URL → wizard runs at `/admin/setup`
-2. Set custom domain (optional) → set `PARACHUTE_HUB_ORIGIN` env to match
-3. Install modules via the admin SPA at `/admin/modules` (or via the wizard)
+1. Open Render Logs → search for `parachute-bootstrap-` to find your one-time admin setup token (printed in a prominent banner on first boot).
+2. Visit your Render service URL's `/admin/setup` → paste the token → create your admin account.
+3. Set custom domain (optional) → set `PARACHUTE_HUB_ORIGIN` env to match.
+4. Install modules via the admin SPA at `/admin/modules` (or via the wizard).
+
+Operators who want env-var-driven seeding (CI, scripted deploys) can still set `PARACHUTE_INITIAL_ADMIN_USERNAME` + `PARACHUTE_INITIAL_ADMIN_PASSWORD` manually in the Render dashboard — hub honors them when present.
 
 Render's docs on Blueprints: <https://render.com/docs/blueprint-spec>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.5.13-rc.23",
+  "version": "0.5.13-rc.34",
   "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

@@ -1005,6 +1005,44 @@ describe("well-known regen after module ops", () => {
     expect(doc.vaults.some((v) => v.name === "default")).toBe(true);
   });
 
+  test("runInstall sets PORT in child env from services.json entry (hub#356)", async () => {
+    // Container deploys (Render / etc.) set PORT in hub's env via the
+    // Dockerfile / platform. Without explicit override at spawn time, every
+    // supervised child inherits hub's PORT via `env: process.env` and tries
+    // to bind hub's own port — EADDRINUSE → crashloop → supervisor gives up.
+    // Regression guard: the spawn captures the child's services.json port.
+    const { supervisor, spawns } = makeIdleSupervisor();
+    const { run } = alwaysOkRun();
+    const wkPath = join(h.dir, "well-known.json");
+    const install = fakeInstall("@openparachute/vault", {
+      name: "vault",
+      manifestName: "parachute-vault",
+      port: 1940,
+      paths: ["/vault/default"],
+      health: "/vault/default/health",
+    });
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const deps = {
+      db: h.db,
+      issuer: ISSUER,
+      manifestPath: h.manifestPath,
+      configDir: h.dir,
+      supervisor,
+      run,
+      findGlobalInstall: install.findGlobalInstall,
+      readModuleManifest: install.readModuleManifest,
+      wellKnownPath: wkPath,
+    };
+    await handleInstall(
+      postReq("/api/modules/vault/install", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      deps,
+    );
+    await new Promise((r) => setTimeout(r, 10));
+    expect(spawns.length).toBe(1);
+    expect(spawns[0]?.env?.PORT).toBe("1940");
+  });
+
   test("runInstall failure: bun add fails -> no well-known regen (no partial state)", async () => {
     const { supervisor } = makeIdleSupervisor();
     const wkPath = join(h.dir, "well-known.json");

package/src/__tests__/hub-origin-resolution.test.ts

@@ -117,6 +117,56 @@ describe("resolveIssuer — precedence chain", () => {
     // Pass 3 — back to request origin.
     expect(resolveIssuer(req(baseUrl), db, undefined)).toBe("http://127.0.0.1:1939");
   });
+
+  test("X-Forwarded-Proto: https upgrades the request-origin fallback", () => {
+    // Render / Tailscale Funnel / cloudflared terminate TLS at the edge
+    // and forward plain HTTP. Without honoring the header, hub publishes
+    // `http://...` in OAuth discovery — mixed-content blocked when the
+    // page loaded over https://. See hub#355 (the notes app's
+    // /oauth/register call surfaced this).
+    const r = new Request("http://parachute-hub.onrender.com/.well-known/oauth-authorization-server", {
+      method: "GET",
+      headers: { "X-Forwarded-Proto": "https" },
+    });
+    expect(resolveIssuer(r, db, undefined)).toBe("https://parachute-hub.onrender.com");
+  });
+
+  test("X-Forwarded-Proto with comma-separated values takes the first", () => {
+    // Multi-hop proxies append; the leftmost is the original client → edge
+    // hop. RFC-style parsing (consistent with isHttpsRequest).
+    const r = new Request("http://hub.internal/oauth/token", {
+      method: "GET",
+      headers: { "X-Forwarded-Proto": "https, http" },
+    });
+    expect(resolveIssuer(r, db, undefined)).toBe("https://hub.internal");
+  });
+
+  test("missing X-Forwarded-Proto leaves the URL scheme as-is (localhost dev)", () => {
+    // No reverse proxy → no header → keep http for the local-dev shape.
+    // Operators on plain HTTP localhost depend on this.
+    const r = new Request("http://127.0.0.1:1939/oauth/token", { method: "GET" });
+    expect(resolveIssuer(r, db, undefined)).toBe("http://127.0.0.1:1939");
+  });
+
+  test("X-Forwarded-Proto is IGNORED when hub_settings or env wins", () => {
+    // Precedence guard: X-Forwarded-Proto should only affect the
+    // request-origin fallback branch. Explicit operator config
+    // (settings row, env var) always wins as-is, including its scheme.
+    // Without this guard, a future refactor could accidentally let the
+    // header override an operator's deliberate choice.
+    const r = new Request("http://hub.internal/oauth/token", {
+      method: "GET",
+      headers: { "X-Forwarded-Proto": "https" },
+    });
+
+    // Env layer wins, even though the header says https — the env value
+    // is returned verbatim (preserving whatever scheme the operator set).
+    expect(resolveIssuer(r, db, "http://configured.example")).toBe("http://configured.example");
+
+    // Settings layer wins above env, also verbatim.
+    setHubOrigin(db, "http://settings.example");
+    expect(resolveIssuer(r, db, "https://env.example")).toBe("http://settings.example");
+  });
 });
 
 describe("resolveIssuerSource — attribution for SPA", () => {

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

@@ -80,13 +80,24 @@ describe("hubFetch routing", () => {
     // hub#259 rc.6: requires an admin row to bypass the fresh-hub
     // funnel redirect to /admin/setup (Bug 2 fix). Seed one so this
     // test continues to exercise the signed-out-but-setup-done branch.
+    //
+    // Hub also funnels to /admin/setup when no vault is installed
+    // (env-seed case). Pass an explicit manifestPath + seed a vault row
+    // so the funnel sees an installed vault and lets the discovery page
+    // render. Without this, the manifestPath default falls back to
+    // `~/.parachute/services.json` — which works on a dev box with an
+    // installed vault but fails in CI with a 302 wizard redirect.
     const h = makeHarness();
     try {
+      writeManifest({ services: [vaultEntry("default")] }, h.manifestPath);
       const db = openHubDb(hubDbPath(h.dir));
       try {
         const { createUser } = await import("../users.ts");
         await createUser(db, "owner", "pw");
-        const res = await hubFetch(h.dir, { getDb: () => db })(req("/"));
+        const res = await hubFetch(h.dir, {
+          getDb: () => db,
+          manifestPath: h.manifestPath,
+        })(req("/"));
         expect(res.status).toBe(200);
         expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
         const body = await res.text();
@@ -102,8 +113,12 @@ describe("hubFetch routing", () => {
   });
 
   test("/ renders 'Signed in as <name>' + sign-out form when session cookie is active (rc.13)", async () => {
+    // Same wizard-funnel bypass as the signed-out test above — seed a
+    // vault row and pass an explicit manifestPath so CI doesn't fall back
+    // to ~/.parachute/services.json.
     const h = makeHarness();
     try {
+      writeManifest({ services: [vaultEntry("default")] }, h.manifestPath);
       const db = openHubDb(hubDbPath(h.dir));
       try {
         const { createUser } = await import("../users.ts");
@@ -113,7 +128,10 @@ describe("hubFetch routing", () => {
         const user = await createUser(db, "aaron", "pw");
         const session = createSession(db, { userId: user.id });
         const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000));
-        const res = await hubFetch(h.dir, { getDb: () => db })(req("/", { headers: { cookie } }));
+        const res = await hubFetch(h.dir, {
+          getDb: () => db,
+          manifestPath: h.manifestPath,
+        })(req("/", { headers: { cookie } }));
         expect(res.status).toBe(200);
         const body = await res.text();
         expect(body).toContain("Signed in as");
@@ -1390,7 +1408,8 @@ describe("hubFetch /vault/<name>/* dynamic proxy (#144)", () => {
       fetch: async (req) => {
         const u = new URL(req.url);
         // Echo enough metadata for tests to verify path + method + body
-        // arrive intact end-to-end.
+        // arrive intact end-to-end. Also echo X-Forwarded-* headers so
+        // tests can assert hub forwards proxy hints (hub#358).
         const body = req.body ? await req.text() : "";
         return new Response(
           JSON.stringify({
@@ -1399,6 +1418,8 @@ describe("hubFetch /vault/<name>/* dynamic proxy (#144)", () => {
             pathname: u.pathname,
             search: u.search,
             body,
+            forwardedHost: req.headers.get("x-forwarded-host"),
+            forwardedProto: req.headers.get("x-forwarded-proto"),
           }),
           { status: 200, headers: { "content-type": "application/json" } },
         );
@@ -1409,6 +1430,164 @@ describe("hubFetch /vault/<name>/* dynamic proxy (#144)", () => {
     return { port: server.port as number, stop: () => server.stop(true) };
   }
 
+  test("forwards X-Forwarded-Host + X-Forwarded-Proto to upstream (hub#358)", async () => {
+    // Container deploys: supervised modules (vault, scribe, app) reverse-
+    // proxy through hub. They need the public origin to construct OAuth
+    // discovery metadata and redirect URIs. Without forwarded headers,
+    // they fall back to their internal loopback URL — breaking OAuth
+    // flows for clients that landed on a hub-proxied URL.
+    const h = makeHarness();
+    const upstream = startUpstream("hdr-test");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: upstream.port,
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      // Simulate Render-shape: page came in over HTTPS at parachute-hub.onrender.com
+      // Render terminates TLS and sets X-Forwarded-Proto: https; the Host
+      // header is preserved as the public hostname.
+      const incoming = new Request("http://parachute-hub.onrender.com/vault/default/.well-known/oauth-authorization-server", {
+        headers: {
+          host: "parachute-hub.onrender.com",
+          "x-forwarded-proto": "https",
+        },
+      });
+      const res = await fetcher(incoming);
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { forwardedHost: string; forwardedProto: string };
+      // Hub captured the public Host and forwarded it as X-Forwarded-Host.
+      expect(body.forwardedHost).toBe("parachute-hub.onrender.com");
+      // X-Forwarded-Proto preserved (edge already set it).
+      expect(body.forwardedProto).toBe("https");
+    } 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
+    // URL's https scheme; proxyRequest synthesizes X-Forwarded-Proto.
+    const h = makeHarness();
+    const upstream = startUpstream("hdr-test");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: upstream.port,
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const incoming = new Request("https://hub.example.com/vault/default/health", {
+        headers: { host: "hub.example.com" },
+      });
+      const res = await fetcher(incoming);
+      const body = (await res.json()) as { forwardedHost: string; forwardedProto: string };
+      expect(body.forwardedHost).toBe("hub.example.com");
+      expect(body.forwardedProto).toBe("https");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("synthesizes X-Forwarded-Proto=http when neither edge nor URL signal HTTPS", async () => {
+    // Plain-HTTP path: no edge, no https URL scheme. isHttpsRequest returns
+    // false; proxyRequest synthesizes "http". This is local-dev shape.
+    const h = makeHarness();
+    const upstream = startUpstream("hdr-test");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: upstream.port,
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const incoming = new Request("http://127.0.0.1:1939/vault/default/health", {
+        headers: { host: "127.0.0.1:1939" },
+      });
+      const res = await fetcher(incoming);
+      const body = (await res.json()) as { forwardedProto: string };
+      expect(body.forwardedProto).toBe("http");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("preserves X-Forwarded-Host when edge already set it (nested-proxy chain)", async () => {
+    // Multi-hop chain: client → edge proxy → hub → upstream. Edge captures
+    // the original host as X-Forwarded-Host before its own host-rewrite;
+    // hub MUST preserve that, not overwrite with its own incoming Host
+    // (which may be the edge's hostname). "Don't clobber" semantics.
+    const h = makeHarness();
+    const upstream = startUpstream("hdr-test");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: upstream.port,
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      // Edge already labeled the canonical hop: original-client.example
+      // (this is what an HTTPS termination proxy in front of hub would set).
+      const incoming = new Request("http://edge.local/vault/default/health", {
+        headers: {
+          host: "edge.local",
+          "x-forwarded-host": "original-client.example",
+          "x-forwarded-proto": "https",
+        },
+      });
+      const res = await fetcher(incoming);
+      const body = (await res.json()) as { forwardedHost: string; forwardedProto: string };
+      // Edge's X-Forwarded-Host preserved verbatim, NOT clobbered by the
+      // edge.local Host that hub itself saw.
+      expect(body.forwardedHost).toBe("original-client.example");
+      expect(body.forwardedProto).toBe("https");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
   test("proxies a /vault/<name>/* request to the matching upstream", async () => {
     const h = makeHarness();
     const upstream = startUpstream("default-vault");

package/src/__tests__/lifecycle.test.ts

@@ -342,7 +342,10 @@ describe("parachute start", () => {
         log: () => {},
       });
       expect(code).toBe(0);
+      // PORT is always set by `parachute start` (hub#356) from the
+      // services.json entry. PARACHUTE_HUB_ORIGIN comes from expose-state.
       expect(spawner.calls[0]?.env).toEqual({
+        PORT: "1940",
         PARACHUTE_HUB_ORIGIN: "https://parachute.taildf9ce2.ts.net",
       });
     } finally {
@@ -364,6 +367,7 @@ describe("parachute start", () => {
       });
       expect(code).toBe(0);
       expect(spawner.calls[0]?.env).toEqual({
+        PORT: "1940",
         PARACHUTE_HUB_ORIGIN: "http://127.0.0.1:1939",
       });
     } finally {
@@ -398,6 +402,7 @@ describe("parachute start", () => {
       });
       expect(code).toBe(0);
       expect(spawner.calls[0]?.env).toEqual({
+        PORT: "1940",
         PARACHUTE_HUB_ORIGIN: "https://override.example.com",
       });
     } finally {
@@ -417,7 +422,11 @@ describe("parachute start", () => {
         log: () => {},
       });
       expect(code).toBe(0);
-      expect(spawner.calls[0]?.env).toBeUndefined();
+      // PORT is always set (hub#356) — even with no override, no exposure,
+      // and no hub.port file, the spawn env carries the canonical PORT
+      // from services.json. Test renamed from "omits env" to reflect
+      // the new minimum-env shape.
+      expect(spawner.calls[0]?.env).toEqual({ PORT: "1940" });
     } finally {
       h.cleanup();
     }
@@ -453,6 +462,7 @@ describe("parachute start", () => {
       });
       expect(code).toBe(0);
       expect(spawner.calls[0]?.env).toEqual({
+        PORT: "1943",
         GROQ_API_KEY: "gsk_real_value",
         QUOTED: "quoted_val",
       });
@@ -483,6 +493,7 @@ describe("parachute start", () => {
       });
       expect(code).toBe(0);
       expect(spawner.calls[0]?.env).toEqual({
+        PORT: "1940",
         SCRIBE_AUTH_TOKEN: "secret",
         PARACHUTE_HUB_ORIGIN: "https://live.example.com",
       });

package/src/__tests__/serve-boot.test.ts

@@ -121,6 +121,27 @@ describe("bootSupervisedModules", () => {
     expect(recorder.calls[0]?.env?.PARACHUTE_HUB_ORIGIN).toBe("https://hub.example");
   });
 
+  test("sets PORT in child env from services.json entry (hub#357)", async () => {
+    // Container deploys (Render etc.) set PORT in hub's process.env via
+    // Dockerfile / platform injection. The supervisor's defaultSpawnFn
+    // passes `env: process.env` so children inherit hub's PORT and try
+    // to bind hub's own port → EADDRINUSE crashloop. This boot path
+    // (called on hub startup to re-spawn supervised modules from
+    // services.json) was missed by hub#356 which only fixed the
+    // install-time + lifecycle paths. Third spawn site, same fix shape.
+    writeManifest({ services: [VAULT_ENTRY] }, h.manifestPath);
+    const recorder = makeRecorder();
+    const sup = new Supervisor({ spawnFn: recorder.spawn });
+
+    await bootSupervisedModules(sup, {
+      manifestPath: h.manifestPath,
+      configDir: h.dir,
+    });
+
+    // VAULT_ENTRY's port = 1940 (vault's canonical).
+    expect(recorder.calls[0]?.env?.PORT).toBe("1940");
+  });
+
   test("merges per-module .env file into child env", async () => {
     writeManifest({ services: [VAULT_ENTRY] }, h.manifestPath);
     // Write a per-module .env at <configDir>/<short>/.env — what the

package/src/__tests__/serve.test.ts

@@ -184,6 +184,15 @@ describe("formatBootstrapTokenBanner", () => {
       expect(line.startsWith("[wizard]")).toBe(true);
     }
   });
+
+  test("uses ═ delimiters and an ALL-CAPS heading so operators spot the block in log viewers", () => {
+    const banner = formatBootstrapTokenBanner("parachute-bootstrap-visual-token");
+    // The ═ box-drawing char is the visual cue an operator scrolling
+    // Render's log tab keys off; this assertion locks the new shape so
+    // a stylistic regression doesn't silently demote the banner.
+    expect(banner).toContain("═");
+    expect(banner).toContain("PARACHUTE BOOTSTRAP TOKEN");
+  });
 });
 
 // --- bootstrap-token generation under needs-setup (Issue 1 wiring) -------

package/src/__tests__/setup-wizard.test.ts

@@ -2143,6 +2143,10 @@ describe("typed vault name (hub#267)", () => {
       const vaultSpawn = spawnRequests.find((s) => s.short === "vault");
       expect(vaultSpawn).toBeDefined();
       expect(vaultSpawn?.env?.PARACHUTE_VAULT_NAME).toBe("smoke-1940");
+      // PORT also injected (hub#356) — supervisor always sets it from the
+      // services.json entry regardless of whether the typed-name path
+      // contributed any additional env vars.
+      expect(vaultSpawn?.env?.PORT).toBe("1940");
     } finally {
       db.close();
     }
@@ -2254,10 +2258,13 @@ describe("typed vault name (hub#267)", () => {
       await new Promise((r) => setTimeout(r, 50));
       const vaultSpawn = spawnRequests.find((s) => s.short === "vault");
       expect(vaultSpawn).toBeDefined();
-      // No env override on the default-name path (vault's
+      // No PARACHUTE_VAULT_NAME override on the default-name path (vault's
       // resolveFirstBootVaultName already defaults to "default" when the
-      // env var is absent, so the override would be redundant).
-      expect(vaultSpawn?.env).toBeUndefined();
+      // env var is absent). PORT is set by the supervisor (hub#356) for
+      // every supervised child regardless — assert the empty-name path
+      // doesn't add PARACHUTE_VAULT_NAME.
+      expect(vaultSpawn?.env?.PARACHUTE_VAULT_NAME).toBeUndefined();
+      expect(vaultSpawn?.env?.PORT).toBe("1940");
     } finally {
       db.close();
     }

package/src/__tests__/spawn-env-propagation.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Regression test for hub#349: Bun.spawn defaults to an EMPTY env, which meant
+ * subprocess `bun add -g` didn't see TMPDIR, BUN_INSTALL, or any other env vars
+ * set by the Dockerfile / Render env. All `defaultRun`-style helpers were
+ * updated to pass `env: process.env`.
+ *
+ * This test asserts that property end-to-end: spawn a real child via `bun -e`
+ * and have it print one parent-set env var. Pre-fix, the child would not see
+ * the var; post-fix, it does.
+ *
+ * We exercise the production path by importing one representative helper.
+ * The full set of seven explicit + several inherited fix sites all use the
+ * same `env: process.env` pattern; testing one is sufficient to lock the
+ * pattern in place — the others are mechanical applications of it.
+ */
+import { describe, expect, test } from "bun:test";
+
+describe("Bun.spawn env propagation (hub#349)", () => {
+  test("child process sees parent env when defaultRun-style helper is used", async () => {
+    // Unique marker so we can't false-positive against leftover env from
+    // another test or the harness itself.
+    const markerKey = "PARACHUTE_HUB_SPAWN_ENV_TEST_MARKER";
+    const markerValue = `marker-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+
+    const originalValue = process.env[markerKey];
+    process.env[markerKey] = markerValue;
+    try {
+      // Spawn a child the same way every defaultRun helper does:
+      // `env: process.env`. The child prints its view of the marker var.
+      const proc = Bun.spawn(
+        ["bun", "-e", `process.stdout.write(process.env.${markerKey} ?? "MISSING")`],
+        {
+          stdout: "pipe",
+          stderr: "pipe",
+          env: process.env,
+        },
+      );
+      const stdout = await new Response(proc.stdout).text();
+      const exitCode = await proc.exited;
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toBe(markerValue);
+    } finally {
+      if (originalValue === undefined) delete process.env[markerKey];
+      else process.env[markerKey] = originalValue;
+    }
+  });
+
+  test("child process does NOT see parent env when env is omitted (negative control)", async () => {
+    // The bug we're guarding against: without `env: process.env`, Bun.spawn
+    // hands the child an empty env. This test pins the failure mode so a
+    // future regression (someone removing `env: process.env`) is caught here,
+    // not in production on Render.
+    const markerKey = "PARACHUTE_HUB_SPAWN_ENV_TEST_MARKER_NEG";
+    const markerValue = `marker-${Date.now()}`;
+
+    const originalValue = process.env[markerKey];
+    process.env[markerKey] = markerValue;
+    try {
+      const proc = Bun.spawn(
+        ["bun", "-e", `process.stdout.write(process.env.${markerKey} ?? "MISSING")`],
+        {
+          stdout: "pipe",
+          stderr: "pipe",
+          // intentionally NO env: process.env
+        },
+      );
+      const stdout = await new Response(proc.stdout).text();
+      const exitCode = await proc.exited;
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toBe("MISSING");
+    } finally {
+      if (originalValue === undefined) delete process.env[markerKey];
+      else process.env[markerKey] = originalValue;
+    }
+  });
+});

package/src/admin-vaults.ts

@@ -206,7 +206,12 @@ function buildEntry(
 }
 
 async function defaultRunCommand(cmd: readonly string[]): Promise<RunResult> {
-  const proc = Bun.spawn([...cmd], { stdio: ["ignore", "pipe", "pipe"] });
+  // Inherit env so the child sees PATH, HOME, BUN_INSTALL, etc. Bun.spawn
+  // defaults to empty env — see api-modules-ops.ts:defaultRun for the rationale.
+  const proc = Bun.spawn([...cmd], {
+    stdio: ["ignore", "pipe", "pipe"],
+    env: process.env,
+  });
   // Drain both pipes in parallel — leaving stderr unread can deadlock long
   // installs once the OS pipe buffer fills (#97). Captured stderr is folded
   // into the orchestration error message on non-zero exit.

package/src/api-modules-ops.ts

@@ -322,7 +322,14 @@ async function resolveSpawnSpec(
 }
 
 function defaultRun(cmd: readonly string[]): Promise<number> {
-  const proc = Bun.spawn([...cmd], { stdio: ["ignore", "inherit", "inherit"] });
+  // Inherit env so child `bun add` sees TMPDIR, BUN_INSTALL, PARACHUTE_*,
+  // etc. set by the Dockerfile / Render env. Bun.spawn defaults to empty
+  // env — without this, bun-add fails with cross-mount rename errors on
+  // Render (where TMPDIR points at the persistent disk). See hub#349.
+  const proc = Bun.spawn([...cmd], {
+    stdio: ["ignore", "inherit", "inherit"],
+    env: process.env,
+  });
   return proc.exited;
 }
 
@@ -394,11 +401,23 @@ async function spawnSupervised(
   if (!entry) return undefined;
   const cmd = spec.startCmd?.(entry);
   if (!cmd || cmd.length === 0) return undefined;
+  // PORT override (hub#356): in container deploys, hub binds its own port
+  // via the PORT env var (Render sets PORT=$PORT, Dockerfile defaults to
+  // 1939). Bun.spawn's `env: process.env` propagates that PORT to every
+  // supervised child — so vault (which reads `process.env.PORT` in
+  // server.ts:230) tries to bind hub's port and crashes EADDRINUSE.
+  // Explicitly override with the child's services.json port so children
+  // honor their canonical port assignment regardless of hub's PORT.
+  // `deps.spawnEnv` still wins (test seam + first-boot vault-name pass-through).
+  const childEnv: Record<string, string> = {
+    PORT: String(entry.port),
+    ...(deps.spawnEnv ?? {}),
+  };
   const req: SpawnRequest = {
     short,
     cmd,
     ...(entry.installDir ? { cwd: entry.installDir } : {}),
-    ...(deps.spawnEnv && Object.keys(deps.spawnEnv).length > 0 ? { env: deps.spawnEnv } : {}),
+    env: childEnv,
   };
   return deps.supervisor.start(req);
 }

package/src/commands/auth.ts

@@ -60,7 +60,13 @@ export interface Runner {
 
 export const defaultRunner: Runner = {
   async run(cmd) {
-    const proc = Bun.spawn([...cmd], { stdio: ["inherit", "inherit", "inherit"] });
+    // Inherit env so the child (e.g. parachute-vault subprocess) sees PATH,
+    // HOME, PARACHUTE_HOME, etc. Bun.spawn defaults to empty env — see
+    // api-modules-ops.ts:defaultRun.
+    const proc = Bun.spawn([...cmd], {
+      stdio: ["inherit", "inherit", "inherit"],
+      env: process.env,
+    });
     return await proc.exited;
   },
 };

package/src/commands/expose-auth-preflight.ts

@@ -26,7 +26,12 @@ import { type VaultAuthStatus, readVaultAuthStatus } from "../vault/auth-status.
 export type InteractiveRunner = (cmd: readonly string[]) => Promise<number>;
 
 const defaultInteractiveRunner: InteractiveRunner = async (cmd) => {
-  const proc = Bun.spawn([...cmd], { stdio: ["inherit", "inherit", "inherit"] });
+  // Inherit env so subprocesses see PATH (to find `tailscale`), HOME, etc.
+  // Bun.spawn defaults to empty env — see api-modules-ops.ts:defaultRun.
+  const proc = Bun.spawn([...cmd], {
+    stdio: ["inherit", "inherit", "inherit"],
+    env: process.env,
+  });
   return await proc.exited;
 };
 

package/src/commands/expose-cloudflare.ts

@@ -69,7 +69,12 @@ export const defaultCloudflaredSpawner: CloudflaredSpawner = {
   spawn(cmd, logFile) {
     mkdirSync(dirname(logFile), { recursive: true });
     const fd = openSync(logFile, "a");
-    const proc = Bun.spawn([...cmd], { stdio: ["ignore", fd, fd] });
+    // Inherit env so cloudflared sees HOME (where it reads ~/.cloudflared/),
+    // PATH, etc. Bun.spawn defaults to empty env — see api-modules-ops.ts.
+    const proc = Bun.spawn([...cmd], {
+      stdio: ["ignore", fd, fd],
+      env: process.env,
+    });
     proc.unref();
     return proc.pid;
   },

package/src/commands/expose-interactive.ts

@@ -46,7 +46,13 @@ import { type ExposeOpts, exposePublic } from "./expose.ts";
 export type InteractiveRunner = (cmd: readonly string[]) => Promise<number>;
 
 const defaultInteractiveRunner: InteractiveRunner = async (cmd) => {
-  const proc = Bun.spawn([...cmd], { stdio: ["inherit", "inherit", "inherit"] });
+  // Inherit env so interactive subprocesses (e.g. `brew install cloudflared`,
+  // `cloudflared tunnel login`) see PATH, HOME, etc. Bun.spawn defaults to
+  // empty env — see api-modules-ops.ts:defaultRun.
+  const proc = Bun.spawn([...cmd], {
+    stdio: ["inherit", "inherit", "inherit"],
+    env: process.env,
+  });
   return await proc.exited;
 };
 

package/src/commands/install.ts

@@ -250,7 +250,13 @@ export interface InstallOpts {
 }
 
 async function defaultRunner(cmd: readonly string[]): Promise<number> {
-  const proc = Bun.spawn([...cmd], { stdio: ["inherit", "inherit", "inherit"] });
+  // Inherit env (TMPDIR, BUN_INSTALL, PATH, HOME, PARACHUTE_*, etc.) — see
+  // api-modules-ops.ts:defaultRun for the rationale. Same Bun.spawn-defaults-
+  // to-empty-env bug; same one-line fix. See hub#349.
+  const proc = Bun.spawn([...cmd], {
+    stdio: ["inherit", "inherit", "inherit"],
+    env: process.env,
+  });
   return await proc.exited;
 }
 

package/src/commands/lifecycle.ts

@@ -67,6 +67,10 @@ export const defaultSpawner: Spawner = {
       // wrapped startCmds like `pnpm exec tsx server.ts` leave the tsx
       // grandchild bound to the port after stop → restart hits EADDRINUSE.
       detached: true,
+      // Inherit env so child sees PATH, HOME, PARACHUTE_HOME, etc.
+      // Bun.spawn defaults to empty env — see api-modules-ops.ts:defaultRun.
+      // Per-call `opts.env` overrides merge on top below.
+      env: process.env,
     };
     if (opts?.env) spawnOpts.env = { ...process.env, ...opts.env };
     if (opts?.cwd) spawnOpts.cwd = opts.cwd;
@@ -432,7 +436,13 @@ export async function start(svc: string | undefined, opts: LifecycleOpts = {}):
     // wrapper for launchd / systemd) — this is idempotent there. Hub-origin
     // override wins on collision; that's the live-exposure source of truth.
     const fileEnv = readEnvFileValues(join(r.configDir, short, ".env"));
-    const env: Record<string, string> = { ...fileEnv };
+    // PORT override (hub#356): same shape as `spawnSupervised` in
+    // api-modules-ops.ts. Without this, operators running `parachute start
+    // vault` inside a container that has PORT in env (Render / Fly / etc.)
+    // hit EADDRINUSE on hub's port. Local dev typically doesn't set PORT, so
+    // this is a no-op there. fileEnv wins on collision so per-service .env
+    // can still override if an operator deliberately set PORT in there.
+    const env: Record<string, string> = { PORT: String(entry.port), ...fileEnv };
     if (r.hubOrigin) env[HUB_ORIGIN_ENV] = r.hubOrigin;
     const spawnerOpts: { env?: Record<string, string>; cwd?: string } = {};
     if (Object.keys(env).length > 0) spawnerOpts.env = env;
@@ -647,7 +657,12 @@ export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
   if (follow) {
     const spawner = opts.tailSpawner ?? {
       spawn(cmd) {
-        const proc = Bun.spawn([...cmd], { stdio: ["ignore", "inherit", "inherit"] });
+        // Inherit env so `tail` sees PATH, etc. Bun.spawn defaults to empty
+        // env — see api-modules-ops.ts:defaultRun.
+        const proc = Bun.spawn([...cmd], {
+          stdio: ["ignore", "inherit", "inherit"],
+          env: process.env,
+        });
         return proc.pid;
       },
     };

package/src/commands/serve-boot.ts

@@ -89,11 +89,15 @@ export async function bootSupervisedModules(
       continue;
     }
 
-    // Per-module .env layers under HUB_ORIGIN (hub-origin wins on
-    // collision — it's the canonical issuer source, and a stale .env
-    // shouldn't override the live `parachute serve` env).
+    // PORT override (hub#357 — third spawn site missed by hub#356).
+    // Without this, modules that read process.env.PORT (vault, scribe)
+    // inherit hub's PORT from Bun.spawn's env: process.env default and
+    // crash EADDRINUSE on hub's port. Container deploy was still broken
+    // after #356 because this BOOT path runs on hub startup before the
+    // supervisor's other spawn paths see any traffic. fileEnv wins on
+    // collision so per-service .env can still override.
     const fileEnv = readEnvFileValues(join(opts.configDir, short, ".env"));
-    const env: Record<string, string> = { ...fileEnv };
+    const env: Record<string, string> = { PORT: String(entry.port), ...fileEnv };
     if (opts.hubOrigin) env[HUB_ORIGIN_ENV] = opts.hubOrigin;
 
     const req: {

package/src/commands/serve.ts

@@ -149,16 +149,26 @@ export async function seedInitialAdminIfNeeded(
  * the token can't proceed; an attacker who reads it before the
  * operator wins the race).
  */
-export function formatBootstrapTokenBanner(token: string): string {
+export function formatBootstrapTokenBanner(token: string, hubUrl?: string): string {
+  const rule = "═".repeat(64);
+  // Substitute the actual hub URL when known (PARACHUTE_HUB_ORIGIN). Operators
+  // staring at the banner in Render Logs shouldn't have to figure out their
+  // own URL — show the literal placeholder only when the issuer isn't set.
+  const url = hubUrl && hubUrl.length > 0 ? hubUrl.replace(/\/+$/, "") : "<hub-url>";
   return [
-    "[wizard] No admin exists — wizard mode active. To claim ownership of this hub:",
-    "[wizard]   1. Visit http://localhost:1939/admin/setup (or your deployed URL)",
-    "[wizard]   2. Paste this bootstrap token into the form:",
+    "[wizard]",
+    `[wizard] ${rule}`,
+    "[wizard]   PARACHUTE BOOTSTRAP TOKEN",
+    `[wizard] ${rule}`,
     "[wizard]",
     `[wizard]   ${token}`,
     "[wizard]",
-    "[wizard] This token grants permission to create the first admin. It expires when",
-    "[wizard] admin is created OR when hub restarts.",
+    `[wizard]   → Visit ${url}/admin/setup and paste this token to create`,
+    "[wizard]     your admin account.",
+    "[wizard]   → Expires when admin is created OR when hub restarts.",
+    "[wizard]",
+    `[wizard] ${rule}`,
+    "[wizard]",
   ].join("\n");
 }
 
@@ -199,14 +209,14 @@ export async function serve(opts: ServeOpts = {}): Promise<{
 
   if (adminBootstrap === "needs-setup") {
     log(
-      "parachute serve: no admin account configured. Set PARACHUTE_INITIAL_ADMIN_USERNAME + PARACHUTE_INITIAL_ADMIN_PASSWORD, or visit /admin/setup once the hub is reachable.",
+      "parachute serve: no admin account configured. Visit /admin/setup once the hub is reachable, or seed via PARACHUTE_INITIAL_ADMIN_USERNAME + PARACHUTE_INITIAL_ADMIN_PASSWORD env vars for scripted deploys.",
     );
     // Mint a bootstrap token + log it. The wizard's account POST will
     // require this token, so an attacker who beats the operator to the
     // freshly-provisioned URL still can't claim the admin row without
     // shell access to the platform's startup logs.
     const token = generateBootstrapToken();
-    log(formatBootstrapTokenBanner(token));
+    log(formatBootstrapTokenBanner(token, issuer));
   }
 
   const supervisor = opts.supervisor ?? new Supervisor();

package/src/commands/upgrade.ts

@@ -74,17 +74,22 @@ export interface UpgradeRunner {
 
 export const defaultRunner: UpgradeRunner = {
   async run(cmd, opts) {
+    // Inherit env so `bun add -g` etc. see TMPDIR, BUN_INSTALL, PATH, HOME.
+    // Bun.spawn defaults to empty env — see api-modules-ops.ts:defaultRun.
     const proc = Bun.spawn([...cmd], {
       cwd: opts?.cwd,
       stdio: ["inherit", "inherit", "inherit"],
+      env: process.env,
     });
     return await proc.exited;
   },
   async capture(cmd, opts) {
+    // Inherit env — same rationale as `run` above.
     const proc = Bun.spawn([...cmd], {
       cwd: opts?.cwd,
       stdout: "pipe",
       stderr: "pipe",
+      env: process.env,
     });
     const [stdout, stderr] = await Promise.all([
       new Response(proc.stdout).text(),

package/src/commands/vault-tokens-create-interactive.ts

@@ -30,7 +30,13 @@ import { createInterface } from "node:readline/promises";
 export type InteractiveRunner = (cmd: readonly string[]) => Promise<number>;
 
 const defaultInteractiveRunner: InteractiveRunner = async (cmd) => {
-  const proc = Bun.spawn([...cmd], { stdio: ["inherit", "inherit", "inherit"] });
+  // Inherit env so the child (parachute-vault subprocess) sees PATH, HOME,
+  // PARACHUTE_HOME, etc. Bun.spawn defaults to empty env — see
+  // api-modules-ops.ts:defaultRun.
+  const proc = Bun.spawn([...cmd], {
+    stdio: ["inherit", "inherit", "inherit"],
+    env: process.env,
+  });
   return await proc.exited;
 };
 

package/src/commands/vault.ts

@@ -2,6 +2,9 @@ export async function dispatchVault(args: readonly string[]): Promise<number> {
   try {
     const proc = Bun.spawn(["parachute-vault", ...args], {
       stdio: ["inherit", "inherit", "inherit"],
+      // Inherit env so parachute-vault sees PATH, HOME, PARACHUTE_HOME, etc.
+      // Bun.spawn defaults to empty env — see api-modules-ops.ts:defaultRun.
+      env: process.env,
     });
     return await proc.exited;
   } catch (err) {

package/src/hub-control.ts

@@ -74,7 +74,12 @@ export interface HubSpawner {
 export const defaultHubSpawner: HubSpawner = {
   spawn(cmd, logFile) {
     const fd = openSync(logFile, "a");
-    const proc = Bun.spawn([...cmd], { stdio: ["ignore", fd, fd] });
+    // Inherit env so the hub child process sees PATH, HOME, PARACHUTE_HOME,
+    // etc. Bun.spawn defaults to empty env — see api-modules-ops.ts.
+    const proc = Bun.spawn([...cmd], {
+      stdio: ["ignore", fd, fd],
+      env: process.env,
+    });
     proc.unref();
     return proc.pid;
   },

package/src/hub-server.ts

@@ -167,6 +167,7 @@ import {
 } from "./oauth-handlers.ts";
 import { buildHubBoundOrigins } from "./origin-check.ts";
 import { clearPid, writePid } from "./process-state.ts";
+import { isHttpsRequest } from "./request-protocol.ts";
 import {
   FIRST_PARTY_FALLBACKS,
   KNOWN_MODULES,
@@ -417,9 +418,28 @@ async function proxyRequest(
   const path = targetPath ?? url.pathname;
   const upstream = `http://127.0.0.1:${port}${path}${url.search}`;
   const headers = new Headers(req.headers);
+  // Capture the public hostname BEFORE deleting Host so we can forward it
+  // as X-Forwarded-Host (hub#358). Without this, supervised modules like
+  // vault see no X-Forwarded-Host header and fall back to their internal
+  // loopback URL when constructing OAuth metadata — publishing
+  // `http://127.0.0.1:1940/...` as the issuer instead of the public origin.
+  const publicHost = req.headers.get("host");
   // Host comes from the requester (tailnet FQDN); the loopback target wants
   // its own. Bun's fetch fills it in when omitted.
   headers.delete("host");
+  // Forward the public origin so downstream services build their public-
+  // facing URLs (OAuth metadata, redirect URIs) against the same host the
+  // client used. We DON'T overwrite X-Forwarded-Host if already set —
+  // some platforms (Render) set it at the edge.
+  if (publicHost && !headers.has("x-forwarded-host")) {
+    headers.set("x-forwarded-host", publicHost);
+  }
+  // Same for protocol — if the edge set X-Forwarded-Proto we preserve it,
+  // otherwise we set it from isHttpsRequest's signal (direct HTTPS to hub
+  // is unusual on Render, but covers local TLS-terminating proxies too).
+  if (!headers.has("x-forwarded-proto")) {
+    headers.set("x-forwarded-proto", isHttpsRequest(req) ? "https" : "http");
+  }
 
   const init: RequestInit & { duplex?: "half" } = {
     method: req.method,
@@ -944,7 +964,29 @@ export function resolveIssuer(
     if (stored) return stored;
   }
   if (configuredIssuer) return configuredIssuer;
-  return new URL(req.url).origin;
+  // Reverse-proxy aware: Render / Tailscale Funnel / cloudflared terminate
+  // TLS at the edge and forward plain HTTP to hub. Without X-Forwarded-Proto
+  // honoring, `req.url.origin` is `http://...` and hub publishes mixed-content
+  // URLs in OAuth discovery (`registration_endpoint`, `authorization_endpoint`,
+  // etc.) — browsers block them when the page itself loaded over https://.
+  // The `isHttpsRequest` helper is the canonical place where this trust
+  // is established (also used for the Secure cookie attribute).
+  //
+  // We do NOT honor X-Forwarded-Host *for hub's own issuer derivation*.
+  // (Note: hub DOES forward X-Forwarded-Host to upstream supervised
+  // modules in `proxyRequest` — that's a separate concern, see #358.
+  // Here we're deriving hub's own canonical origin from the incoming
+  // request, not what to tell downstream services.) Render, Tailscale
+  // Funnel, and cloudflared all preserve the Host header end-to-end,
+  // so `req.url`'s host already reflects the public hostname.
+  // Operators on a proxy that rewrites Host (some nginx / Caddy
+  // configs) should set hub_origin via the admin SPA — that path
+  // bypasses this fallback entirely.
+  const url = new URL(req.url);
+  if (isHttpsRequest(req)) {
+    url.protocol = "https:";
+  }
+  return url.origin;
 }
 
 /**

package/src/supervisor.ts

@@ -403,6 +403,10 @@ async function pumpLines(
 const defaultSpawnFn: SpawnFn = (req) => {
   const spawnOpts: Parameters<typeof Bun.spawn>[1] = {
     stdio: ["ignore", "pipe", "pipe"],
+    // Inherit env so supervised module sees PATH, HOME, PARACHUTE_HOME, etc.
+    // Bun.spawn defaults to empty env — see api-modules-ops.ts:defaultRun.
+    // Per-call `req.env` overrides merge on top below.
+    env: process.env,
   };
   if (req.cwd) spawnOpts.cwd = req.cwd;
   if (req.env) spawnOpts.env = { ...process.env, ...req.env };

package/src/tailscale/run.ts

@@ -7,7 +7,13 @@ export interface CommandResult {
 export type Runner = (cmd: readonly string[]) => Promise<CommandResult>;
 
 export async function defaultRunner(cmd: readonly string[]): Promise<CommandResult> {
-  const proc = Bun.spawn([...cmd], { stdout: "pipe", stderr: "pipe" });
+  // Inherit env so `tailscale` sees PATH (and HOME for state dir). Bun.spawn
+  // defaults to empty env — see api-modules-ops.ts:defaultRun for rationale.
+  const proc = Bun.spawn([...cmd], {
+    stdout: "pipe",
+    stderr: "pipe",
+    env: process.env,
+  });
   const [stdout, stderr, code] = await Promise.all([
     new Response(proc.stdout).text(),
     new Response(proc.stderr).text(),