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

package/src/git-transport.ts

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

package/src/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"
   );
 }
 

package/src/hub-server.ts

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

package/src/scope-explanations.ts

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