@openparachute/hub 0.7.4 → 0.7.5-rc.1

package/package.json

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

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

@@ -0,0 +1,450 @@
+import { describe, expect, test } from "bun:test";
+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 {
+  type GitTransportDeps,
+  extractToken,
+  findHeaderEnd,
+  handleGitTransport,
+  parseCgiHeaders,
+  parseGitPath,
+  requiredAccess,
+} from "../git-transport.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { hubFetch } from "../hub-server.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 {
+  dir: string;
+  gitRoot: string;
+  db: ReturnType<typeof openHubDb>;
+  userId: string;
+  cleanup: () => void;
+}
+
+async function makeHarness(): Promise<Harness> {
+  const dir = mkdtempSync(join(tmpdir(), "phub-git-"));
+  const db = openHubDb(hubDbPath(dir));
+  rotateSigningKey(db);
+  const u = await createUser(db, "owner", "pw");
+  return {
+    dir,
+    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: "surface",
+    clientId: "test-client",
+    issuer: ISSUER,
+  });
+  return token;
+}
+
+function deps(h: Harness, extra?: Partial<GitTransportDeps>): GitTransportDeps {
+  return {
+    db: h.db,
+    gitRoot: h.gitRoot,
+    knownIssuers: () => [ISSUER],
+    ...extra,
+  };
+}
+
+function gitReq(path: string, init?: RequestInit): Request {
+  return new Request(`http://127.0.0.1${path}`, init);
+}
+
+// ---------------------------------------------------------------------------
+// Pure parsers
+// ---------------------------------------------------------------------------
+
+describe("parseGitPath", () => {
+  test("parses name + subpath", () => {
+    expect(parseGitPath("/git/gitcoin-brain/info/refs")).toEqual({
+      name: "gitcoin-brain",
+      gitSubpath: "info/refs",
+    });
+  });
+  test("strips a trailing .git on the name segment", () => {
+    expect(parseGitPath("/git/foo.git/git-receive-pack")).toEqual({
+      name: "foo",
+      gitSubpath: "git-receive-pack",
+    });
+  });
+  test("rejects non-/git paths", () => {
+    expect(parseGitPath("/surface/foo")).toBeNull();
+  });
+  test("rejects a bare /git/<name> with no subpath", () => {
+    expect(parseGitPath("/git/foo")).toBeNull();
+    expect(parseGitPath("/git/foo/")).toBeNull();
+  });
+  test("rejects path traversal in the name", () => {
+    expect(parseGitPath("/git/../etc/info/refs")).toBeNull();
+    expect(parseGitPath("/git/.../info/refs")).toBeNull();
+  });
+  test("rejects traversal in the subpath", () => {
+    expect(parseGitPath("/git/foo/../../etc/passwd")).toBeNull();
+  });
+  test("rejects slashes / illegal chars in the name", () => {
+    expect(parseGitPath("/git/a@b/info/refs")).toBeNull();
+  });
+});
+
+describe("requiredAccess", () => {
+  test("receive-pack is write", () => {
+    expect(requiredAccess("git-receive-pack", null)).toBe("write");
+    expect(requiredAccess("info/refs", "git-receive-pack")).toBe("write");
+  });
+  test("upload-pack is read", () => {
+    expect(requiredAccess("git-upload-pack", null)).toBe("read");
+    expect(requiredAccess("info/refs", "git-upload-pack")).toBe("read");
+  });
+  test("dumb / unknown paths default to read", () => {
+    expect(requiredAccess("info/refs", null)).toBe("read");
+    expect(requiredAccess("HEAD", null)).toBe("read");
+    expect(requiredAccess("objects/info/packs", null)).toBe("read");
+  });
+});
+
+describe("extractToken", () => {
+  test("Bearer", () => {
+    const r = gitReq("/git/foo/info/refs", { headers: { authorization: "Bearer abc.def.ghi" } });
+    expect(extractToken(r)).toBe("abc.def.ghi");
+  });
+  test("Basic x-access-token:<jwt>", () => {
+    const b64 = Buffer.from("x-access-token:my.jwt.tok").toString("base64");
+    const r = gitReq("/git/foo/info/refs", { headers: { authorization: `Basic ${b64}` } });
+    expect(extractToken(r)).toBe("my.jwt.tok");
+  });
+  test("Basic <jwt>:x-oauth-basic (legacy, token in username)", () => {
+    const b64 = Buffer.from("my.jwt.tok:x-oauth-basic").toString("base64");
+    const r = gitReq("/git/foo/info/refs", { headers: { authorization: `Basic ${b64}` } });
+    expect(extractToken(r)).toBe("my.jwt.tok");
+  });
+  test("no header → null", () => {
+    expect(extractToken(gitReq("/git/foo/info/refs"))).toBeNull();
+  });
+});
+
+describe("parseCgiHeaders", () => {
+  test("default 200 when no Status line", () => {
+    const { status, headers } = parseCgiHeaders(
+      "Content-Type: application/x-git-upload-pack-advertisement",
+    );
+    expect(status).toBe(200);
+    expect(headers.get("content-type")).toBe("application/x-git-upload-pack-advertisement");
+  });
+  test("honors a Status line", () => {
+    const { status } = parseCgiHeaders("Status: 404 Not Found\r\nContent-Type: text/plain");
+    expect(status).toBe(404);
+  });
+});
+
+describe("findHeaderEnd", () => {
+  const enc = new TextEncoder();
+  test("finds CRLFCRLF", () => {
+    const buf = enc.encode("A: b\r\nC: d\r\n\r\nBODY");
+    const r = findHeaderEnd(buf);
+    expect(r?.sepLen).toBe(4);
+    expect(new TextDecoder().decode(buf.slice(0, r?.idx))).toBe("A: b\r\nC: d");
+  });
+  test("finds LFLF", () => {
+    const buf = enc.encode("A: b\n\nBODY");
+    const r = findHeaderEnd(buf);
+    expect(r?.sepLen).toBe(2);
+  });
+  test("returns null without a boundary", () => {
+    expect(findHeaderEnd(enc.encode("A: b\r\n"))).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Auth gate (handler-direct — no real server needed)
+// ---------------------------------------------------------------------------
+
+describe("handleGitTransport — auth gate", () => {
+  test("401 + WWW-Authenticate: Bearer when no credential", async () => {
+    const h = await makeHarness();
+    try {
+      const res = await handleGitTransport(
+        gitReq("/git/foo/info/refs?service=git-receive-pack"),
+        deps(h),
+      );
+      expect(res.status).toBe(401);
+      expect(res.headers.get("www-authenticate") ?? "").toContain("Bearer");
+      // Nothing provisioned on an unauthenticated probe.
+      expect(existsSync(join(h.gitRoot, "foo.git"))).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("401 on an invalid/garbage token", async () => {
+    const h = await makeHarness();
+    try {
+      const res = await handleGitTransport(
+        gitReq("/git/foo/info/refs?service=git-receive-pack", {
+          headers: { authorization: "Bearer not-a-jwt" },
+        }),
+        deps(h),
+      );
+      expect(res.status).toBe(401);
+      expect(res.headers.get("www-authenticate") ?? "").toContain("Bearer");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("403 when a valid token lacks surface:<name>:write (push)", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["surface:foo:read", "vault:default:read"]);
+      const res = await handleGitTransport(
+        gitReq("/git/foo/info/refs?service=git-receive-pack", {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+        deps(h),
+      );
+      expect(res.status).toBe(403);
+      // A read-only credential never provisions a write repo on a push attempt.
+      expect(existsSync(join(h.gitRoot, "foo.git"))).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("403 on a read (upload-pack) with neither read nor write scope", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["surface:other:read"]);
+      const res = await handleGitTransport(
+        gitReq("/git/foo/info/refs?service=git-upload-pack", {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+        deps(h),
+      );
+      expect(res.status).toBe(403);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("a write token authorizes a push info/refs (advertisement, 200)", 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}` },
+        }),
+        deps(h),
+      );
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toContain("git-receive-pack-advertisement");
+      // First authenticated access provisions the bare repo.
+      expect(existsSync(join(h.gitRoot, "foo.git"))).toBe(true);
+      const body = await res.text();
+      expect(body).toContain("git-receive-pack");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("a read token authorizes a fetch info/refs (upload-pack, 200)", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["surface:foo:read"]);
+      const res = await handleGitTransport(
+        gitReq("/git/foo/info/refs?service=git-upload-pack", {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+        deps(h),
+      );
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toContain("git-upload-pack-advertisement");
+      // Drain the body so the http-backend service finishes before teardown
+      // (else cleanup's rmSync can race the still-running `git upload-pack`).
+      await res.text();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("write ⊇ read: a write token may also fetch", 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-upload-pack", {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+        deps(h),
+      );
+      expect(res.status).toBe(200);
+      await res.text();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("Basic x-access-token:<jwt> is accepted (older-git compat)", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["surface:foo:write"]);
+      const b64 = Buffer.from(`x-access-token:${token}`).toString("base64");
+      const res = await handleGitTransport(
+        gitReq("/git/foo/info/refs?service=git-receive-pack", {
+          headers: { authorization: `Basic ${b64}` },
+        }),
+        deps(h),
+      );
+      expect(res.status).toBe(200);
+      await res.text();
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Dispatch wiring through hubFetch
+// ---------------------------------------------------------------------------
+
+describe("hubFetch /git dispatch", () => {
+  test("routes /git/* to the transport (401 unauth, with WWW-Authenticate)", async () => {
+    const h = await makeHarness();
+    try {
+      const handler = hubFetch(h.dir, {
+        getDb: () => h.db,
+        gitRoot: h.gitRoot,
+        issuer: ISSUER,
+        loopbackPort: 1939,
+      });
+      const res = await handler(gitReq("/git/foo/info/refs?service=git-upload-pack"));
+      expect(res.status).toBe(401);
+      expect(res.headers.get("www-authenticate") ?? "").toContain("Bearer");
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Real git push round-trip through a live server
+// ---------------------------------------------------------------------------
+
+function git(
+  args: string[],
+  cwd: string,
+  env?: Record<string, string>,
+): { code: number; out: string; err: string } {
+  const r = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0", ...env },
+  });
+  return { code: r.status ?? -1, out: r.stdout ?? "", err: r.stderr ?? "" };
+}
+
+/**
+ * Async git — for any client op that talks to the in-process `Bun.serve`. The
+ * synchronous `spawnSync` would BLOCK Bun's single event loop, starving the
+ * server that's meant to answer this very request → deadlock. The async spawn
+ * keeps the loop free so the server can respond. (Setup ops above use the sync
+ * helper because they never touch the server.)
+ */
+async function gitAsync(
+  args: string[],
+  cwd: string,
+  env?: Record<string, string>,
+): Promise<{ code: number; err: string }> {
+  const proc = Bun.spawn(["git", ...args], {
+    cwd,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0", ...env },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [code, err] = await Promise.all([
+    proc.exited,
+    new Response(proc.stderr as ReadableStream<Uint8Array>).text(),
+  ]);
+  return { code, err };
+}
+
+describe("git push round-trip", () => {
+  test("an authed push lands the ref in the bare repo + fires post-receive", async () => {
+    const h = await makeHarness();
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: hubFetch(h.dir, {
+        getDb: () => h.db,
+        gitRoot: h.gitRoot,
+        issuer: ISSUER,
+        loopbackPort: 1939,
+      }),
+    });
+    const work = mkdtempSync(join(tmpdir(), "phub-git-work-"));
+    try {
+      const token = await mint(h, ["surface:foo:write"]);
+      const base = `http://127.0.0.1:${server.port}`;
+
+      // Author a commit in a throwaway working repo.
+      expect(git(["init", "-q", "-b", "main", work], tmpdir()).code).toBe(0);
+      git(["config", "user.email", "test@parachute.computer"], work);
+      git(["config", "user.name", "Test"], work);
+      Bun.write(join(work, "index.html"), "<h1>surface</h1>\n");
+      expect(git(["add", "-A"], work).code).toBe(0);
+      expect(git(["commit", "-q", "-m", "first"], work).code).toBe(0);
+      const localRev = git(["rev-parse", "HEAD"], work).out.trim();
+
+      // Push through the hub-authenticated endpoint (token via extraHeader, so
+      // the request carries Authorization up-front — exercises info/refs +
+      // receive-pack transfer end-to-end). Async spawn (see gitAsync) so the
+      // in-process server can answer.
+      const push = await gitAsync(
+        [
+          "-c",
+          `http.extraHeader=Authorization: Bearer ${token}`,
+          "push",
+          `${base}/git/foo`,
+          "main",
+        ],
+        work,
+      );
+      expect(push.code).toBe(0);
+
+      // The ref landed in the hub-side bare repo at the pushed sha.
+      const bare = join(h.gitRoot, "foo.git");
+      const serverRev = git(
+        ["--git-dir", bare, "rev-parse", "refs/heads/main"],
+        tmpdir(),
+      ).out.trim();
+      expect(serverRev).toBe(localRev);
+
+      // post-receive placeholder fired and logged the ref.
+      const logPath = join(bare, "post-receive.log");
+      expect(existsSync(logPath)).toBe(true);
+      expect(readFileSync(logPath, "utf8")).toContain("refs/heads/main");
+    } finally {
+      server.stop(true);
+      rmSync(work, { recursive: true, force: true });
+      h.cleanup();
+    }
+  });
+});

package/src/git-transport.ts

@@ -0,0 +1,473 @@
+/**
+ * Hub-authenticated git smart-HTTP transport — the Surface Git Transport
+ * substrate (Phase 0a, design doc 2026-06-30-surface-git-transport.md).
+ *
+ * The hub provides ONE general primitive: an authenticated `git http-backend`
+ * endpoint at `/git/<name>/*` backed by a bare repo per `<name>`. A client
+ * (agent, human, or a standalone Claude Code session) authenticates with a
+ * hub-issued JWT carrying `surface:<name>:write` (push) or `surface:<name>:read`
+ * (fetch) and does a plain `git push` / `git clone`. Surfaces are the first
+ * consumer; "hub-authenticated git" generalizes to any module that wants
+ * 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.
+ *
+ * The mechanism (grounded in git's smart-HTTP protocol):
+ *   1. Discovery `GET /git/<name>/info/refs?service=git-(upload|receive)-pack`
+ *      then transfer `POST /git/<name>/git-(upload|receive)-pack`.
+ *      Scope keys PURELY off the service/path — no pack parsing:
+ *        receive-pack ⇒ write, upload-pack ⇒ read.
+ *   2. The 401 dance: an unauthenticated request gets `401` +
+ *      `WWW-Authenticate` (LOAD-BEARING — git won't invoke its credential
+ *      helper / retry without it). Enforced at BOTH the info/refs GET and the
+ *      transfer POST.
+ *   3. Bearer or Basic: git ≥2.46 sends `Authorization: Bearer <jwt>`; older
+ *      git uses Basic with `x-access-token:<jwt>` (GitHub's compat trick).
+ *      Both are accepted.
+ *   4. The gate validates the JWT (signature → hub keys; `iss` ∈ the
+ *      multi-origin hub-bound set; revocation — the existing
+ *      `validateAccessToken` path) and checks the scope, then streams the
+ *      request + response bodies through `git http-backend` with CGI env.
+ *      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 { validateAccessToken } from "./jwt-sign.ts";
+
+/** Logger seam — defaults to `console`. */
+export interface GitTransportLog {
+  warn: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+}
+
+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.
+   */
+  gitRoot: string;
+  /**
+   * The SET of origins this hub legitimately answers on
+   * (`buildHubBoundOrigins` — loopback ∪ expose-state ∪ platform ∪ per-request
+   * issuer). Passed straight to `validateAccessToken` as the `iss` allow-set so
+   * a credential minted under a still-valid prior origin keeps validating
+   * across an origin switch. SECURITY: must come ONLY from
+   * `buildHubBoundOrigins`, never a raw request Host (the signature is verified
+   * against the hub's own key first, so this is an additive `iss` relaxation
+   * only — see `validateAccessToken`).
+   */
+  knownIssuers: () => readonly string[];
+  /** Resolved peer address, surfaced to the backend as REMOTE_ADDR. */
+  peerAddr?: string | null;
+  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}$/;
+
+/** Which authority a request needs, keyed purely off the git service/path. */
+type Access = "read" | "write";
+
+interface ParsedGitPath {
+  /** Canonical surface name (trailing `.git` stripped). */
+  name: string;
+  /** The git subpath after the name, e.g. `info/refs` or `git-receive-pack`. */
+  gitSubpath: string;
+}
+
+/**
+ * Parse `/git/<name>/<gitSubpath>` (the `<name>` may carry a trailing `.git`).
+ * Returns null when the path is not a well-formed, safe git route — the caller
+ * 404s (we don't distinguish malformed-name from unknown-surface, to avoid
+ * leaking which names exist).
+ */
+export function parseGitPath(pathname: string): ParsedGitPath | null {
+  if (!pathname.startsWith("/git/")) return null;
+  const rest = pathname.slice("/git/".length);
+  const slash = rest.indexOf("/");
+  // A bare `/git/<name>` with no git subpath is never a real smart-HTTP request.
+  if (slash <= 0) return null;
+  const rawName = rest.slice(0, slash);
+  const gitSubpath = rest.slice(slash + 1);
+  if (gitSubpath.length === 0) return null;
+  const name = rawName.endsWith(".git") ? rawName.slice(0, -".git".length) : rawName;
+  if (!SURFACE_NAME_RE.test(name)) return null;
+  // Defense-in-depth: reject any traversal sequence in the remaining subpath.
+  // `git http-backend` confines itself to GIT_PROJECT_ROOT, but we never want a
+  // `..` to reach it. (Legitimate subpaths are `info/refs`, `git-upload-pack`,
+  // `git-receive-pack`, `objects/...` — none contain `..`.)
+  if (gitSubpath.split("/").some((seg) => seg === "..")) return null;
+  return { name, gitSubpath };
+}
+
+/**
+ * Required authority for a request: write for receive-pack (push), read for
+ * upload-pack (fetch) and any other discovery/dumb path. Keys purely off the
+ * service param / path — no pack inspection.
+ */
+export function requiredAccess(gitSubpath: string, serviceParam: string | null): Access {
+  if (gitSubpath === "git-receive-pack") return "write";
+  if (gitSubpath === "git-upload-pack") return "read";
+  if (gitSubpath === "info/refs") {
+    return serviceParam === "git-receive-pack" ? "write" : "read";
+  }
+  // Dumb-HTTP object/ref fetches (objects/*, HEAD, packed-refs) are read-only.
+  return "read";
+}
+
+/**
+ * Extract the presented JWT from either `Authorization: Bearer <jwt>` or HTTP
+ * Basic. Returns null when no credential is present.
+ *
+ * Basic forms accepted (GitHub-compat, §6.3):
+ *   - `x-access-token:<jwt>`  → token in the password (the documented form);
+ *   - `<jwt>:x-oauth-basic`   → token in the username (legacy);
+ *   - `<jwt>:`                → token in the username (empty password).
+ */
+export function extractToken(req: Request): string | null {
+  const header = req.headers.get("authorization");
+  if (!header) return null;
+  const bearer = header.match(/^Bearer\s+(.+)$/i);
+  if (bearer?.[1]) return bearer[1].trim();
+  const basic = header.match(/^Basic\s+(.+)$/i);
+  if (basic?.[1]) {
+    let decoded: string;
+    try {
+      decoded = Buffer.from(basic[1].trim(), "base64").toString("utf8");
+    } catch {
+      return null;
+    }
+    const idx = decoded.indexOf(":");
+    const user = idx === -1 ? decoded : decoded.slice(0, idx);
+    const pass = idx === -1 ? "" : decoded.slice(idx + 1);
+    if (user === "x-access-token") return pass || null;
+    if (pass && pass !== "x-oauth-basic") return pass;
+    return user || null;
+  }
+  return null;
+}
+
+/**
+ * 401 — missing or invalid credential. The `WWW-Authenticate` header is
+ * LOAD-BEARING: without it git won't invoke its credential helper or retry.
+ * We advertise BOTH `Bearer` (git ≥2.46 native + modern helpers) and `Basic`
+ * (older git's helper-based retry with `x-access-token:<jwt>`), so the widest
+ * range of clients re-authenticates.
+ */
+function unauthorized(reason: string): Response {
+  const headers = new Headers({
+    "content-type": "text/plain; charset=utf-8",
+    "cache-control": "no-store",
+  });
+  headers.append("www-authenticate", "Bearer");
+  headers.append("www-authenticate", 'Basic realm="Parachute Surface Git"');
+  return new Response(`Unauthorized: ${reason}\n`, { status: 401, headers });
+}
+
+/**
+ * 403 — a VALID credential that lacks the required scope. Deliberately NOT a
+ * 401: re-prompting the same identity yields no more authority, so a 401 would
+ * only spin the credential helper. The `WWW-Authenticate: ... insufficient_scope`
+ * header makes the reason machine-readable (RFC 6750), mirroring
+ * `adminAuthErrorResponse`.
+ */
+function forbidden(scope: string): Response {
+  return new Response(`Forbidden: token missing required scope ${scope}\n`, {
+    status: 403,
+    headers: {
+      "content-type": "text/plain; charset=utf-8",
+      "cache-control": "no-store",
+      "www-authenticate": `Bearer error="insufficient_scope", scope="${scope}"`,
+    },
+  });
+}
+
+/**
+ * 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.
+ * Exported for unit testing.
+ */
+export function findHeaderEnd(buf: Uint8Array): { idx: number; sepLen: number } | null {
+  for (let i = 0; i + 1 < buf.length; i++) {
+    if (buf[i] === 0x0a && buf[i + 1] === 0x0a) return { idx: i, sepLen: 2 };
+    if (
+      i + 3 < buf.length &&
+      buf[i] === 0x0d &&
+      buf[i + 1] === 0x0a &&
+      buf[i + 2] === 0x0d &&
+      buf[i + 3] === 0x0a
+    ) {
+      return { idx: i, sepLen: 4 };
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse CGI response headers (the block before the first blank line) into an
+ * HTTP status + Headers. `Status: NNN reason` maps to the HTTP status (default
+ * 200 when absent); every other `Key: Value` line is forwarded verbatim.
+ * Exported for unit testing.
+ */
+export function parseCgiHeaders(headerBlock: string): { status: number; headers: Headers } {
+  const headers = new Headers();
+  let status = 200;
+  for (const rawLine of headerBlock.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.length === 0) continue;
+    const colon = line.indexOf(":");
+    if (colon === -1) continue;
+    const key = line.slice(0, colon).trim();
+    const value = line.slice(colon + 1).trim();
+    if (key.toLowerCase() === "status") {
+      const code = Number.parseInt(value.split(/\s+/)[0] ?? "", 10);
+      if (Number.isFinite(code) && code >= 100 && code < 600) status = code;
+      continue;
+    }
+    headers.append(key, value);
+  }
+  return { status, headers };
+}
+
+const MAX_CGI_HEADER_BYTES = 64 * 1024;
+
+function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+
+/**
+ * Read the CGI header block off `stdout`, then return a Response whose body
+ * STREAMS the remainder (leftover bytes already read + the rest of the stream).
+ * Never buffers the whole pack — only the small header block is accumulated.
+ */
+async function cgiResponse(stdout: ReadableStream<Uint8Array>): Promise<Response> {
+  const reader = stdout.getReader();
+  let buf: Uint8Array = new Uint8Array(0);
+  let boundary: { idx: number; sepLen: number } | null = null;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (value && value.length > 0) {
+      buf = concatBytes(buf, value);
+      boundary = findHeaderEnd(buf);
+      if (boundary) break;
+      if (buf.length > MAX_CGI_HEADER_BYTES) {
+        reader.cancel().catch(() => {});
+        return new Response("bad gateway: git http-backend emitted no CGI header block\n", {
+          status: 502,
+          headers: { "content-type": "text/plain; charset=utf-8" },
+        });
+      }
+    }
+    if (done) break;
+  }
+
+  const headerEnd = boundary ? boundary.idx : buf.length;
+  const sepLen = boundary ? boundary.sepLen : 0;
+  const headerBlock = new TextDecoder().decode(buf.slice(0, headerEnd));
+  const leftover = buf.slice(headerEnd + sepLen);
+  const { status, headers } = parseCgiHeaders(headerBlock);
+
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      if (leftover.length > 0) controller.enqueue(leftover);
+      if (boundary === null) controller.close();
+    },
+    async pull(controller) {
+      const { done, value } = await reader.read();
+      if (done) {
+        controller.close();
+        return;
+      }
+      if (value && value.length > 0) controller.enqueue(value);
+    },
+    cancel(reason) {
+      reader.cancel(reason).catch(() => {});
+    },
+  });
+  return new Response(body, { status, headers });
+}
+
+/**
+ * Handle a `/git/<name>/*` request: parse → auth-gate → ensure bare repo →
+ * stream-proxy to `git http-backend`. Always returns a Response (the caller
+ * gates on the `/git/` prefix). A null `parseGitPath` 404s.
+ */
+export async function handleGitTransport(req: Request, deps: GitTransportDeps): Promise<Response> {
+  const log = deps.log ?? console;
+  const url = new URL(req.url);
+  const parsed = parseGitPath(url.pathname);
+  if (!parsed) return new Response("not found", { status: 404 });
+  const { name, gitSubpath } = parsed;
+
+  const serviceParam = url.searchParams.get("service");
+  const access = requiredAccess(gitSubpath, serviceParam);
+
+  // --- Auth gate (BEFORE touching the filesystem or spawning anything) ------
+  const token = extractToken(req);
+  if (!token) return unauthorized("a hub access token is required");
+
+  let sub: string;
+  let scopes: string[];
+  try {
+    const validated = await validateAccessToken(deps.db, token, deps.knownIssuers());
+    const subClaim = validated.payload.sub;
+    if (typeof subClaim !== "string" || subClaim.length === 0) {
+      return unauthorized("token missing required `sub` claim");
+    }
+    sub = subClaim;
+    const scopeClaim = (validated.payload as { scope?: unknown }).scope;
+    scopes = typeof scopeClaim === "string" ? scopeClaim.split(/\s+/).filter(Boolean) : [];
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return unauthorized(`invalid token: ${msg}`);
+  }
+
+  // Authority check. Write requires `surface:<name>:write`. Read is satisfied
+  // by either `surface:<name>:read` OR `surface:<name>:write` (write ⊇ read —
+  // a writer can always fetch, matching GitHub's model).
+  const writeScope = `surface:${name}:write`;
+  const readScope = `surface:${name}:read`;
+  const ok =
+    access === "write"
+      ? scopes.includes(writeScope)
+      : scopes.includes(readScope) || scopes.includes(writeScope);
+  if (!ok) return forbidden(access === "write" ? writeScope : readScope);
+
+  // --- Provision (first access) + proxy -------------------------------------
+  try {
+    ensureBareRepo(deps.gitRoot, name, log);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.warn(`[git-transport] repo provisioning failed for "${name}": ${msg}`);
+    return new Response("internal error: could not provision surface repo\n", {
+      status: 500,
+      headers: { "content-type": "text/plain; charset=utf-8" },
+    });
+  }
+
+  // Minimal CGI env — we deliberately do NOT inherit the hub's full process
+  // env (no hub secrets reach the subprocess). REMOTE_USER is the validated
+  // token subject only. GIT_PROTOCOL passes the client's protocol negotiation
+  // (v2) through; QUERY_STRING/CONTENT_TYPE/REQUEST_METHOD are standard CGI.
+  const query = url.search.startsWith("?") ? url.search.slice(1) : url.search;
+  const env: Record<string, string> = {
+    PATH: process.env.PATH ?? "",
+    GIT_PROJECT_ROOT: deps.gitRoot,
+    GIT_HTTP_EXPORT_ALL: "1",
+    PATH_INFO: `/${name}.git/${gitSubpath}`,
+    REQUEST_METHOD: req.method,
+    QUERY_STRING: query,
+    CONTENT_TYPE: req.headers.get("content-type") ?? "",
+    REMOTE_USER: sub,
+    REMOTE_ADDR: deps.peerAddr ?? "",
+    GIT_PROTOCOL: req.headers.get("git-protocol") ?? "",
+  };
+  // Set CONTENT_LENGTH only for non-chunked bodies. Large pushes use chunked
+  // transfer (no Content-Length): the smart-service POST path reads the
+  // self-delimiting pkt-line/pack stream off stdin to its natural end, so we
+  // simply pipe the request body and let stdin EOF terminate it — never
+  // buffering the pack to compute a length.
+  const contentLength = req.headers.get("content-length");
+  if (contentLength) env.CONTENT_LENGTH = contentLength;
+
+  let proc: ReturnType<typeof Bun.spawn>;
+  try {
+    proc = Bun.spawn(["git", "http-backend"], {
+      env,
+      // Stream the request body straight to the backend's stdin (Bun pumps it
+      // concurrently with our stdout read — no deadlock, no buffering). GET
+      // discovery has no body.
+      stdin: req.body ?? "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.warn(`[git-transport] failed to spawn git http-backend: ${msg}`);
+    return new Response("internal error: git http-backend unavailable\n", {
+      status: 500,
+      headers: { "content-type": "text/plain; charset=utf-8" },
+    });
+  }
+
+  // Drain stderr in the background — surfaces hook output + backend errors in
+  // the hub log without blocking the response stream.
+  void (async () => {
+    try {
+      const text = await new Response(proc.stderr as ReadableStream<Uint8Array>).text();
+      if (text.trim().length > 0) log.info(`[git-transport] ${name}: ${text.trim()}`);
+    } catch {
+      // stderr drain is best-effort.
+    }
+  })();
+
+  return cgiResponse(proc.stdout as ReadableStream<Uint8Array>);
+}

package/src/hub-server.ts

@@ -239,6 +239,7 @@ import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "./config.ts";
 import { applyCorsHeaders, corsPreflightResponse, isCorsAllowedRoute } from "./cors.ts";
 import { ensureCsrfToken } from "./csrf.ts";
 import { readExposeState } from "./expose-state.ts";
+import { handleGitTransport } from "./git-transport.ts";
 import { HUB_DEFAULT_PORT, HUB_SVC, clearHubPort, writeHubPort } from "./hub-control.ts";
 import {
   classifyDbError,
@@ -1212,6 +1213,12 @@ export interface HubFetchDeps {
    * the doc reflect `parachute vault create` etc. without re-running expose.
    */
   manifestPath?: string;
+  /**
+   * Directory holding the per-surface bare repos for the git-transport endpoint
+   * (`/git/<name>/*` → `<gitRoot>/<name>.git`). Tests point this at a tmpdir;
+   * production defaults to `<CONFIG_DIR>/hub/git`.
+   */
+  gitRoot?: string;
   /**
    * Path to `connections.json` (the Connections store, P5). Tests point this
    * at a tmpdir; production defaults to `<CONFIG_DIR>/connections.json`.
@@ -1983,6 +1990,7 @@ export function hubFetch(
   const getDb = deps?.getDb;
   const configuredIssuer = deps?.issuer;
   const manifestPath = deps?.manifestPath ?? SERVICES_MANIFEST_PATH;
+  const gitRoot = deps?.gitRoot ?? join(CONFIG_DIR, "hub", "git");
   const spaDistDir = deps?.spaDistDir ?? defaultSpaDistDir();
   const loopbackPort = deps?.loopbackPort;
   const loadExposeHubOrigin =
@@ -3801,6 +3809,24 @@ export function hubFetch(
         return serveSpa(spaDistDir, pathname, "/admin");
       }
 
+      // /git/<name>/* — hub-authenticated git smart-HTTP transport (Surface
+      // Git Transport, Phase 0a). Placed BEFORE the generic services.json
+      // proxy so a `/git/` route is never shadowed by a module mount. The
+      // endpoint is AUTH-gated, not LAYER-gated: it's reachable from any
+      // exposure layer because the hub JWT (validated against the multi-origin
+      // iss-set) is the gate. It NEVER builds or executes the pushed tree — the
+      // hub only receives + stores bytes (the RCE-bearing build is surface-host's
+      // sandboxed job, Phase 0b). See src/git-transport.ts.
+      if (pathname.startsWith("/git/")) {
+        if (!getDb) return new Response("not found", { status: 404 });
+        return handleGitTransport(req, {
+          db: getDb(),
+          gitRoot,
+          knownIssuers: () => oauthDeps(req).hubBoundOrigins(),
+          peerAddr,
+        });
+      }
+
       // Generic services.json-driven dispatch for non-vault modules. Reaches
       // here only after every hub-owned prefix above has had its turn — so
       // `/`, `/admin/*`, `/oauth/*`, `/.well-known/*`, `/hub/*`, `/vault/*`,

package/src/oauth-handlers.ts

@@ -425,6 +425,7 @@ function oauthErrorRedirect(
 const OPTIONAL_MODULE_SCOPES: ReadonlyArray<readonly [prefix: string, short: string]> = [
   ["scribe:", "scribe"],
   ["agent:", "agent"],
+  ["surface:", "surface"],
 ];
 
 /**

package/src/scope-explanations.ts

@@ -46,12 +46,13 @@ export const SCOPE_EXPLANATIONS: Record<string, ScopeExplanation> = {
       "Read and write everything, plus admin: config & settings, triggers & automation, GitHub backup, and minting access tokens.",
     level: "admin",
   },
-  // Optional-module scopes (scribe / agent). These are in FIRST_PARTY_SCOPES
-  // (= Object.keys(this map)) but the modules may not be installed — so they're
-  // GATED in `OPTIONAL_MODULE_SCOPES` (oauth-handlers.ts) and only advertised in
-  // `scopes_supported` when the service is in services.json. If you add scopes
-  // for another optional module here, add a matching gate there too, or a
-  // vault-only hub will over-advertise them (the bug behind hub#489).
+  // Optional-module scopes (scribe / agent / surface). These are in
+  // FIRST_PARTY_SCOPES (= Object.keys(this map)) but the modules may not be
+  // installed — so they're GATED in `OPTIONAL_MODULE_SCOPES` (oauth-handlers.ts)
+  // and only advertised in `scopes_supported` when the service is in
+  // services.json. If you add scopes for another optional module here, add a
+  // matching gate there too, or a vault-only hub will over-advertise them (the
+  // bug behind hub#489).
   "scribe:transcribe": {
     label: "Send audio to Scribe for transcription.",
     level: "write",
@@ -64,6 +65,20 @@ export const SCOPE_EXPLANATIONS: Record<string, ScopeExplanation> = {
     label: "Post messages to your Agent.",
     level: "send",
   },
+  // Surface Git Transport scopes (surface-host). `surface:read` = clone/fetch a
+  // surface's hub-hosted git repo; `surface:write` = push to it. Named forms
+  // (`surface:<name>:<verb>`) collapse to these via the 3→2-segment rule in
+  // `isKnownScope`. surface-host's module.json declares them too; listing them
+  // here makes them first-party (mintable + a consent label) even on a hub
+  // where surface-host isn't installed.
+  "surface:read": {
+    label: "Clone and fetch a surface's source (its hub-hosted git repo).",
+    level: "read",
+  },
+  "surface:write": {
+    label: "Push to a surface's source (its hub-hosted git repo).",
+    level: "write",
+  },
   "hub:admin": {
     label: "Manage hub identity (user accounts, signing keys, registered OAuth clients).",
     level: "admin",