@openparachute/hub 0.7.7-rc.12 → 0.7.7-rc.13

package/package.json

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

package/src/__tests__/api-settings-root-redirect.test.ts

@@ -18,10 +18,11 @@ import { join } from "node:path";
 import {
   API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE,
   handleApiSettingsRootRedirect,
+  validateRootMode,
   validateRootRedirect,
 } from "../api-settings-root-redirect.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
-import { getRootRedirect, setRootRedirect } from "../hub-settings.ts";
+import { getRootMode, getRootRedirect, setRootMode, setRootRedirect } from "../hub-settings.ts";
 import { recordTokenMint, signAccessToken } from "../jwt-sign.ts";
 import { rotateSigningKey } from "../signing-keys.ts";
 import { createUser } from "../users.ts";
@@ -192,7 +193,14 @@ describe("GET /api/settings/root-redirect", () => {
     );
     expect(res.status).toBe(200);
     const body = (await res.json()) as Record<string, unknown>;
-    expect(body).toEqual({ root_redirect: null, resolved: "/admin", source: "default" });
+    expect(body).toEqual({
+      root_redirect: null,
+      resolved: "/admin",
+      source: "default",
+      root_mode: null,
+      resolved_mode: "redirect",
+      mode_source: "default",
+    });
   });
 
   // H1.1 — Bearer scheme is case-insensitive per RFC 7235 (V1.4/C1.3 parity).
@@ -204,7 +212,14 @@ describe("GET /api/settings/root-redirect", () => {
     );
     expect(res.status).toBe(200);
     const body = (await res.json()) as Record<string, unknown>;
-    expect(body).toEqual({ root_redirect: null, resolved: "/admin", source: "default" });
+    expect(body).toEqual({
+      root_redirect: null,
+      resolved: "/admin",
+      source: "default",
+      root_mode: null,
+      resolved_mode: "redirect",
+      mode_source: "default",
+    });
   });
 
   test("reflects a stored value with source=db", async () => {
@@ -219,6 +234,9 @@ describe("GET /api/settings/root-redirect", () => {
       root_redirect: "/surface/reading-room",
       resolved: "/surface/reading-room",
       source: "db",
+      root_mode: null,
+      resolved_mode: "redirect",
+      mode_source: "default",
     });
   });
 
@@ -233,6 +251,9 @@ describe("GET /api/settings/root-redirect", () => {
       root_redirect: null,
       resolved: "/surface/from-env",
       source: "env",
+      root_mode: null,
+      resolved_mode: "redirect",
+      mode_source: "default",
     });
   });
 });
@@ -251,7 +272,10 @@ describe("PUT /api/settings/root-redirect", () => {
       deps(h),
     );
     expect(put.status).toBe(200);
-    expect((await put.json()) as unknown).toEqual({ root_redirect: "/surface/reading-room" });
+    expect((await put.json()) as unknown).toEqual({
+      root_redirect: "/surface/reading-room",
+      root_mode: null,
+    });
     expect(getRootRedirect(h.db)).toBe("/surface/reading-room");
 
     const get = await handleApiSettingsRootRedirect(
@@ -294,7 +318,7 @@ describe("PUT /api/settings/root-redirect", () => {
     }
   });
 
-  test("400 on a body without a root_redirect field", async () => {
+  test("400 on a body with neither root_redirect nor root_mode", async () => {
     const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
     const res = await handleApiSettingsRootRedirect(
       putReq({ wrong: "x" }, { authorization: `Bearer ${bearer}` }),
@@ -312,3 +336,122 @@ describe("PUT /api/settings/root-redirect", () => {
     expect(res.status).toBe(400);
   });
 });
+
+describe("validateRootMode — pure validator", () => {
+  test("null + empty string → normalized null (clear)", () => {
+    expect(validateRootMode(null)).toEqual({ ok: true, normalized: null });
+    expect(validateRootMode("")).toEqual({ ok: true, normalized: null });
+  });
+
+  test("valid modes normalize verbatim", () => {
+    expect(validateRootMode("redirect")).toEqual({ ok: true, normalized: "redirect" });
+    expect(validateRootMode("serve-app")).toEqual({ ok: true, normalized: "serve-app" });
+  });
+
+  test("rejects unknown modes + non-strings", () => {
+    for (const bad of ["serveapp", "SERVE-APP", "app", 42, {}]) {
+      expect(validateRootMode(bad).ok).toBe(false);
+    }
+  });
+});
+
+describe("root_mode over the endpoint", () => {
+  let h: Harness;
+  beforeEach(async () => {
+    h = await makeHarness();
+  });
+  afterEach(() => h.cleanup());
+
+  test("GET reflects a stored serve-app mode with mode_source=db", async () => {
+    setRootMode(h.db, "serve-app");
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const res = await handleApiSettingsRootRedirect(
+      getReq({ authorization: `Bearer ${bearer}` }),
+      deps(h),
+    );
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body.root_mode).toBe("serve-app");
+    expect(body.resolved_mode).toBe("serve-app");
+    expect(body.mode_source).toBe("db");
+  });
+
+  test("GET surfaces an env-sourced mode while the stored row is null", async () => {
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const res = await handleApiSettingsRootRedirect(
+      getReq({ authorization: `Bearer ${bearer}` }),
+      deps(h, { env: { PARACHUTE_HUB_ROOT_MODE: "serve-app" } }),
+    );
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body.root_mode).toBeNull();
+    expect(body.resolved_mode).toBe("serve-app");
+    expect(body.mode_source).toBe("env");
+  });
+
+  test("PUT stores serve-app + GET reflects it on the next request (no restart)", async () => {
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const put = await handleApiSettingsRootRedirect(
+      putReq({ root_mode: "serve-app" }, { authorization: `Bearer ${bearer}` }),
+      deps(h),
+    );
+    expect(put.status).toBe(200);
+    expect((await put.json()) as unknown).toEqual({ root_redirect: null, root_mode: "serve-app" });
+    expect(getRootMode(h.db)).toBe("serve-app");
+  });
+
+  test("PUT redirect / null clears the row back to the default", async () => {
+    setRootMode(h.db, "serve-app");
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    // Writing the default "redirect" deletes the row (footgun-guard parity).
+    const res = await handleApiSettingsRootRedirect(
+      putReq({ root_mode: "redirect" }, { authorization: `Bearer ${bearer}` }),
+      deps(h),
+    );
+    expect(res.status).toBe(200);
+    expect(getRootMode(h.db)).toBeNull();
+  });
+
+  test("PUT rejects an invalid mode with 400 + writes nothing", async () => {
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const res = await handleApiSettingsRootRedirect(
+      putReq({ root_mode: "serveapp" }, { authorization: `Bearer ${bearer}` }),
+      deps(h),
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body.error).toBe("invalid_root_mode");
+    expect(getRootMode(h.db)).toBeNull();
+  });
+
+  test("PUT applies both root_mode + root_redirect in one call", async () => {
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const res = await handleApiSettingsRootRedirect(
+      putReq(
+        { root_mode: "serve-app", root_redirect: "/surface/fallback" },
+        { authorization: `Bearer ${bearer}` },
+      ),
+      deps(h),
+    );
+    expect(res.status).toBe(200);
+    expect((await res.json()) as unknown).toEqual({
+      root_redirect: "/surface/fallback",
+      root_mode: "serve-app",
+    });
+    expect(getRootMode(h.db)).toBe("serve-app");
+    expect(getRootRedirect(h.db)).toBe("/surface/fallback");
+  });
+
+  test("a rejected mode does NOT half-apply a valid redirect in the same call", async () => {
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const res = await handleApiSettingsRootRedirect(
+      putReq(
+        { root_mode: "bogus", root_redirect: "/surface/should-not-land" },
+        { authorization: `Bearer ${bearer}` },
+      ),
+      deps(h),
+    );
+    expect(res.status).toBe(400);
+    // Both-validated-before-either-applied: the redirect was NOT written.
+    expect(getRootRedirect(h.db)).toBeNull();
+    expect(getRootMode(h.db)).toBeNull();
+  });
+});

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

@@ -12,9 +12,15 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { hub, hubSetOrigin, hubSetRootRedirect, rewriteCaddyfileHost } from "../commands/hub.ts";
+import {
+  hub,
+  hubSetOrigin,
+  hubSetRootMode,
+  hubSetRootRedirect,
+  rewriteCaddyfileHost,
+} from "../commands/hub.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
-import { getHubOrigin, getRootRedirect } from "../hub-settings.ts";
+import { getHubOrigin, getRootMode, getRootRedirect } from "../hub-settings.ts";
 import type { CommandResult } from "../tailscale/run.ts";
 
 describe("parachute hub set-origin", () => {
@@ -498,3 +504,65 @@ describe("parachute hub set-root-redirect", () => {
     expect(persisted()).toBe("/surface/via-dispatcher");
   });
 });
+
+describe("parachute hub set-root-mode", () => {
+  let dir: string;
+  let log: string[];
+  const collect = (line: string) => log.push(line);
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "hub-set-root-mode-"));
+    log = [];
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  function persisted(): string | null {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      return getRootMode(db);
+    } finally {
+      db.close();
+    }
+  }
+
+  test("persists serve-app to hub_settings.root_mode", async () => {
+    const code = await hubSetRootMode(["serve-app"], { configDir: dir, log: collect });
+    expect(code).toBe(0);
+    expect(persisted()).toBe("serve-app");
+    expect(log.join("\n")).toMatch(/serves the Parachute app/);
+  });
+
+  test("`redirect` stores as absence (the default), clearing any row", async () => {
+    await hubSetRootMode(["serve-app"], { configDir: dir, log: collect });
+    const code = await hubSetRootMode(["redirect"], { configDir: dir, log: collect });
+    expect(code).toBe(0);
+    expect(persisted()).toBeNull();
+  });
+
+  test("--clear deletes the row", async () => {
+    await hubSetRootMode(["serve-app"], { configDir: dir, log: collect });
+    const code = await hubSetRootMode(["--clear"], { configDir: dir, log: collect });
+    expect(code).toBe(0);
+    expect(persisted()).toBeNull();
+  });
+
+  test("rejects an unknown mode without writing", async () => {
+    for (const bad of ["serveapp", "SERVE-APP", "app", "/surface/x"]) {
+      const code = await hubSetRootMode([bad], { configDir: dir, log: collect });
+      expect(code).toBe(1);
+      expect(persisted()).toBeNull();
+    }
+  });
+
+  test("usage error (exit 1) when no mode + no --clear", async () => {
+    const code = await hubSetRootMode([], { configDir: dir, log: collect });
+    expect(code).toBe(1);
+    expect(persisted()).toBeNull();
+  });
+
+  test("routed through the `hub` dispatcher", async () => {
+    const code = await hub(["set-root-mode", "serve-app"], { configDir: dir, log: collect });
+    expect(code).toBe(0);
+    expect(persisted()).toBe("serve-app");
+  });
+});

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

@@ -17,7 +17,7 @@ import {
   resolveClientIp,
   stripHopByHopHeaders,
 } from "../hub-server.ts";
-import { setNotesRedirectDisabled } from "../hub-settings.ts";
+import { setNotesRedirectDisabled, setRootMode } from "../hub-settings.ts";
 import { clearNotesRedirectLogState } from "../notes-redirect.ts";
 import { mintOperatorToken } from "../operator-token.ts";
 import { pidPath } from "../process-state.ts";
@@ -6418,3 +6418,287 @@ describe("hubFetch proxied-page security headers (hub#643 Tier-1)", () => {
     }
   });
 });
+
+// root_mode = serve-app: the hub serves the installed app's dist AT `/`, with
+// the fresh-hub funnel + pre-admin 503 + every hub-owned route preempting it.
+describe("hubFetch — root_mode serve-app", () => {
+  // A fixture app dist (index.html + assets). Distinct marker text so a test can
+  // tell an app-served body from an admin-SPA / discovery body.
+  function makeAppDist(dir: string): string {
+    const dist = join(dir, "app-dist");
+    mkdirSync(join(dist, "assets"), { recursive: true });
+    writeFileSync(join(dist, "index.html"), "<!doctype html><title>PARACHUTE-APP-SHELL</title>");
+    writeFileSync(join(dist, "assets", "app-xyz.js"), "console.log('serve-app')");
+    writeFileSync(join(dist, "manifest.webmanifest"), '{"name":"Parachute"}');
+    return dist;
+  }
+
+  // A distinct admin-SPA fixture so `/admin` reachability is provable (its body
+  // must NOT be the app shell).
+  function makeAdminDist(dir: string): string {
+    const dist = join(dir, "admin-dist");
+    mkdirSync(dist, { recursive: true });
+    writeFileSync(join(dist, "index.html"), "<!doctype html><title>ADMIN-SPA</title>");
+    return dist;
+  }
+
+  // Seed admin + a vault so the fresh-hub wizard funnel is bypassed (the
+  // "setup complete" state where serve-app should actually engage).
+  async function setupCompleteDb(h: Harness): Promise<ReturnType<typeof openHubDb>> {
+    writeManifest({ services: [vaultEntry("default")] }, h.manifestPath);
+    const db = openHubDb(hubDbPath(h.dir));
+    await createUser(db, "owner", "pw");
+    return db;
+  }
+
+  test("serves the app index.html at `/` (200, text/html, no redirect, no chrome)", async () => {
+    const h = makeHarness();
+    const db = await setupCompleteDb(h);
+    try {
+      setRootMode(db, "serve-app");
+      const dist = makeAppDist(h.dir);
+      const res = await hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+        resolveAppDist: () => dist,
+      })(req("/"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toContain("text/html");
+      const body = await res.text();
+      expect(body).toContain("PARACHUTE-APP-SHELL");
+      // No identity chrome injected on the root-served app HTML.
+      expect(body).not.toContain('class="auth-indicator"');
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+
+  test("serves an app asset from dist (/assets/*) with an inferred content-type", async () => {
+    const h = makeHarness();
+    const db = await setupCompleteDb(h);
+    try {
+      setRootMode(db, "serve-app");
+      const dist = makeAppDist(h.dir);
+      const res = await hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+        resolveAppDist: () => dist,
+      })(req("/assets/app-xyz.js", { headers: { accept: "*/*" } }));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type") ?? "").toMatch(/javascript/);
+      expect(await res.text()).toContain("serve-app");
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+
+  test("SPA-fallback: an unclaimed HTML deep link gets the app shell", async () => {
+    const h = makeHarness();
+    const db = await setupCompleteDb(h);
+    try {
+      setRootMode(db, "serve-app");
+      const dist = makeAppDist(h.dir);
+      const res = await hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+        resolveAppDist: () => dist,
+      })(req("/some/app/deep/link", { headers: { accept: "text/html" } }));
+      expect(res.status).toBe(200);
+      expect(await res.text()).toContain("PARACHUTE-APP-SHELL");
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+
+  test("a non-HTML unclaimed path keeps the branded 404 (not the app shell)", async () => {
+    const h = makeHarness();
+    const db = await setupCompleteDb(h);
+    try {
+      setRootMode(db, "serve-app");
+      const dist = makeAppDist(h.dir);
+      const res = await hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+        resolveAppDist: () => dist,
+      })(req("/definitely/not/a/file.json", { headers: { accept: "application/json" } }));
+      expect(res.status).toBe(404);
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+
+  test("a malformed percent-encoded asset path 404s (not 500) through the real dispatch", async () => {
+    const h = makeHarness();
+    const db = await setupCompleteDb(h);
+    try {
+      setRootMode(db, "serve-app");
+      const dist = makeAppDist(h.dir);
+      // `%ZZ` is an invalid escape — decodeURIComponent throws. Without the
+      // guard in serveAppAtRoot this escapes to the dispatch outer catch → 500.
+      const res = await hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+        resolveAppDist: () => dist,
+      })(req("/assets/%ZZ", { headers: { accept: "text/html" } }));
+      expect(res.status).toBe(404);
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+
+  test("app-not-installed falls back to the redirect (with resolveAppDist → null)", async () => {
+    const h = makeHarness();
+    const db = await setupCompleteDb(h);
+    try {
+      setRootMode(db, "serve-app");
+      const res = await hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+        resolveAppDist: () => null, // app not installed
+      })(req("/"));
+      // Falls through to the redirect (default /admin).
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toBe("/admin");
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+
+  // --- Precedence: the funnels + hub-owned routes preempt serve-app ---------
+
+  test("fresh-hub wizard funnel WINS over serve-app (no admin → `/` 302 /admin/setup)", async () => {
+    const h = makeHarness();
+    // NO admin user, NO vault → needsWizard. serve-app is set + app resolvable.
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      setRootMode(db, "serve-app");
+      const dist = makeAppDist(h.dir);
+      const res = await hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+        resolveAppDist: () => dist,
+      })(req("/"));
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toBe("/admin/setup");
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+
+  test("pre-admin 503 lockout WINS over serve-app (no admin → /api/* 503 setup_required)", async () => {
+    const h = makeHarness();
+    const db = openHubDb(hubDbPath(h.dir)); // no admin
+    try {
+      setRootMode(db, "serve-app");
+      const dist = makeAppDist(h.dir);
+      const res = await hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+        resolveAppDist: () => dist,
+      })(req("/api/hub"));
+      expect(res.status).toBe(503);
+      const body = (await res.json()) as { error?: string };
+      expect(body.error).toBe("setup_required");
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+
+  test("/admin stays reachable in serve-app mode (dispatched before the tail, not the app shell)", async () => {
+    const h = makeHarness();
+    const db = await setupCompleteDb(h);
+    try {
+      setRootMode(db, "serve-app");
+      const appDist = makeAppDist(h.dir);
+      const adminDist = makeAdminDist(h.dir);
+      const res = await hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+        spaDistDir: adminDist,
+        resolveAppDist: () => appDist,
+      })(req("/admin"));
+      expect(res.status).toBe(200);
+      const body = await res.text();
+      expect(body).toContain("ADMIN-SPA");
+      expect(body).not.toContain("PARACHUTE-APP-SHELL");
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+
+  test("reserved /api|/oauth|/.well-known unclaimed paths keep the branded 404 (not the app shell)", async () => {
+    const h = makeHarness();
+    const db = await setupCompleteDb(h);
+    try {
+      setRootMode(db, "serve-app");
+      const dist = makeAppDist(h.dir);
+      const handler = hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+        resolveAppDist: () => dist,
+      });
+      // A browser navigation (Accept: text/html) to an unmatched /api path must
+      // NOT be shelled — it keeps the branded 404 for the API namespace.
+      const res = await handler(req("/api/nonexistent", { headers: { accept: "text/html" } }));
+      expect(res.status).toBe(404);
+      expect(await res.text()).not.toContain("PARACHUTE-APP-SHELL");
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+
+  // --- Regression pin: redirect mode is byte-identical to before ------------
+
+  test("redirect mode (default) is inert even with resolveAppDist wired — `/` still 302s /admin", async () => {
+    const h = makeHarness();
+    const db = await setupCompleteDb(h); // no root_mode set → default redirect
+    try {
+      const dist = makeAppDist(h.dir);
+      const handler = hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+        resolveAppDist: () => dist, // wired but must stay inert in redirect mode
+      });
+      const rootRes = await handler(req("/"));
+      expect(rootRes.status).toBe(302);
+      expect(rootRes.headers.get("location")).toBe("/admin");
+      // The 404 tail is unchanged too: an unclaimed HTML path is the branded
+      // 404 page, NOT the app shell.
+      const tailRes = await handler(req("/random/unclaimed", { headers: { accept: "text/html" } }));
+      expect(tailRes.status).toBe(404);
+      expect(await tailRes.text()).not.toContain("PARACHUTE-APP-SHELL");
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+
+  test("a non-GET `/` in serve-app mode keeps its 302 (only GET serves the app)", async () => {
+    const h = makeHarness();
+    const db = await setupCompleteDb(h);
+    try {
+      setRootMode(db, "serve-app");
+      const dist = makeAppDist(h.dir);
+      const res = await hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+        resolveAppDist: () => dist,
+      })(req("/", { method: "POST" }));
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toBe("/admin");
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+});