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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.5-rc.1",
+  "version": "0.7.5-rc.2",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {
@@ -11,8 +11,15 @@
   "bin": {
     "parachute": "src/cli.ts"
   },
-  "workspaces": ["packages/*"],
-  "files": ["src", "web/ui/dist", "README.md", "LICENSE"],
+  "workspaces": [
+    "packages/*"
+  ],
+  "files": [
+    "src",
+    "web/ui/dist",
+    "README.md",
+    "LICENSE"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/ParachuteComputer/parachute-hub.git"

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

@@ -0,0 +1,144 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { notifySurfacePushed } from "../git-notify.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { validateAccessToken } from "../jwt-sign.ts";
+import { rotateSigningKey } from "../signing-keys.ts";
+
+const ISSUER = "http://127.0.0.1:1939";
+
+interface Harness {
+  db: ReturnType<typeof openHubDb>;
+  cleanup: () => void;
+}
+
+function makeHarness(): Harness {
+  const dir = mkdtempSync(join(tmpdir(), "phub-notify-"));
+  const db = openHubDb(hubDbPath(dir));
+  rotateSigningKey(db);
+  return {
+    db,
+    cleanup: () => {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+/** A fetch spy that records the last call and returns a canned response. */
+function fetchSpy(status = 200, body = '{"ok":true}') {
+  const calls: Array<{ url: string; init: RequestInit }> = [];
+  const impl = ((url: string | URL | Request, init?: RequestInit) => {
+    calls.push({ url: String(url), init: init ?? {} });
+    return Promise.resolve(new Response(body, { status }));
+  }) as unknown as typeof fetch;
+  return { impl, calls };
+}
+
+describe("notifySurfacePushed", () => {
+  test("no surface module installed → no-op, no fetch", async () => {
+    const h = makeHarness();
+    const spy = fetchSpy();
+    try {
+      const out = await notifySurfacePushed("brain", {
+        db: h.db,
+        issuer: ISSUER,
+        resolveModuleOrigin: () => null,
+        cloneBaseOrigin: ISSUER,
+        fetchImpl: spy.impl,
+        log: { warn() {}, info() {} },
+      });
+      expect(out.notified).toBe(false);
+      expect(out.reason).toBe("surface-module-not-installed");
+      expect(spy.calls.length).toBe(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("posts to /surface/api/git-pushed with a surface:admin bearer + surface:<name>:read pull token", async () => {
+    const h = makeHarness();
+    const spy = fetchSpy();
+    try {
+      const out = await notifySurfacePushed("brain", {
+        db: h.db,
+        issuer: ISSUER,
+        resolveModuleOrigin: (short) => (short === "surface" ? "http://127.0.0.1:1946" : null),
+        cloneBaseOrigin: ISSUER,
+        fetchImpl: spy.impl,
+        log: { warn() {}, info() {} },
+      });
+      expect(out.notified).toBe(true);
+      expect(spy.calls.length).toBe(1);
+
+      const call = spy.calls[0]!;
+      expect(call.url).toBe("http://127.0.0.1:1946/surface/api/git-pushed");
+      expect(call.init.method).toBe("POST");
+
+      const headers = new Headers(call.init.headers as Record<string, string>);
+      const auth = headers.get("authorization") ?? "";
+      expect(auth.startsWith("Bearer ")).toBe(true);
+
+      // notify-auth bearer validates as surface:admin, aud "surface".
+      const notifyTok = auth.slice("Bearer ".length);
+      const notifyClaims = await validateAccessToken(h.db, notifyTok, [ISSUER]);
+      expect((notifyClaims.payload as { scope?: string }).scope).toBe("surface:admin");
+      expect(notifyClaims.payload.aud).toBe("surface");
+
+      // Body carries the surface name, a loopback clone_url, and a pull token
+      // scoped to exactly surface:brain:read.
+      const body = JSON.parse(String(call.init.body)) as {
+        surface: string;
+        clone_url: string;
+        pull_token: string;
+      };
+      expect(body.surface).toBe("brain");
+      expect(body.clone_url).toBe("http://127.0.0.1:1939/git/brain");
+      const pullClaims = await validateAccessToken(h.db, body.pull_token, [ISSUER]);
+      expect((pullClaims.payload as { scope?: string }).scope).toBe("surface:brain:read");
+      expect(pullClaims.payload.aud).toBe("surface");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("surface-host rejection is reported, never thrown", async () => {
+    const h = makeHarness();
+    const spy = fetchSpy(403, "forbidden");
+    try {
+      const out = await notifySurfacePushed("brain", {
+        db: h.db,
+        issuer: ISSUER,
+        resolveModuleOrigin: () => "http://127.0.0.1:1946",
+        cloneBaseOrigin: ISSUER,
+        fetchImpl: spy.impl,
+        log: { warn() {}, info() {} },
+      });
+      expect(out.notified).toBe(false);
+      expect(out.reason).toBe("notify-rejected:403");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("a fetch throw is swallowed (best-effort)", async () => {
+    const h = makeHarness();
+    const throwing = (() => Promise.reject(new Error("econnrefused"))) as unknown as typeof fetch;
+    try {
+      const out = await notifySurfacePushed("brain", {
+        db: h.db,
+        issuer: ISSUER,
+        resolveModuleOrigin: () => "http://127.0.0.1:1946",
+        cloneBaseOrigin: ISSUER,
+        fetchImpl: throwing,
+        log: { warn() {}, info() {} },
+      });
+      expect(out.notified).toBe(false);
+      expect(out.reason).toBe("notify-error");
+    } finally {
+      h.cleanup();
+    }
+  });
+});

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

@@ -285,6 +285,27 @@ describe("handleGitTransport — auth gate", () => {
     }
   });
 
+  test("onPushed does NOT fire for a fetch (upload-pack) advertisement", async () => {
+    const h = await makeHarness();
+    let pushed = 0;
+    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, { onPushed: () => void pushed++ }),
+      );
+      expect(res.status).toBe(200);
+      await res.text();
+      // Give any (erroneous) background fire a tick to run.
+      await new Promise((r) => setTimeout(r, 50));
+      expect(pushed).toBe(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("write ⊇ read: a write token may also fetch", async () => {
     const h = await makeHarness();
     try {
@@ -389,15 +410,26 @@ async function gitAsync(
 describe("git push round-trip", () => {
   test("an authed push lands the ref in the bare repo + fires post-receive", async () => {
     const h = await makeHarness();
+    // Capture the onPushed deploy hand-off. Wire it through the low-level
+    // handler with a live server so we exercise the true subprocess-exit fire.
+    const pushedNames: string[] = [];
+    let resolvePushed: (name: string) => void = () => {};
+    const pushedOnce = new Promise<string>((r) => {
+      resolvePushed = r;
+    });
     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,
-      }),
+      fetch: (req) =>
+        handleGitTransport(req, {
+          db: h.db,
+          gitRoot: h.gitRoot,
+          knownIssuers: () => [ISSUER],
+          onPushed: (name) => {
+            pushedNames.push(name);
+            resolvePushed(name);
+          },
+        }),
     });
     const work = mkdtempSync(join(tmpdir(), "phub-git-work-"));
     try {
@@ -441,6 +473,16 @@ describe("git push round-trip", () => {
       const logPath = join(bare, "post-receive.log");
       expect(existsSync(logPath)).toBe(true);
       expect(readFileSync(logPath, "utf8")).toContain("refs/heads/main");
+
+      // The deploy hand-off fired with the surface name (the receive-pack
+      // subprocess exited 0). It's observed off the subprocess, which can lag
+      // the client's push return by a tick — await the signal.
+      const pushedName = await Promise.race([
+        pushedOnce,
+        new Promise<string>((_, rej) => setTimeout(() => rej(new Error("onPushed timeout")), 5000)),
+      ]);
+      expect(pushedName).toBe("foo");
+      expect(pushedNames).toEqual(["foo"]);
     } finally {
       server.stop(true);
       rmSync(work, { recursive: true, force: true });

package/src/git-notify.ts

@@ -0,0 +1,176 @@
+/**
+ * Deploy hand-off for the Surface Git Transport (Phase 0b, design doc
+ * 2026-06-30-surface-git-transport.md §5 step 5 + §7).
+ *
+ * After a successful `git push` to `/git/<name>` (receive-pack), the hub
+ * NOTIFIES the surface module over HTTP so it can pull + build + serve the new
+ * source. This is the settled "service-to-service via HTTP, not shell-out"
+ * seam: the `post-receive` hook does NOT build the pushed tree (that would run
+ * attacker-influenceable code as the hub/git user — RCE §7); the exec authority
+ * stays inside surface-host's own sandbox. The hub only sends an authenticated
+ * signal + a short-lived, narrowly-scoped read credential.
+ *
+ * Two hub-minted tokens ride this hand-off (both SHORT-LIVED + UNREGISTERED —
+ * they expire in minutes and are consumed inline, mirroring the H4
+ * credential-delivery provisioning-token pattern in admin-connections.ts):
+ *
+ *   1. notify-auth — a `surface:admin` bearer (aud `surface`) that
+ *      authenticates the hub→surface-host POST. surface-host validates it with
+ *      the SAME `enforceScope(surface:admin)` it uses for the hub's credential
+ *      deliveries, so a random on-box process can't forge a push-notify.
+ *   2. pull-token — a `surface:<name>:read` bearer (aud `surface`) that
+ *      surface-host presents back to THIS hub's `/git/<name>` endpoint to
+ *      `git clone` the freshly-pushed source. Least-privilege: read on exactly
+ *      the one surface, valid only long enough to clone.
+ *
+ * Modular by design (§1): surface-host pulls over the network (not a shared
+ * disk), so the seam already works when hub + surface-host are separate
+ * containers. `clone_url` is the hub's own loopback origin today; a cloud
+ * deploy supplies the internal hub URL instead. The token's `iss` is the hub
+ * issuer, which is a member of the hub's own bound-origin set, so the clone
+ * validates when it comes back in over loopback.
+ */
+import type { Database } from "bun:sqlite";
+import { signAccessToken } from "./jwt-sign.ts";
+
+/** Provenance identity stamped on the hub-internal notify + pull tokens. */
+const NOTIFY_SUBJECT = "surface-git-transport";
+const NOTIFY_CLIENT_ID = "surface-git-transport";
+
+/** aud of both minted tokens — surface-host declares `aud: "surface"`. */
+const SURFACE_AUDIENCE = "surface";
+
+/**
+ * notify-auth TTL. The POST is fired immediately; a small window covers a
+ * momentarily-busy loopback without leaving a usable credential lying around.
+ */
+const NOTIFY_TTL_SECONDS = 120;
+
+/**
+ * pull-token TTL. Long enough for surface-host to `git clone --depth 1` a
+ * source surface right after the notify lands, short enough that a leaked
+ * token is near-useless. Both TTLs here MUST stay well under the hub's
+ * registered-mint threshold (admin-connections REGISTERED_MINT_TTL_THRESHOLD,
+ * 600s) so these fire-and-forget tokens remain unregistered-by-policy — bumping
+ * either past it without registering them would leak unrevocable tokens.
+ */
+const PULL_TTL_SECONDS = 300;
+
+/** Bound the notify HTTP call so a wedged surface-host can't hang the caller. */
+const NOTIFY_FETCH_TIMEOUT_MS = 10_000;
+
+export interface GitNotifyLog {
+  warn: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+}
+
+export interface NotifySurfacePushedDeps {
+  /** Hub DB — for `signAccessToken`'s active-signing-key lookup. */
+  db: Database;
+  /**
+   * Hub issuer (the `iss` claim), resolved per-request via `resolveIssuer`
+   * (`oauthDeps(req).issuer`). Both minted tokens carry it; the pull token
+   * validates against the hub's own bound-origin set on the clone-back.
+   */
+  issuer: string;
+  /**
+   * Resolve a module's loopback origin by short name (`makeResolveModuleOrigin`
+   * over services.json). Returns null when the surface module isn't installed —
+   * in which case there's nothing to notify and we no-op.
+   */
+  resolveModuleOrigin: (short: string) => string | null;
+  /**
+   * Origin surface-host should `git clone` from — the hub's own loopback origin
+   * today (`http://127.0.0.1:<port>`). The `/git/<name>` suffix is appended
+   * here so the module gets a ready-to-use URL.
+   */
+  cloneBaseOrigin: string;
+  fetchImpl?: typeof fetch;
+  now?: () => Date;
+  log?: GitNotifyLog;
+  /** Test seam — defaults to the real `signAccessToken`. */
+  signToken?: typeof signAccessToken;
+}
+
+/**
+ * Notify surface-host that surface `<name>` was pushed. Best-effort +
+ * fire-and-forget from the caller's perspective: this never throws (the git
+ * transport handler already returned the push response to the client); every
+ * failure path logs and returns.
+ *
+ * Returns a small outcome for tests/log assertions; production ignores it.
+ */
+export async function notifySurfacePushed(
+  name: string,
+  deps: NotifySurfacePushedDeps,
+): Promise<{ notified: boolean; reason?: string }> {
+  const log = deps.log ?? console;
+  const sign = deps.signToken ?? signAccessToken;
+
+  const moduleOrigin = deps.resolveModuleOrigin("surface");
+  if (!moduleOrigin) {
+    // No surface module installed on this hub — nothing to serve the push.
+    log.info(`[git-notify] surface module not installed; skipping notify for "${name}"`);
+    return { notified: false, reason: "surface-module-not-installed" };
+  }
+
+  let notifyAuth: string;
+  let pullToken: string;
+  try {
+    const now = deps.now;
+    const common = {
+      sub: NOTIFY_SUBJECT,
+      clientId: NOTIFY_CLIENT_ID,
+      issuer: deps.issuer,
+      audience: SURFACE_AUDIENCE,
+      ...(now !== undefined ? { now } : {}),
+    };
+    notifyAuth = (
+      await sign(deps.db, { ...common, scopes: ["surface:admin"], ttlSeconds: NOTIFY_TTL_SECONDS })
+    ).token;
+    pullToken = (
+      await sign(deps.db, {
+        ...common,
+        scopes: [`surface:${name}:read`],
+        ttlSeconds: PULL_TTL_SECONDS,
+      })
+    ).token;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.warn(`[git-notify] failed to mint notify tokens for "${name}": ${msg}`);
+    return { notified: false, reason: "mint-failed" };
+  }
+
+  const cloneUrl = `${deps.cloneBaseOrigin.replace(/\/+$/, "")}/git/${name}`;
+  const endpoint = `${moduleOrigin.replace(/\/+$/, "")}/surface/api/git-pushed`;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+
+  try {
+    const res = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${notifyAuth}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ surface: name, clone_url: cloneUrl, pull_token: pullToken }),
+      signal: AbortSignal.timeout(NOTIFY_FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+      let detail = `HTTP ${res.status}`;
+      try {
+        const text = (await res.text()).trim();
+        if (text) detail += `: ${text.slice(0, 300)}`;
+      } catch {
+        // best-effort detail
+      }
+      log.warn(`[git-notify] surface-host rejected push notify for "${name}" (${detail})`);
+      return { notified: false, reason: `notify-rejected:${res.status}` };
+    }
+    log.info(`[git-notify] notified surface-host of push to "${name}"`);
+    return { notified: true };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.warn(`[git-notify] push notify to surface-host failed for "${name}": ${msg}`);
+    return { notified: false, reason: "notify-error" };
+  }
+}

package/src/git-transport.ts

@@ -68,6 +68,23 @@ export interface GitTransportDeps {
   knownIssuers: () => readonly string[];
   /** Resolved peer address, surfaced to the backend as REMOTE_ADDR. */
   peerAddr?: string | null;
+  /**
+   * Fired AFTER a `git-receive-pack` POST subprocess exits 0 — i.e. a push
+   * landed (the refs are updated + the post-receive hook has run by the time
+   * `http-backend` exits). The deploy hand-off (design §5 step 5): the hub
+   * notifies surface-host over HTTP + a hub JWT, NEVER a shell-out that builds
+   * the pushed tree (that exec authority belongs to the module's sandbox, not
+   * this substrate). Fire-and-forget + best-effort: a notify failure never
+   * affects the push response the client already received. Keyed off the
+   * subprocess exit, not the streamed response, so it observes the true push
+   * outcome. Phase 0b wires this in hub-server.ts; tests inject a spy.
+   *
+   * Precision note: this fires on every SUCCESSFUL receive-pack, not strictly
+   * per ref-update — a no-op re-push (no new objects) still exits 0 and
+   * notifies. surface-host's re-pull→re-build→re-serve is idempotent, so the
+   * worst case is a redundant rebuild of identical bytes.
+   */
+  onPushed?: (name: string) => void | Promise<void>;
   log?: GitTransportLog;
 }
 
@@ -469,5 +486,30 @@ export async function handleGitTransport(req: Request, deps: GitTransportDeps):
     }
   })();
 
+  // Deploy hand-off (§5 step 5). On a SUCCESSFUL push (receive-pack POST exits
+  // 0 → refs updated, post-receive ran), notify the surface module so it pulls
+  // + builds + serves. Fire-and-forget, observed off the subprocess exit (not
+  // the streamed response), and fully decoupled from the client's response:
+  // a notify error is logged, never surfaced to the pusher. The hub NEVER
+  // builds here — `onPushed` only sends an authenticated HTTP notify.
+  if (access === "write" && gitSubpath === "git-receive-pack" && deps.onPushed) {
+    const onPushed = deps.onPushed;
+    void (async () => {
+      let code: number;
+      try {
+        code = await proc.exited;
+      } catch {
+        return; // subprocess vanished — nothing to notify about
+      }
+      if (code !== 0) return;
+      try {
+        await onPushed(name);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.warn(`[git-transport] post-push notify failed for "${name}": ${msg}`);
+      }
+    })();
+  }
+
   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 { notifySurfacePushed } from "./git-notify.ts";
 import { handleGitTransport } from "./git-transport.ts";
 import { HUB_DEFAULT_PORT, HUB_SVC, clearHubPort, writeHubPort } from "./hub-control.ts";
 import {
@@ -3819,11 +3820,26 @@ export function hubFetch(
       // sandboxed job, Phase 0b). See src/git-transport.ts.
       if (pathname.startsWith("/git/")) {
         if (!getDb) return new Response("not found", { status: 404 });
+        const db = getDb();
+        const issuer = oauthDeps(req).issuer;
         return handleGitTransport(req, {
-          db: getDb(),
+          db,
           gitRoot,
           knownIssuers: () => oauthDeps(req).hubBoundOrigins(),
           peerAddr,
+          // 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
+          // only sends the authenticated signal (git-notify.ts). Fire-and-
+          // forget; a notify failure is logged, never surfaced to the pusher.
+          onPushed: async (name) => {
+            await notifySurfacePushed(name, {
+              db,
+              issuer: issuer ?? `http://127.0.0.1:${loopbackPort ?? 1939}`,
+              resolveModuleOrigin: makeResolveModuleOrigin(manifestPath),
+              cloneBaseOrigin: `http://127.0.0.1:${loopbackPort ?? 1939}`,
+            });
+          },
         });
       }