@openparachute/hub 0.5.13-rc.29 → 0.5.13-rc.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.5.13-rc.29",
+  "version": "0.5.13-rc.35",
   "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,88 @@ 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 sets PARACHUTE_HUB_ORIGIN in child env from deps.issuer (hub#365)", async () => {
+    // Supervised modules (vault, scribe, app) validate the `iss` claim
+    // on hub-minted JWTs against PARACHUTE_HUB_ORIGIN. Without it, they
+    // fall back to a loopback default and reject any token whose iss is
+    // the public Render URL — surfaces as "hub JWT verification failed:
+    // unexpected 'iss' claim value" on the first authed vault call.
+    // Regression guard: install-path spawn carries the hub's resolved
+    // issuer as PARACHUTE_HUB_ORIGIN.
+    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,
+      // Use the test's canonical ISSUER (matches the bearer's iss claim
+      // so handleInstall doesn't 401 — mintBearer always uses ISSUER).
+      // The assertion below verifies whatever issuer is on `deps` lands
+      // in the child's PARACHUTE_HUB_ORIGIN env.
+      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?.PARACHUTE_HUB_ORIGIN).toBe(ISSUER);
+  });
+
   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-server.test.ts

@@ -5,7 +5,13 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { HUB_SVC, hubPortPath } from "../hub-control.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
-import { findServiceUpstream, findVaultUpstream, hubFetch, layerOf } from "../hub-server.ts";
+import {
+  findServiceUpstream,
+  findVaultUpstream,
+  hubFetch,
+  layerOf,
+  parseArgs,
+} from "../hub-server.ts";
 import { setNotesRedirectDisabled } from "../hub-settings.ts";
 import { clearNotesRedirectLogState } from "../notes-redirect.ts";
 import { pidPath } from "../process-state.ts";
@@ -80,13 +86,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 +119,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 +134,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 +1414,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 +1424,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 +1436,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");
@@ -3033,3 +3218,44 @@ describe("hub-server.ts startup PID/port registration (#148)", () => {
     }
   }, 10_000);
 });
+
+describe("parseArgs — issuer env precedence (hub#365)", () => {
+  test("--issuer flag wins over both env vars", () => {
+    const got = parseArgs(["--issuer", "https://flag.example"], {
+      PARACHUTE_HUB_ORIGIN: "https://env.example",
+      RENDER_EXTERNAL_URL: "https://render.example",
+    });
+    expect(got.issuer).toBe("https://flag.example");
+  });
+
+  test("PARACHUTE_HUB_ORIGIN wins over RENDER_EXTERNAL_URL", () => {
+    const got = parseArgs([], {
+      PARACHUTE_HUB_ORIGIN: "https://hub.example",
+      RENDER_EXTERNAL_URL: "https://render.example",
+    });
+    expect(got.issuer).toBe("https://hub.example");
+  });
+
+  test("RENDER_EXTERNAL_URL is used when no override (standalone Render boot)", () => {
+    const got = parseArgs([], { RENDER_EXTERNAL_URL: "https://app.onrender.com" });
+    expect(got.issuer).toBe("https://app.onrender.com");
+  });
+
+  test("trailing slashes are stripped from all three sources", () => {
+    expect(parseArgs(["--issuer", "https://x.example/"], {}).issuer).toBe("https://x.example");
+    expect(parseArgs([], { PARACHUTE_HUB_ORIGIN: "https://x.example///" }).issuer).toBe(
+      "https://x.example",
+    );
+    expect(parseArgs([], { RENDER_EXTERNAL_URL: "https://x.example/" }).issuer).toBe(
+      "https://x.example",
+    );
+  });
+
+  test("issuer is undefined when no source is set", () => {
+    expect(parseArgs([], {}).issuer).toBeUndefined();
+    expect(parseArgs([], { PARACHUTE_HUB_ORIGIN: "" }).issuer).toBeUndefined();
+    expect(parseArgs([], { RENDER_EXTERNAL_URL: "" }).issuer).toBeUndefined();
+    // Bare slash collapses to empty after strip — must not become "" issuer.
+    expect(parseArgs([], { RENDER_EXTERNAL_URL: "/" }).issuer).toBeUndefined();
+  });
+});

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

@@ -6,6 +6,7 @@ import { _resetBootstrapTokenForTests, getBootstrapToken } from "../bootstrap-to
 import {
   formatBootstrapTokenBanner,
   formatListeningBanner,
+  resolveStartupIssuer,
   seedInitialAdminIfNeeded,
 } from "../commands/serve.ts";
 import { openHubDb } from "../hub-db.ts";
@@ -245,3 +246,66 @@ describe("bootstrap-token wiring under needs-setup", () => {
     expect(getBootstrapToken()).toBeUndefined();
   });
 });
+
+describe("resolveStartupIssuer — precedence chain (hub#365)", () => {
+  test("explicit opts.issuer wins over everything", () => {
+    const got = resolveStartupIssuer(
+      { issuer: "https://override.example" },
+      {
+        PARACHUTE_HUB_ORIGIN: "https://env.example",
+        RENDER_EXTERNAL_URL: "https://render.example.onrender.com",
+      },
+    );
+    expect(got).toBe("https://override.example");
+  });
+
+  test("PARACHUTE_HUB_ORIGIN wins over RENDER_EXTERNAL_URL", () => {
+    const got = resolveStartupIssuer(
+      {},
+      {
+        PARACHUTE_HUB_ORIGIN: "https://custom-domain.example",
+        RENDER_EXTERNAL_URL: "https://parachute-hub.onrender.com",
+      },
+    );
+    expect(got).toBe("https://custom-domain.example");
+  });
+
+  test("RENDER_EXTERNAL_URL is used when PARACHUTE_HUB_ORIGIN unset", () => {
+    // The load-bearing case: operator clicks Deploy to Render, container
+    // boots without an explicit PARACHUTE_HUB_ORIGIN (it doesn't yet
+    // appear in render.yaml as a default), Render injects RENDER_EXTERNAL_URL
+    // → hub picks it up automatically → supervised modules get the right
+    // PARACHUTE_HUB_ORIGIN → vault's iss check passes on the first
+    // authenticated request.
+    const got = resolveStartupIssuer(
+      {},
+      { RENDER_EXTERNAL_URL: "https://parachute-hub.onrender.com" },
+    );
+    expect(got).toBe("https://parachute-hub.onrender.com");
+  });
+
+  test("strips trailing slashes from any source for canonical form", () => {
+    expect(resolveStartupIssuer({ issuer: "https://x.example/" }, {})).toBe("https://x.example");
+    expect(resolveStartupIssuer({ issuer: "https://x.example//" }, {})).toBe("https://x.example");
+    expect(
+      resolveStartupIssuer({}, { PARACHUTE_HUB_ORIGIN: "https://x.example/" }),
+    ).toBe("https://x.example");
+    expect(
+      resolveStartupIssuer({}, { RENDER_EXTERNAL_URL: "https://x.example/" }),
+    ).toBe("https://x.example");
+  });
+
+  test("returns undefined when no source has a value", () => {
+    expect(resolveStartupIssuer({}, {})).toBeUndefined();
+    expect(resolveStartupIssuer({}, { RENDER_EXTERNAL_URL: "" })).toBeUndefined();
+    expect(resolveStartupIssuer({}, { PARACHUTE_HUB_ORIGIN: "" })).toBeUndefined();
+  });
+
+  test("empty string after slash-strip collapses to undefined (defensive)", () => {
+    // `/` alone strips to empty string → `||` evaluates false → undefined.
+    // Guards against a misconfigured env where someone sets the var to "/"
+    // expecting it to mean "root" (it doesn't — leaves hub without a usable
+    // origin, which is the same as not setting it at all).
+    expect(resolveStartupIssuer({}, { PARACHUTE_HUB_ORIGIN: "/" })).toBeUndefined();
+  });
+});

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/api-modules-ops.ts

@@ -401,11 +401,35 @@ 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.
+  //
+  // PARACHUTE_HUB_ORIGIN propagation (hub#365): supervised modules
+  // (vault, scribe, app) need to know the canonical hub origin to
+  // validate the `iss` claim on hub-minted JWTs. Without it, they
+  // fall back to a loopback default and reject any token whose iss is
+  // the public Render URL — surfaces as "hub JWT verification failed:
+  // unexpected 'iss' claim value" on the first authed vault call.
+  // `deps.issuer` is per-request, derived via resolveIssuer (which
+  // honors X-Forwarded-Proto / Host). Passing it as PARACHUTE_HUB_ORIGIN
+  // anchors the child's iss expectation to the same value hub mints with.
+  //
+  // `deps.spawnEnv` still wins (test seam + first-boot vault-name pass-through).
+  const childEnv: Record<string, string> = {
+    PORT: String(entry.port),
+    ...(deps.issuer ? { PARACHUTE_HUB_ORIGIN: deps.issuer } : {}),
+    ...(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/lifecycle.ts

@@ -436,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;

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

@@ -110,6 +110,41 @@ function parsePort(raw: string | undefined): number | undefined {
   return n;
 }
 
+/**
+ * Derive the canonical issuer URL hub uses for JWT iss claims + propagation
+ * to supervised modules' PARACHUTE_HUB_ORIGIN env.
+ *
+ * Precedence (highest first):
+ *   1. Explicit `--issuer` flag (test override too)
+ *   2. `PARACHUTE_HUB_ORIGIN` env (operator-set, typical custom-domain case)
+ *   3. Platform-injected public URL — currently Render's RENDER_EXTERNAL_URL.
+ *      This is the load-bearing tier for container deploys where the
+ *      operator can't know the URL at deploy time. Render generates the
+ *      *.onrender.com hostname after service creation and injects it for
+ *      web services; hub picks it up automatically.
+ *   4. None (returns undefined). Hub falls back to per-request derivation
+ *      via `resolveIssuer` in hub-server.ts — works for `/.well-known`
+ *      discovery but supervised modules with cached iss expectations
+ *      won't have a static value to validate against, so OAuth flows
+ *      through hub-mint → vault-validate will fail with iss-mismatch.
+ *      This is the "no canonical origin known" degraded mode.
+ *
+ * Future platforms (Fly's `FLY_APP_NAME` + region, Railway's
+ * `RAILWAY_PUBLIC_DOMAIN`, etc.) can extend tier 3 as needed.
+ *
+ * Trailing slashes are stripped for canonical-form comparison; empty
+ * strings collapse to undefined.
+ */
+export function resolveStartupIssuer(
+  opts: { issuer?: string },
+  env: NodeJS.ProcessEnv,
+): string | undefined {
+  return (
+    (opts.issuer ?? env.PARACHUTE_HUB_ORIGIN ?? env.RENDER_EXTERNAL_URL)?.replace(/\/+$/, "") ||
+    undefined
+  );
+}
+
 /**
  * Seed the initial admin from env vars when no admin exists. Returns the
  * bootstrap state so the caller can log it for operator visibility.
@@ -189,7 +224,7 @@ export async function serve(opts: ServeOpts = {}): Promise<{
 
   const envPort = parsePort(env.PORT);
   const port = opts.port ?? envPort ?? DEFAULT_PORT;
-  const issuer = (opts.issuer ?? env.PARACHUTE_HUB_ORIGIN)?.replace(/\/+$/, "") || undefined;
+  const issuer = resolveStartupIssuer(opts, env);
   // Containers default to 0.0.0.0 so the platform's HTTP forwarder can
   // reach us; the `--hostname` flag / PARACHUTE_BIND_HOST is the escape
   // hatch for setups that want loopback-only inside a sidecar.

package/src/hub-server.ts

@@ -213,8 +213,14 @@ interface Args {
  *                                Containers should set 0.0.0.0.
  *   PARACHUTE_HUB_ORIGIN       — canonical https://… origin used as the
  *                                OAuth issuer claim.
+ *   RENDER_EXTERNAL_URL        — Render auto-injects the public https URL;
+ *                                used as fallback issuer so the standalone
+ *                                `bun src/hub-server.ts` boot path works
+ *                                without operator config. Mirrors the
+ *                                precedence in commands/serve.ts's
+ *                                resolveStartupIssuer.
  */
-function parseArgs(argv: string[], env: NodeJS.ProcessEnv = process.env): Args {
+export function parseArgs(argv: string[], env: NodeJS.ProcessEnv = process.env): Args {
   let port: number | undefined;
   let hostname: string | undefined;
   let wellKnownDir: string | undefined;
@@ -250,8 +256,9 @@ function parseArgs(argv: string[], env: NodeJS.ProcessEnv = process.env): Args {
   if (port === undefined) port = HUB_DEFAULT_PORT;
   if (hostname === undefined) hostname = env.PARACHUTE_BIND_HOST || "127.0.0.1";
   if (wellKnownDir === undefined) wellKnownDir = WELL_KNOWN_DIR;
-  if (issuer === undefined && env.PARACHUTE_HUB_ORIGIN) {
-    issuer = env.PARACHUTE_HUB_ORIGIN.replace(/\/+$/, "");
+  if (issuer === undefined) {
+    const fromEnv = env.PARACHUTE_HUB_ORIGIN ?? env.RENDER_EXTERNAL_URL;
+    if (fromEnv) issuer = fromEnv.replace(/\/+$/, "") || undefined;
   }
   return { port, hostname, wellKnownDir, dbPath: dbPath ?? hubDbPath(), issuer };
 }
@@ -418,9 +425,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,
@@ -953,11 +979,16 @@ export function resolveIssuer(
   // 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. 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.
+  // 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:";