@openparachute/hub 0.5.10-rc.6 → 0.5.10-rc.9

package/package.json

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

package/src/__tests__/api-modules-ops.test.ts

@@ -415,6 +415,71 @@ describe("POST /api/modules/:short/upgrade", () => {
     await new Promise((r) => setTimeout(r, 10));
     expect(calls).toContainEqual(["bun", "add", "-g", "@openparachute/vault@latest"]);
   });
+
+  test("fails with 'try install first' when module is installed but never supervised", async () => {
+    // Module has a services.json row (e.g. seeded by `parachute install`
+    // pre-supervisor era) but the supervisor never spawned it.
+    // `bun add -g` succeeds, then `supervisor.restart()` returns
+    // undefined because there's no entry in the Map. The operation
+    // should land in `failed` with the canonical "try install first"
+    // message rather than silently succeed (hub#265).
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-vault",
+        port: 1940,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+        version: "0.4.5",
+      },
+    ]);
+    const { supervisor, spawns } = makeIdleSupervisor();
+    // Intentionally do NOT call supervisor.start(...) — that's the
+    // path under test.
+
+    const { run, calls } = alwaysOkRun();
+    const bearer = await mintBearer(h, [API_MODULES_OPS_REQUIRED_SCOPE]);
+    const deps = {
+      db: h.db,
+      issuer: ISSUER,
+      manifestPath: h.manifestPath,
+      configDir: h.dir,
+      supervisor,
+      run,
+    };
+    const res = await handleUpgrade(
+      postReq("/api/modules/vault/upgrade", { authorization: `Bearer ${bearer}` }),
+      "vault",
+      deps,
+    );
+    expect(res.status).toBe(202);
+    const body = (await res.json()) as { operation_id: string };
+    // Give the async runUpgrade chain a tick to settle.
+    await new Promise((r) => setTimeout(r, 10));
+
+    // bun add was still attempted (it's the first step).
+    expect(calls).toContainEqual(["bun", "add", "-g", "@openparachute/vault@latest"]);
+    // No supervisor spawn ever happened — confirms the missing
+    // supervisor entry is what we exercised, not some other branch.
+    expect(spawns).toEqual([]);
+
+    // Poll the operation: status `failed`, message points the
+    // operator at the install path.
+    const opRes = await handleOperationGet(
+      getReq(`/api/modules/operations/${body.operation_id}`, {
+        authorization: `Bearer ${bearer}`,
+      }),
+      body.operation_id,
+      deps,
+    );
+    const op = (await opRes.json()) as {
+      status: string;
+      error?: string;
+      log: string[];
+    };
+    expect(op.status).toBe("failed");
+    expect(op.error).toMatch(/supervisor restart found no module/);
+    expect(op.log.join(" ")).toMatch(/try install first/);
+  });
 });
 
 describe("POST /api/modules/:short/uninstall", () => {

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

@@ -165,6 +165,29 @@ describe("hubFetch routing", () => {
     }
   });
 
+  test("/.well-known/parachute.json sets cache-control: no-store (hub#268 Item 1)", async () => {
+    // The discovery page (/) fetches this doc and renders Service tiles
+    // from it. Without no-store, the browser HTTP cache returns the
+    // stale services list the next time the operator clicks back to /
+    // after installing a module via /admin/modules. The doc is built
+    // per-request anyway, so giving up cacheability has no real cost.
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [] }, h.manifestPath);
+      const getRes = await hubFetch(h.dir, { manifestPath: h.manifestPath })(
+        req("/.well-known/parachute.json"),
+      );
+      expect(getRes.headers.get("cache-control")).toBe("no-store");
+      // Preflight gets the same header (same corsHeaders object).
+      const optRes = await hubFetch(h.dir, { manifestPath: h.manifestPath })(
+        req("/.well-known/parachute.json", { method: "OPTIONS" }),
+      );
+      expect(optRes.headers.get("cache-control")).toBe("no-store");
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("OPTIONS preflight on /.well-known/parachute.json returns 204 + CORS", async () => {
     const h = makeHarness();
     try {
@@ -1010,16 +1033,17 @@ describe("hubFetch routing", () => {
     }
   });
 
-  test("/admin/setup 301s to /login once admin + vault both exist (hub#259)", async () => {
+  test("/admin/setup 301s to /login once admin + vault + expose mode all exist (hub#259, hub#268)", async () => {
     const h = makeHarness();
     try {
       const db = openHubDb(hubDbPath(h.dir));
       try {
         await createUser(db, "owner", "pw");
-        // Seed the vault entry so the wizard's state derives as "done"
-        // and the GET 301s. Without this the wizard would still resume
-        // at the vault step.
+        // Seed the vault entry + expose-mode answer so the wizard's
+        // state derives as "done" and the GET 301s. Without expose
+        // (hub#268 Item 2) the wizard would resume on the expose step.
         const { writeManifest } = await import("../services-manifest.ts");
+        const { setSetting } = await import("../hub-settings.ts");
         const { join } = await import("node:path");
         writeManifest(
           {
@@ -1035,6 +1059,7 @@ describe("hubFetch routing", () => {
           },
           join(h.dir, "services.json"),
         );
+        setSetting(db, "setup_expose_mode", "localhost");
         const res = await hubFetch(h.dir, {
           getDb: () => db,
           manifestPath: join(h.dir, "services.json"),

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

@@ -0,0 +1,225 @@
+/**
+ * Tests for hub-local key/value settings (hub#268).
+ *
+ * Covers the bare KV API (get/set/delete) and the two domain helpers
+ * the wizard + oauth handlers consume: setup_expose_mode validation and
+ * the first-client auto-approve window (open + check + consume + clear).
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import {
+  FIRST_CLIENT_AUTO_APPROVE_WINDOW_MS,
+  SETUP_EXPOSE_MODES,
+  consumeFirstClientAutoApproveWindow,
+  deleteSetting,
+  getSetting,
+  isFirstClientAutoApproveWindowOpen,
+  isSetupExposeMode,
+  openFirstClientAutoApproveWindow,
+  setSetting,
+} from "../hub-settings.ts";
+
+describe("hub-settings — bare KV", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "hub-settings-"));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  test("getSetting returns undefined for an absent key", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      expect(getSetting(db, "setup_expose_mode")).toBeUndefined();
+    } finally {
+      db.close();
+    }
+  });
+
+  test("setSetting writes a value getSetting reads back", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      setSetting(db, "setup_expose_mode", "tailnet");
+      expect(getSetting(db, "setup_expose_mode")).toBe("tailnet");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("setSetting overwrites an existing value (UPSERT)", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      setSetting(db, "setup_expose_mode", "tailnet");
+      setSetting(db, "setup_expose_mode", "public");
+      expect(getSetting(db, "setup_expose_mode")).toBe("public");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("deleteSetting removes a row + idempotently no-ops on a missing key", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      setSetting(db, "setup_expose_mode", "localhost");
+      deleteSetting(db, "setup_expose_mode");
+      expect(getSetting(db, "setup_expose_mode")).toBeUndefined();
+      // Second delete is a no-op.
+      deleteSetting(db, "setup_expose_mode");
+      expect(getSetting(db, "setup_expose_mode")).toBeUndefined();
+    } finally {
+      db.close();
+    }
+  });
+
+  test("setSetting updates the updated_at column on every write", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const t1 = new Date("2026-05-19T00:00:00.000Z");
+      const t2 = new Date("2026-05-19T00:01:00.000Z");
+      setSetting(db, "setup_expose_mode", "localhost", () => t1);
+      setSetting(db, "setup_expose_mode", "localhost", () => t2);
+      // Re-write with the same value still bumps updated_at — useful
+      // for operational polling that wants to distinguish stale vs
+      // fresh state.
+      const row = db
+        .query<{ updated_at: string }, []>(
+          "SELECT updated_at FROM hub_settings WHERE key = 'setup_expose_mode'",
+        )
+        .get();
+      expect(row?.updated_at).toBe(t2.toISOString());
+    } finally {
+      db.close();
+    }
+  });
+});
+
+describe("hub-settings — isSetupExposeMode", () => {
+  test("accepts the three canonical values", () => {
+    for (const m of SETUP_EXPOSE_MODES) {
+      expect(isSetupExposeMode(m)).toBe(true);
+    }
+  });
+
+  test("rejects anything else (typos, empty, non-string)", () => {
+    expect(isSetupExposeMode("local")).toBe(false);
+    expect(isSetupExposeMode("LOCALHOST")).toBe(false);
+    expect(isSetupExposeMode("")).toBe(false);
+    expect(isSetupExposeMode(null)).toBe(false);
+    expect(isSetupExposeMode(undefined)).toBe(false);
+    expect(isSetupExposeMode(42)).toBe(false);
+  });
+});
+
+describe("hub-settings — first-client auto-approve window", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "hub-settings-"));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  test("window is closed by default (no row)", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      expect(isFirstClientAutoApproveWindowOpen(db)).toBe(false);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("openFirstClientAutoApproveWindow opens a window 60 minutes long", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const now = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => now);
+      const stored = getSetting(db, "pending_first_client_auto_approve_until");
+      expect(stored).toBeDefined();
+      const parsed = new Date(stored ?? "");
+      expect(parsed.getTime() - now.getTime()).toBe(FIRST_CLIENT_AUTO_APPROVE_WINDOW_MS);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("isFirstClientAutoApproveWindowOpen → true within window, false after expiry", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const t0 = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => t0);
+      // 30 minutes in → still open.
+      expect(
+        isFirstClientAutoApproveWindowOpen(db, () => new Date(t0.getTime() + 30 * 60 * 1000)),
+      ).toBe(true);
+      // 60 minutes + 1 ms in → closed.
+      expect(
+        isFirstClientAutoApproveWindowOpen(
+          db,
+          () => new Date(t0.getTime() + FIRST_CLIENT_AUTO_APPROVE_WINDOW_MS + 1),
+        ),
+      ).toBe(false);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("consumeFirstClientAutoApproveWindow consumes the window once, then returns false", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const now = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => now);
+      // First call consumes.
+      expect(consumeFirstClientAutoApproveWindow(db, () => now)).toBe(true);
+      // Second call sees no window.
+      expect(consumeFirstClientAutoApproveWindow(db, () => now)).toBe(false);
+      // The row is cleared.
+      expect(getSetting(db, "pending_first_client_auto_approve_until")).toBeUndefined();
+    } finally {
+      db.close();
+    }
+  });
+
+  test("consume returns false when the window has expired (and clears nothing)", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const t0 = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => t0);
+      const past = new Date(t0.getTime() + FIRST_CLIENT_AUTO_APPROVE_WINDOW_MS + 1);
+      expect(consumeFirstClientAutoApproveWindow(db, () => past)).toBe(false);
+      // Row is still there (no implicit cleanup on expiry — the setting
+      // just stops being "open"). A future open() resets it.
+      expect(getSetting(db, "pending_first_client_auto_approve_until")).toBeDefined();
+    } finally {
+      db.close();
+    }
+  });
+
+  test("malformed timestamp string is treated as closed (not parseable → not open)", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      setSetting(db, "pending_first_client_auto_approve_until", "not-a-date");
+      expect(isFirstClientAutoApproveWindowOpen(db)).toBe(false);
+      expect(consumeFirstClientAutoApproveWindow(db)).toBe(false);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("reopening the window after consume restarts the 60-minute clock", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const t0 = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => t0);
+      consumeFirstClientAutoApproveWindow(db, () => t0);
+      // Re-open at t0 + 90min.
+      const t1 = new Date(t0.getTime() + 90 * 60 * 1000);
+      openFirstClientAutoApproveWindow(db, () => t1);
+      // The new window's expiry is t1 + 60min, not t0 + 60min.
+      const stored = getSetting(db, "pending_first_client_auto_approve_until");
+      const parsed = new Date(stored ?? "");
+      expect(parsed.getTime()).toBe(t1.getTime() + FIRST_CLIENT_AUTO_APPROVE_WINDOW_MS);
+    } finally {
+      db.close();
+    }
+  });
+});

package/src/__tests__/hub.test.ts

@@ -103,6 +103,23 @@ describe("renderHub", () => {
     expect(html).toContain("Could not load services");
   });
 
+  test("discovery page fetches with cache: 'no-store' (hub#268 Item 1)", () => {
+    // Without `cache: 'no-store'` the browser's HTTP cache can return
+    // a stale services list when the operator clicks back to / after
+    // installing a module via /admin/modules. Server-side also sets
+    // cache-control: no-store on the well-known doc.
+    expect(html).toContain("cache: 'no-store'");
+  });
+
+  test("discovery page re-fetches on bfcache restore via pageshow (hub#268 Item 1)", () => {
+    // When the operator clicks back from /admin/modules to / the
+    // browser may restore the prior DOM without re-running the IIFE.
+    // The pageshow handler re-runs loadServices() when the page was
+    // restored from cache (`e.persisted === true`).
+    expect(html).toContain("addEventListener('pageshow'");
+    expect(html).toContain("e.persisted");
+  });
+
   test("does not retain the old aggregate-by-module-type code", () => {
     // The Vault collapse + per-module aggregation pattern is gone — Use
     // entries are direct service-path → label lookups; Admin is hardcoded.

package/src/__tests__/oauth-handlers.test.ts

@@ -6,6 +6,12 @@ import { join } from "node:path";
 import { getClient, registerClient } from "../clients.ts";
 import { CSRF_COOKIE_NAME } from "../csrf.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
+import {
+  FIRST_CLIENT_AUTO_APPROVE_WINDOW_MS,
+  getSetting,
+  openFirstClientAutoApproveWindow,
+  setSetting,
+} from "../hub-settings.ts";
 import { findTokenRowByJti, validateAccessToken } from "../jwt-sign.ts";
 import {
   authorizationServerMetadata,
@@ -4216,3 +4222,144 @@ describe("inline approve button on pending /oauth/authorize (#208)", () => {
     }
   });
 });
+
+// DCR first-client auto-approve window (hub#268 Item 3). The wizard's
+// expose-step POST opens a 60-minute window where the very next
+// `/oauth/register` registration is auto-approved + the window cleared.
+// Single-use: client #2 within the same window falls through to the
+// standard pending-approval flow.
+describe("DCR first-client auto-approve window (hub#268 Item 3)", () => {
+  function registerRequest(): Request {
+    return new Request(`${ISSUER}/oauth/register`, {
+      method: "POST",
+      body: JSON.stringify({
+        redirect_uris: ["https://app.example/cb"],
+        client_name: "first-client",
+      }),
+      headers: { "content-type": "application/json" },
+    });
+  }
+
+  test("client registered within the open window → status approved + window cleared", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const t0 = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => t0);
+      const res = await handleRegister(db, registerRequest(), {
+        issuer: ISSUER,
+        now: () => t0,
+      });
+      expect(res.status).toBe(201);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("approved");
+      // Persisted, not just response-shaped.
+      const row = getClient(db, body.client_id as string);
+      expect(row?.status).toBe("approved");
+      // Window cleared on consume (single-use).
+      expect(getSetting(db, "pending_first_client_auto_approve_until")).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("client registered AFTER the window has expired → status pending", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const t0 = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => t0);
+      const past = new Date(t0.getTime() + FIRST_CLIENT_AUTO_APPROVE_WINDOW_MS + 1);
+      const res = await handleRegister(db, registerRequest(), {
+        issuer: ISSUER,
+        now: () => past,
+      });
+      expect(res.status).toBe(201);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("second client within window after first auto-approved → status pending (single-use)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const t0 = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => t0);
+      // Client #1: approved.
+      const res1 = await handleRegister(db, registerRequest(), {
+        issuer: ISSUER,
+        now: () => t0,
+      });
+      const body1 = (await res1.json()) as Record<string, unknown>;
+      expect(body1.status).toBe("approved");
+      // Client #2 within the (still-not-expired) window: pending.
+      const stillWithinWindow = new Date(t0.getTime() + 30 * 60 * 1000);
+      const res2 = await handleRegister(db, registerRequest(), {
+        issuer: ISSUER,
+        now: () => stillWithinWindow,
+      });
+      const body2 = (await res2.json()) as Record<string, unknown>;
+      expect(body2.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("no window set → status pending (default public-DCR flow)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const res = await handleRegister(db, registerRequest(), { issuer: ISSUER });
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("pending");
+      // Settings row untouched.
+      expect(getSetting(db, "pending_first_client_auto_approve_until")).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("operator-bearer auto-approve still takes precedence over the window (no double-consume)", async () => {
+    // Bearer-authenticated registration approves directly; the
+    // auto-approve window should NOT be consumed in that case — it's
+    // still available for the first un-authenticated client.
+    const { db, cleanup } = await makeDb();
+    try {
+      const t0 = new Date("2026-05-19T00:00:00.000Z");
+      openFirstClientAutoApproveWindow(db, () => t0);
+      // We can't easily mint an operator bearer in this test layer, so
+      // simulate by using the session-cookie path (issuer-trusted) which
+      // also auto-approves before falling through to the window check.
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const req = new Request(`${ISSUER}/oauth/register`, {
+        method: "POST",
+        body: JSON.stringify({ redirect_uris: ["https://app.example/cb"] }),
+        headers: {
+          "content-type": "application/json",
+          cookie: buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000)),
+          origin: ISSUER,
+        },
+      });
+      const res = await handleRegister(db, req, { issuer: ISSUER, now: () => t0 });
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("approved");
+      // Window NOT consumed — still set, still open. The session-cookie
+      // path approved first, never reaching the window-consume code.
+      expect(getSetting(db, "pending_first_client_auto_approve_until")).toBeDefined();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("malformed timestamp in the setting → treated as no-window, status pending", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      setSetting(db, "pending_first_client_auto_approve_until", "not-a-real-iso-string");
+      const res = await handleRegister(db, registerRequest(), { issuer: ISSUER });
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+});