@openparachute/hub 0.5.2 → 0.5.9-rc.6

package/src/__tests__/setup.test.ts

@@ -115,18 +115,21 @@ describe("setup", () => {
     const h = makeHarness();
     try {
       // Pre-seed every first-party shortname so survey returns all-installed.
-      for (const m of [
-        "parachute-vault",
-        "parachute-notes",
-        "parachute-scribe",
-        "parachute-channel",
-      ]) {
+      // Distinct canonical ports per service — services-manifest.ts now
+      // rejects duplicate ports between distinct services (hub#195).
+      const seeds: Array<{ name: string; port: number }> = [
+        { name: "parachute-vault", port: 1940 },
+        { name: "parachute-notes", port: 1942 },
+        { name: "parachute-scribe", port: 1943 },
+        { name: "parachute-channel", port: 1941 },
+      ];
+      for (const s of seeds) {
         upsertService(
           {
-            name: m,
+            name: s.name,
             version: "0.0.0",
-            port: 1940,
-            paths: [`/${m.replace(/^parachute-/, "")}`],
+            port: s.port,
+            paths: [`/${s.name.replace(/^parachute-/, "")}`],
             health: "/health",
           },
           h.manifestPath,

package/src/__tests__/status.test.ts

@@ -317,6 +317,179 @@ describe("status", () => {
     }
   });
 
+  // Canonical-port drift warning (hub#195). When a known service ends up at
+  // a non-canonical port (because of an upgrade rewrite, a port-walk fallback,
+  // or an operator edit), surface it in `parachute status` so a silent miswire
+  // is operator-visible. Warning, not error — operators may have moved the
+  // service deliberately to dodge a third-party clash.
+  describe("canonical-port drift warning", () => {
+    test("warns when scribe is at non-canonical port (1944 instead of 1943)", async () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "parachute-scribe",
+            port: 1944,
+            paths: ["/scribe"],
+            health: "/scribe/health",
+            version: "0.4.0",
+          },
+          path,
+        );
+        const lines: string[] = [];
+        await status({
+          manifestPath: path,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: (l) => lines.push(l),
+        });
+        expect(lines.some((l) => l.includes("canonical port is 1943"))).toBe(true);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("does not warn when service is on its canonical port", async () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "parachute-scribe",
+            port: 1943,
+            paths: ["/scribe"],
+            health: "/scribe/health",
+            version: "0.4.0",
+          },
+          path,
+        );
+        const lines: string[] = [];
+        await status({
+          manifestPath: path,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: (l) => lines.push(l),
+        });
+        expect(lines.some((l) => l.includes("canonical port"))).toBe(false);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("does not warn for third-party services with no canonical port", async () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "third-party-thing",
+            port: 9000,
+            paths: ["/widget"],
+            health: "/health",
+            version: "1.0.0",
+          },
+          path,
+        );
+        const lines: string[] = [];
+        await status({
+          manifestPath: path,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: (l) => lines.push(l),
+        });
+        expect(lines.some((l) => l.includes("canonical port"))).toBe(false);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("warning does not affect exit code (status stays 0 when healthy)", async () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "parachute-scribe",
+            port: 1944,
+            paths: ["/scribe"],
+            health: "/scribe/health",
+            version: "0.4.0",
+          },
+          path,
+        );
+        const code = await status({
+          manifestPath: path,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: () => {},
+        });
+        // Drift is informational. A healthy probed service still returns 0
+        // even when the port has drifted off canonical.
+        expect(code).toBe(0);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("warning still fires when service is stopped (probe skipped)", async () => {
+      const { path, configDir, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "parachute-scribe",
+            port: 1944,
+            paths: ["/scribe"],
+            health: "/scribe/health",
+            version: "0.4.0",
+          },
+          path,
+        );
+        writePid("scribe", 4242, configDir);
+        const lines: string[] = [];
+        await status({
+          manifestPath: path,
+          configDir,
+          alive: () => false,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: (l) => lines.push(l),
+        });
+        // Drift is computed from services.json, not from the probe — a
+        // stopped service with a drifted port should still surface the
+        // warning so operators see the miswire even before they start it.
+        expect(lines.some((l) => l.includes("canonical port is 1943"))).toBe(true);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("multi-vault instance rows do not surface a drift warning (intentional gap)", async () => {
+      // Pinning the documented gap: `parachute-vault-default` is not
+      // a canonical manifest name in FIRST_PARTY_FALLBACKS, so
+      // `canonicalPortForManifest` returns undefined and no drift
+      // warning fires — even when the row's port differs from the
+      // canonical `parachute-vault` port (1940). Rationale lives on
+      // `canonicalPortForManifest` in service-spec.ts; this test pins
+      // the behavior so a future change to the lookup shape doesn't
+      // accidentally start emitting drift on every multi-vault row
+      // without an explicit decision.
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "parachute-vault-default",
+            port: 1944,
+            paths: ["/vault/default"],
+            health: "/vault/default/health",
+            version: "0.2.4",
+          },
+          path,
+        );
+        const lines: string[] = [];
+        await status({
+          manifestPath: path,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: (l) => lines.push(l),
+        });
+        expect(lines.some((l) => l.includes("canonical port"))).toBe(false);
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
   test("stopped services still render a URL line so the user knows where to point clients post-start", async () => {
     const { path, configDir, cleanup } = makeTempPath();
     try {
@@ -344,4 +517,203 @@ describe("status", () => {
       cleanup();
     }
   });
+
+  describe("install-source surface (hub#243)", () => {
+    test("renders SOURCE column header + per-row label", async () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "parachute-vault",
+            port: 1940,
+            paths: ["/vault/default"],
+            health: "/vault/default/health",
+            version: "0.4.4-rc.3",
+            installDir: "/Users/me/code/parachute-vault",
+          },
+          path,
+        );
+        const lines: string[] = [];
+        await status({
+          manifestPath: path,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: (l) => lines.push(l),
+          installSourceDeps: {
+            bunGlobalPrefixes: () => ["/home/test/.bun/install/global/node_modules"],
+            resolveBunGlobal: () => null,
+            readJson: (p) =>
+              p === "/Users/me/code/parachute-vault/package.json"
+                ? { name: "@openparachute/vault", version: "0.4.4-rc.3" }
+                : (() => {
+                    throw new Error("nope");
+                  })(),
+            readGitHead: () => "8aa167b",
+          },
+        });
+        expect(lines[0]).toMatch(/SOURCE/);
+        expect(lines.some((l) => l.includes("bun-linked → parachute-vault @ 8aa167b"))).toBe(true);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("STALE continuation line fires when bun-linked live version != cached version", async () => {
+      // Reproduces hub#243's motivating case: services.json says 0.3.11-rc.1
+      // but the live source has been rebuilt to 0.3.15-rc.1. Operator should
+      // see STALE in one glance from `parachute status` output.
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "parachute-notes",
+            port: 1942,
+            paths: ["/notes"],
+            health: "/notes/health",
+            version: "0.3.11-rc.1",
+            installDir: "/Users/me/code/parachute-notes",
+          },
+          path,
+        );
+        const lines: string[] = [];
+        await status({
+          manifestPath: path,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: (l) => lines.push(l),
+          installSourceDeps: {
+            bunGlobalPrefixes: () => ["/home/test/.bun/install/global/node_modules"],
+            resolveBunGlobal: () => null,
+            readJson: (p) =>
+              p === "/Users/me/code/parachute-notes/package.json"
+                ? { name: "@openparachute/notes", version: "0.3.15-rc.1" }
+                : (() => {
+                    throw new Error("nope");
+                  })(),
+            readGitHead: () => "051c404",
+          },
+        });
+        expect(
+          lines.some((l) =>
+            l.includes("STALE: services.json cached 0.3.11-rc.1; live package.json 0.3.15-rc.1"),
+          ),
+        ).toBe(true);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("npm-installed services render as `npm (<version>)` and never STALE", async () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "parachute-scribe",
+            port: 1943,
+            paths: ["/scribe"],
+            health: "/scribe/health",
+            version: "0.4.2-rc.1",
+            installDir: "/home/test/.bun/install/global/node_modules/@openparachute/scribe",
+          },
+          path,
+        );
+        const lines: string[] = [];
+        await status({
+          manifestPath: path,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: (l) => lines.push(l),
+          installSourceDeps: {
+            bunGlobalPrefixes: () => ["/home/test/.bun/install/global/node_modules"],
+            resolveBunGlobal: () => null,
+            readJson: (p) =>
+              p === "/home/test/.bun/install/global/node_modules/@openparachute/scribe/package.json"
+                ? { name: "@openparachute/scribe", version: "0.4.2-rc.1" }
+                : (() => {
+                    throw new Error("nope");
+                  })(),
+            readGitHead: () => undefined,
+          },
+        });
+        expect(lines.some((l) => l.includes("npm (0.4.2-rc.1)"))).toBe(true);
+        expect(lines.some((l) => l.includes("STALE:"))).toBe(false);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("entries without installDir fall back to bun-global symlink lookup", async () => {
+      // Some services.json entries (older first-party rows, or rows written
+      // by a service that doesn't echo installDir) leave the field absent.
+      // detectInstallSource maps the entry name → first-party package and
+      // probes bun globals for the symlink. Pins that fallback path.
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "parachute-vault",
+            port: 1940,
+            paths: ["/vault/default"],
+            health: "/vault/default/health",
+            version: "0.4.4-rc.3",
+            // No installDir.
+          },
+          path,
+        );
+        const lines: string[] = [];
+        await status({
+          manifestPath: path,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: (l) => lines.push(l),
+          installSourceDeps: {
+            bunGlobalPrefixes: () => ["/home/test/.bun/install/global/node_modules"],
+            resolveBunGlobal: (pkg) =>
+              pkg === "@openparachute/vault" ? "/Users/me/code/parachute-vault" : null,
+            readJson: (p) =>
+              p === "/Users/me/code/parachute-vault/package.json"
+                ? { name: "@openparachute/vault", version: "0.4.4-rc.3" }
+                : (() => {
+                    throw new Error("nope");
+                  })(),
+            readGitHead: () => "8aa167b",
+          },
+        });
+        expect(lines.some((l) => l.includes("bun-linked → parachute-vault @ 8aa167b"))).toBe(true);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("third-party row without installDir + no mapping renders as 'unknown'", async () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "agent",
+            port: 1946,
+            paths: ["/agent"],
+            health: "/agent/health",
+            version: "0.1.4-rc.1",
+            // No installDir; agent isn't in FIRST_PARTY_FALLBACKS by short name,
+            // and the fallback bun-global lookup needs a known package name.
+          },
+          path,
+        );
+        const lines: string[] = [];
+        await status({
+          manifestPath: path,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: (l) => lines.push(l),
+          installSourceDeps: {
+            bunGlobalPrefixes: () => ["/home/test/.bun/install/global/node_modules"],
+            resolveBunGlobal: () => null,
+            readJson: () => {
+              throw new Error("not reached");
+            },
+            readGitHead: () => undefined,
+          },
+        });
+        expect(lines.some((l) => l.includes("unknown"))).toBe(true);
+      } finally {
+        cleanup();
+      }
+    });
+  });
 });

package/src/__tests__/well-known.test.ts

@@ -302,6 +302,75 @@ describe("buildWellKnown", () => {
     expect(doc.notes).toEqual([{ url: "https://x.example/notes", version: "0.0.1" }]);
   });
 
+  // Phase D consumer-side: services entries surface uiUrl + displayName +
+  // tagline so the discovery page can render data-driven Service tiles.
+  test("uiUrl resolver result rides into doc.services entry as absolute URL", () => {
+    const doc = buildWellKnown({
+      services: [notes],
+      canonicalOrigin: "https://x.example",
+      uiUrlFor: () => "/notes",
+    });
+    const svc = doc.services.find((s) => s.name === "parachute-notes");
+    expect(svc?.uiUrl).toBe("https://x.example/notes");
+  });
+
+  test("uiUrl absolute URL passes through verbatim", () => {
+    const doc = buildWellKnown({
+      services: [notes],
+      canonicalOrigin: "https://x.example",
+      uiUrlFor: () => "https://notes.example.com/app",
+    });
+    const svc = doc.services.find((s) => s.name === "parachute-notes");
+    expect(svc?.uiUrl).toBe("https://notes.example.com/app");
+  });
+
+  test("uiUrl absent when the resolver returns undefined (vault case)", () => {
+    const doc = buildWellKnown({
+      services: [vault, notes],
+      canonicalOrigin: "https://x.example",
+      uiUrlFor: (e) => (e.name === "parachute-notes" ? "/notes" : undefined),
+    });
+    const vaultSvc = doc.services.find((s) => s.name === "parachute-vault");
+    const notesSvc = doc.services.find((s) => s.name === "parachute-notes");
+    expect(vaultSvc).not.toHaveProperty("uiUrl");
+    expect(notesSvc?.uiUrl).toBe("https://x.example/notes");
+  });
+
+  test("displayName resolver overrides services.json displayName", () => {
+    const notesWithName: ServiceEntry = { ...notes, displayName: "FromServicesJson" };
+    const doc = buildWellKnown({
+      services: [notesWithName],
+      canonicalOrigin: "https://x.example",
+      displayNameFor: () => "FromModuleJson",
+    });
+    const svc = doc.services.find((s) => s.name === "parachute-notes");
+    expect(svc?.displayName).toBe("FromModuleJson");
+  });
+
+  test("displayName falls back to services.json when resolver returns undefined", () => {
+    const notesWithName: ServiceEntry = { ...notes, displayName: "FromServicesJson" };
+    const doc = buildWellKnown({
+      services: [notesWithName],
+      canonicalOrigin: "https://x.example",
+      displayNameFor: () => undefined,
+    });
+    const svc = doc.services.find((s) => s.name === "parachute-notes");
+    expect(svc?.displayName).toBe("FromServicesJson");
+  });
+
+  test("tagline rides through from services.json (no resolver needed)", () => {
+    const notesWithTagline: ServiceEntry = {
+      ...notes,
+      tagline: "Notes PWA backed by your vault.",
+    };
+    const doc = buildWellKnown({
+      services: [notesWithTagline],
+      canonicalOrigin: "https://x.example",
+    });
+    const svc = doc.services.find((s) => s.name === "parachute-notes");
+    expect(svc?.tagline).toBe("Notes PWA backed by your vault.");
+  });
+
   test("falls back to / for empty paths", () => {
     const entry: ServiceEntry = { ...vault, paths: [] };
     const doc = buildWellKnown({

package/src/admin-clients.ts

@@ -0,0 +1,139 @@
+/**
+ * Admin endpoints for OAuth client lookup + approval. Standalone surface so
+ * the hub's SPA approve-client page can deep-link to "approve this client_id"
+ * without round-tripping through the `/oauth/authorize` flow (whose
+ * `POST /oauth/authorize/approve` requires a `return_to` authorize URL).
+ *
+ *   GET  /api/oauth/clients/<client_id>            client details
+ *   POST /api/oauth/clients/<client_id>/approve    flip status to approved
+ *
+ * Both gated by `parachute:host:admin` Bearer (same shape as /api/grants,
+ * /api/auth/tokens, etc.). The SPA mints one via the session cookie at
+ * `/admin/host-admin-token`.
+ *
+ * Audit: approval emits a `console.log("client approved: ...")` line in the
+ * same `key=value` shape used elsewhere (`grant revoked`, `consent skipped`).
+ * `parachute auth approve-client` writes to the same `approveClient` db
+ * helper but no audit line — adding one to the CLI is a separate cleanup;
+ * the API path logs because cross-machine "who approved this" is the
+ * audit-grade signal we'd want when the operator approves from a browser
+ * rather than a terminal they own.
+ */
+import type { Database } from "bun:sqlite";
+import {
+  type AdminAuthContext,
+  type AdminAuthError,
+  adminAuthErrorResponse,
+  requireScope,
+} from "./admin-auth.ts";
+import { HOST_ADMIN_SCOPE } from "./admin-vaults.ts";
+import { approveClient, getClient } from "./clients.ts";
+
+export interface AdminClientsDeps {
+  db: Database;
+  /** Hub origin — passed through to JWT validation as the expected `iss`. */
+  issuer: string;
+}
+
+export interface AdminClientView {
+  client_id: string;
+  /** May be null when the client never declared a `client_name` on /oauth/register. */
+  client_name: string | null;
+  redirect_uris: string[];
+  /** Scopes the client requested at registration. The operator approves the client, not these. */
+  scopes: string[];
+  status: "pending" | "approved";
+  registered_at: string;
+}
+
+export async function handleGetClient(
+  req: Request,
+  clientId: string,
+  deps: AdminClientsDeps,
+): Promise<Response> {
+  if (req.method !== "GET") {
+    return jsonError(405, "method_not_allowed", "use GET");
+  }
+  try {
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+  } catch (err) {
+    return adminAuthErrorResponse(err as AdminAuthError);
+  }
+  const client = getClient(deps.db, clientId);
+  if (!client) {
+    return jsonError(404, "not_found", `no client registered with id ${clientId}`);
+  }
+  const view: AdminClientView = {
+    client_id: client.clientId,
+    client_name: client.clientName,
+    redirect_uris: client.redirectUris,
+    scopes: client.scopes,
+    status: client.status,
+    registered_at: client.registeredAt,
+  };
+  return new Response(JSON.stringify(view), {
+    status: 200,
+    headers: {
+      "content-type": "application/json",
+      "cache-control": "no-store",
+    },
+  });
+}
+
+export async function handleApproveClient(
+  req: Request,
+  clientId: string,
+  deps: AdminClientsDeps,
+): Promise<Response> {
+  if (req.method !== "POST") {
+    return jsonError(405, "method_not_allowed", "use POST");
+  }
+  let ctx: AdminAuthContext;
+  try {
+    ctx = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+  } catch (err) {
+    return adminAuthErrorResponse(err as AdminAuthError);
+  }
+  const before = getClient(deps.db, clientId);
+  if (!before) {
+    return jsonError(404, "not_found", `no client registered with id ${clientId}`);
+  }
+  // Idempotent — approveClient is a no-op when the row is already approved.
+  // The audit line only fires on the actual state change; a no-op approve
+  // shouldn't pollute the log with "approved a thing that was already
+  // approved" noise from a UI tab re-submit.
+  const wasPending = before.status === "pending";
+  const ok = approveClient(deps.db, clientId);
+  if (!ok) {
+    // Race: the row was deleted between getClient and approveClient. Same
+    // surface as "no client" — the operator's intent (this client_id is
+    // approved or doesn't exist) is satisfied.
+    return jsonError(404, "not_found", `no client registered with id ${clientId}`);
+  }
+  if (wasPending) {
+    console.log(
+      `client approved: client_id=${clientId} client_name=${before.clientName ?? ""} approver_sub=${ctx.sub}`,
+    );
+  }
+  return new Response(
+    JSON.stringify({
+      client_id: clientId,
+      status: "approved",
+      already_approved: !wasPending,
+    }),
+    {
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        "cache-control": "no-store",
+      },
+    },
+  );
+}
+
+function jsonError(status: number, error: string, description: string): Response {
+  return new Response(JSON.stringify({ error, error_description: description }), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}