@openparachute/hub 0.7.5-rc.2 → 0.7.5-rc.4

package/src/__tests__/git-registry.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  ensureSurfaceRepo,
+  isSurfaceRegistered,
+  listSurfaces,
+  loadRegistry,
+  registerSurface,
+  registryPath,
+  repoDirFor,
+} from "../git-registry.ts";
+
+function tmpGitRoot(): { gitRoot: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), "phub-registry-"));
+  const gitRoot = join(dir, "git");
+  return { gitRoot, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+describe("loadRegistry", () => {
+  test("missing file → empty registry", () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      expect(loadRegistry(gitRoot)).toEqual({ version: 1, surfaces: {} });
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("corrupt JSON → empty registry (never throws)", () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      mkdirSync(gitRoot, { recursive: true });
+      writeFileSync(registryPath(gitRoot), "{ not json");
+      expect(loadRegistry(gitRoot)).toEqual({ version: 1, surfaces: {} });
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("ensureSurfaceRepo", () => {
+  test("provisions a bare repo with http.receivepack=true + post-receive hook", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      const repoDir = await ensureSurfaceRepo(gitRoot, "foo");
+      expect(repoDir).toBe(repoDirFor(gitRoot, "foo"));
+      expect(existsSync(repoDir)).toBe(true);
+      expect(existsSync(join(repoDir, "hooks", "post-receive"))).toBe(true);
+      const rp = spawnSync("git", ["-C", repoDir, "config", "http.receivepack"], {
+        encoding: "utf8",
+      });
+      expect(rp.stdout.trim()).toBe("true");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("idempotent — a second call is a no-op that returns the same path", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      const a = await ensureSurfaceRepo(gitRoot, "foo");
+      const b = await ensureSurfaceRepo(gitRoot, "foo");
+      expect(a).toBe(b);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("rejects an invalid surface name", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      await expect(ensureSurfaceRepo(gitRoot, "../evil")).rejects.toThrow();
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("registerSurface", () => {
+  test("provisions the repo + records the entry", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      const entry = await registerSurface(gitRoot, "brain", {
+        mount: "/surface/brain",
+        mode: "prod",
+      });
+      expect(entry.name).toBe("brain");
+      expect(entry.mount).toBe("/surface/brain");
+      expect(entry.mode).toBe("prod");
+      expect(existsSync(repoDirFor(gitRoot, "brain"))).toBe(true);
+      expect(loadRegistry(gitRoot).surfaces.brain?.name).toBe("brain");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("idempotent re-register preserves the original registeredAt", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      const first = await registerSurface(gitRoot, "brain", {
+        now: () => new Date("2026-01-01T00:00:00Z"),
+      });
+      const second = await registerSurface(gitRoot, "brain", {
+        mount: "/surface/brain",
+        now: () => new Date("2026-02-02T00:00:00Z"),
+      });
+      expect(second.registeredAt).toBe(first.registeredAt);
+      expect(second.registeredAt).toBe("2026-01-01T00:00:00.000Z");
+      // Later metadata still applies.
+      expect(second.mount).toBe("/surface/brain");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("rejects an invalid name without provisioning", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      await expect(registerSurface(gitRoot, "a/b")).rejects.toThrow(/invalid surface name/);
+      expect(existsSync(registryPath(gitRoot))).toBe(false);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("isSurfaceRegistered", () => {
+  test("false for an unknown name, true after register", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      expect(isSurfaceRegistered(gitRoot, "foo")).toBe(false);
+      await registerSurface(gitRoot, "foo");
+      expect(isSurfaceRegistered(gitRoot, "foo")).toBe(true);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("grandfathers a bare repo that exists on disk without a registry entry", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      await ensureSurfaceRepo(gitRoot, "legacy");
+      // No registry.json entry, but the repo exists → still registered.
+      expect(existsSync(registryPath(gitRoot))).toBe(false);
+      expect(isSurfaceRegistered(gitRoot, "legacy")).toBe(true);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("false for a name that fails the charset (never touches the filesystem)", () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      expect(isSurfaceRegistered(gitRoot, "../etc")).toBe(false);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("listSurfaces", () => {
+  test("returns entries sorted by name", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      await registerSurface(gitRoot, "zeta");
+      await registerSurface(gitRoot, "alpha");
+      await registerSurface(gitRoot, "mid");
+      expect(listSurfaces(gitRoot).map((s) => s.name)).toEqual(["alpha", "mid", "zeta"]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("excludes a grandfathered disk-only repo (registry entries only)", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      await registerSurface(gitRoot, "registered");
+      await ensureSurfaceRepo(gitRoot, "grandfathered"); // repo exists, no entry
+      // isSurfaceRegistered grandfathers it (pushable), but listSurfaces does not.
+      expect(isSurfaceRegistered(gitRoot, "grandfathered")).toBe(true);
+      expect(listSurfaces(gitRoot).map((s) => s.name)).toEqual(["registered"]);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("saveRegistry atomicity", () => {
+  test("registry.json is written pretty + reloadable", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      await registerSurface(gitRoot, "foo");
+      const raw = readFileSync(registryPath(gitRoot), "utf8");
+      expect(raw.endsWith("\n")).toBe(true);
+      expect(JSON.parse(raw).surfaces.foo.name).toBe("foo");
+    } finally {
+      cleanup();
+    }
+  });
+});

package/src/__tests__/git-transport.test.ts

@@ -3,6 +3,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { ensureSurfaceRepo, isSurfaceRegistered, registerSurface } from "../git-registry.ts";
 import {
   type GitTransportDeps,
   extractToken,
@@ -61,6 +62,11 @@ function deps(h: Harness, extra?: Partial<GitTransportDeps>): GitTransportDeps {
     db: h.db,
     gitRoot: h.gitRoot,
     knownIssuers: () => [ISSUER],
+    // Default: treat every name as declared + provision on demand (the Phase-0a
+    // "feel it" behavior). The declaration-gate tests below override `isDeclared`
+    // or use the real registry.
+    isDeclared: () => true,
+    ensureRepo: (name) => ensureSurfaceRepo(h.gitRoot, name),
     ...extra,
   };
 }
@@ -342,6 +348,176 @@ describe("handleGitTransport — auth gate", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Declaration gate (Phase 1) — provision/serve only a REGISTERED surface
+// ---------------------------------------------------------------------------
+
+describe("handleGitTransport — declaration gate", () => {
+  /** Deps wired to the REAL registry (isSurfaceRegistered + ensureSurfaceRepo). */
+  function regDeps(h: Harness): GitTransportDeps {
+    return deps(h, {
+      isDeclared: (name) => isSurfaceRegistered(h.gitRoot, name),
+      ensureRepo: (name) => ensureSurfaceRepo(h.gitRoot, name),
+    });
+  }
+
+  test("404 for an authed write to an UNdeclared surface (no auto-provision)", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["surface:foo:write"]);
+      const res = await handleGitTransport(
+        gitReq("/git/foo/info/refs?service=git-receive-pack", {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+        regDeps(h),
+      );
+      // A valid write token for an undeclared name is NOT enough — the registry
+      // gate 404s (indistinguishable from a bad path) and nothing is provisioned.
+      expect(res.status).toBe(404);
+      expect(existsSync(join(h.gitRoot, "foo.git"))).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("a declared (registered) surface serves the push advertisement", async () => {
+    const h = await makeHarness();
+    try {
+      // Lifecycle: surface-host registers the discovered `#surface` first.
+      await registerSurface(h.gitRoot, "foo");
+      expect(existsSync(join(h.gitRoot, "foo.git"))).toBe(true);
+      const token = await mint(h, ["surface:foo:write"]);
+      const res = await handleGitTransport(
+        gitReq("/git/foo/info/refs?service=git-receive-pack", {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+        regDeps(h),
+      );
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toContain("git-receive-pack-advertisement");
+      await res.text();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("grandfathering: an already-provisioned bare repo counts as declared", async () => {
+    const h = await makeHarness();
+    try {
+      // A Phase-0a repo that exists on disk but has no registry.json entry.
+      await ensureSurfaceRepo(h.gitRoot, "legacy");
+      expect(isSurfaceRegistered(h.gitRoot, "legacy")).toBe(true);
+      const token = await mint(h, ["surface:legacy:read"]);
+      const res = await handleGitTransport(
+        gitReq("/git/legacy/info/refs?service=git-upload-pack", {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+        regDeps(h),
+      );
+      expect(res.status).toBe(200);
+      await res.text();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("gate runs AFTER auth: no token on an undeclared name still 401 (not 404)", async () => {
+    const h = await makeHarness();
+    try {
+      const res = await handleGitTransport(
+        gitReq("/git/foo/info/refs?service=git-upload-pack"),
+        regDeps(h),
+      );
+      // 401 (not 404) — an unauthenticated probe never learns registry membership.
+      expect(res.status).toBe(401);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("gate runs AFTER scope: wrong-surface token on an undeclared name is 403 (not 404)", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["surface:other:write"]);
+      const res = await handleGitTransport(
+        gitReq("/git/foo/info/refs?service=git-receive-pack", {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+        regDeps(h),
+      );
+      // 403 (scope) before 404 (registry) — a valid-but-wrong token never learns
+      // membership either.
+      expect(res.status).toBe(403);
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Direct transfer POST (no prior info/refs GET) — auth enforced at BOTH points
+// ---------------------------------------------------------------------------
+
+describe("handleGitTransport — direct transfer POST", () => {
+  test("401 on a direct POST to git-receive-pack with no credential", async () => {
+    const h = await makeHarness();
+    try {
+      const res = await handleGitTransport(
+        gitReq("/git/foo/git-receive-pack", {
+          method: "POST",
+          headers: { "content-type": "application/x-git-receive-pack-request" },
+        }),
+        deps(h),
+      );
+      // A client that skips the info/refs GET is still gated at the POST.
+      expect(res.status).toBe(401);
+      expect(res.headers.get("www-authenticate") ?? "").toContain("Bearer");
+      expect(existsSync(join(h.gitRoot, "foo.git"))).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("403 on a direct POST to git-receive-pack with only read scope", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["surface:foo:read"]);
+      const res = await handleGitTransport(
+        gitReq("/git/foo/git-receive-pack", {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${token}`,
+            "content-type": "application/x-git-receive-pack-request",
+          },
+        }),
+        deps(h),
+      );
+      // receive-pack requires write; a read token is refused at the POST itself.
+      expect(res.status).toBe(403);
+      expect(existsSync(join(h.gitRoot, "foo.git"))).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("401 on a direct POST to git-upload-pack with no credential", async () => {
+    const h = await makeHarness();
+    try {
+      const res = await handleGitTransport(
+        gitReq("/git/foo/git-upload-pack", {
+          method: "POST",
+          headers: { "content-type": "application/x-git-upload-pack-request" },
+        }),
+        deps(h),
+      );
+      expect(res.status).toBe(401);
+      expect(res.headers.get("www-authenticate") ?? "").toContain("Bearer");
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Dispatch wiring through hubFetch
 // ---------------------------------------------------------------------------
@@ -425,6 +601,8 @@ describe("git push round-trip", () => {
           db: h.db,
           gitRoot: h.gitRoot,
           knownIssuers: () => [ISSUER],
+          isDeclared: (name) => isSurfaceRegistered(h.gitRoot, name),
+          ensureRepo: (name) => ensureSurfaceRepo(h.gitRoot, name),
           onPushed: (name) => {
             pushedNames.push(name);
             resolvePushed(name);
@@ -434,6 +612,9 @@ describe("git push round-trip", () => {
     const work = mkdtempSync(join(tmpdir(), "phub-git-work-"));
     try {
       const token = await mint(h, ["surface:foo:write"]);
+      // Declare the surface first (the Phase-1 lifecycle: surface-host registers
+      // a discovered `#surface` note before the push) — provisions the bare repo.
+      await registerSurface(h.gitRoot, "foo");
       const base = `http://127.0.0.1:${server.port}`;
 
       // Author a commit in a throwaway working repo.

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

@@ -202,6 +202,19 @@ describe("connectionKey / grantId derivation (idempotency)", () => {
     expect(k1).toBe("service:github");
   });
 
+  test("surface key includes the access verb", () => {
+    expect(connectionKey({ kind: "surface", target: "gitcoin-brain", access: "write" })).toBe(
+      "surface:gitcoin-brain:write",
+    );
+    expect(connectionKey({ kind: "surface", target: "gitcoin-brain", access: "read" })).toBe(
+      "surface:gitcoin-brain:read",
+    );
+    // access defaults to read (matches the vault default); target lowercased for the slug
+    expect(connectionKey({ kind: "surface", target: "Gitcoin-Brain" })).toBe(
+      "surface:gitcoin-brain:read",
+    );
+  });
+
   test("mcp key is the url target", () => {
     expect(connectionKey({ kind: "mcp", target: "https://x.test/mcp" })).toBe(
       "mcp:https://x.test/mcp",

package/src/__tests__/scope-explanations.test.ts

@@ -93,6 +93,22 @@ describe("explainScope", () => {
     expect(explainScope("vault:my-techne_2:admin")?.level).toBe("admin");
     expect(explainScope("vault:*:admin")?.level).toBe("admin");
   });
+
+  // Surface Git Transport Phase 1: named per-surface scopes
+  // (`surface:<name>:<verb>`) reach the consent screen via the 3→2-segment
+  // collapse, so explainScope MUST resolve them to the unnamed surface:read /
+  // surface:write labels — else the operator sees the raw scope string.
+  test("named surface scopes (surface:<name>:<verb>) reuse the unnamed-verb explanation", () => {
+    expect(explainScope("surface:gitcoin-brain:read")?.label).toBe(
+      SCOPE_EXPLANATIONS["surface:read"]?.label,
+    );
+    expect(explainScope("surface:gitcoin-brain:read")?.level).toBe("read");
+    expect(explainScope("surface:my-app_2:write")?.label).toBe(
+      SCOPE_EXPLANATIONS["surface:write"]?.label,
+    );
+    expect(explainScope("surface:my-app_2:write")?.level).toBe("write");
+    expect(explainScope("surface:*:write")?.level).toBe("write");
+  });
 });
 
 describe("scopeIsAdmin", () => {