npm - @openparachute/hub - Versions diffs - 0.6.5-rc.8 → 0.7.1 - Mend

@openparachute/hub 0.6.5-rc.8 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (69) hide show

package/package.json +1 -1
package/src/__tests__/account-setup.test.ts +310 -6
package/src/__tests__/account-vault-admin-token.test.ts +35 -3
package/src/__tests__/admin-channel-token.test.ts +173 -0
package/src/__tests__/admin-connections-credentials.test.ts +1320 -0
package/src/__tests__/admin-connections.test.ts +1154 -0
package/src/__tests__/admin-csrf-belt.test.ts +346 -0
package/src/__tests__/admin-module-token.test.ts +311 -0
package/src/__tests__/admin-vaults.test.ts +590 -0
package/src/__tests__/api-invites.test.ts +166 -6
package/src/__tests__/api-modules-ops.test.ts +70 -5
package/src/__tests__/api-modules.test.ts +262 -79
package/src/__tests__/audience-gate.test.ts +752 -0
package/src/__tests__/hub-db.test.ts +36 -0
package/src/__tests__/hub-server.test.ts +585 -21
package/src/__tests__/invites.test.ts +91 -1
package/src/__tests__/lifecycle.test.ts +238 -3
package/src/__tests__/module-manifest.test.ts +305 -8
package/src/__tests__/serve-boot.test.ts +133 -2
package/src/__tests__/service-spec-discovery.test.ts +109 -0
package/src/__tests__/setup-gate.test.ts +13 -7
package/src/__tests__/setup-wizard.test.ts +228 -1
package/src/__tests__/vault-name.test.ts +20 -5
package/src/__tests__/well-known.test.ts +44 -8
package/src/__tests__/ws-bridge.test.ts +573 -0
package/src/__tests__/ws-connection-caps.test.ts +456 -0
package/src/account-setup.ts +94 -23
package/src/account-vault-admin-token.ts +43 -14
package/src/admin-channel-token.ts +135 -0
package/src/admin-connections.ts +1882 -0
package/src/admin-login-ui.ts +64 -15
package/src/admin-module-token.ts +197 -0
package/src/admin-vaults.ts +399 -12
package/src/api-hub-upgrade.ts +4 -3
package/src/api-invites.ts +92 -12
package/src/api-modules-ops.ts +41 -16
package/src/api-modules.ts +238 -116
package/src/api-tokens.ts +8 -5
package/src/audience-gate.ts +268 -0
package/src/chrome-strip.ts +8 -1
package/src/commands/lifecycle.ts +187 -47
package/src/commands/serve-boot.ts +80 -3
package/src/commands/setup.ts +4 -4
package/src/connections-store.ts +191 -0
package/src/grants.ts +50 -0
package/src/help.ts +13 -6
package/src/host-admin-token-validation.ts +6 -2
package/src/hub-db.ts +26 -1
package/src/hub-server.ts +849 -70
package/src/invites.ts +91 -2
package/src/jwt-sign.ts +47 -1
package/src/module-manifest.ts +536 -23
package/src/origin-check.ts +109 -0
package/src/proxy-error-ui.ts +1 -1
package/src/service-spec.ts +132 -41
package/src/services-manifest.ts +97 -0
package/src/setup-wizard.ts +68 -6
package/src/users.ts +11 -0
package/src/vault-name.ts +27 -7
package/src/well-known.ts +41 -33
package/src/ws-bridge.ts +256 -0
package/src/ws-connection-caps.ts +170 -0
package/web/ui/dist/assets/index-Cxtod68O.js +61 -0
package/web/ui/dist/assets/index-E_9wqjEm.css +1 -0
package/web/ui/dist/index.html +2 -2
package/src/__tests__/api-modules-config.test.ts +0 -882
package/src/api-modules-config.ts +0 -421
package/web/ui/dist/assets/index-BYYUeLGA.css +0 -1
package/web/ui/dist/assets/index-D3cDUOOj.js +0 -61

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

@@ -13,6 +13,7 @@ import {
   hubFetch,
   layerOf,
   parseArgs,
+  resolveClientIp,
 } from "../hub-server.ts";
 import { setNotesRedirectDisabled } from "../hub-settings.ts";
 import { clearNotesRedirectLogState } from "../notes-redirect.ts";
@@ -85,20 +86,26 @@ function vaultEntry(name: string): ServiceEntry {
 }
 describe("hubFetch routing", () => {
-  test("/ serves hub.html with text/html content-type", async () => {
+  // Admin-shell IA (R1): the bare `/` page redirects into the single coherent
+  // admin shell at `/admin`. The old discovery-page content moved into the
+  // shell's Home overview. Only the bare `/` redirects — `/hub.html` still
+  // serves the discovery page (static expose file + explicit-`.html` bookmarks).
+  test("/ redirects (302) to /admin (admin-shell IA)", async () => {
     const h = makeHarness();
     try {
+      // No DB → exercises the redirect on the static-fallback path. The
+      // redirect sits above the static hub.html serve, so it fires regardless
+      // of whether a disk file exists.
       writeFileSync(join(h.dir, "hub.html"), "<html><body>hi</body></html>");
       const res = await hubFetch(h.dir)(req("/"));
-      expect(res.status).toBe(200);
-      expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
-      expect(await res.text()).toContain("<html>");
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toBe("/admin");
     } finally {
       h.cleanup();
     }
   });
-  test("/hub.html serves the same file as / (no DB → static fallback)", async () => {
+  test("/hub.html still serves the discovery page (no DB → static fallback)", async () => {
     const h = makeHarness();
     try {
       writeFileSync(join(h.dir, "hub.html"), "<html>x</html>");
@@ -173,11 +180,14 @@ describe("hubFetch routing", () => {
     }
   });
-  test("/ renders the signed-out indicator dynamically when DB is configured but no session cookie (rc.13)", async () => {
+  test("/hub.html renders the signed-out indicator dynamically when DB is configured but no session cookie (rc.13)", async () => {
     // The dynamic path takes over from the static disk file the moment a
     // DB is configured. With no session cookie, we still render — just
     // with the "Sign in" affordance.
     //
+    // Targets `/hub.html` (not `/`): bare `/` now 302-redirects to the admin
+    // shell (R1). `/hub.html` still serves the dynamic discovery page.
+    //
     // 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.
@@ -198,7 +208,7 @@ describe("hubFetch routing", () => {
         const res = await hubFetch(h.dir, {
           getDb: () => db,
           manifestPath: h.manifestPath,
-        })(req("/"));
+        })(req("/hub.html"));
         expect(res.status).toBe(200);
         expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
         const body = await res.text();
@@ -213,10 +223,11 @@ describe("hubFetch routing", () => {
     }
   });
-  test("/ renders 'Signed in as <name>' + sign-out form when session cookie is active (rc.13)", async () => {
+  test("/hub.html 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.
+    // to ~/.parachute/services.json. Targets `/hub.html` (bare `/` now
+    // redirects to the admin shell, R1).
     const h = makeHarness();
     try {
       writeManifest({ services: [vaultEntry("default")] }, h.manifestPath);
@@ -232,7 +243,7 @@ describe("hubFetch routing", () => {
         const res = await hubFetch(h.dir, {
           getDb: () => db,
           manifestPath: h.manifestPath,
-        })(req("/", { headers: { cookie } }));
+        })(req("/hub.html", { headers: { cookie } }));
         expect(res.status).toBe(200);
         const body = await res.text();
         expect(body).toContain("Signed in as");
@@ -249,6 +260,36 @@ describe("hubFetch routing", () => {
     }
   });
+  test("/ → /admin even with a DB + admin + vault (setup complete; not the wizard funnel)", async () => {
+    // Distinguishes the admin-shell redirect (302 → /admin) from the fresh-hub
+    // wizard funnel (302 → /admin/setup). With admin + vault seeded, the wizard
+    // funnel is bypassed and the bare `/` lands on the admin shell. Also proves
+    // the redirect fires on the DB-configured path, not just the static
+    // fallback. `/hub.html` under the same setup still renders the discovery
+    // page (asserted separately above) — only bare `/` redirects.
+    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 handler = hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath });
+        const rootRes = await handler(req("/"));
+        expect(rootRes.status).toBe(302);
+        expect(rootRes.headers.get("location")).toBe("/admin");
+        // /hub.html under the same setup-complete state still serves discovery.
+        const hubHtmlRes = await handler(req("/hub.html"));
+        expect(hubHtmlRes.status).toBe(200);
+        expect(hubHtmlRes.headers.get("content-type")).toBe("text/html; charset=utf-8");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
   test("/.well-known/parachute.json builds the doc dynamically from services.json", async () => {
     const h = makeHarness();
     try {
@@ -648,8 +689,9 @@ describe("hubFetch routing", () => {
   test("missing hub.html returns 404 rather than crashing", async () => {
     const h = makeHarness();
     try {
-      // dir exists but no files in it
-      const res = await hubFetch(h.dir)(req("/"));
+      // dir exists but no files in it. Targets `/hub.html` directly — bare `/`
+      // now 302-redirects to the admin shell before reaching the static serve.
+      const res = await hubFetch(h.dir)(req("/hub.html"));
       expect(res.status).toBe(404);
     } finally {
       h.cleanup();
@@ -932,23 +974,28 @@ describe("hubFetch routing", () => {
   // 301-redirect to the new /admin/* mount. Tests cover every entry in the
   // dispatch — operator bookmarks landing on any of these still work.
-  test("301: /vault → /admin/vaults", async () => {
+  // B5 (2026-06-09 hub-module-boundary): the legacy `/vault[/new]` 301s point
+  // DIRECTLY at vault's daemon-level admin surface — not at /admin/vaults,
+  // whose SPA route is now just a feature-detected forwarder. Pointing at the
+  // final target avoids a redirect → SPA-load → client-side-forward chain.
+  test("301: /vault → /vault/admin/ (direct — no chain through /admin/vaults)", async () => {
     const h = makeHarness();
     try {
       const res = await hubFetch(h.dir)(req("/vault"));
       expect(res.status).toBe(301);
-      expect(res.headers.get("location")).toBe("/admin/vaults");
+      expect(res.headers.get("location")).toBe("/vault/admin/");
     } finally {
       h.cleanup();
     }
   });
-  test("301: /vault/new → /admin/vaults/new", async () => {
+  test("301: /vault/new → /vault/admin/ (create relocated into vault's surface)", async () => {
     const h = makeHarness();
     try {
       const res = await hubFetch(h.dir)(req("/vault/new"));
       expect(res.status).toBe(301);
-      expect(res.headers.get("location")).toBe("/admin/vaults/new");
+      expect(res.headers.get("location")).toBe("/vault/admin/");
     } finally {
       h.cleanup();
     }
@@ -959,7 +1006,7 @@ describe("hubFetch routing", () => {
     try {
       const res = await hubFetch(h.dir)(req("/vault?next=foo"));
       expect(res.status).toBe(301);
-      expect(res.headers.get("location")).toBe("/admin/vaults?next=foo");
+      expect(res.headers.get("location")).toBe("/vault/admin/?next=foo");
     } finally {
       h.cleanup();
     }
@@ -1622,7 +1669,7 @@ describe("hubFetch routing", () => {
     }
   });
-  test("live Bun.serve round-trip: / and /.well-known resolve", async () => {
+  test("live Bun.serve round-trip: /, /hub.html and /.well-known resolve", async () => {
     const h = makeHarness();
     try {
       writeFileSync(join(h.dir, "hub.html"), "<html>live</html>");
@@ -1634,9 +1681,15 @@ describe("hubFetch routing", () => {
       });
       try {
         const base = `http://127.0.0.1:${server.port}`;
-        const r1 = await fetch(`${base}/`);
-        expect(r1.status).toBe(200);
-        expect(await r1.text()).toBe("<html>live</html>");
+        // Bare `/` 302-redirects into the admin shell (R1). `redirect: "manual"`
+        // so we observe the redirect itself rather than following it to /admin.
+        const r1 = await fetch(`${base}/`, { redirect: "manual" });
+        expect(r1.status).toBe(302);
+        expect(r1.headers.get("location")).toBe("/admin");
+        // The discovery page still serves at /hub.html.
+        const rHub = await fetch(`${base}/hub.html`);
+        expect(rHub.status).toBe(200);
+        expect(await rHub.text()).toBe("<html>live</html>");
         const r2 = await fetch(`${base}/.well-known/parachute.json`);
         expect(r2.headers.get("content-type")).toBe("application/json");
         expect(await r2.json()).toEqual({ vaults: [], services: [] });
@@ -4051,6 +4104,208 @@ describe("hubFetch publicExposure layer-gate (proxyToVault)", () => {
   });
 });
+describe("hubFetch /vault/admin daemon-level mount (B-route, hub-module-boundary)", () => {
+  // /vault/admin + /vault/admin/* route to the vault MODULE's daemon
+  // (resolved via findServiceByShort, not findVaultUpstream) — the
+  // daemon-level multi-vault admin surface, not an instance path. "admin"
+  // is a reserved vault name (B2h) so no instance can ever claim the mount.
+  /** Upstream that ECHOES the request path, so the tests can pin both which
+   * daemon got the request and that the FULL path was forwarded (vault's
+   * row declares no stripPrefix). */
+  function startEchoUpstream(tag: string): { port: number; stop: () => void } {
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: (r) =>
+        new Response(JSON.stringify({ tag, path: new URL(r.url).pathname }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        }),
+    });
+    return { port: server.port as number, stop: () => server.stop(true) };
+  }
+  const fakeServer = (address: string) => ({ requestIP: () => ({ address }) });
+  test("/vault/admin and /vault/admin/* route to the vault module's daemon port with the FULL path", async () => {
+    const h = makeHarness();
+    const upstream = startEchoUpstream("vault-daemon");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              // The canonical self-registered row name — findServiceByShort
+              // resolves `parachute-vault` → short "vault".
+              name: "parachute-vault",
+              port: upstream.port,
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.5.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      for (const path of ["/vault/admin", "/vault/admin/", "/vault/admin/assets/app.js"]) {
+        const res = await fetcher(req(path));
+        expect(res.status).toBe(200);
+        const body = (await res.json()) as { tag: string; path: string };
+        expect(body.tag).toBe("vault-daemon");
+        // Full path forwarded — no prefix strip (vault routes /vault/admin itself).
+        expect(body.path).toBe(path);
+      }
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+  test("/vault/admin is NOT captured by a per-instance mount — daemon-level route wins", async () => {
+    // A pathological vault row mounted at the bare `/vault` would prefix-match
+    // `/vault/admin` in findVaultUpstream; the daemon-level branch runs FIRST
+    // so the per-vault proxy never sees the path (and no consumer can
+    // fabricate a phantom instance named "admin"). With distinct upstream
+    // ports we can tell exactly which one served the request.
+    const h = makeHarness();
+    const daemonUpstream = startEchoUpstream("vault-daemon");
+    const instanceUpstream = startEchoUpstream("vault-instance");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: daemonUpstream.port,
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.5.0",
+            },
+            {
+              // Pathological-but-representable bare mount on a second row.
+              name: "parachute-vault-bare",
+              port: instanceUpstream.port,
+              paths: ["/vault"],
+              health: "/vault/health",
+              version: "0.5.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/vault/admin/"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string };
+      expect(body.tag).toBe("vault-daemon");
+    } finally {
+      daemonUpstream.stop();
+      instanceUpstream.stop();
+      h.cleanup();
+    }
+  });
+  test('a vault instance named "adminx" still routes per-instance (exact-segment match only)', async () => {
+    const h = makeHarness();
+    const upstream = startEchoUpstream("vault-daemon");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: upstream.port,
+              paths: ["/vault/adminx"],
+              health: "/vault/adminx/health",
+              version: "0.5.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      // Per-instance path — proxied through the per-vault dispatch (full
+      // path forwarded; vault rows don't strip).
+      const res = await fetcher(req("/vault/adminx/health"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { path: string };
+      expect(body.path).toBe("/vault/adminx/health");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+  test("404 cleanly when no vault module is installed", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              // Some other module installed — must not capture /vault/admin.
+              name: "parachute-scribe",
+              port: 1942,
+              paths: ["/scribe"],
+              health: "/scribe/health",
+              version: "0.1.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/vault/admin/"));
+      expect(res.status).toBe(404);
+    } finally {
+      h.cleanup();
+    }
+  });
+  test('publicExposure: "loopback" on the vault row cloaks /vault/admin from tailnet/public (same gate as proxyToVault)', async () => {
+    const h = makeHarness();
+    const upstream = startEchoUpstream("vault-daemon");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: upstream.port,
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.5.0",
+              publicExposure: "loopback",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      // Tailnet caller → cloaked.
+      const tailnet = await fetcher(
+        req("/vault/admin/", { headers: { "Tailscale-User-Login": "alice@example.com" } }),
+      );
+      expect(tailnet.status).toBe(404);
+      // Public caller → cloaked.
+      const pub = await fetcher(req("/vault/admin/", { headers: { "CF-Ray": "abc123" } }));
+      expect(pub.status).toBe(404);
+      // Header-absent NON-loopback peer (0.0.0.0 bind) → cloaked (#526 posture).
+      const direct = await fetcher(req("/vault/admin/"), fakeServer("198.51.100.4"));
+      expect(direct.status).toBe(404);
+      // Loopback peer → reaches the daemon.
+      const loop = await fetcher(req("/vault/admin/"), fakeServer("127.0.0.1"));
+      expect(loop.status).toBe(200);
+      expect(((await loop.json()) as { tag: string }).tag).toBe("vault-daemon");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+});
 /** Find a port that no one is listening on by binding briefly and releasing. */
 async function pickClosedPort(): Promise<number> {
   const s = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: () => new Response("x") });
@@ -5004,6 +5259,50 @@ describe("force-change-password per-request gate (#469)", () => {
     }
   });
+  test("(a) pre-rotation browser GET /vault/admin/ is 302'd to change-password (B-route gate parity)", async () => {
+    // The daemon-level /vault/admin mount applies the SAME per-request
+    // force-change-password gate as the per-vault proxy — a pre-rotation
+    // session can't reach the multi-vault admin surface on an un-rotated
+    // temp password either.
+    const h = makeHarness();
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              // Canonical row name so findServiceByShort would resolve it if
+              // the request ever got past the gate.
+              name: "parachute-vault",
+              port: 1940,
+              paths: ["/vault/work"],
+              health: "/vault/work/health",
+              version: "0.5.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const { cookie } = await seedUser(h, db, {
+          passwordChanged: false,
+          assignedVaults: ["work"],
+        });
+        const res = await hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath })(
+          req("/vault/admin/", { headers: { cookie, accept: "text/html" } }),
+        );
+        // Gated BEFORE proxyToVaultAdmin ever runs — the gate's 302, not a
+        // proxy 404/502.
+        expect(res.status).toBe(302);
+        expect(res.headers.get("location")).toBe("/account/change-password");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
   test("(b) pre-rotation user CAN still reach /account/change-password (GET)", async () => {
     const h = makeHarness();
     try {
@@ -5282,3 +5581,268 @@ describe("force-change-password per-request gate (#469)", () => {
     }
   });
 });
+describe("substrate trust headers — X-Parachute-Layer / X-Parachute-Client-IP (H2)", () => {
+  // The hub stamps the layerOf classification + resolved client IP on every
+  // request it forwards to a module upstream, STRIPPING any inbound
+  // occurrences first (a public client must not be able to inject a forged
+  // "loopback" trust signal past the proxy). Surface-runtime design §10.
+  function startEchoUpstream(): { port: number; stop: () => void } {
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: (req) =>
+        new Response(
+          JSON.stringify({
+            layer: req.headers.get("x-parachute-layer"),
+            clientIp: req.headers.get("x-parachute-client-ip"),
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        ),
+    });
+    return { port: server.port as number, stop: () => server.stop(true) };
+  }
+  const fakeServer = (address: string) => ({ requestIP: () => ({ address }) });
+  function writeEchoService(h: Harness, port: number): void {
+    writeManifest(
+      {
+        services: [
+          {
+            name: "echo-svc",
+            port,
+            paths: ["/echo-svc"],
+            health: "/echo-svc/health",
+            version: "0.1.0",
+          },
+        ],
+      },
+      h.manifestPath,
+    );
+  }
+  test("loopback direct-to-hub → stamped loopback + peer IP (generic proxy)", async () => {
+    const h = makeHarness();
+    const upstream = startEchoUpstream();
+    try {
+      writeEchoService(h, upstream.port);
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/echo-svc/x"), fakeServer("127.0.0.1"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { layer: string; clientIp: string };
+      expect(body.layer).toBe("loopback");
+      expect(body.clientIp).toBe("127.0.0.1");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+  test("tailnet request → stamped tailnet + X-Forwarded-For client IP", async () => {
+    const h = makeHarness();
+    const upstream = startEchoUpstream();
+    try {
+      writeEchoService(h, upstream.port);
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(
+        req("/echo-svc/x", {
+          headers: {
+            "tailscale-user-login": "aaron@example.com",
+            "x-forwarded-for": "100.64.0.7",
+          },
+        }),
+        fakeServer("127.0.0.1"),
+      );
+      const body = (await res.json()) as { layer: string; clientIp: string };
+      expect(body.layer).toBe("tailnet");
+      expect(body.clientIp).toBe("100.64.0.7");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+  test("public (cloudflared) request → stamped public + CF-Connecting-IP", async () => {
+    const h = makeHarness();
+    const upstream = startEchoUpstream();
+    try {
+      writeEchoService(h, upstream.port);
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(
+        req("/echo-svc/x", {
+          headers: { "cf-ray": "8abc123", "cf-connecting-ip": "203.0.113.9" },
+        }),
+        fakeServer("127.0.0.1"),
+      );
+      const body = (await res.json()) as { layer: string; clientIp: string };
+      expect(body.layer).toBe("public");
+      expect(body.clientIp).toBe("203.0.113.9");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+  test("inbound spoof is STRIPPED — public peer injecting loopback headers gets re-stamped", async () => {
+    // The attack H2's strip exists for: a direct network peer (0.0.0.0 bind)
+    // sends X-Parachute-Layer: loopback + a forged client IP. The hub must
+    // strip both and stamp its own fail-closed classification.
+    const h = makeHarness();
+    const upstream = startEchoUpstream();
+    try {
+      writeEchoService(h, upstream.port);
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(
+        req("/echo-svc/x", {
+          headers: {
+            "x-parachute-layer": "loopback",
+            "x-parachute-client-ip": "127.0.0.1",
+          },
+        }),
+        fakeServer("198.51.100.20"),
+      );
+      const body = (await res.json()) as { layer: string; clientIp: string };
+      expect(body.layer).toBe("public"); // header-absent non-loopback peer → public
+      expect(body.clientIp).toBe("198.51.100.20"); // peer address, not the forgery
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+  test("direct caller injecting CF-Connecting-IP: layer stamp stays sound (public), client IP is best-effort attribution", async () => {
+    // Pins the documented property (resolveClientIp's "Known limitation"):
+    // a DIRECT caller can spoof the forwarded-IP headers and misattribute
+    // its own address — X-Parachute-Client-IP reflects the injected value —
+    // but it CANNOT spoof the LAYER: the CF header's presence classifies the
+    // request "public" regardless of the peer (here even a loopback one),
+    // so spoofing only ever moves the trust signal DOWN. Layer is the
+    // security signal; client IP is attribution.
+    const h = makeHarness();
+    const upstream = startEchoUpstream();
+    try {
+      writeEchoService(h, upstream.port);
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(
+        req("/echo-svc/x", {
+          headers: { "cf-connecting-ip": "203.0.113.50" },
+        }),
+        fakeServer("127.0.0.1"),
+      );
+      const body = (await res.json()) as { layer: string; clientIp: string };
+      expect(body.layer).toBe("public"); // CF header presence → public, not loopback
+      expect(body.clientIp).toBe("203.0.113.50"); // injected value — best-effort by design
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+  test("unknown peer (no Server threaded) → fail-closed public, header for client IP omitted", async () => {
+    const h = makeHarness();
+    const upstream = startEchoUpstream();
+    try {
+      writeEchoService(h, upstream.port);
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      // No second arg — peerAddr resolves null; layer fails closed to public.
+      const res = await fetcher(req("/echo-svc/x"));
+      const body = (await res.json()) as { layer: string; clientIp: string | null };
+      expect(body.layer).toBe("public");
+      expect(body.clientIp).toBeNull();
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+  test("per-vault proxy stamps the same headers (shared proxyRequest path)", async () => {
+    const h = makeHarness();
+    const upstream = startEchoUpstream();
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault-default",
+              port: upstream.port,
+              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/api/notes"), fakeServer("127.0.0.1"));
+      const body = (await res.json()) as { layer: string; clientIp: string };
+      expect(body.layer).toBe("loopback");
+      expect(body.clientIp).toBe("127.0.0.1");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+  test("/vault/admin route stamps the same headers (proxyToVaultAdmin path)", async () => {
+    const h = makeHarness();
+    const upstream = startEchoUpstream();
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: upstream.port,
+              paths: ["/vault/default"],
+              health: "/health",
+              version: "0.5.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(
+        req("/vault/admin/", {
+          headers: { "tailscale-user-login": "aaron@example.com" },
+        }),
+        fakeServer("127.0.0.1"),
+      );
+      const body = (await res.json()) as { layer: string };
+      expect(body.layer).toBe("tailnet");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+});
+describe("resolveClientIp (H2)", () => {
+  test("CF-Connecting-IP wins over X-Forwarded-For and peer", () => {
+    const r = req("/", {
+      headers: { "cf-connecting-ip": "203.0.113.1", "x-forwarded-for": "10.0.0.1" },
+    });
+    expect(resolveClientIp(r, "127.0.0.1")).toBe("203.0.113.1");
+  });
+  test("X-Forwarded-For first hop wins over peer", () => {
+    const r = req("/", { headers: { "x-forwarded-for": "10.0.0.1, 10.0.0.2" } });
+    expect(resolveClientIp(r, "127.0.0.1")).toBe("10.0.0.1");
+  });
+  test("falls back to the peer address", () => {
+    expect(resolveClientIp(req("/"), "198.51.100.7")).toBe("198.51.100.7");
+  });
+  test("null when nothing resolves", () => {
+    expect(resolveClientIp(req("/"), null)).toBeNull();
+  });
+  test("whitespace-only header values are treated as absent", () => {
+    const r = req("/", { headers: { "x-forwarded-for": "   " } });
+    expect(resolveClientIp(r, null)).toBeNull();
+  });
+});