@openparachute/hub 0.7.0 → 0.7.2-rc.1

package/src/__tests__/clients.test.ts

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import {
   InvalidRedirectUriError,
   approveClient,
+  expandRedirectUrisForHubOrigins,
   getClient,
   isValidRedirectUri,
   listClientsByStatus,
@@ -144,6 +145,96 @@ describe("requireRegisteredRedirectUri", () => {
   });
 });
 
+describe("expandRedirectUrisForHubOrigins (surface#118 cross-hub-origin DCR expansion)", () => {
+  const LOOPBACK = "http://127.0.0.1:1939";
+  const PUBLIC = "https://box.taildf9ce2.ts.net";
+  const hubOrigins = [LOOPBACK, "http://localhost:1939", PUBLIC];
+
+  test("expands a loopback-rooted URI onto every other hub origin", () => {
+    const out = expandRedirectUrisForHubOrigins([`${LOOPBACK}/surface/notes/oauth/callback`], hubOrigins);
+    // Original is preserved + the public + localhost variants are added.
+    expect(out).toContain(`${LOOPBACK}/surface/notes/oauth/callback`);
+    expect(out).toContain(`${PUBLIC}/surface/notes/oauth/callback`);
+    expect(out).toContain("http://localhost:1939/surface/notes/oauth/callback");
+    // The submitted URI comes first (order-preserving).
+    expect(out[0]).toBe(`${LOOPBACK}/surface/notes/oauth/callback`);
+  });
+
+  test("INVARIANT: a foreign-origin URI is stored verbatim — not expanded, not dropped", () => {
+    const foreign = "https://my-vault-ui.example/oauth/callback";
+    const out = expandRedirectUrisForHubOrigins([foreign], hubOrigins);
+    // Stored exactly as submitted...
+    expect(out).toContain(foreign);
+    // ...and NOTHING was minted on any hub origin from it (no open redirect).
+    expect(out).toEqual([foreign]);
+    for (const o of hubOrigins) {
+      expect(out).not.toContain(`${o}/oauth/callback`);
+    }
+  });
+
+  test("mixed submit: hub-origin URI expands, foreign URI rides verbatim alongside", () => {
+    const foreign = "https://evil.example/cb";
+    const out = expandRedirectUrisForHubOrigins(
+      [`${LOOPBACK}/surface/notes/`, foreign],
+      hubOrigins,
+    );
+    // Hub-origin URI fanned out to the public origin.
+    expect(out).toContain(`${PUBLIC}/surface/notes/`);
+    // Foreign URI present, but no hub-origin variant of it exists.
+    expect(out).toContain(foreign);
+    for (const o of hubOrigins) {
+      expect(out).not.toContain(`${o}/cb`);
+    }
+  });
+
+  test("single known hub origin → no expansion (submitted set returned as-is)", () => {
+    const out = expandRedirectUrisForHubOrigins(
+      [`${LOOPBACK}/surface/notes/`],
+      [LOOPBACK],
+    );
+    expect(out).toEqual([`${LOOPBACK}/surface/notes/`]);
+  });
+
+  test("dedupes — already-public + loopback submit doesn't double-register", () => {
+    const out = expandRedirectUrisForHubOrigins(
+      [`${LOOPBACK}/surface/notes/`, `${PUBLIC}/surface/notes/`],
+      hubOrigins,
+    );
+    const publicCount = out.filter((u) => u === `${PUBLIC}/surface/notes/`).length;
+    expect(publicCount).toBe(1);
+  });
+
+  test("path + query + hash are preserved across origins", () => {
+    const out = expandRedirectUrisForHubOrigins(
+      [`${LOOPBACK}/surface/notes/oauth-callback?foo=bar`],
+      hubOrigins,
+    );
+    expect(out).toContain(`${PUBLIC}/surface/notes/oauth-callback?foo=bar`);
+  });
+
+  test("expanded URIs survive registerClient → requireRegisteredRedirectUri strict match", () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const expanded = expandRedirectUrisForHubOrigins(
+        [`${LOOPBACK}/surface/notes/oauth/callback`],
+        hubOrigins,
+      );
+      const r = registerClient(db, { redirectUris: expanded });
+      // The public-origin variant now matches exactly at authorize time — the
+      // off-localhost sign-in that surface#118 broke.
+      expect(
+        requireRegisteredRedirectUri(r.client, `${PUBLIC}/surface/notes/oauth/callback`),
+      ).toBe(`${PUBLIC}/surface/notes/oauth/callback`);
+      // A truly-unregistered URI is still rejected — strict match unchanged.
+      expect(() =>
+        requireRegisteredRedirectUri(r.client, "https://evil.example/surface/notes/oauth/callback"),
+      ).toThrow(InvalidRedirectUriError);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
 describe("verifyClientSecret", () => {
   test("matches the issued secret, rejects others", () => {
     const { db, cleanup } = makeDb();

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

@@ -0,0 +1,219 @@
+/**
+ * Tests for the agent-connector grant store (`grants-store.ts`, 4b-1).
+ *
+ * Distinct from `grants.test.ts` (the OAuth consent skip-list in SQLite). This
+ * is the on-disk JSON store for approval-gated agent grants: round-trip, 0600
+ * perms (the file holds the granted secrets), idempotency-key derivation, and
+ * the lenient-read posture.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  type ConnectionSpec,
+  type GrantRecord,
+  connectionKey,
+  getGrant,
+  grantId,
+  listGrantsForAgent,
+  putGrant,
+  readGrants,
+  removeGrant,
+} from "../grants-store.ts";
+
+let dir: string;
+let storePath: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "phub-grants-store-"));
+  storePath = join(dir, "agent-grants.json");
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function vaultSpec(over: Partial<ConnectionSpec> = {}): ConnectionSpec {
+  return { kind: "vault", target: "research", access: "read", ...over };
+}
+
+function rec(over: Partial<GrantRecord> = {}): GrantRecord {
+  const connection = over.connection ?? vaultSpec();
+  return {
+    id: over.id ?? grantId("agent1", connection),
+    agent: over.agent ?? "agent1",
+    connection,
+    status: over.status ?? "pending",
+    createdAt: over.createdAt ?? "2026-06-17T00:00:00.000Z",
+    ...(over.reason ? { reason: over.reason } : {}),
+    ...(over.material ? { material: over.material } : {}),
+    ...(over.approvedAt ? { approvedAt: over.approvedAt } : {}),
+  };
+}
+
+describe("round-trip", () => {
+  test("a missing file reads as empty", () => {
+    expect(readGrants(storePath)).toEqual([]);
+  });
+
+  test("put → read returns the record", () => {
+    const r = rec();
+    putGrant(storePath, r);
+    const back = readGrants(storePath);
+    expect(back).toHaveLength(1);
+    expect(back[0]).toEqual(r);
+  });
+
+  test("put upserts by id (no duplicate row)", () => {
+    const r = rec();
+    putGrant(storePath, r);
+    putGrant(storePath, { ...r, status: "approved", approvedAt: "2026-06-18T00:00:00.000Z" });
+    const back = readGrants(storePath);
+    expect(back).toHaveLength(1);
+    expect(back[0]?.status).toBe("approved");
+  });
+
+  test("getGrant + removeGrant", () => {
+    const r = rec();
+    putGrant(storePath, r);
+    expect(getGrant(storePath, r.id)?.id).toBe(r.id);
+    const removed = removeGrant(storePath, r.id);
+    expect(removed?.id).toBe(r.id);
+    expect(getGrant(storePath, r.id)).toBeNull();
+  });
+
+  test("listGrantsForAgent filters by agent (case-insensitive)", () => {
+    putGrant(storePath, rec({ id: "a", agent: "AgentOne" }));
+    putGrant(
+      storePath,
+      rec({ id: "b", agent: "agenttwo", connection: vaultSpec({ target: "x" }) }),
+    );
+    expect(listGrantsForAgent(storePath, "agentone")).toHaveLength(1);
+    expect(listGrantsForAgent(storePath, "AGENTTWO")).toHaveLength(1);
+    expect(listGrantsForAgent(storePath, "nope")).toHaveLength(0);
+  });
+});
+
+describe("0600 perms (the file holds secrets)", () => {
+  test("the store file is created mode 0600", () => {
+    putGrant(
+      storePath,
+      rec({
+        status: "approved",
+        material: { kind: "service", token: "ghp_secret" },
+        connection: { kind: "service", target: "github" },
+      }),
+    );
+    const mode = statSync(storePath).mode & 0o777;
+    expect(mode).toBe(0o600);
+  });
+});
+
+describe("lenient read", () => {
+  test("garbage JSON reads as empty", () => {
+    writeFileSync(storePath, "not json {{{");
+    expect(readGrants(storePath)).toEqual([]);
+  });
+
+  test("a top-level array (wrong shape) reads as empty", () => {
+    writeFileSync(storePath, JSON.stringify([{ id: "x" }]));
+    expect(readGrants(storePath)).toEqual([]);
+  });
+
+  test("a malformed row is dropped, valid rows survive", () => {
+    const valid = rec();
+    writeFileSync(
+      storePath,
+      JSON.stringify({
+        grants: [
+          valid,
+          { id: "missing-agent" }, // no agent/connection/status → dropped
+          { id: "bad-status", agent: "a", connection: vaultSpec(), status: "weird" }, // bad status → dropped
+        ],
+      }),
+    );
+    const back = readGrants(storePath);
+    expect(back).toHaveLength(1);
+    expect(back[0]?.id).toBe(valid.id);
+  });
+});
+
+describe("4b-2 mcp material + needs_consent (regression)", () => {
+  test("mcp material round-trips (OAuth shape)", () => {
+    const r = rec({
+      status: "approved",
+      connection: { kind: "mcp", target: "https://remote.test/mcp" },
+      material: {
+        kind: "mcp",
+        access_token: "at-1",
+        refresh_token: "rt-1",
+        expiresAt: "2026-06-18T13:00:00.000Z",
+        issuer: "https://issuer.test",
+        clientId: "cid-1",
+        tokenEndpoint: "https://issuer.test/oauth/token",
+        revocationEndpoint: "https://issuer.test/oauth/revoke",
+        mcpUrl: "https://remote.test/mcp",
+      },
+    });
+    putGrant(storePath, r);
+    const back = readGrants(storePath);
+    expect(back).toHaveLength(1);
+    expect(back[0]).toEqual(r);
+  });
+
+  test("mcp static-bearer material round-trips (no refresh)", () => {
+    const r = rec({
+      status: "approved",
+      connection: { kind: "mcp", target: "https://remote.test/mcp" },
+      material: { kind: "mcp", access_token: "static-paste", mcpUrl: "https://remote.test/mcp" },
+    });
+    putGrant(storePath, r);
+    expect(readGrants(storePath)[0]).toEqual(r);
+  });
+
+  test("a needs_consent row SURVIVES readGrants (the 4b-2 blocker regression)", () => {
+    const r = rec({
+      status: "needs_consent",
+      reason: "refresh failed: invalid_grant",
+      connection: { kind: "mcp", target: "https://remote.test/mcp" },
+    });
+    putGrant(storePath, r);
+    const back = readGrants(storePath);
+    expect(back).toHaveLength(1);
+    expect(back[0]?.status).toBe("needs_consent");
+    expect(getGrant(storePath, r.id)?.status).toBe("needs_consent");
+  });
+});
+
+describe("connectionKey / grantId derivation (idempotency)", () => {
+  test("vault key includes access + sorted tags", () => {
+    expect(connectionKey(vaultSpec())).toBe("vault:research:read");
+    expect(connectionKey(vaultSpec({ access: "write" }))).toBe("vault:research:write");
+    // tag order doesn't change the key
+    const a = connectionKey(vaultSpec({ tags: ["#b", "#a"] }));
+    const b = connectionKey(vaultSpec({ tags: ["#a", "#b"] }));
+    expect(a).toBe(b);
+    expect(a).toBe("vault:research:read##a,#b");
+  });
+
+  test("service key ignores inject (re-declare with new inject → same key)", () => {
+    const k1 = connectionKey({ kind: "service", target: "github", inject: ["env"] });
+    const k2 = connectionKey({ kind: "service", target: "github", inject: ["env", "mcp"] });
+    expect(k1).toBe(k2);
+    expect(k1).toBe("service:github");
+  });
+
+  test("mcp key is the url target", () => {
+    expect(connectionKey({ kind: "mcp", target: "https://x.test/mcp" })).toBe(
+      "mcp:https://x.test/mcp",
+    );
+  });
+
+  test("grantId is a stable URL-safe slug from agent + key", () => {
+    const id = grantId("agent1", vaultSpec());
+    expect(id).toMatch(/^[a-z0-9][a-z0-9-]*$/);
+    // deterministic
+    expect(grantId("agent1", vaultSpec())).toBe(id);
+    // different connection → different id
+    expect(grantId("agent1", vaultSpec({ access: "write" }))).not.toBe(id);
+  });
+});

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

@@ -380,6 +380,42 @@ describe("openHubDb + migrate", () => {
     }
   });
 
+  test("v13 adds invites.username; pre-existing invite rows keep NULL (no backfill)", () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(h.dbPath);
+      try {
+        // Simulate a real v12 install: strip the v13 column, mark v13
+        // unapplied, and seed an invite row that pre-dates pre-naming.
+        db.exec(`
+          ALTER TABLE invites DROP COLUMN username;
+          INSERT INTO invites (token, created_by, vault_name, role, provision_vault,
+                               default_mirror, expires_at, created_at)
+          VALUES ('hash-v12', NULL, 'maya', 'write', 1, NULL,
+                  '2099-01-01T00:00:00.000Z', '2026-06-01T00:00:00.000Z');
+        `);
+        db.exec("DELETE FROM schema_version WHERE version = 13");
+        migrate(db);
+        const cols = db
+          .query<{ name: string }, []>("SELECT name FROM pragma_table_info('invites')")
+          .all()
+          .map((c) => c.name);
+        expect(cols).toContain("username");
+        // Grandfathered row → NULL (redeemer picks their own name).
+        const row = db
+          .query<{ username: string | null }, [string]>(
+            "SELECT username FROM invites WHERE token = ?",
+          )
+          .get("hash-v12");
+        expect(row?.username).toBeNull();
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("v10 FK cascade: deleting a user drops their user_vaults rows", () => {
     const h = makeHarness();
     try {

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

@@ -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";
@@ -1575,8 +1576,10 @@ describe("hubFetch routing", () => {
   });
 
   // Pre-admin lockout (hub#258). When no admin row exists, operator-
-  // facing surfaces (admin/api/login) 503 with a JSON body pointing at
-  // /admin/setup. Public surfaces (health, well-known, /, oauth, vault,
+  // facing API surfaces (admin/api) 503 with a JSON body pointing at
+  // /admin/setup. The browser-facing `/login` GET 302s to the wizard
+  // instead (hub#644) — a JSON 503 there would render as raw text in the
+  // visitor's tab. Public surfaces (health, well-known, /, oauth, vault,
   // /admin/setup itself) stay open so the container is reachable and
   // OAuth third parties aren't held hostage by admin onboarding.
   test("pre-admin lockout: /admin/vaults returns 503 setup_required", async () => {
@@ -1614,7 +1617,7 @@ describe("hubFetch routing", () => {
     }
   });
 
-  test("pre-admin lockout: /login is gated, /admin/setup + /health + well-known stay open, / funnels to /admin/setup", async () => {
+  test("pre-admin lockout: /login GET funnels to /admin/setup, /admin/setup + /health + well-known stay open, / funnels to /admin/setup", async () => {
     const h = makeHarness();
     try {
       writeFileSync(join(h.dir, "hub.html"), "<html>discovery</html>");
@@ -1622,9 +1625,11 @@ describe("hubFetch routing", () => {
       const db = openHubDb(hubDbPath(h.dir));
       try {
         const handler = hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath });
-        // /login gated
+        // /login GET funnels to the wizard (hub#644) — the browser-facing
+        // sign-in surface 302s to /admin/setup instead of a raw JSON 503.
         const loginRes = await handler(req("/login"));
-        expect(loginRes.status).toBe(503);
+        expect(loginRes.status).toBe(302);
+        expect(loginRes.headers.get("location")).toBe("/admin/setup");
         // /admin/setup open
         const setupRes = await handler(req("/admin/setup"));
         expect(setupRes.status).toBe(200);
@@ -5580,3 +5585,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();
+  });
+});