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

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

@@ -3,6 +3,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { ensureSurfaceRepo, isSurfaceRegistered, registerSurface } from "../git-registry.ts";
 import {
   type GitTransportDeps,
   extractToken,
@@ -61,6 +62,11 @@ function deps(h: Harness, extra?: Partial<GitTransportDeps>): GitTransportDeps {
     db: h.db,
     gitRoot: h.gitRoot,
     knownIssuers: () => [ISSUER],
+    // Default: treat every name as declared + provision on demand (the Phase-0a
+    // "feel it" behavior). The declaration-gate tests below override `isDeclared`
+    // or use the real registry.
+    isDeclared: () => true,
+    ensureRepo: (name) => ensureSurfaceRepo(h.gitRoot, name),
     ...extra,
   };
 }
@@ -285,6 +291,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 {
@@ -321,6 +348,176 @@ describe("handleGitTransport — auth gate", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Declaration gate (Phase 1) — provision/serve only a REGISTERED surface
+// ---------------------------------------------------------------------------
+
+describe("handleGitTransport — declaration gate", () => {
+  /** Deps wired to the REAL registry (isSurfaceRegistered + ensureSurfaceRepo). */
+  function regDeps(h: Harness): GitTransportDeps {
+    return deps(h, {
+      isDeclared: (name) => isSurfaceRegistered(h.gitRoot, name),
+      ensureRepo: (name) => ensureSurfaceRepo(h.gitRoot, name),
+    });
+  }
+
+  test("404 for an authed write to an UNdeclared surface (no auto-provision)", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["surface:foo:write"]);
+      const res = await handleGitTransport(
+        gitReq("/git/foo/info/refs?service=git-receive-pack", {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+        regDeps(h),
+      );
+      // A valid write token for an undeclared name is NOT enough — the registry
+      // gate 404s (indistinguishable from a bad path) and nothing is provisioned.
+      expect(res.status).toBe(404);
+      expect(existsSync(join(h.gitRoot, "foo.git"))).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("a declared (registered) surface serves the push advertisement", async () => {
+    const h = await makeHarness();
+    try {
+      // Lifecycle: surface-host registers the discovered `#surface` first.
+      await registerSurface(h.gitRoot, "foo");
+      expect(existsSync(join(h.gitRoot, "foo.git"))).toBe(true);
+      const token = await mint(h, ["surface:foo:write"]);
+      const res = await handleGitTransport(
+        gitReq("/git/foo/info/refs?service=git-receive-pack", {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+        regDeps(h),
+      );
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toContain("git-receive-pack-advertisement");
+      await res.text();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("grandfathering: an already-provisioned bare repo counts as declared", async () => {
+    const h = await makeHarness();
+    try {
+      // A Phase-0a repo that exists on disk but has no registry.json entry.
+      await ensureSurfaceRepo(h.gitRoot, "legacy");
+      expect(isSurfaceRegistered(h.gitRoot, "legacy")).toBe(true);
+      const token = await mint(h, ["surface:legacy:read"]);
+      const res = await handleGitTransport(
+        gitReq("/git/legacy/info/refs?service=git-upload-pack", {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+        regDeps(h),
+      );
+      expect(res.status).toBe(200);
+      await res.text();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("gate runs AFTER auth: no token on an undeclared name still 401 (not 404)", async () => {
+    const h = await makeHarness();
+    try {
+      const res = await handleGitTransport(
+        gitReq("/git/foo/info/refs?service=git-upload-pack"),
+        regDeps(h),
+      );
+      // 401 (not 404) — an unauthenticated probe never learns registry membership.
+      expect(res.status).toBe(401);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("gate runs AFTER scope: wrong-surface token on an undeclared name is 403 (not 404)", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["surface:other:write"]);
+      const res = await handleGitTransport(
+        gitReq("/git/foo/info/refs?service=git-receive-pack", {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+        regDeps(h),
+      );
+      // 403 (scope) before 404 (registry) — a valid-but-wrong token never learns
+      // membership either.
+      expect(res.status).toBe(403);
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Direct transfer POST (no prior info/refs GET) — auth enforced at BOTH points
+// ---------------------------------------------------------------------------
+
+describe("handleGitTransport — direct transfer POST", () => {
+  test("401 on a direct POST to git-receive-pack with no credential", async () => {
+    const h = await makeHarness();
+    try {
+      const res = await handleGitTransport(
+        gitReq("/git/foo/git-receive-pack", {
+          method: "POST",
+          headers: { "content-type": "application/x-git-receive-pack-request" },
+        }),
+        deps(h),
+      );
+      // A client that skips the info/refs GET is still gated at the POST.
+      expect(res.status).toBe(401);
+      expect(res.headers.get("www-authenticate") ?? "").toContain("Bearer");
+      expect(existsSync(join(h.gitRoot, "foo.git"))).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("403 on a direct POST to git-receive-pack with only read scope", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["surface:foo:read"]);
+      const res = await handleGitTransport(
+        gitReq("/git/foo/git-receive-pack", {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${token}`,
+            "content-type": "application/x-git-receive-pack-request",
+          },
+        }),
+        deps(h),
+      );
+      // receive-pack requires write; a read token is refused at the POST itself.
+      expect(res.status).toBe(403);
+      expect(existsSync(join(h.gitRoot, "foo.git"))).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("401 on a direct POST to git-upload-pack with no credential", async () => {
+    const h = await makeHarness();
+    try {
+      const res = await handleGitTransport(
+        gitReq("/git/foo/git-upload-pack", {
+          method: "POST",
+          headers: { "content-type": "application/x-git-upload-pack-request" },
+        }),
+        deps(h),
+      );
+      expect(res.status).toBe(401);
+      expect(res.headers.get("www-authenticate") ?? "").toContain("Bearer");
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Dispatch wiring through hubFetch
 // ---------------------------------------------------------------------------
@@ -389,19 +586,35 @@ 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],
+          isDeclared: (name) => isSurfaceRegistered(h.gitRoot, name),
+          ensureRepo: (name) => ensureSurfaceRepo(h.gitRoot, name),
+          onPushed: (name) => {
+            pushedNames.push(name);
+            resolvePushed(name);
+          },
+        }),
     });
     const work = mkdtempSync(join(tmpdir(), "phub-git-work-"));
     try {
       const token = await mint(h, ["surface:foo:write"]);
+      // Declare the surface first (the Phase-1 lifecycle: surface-host registers
+      // a discovered `#surface` note before the push) — provisions the bare repo.
+      await registerSurface(h.gitRoot, "foo");
       const base = `http://127.0.0.1:${server.port}`;
 
       // Author a commit in a throwaway working repo.
@@ -441,6 +654,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/__tests__/scope-explanations.test.ts

@@ -93,6 +93,22 @@ describe("explainScope", () => {
     expect(explainScope("vault:my-techne_2:admin")?.level).toBe("admin");
     expect(explainScope("vault:*:admin")?.level).toBe("admin");
   });
+
+  // Surface Git Transport Phase 1: named per-surface scopes
+  // (`surface:<name>:<verb>`) reach the consent screen via the 3→2-segment
+  // collapse, so explainScope MUST resolve them to the unnamed surface:read /
+  // surface:write labels — else the operator sees the raw scope string.
+  test("named surface scopes (surface:<name>:<verb>) reuse the unnamed-verb explanation", () => {
+    expect(explainScope("surface:gitcoin-brain:read")?.label).toBe(
+      SCOPE_EXPLANATIONS["surface:read"]?.label,
+    );
+    expect(explainScope("surface:gitcoin-brain:read")?.level).toBe("read");
+    expect(explainScope("surface:my-app_2:write")?.label).toBe(
+      SCOPE_EXPLANATIONS["surface:write"]?.label,
+    );
+    expect(explainScope("surface:my-app_2:write")?.level).toBe("write");
+    expect(explainScope("surface:*:write")?.level).toBe("write");
+  });
 });
 
 describe("scopeIsAdmin", () => {

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-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" };
+  }
+}