@openparachute/hub 0.5.13-rc.21 → 0.5.13-rc.23

package/README.md

@@ -8,12 +8,30 @@ The hub coordinates the modules running on your machine: it installs them, runs
 
 ## Install
 
+### Local (Bun)
+
 ```sh
 bun add -g @openparachute/hub
 ```
 
 Prereqs: [Bun](https://bun.sh) 1.3.0 or later. `parachute expose` also requires [Tailscale](https://tailscale.com/download) **1.82 or newer** (installed + `tailscale up` run once); the `expose` path is under active polish for launch, so expect rough edges.
 
+### Hosted (Render)
+
+[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/ParachuteComputer/parachute-hub)
+
+One-click Render deploy via the `render.yaml` Blueprint in this repo. Provisions a $7/mo Starter service + 1 GiB persistent disk + auto-deploys from `main`. Comes pre-configured with `PARACHUTE_INSTALL_CHANNEL=latest` so modules you install via the admin SPA (vault, app, scribe, runner) pull stable releases by default.
+
+**Want pre-release / rc modules?** Set `PARACHUTE_INSTALL_CHANNEL=rc` in your Render dashboard env vars (useful for dev/testing against the rc release line).
+
+After deploy:
+
+1. Open your Render service URL → wizard runs at `/admin/setup`
+2. Set custom domain (optional) → set `PARACHUTE_HUB_ORIGIN` env to match
+3. Install modules via the admin SPA at `/admin/modules` (or via the wizard)
+
+Render's docs on Blueprints: <https://render.com/docs/blueprint-spec>
+
 ## First 5 minutes
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.5.13-rc.21",
+  "version": "0.5.13-rc.23",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/api-hub.test.ts

@@ -0,0 +1,251 @@
+/**
+ * `GET /api/hub` — hub version + uptime + install-source surface for the
+ * admin SPA's version badge.
+ *
+ * Tests assert the contract:
+ *   - 405 on non-GET (matches the shape of other /api/* read endpoints).
+ *   - 401/403 on missing or under-scoped bearer (host:admin required).
+ *   - Happy path returns the expected shape + uptime increments between
+ *     calls.
+ *   - PARACHUTE_HOME=/parachute (the Render Blueprint pin) overrides
+ *     `source` to "container".
+ *   - PARACHUTE_BUILD_TIME passes through as `container_build_time`.
+ */
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type HubStatusResponse, handleApiHub } from "../api-hub.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { signAccessToken } from "../jwt-sign.ts";
+import { mintOperatorToken } from "../operator-token.ts";
+import { rotateSigningKey } from "../signing-keys.ts";
+import { createUser } from "../users.ts";
+
+interface Harness {
+  dir: string;
+  cleanup: () => void;
+}
+
+function makeHarness(): Harness {
+  const dir = mkdtempSync(join(tmpdir(), "phub-api-hub-"));
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+const ISSUER = "http://127.0.0.1:1939";
+
+// `hubSrcDir` defaults to `dirname(import.meta.url)` of api-hub.ts — but in
+// tests we drive it explicitly so test-side test-double dirs don't accidentally
+// pick up the real package.json. Point it at this file's dir (under __tests__/)
+// so the climb-to-package.json loop walks up to the repo root and finds the
+// real hub package.json.
+const HUB_SRC_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+async function bootstrap(
+  dir: string,
+): Promise<{ db: ReturnType<typeof openHubDb>; userId: string }> {
+  const db = openHubDb(hubDbPath(dir));
+  rotateSigningKey(db);
+  const u = await createUser(db, "owner", "pw");
+  return { db, userId: u.id };
+}
+
+function getRequest(headers: Record<string, string> = {}): Request {
+  return new Request("http://localhost/api/hub", {
+    method: "GET",
+    headers,
+  });
+}
+
+describe("GET /api/hub (hub version + uptime badge surface)", () => {
+  test("405 on non-GET", async () => {
+    const h = makeHarness();
+    try {
+      const { db } = await bootstrap(h.dir);
+      try {
+        const req = new Request("http://localhost/api/hub", { method: "POST" });
+        const resp = await handleApiHub(req, { db, issuer: ISSUER });
+        expect(resp.status).toBe(405);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("401 when no Authorization header", async () => {
+    const h = makeHarness();
+    try {
+      const { db } = await bootstrap(h.dir);
+      try {
+        const resp = await handleApiHub(getRequest(), { db, issuer: ISSUER });
+        expect(resp.status).toBe(401);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("403 when bearer scope lacks parachute:host:admin", async () => {
+    const h = makeHarness();
+    try {
+      const { db, userId } = await bootstrap(h.dir);
+      try {
+        const narrow = await signAccessToken(db, {
+          sub: userId,
+          // Adjacent host scope but NOT host:admin — host:auth is the
+          // tokens-registry scope, not the admin one. Confirms the gate
+          // checks the exact scope, not any host:* membership.
+          scopes: ["parachute:host:auth"],
+          audience: "hub",
+          clientId: "parachute-hub",
+          issuer: ISSUER,
+          ttlSeconds: 3600,
+        });
+        const resp = await handleApiHub(getRequest({ authorization: `Bearer ${narrow.token}` }), {
+          db,
+          issuer: ISSUER,
+        });
+        expect(resp.status).toBe(403);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("happy path: returns version + started_at + uptime_ms + source", async () => {
+    const h = makeHarness();
+    try {
+      const { db, userId } = await bootstrap(h.dir);
+      try {
+        const op = await mintOperatorToken(db, userId, { issuer: ISSUER });
+        const startedAt = new Date(Date.now() - 5000); // started 5s ago
+        const resp = await handleApiHub(getRequest({ authorization: `Bearer ${op.token}` }), {
+          db,
+          issuer: ISSUER,
+          hubSrcDir: HUB_SRC_DIR,
+          startedAt,
+          // Override env so we're not at the mercy of the host's
+          // PARACHUTE_HOME (or PARACHUTE_BUILD_TIME) when the test runs.
+          env: {},
+        });
+        expect(resp.status).toBe(200);
+        const body = (await resp.json()) as HubStatusResponse;
+        // Version pulled from the real hub package.json — assert SemVer
+        // shape rather than pinning a specific number (otherwise this test
+        // breaks on every rc bump).
+        expect(body.version).toMatch(/^\d+\.\d+\.\d+/);
+        expect(body.started_at).toBe(startedAt.toISOString());
+        expect(body.uptime_ms).toBeGreaterThanOrEqual(5000);
+        // hubSrcDir points at the real repo's src/, so install-source
+        // classification will report bun-linked OR npm OR unknown — never
+        // "container" because we cleared PARACHUTE_HOME.
+        expect(body.source).not.toBe("container");
+        expect(body.container_build_time).toBeUndefined();
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("uptime_ms increments between calls", async () => {
+    const h = makeHarness();
+    try {
+      const { db, userId } = await bootstrap(h.dir);
+      try {
+        const op = await mintOperatorToken(db, userId, { issuer: ISSUER });
+        const startedAt = new Date("2026-05-23T14:00:00.000Z");
+        // Drive "now" so the assertion isn't a flaky timing test.
+        const first = await handleApiHub(getRequest({ authorization: `Bearer ${op.token}` }), {
+          db,
+          issuer: ISSUER,
+          hubSrcDir: HUB_SRC_DIR,
+          startedAt,
+          now: () => new Date("2026-05-23T14:00:05.000Z"),
+          env: {},
+        });
+        const second = await handleApiHub(getRequest({ authorization: `Bearer ${op.token}` }), {
+          db,
+          issuer: ISSUER,
+          hubSrcDir: HUB_SRC_DIR,
+          startedAt,
+          now: () => new Date("2026-05-23T14:00:08.000Z"),
+          env: {},
+        });
+        const firstBody = (await first.json()) as HubStatusResponse;
+        const secondBody = (await second.json()) as HubStatusResponse;
+        expect(firstBody.uptime_ms).toBe(5000);
+        expect(secondBody.uptime_ms).toBe(8000);
+        expect(secondBody.uptime_ms).toBeGreaterThan(firstBody.uptime_ms);
+        // started_at stays stable across calls (captured once at process
+        // start, not per-request).
+        expect(secondBody.started_at).toBe(firstBody.started_at);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("PARACHUTE_HOME=/parachute overrides source to 'container'", async () => {
+    const h = makeHarness();
+    try {
+      const { db, userId } = await bootstrap(h.dir);
+      try {
+        const op = await mintOperatorToken(db, userId, { issuer: ISSUER });
+        const resp = await handleApiHub(getRequest({ authorization: `Bearer ${op.token}` }), {
+          db,
+          issuer: ISSUER,
+          hubSrcDir: HUB_SRC_DIR,
+          env: { PARACHUTE_HOME: "/parachute" },
+        });
+        expect(resp.status).toBe(200);
+        const body = (await resp.json()) as HubStatusResponse;
+        expect(body.source).toBe("container");
+        // bun_linked_path is suppressed under container source — operators
+        // on Render don't have a meaningful "checkout path" to surface.
+        expect(body.bun_linked_path).toBeUndefined();
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("PARACHUTE_BUILD_TIME passes through as container_build_time", async () => {
+    const h = makeHarness();
+    try {
+      const { db, userId } = await bootstrap(h.dir);
+      try {
+        const op = await mintOperatorToken(db, userId, { issuer: ISSUER });
+        const resp = await handleApiHub(getRequest({ authorization: `Bearer ${op.token}` }), {
+          db,
+          issuer: ISSUER,
+          hubSrcDir: HUB_SRC_DIR,
+          env: {
+            PARACHUTE_HOME: "/parachute",
+            PARACHUTE_BUILD_TIME: "2026-05-23T14:21:00.000Z",
+          },
+        });
+        expect(resp.status).toBe(200);
+        const body = (await resp.json()) as HubStatusResponse;
+        expect(body.container_build_time).toBe("2026-05-23T14:21:00.000Z");
+        expect(body.source).toBe("container");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+});

package/src/api-hub.ts

@@ -0,0 +1,201 @@
+import type { Database } from "bun:sqlite";
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { adminAuthErrorResponse, requireScope } from "./admin-auth.ts";
+import { HOST_ADMIN_SCOPE } from "./admin-vaults.ts";
+import { detectHubInstallSource } from "./install-source.ts";
+
+/**
+ * `GET /api/hub` — hub runtime info for the admin SPA's version badge.
+ *
+ * Operators (especially Render deployers tracking auto-deploys from `main`)
+ * need to tell at a glance: what version is this hub running, when did it
+ * last restart, is this the version I expect? The CLI surface `parachute
+ * status` already shows the same data; this endpoint mirrors it for the
+ * browser SPA.
+ *
+ * Bearer-gated on `parachute:host:admin` (same as `/vaults` and `/api/grants`).
+ * Operators-only: the version + uptime + install-source fingerprint isn't
+ * sensitive per se, but it's adjacent to operator-only diagnostics so it
+ * lives behind the same gate as the rest of the admin surface.
+ *
+ * Response shape (snake_case to match other `/api/*` endpoints):
+ *
+ *   {
+ *     "version":              "0.5.13-rc.23",
+ *     "started_at":           "2026-05-23T14:23:45.000Z",
+ *     "uptime_ms":            8025000,
+ *     "source":               "bun-linked" | "npm" | "container" | "unknown",
+ *     "bun_linked_path":      "/Users/.../parachute-hub"        // optional
+ *     "git_head":             "a53af21"                          // optional
+ *     "container_build_time": "2026-05-23T14:21:00Z"             // optional
+ *   }
+ *
+ * - `source` reuses `detectHubInstallSource` from install-source.ts (the
+ *   same logic `parachute status` uses for the SOURCE column). The fourth
+ *   value `"container"` is hub-specific: when `process.env.PARACHUTE_HOME
+ *   === "/parachute"` (the Render Blueprint pin) we override `bun-linked`
+ *   → `container` so the badge tells operators "you're on Render", not
+ *   the misleading "bun-linked from /app".
+ * - `started_at` is captured once at module load (see `HUB_PROCESS_STARTED_AT`).
+ *   `uptime_ms` is computed server-side at request time so the client
+ *   doesn't have to deal with clock skew.
+ * - `container_build_time` reads `process.env.PARACHUTE_BUILD_TIME` —
+ *   passed through by the Dockerfile when set as a build arg (operators
+ *   can set this themselves in render.yaml or via `--build-arg` to surface
+ *   the image build time). Not surfaced when unset.
+ */
+
+export interface ApiHubDeps {
+  db: Database;
+  /** Hub origin — used to validate the bearer's `iss`. */
+  issuer: string;
+  /**
+   * Override the directory used to locate the hub's package.json and to
+   * classify install source. Defaults to `dirname(import.meta.url)` —
+   * which is `<repo>/src/` for normal layouts. Test seam.
+   */
+  hubSrcDir?: string;
+  /** Override `process.env` lookups. Test seam. */
+  env?: Record<string, string | undefined>;
+  /** Override the started-at timestamp. Test seam — defaults to the module-level capture. */
+  startedAt?: Date;
+  /** Override "now" for uptime computation. Test seam. */
+  now?: () => Date;
+}
+
+/**
+ * The hub process's start time. Captured exactly once at module load and
+ * re-exported so the request handler returns a stable value across calls
+ * (and so the `parachute status` CLI surface in the same process can pull
+ * it from one source).
+ */
+export const HUB_PROCESS_STARTED_AT: Date = new Date();
+
+/** Wire shape returned by `GET /api/hub`. Snake-case to match other `/api/*` endpoints. */
+export interface HubStatusResponse {
+  version: string;
+  started_at: string;
+  uptime_ms: number;
+  source: "bun-linked" | "npm" | "container" | "unknown";
+  bun_linked_path?: string;
+  git_head?: string;
+  container_build_time?: string;
+  /** Render-set runtime env vars surfaced when running on Render. Sourced from RENDER_GIT_COMMIT + RENDER_GIT_BRANCH. */
+  render_commit?: string;
+  render_branch?: string;
+}
+
+export async function handleApiHub(req: Request, deps: ApiHubDeps): Promise<Response> {
+  if (req.method !== "GET") {
+    return jsonError(405, "method_not_allowed", "use GET");
+  }
+
+  // Bearer-gate on `parachute:host:admin`. Same shape as the other admin
+  // endpoints — SPA mints via /admin/host-admin-token.
+  try {
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+  } catch (err) {
+    return adminAuthErrorResponse(err);
+  }
+
+  const env = deps.env ?? process.env;
+  const startedAt = deps.startedAt ?? HUB_PROCESS_STARTED_AT;
+  const now = (deps.now ?? (() => new Date()))();
+  const hubSrcDir = deps.hubSrcDir ?? dirname(fileURLToPath(import.meta.url));
+
+  // detectHubInstallSource climbs from src/ to the nearest package.json,
+  // reads its version, classifies as bun-linked vs npm vs unknown.
+  const source = detectHubInstallSource(hubSrcDir);
+
+  // Read version from the nearest package.json (same logic the install-source
+  // detector ran). We don't reuse `source.livePackageVersion` because the
+  // unknown-source branch leaves it undefined — but the version field on the
+  // response must always be present.
+  const version = readHubVersion(hubSrcDir) ?? "unknown";
+
+  // Container override: the Render Blueprint pins PARACHUTE_HOME=/parachute,
+  // which is a reliable container-mode signal. The install-source detector
+  // would label this `bun-linked` (the image runs from /app/src, not bun
+  // globals), which is technically true but misleading for the operator —
+  // "container" is what they actually want to see.
+  const isContainer = env.PARACHUTE_HOME === "/parachute";
+
+  const body: HubStatusResponse = {
+    version,
+    started_at: startedAt.toISOString(),
+    uptime_ms: Math.max(0, now.getTime() - startedAt.getTime()),
+    source: isContainer ? "container" : source.kind,
+  };
+
+  if (!isContainer && source.kind === "bun-linked" && source.path) {
+    body.bun_linked_path = source.path;
+  }
+  // `git_head` is meaningful only for bun-linked dev installs — the container
+  // image strips `.git` at build time so source.gitHead is always undefined
+  // there. Explicit !isContainer guard for symmetry with bun_linked_path.
+  if (!isContainer && source.gitHead) {
+    body.git_head = source.gitHead;
+  }
+  const buildTime = env.PARACHUTE_BUILD_TIME;
+  if (typeof buildTime === "string" && buildTime.length > 0) {
+    body.container_build_time = buildTime;
+  }
+  // Render exposes RENDER_GIT_COMMIT + RENDER_GIT_BRANCH at runtime when
+  // the container is running on Render. Surface for operator diagnostics
+  // (the commit SHA is a more rigorous identity than build-time wall-clock).
+  // Container-mode only — local dev never has these set.
+  if (isContainer) {
+    const renderCommit = env.RENDER_GIT_COMMIT;
+    if (typeof renderCommit === "string" && renderCommit.length > 0) {
+      body.render_commit = renderCommit;
+    }
+    const renderBranch = env.RENDER_GIT_BRANCH;
+    if (typeof renderBranch === "string" && renderBranch.length > 0) {
+      body.render_branch = renderBranch;
+    }
+  }
+
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {
+      "content-type": "application/json",
+      "cache-control": "no-store",
+    },
+  });
+}
+
+/**
+ * Read the hub's package.json `version` field. Climbs from `srcDir` to the
+ * nearest package.json (same pattern as `findNearestPackageDir` in
+ * install-source.ts). Returns undefined if the file's missing or malformed.
+ */
+function readHubVersion(srcDir: string): string | undefined {
+  let current = resolve(srcDir);
+  for (let i = 0; i < 16; i++) {
+    try {
+      const parsed = JSON.parse(readFileSync(join(current, "package.json"), "utf8")) as unknown;
+      if (parsed && typeof parsed === "object") {
+        const v = (parsed as Record<string, unknown>).version;
+        if (typeof v === "string" && v.length > 0) return v;
+      }
+    } catch {
+      // No package.json here — climb.
+    }
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+  return undefined;
+}
+
+function jsonError(status: number, error: string, description: string): Response {
+  return new Response(JSON.stringify({ error, error_description: description }), {
+    status,
+    headers: {
+      "content-type": "application/json",
+      "cache-control": "no-store",
+    },
+  });
+}

package/src/hub-server.ts

@@ -46,6 +46,7 @@
  *   /admin/host-admin-token       (GET)        → SPA bearer mint (cookie-gated)
  *   /admin/vault-admin-token/<n>  (GET)        → per-vault bearer mint (cookie-gated)
  *   /api/me                       (GET)        → who-am-I (session+CSRF or hasSession:false)
+ *   /api/hub                      (GET)        → hub version + uptime + install-source (host:admin)
  *   /api/modules                  (GET)        → curated + installed module catalog (host:auth)
  *   /api/modules/channel          (PUT)        → operator channel toggle (host:admin)
  *   /api/modules/:short/install   (POST)       → bun add + spawn (async op)
@@ -117,6 +118,7 @@ import { handleHostAdminToken } from "./admin-host-admin-token.ts";
 import { handleVaultAdminToken } from "./admin-vault-admin-token.ts";
 import { handleCreateVault } from "./admin-vaults.ts";
 import { handleAccountChangePasswordGet, handleAccountChangePasswordPost } from "./api-account.ts";
+import { handleApiHub } from "./api-hub.ts";
 import { handleApiMe } from "./api-me.ts";
 import { handleApiMintToken } from "./api-mint-token.ts";
 import { handleApiModulesConfig, parseModulesConfigPath } from "./api-modules-config.ts";
@@ -1526,6 +1528,17 @@ export function hubFetch(
       return handleApiMe(req, { db: getDb() });
     }
 
+    // Hub version + uptime + install-source — drives the admin SPA's
+    // version badge (hub#348). Bearer-gated on `parachute:host:admin`
+    // (same as the rest of the operator-only admin surface).
+    if (pathname === "/api/hub") {
+      if (!getDb) return dbNotConfigured();
+      return handleApiHub(req, {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+      });
+    }
+
     if (pathname === "/api/modules") {
       if (!getDb) return dbNotConfigured();
       const modulesDeps: Parameters<typeof handleApiModules>[1] = {