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

package/package.json

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

package/src/__tests__/admin-agent-grants.test.ts

@@ -1658,3 +1658,313 @@ describe("revoke(mcp)", () => {
     expect(readGrants(harness.storePath).find((r) => r.id === id)?.material).toBeUndefined();
   });
 });
+
+// === surface grants (Surface Git Transport Phase 2, §6a) ===================
+
+describe("surface grants (Phase 2)", () => {
+  test("PUT: creates a pending surface grant (201) — no material, no self-grant", async () => {
+    const bearer = await moduleBearer();
+    const res = await dispatch(
+      bearerReq("PUT", "/admin/grants", bearer, {
+        agent: "surfacer",
+        connection: { kind: "surface", target: "gitcoin-brain", access: "write" },
+      }),
+    );
+    expect(res.status).toBe(201);
+    const body = await json(res);
+    // A note can only REQUEST — it lands pending with NO material until the
+    // operator approves. This IS the "a note can never GRANT" invariant.
+    expect(body.status).toBe("pending");
+    expect(body).not.toHaveProperty("material");
+    expect((body.connection as Record<string, unknown>).kind).toBe("surface");
+    expect((body.connection as Record<string, unknown>).access).toBe("write");
+  });
+
+  test("PUT: a pending surface grant's /material 409s (never grantable pre-approval)", async () => {
+    const bearer = await moduleBearer();
+    const created = await json(
+      await dispatch(
+        bearerReq("PUT", "/admin/grants", bearer, {
+          agent: "surfacer",
+          connection: { kind: "surface", target: "gitcoin-brain", access: "write" },
+        }),
+      ),
+    );
+    const res = await dispatch(bearerReq("GET", `/admin/grants/${created.id}/material`, bearer));
+    expect(res.status).toBe(409);
+  });
+
+  test("PUT: rejects an invalid surface name (400)", async () => {
+    const bearer = await moduleBearer();
+    const res = await dispatch(
+      bearerReq("PUT", "/admin/grants", bearer, {
+        agent: "surfacer",
+        connection: { kind: "surface", target: "bad/name", access: "write" },
+      }),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test("PUT: rejects a bad surface access verb (400)", async () => {
+    const bearer = await moduleBearer();
+    const res = await dispatch(
+      bearerReq("PUT", "/admin/grants", bearer, {
+        agent: "surfacer",
+        connection: { kind: "surface", target: "gitcoin-brain", access: "admin" },
+      }),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test("approve: MINTS a registered surface:<name>:write token (operator-gated)", async () => {
+    const bearer = await moduleBearer();
+    const cookie = await operatorCookie();
+    const created = await json(
+      await dispatch(
+        bearerReq("PUT", "/admin/grants", bearer, {
+          agent: "surfacer",
+          connection: { kind: "surface", target: "gitcoin-brain", access: "write" },
+        }),
+      ),
+    );
+    const id = created.id as string;
+    const res = await dispatch(cookieReq("POST", `/admin/grants/${id}/approve`, cookie));
+    expect(res.status).toBe(200);
+    const body = await json(res);
+    expect(body.status).toBe("approved");
+    expect(body).not.toHaveProperty("material");
+    expect(body.approvedAt).toBeDefined();
+
+    const stored = readGrants(harness.storePath).find((r) => r.id === id);
+    const mat = stored?.material as { kind: string; token: string; jti: string };
+    expect(mat.kind).toBe("surface");
+    const claims = decodeJwt(mat.token) as Record<string, unknown>;
+    expect(claims.scope).toBe("surface:gitcoin-brain:write");
+    expect(claims.aud).toBe("surface.gitcoin-brain");
+    // registered → revocable
+    expect(findTokenRowByJti(harness.db, mat.jti)).not.toBeNull();
+  });
+
+  test("approve: is operator-only — a module Bearer cannot approve", async () => {
+    const bearer = await moduleBearer();
+    const created = await json(
+      await dispatch(
+        bearerReq("PUT", "/admin/grants", bearer, {
+          agent: "surfacer",
+          connection: { kind: "surface", target: "gitcoin-brain", access: "write" },
+        }),
+      ),
+    );
+    const id = created.id as string;
+    // A host-admin Bearer is module-auth, NOT the operator cookie the approve
+    // path requires — so it 401s (a note/module can never self-approve).
+    const res = await dispatch(bearerReq("POST", `/admin/grants/${id}/approve`, bearer));
+    expect(res.status).toBe(401);
+    expect(readGrants(harness.storePath).find((r) => r.id === id)?.status).toBe("pending");
+  });
+
+  test("approve: a non-first-admin operator cannot approve (403)", async () => {
+    const bearer = await moduleBearer();
+    const friend = await friendCookie();
+    const created = await json(
+      await dispatch(
+        bearerReq("PUT", "/admin/grants", bearer, {
+          agent: "surfacer",
+          connection: { kind: "surface", target: "gitcoin-brain", access: "write" },
+        }),
+      ),
+    );
+    const id = created.id as string;
+    const res = await dispatch(cookieReq("POST", `/admin/grants/${id}/approve`, friend));
+    expect(res.status).toBe(403);
+    expect(readGrants(harness.storePath).find((r) => r.id === id)?.status).toBe("pending");
+  });
+
+  test("material: an approved surface grant returns { kind:surface, token, remoteUrl }", async () => {
+    const bearer = await moduleBearer();
+    const cookie = await operatorCookie();
+    const created = await json(
+      await dispatch(
+        bearerReq("PUT", "/admin/grants", bearer, {
+          agent: "surfacer",
+          connection: { kind: "surface", target: "gitcoin-brain", access: "write" },
+        }),
+      ),
+    );
+    const id = created.id as string;
+    await dispatch(cookieReq("POST", `/admin/grants/${id}/approve`, cookie));
+    const res = await dispatch(bearerReq("GET", `/admin/grants/${id}/material`, bearer));
+    expect(res.status).toBe(200);
+    const mat = await json(res);
+    expect(mat.kind).toBe("surface");
+    expect(typeof mat.token).toBe("string");
+    // The git remote the agent clones/pushes to — the git-transport endpoint.
+    expect(mat.remoteUrl).toBe(`${HUB_ORIGIN}/git/gitcoin-brain`);
+    const claims = decodeJwt(mat.token as string) as Record<string, unknown>;
+    expect(claims.scope).toBe("surface:gitcoin-brain:write");
+  });
+
+  test("a read-only surface grant mints surface:<name>:read", async () => {
+    const bearer = await moduleBearer();
+    const cookie = await operatorCookie();
+    const created = await json(
+      await dispatch(
+        bearerReq("PUT", "/admin/grants", bearer, {
+          agent: "surfacer",
+          connection: { kind: "surface", target: "gitcoin-brain", access: "read" },
+        }),
+      ),
+    );
+    const id = created.id as string;
+    await dispatch(cookieReq("POST", `/admin/grants/${id}/approve`, cookie));
+    const mat = await json(
+      await dispatch(bearerReq("GET", `/admin/grants/${id}/material`, bearer)),
+    );
+    expect(mat.remoteUrl).toBe(`${HUB_ORIGIN}/git/gitcoin-brain`);
+    const claims = decodeJwt(mat.token as string) as Record<string, unknown>;
+    expect(claims.scope).toBe("surface:gitcoin-brain:read");
+  });
+
+  test("a mixed-case surface name is canonicalized to lowercase (scope + remote + idempotency)", async () => {
+    const bearer = await moduleBearer();
+    const cookie = await operatorCookie();
+    const created = await json(
+      await dispatch(
+        bearerReq("PUT", "/admin/grants", bearer, {
+          agent: "surfacer",
+          connection: { kind: "surface", target: "GitCoin-Brain", access: "write" },
+        }),
+      ),
+    );
+    // Stored target is normalized to lowercase, so the minted scope + the /material
+    // remote match a lowercase-registered surface and the agent's echoed-target key
+    // stays consistent (no mixed-case collapse mismatch).
+    expect((created.connection as Record<string, unknown>).target).toBe("gitcoin-brain");
+    // A second PUT with the lowercase twin is the SAME grant (idempotent), not a fork.
+    const twin = await json(
+      await dispatch(
+        bearerReq("PUT", "/admin/grants", bearer, {
+          agent: "surfacer",
+          connection: { kind: "surface", target: "gitcoin-brain", access: "write" },
+        }),
+      ),
+    );
+    expect(twin.id).toBe(created.id);
+    expect(readGrants(harness.storePath).filter((r) => r.agent === "surfacer")).toHaveLength(1);
+    // Approve → the minted scope + the /material remote are both lowercase.
+    await dispatch(cookieReq("POST", `/admin/grants/${created.id as string}/approve`, cookie));
+    const mat = await json(
+      await dispatch(bearerReq("GET", `/admin/grants/${created.id as string}/material`, bearer)),
+    );
+    expect(mat.remoteUrl).toBe(`${HUB_ORIGIN}/git/gitcoin-brain`);
+    expect((decodeJwt(mat.token as string) as Record<string, unknown>).scope).toBe(
+      "surface:gitcoin-brain:write",
+    );
+  });
+
+  test("re-approval revokes the prior minted surface token", async () => {
+    const bearer = await moduleBearer();
+    const cookie = await operatorCookie();
+    const created = await json(
+      await dispatch(
+        bearerReq("PUT", "/admin/grants", bearer, {
+          agent: "surfacer",
+          connection: { kind: "surface", target: "gitcoin-brain", access: "write" },
+        }),
+      ),
+    );
+    const id = created.id as string;
+    await dispatch(cookieReq("POST", `/admin/grants/${id}/approve`, cookie));
+    const firstJti = (
+      readGrants(harness.storePath).find((r) => r.id === id)?.material as { jti: string }
+    ).jti;
+    await dispatch(cookieReq("POST", `/admin/grants/${id}/approve`, cookie));
+    const secondJti = (
+      readGrants(harness.storePath).find((r) => r.id === id)?.material as { jti: string }
+    ).jti;
+    expect(secondJti).not.toBe(firstJti);
+    expect(findTokenRowByJti(harness.db, firstJti)?.revokedAt).toBeTruthy();
+    expect(findTokenRowByJti(harness.db, secondJti)?.revokedAt).toBeFalsy();
+  });
+
+  test("revoke: drops the material AND revokes the minted token in the registry", async () => {
+    const bearer = await moduleBearer();
+    const cookie = await operatorCookie();
+    const created = await json(
+      await dispatch(
+        bearerReq("PUT", "/admin/grants", bearer, {
+          agent: "surfacer",
+          connection: { kind: "surface", target: "gitcoin-brain", access: "write" },
+        }),
+      ),
+    );
+    const id = created.id as string;
+    await dispatch(cookieReq("POST", `/admin/grants/${id}/approve`, cookie));
+    const jti = (
+      readGrants(harness.storePath).find((r) => r.id === id)?.material as { jti: string }
+    ).jti;
+    const res = await dispatch(cookieReq("POST", `/admin/grants/${id}/revoke`, cookie));
+    expect(res.status).toBe(200);
+    const stored = readGrants(harness.storePath).find((r) => r.id === id);
+    expect(stored?.status).toBe("revoked");
+    expect(stored?.material).toBeUndefined();
+    expect(findTokenRowByJti(harness.db, jti)?.revokedAt).toBeTruthy();
+    // /material now 409s
+    const mat = await dispatch(bearerReq("GET", `/admin/grants/${id}/material`, bearer));
+    expect(mat.status).toBe(409);
+  });
+
+  test("reconcile prunes a surface grant that's no longer wanted", async () => {
+    const bearer = await moduleBearer();
+    const cookie = await operatorCookie();
+    const created = await json(
+      await dispatch(
+        bearerReq("PUT", "/admin/grants", bearer, {
+          agent: "surfacer",
+          connection: { kind: "surface", target: "gitcoin-brain", access: "write" },
+        }),
+      ),
+    );
+    const id = created.id as string;
+    await dispatch(cookieReq("POST", `/admin/grants/${id}/approve`, cookie));
+    const jti = (
+      readGrants(harness.storePath).find((r) => r.id === id)?.material as { jti: string }
+    ).jti;
+    // reconcile with NO live connections → prune (tears down the token too)
+    const res = await dispatch(
+      bearerReq("POST", "/admin/grants/reconcile", bearer, {
+        agent: "surfacer",
+        liveConnections: [],
+      }),
+    );
+    expect(res.status).toBe(200);
+    const body = await json(res);
+    expect(body.pruned).toBe(1);
+    expect(getGrant(harness.storePath, id)).toBeNull();
+    expect(findTokenRowByJti(harness.db, jti)?.revokedAt).toBeTruthy();
+  });
+
+  test("reconcile KEEPS a surface grant that's still declared (spec-derived key match)", async () => {
+    const bearer = await moduleBearer();
+    const created = await json(
+      await dispatch(
+        bearerReq("PUT", "/admin/grants", bearer, {
+          agent: "surfacer",
+          connection: { kind: "surface", target: "gitcoin-brain", access: "write" },
+        }),
+      ),
+    );
+    const id = created.id as string;
+    // The agent sends the SPEC (not a pre-computed key); the hub re-derives the
+    // key with its OWN connectionKey → the still-wanted grant is kept.
+    const res = await dispatch(
+      bearerReq("POST", "/admin/grants/reconcile", bearer, {
+        agent: "surfacer",
+        liveConnections: [{ kind: "surface", target: "gitcoin-brain", access: "write" }],
+      }),
+    );
+    expect(res.status).toBe(200);
+    expect((await json(res)).pruned).toBe(0);
+    expect(getGrant(harness.storePath, id)).not.toBeNull();
+  });
+});

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

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

package/src/admin-agent-grants.ts

@@ -33,15 +33,18 @@
  *   GET  /admin/grants?agent=<name>          → { grants: [...] } — NO material on any row.
  *   GET  /admin/grants/<id>/material         → APPROVED grants only: the injectable
  *                                              secret. vault → { kind, token, mcpUrl };
- *                                              service → { kind, token, inject }.
+ *                                              service → { kind, token, inject };
+ *                                              surface → { kind, token, remoteUrl }.
  *                                              404 unknown id, 409 not approved.
  *
  * OPERATOR-AUTH (a first-admin session cookie; CSRF-belted by the dispatch in
  * hub-server.ts, exactly like /admin/connections POST/DELETE):
  *
  *   POST /admin/grants/<id>/approve          { token? } → vault: MINT now + store;
- *                                              service: store the pasted `token`. Returns
- *                                              the updated grant (no material).
+ *                                              surface: MINT a `surface:<name>:<verb>`
+ *                                              token now + store; service: store the
+ *                                              pasted `token`. Returns the updated
+ *                                              grant (no material).
  *   POST /admin/grants/<id>/revoke           → drop the stored material + status=revoked
  *                                              (the agent loses it next spawn).
  *
@@ -58,6 +61,7 @@ import {
   requireScope,
 } from "./admin-auth.ts";
 import { HOST_ADMIN_SCOPE } from "./admin-vaults.ts";
+import { SURFACE_NAME_RE, surfaceGitRemoteUrl } from "./git-registry.ts";
 import {
   type ConnectionSpec,
   type GrantAccess,
@@ -92,6 +96,12 @@ import { validateVaultName } from "./vault-name.ts";
  * table so revoke can drop it.
  */
 const VAULT_GRANT_TTL_SECONDS = 90 * 24 * 60 * 60;
+/**
+ * TTL of a minted surface grant token — 90 days, matching the vault grant posture
+ * (a headless agent re-fetches at spawn; a long-lived token spares a re-mint every
+ * turn). Registered in the tokens table so revoke can drop it (registered-mint rule).
+ */
+const SURFACE_GRANT_TTL_SECONDS = 90 * 24 * 60 * 60;
 const GRANT_CLIENT_ID = "parachute-hub-spa";
 
 /** Agent-name charset — lands in the grant id + a `?agent=` query. Conservative slug. */
@@ -367,8 +377,8 @@ function parseConnectionSpec(raw: unknown): { spec: ConnectionSpec } | { error:
   }
   const c = raw as Record<string, unknown>;
   const kind = c.kind;
-  if (kind !== "vault" && kind !== "service" && kind !== "mcp") {
-    return { error: `connection.kind must be "vault", "service", or "mcp"` };
+  if (kind !== "vault" && kind !== "service" && kind !== "surface" && kind !== "mcp") {
+    return { error: `connection.kind must be "vault", "service", "surface", or "mcp"` };
   }
   const target = typeof c.target === "string" ? c.target.trim() : "";
   if (!target) return { error: "connection.target is required" };
@@ -435,6 +445,34 @@ function parseConnectionSpec(raw: unknown): { spec: ConnectionSpec } | { error:
     };
   }
 
+  if (kind === "surface") {
+    // A surface's hub-hosted git repo (Phase 2). `target` is the surface name —
+    // the SAME `SURFACE_NAME_RE` slug the git-transport URL parser + registry
+    // enforce (no slashes/dots → no path traversal in the git endpoint), so a
+    // grant can only ever name a well-formed surface. NORMALIZED to lowercase (the
+    // canonical form): `connectionKey` + `grantId` already lowercase, so the STORED
+    // target, the minted `surface:<name>:<verb>` scope, and the `/git/<name>` remote
+    // must lowercase too — else a mixed-case want (e.g. `GitCoin-Brain`) would collapse
+    // to the same grantId as its lowercase twin but mint a differently-cased scope,
+    // and the agent's status key (from its echoed target) would diverge. Surface names
+    // are lowercase-kebab by convention (surface-host registers them lowercase). The
+    // agent side lowercases at parse too (grants.ts parseSurfaceWant) so both repos'
+    // keys agree. `access` is `read` (default) or `write`; the agent always declares
+    // the verb explicitly (`surface:<name>:<verb>`).
+    if (!SURFACE_NAME_RE.test(target)) {
+      return { error: `connection.target "${target}" is not a valid surface name` };
+    }
+    const name = target.toLowerCase();
+    let access: GrantAccess = "read";
+    if (c.access !== undefined) {
+      if (c.access !== "read" && c.access !== "write") {
+        return { error: `connection.access must be "read" or "write"` };
+      }
+      access = c.access;
+    }
+    return { spec: { kind: "surface", target: name, access } };
+  }
+
   // mcp — modeled, not grantable in 4b-1. Accept a URL target; the grant lands
   // pending with the slice-2 reason. Validate it parses as an http(s) URL so a
   // typo doesn't sit pending forever masquerading as an OAuth-blocked grant.
@@ -520,6 +558,15 @@ async function grantMaterial(req: Request, id: string, deps: AgentGrantsDeps): P
       token: grant.material.token,
       inject: grant.connection.kind === "service" ? (grant.connection.inject ?? []) : [],
     };
+  } else if (grant.material.kind === "surface") {
+    // The minted `surface:<name>:<verb>` token + the surface's git remote — the
+    // agent injects the token into `git clone`/`git push` (via GIT_ASKPASS) to
+    // the remote. One token covers clone AND push (write ⊇ read at the endpoint).
+    payload = {
+      kind: "surface",
+      token: grant.material.token,
+      remoteUrl: surfaceGitRemoteUrl(deps.hubOrigin, grant.connection.target),
+    };
   } else {
     // mcp — refresh first if it's an OAuth grant near/past expiry. A refresh
     // FAILURE flips the grant to needs_consent (material dropped) and 409s.
@@ -714,6 +761,57 @@ async function approveGrant(req: Request, id: string, deps: AgentGrantsDeps): Pr
     return grantResponse(200, updated);
   }
 
+  if (conn.kind === "surface") {
+    // Surface git grant (Phase 2, §6a step 3). The operator approving here IS the
+    // "a note can only REQUEST, never GRANT" gate: the module registered this
+    // pending, and only this operator-cookie + first-admin path mints the token.
+    // We deliberately do NOT require the surface to be REGISTERED at approve time:
+    // registration (surface-host discovering the `#surface` note) is async +
+    // declarative and may lag the grant; the git-transport already fails closed
+    // (404) on an unregistered name even with a valid token, so a pre-approved
+    // grant for a not-yet-declared surface is simply inert until it's declared —
+    // no escalation, and no ordering dependency between the two operator actions.
+    //
+    // Re-approval of an already-approved surface grant: revoke the prior minted
+    // token first so exactly one live token exists per grant (mirrors vault).
+    if (grant.material?.kind === "surface") {
+      try {
+        revokeTokenByJti(deps.db, grant.material.jti, now);
+      } catch {
+        // Best-effort — a missing registry row leaves nothing to revoke.
+      }
+    }
+    const access = conn.access ?? "read";
+    const scope = `surface:${conn.target}:${access}`;
+    let minted: { token: string; jti: string; expiresAt: string };
+    try {
+      minted = await mintSurfaceGrant(deps, op.userId, scope);
+    } catch (err) {
+      return jsonError(
+        500,
+        "mint_failed",
+        `failed to mint surface grant: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    const updated: GrantRecord = {
+      id: grant.id,
+      agent: grant.agent,
+      connection: grant.connection,
+      status: "approved",
+      createdAt: grant.createdAt,
+      approvedAt,
+      material: {
+        kind: "surface",
+        token: minted.token,
+        jti: minted.jti,
+        expiresAt: minted.expiresAt,
+      },
+    };
+    putGrant(deps.storePath, updated);
+    console.log(`agent grant approved: id=${id} agent=${grant.agent} kind=surface scope=${scope}`);
+    return grantResponse(200, updated);
+  }
+
   // service — store the operator-pasted API token.
   // Trim — a pasted "  tok  " must not inject whitespace into the eventual
   // `Authorization: Bearer` header (drive-by correctness fix; the mcp
@@ -1184,6 +1282,9 @@ async function revokeGrant(req: Request, id: string, deps: AgentGrantsDeps): Pro
  *
  *   - vault   → revoke the minted token in the registry so it's dead immediately,
  *               not just absent from the next fetch.
+ *   - surface → same as vault: revoke the minted `surface:<name>:<verb>` token in
+ *               the registry so the git endpoint rejects it immediately (the
+ *               revocation list), not just on the agent's next fetch.
  *   - mcp     → best-effort revoke the refresh token at the issuer so the remote
  *               credential dies, not just our local copy. A static bearer (no
  *               refresh/revocation endpoint) is a no-op (operator rotates upstream).
@@ -1195,7 +1296,7 @@ async function tearDownGrantMaterial(
   deps: AgentGrantsDeps,
   now: Date,
 ): Promise<void> {
-  if (grant.material?.kind === "vault") {
+  if (grant.material?.kind === "vault" || grant.material?.kind === "surface") {
     try {
       revokeTokenByJti(deps.db, grant.material.jti, now);
     } catch {
@@ -1373,6 +1474,55 @@ async function mintVaultGrant(
   return { token: signed.token, jti: signed.jti, expiresAt: signed.expiresAt };
 }
 
+/**
+ * Mint the token for an approved SURFACE grant (Phase 2): a REGISTERED
+ * (created_via "agent_grant") `surface:<name>:<access>` JWT the git-transport
+ * endpoint validates (`validateAccessToken` → signature + `iss` ∈ hub-bound set +
+ * revocation, then `scopes.includes("surface:<name>:<verb>")`). Mirrors
+ * {@link mintVaultGrant} — same TTL posture + registered-mint discipline — minus
+ * the vault-only bits: NO `vaultScope` pin (surface isn't a per-user vault) and
+ * NO `scoped_tags`. Audience is `surface.<name>` for symmetry with `vault.<name>`;
+ * the git endpoint doesn't check `aud` (it keys purely off the URL path + the
+ * scope), so it's cosmetic but honest.
+ *
+ * The scope is signed VERBATIM (no `capScopesToUserAuthority` — that caps only the
+ * OAuth-consent/mint-token paths, never `signAccessToken`), so a
+ * `surface:<name>:write` grant mints exactly that authority. The operator-cookie +
+ * first-admin approve gate upstream is the governance (a note can only REQUEST).
+ */
+async function mintSurfaceGrant(
+  deps: AgentGrantsDeps,
+  userId: string,
+  scope: string,
+): Promise<{ token: string; jti: string; expiresAt: string }> {
+  // `surface:<name>:<verb>` — the audience takes the surface name (parallel to
+  // `vault.<name>`); split off the middle segment.
+  const surfaceName = scope.split(":")[1] ?? "";
+  const sign = deps.signToken ?? signAccessToken;
+  const signed = await sign(deps.db, {
+    sub: userId || "agent-grant",
+    scopes: [scope],
+    audience: `surface.${surfaceName}`,
+    clientId: GRANT_CLIENT_ID,
+    issuer: deps.hubOrigin,
+    ttlSeconds: SURFACE_GRANT_TTL_SECONDS,
+    ...(deps.now !== undefined ? { now: deps.now } : {}),
+  });
+  // Register the long-lived mint so revoke can drop it (registered-mint rule —
+  // an unregistered long-lived token is unrevocable).
+  recordTokenMint(deps.db, {
+    jti: signed.jti,
+    createdVia: "agent_grant",
+    subject: "agent-grant",
+    ...(userId ? { userId } : {}),
+    clientId: GRANT_CLIENT_ID,
+    scopes: [scope],
+    expiresAt: signed.expiresAt,
+    ...(deps.now !== undefined ? { now: deps.now } : {}),
+  });
+  return { token: signed.token, jti: signed.jti, expiresAt: signed.expiresAt };
+}
+
 // ===========================================================================
 // Wire shapes
 // ===========================================================================

package/src/git-registry.ts

@@ -75,6 +75,19 @@ export function repoDirFor(gitRoot: string, name: string): string {
   return join(gitRoot, `${name}.git`);
 }
 
+/**
+ * The client-facing git remote for a surface — `<hubOrigin>/git/<name>` — the URL
+ * an authorized client (agent / human / standalone Claude Code) clones + pushes to
+ * (the git-transport endpoint, `parseGitPath`). The trailing `/info/refs` git
+ * appends resolves to `parseGitPath("/git/<name>/info/refs")`, so no `.git` suffix
+ * is needed on the URL. Handed to a surface-grant holder as the `remoteUrl` in its
+ * `/material` (Phase 2 §6a) so the agent knows where to clone/push. NOTE: `name`
+ * is a `SURFACE_NAME_RE` slug (validated upstream) — no path traversal possible.
+ */
+export function surfaceGitRemoteUrl(hubOrigin: string, name: string): string {
+  return `${hubOrigin.replace(/\/+$/, "")}/git/${name}`;
+}
+
 /**
  * Read + parse the registry. A missing or corrupt file yields an empty registry
  * (the transport still fails closed on unregistered names — see

package/src/grants-store.ts

@@ -43,15 +43,21 @@ export type GrantInject = "env" | "mcp";
  *     `target` is the service key; `inject` hints how the agent side wires it
  *     (`env` → an env var, `mcp` → the service's MCP server, or both). Grant =
  *     an operator-pasted API token.
+ *   - `surface` — a Parachute SURFACE's hub-hosted git repo (Surface Git
+ *     Transport Phase 2, design 2026-06-30-surface-git-transport.md §6a).
+ *     `target` is the surface name; `access` the verb (`write` = clone+push,
+ *     `read` = clone only — write ⊇ read at the git-transport endpoint). Grant =
+ *     a hub-minted, revocable `surface:<target>:<access>` JWT the agent injects
+ *     into `git push`/`git clone` via a per-spawn GIT_ASKPASS (never `.git/config`).
  *   - `mcp`     — a remote MCP / remote vault. `target` is the MCP URL. Grant =
  *     an OAuth token — NOT implemented in 4b-1 (slice 2). Modeled here; the
  *     grant stays `pending` with a clear reason.
  */
 export interface ConnectionSpec {
-  readonly kind: "vault" | "service" | "mcp";
-  /** Vault name / service key / MCP URL, per `kind`. */
+  readonly kind: "vault" | "service" | "surface" | "mcp";
+  /** Vault name / service key / surface name / MCP URL, per `kind`. */
   readonly target: string;
-  /** Vault grants only — `read` (default) or `write`. */
+  /** Vault + surface grants — `read` (default) or `write`. */
   readonly access?: GrantAccess;
   /** Vault grants only — tag-scope (`scoped_tags`); empty/absent = vault-wide. */
   readonly tags?: readonly string[];
@@ -87,6 +93,16 @@ export type GrantMaterial =
       /** The operator-pasted API token. */
       readonly token: string;
     }
+  | {
+      readonly kind: "surface";
+      /** The minted `surface:<target>:<access>` JWT (write ⊇ read — one token
+       *  authenticates both `git clone` and `git push`). */
+      readonly token: string;
+      /** jti of the minted token — registered so revoke can drop it. */
+      readonly jti: string;
+      /** ISO expiry of the minted token. */
+      readonly expiresAt: string;
+    }
   | {
       readonly kind: "mcp";
       /**
@@ -151,6 +167,10 @@ export function connectionKey(spec: ConnectionSpec): string {
   if (spec.kind === "service") {
     return `service:${target}`;
   }
+  if (spec.kind === "surface") {
+    const access = spec.access ?? "read";
+    return `surface:${target}:${access}`;
+  }
   // mcp — keyed on the URL only (its target).
   return `mcp:${target}`;
 }
@@ -181,7 +201,8 @@ function isConnectionSpec(v: unknown): v is ConnectionSpec {
   if (!v || typeof v !== "object") return false;
   const s = v as Record<string, unknown>;
   return (
-    (s.kind === "vault" || s.kind === "service" || s.kind === "mcp") && typeof s.target === "string"
+    (s.kind === "vault" || s.kind === "service" || s.kind === "surface" || s.kind === "mcp") &&
+    typeof s.target === "string"
   );
 }