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

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/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,247 @@
+/**
+ * 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`);
+}
+
+/**
+ * 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
+ * `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() };
+}