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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.5-rc.1",
+  "version": "0.7.5-rc.3",
   "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__/admin-surfaces.test.ts

@@ -0,0 +1,207 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { routeAdminSurfaces } from "../admin-surfaces.ts";
+import { isSurfaceRegistered, repoDirFor } from "../git-registry.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { signAccessToken } from "../jwt-sign.ts";
+import { rotateSigningKey } from "../signing-keys.ts";
+import { createUser } from "../users.ts";
+
+const ISSUER = "http://127.0.0.1:1939";
+
+interface Harness {
+  gitRoot: string;
+  db: ReturnType<typeof openHubDb>;
+  userId: string;
+  cleanup: () => void;
+}
+
+async function makeHarness(): Promise<Harness> {
+  const dir = mkdtempSync(join(tmpdir(), "phub-adminsurf-"));
+  const db = openHubDb(hubDbPath(dir));
+  rotateSigningKey(db);
+  const u = await createUser(db, "owner", "pw");
+  return {
+    gitRoot: join(dir, "git"),
+    db,
+    userId: u.id,
+    cleanup: () => {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+async function mint(h: Harness, scopes: string[]): Promise<string> {
+  const { token } = await signAccessToken(h.db, {
+    sub: h.userId,
+    scopes,
+    audience: "operator",
+    clientId: "test-operator",
+    issuer: ISSUER,
+  });
+  return token;
+}
+
+function deps(h: Harness) {
+  return { db: h.db, gitRoot: h.gitRoot, issuer: ISSUER, knownIssuers: [ISSUER] };
+}
+
+function req(method: string, headers?: Record<string, string>, body?: unknown): Request {
+  return new Request("http://127.0.0.1/admin/surfaces", {
+    method,
+    headers,
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  });
+}
+
+describe("routeAdminSurfaces — routing", () => {
+  test("returns null for a non-/admin/surfaces path", async () => {
+    const h = await makeHarness();
+    try {
+      const res = await routeAdminSurfaces(new Request("http://127.0.0.1/admin/other"), deps(h));
+      expect(res).toBeNull();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("405 on an unsupported method", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["parachute:host:admin"]);
+      const res = await routeAdminSurfaces(
+        req("DELETE", { authorization: `Bearer ${token}` }),
+        deps(h),
+      );
+      expect(res?.status).toBe(405);
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("routeAdminSurfaces — auth", () => {
+  test("401 without a bearer", async () => {
+    const h = await makeHarness();
+    try {
+      const res = await routeAdminSurfaces(req("POST", {}, { name: "foo" }), deps(h));
+      expect(res?.status).toBe(401);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("403 when the token lacks parachute:host:admin", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["surface:foo:write"]);
+      const res = await routeAdminSurfaces(
+        req("POST", { authorization: `Bearer ${token}` }, { name: "foo" }),
+        deps(h),
+      );
+      expect(res?.status).toBe(403);
+      // No provisioning happened on a rejected auth.
+      expect(existsSync(repoDirFor(h.gitRoot, "foo"))).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("401 on a garbage token", async () => {
+    const h = await makeHarness();
+    try {
+      const res = await routeAdminSurfaces(
+        req("POST", { authorization: "Bearer not-a-jwt" }, { name: "foo" }),
+        deps(h),
+      );
+      expect(res?.status).toBe(401);
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("routeAdminSurfaces — register + list", () => {
+  test("POST registers a surface (provisions the repo + returns the entry)", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["parachute:host:admin"]);
+      const res = await routeAdminSurfaces(
+        req(
+          "POST",
+          { authorization: `Bearer ${token}`, "content-type": "application/json" },
+          { name: "brain", mount: "/surface/brain", mode: "prod" },
+        ),
+        deps(h),
+      );
+      expect(res?.status).toBe(200);
+      const body = (await res?.json()) as {
+        ok: boolean;
+        surface: { name: string; mount?: string };
+      };
+      expect(body.ok).toBe(true);
+      expect(body.surface.name).toBe("brain");
+      expect(body.surface.mount).toBe("/surface/brain");
+      expect(isSurfaceRegistered(h.gitRoot, "brain")).toBe(true);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("POST with a missing name → 400", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["parachute:host:admin"]);
+      const res = await routeAdminSurfaces(
+        req("POST", { authorization: `Bearer ${token}` }, { mount: "/surface/x" }),
+        deps(h),
+      );
+      expect(res?.status).toBe(400);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("POST with an invalid name → 400 (no repo provisioned)", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["parachute:host:admin"]);
+      const res = await routeAdminSurfaces(
+        req("POST", { authorization: `Bearer ${token}` }, { name: "a/b" }),
+        deps(h),
+      );
+      expect(res?.status).toBe(400);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("GET lists registered surfaces", async () => {
+    const h = await makeHarness();
+    try {
+      const token = await mint(h, ["parachute:host:admin"]);
+      await routeAdminSurfaces(
+        req("POST", { authorization: `Bearer ${token}` }, { name: "alpha" }),
+        deps(h),
+      );
+      await routeAdminSurfaces(
+        req("POST", { authorization: `Bearer ${token}` }, { name: "zeta" }),
+        deps(h),
+      );
+      const res = await routeAdminSurfaces(
+        new Request("http://127.0.0.1/admin/surfaces", {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+        deps(h),
+      );
+      expect(res?.status).toBe(200);
+      const body = (await res?.json()) as { surfaces: Array<{ name: string }> };
+      expect(body.surfaces.map((s) => s.name)).toEqual(["alpha", "zeta"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+});

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-registry.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  ensureSurfaceRepo,
+  isSurfaceRegistered,
+  listSurfaces,
+  loadRegistry,
+  registerSurface,
+  registryPath,
+  repoDirFor,
+} from "../git-registry.ts";
+
+function tmpGitRoot(): { gitRoot: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), "phub-registry-"));
+  const gitRoot = join(dir, "git");
+  return { gitRoot, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+describe("loadRegistry", () => {
+  test("missing file → empty registry", () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      expect(loadRegistry(gitRoot)).toEqual({ version: 1, surfaces: {} });
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("corrupt JSON → empty registry (never throws)", () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      mkdirSync(gitRoot, { recursive: true });
+      writeFileSync(registryPath(gitRoot), "{ not json");
+      expect(loadRegistry(gitRoot)).toEqual({ version: 1, surfaces: {} });
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("ensureSurfaceRepo", () => {
+  test("provisions a bare repo with http.receivepack=true + post-receive hook", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      const repoDir = await ensureSurfaceRepo(gitRoot, "foo");
+      expect(repoDir).toBe(repoDirFor(gitRoot, "foo"));
+      expect(existsSync(repoDir)).toBe(true);
+      expect(existsSync(join(repoDir, "hooks", "post-receive"))).toBe(true);
+      const rp = spawnSync("git", ["-C", repoDir, "config", "http.receivepack"], {
+        encoding: "utf8",
+      });
+      expect(rp.stdout.trim()).toBe("true");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("idempotent — a second call is a no-op that returns the same path", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      const a = await ensureSurfaceRepo(gitRoot, "foo");
+      const b = await ensureSurfaceRepo(gitRoot, "foo");
+      expect(a).toBe(b);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("rejects an invalid surface name", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      await expect(ensureSurfaceRepo(gitRoot, "../evil")).rejects.toThrow();
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("registerSurface", () => {
+  test("provisions the repo + records the entry", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      const entry = await registerSurface(gitRoot, "brain", {
+        mount: "/surface/brain",
+        mode: "prod",
+      });
+      expect(entry.name).toBe("brain");
+      expect(entry.mount).toBe("/surface/brain");
+      expect(entry.mode).toBe("prod");
+      expect(existsSync(repoDirFor(gitRoot, "brain"))).toBe(true);
+      expect(loadRegistry(gitRoot).surfaces.brain?.name).toBe("brain");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("idempotent re-register preserves the original registeredAt", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      const first = await registerSurface(gitRoot, "brain", {
+        now: () => new Date("2026-01-01T00:00:00Z"),
+      });
+      const second = await registerSurface(gitRoot, "brain", {
+        mount: "/surface/brain",
+        now: () => new Date("2026-02-02T00:00:00Z"),
+      });
+      expect(second.registeredAt).toBe(first.registeredAt);
+      expect(second.registeredAt).toBe("2026-01-01T00:00:00.000Z");
+      // Later metadata still applies.
+      expect(second.mount).toBe("/surface/brain");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("rejects an invalid name without provisioning", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      await expect(registerSurface(gitRoot, "a/b")).rejects.toThrow(/invalid surface name/);
+      expect(existsSync(registryPath(gitRoot))).toBe(false);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("isSurfaceRegistered", () => {
+  test("false for an unknown name, true after register", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      expect(isSurfaceRegistered(gitRoot, "foo")).toBe(false);
+      await registerSurface(gitRoot, "foo");
+      expect(isSurfaceRegistered(gitRoot, "foo")).toBe(true);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("grandfathers a bare repo that exists on disk without a registry entry", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      await ensureSurfaceRepo(gitRoot, "legacy");
+      // No registry.json entry, but the repo exists → still registered.
+      expect(existsSync(registryPath(gitRoot))).toBe(false);
+      expect(isSurfaceRegistered(gitRoot, "legacy")).toBe(true);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("false for a name that fails the charset (never touches the filesystem)", () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      expect(isSurfaceRegistered(gitRoot, "../etc")).toBe(false);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("listSurfaces", () => {
+  test("returns entries sorted by name", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      await registerSurface(gitRoot, "zeta");
+      await registerSurface(gitRoot, "alpha");
+      await registerSurface(gitRoot, "mid");
+      expect(listSurfaces(gitRoot).map((s) => s.name)).toEqual(["alpha", "mid", "zeta"]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("excludes a grandfathered disk-only repo (registry entries only)", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      await registerSurface(gitRoot, "registered");
+      await ensureSurfaceRepo(gitRoot, "grandfathered"); // repo exists, no entry
+      // isSurfaceRegistered grandfathers it (pushable), but listSurfaces does not.
+      expect(isSurfaceRegistered(gitRoot, "grandfathered")).toBe(true);
+      expect(listSurfaces(gitRoot).map((s) => s.name)).toEqual(["registered"]);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("saveRegistry atomicity", () => {
+  test("registry.json is written pretty + reloadable", async () => {
+    const { gitRoot, cleanup } = tmpGitRoot();
+    try {
+      await registerSurface(gitRoot, "foo");
+      const raw = readFileSync(registryPath(gitRoot), "utf8");
+      expect(raw.endsWith("\n")).toBe(true);
+      expect(JSON.parse(raw).surfaces.foo.name).toBe("foo");
+    } finally {
+      cleanup();
+    }
+  });
+});