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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.5-rc.2",
+  "version": "0.7.5-rc.3",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/admin-surfaces.test.ts

@@ -0,0 +1,207 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { routeAdminSurfaces } from "../admin-surfaces.ts";
+import { isSurfaceRegistered, repoDirFor } from "../git-registry.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { signAccessToken } from "../jwt-sign.ts";
+import { rotateSigningKey } from "../signing-keys.ts";
+import { createUser } from "../users.ts";
+
+const ISSUER = "http://127.0.0.1:1939";
+
+interface Harness {
+  gitRoot: string;
+  db: ReturnType<typeof openHubDb>;
+  userId: string;
+  cleanup: () => void;
+}
+
+async function makeHarness(): Promise<Harness> {
+  const dir = mkdtempSync(join(tmpdir(), "phub-adminsurf-"));
+  const db = openHubDb(hubDbPath(dir));
+  rotateSigningKey(db);
+  const u = await createUser(db, "owner", "pw");
+  return {
+    gitRoot: join(dir, "git"),
+    db,
+    userId: u.id,
+    cleanup: () => {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+async function mint(h: Harness, scopes: string[]): Promise<string> {
+  const { token } = await signAccessToken(h.db, {
+    sub: h.userId,
+    scopes,
+    audience: "operator",
+    clientId: "test-operator",
+    issuer: ISSUER,
+  });
+  return token;
+}
+
+function deps(h: Harness) {
+  return { db: h.db, gitRoot: h.gitRoot, issuer: ISSUER, knownIssuers: [ISSUER] };
+}
+
+function req(method: string, headers?: Record<string, string>, body?: unknown): Request {
+  return new Request("http://127.0.0.1/admin/surfaces", {
+    method,
+    headers,
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  });
+}
+
+describe("routeAdminSurfaces — routing", () => {
+  test("returns null for a non-/admin/surfaces path", async () => {
+    const h = await makeHarness();
+    try {
+      const res = await routeAdminSurfaces(new Request("http://127.0.0.1/admin/other"), deps(h));
+      expect(res).toBeNull();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("405 on an unsupported method", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["parachute:host:admin"]);
+      const res = await routeAdminSurfaces(
+        req("DELETE", { authorization: `Bearer ${token}` }),
+        deps(h),
+      );
+      expect(res?.status).toBe(405);
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("routeAdminSurfaces — auth", () => {
+  test("401 without a bearer", async () => {
+    const h = await makeHarness();
+    try {
+      const res = await routeAdminSurfaces(req("POST", {}, { name: "foo" }), deps(h));
+      expect(res?.status).toBe(401);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("403 when the token lacks parachute:host:admin", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["surface:foo:write"]);
+      const res = await routeAdminSurfaces(
+        req("POST", { authorization: `Bearer ${token}` }, { name: "foo" }),
+        deps(h),
+      );
+      expect(res?.status).toBe(403);
+      // No provisioning happened on a rejected auth.
+      expect(existsSync(repoDirFor(h.gitRoot, "foo"))).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("401 on a garbage token", async () => {
+    const h = await makeHarness();
+    try {
+      const res = await routeAdminSurfaces(
+        req("POST", { authorization: "Bearer not-a-jwt" }, { name: "foo" }),
+        deps(h),
+      );
+      expect(res?.status).toBe(401);
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("routeAdminSurfaces — register + list", () => {
+  test("POST registers a surface (provisions the repo + returns the entry)", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["parachute:host:admin"]);
+      const res = await routeAdminSurfaces(
+        req(
+          "POST",
+          { authorization: `Bearer ${token}`, "content-type": "application/json" },
+          { name: "brain", mount: "/surface/brain", mode: "prod" },
+        ),
+        deps(h),
+      );
+      expect(res?.status).toBe(200);
+      const body = (await res?.json()) as {
+        ok: boolean;
+        surface: { name: string; mount?: string };
+      };
+      expect(body.ok).toBe(true);
+      expect(body.surface.name).toBe("brain");
+      expect(body.surface.mount).toBe("/surface/brain");
+      expect(isSurfaceRegistered(h.gitRoot, "brain")).toBe(true);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("POST with a missing name → 400", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["parachute:host:admin"]);
+      const res = await routeAdminSurfaces(
+        req("POST", { authorization: `Bearer ${token}` }, { mount: "/surface/x" }),
+        deps(h),
+      );
+      expect(res?.status).toBe(400);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("POST with an invalid name → 400 (no repo provisioned)", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["parachute:host:admin"]);
+      const res = await routeAdminSurfaces(
+        req("POST", { authorization: `Bearer ${token}` }, { name: "a/b" }),
+        deps(h),
+      );
+      expect(res?.status).toBe(400);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("GET lists registered surfaces", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["parachute:host:admin"]);
+      await routeAdminSurfaces(
+        req("POST", { authorization: `Bearer ${token}` }, { name: "alpha" }),
+        deps(h),
+      );
+      await routeAdminSurfaces(
+        req("POST", { authorization: `Bearer ${token}` }, { name: "zeta" }),
+        deps(h),
+      );
+      const res = await routeAdminSurfaces(
+        new Request("http://127.0.0.1/admin/surfaces", {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+        deps(h),
+      );
+      expect(res?.status).toBe(200);
+      const body = (await res?.json()) as { surfaces: Array<{ name: string }> };
+      expect(body.surfaces.map((s) => s.name)).toEqual(["alpha", "zeta"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+});

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__/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", () => {

package/src/admin-surfaces.ts

@@ -0,0 +1,158 @@
+/**
+ * `/admin/surfaces` — the surface → bare-repo registry endpoint (Surface Git
+ * Transport Phase 1, design doc 2026-06-30-surface-git-transport.md §9/§10).
+ *
+ * This is the seam by which "vault declares" reaches the hub substrate. The
+ * vault holds the `#surface` note; surface-host discovers it (it custodies a
+ * vault read cred) and POSTs here to REGISTER the surface — which provisions its
+ * bare repo and records the name→repo mapping (git-registry.ts). The
+ * git-transport endpoint then serves/provisions ONLY registered names (§10 step
+ * 1). The hub never reads the vault itself — surface-host is the reader; this
+ * endpoint just records what it's told, gated on operator authority.
+ *
+ *   - `POST /admin/surfaces`  {name, mount?, mode?}  → register (idempotent)
+ *   - `GET  /admin/surfaces`                          → list registered surfaces
+ *
+ * Auth: a Bearer carrying `parachute:host:admin` — the operator token
+ * surface-host already reads for its DCR + redirect-self-heal calls. Same
+ * validation shape as `api-modules-ops.ts` (`validateHostAdminToken` against the
+ * multi-origin known-issuer set, then a scope check): the scope is
+ * operator-only/non-requestable, so the iss relaxation can't reach an OAuth
+ * token.
+ */
+import type { Database } from "bun:sqlite";
+import { type SurfaceRegistryEntry, listSurfaces, registerSurface } from "./git-registry.ts";
+import { validateHostAdminToken } from "./host-admin-token-validation.ts";
+
+/** Scope required to register/list surfaces — the operator token carries it. */
+export const ADMIN_SURFACES_REQUIRED_SCOPE = "parachute:host:admin";
+
+export interface AdminSurfacesLog {
+  warn: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+}
+
+export interface AdminSurfacesDeps {
+  db: Database;
+  /** Bare-repo root (`<CONFIG_DIR>/hub/git`). */
+  gitRoot: string;
+  /** Per-request hub issuer (`oauthDeps(req).issuer`). */
+  issuer: string;
+  /**
+   * The SET of origins the hub answers on (`oauthDeps(req).hubBoundOrigins()`),
+   * so an operator token minted under a prior origin keeps validating across an
+   * origin switch (hub#516 pattern).
+   */
+  knownIssuers?: readonly string[];
+  log?: AdminSurfacesLog;
+}
+
+function json(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+function jsonError(status: number, error: string, description: string): Response {
+  return json(status, { error, error_description: description });
+}
+
+/** Validate the operator bearer + require the surfaces scope. Mirrors api-modules-ops. */
+async function authorize(req: Request, deps: AdminSurfacesDeps): Promise<Response | undefined> {
+  const auth = req.headers.get("authorization");
+  if (!auth || !auth.startsWith("Bearer ")) {
+    return jsonError(401, "unauthenticated", "Authorization: Bearer <token> required");
+  }
+  const bearer = auth.slice("Bearer ".length).trim();
+  if (!bearer) return jsonError(401, "unauthenticated", "empty bearer token");
+  try {
+    const validated = await validateHostAdminToken(
+      deps.db,
+      bearer,
+      deps.knownIssuers ?? [deps.issuer],
+    );
+    if (typeof validated.payload.sub !== "string" || validated.payload.sub.length === 0) {
+      return jsonError(401, "unauthenticated", "bearer token has no sub claim");
+    }
+    const scopes =
+      typeof validated.payload.scope === "string"
+        ? validated.payload.scope.split(/\s+/).filter((s) => s.length > 0)
+        : [];
+    if (!scopes.includes(ADMIN_SURFACES_REQUIRED_SCOPE)) {
+      return jsonError(
+        403,
+        "insufficient_scope",
+        `bearer token lacks ${ADMIN_SURFACES_REQUIRED_SCOPE}`,
+      );
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return jsonError(401, "unauthenticated", `bearer token invalid — ${msg}`);
+  }
+  return undefined;
+}
+
+interface RegisterBody {
+  name?: unknown;
+  mount?: unknown;
+  mode?: unknown;
+}
+
+/**
+ * Route `/admin/surfaces`. Returns null when the path isn't ours (the caller
+ * falls through). GET lists; POST registers; other methods 405.
+ */
+export async function routeAdminSurfaces(
+  req: Request,
+  deps: AdminSurfacesDeps,
+): Promise<Response | null> {
+  const { pathname } = new URL(req.url);
+  if (pathname !== "/admin/surfaces") return null;
+  const log = deps.log ?? console;
+
+  if (req.method === "GET") {
+    const authFail = await authorize(req, deps);
+    if (authFail) return authFail;
+    return json(200, { surfaces: listSurfaces(deps.gitRoot) });
+  }
+
+  if (req.method === "POST") {
+    const authFail = await authorize(req, deps);
+    if (authFail) return authFail;
+
+    let body: RegisterBody;
+    try {
+      body = (await req.json()) as RegisterBody;
+    } catch {
+      return jsonError(400, "invalid_body", "request body must be JSON");
+    }
+    if (typeof body.name !== "string" || body.name.length === 0) {
+      return jsonError(400, "invalid_name", "`name` is required (non-empty string)");
+    }
+    if (body.mount !== undefined && typeof body.mount !== "string") {
+      return jsonError(400, "invalid_mount", "`mount`, when present, must be a string");
+    }
+    if (body.mode !== undefined && body.mode !== "dev" && body.mode !== "prod") {
+      return jsonError(400, "invalid_mode", '`mode`, when present, must be "dev" or "prod"');
+    }
+    let entry: SurfaceRegistryEntry;
+    try {
+      entry = await registerSurface(deps.gitRoot, body.name, {
+        ...(typeof body.mount === "string" ? { mount: body.mount } : {}),
+        ...(body.mode === "dev" || body.mode === "prod" ? { mode: body.mode } : {}),
+        log,
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      // A bad name is the caller's fault (400); a provisioning failure is ours (500).
+      if (/invalid surface name/.test(msg)) return jsonError(400, "invalid_name", msg);
+      log.warn(`[admin-surfaces] register failed for "${String(body.name)}": ${msg}`);
+      return jsonError(500, "register_failed", "could not provision the surface repo");
+    }
+    log.info(`[admin-surfaces] registered surface "${entry.name}"`);
+    return json(200, { ok: true, surface: entry });
+  }
+
+  return jsonError(405, "method_not_allowed", "use GET or POST on /admin/surfaces");
+}

package/src/git-registry.ts

@@ -0,0 +1,234 @@
+/**
+ * Surface → bare-repo registry for the Surface Git Transport (Phase 1, design
+ * doc 2026-06-30-surface-git-transport.md §9 + §10, "Decisions locked" #3).
+ *
+ * This is the hub-side half of "vault declares, hub authenticates, surface-host
+ * serves." The vault holds the `#surface` declaration; surface-host discovers it
+ * (it custodies a vault read cred) and REGISTERS the surface with the hub over
+ * `POST /admin/surfaces` (operator-authed). This module owns the resulting
+ * mapping:
+ *
+ *   - the persisted `name → bare-repo` registry (`<gitRoot>/registry.json`), and
+ *   - the async bare-repo provisioning (`ensureSurfaceRepo`).
+ *
+ * The registry is what TIES provisioning to a declared surface (§10 step 1): the
+ * git-transport endpoint only serves — and only ever provisions a repo for — a
+ * name that is REGISTERED (`isSurfaceRegistered`), a scoping improvement over
+ * Phase 0a's provision-on-first-push-of-any-name. The scope gate
+ * (`surface:<name>:write`, operator-granted) still runs first; this is a second,
+ * declaration-level gate.
+ *
+ * Grandfathering: a name whose bare repo already exists on disk (a Phase 0a
+ * auto-provisioned repo) counts as registered even without a registry.json
+ * entry, so the tightening never orphans an already-provisioned surface.
+ *
+ * Substrate discipline (§4): this module NEVER reads the vault and NEVER builds
+ * or executes a pushed tree. It only records names + creates empty bare repos.
+ * The vault read + the sandboxed build live in surface-host.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Logger seam — defaults to `console`. */
+export interface GitRegistryLog {
+  warn: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+}
+
+/**
+ * Surface-name charset — the single source of truth shared with the
+ * git-transport URL parser (imported there). Kebab/alnum only, NO slashes or
+ * dots, so a parsed name can never escape `gitRoot` via path traversal. Bounded
+ * length keeps a hostile name from ballooning a path.
+ */
+export const SURFACE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+
+/** One registered surface's metadata (the declaration pointer, not the artifact). */
+export interface SurfaceRegistryEntry {
+  /** Canonical surface name (== the `/git/<name>` + `/surface/<name>` segment). */
+  name: string;
+  /** Declared mount path (from the `#surface` note), informational. */
+  mount?: string;
+  /** Declared mode (from the `#surface` note), informational. */
+  mode?: "dev" | "prod";
+  /** ISO timestamp the surface was first registered. Preserved across re-registers. */
+  registeredAt: string;
+  /** ISO timestamp the bare repo was (first) provisioned. */
+  provisionedAt: string;
+}
+
+/** The persisted registry shape (`<gitRoot>/registry.json`). */
+export interface SurfaceRegistry {
+  version: 1;
+  surfaces: Record<string, SurfaceRegistryEntry>;
+}
+
+const EMPTY_REGISTRY: SurfaceRegistry = { version: 1, surfaces: {} };
+
+/** `<gitRoot>/registry.json`. */
+export function registryPath(gitRoot: string): string {
+  return join(gitRoot, "registry.json");
+}
+
+/** `<gitRoot>/<name>.git`. */
+export function repoDirFor(gitRoot: string, name: string): string {
+  return join(gitRoot, `${name}.git`);
+}
+
+/**
+ * Read + parse the registry. A missing or corrupt file yields an empty registry
+ * (the transport still fails closed on unregistered names — see
+ * `isSurfaceRegistered`), never a throw: a torn registry.json must not take the
+ * git endpoint down.
+ */
+export function loadRegistry(gitRoot: string): SurfaceRegistry {
+  const file = registryPath(gitRoot);
+  if (!existsSync(file)) return { version: 1, surfaces: {} };
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8")) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      return { ...EMPTY_REGISTRY };
+    const surfaces = (parsed as { surfaces?: unknown }).surfaces;
+    if (!surfaces || typeof surfaces !== "object" || Array.isArray(surfaces)) {
+      return { ...EMPTY_REGISTRY };
+    }
+    return { version: 1, surfaces: surfaces as Record<string, SurfaceRegistryEntry> };
+  } catch {
+    return { ...EMPTY_REGISTRY };
+  }
+}
+
+/**
+ * Persist the registry ATOMICALLY (stage 0600 → rename), so a crash mid-write
+ * leaves the prior registry intact and no reader observes a partial file.
+ */
+export function saveRegistry(gitRoot: string, reg: SurfaceRegistry): void {
+  mkdirSync(gitRoot, { recursive: true });
+  const file = registryPath(gitRoot);
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${JSON.stringify(reg, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+/**
+ * Is `name` a registered surface? True when it has a registry.json entry OR its
+ * bare repo already exists on disk (grandfathering a Phase 0a auto-provisioned
+ * repo). This is the declaration gate the git-transport endpoint consults after
+ * the scope check passes.
+ */
+export function isSurfaceRegistered(gitRoot: string, name: string): boolean {
+  if (!SURFACE_NAME_RE.test(name)) return false;
+  if (loadRegistry(gitRoot).surfaces[name]) return true;
+  return existsSync(repoDirFor(gitRoot, name));
+}
+
+/**
+ * Every registered surface, sorted by name (for `GET /admin/surfaces`). NOTE:
+ * this lists only registry.json entries — a grandfathered disk-only bare repo (a
+ * Phase-0a auto-provisioned repo with no entry) is still *pushable*
+ * (`isSurfaceRegistered` grandfathers it) but does NOT appear here until
+ * surface-host's next discovery pass re-registers it and writes its entry.
+ */
+export function listSurfaces(gitRoot: string): SurfaceRegistryEntry[] {
+  const reg = loadRegistry(gitRoot);
+  return Object.values(reg.surfaces).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Ensure `<gitRoot>/<name>.git` exists as an exportable bare repo, provisioning
+ * it if absent. ASYNC (Phase 1 nit): uses `Bun.spawn` + `await`, never the
+ * event-loop-blocking `spawnSync` — a slow disk on `git init` no longer stalls
+ * the whole hub. Idempotent: an existing repo is returned untouched.
+ *
+ * `http.receivepack = true` is REQUIRED for push: `git http-backend` enables
+ * upload-pack from `GIT_HTTP_EXPORT_ALL` alone but refuses receive-pack unless
+ * the repo opts in explicitly.
+ */
+export async function ensureSurfaceRepo(
+  gitRoot: string,
+  name: string,
+  log: GitRegistryLog = console,
+): Promise<string> {
+  if (!SURFACE_NAME_RE.test(name)) {
+    throw new Error(`refusing to provision repo for invalid surface name "${name}"`);
+  }
+  const repoDir = repoDirFor(gitRoot, name);
+  if (existsSync(repoDir)) return repoDir;
+  mkdirSync(gitRoot, { recursive: true });
+
+  const init = await runGit(["init", "--bare", repoDir]);
+  if (init.code !== 0) {
+    throw new Error(`git init --bare failed: ${init.stderr || "unknown"}`);
+  }
+  const cfg = await runGit(["-C", repoDir, "config", "http.receivepack", "true"]);
+  if (cfg.code !== 0) {
+    throw new Error(`git config http.receivepack failed: ${cfg.stderr || "unknown"}`);
+  }
+  writePostReceiveHook(repoDir, name);
+  log.info(`[git-registry] provisioned bare repo for surface "${name}" at ${repoDir}`);
+  return repoDir;
+}
+
+/**
+ * Register (or re-register) a declared surface: validate the name, ensure its
+ * bare repo, and upsert the registry entry (preserving the original
+ * `registeredAt` on a re-register). Idempotent — surface-host calls this on
+ * every discovery pass.
+ */
+export async function registerSurface(
+  gitRoot: string,
+  name: string,
+  opts: { mount?: string; mode?: "dev" | "prod"; now?: () => Date; log?: GitRegistryLog } = {},
+): Promise<SurfaceRegistryEntry> {
+  const now = opts.now ?? (() => new Date());
+  if (!SURFACE_NAME_RE.test(name)) {
+    throw new Error(`invalid surface name "${name}" (must match ${SURFACE_NAME_RE})`);
+  }
+  await ensureSurfaceRepo(gitRoot, name, opts.log ?? console);
+
+  const reg = loadRegistry(gitRoot);
+  const prior = reg.surfaces[name];
+  const nowIso = now().toISOString();
+  const entry: SurfaceRegistryEntry = {
+    name,
+    ...(opts.mount !== undefined ? { mount: opts.mount } : {}),
+    ...(opts.mode !== undefined ? { mode: opts.mode } : {}),
+    registeredAt: prior?.registeredAt ?? nowIso,
+    provisionedAt: prior?.provisionedAt ?? nowIso,
+  };
+  reg.surfaces[name] = entry;
+  saveRegistry(gitRoot, reg);
+  return entry;
+}
+
+/**
+ * Phase-0a placeholder post-receive hook: logs the received refs (to stdout,
+ * relayed to the pusher as `remote:` lines, and appended to `post-receive.log`
+ * in the repo dir for verification). The real deploy hand-off is the hub's
+ * `onPushed` → HTTP + hub-JWT notify to surface-host (git-notify.ts) — this hook
+ * NEVER builds the pushed tree (that exec authority belongs to the module's
+ * sandbox, not the substrate — §5/§7).
+ */
+function writePostReceiveHook(repoDir: string, name: string): void {
+  const hook = `#!/bin/sh
+# Parachute Surface Git Transport — post-receive placeholder.
+# Logs received refs only. The deploy hand-off is the hub's onPushed → HTTP +
+# hub-JWT notify to surface-host; the pushed tree is NEVER built in this process
+# (that exec authority belongs to the module's sandbox, not the substrate).
+while read -r oldrev newrev refname; do
+  printf '[parachute] surface %s received %s (%s..%s)\\n' "${name}" "$refname" "$oldrev" "$newrev"
+  printf '%s %s %s\\n' "$oldrev" "$newrev" "$refname" >> post-receive.log
+done
+`;
+  const hookPath = join(repoDir, "hooks", "post-receive");
+  writeFileSync(hookPath, hook, { mode: 0o755 });
+}
+
+async function runGit(args: string[]): Promise<{ code: number; stderr: string }> {
+  const proc = Bun.spawn(["git", ...args], { stdout: "ignore", stderr: "pipe" });
+  const [code, stderr] = await Promise.all([
+    proc.exited,
+    new Response(proc.stderr as ReadableStream<Uint8Array>).text(),
+  ]);
+  return { code, stderr: stderr.trim() };
+}

package/src/git-transport.ts

@@ -11,10 +11,16 @@
  * versioned, authenticated, file-shaped content movement.
  *
  * What this layer does NOT do (by deliberate trust boundary, §7): it never
- * BUILDS or executes the pushed tree. The hub only receives + stores bytes;
- * the `post-receive` hook here is a Phase-0a placeholder that logs the refs.
- * Building pushed source is surface-host's sandboxed job (Phase 0b) — keeping
- * the RCE surface out of the substrate is the whole point of the split.
+ * BUILDS or executes the pushed tree. The hub only receives + stores bytes; the
+ * `post-receive` hook (written by git-registry.ts) is a placeholder that only
+ * logs the refs — the deploy hand-off is the hub's `onPushed` → HTTP + hub-JWT
+ * notify to surface-host. Building pushed source is surface-host's sandboxed job
+ * — keeping the RCE surface out of the substrate is the whole point of the split.
+ *
+ * Provisioning is gated on DECLARATION (Phase 1, §9/§10): the hub serves — and
+ * ever provisions a repo for — only a REGISTERED surface (`isDeclared`), never
+ * any arbitrary name a write token happens to name. surface-host discovers a
+ * `#surface` note and registers it via `POST /admin/surfaces` (git-registry.ts).
  *
  * The mechanism (grounded in git's smart-HTTP protocol):
  *   1. Discovery `GET /git/<name>/info/refs?service=git-(upload|receive)-pack`
@@ -35,9 +41,7 @@
  *      Never buffers whole packs.
  */
 import type { Database } from "bun:sqlite";
-import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { SURFACE_NAME_RE } from "./git-registry.ts";
 import { validateAccessToken } from "./jwt-sign.ts";
 
 /** Logger seam — defaults to `console`. */
@@ -50,11 +54,26 @@ export interface GitTransportDeps {
   /** Hub DB handle — for signature/kid lookup + revocation in `validateAccessToken`. */
   db: Database;
   /**
-   * Directory holding the bare repos. Each surface lives at
-   * `<gitRoot>/<name>.git`. Production: `<CONFIG_DIR>/hub/git`. Tests point
-   * this at a tmpdir.
+   * Directory holding the bare repos (`GIT_PROJECT_ROOT` for `http-backend`).
+   * Each surface lives at `<gitRoot>/<name>.git`. Production: `<CONFIG_DIR>/hub/git`.
+   * Tests point this at a tmpdir.
    */
   gitRoot: string;
+  /**
+   * The declaration gate: is `<name>` a REGISTERED surface? Consulted AFTER the
+   * scope check passes — so an unauthorized probe always gets 401/403 and never
+   * learns registry membership; only a caller already holding a valid
+   * `surface:<name>:*` token can distinguish registered (proceeds) from
+   * unregistered (404). Production wires this to `isSurfaceRegistered(gitRoot, …)`
+   * (git-registry.ts), which grandfathers already-provisioned bare repos.
+   */
+  isDeclared: (name: string) => boolean | Promise<boolean>;
+  /**
+   * Idempotently ensure the bare repo for a registered `<name>` exists, returning
+   * its path. Only ever called for a name that passed `isDeclared`. Production
+   * wires this to `ensureSurfaceRepo(gitRoot, …)` (async; the Phase-1 async nit).
+   */
+  ensureRepo: (name: string) => Promise<string>;
   /**
    * The SET of origins this hub legitimately answers on
    * (`buildHubBoundOrigins` — loopback ∪ expose-state ∪ platform ∪ per-request
@@ -88,14 +107,11 @@ export interface GitTransportDeps {
   log?: GitTransportLog;
 }
 
-/**
- * Surface-name charset. Kebab/alnum only — NO slashes or dots, so a parsed
- * name can never escape `gitRoot` via path traversal. A trailing `.git` on the
- * URL segment is stripped before this check (so `/git/foo.git/...` and
- * `/git/foo/...` both resolve to `foo`). Bounded length keeps a hostile name
- * from ballooning a path.
- */
-const SURFACE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+// Surface-name charset (`SURFACE_NAME_RE`, imported from git-registry.ts): the
+// shared kebab/alnum-only allowlist — NO slashes or dots, so a parsed name can
+// never escape `gitRoot` via path traversal. A trailing `.git` on the URL
+// segment is stripped before the check (so `/git/foo.git/...` and `/git/foo/...`
+// both resolve to `foo`).
 
 /** Which authority a request needs, keyed purely off the git service/path. */
 type Access = "read" | "write";
@@ -214,56 +230,6 @@ function forbidden(scope: string): Response {
   });
 }
 
-/**
- * Ensure `<gitRoot>/<name>.git` exists as an exportable bare repo, creating it
- * on first authenticated access (Phase 1 will add a real registry; this keeps
- * it simple now). Returns the repo dir. Only ever called AFTER the auth gate
- * passes, so unauthenticated probing can never provision a repo.
- *
- * `http.receivepack = true` is REQUIRED for push: `git http-backend` enables
- * upload-pack from `GIT_HTTP_EXPORT_ALL` alone but refuses receive-pack unless
- * the repo opts in explicitly.
- */
-function ensureBareRepo(gitRoot: string, name: string, log: GitTransportLog): string {
-  const repoDir = join(gitRoot, `${name}.git`);
-  if (existsSync(repoDir)) return repoDir;
-  mkdirSync(gitRoot, { recursive: true });
-  const init = spawnSync("git", ["init", "--bare", repoDir], { encoding: "utf8" });
-  if (init.status !== 0) {
-    throw new Error(`git init --bare failed: ${init.stderr || init.error?.message || "unknown"}`);
-  }
-  const cfg = spawnSync("git", ["-C", repoDir, "config", "http.receivepack", "true"], {
-    encoding: "utf8",
-  });
-  if (cfg.status !== 0) {
-    throw new Error(`git config http.receivepack failed: ${cfg.stderr || "unknown"}`);
-  }
-  writePostReceiveHook(repoDir, name);
-  log.info(`[git-transport] provisioned bare repo for surface "${name}" at ${repoDir}`);
-  return repoDir;
-}
-
-/**
- * Phase-0a placeholder hook: log the received refs (to stdout, relayed to the
- * pusher as `remote:` lines, and appended to `post-receive.log` in the repo
- * dir for verification). Phase 0b replaces the body with an HTTP + hub-JWT
- * notify to surface-host (NEVER a shell-out that builds the pushed tree — §5/§7).
- */
-function writePostReceiveHook(repoDir: string, name: string): void {
-  const hook = `#!/bin/sh
-# Parachute Surface Git Transport — Phase 0a placeholder.
-# Logs received refs only. Phase 0b: notify surface-host over HTTP + a hub JWT
-# (never build the pushed tree in this process — that exec authority belongs to
-# the module's sandbox, not the substrate).
-while read -r oldrev newrev refname; do
-  printf '[parachute] surface %s received %s (%s..%s)\\n' "${name}" "$refname" "$oldrev" "$newrev"
-  printf '%s %s %s\\n' "$oldrev" "$newrev" "$refname" >> post-receive.log
-done
-`;
-  const hookPath = join(repoDir, "hooks", "post-receive");
-  writeFileSync(hookPath, hook, { mode: 0o755 });
-}
-
 /**
  * The byte offset + separator length where CGI headers end (first blank line).
  * Handles both `\r\n\r\n` (4) and `\n\n` (2). Returns null if no boundary yet.
@@ -418,9 +384,30 @@ export async function handleGitTransport(req: Request, deps: GitTransportDeps):
       : scopes.includes(readScope) || scopes.includes(writeScope);
   if (!ok) return forbidden(access === "write" ? writeScope : readScope);
 
-  // --- Provision (first access) + proxy -------------------------------------
+  // --- Declaration gate (AFTER auth, so it never leaks registry membership) --
+  // The scope check above already proved the caller is authorized for this
+  // surface; only now do we consult the registry. An unregistered name 404s
+  // (indistinguishable from a malformed path — we don't reveal which names
+  // exist), which is the Phase-1 tightening: a repo is provisioned/served only
+  // for a DECLARED surface, never any arbitrary name a write token was minted
+  // for. Grandfathering (an already-provisioned bare repo counts as declared)
+  // lives in `isSurfaceRegistered`.
+  let declared: boolean;
+  try {
+    declared = await deps.isDeclared(name);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.warn(`[git-transport] declaration check failed for "${name}": ${msg}`);
+    return new Response("internal error: could not resolve surface registry\n", {
+      status: 500,
+      headers: { "content-type": "text/plain; charset=utf-8" },
+    });
+  }
+  if (!declared) return new Response("not found", { status: 404 });
+
+  // --- Ensure repo (idempotent, async) + proxy ------------------------------
   try {
-    ensureBareRepo(deps.gitRoot, name, log);
+    await deps.ensureRepo(name);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     log.warn(`[git-transport] repo provisioning failed for "${name}": ${msg}`);

package/src/hub-server.ts

@@ -187,6 +187,7 @@ import {
 } from "./admin-handlers.ts";
 import { handleHostAdminToken } from "./admin-host-admin-token.ts";
 import { handleModuleToken } from "./admin-module-token.ts";
+import { routeAdminSurfaces } from "./admin-surfaces.ts";
 import { handleVaultAdminToken } from "./admin-vault-admin-token.ts";
 import { handleCreateVault, handleDeleteVault } from "./admin-vaults.ts";
 import { handleApiAccount } from "./api-account-2fa.ts";
@@ -240,6 +241,7 @@ import { applyCorsHeaders, corsPreflightResponse, isCorsAllowedRoute } from "./c
 import { ensureCsrfToken } from "./csrf.ts";
 import { readExposeState } from "./expose-state.ts";
 import { notifySurfacePushed } from "./git-notify.ts";
+import { ensureSurfaceRepo, isSurfaceRegistered } from "./git-registry.ts";
 import { handleGitTransport } from "./git-transport.ts";
 import { HUB_DEFAULT_PORT, HUB_SVC, clearHubPort, writeHubPort } from "./hub-control.ts";
 import {
@@ -3792,6 +3794,29 @@ export function hubFetch(
         return new Response("not found", { status: 404 });
       }
 
+      // /admin/surfaces — the surface → bare-repo registry (Surface Git
+      // Transport Phase 1). surface-host discovers a `#surface` note (it reads
+      // the vault) and POSTs here to register it → the hub provisions the bare
+      // repo + records name→repo, which the /git/ endpoint then gates
+      // provisioning on. Operator-authed (parachute:host:admin — the operator
+      // token surface-host already reads). Placed BEFORE the /admin/* SPA
+      // fallback so its POST/GET aren't swallowed by the GET-only shell.
+      if (pathname === "/admin/surfaces") {
+        if (!getDb) return dbNotConfigured();
+        const od = oauthDeps(req);
+        const handled = await routeAdminSurfaces(req, {
+          db: getDb(),
+          gitRoot,
+          issuer: od.issuer,
+          knownIssuers: od.hubBoundOrigins(),
+        });
+        // routeAdminSurfaces returns null ONLY for a non-matching path, which
+        // can't happen inside this exact-match branch — so `handled` is always a
+        // Response here. The guard is a belt: a null would harmlessly fall to the
+        // /admin/* SPA below (which 405s a non-GET).
+        if (handled) return handled;
+      }
+
       // /admin/* SPA mount. All non-SPA admin handlers (host-admin-token,
       // vault-admin-token, login, logout, config, api/auth/*, api/grants,
       // grants/*) ran above and either matched or returned. Anything that
@@ -3827,6 +3852,12 @@ export function hubFetch(
           gitRoot,
           knownIssuers: () => oauthDeps(req).hubBoundOrigins(),
           peerAddr,
+          // Declaration gate (Phase 1): serve/provision ONLY a registered
+          // surface (grandfathering already-provisioned bare repos), never any
+          // arbitrary name a write token happens to carry. surface-host
+          // registers a discovered `#surface` note via /admin/surfaces.
+          isDeclared: (name) => isSurfaceRegistered(gitRoot, name),
+          ensureRepo: (name) => ensureSurfaceRepo(gitRoot, name),
           // Deploy hand-off (Phase 0b §5 step 5): on a successful push, notify
           // the surface module over HTTP + a hub JWT so it pulls + builds +
           // serves. NEVER a shell-out that builds the pushed tree — the hub

package/src/scope-explanations.ts

@@ -342,6 +342,18 @@ export function isRequestableScope(scope: string): boolean {
  */
 const VAULT_VERB_RE = /^vault:[a-zA-Z0-9_*-]+:(read|write|admin)$/;
 
+/**
+ * Named per-surface scopes (`surface:<name>:<verb>` for verb ∈ {read, write}) —
+ * the Surface Git Transport grant shape (Decisions-locked #2: read = clone,
+ * write = push). The 3→2-segment collapse means the hub validates every
+ * `surface:<name>:<verb>` off the declared unnamed `surface:read`/`surface:write`,
+ * so the consent screen must render the named form with the SAME operator-facing
+ * label — else `surface:gitcoin-brain:write` shows raw. Parallel to
+ * `VAULT_VERB_RE`. (No named `admin` form: surface admin is the unnamed,
+ * module-level `surface:admin`.)
+ */
+const SURFACE_VERB_RE = /^surface:[a-zA-Z0-9_*-]+:(read|write)$/;
+
 export function explainScope(scope: string): ScopeExplanation | null {
   const direct = SCOPE_EXPLANATIONS[scope];
   if (direct) return direct;
@@ -349,6 +361,10 @@ export function explainScope(scope: string): ScopeExplanation | null {
     const verb = scope.split(":")[2] as "read" | "write" | "admin";
     return SCOPE_EXPLANATIONS[`vault:${verb}`] ?? null;
   }
+  if (SURFACE_VERB_RE.test(scope)) {
+    const verb = scope.split(":")[2] as "read" | "write";
+    return SCOPE_EXPLANATIONS[`surface:${verb}`] ?? null;
+  }
   return null;
 }