@openparachute/hub 0.7.4-rc.19 → 0.7.4-rc.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.4-rc.19",
+  "version": "0.7.4-rc.20",
   "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

@@ -0,0 +1,302 @@
+/**
+ * Tests for `/api/settings/root-redirect`.
+ *
+ * Covers:
+ *   - `validateRootRedirect` pure validator (null/empty clear, safe path,
+ *     open-redirect rejection).
+ *   - GET response shape (root_redirect + resolved + source).
+ *   - PUT happy path + open-redirect rejection (the highest-stakes part).
+ *   - PUT clear (null) reverts to env/default precedence.
+ *   - Auth gating: 401 missing/empty bearer, 403 wrong scope.
+ *   - "Change takes effect on the next request" — the GET resolved value
+ *     reflects the value just written, without restarting.
+ */
+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 {
+  API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE,
+  handleApiSettingsRootRedirect,
+  validateRootRedirect,
+} from "../api-settings-root-redirect.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { getRootRedirect, setRootRedirect } from "../hub-settings.ts";
+import { recordTokenMint, 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 {
+  dir: string;
+  db: ReturnType<typeof openHubDb>;
+  userId: string;
+  cleanup: () => void;
+}
+
+async function makeHarness(): Promise<Harness> {
+  const dir = mkdtempSync(join(tmpdir(), "phub-api-settings-root-redirect-"));
+  const db = openHubDb(hubDbPath(dir));
+  rotateSigningKey(db);
+  const user = await createUser(db, "owner", "pw");
+  return {
+    dir,
+    db,
+    userId: user.id,
+    cleanup: () => {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+async function mintBearer(h: Harness, scopes: string[]): Promise<string> {
+  const signed = await signAccessToken(h.db, {
+    sub: h.userId,
+    scopes,
+    audience: "parachute-hub",
+    clientId: "parachute-hub",
+    issuer: ISSUER,
+    ttlSeconds: 3600,
+  });
+  recordTokenMint(h.db, {
+    jti: signed.jti,
+    createdVia: "operator_mint",
+    subject: h.userId,
+    clientId: "parachute-hub",
+    scopes,
+    expiresAt: signed.expiresAt,
+  });
+  return signed.token;
+}
+
+function getReq(headers: Record<string, string> = {}): Request {
+  return new Request("http://localhost/api/settings/root-redirect", { method: "GET", headers });
+}
+
+function putReq(body: unknown, headers: Record<string, string> = {}): Request {
+  return new Request("http://localhost/api/settings/root-redirect", {
+    method: "PUT",
+    headers: { "content-type": "application/json", ...headers },
+    body: typeof body === "string" ? body : JSON.stringify(body),
+  });
+}
+
+// Empty env so the resolver's env layer is deterministic (the host's real
+// PARACHUTE_HUB_ROOT_REDIRECT must not leak into GET's resolved/source).
+const noEnv: NodeJS.ProcessEnv = {};
+
+function deps(
+  h: Harness,
+  overrides: Partial<Parameters<typeof handleApiSettingsRootRedirect>[1]> = {},
+) {
+  return {
+    db: h.db,
+    issuer: ISSUER,
+    env: noEnv,
+    ...overrides,
+  };
+}
+
+describe("validateRootRedirect — pure validator", () => {
+  test("null → normalized null (clear)", () => {
+    expect(validateRootRedirect(null)).toEqual({ ok: true, normalized: null });
+  });
+
+  test("empty string → normalized null (clear footgun guard)", () => {
+    expect(validateRootRedirect("")).toEqual({ ok: true, normalized: null });
+  });
+
+  test("safe same-origin path → normalized verbatim", () => {
+    expect(validateRootRedirect("/surface/reading-room")).toEqual({
+      ok: true,
+      normalized: "/surface/reading-room",
+    });
+  });
+
+  test("rejects off-origin + scheme shapes", () => {
+    for (const bad of [
+      "//evil.com",
+      "/\\evil.com",
+      "https://evil.com",
+      "javascript:alert(1)",
+      "admin",
+      "/",
+    ]) {
+      const r = validateRootRedirect(bad);
+      expect(r.ok).toBe(false);
+    }
+  });
+
+  test("rejects non-string non-null", () => {
+    expect(validateRootRedirect(42).ok).toBe(false);
+    expect(validateRootRedirect({}).ok).toBe(false);
+  });
+});
+
+describe("auth gating", () => {
+  let h: Harness;
+  beforeEach(async () => {
+    h = await makeHarness();
+  });
+  afterEach(() => h.cleanup());
+
+  test("405 on non-GET/PUT", async () => {
+    const res = await handleApiSettingsRootRedirect(
+      new Request("http://localhost/api/settings/root-redirect", { method: "POST" }),
+      deps(h),
+    );
+    expect(res.status).toBe(405);
+  });
+
+  test("401 when Authorization header is missing", async () => {
+    const res = await handleApiSettingsRootRedirect(getReq(), deps(h));
+    expect(res.status).toBe(401);
+  });
+
+  test("401 on empty bearer", async () => {
+    const res = await handleApiSettingsRootRedirect(getReq({ authorization: "Bearer " }), deps(h));
+    expect(res.status).toBe(401);
+  });
+
+  test("403 when the bearer lacks the required scope", async () => {
+    const bearer = await mintBearer(h, ["parachute:host:auth"]);
+    const resGet = await handleApiSettingsRootRedirect(
+      getReq({ authorization: `Bearer ${bearer}` }),
+      deps(h),
+    );
+    expect(resGet.status).toBe(403);
+    const resPut = await handleApiSettingsRootRedirect(
+      putReq({ root_redirect: "/surface/x" }, { authorization: `Bearer ${bearer}` }),
+      deps(h),
+    );
+    expect(resPut.status).toBe(403);
+    // Nothing was written.
+    expect(getRootRedirect(h.db)).toBeNull();
+  });
+});
+
+describe("GET /api/settings/root-redirect", () => {
+  let h: Harness;
+  beforeEach(async () => {
+    h = await makeHarness();
+  });
+  afterEach(() => h.cleanup());
+
+  test("default shape when unset: /admin from the default layer", async () => {
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const res = await handleApiSettingsRootRedirect(
+      getReq({ authorization: `Bearer ${bearer}` }),
+      deps(h),
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body).toEqual({ root_redirect: null, resolved: "/admin", source: "default" });
+  });
+
+  test("reflects a stored value with source=db", async () => {
+    setRootRedirect(h.db, "/surface/reading-room");
+    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).toEqual({
+      root_redirect: "/surface/reading-room",
+      resolved: "/surface/reading-room",
+      source: "db",
+    });
+  });
+
+  test("surfaces an env-sourced resolved value 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_REDIRECT: "/surface/from-env" } }),
+    );
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body).toEqual({
+      root_redirect: null,
+      resolved: "/surface/from-env",
+      source: "env",
+    });
+  });
+});
+
+describe("PUT /api/settings/root-redirect", () => {
+  let h: Harness;
+  beforeEach(async () => {
+    h = await makeHarness();
+  });
+  afterEach(() => h.cleanup());
+
+  test("stores a safe path + 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_redirect: "/surface/reading-room" }, { authorization: `Bearer ${bearer}` }),
+      deps(h),
+    );
+    expect(put.status).toBe(200);
+    expect((await put.json()) as unknown).toEqual({ root_redirect: "/surface/reading-room" });
+    expect(getRootRedirect(h.db)).toBe("/surface/reading-room");
+
+    const get = await handleApiSettingsRootRedirect(
+      getReq({ authorization: `Bearer ${bearer}` }),
+      deps(h),
+    );
+    const body = (await get.json()) as Record<string, unknown>;
+    expect(body.resolved).toBe("/surface/reading-room");
+    expect(body.source).toBe("db");
+  });
+
+  test("null clears the row", async () => {
+    setRootRedirect(h.db, "/surface/x");
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const res = await handleApiSettingsRootRedirect(
+      putReq({ root_redirect: null }, { authorization: `Bearer ${bearer}` }),
+      deps(h),
+    );
+    expect(res.status).toBe(200);
+    expect(getRootRedirect(h.db)).toBeNull();
+  });
+
+  test("rejects open-redirect payloads with 400 and writes nothing", async () => {
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    for (const bad of [
+      "//evil.com",
+      "https://evil.com",
+      "javascript:alert(1)",
+      "/\\evil.com",
+      "/",
+    ]) {
+      const res = await handleApiSettingsRootRedirect(
+        putReq({ root_redirect: bad }, { 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_redirect");
+      expect(getRootRedirect(h.db)).toBeNull();
+    }
+  });
+
+  test("400 on a body without a root_redirect field", async () => {
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const res = await handleApiSettingsRootRedirect(
+      putReq({ wrong: "x" }, { authorization: `Bearer ${bearer}` }),
+      deps(h),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test("400 on non-JSON body", async () => {
+    const bearer = await mintBearer(h, [API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE]);
+    const res = await handleApiSettingsRootRedirect(
+      putReq("not json{", { authorization: `Bearer ${bearer}` }),
+      deps(h),
+    );
+    expect(res.status).toBe(400);
+  });
+});

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

@@ -12,9 +12,9 @@ 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, rewriteCaddyfileHost } from "../commands/hub.ts";
+import { hub, hubSetOrigin, hubSetRootRedirect, rewriteCaddyfileHost } from "../commands/hub.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
-import { getHubOrigin } from "../hub-settings.ts";
+import { getHubOrigin, getRootRedirect } from "../hub-settings.ts";
 import type { CommandResult } from "../tailscale/run.ts";
 
 describe("parachute hub set-origin", () => {
@@ -431,3 +431,70 @@ describe("parachute hub set-origin — Caddy automation", () => {
     expect(log.join("\n")).toContain("already points at old.example.com");
   });
 });
+
+describe("parachute hub set-root-redirect", () => {
+  let dir: string;
+  let log: string[];
+  const collect = (line: string) => log.push(line);
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "hub-set-root-redirect-"));
+    log = [];
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  /** Open the configDir's hub.db and read the persisted root_redirect. */
+  function persisted(): string | null {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      return getRootRedirect(db);
+    } finally {
+      db.close();
+    }
+  }
+
+  test("persists a safe same-origin path to hub_settings.root_redirect", async () => {
+    const code = await hubSetRootRedirect(["/surface/reading-room"], {
+      configDir: dir,
+      log: collect,
+    });
+    expect(code).toBe(0);
+    expect(persisted()).toBe("/surface/reading-room");
+  });
+
+  test("--clear deletes the row", async () => {
+    await hubSetRootRedirect(["/surface/x"], { configDir: dir, log: collect });
+    const code = await hubSetRootRedirect(["--clear"], { configDir: dir, log: collect });
+    expect(code).toBe(0);
+    expect(persisted()).toBeNull();
+  });
+
+  test("rejects an open-redirect path without writing", async () => {
+    for (const bad of ["//evil.com", "https://evil.com", "/\\evil.com", "/"]) {
+      const code = await hubSetRootRedirect([bad], { configDir: dir, log: collect });
+      expect(code).toBe(1);
+      expect(persisted()).toBeNull();
+    }
+  });
+
+  test("rejects a path with no leading slash without writing", async () => {
+    const code = await hubSetRootRedirect(["surface/x"], { configDir: dir, log: collect });
+    expect(code).toBe(1);
+    expect(persisted()).toBeNull();
+  });
+
+  test("usage error (exit 1) when no path + no --clear", async () => {
+    const code = await hubSetRootRedirect([], { configDir: dir, log: collect });
+    expect(code).toBe(1);
+    expect(persisted()).toBeNull();
+  });
+
+  test("routed through the `hub` dispatcher", async () => {
+    const code = await hub(["set-root-redirect", "/surface/via-dispatcher"], {
+      configDir: dir,
+      log: collect,
+    });
+    expect(code).toBe(0);
+    expect(persisted()).toBe("/surface/via-dispatcher");
+  });
+});

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

@@ -12,8 +12,10 @@ import { join } from "node:path";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import {
   DEFAULT_MODULE_INSTALL_CHANNEL,
+  DEFAULT_ROOT_REDIRECT,
   FIRST_CLIENT_AUTO_APPROVE_WINDOW_MS,
   MODULE_INSTALL_CHANNELS,
+  PARACHUTE_HUB_ROOT_REDIRECT_ENV,
   PARACHUTE_INSTALL_CHANNEL_ENV,
   PARACHUTE_MODULE_CHANNEL_ENV,
   SETUP_EXPOSE_MODES,
@@ -21,15 +23,20 @@ import {
   deleteSetting,
   getHubOrigin,
   getModuleInstallChannel,
+  getRootRedirect,
   getSetting,
   isFirstClientAutoApproveWindowOpen,
   isModuleInstallChannel,
   isNotesRedirectDisabled,
+  isSafeRedirectPath,
   isSetupExposeMode,
   openFirstClientAutoApproveWindow,
+  resolveRootRedirect,
+  resolveRootRedirectDetailed,
   setHubOrigin,
   setModuleInstallChannel,
   setNotesRedirectDisabled,
+  setRootRedirect,
   setSetting,
 } from "../hub-settings.ts";
 
@@ -613,3 +620,184 @@ describe("hub-settings — notes_redirect_disabled (parachute-app §16)", () =>
     }
   });
 });
+
+describe("hub-settings — isSafeRedirectPath (open-redirect guard)", () => {
+  test("accepts plain same-origin relative paths", () => {
+    expect(isSafeRedirectPath("/admin")).toBe(true);
+    expect(isSafeRedirectPath("/surface/reading-room")).toBe(true);
+    expect(isSafeRedirectPath("/vault/default/")).toBe(true);
+    // Query + fragment stay same-origin → allowed.
+    expect(isSafeRedirectPath("/surface/x?view=reading#top")).toBe(true);
+    // Deep paths with hyphens/dots/underscores (regression: a botched
+    // whitespace regex once rejected `-`).
+    expect(isSafeRedirectPath("/a-b_c.d/e")).toBe(true);
+  });
+
+  test("rejects protocol-relative + backslash authority tricks", () => {
+    expect(isSafeRedirectPath("//evil.com")).toBe(false);
+    expect(isSafeRedirectPath("//evil.com/path")).toBe(false);
+    expect(isSafeRedirectPath("/\\evil.com")).toBe(false);
+    expect(isSafeRedirectPath("/\\\\evil.com")).toBe(false);
+  });
+
+  test("rejects absolute URLs + scheme payloads", () => {
+    expect(isSafeRedirectPath("https://evil.com")).toBe(false);
+    expect(isSafeRedirectPath("http://evil.com/x")).toBe(false);
+    // biome-ignore lint/suspicious/noExplicitAny: testing the runtime guard with a hostile string
+    expect(isSafeRedirectPath("javascript:alert(1)" as any)).toBe(false);
+    expect(isSafeRedirectPath("data:text/html,<script>1</script>")).toBe(false);
+  });
+
+  test("rejects values missing a leading slash", () => {
+    expect(isSafeRedirectPath("admin")).toBe(false);
+    expect(isSafeRedirectPath("evil.com")).toBe(false);
+    expect(isSafeRedirectPath("")).toBe(false);
+  });
+
+  test("rejects pathname-`/` targets (would 302-loop the bare-`/` route)", () => {
+    expect(isSafeRedirectPath("/")).toBe(false);
+    expect(isSafeRedirectPath("/?next=x")).toBe(false);
+    expect(isSafeRedirectPath("/#frag")).toBe(false);
+  });
+
+  test("rejects whitespace + control chars (header-injection / normalization)", () => {
+    expect(isSafeRedirectPath("/admin\r\nSet-Cookie: x=1")).toBe(false);
+    expect(isSafeRedirectPath("/ad min")).toBe(false);
+    expect(isSafeRedirectPath("/admin\t")).toBe(false);
+    expect(isSafeRedirectPath("/\tadmin")).toBe(false);
+    expect(isSafeRedirectPath("/admin ")).toBe(false);
+    // U+2028 line separator (stripped by some parsers) — built via charCode so
+    // the source file carries no irregular-whitespace literal.
+    expect(isSafeRedirectPath(`/admin${String.fromCharCode(0x2028)}x`)).toBe(false);
+  });
+
+  test("rejects non-string inputs", () => {
+    // biome-ignore lint/suspicious/noExplicitAny: exercising the runtime type guard
+    expect(isSafeRedirectPath(null as any)).toBe(false);
+    // biome-ignore lint/suspicious/noExplicitAny: exercising the runtime type guard
+    expect(isSafeRedirectPath(undefined as any)).toBe(false);
+    // biome-ignore lint/suspicious/noExplicitAny: exercising the runtime type guard
+    expect(isSafeRedirectPath(42 as any)).toBe(false);
+    // biome-ignore lint/suspicious/noExplicitAny: exercising the runtime type guard
+    expect(isSafeRedirectPath({} as any)).toBe(false);
+  });
+});
+
+describe("hub-settings — root_redirect storage + resolution", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "hub-settings-root-redirect-"));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  // An empty env so the resolver's env layer is deterministic (the host's real
+  // PARACHUTE_HUB_ROOT_REDIRECT, if any, must not leak in).
+  const noEnv: NodeJS.ProcessEnv = {};
+  const silent = () => {};
+
+  test("getRootRedirect round-trips via setRootRedirect", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      expect(getRootRedirect(db)).toBeNull();
+      setRootRedirect(db, "/surface/reading-room");
+      expect(getRootRedirect(db)).toBe("/surface/reading-room");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("setRootRedirect(null) / empty clears the row", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      setRootRedirect(db, "/surface/x");
+      setRootRedirect(db, null);
+      expect(getRootRedirect(db)).toBeNull();
+      setRootRedirect(db, "/surface/x");
+      setRootRedirect(db, "");
+      expect(getRootRedirect(db)).toBeNull();
+    } finally {
+      db.close();
+    }
+  });
+
+  test("resolves to /admin default when neither DB nor env is set", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      expect(resolveRootRedirect(db, { env: noEnv })).toBe(DEFAULT_ROOT_REDIRECT);
+      expect(resolveRootRedirectDetailed(db, { env: noEnv })).toEqual({
+        value: "/admin",
+        source: "default",
+      });
+    } finally {
+      db.close();
+    }
+  });
+
+  test("env override applies when no DB row", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const env = { [PARACHUTE_HUB_ROOT_REDIRECT_ENV]: "/surface/from-env" };
+      expect(resolveRootRedirectDetailed(db, { env })).toEqual({
+        value: "/surface/from-env",
+        source: "env",
+      });
+    } finally {
+      db.close();
+    }
+  });
+
+  test("DB row overrides env (DB is tier-1)", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      setRootRedirect(db, "/surface/from-db");
+      const env = { [PARACHUTE_HUB_ROOT_REDIRECT_ENV]: "/surface/from-env" };
+      expect(resolveRootRedirectDetailed(db, { env })).toEqual({
+        value: "/surface/from-db",
+        source: "db",
+      });
+    } finally {
+      db.close();
+    }
+  });
+
+  test("an unsafe DB row is ignored → falls through to env", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      // Simulate a hand-edited sqlite row that bypassed write-side validation.
+      setSetting(db, "root_redirect", "//evil.com");
+      const env = { [PARACHUTE_HUB_ROOT_REDIRECT_ENV]: "/surface/from-env" };
+      expect(resolveRootRedirect(db, { env, warn: silent })).toBe("/surface/from-env");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("an unsafe DB row with no env → falls all the way back to /admin", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      setSetting(db, "root_redirect", "https://evil.com");
+      expect(resolveRootRedirect(db, { env: noEnv, warn: silent })).toBe("/admin");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("an unsafe env value is ignored → falls back to /admin", () => {
+    const db = openHubDb(hubDbPath(dir));
+    try {
+      const env = { [PARACHUTE_HUB_ROOT_REDIRECT_ENV]: "//evil.com" };
+      expect(resolveRootRedirectDetailed(db, { env, warn: silent })).toEqual({
+        value: "/admin",
+        source: "default",
+      });
+    } finally {
+      db.close();
+    }
+  });
+
+  test("a null db (no state) resolves from env / default only", () => {
+    expect(resolveRootRedirect(null, { env: noEnv })).toBe("/admin");
+    const env = { [PARACHUTE_HUB_ROOT_REDIRECT_ENV]: "/surface/from-env" };
+    expect(resolveRootRedirect(null, { env })).toBe("/surface/from-env");
+  });
+});

package/src/__tests__/setup-gate.test.ts

@@ -31,6 +31,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { hubFetch } from "../hub-server.ts";
+import { setRootRedirect, setSetting } from "../hub-settings.ts";
 import { writeManifest } from "../services-manifest.ts";
 import { createUser } from "../users.ts";
 
@@ -101,9 +102,7 @@ describe("setup gate (no admin yet)", () => {
   test("/login POST still 503s setup_required when no admin exists (hub#644)", async () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {
-      const res = await hubFetch(h.dir, { getDb: () => db })(
-        req("/login", { method: "POST" }),
-      );
+      const res = await hubFetch(h.dir, { getDb: () => db })(req("/login", { method: "POST" }));
       expect(res.status).toBe(503);
       const body = (await res.json()) as Record<string, unknown>;
       expect(body.error).toBe("setup_required");
@@ -368,3 +367,112 @@ describe("setup gate (admin exists)", () => {
     }
   });
 });
+
+describe("configurable bare-`/` redirect target", () => {
+  let h: Harness;
+  beforeEach(() => {
+    h = makeHarness();
+  });
+  afterEach(() => h.cleanup());
+
+  /** A set-up hub (admin + vault) so the bare-`/` redirect is reached. */
+  function setUpHub(db: ReturnType<typeof openHubDb>): void {
+    writeManifest(
+      {
+        services: [
+          {
+            name: "parachute-vault",
+            version: "0.1.0",
+            port: 1940,
+            paths: ["/vault/default"],
+            health: "/health",
+          },
+        ],
+      },
+      join(h.dir, "services.json"),
+    );
+  }
+
+  function handler(db: ReturnType<typeof openHubDb>) {
+    return hubFetch(h.dir, { getDb: () => db, manifestPath: join(h.dir, "services.json") });
+  }
+
+  test("a configured root_redirect retargets the bare-`/` 302", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      setUpHub(db);
+      setRootRedirect(db, "/surface/reading-room");
+      const res = await handler(db)(req("/"));
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toBe("/surface/reading-room");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("an unsafe stored root_redirect falls back to /admin (never an open redirect)", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      setUpHub(db);
+      // A hand-edited sqlite row that bypassed write-side validation.
+      setSetting(db, "root_redirect", "//evil.com");
+      const res = await handler(db)(req("/"));
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toBe("/admin");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("PARACHUTE_HUB_ROOT_REDIRECT env retargets the bare-`/` 302 (no DB row)", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    const prev = process.env.PARACHUTE_HUB_ROOT_REDIRECT;
+    process.env.PARACHUTE_HUB_ROOT_REDIRECT = "/surface/from-env";
+    try {
+      await createUser(db, "owner", "pw");
+      setUpHub(db);
+      const res = await handler(db)(req("/"));
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toBe("/surface/from-env");
+    } finally {
+      // Restore process.env to its pre-test state. `delete` (not assign-undefined,
+      // which would coerce to the string "undefined") removes a key we added.
+      if (prev === undefined) {
+        // biome-ignore lint/performance/noDelete: env-key cleanup, not a hot path
+        delete process.env.PARACHUTE_HUB_ROOT_REDIRECT;
+      } else {
+        process.env.PARACHUTE_HUB_ROOT_REDIRECT = prev;
+      }
+      db.close();
+    }
+  });
+
+  test("wizard funnel WINS: a configured root_redirect does NOT bypass setup on a fresh hub", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      // No admin yet → not-set-up hub. Even with a surface configured, the
+      // bare-`/` must funnel to the wizard, not a surface that can't work yet.
+      setRootRedirect(db, "/surface/reading-room");
+      const res = await handler(db)(req("/"));
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toBe("/admin/setup");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("default is unchanged: bare-`/` → /admin when nothing is configured", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      setUpHub(db);
+      const res = await handler(db)(req("/"));
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toBe("/admin");
+    } finally {
+      db.close();
+    }
+  });
+});

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

@@ -0,0 +1,188 @@
+/**
+ * `GET|PUT /api/settings/root-redirect` — operator-settable target for the
+ * bare-`/` 302.
+ *
+ * The hub's root (`/`) redirects to `/admin` by default. This endpoint lets an
+ * operator point it at a surface instead (e.g. a custom-domain hub fronting a
+ * team reading-room surface) without redeploying. The stored value resolves
+ * tier-1 in `resolveRootRedirect` (hub-settings.ts):
+ *
+ *   1. hub_settings.root_redirect (this endpoint writes here)
+ *   2. PARACHUTE_HUB_ROOT_REDIRECT env
+ *   3. `/admin` default (unchanged behavior)
+ *
+ * The endpoint surfaces both the stored value *and* the resolved value + source
+ * so the SPA can render "current: /surface/x (from env)" while the input shows
+ * the empty stored row — same separation rationale as `/api/settings/hub-origin`.
+ *
+ * OPEN-REDIRECT SAFETY is the highest-stakes part: the resolved value lands in a
+ * `Location:` header, so an off-origin value would be a textbook open redirect.
+ * PUT validation (and the read-time resolver) require a SAME-ORIGIN relative
+ * path via `isSafeRedirectPath` — must start with a single `/`, never `//` /
+ * `/\` / a scheme, no control chars / whitespace, and must not resolve back to
+ * `/` (redirect loop). Anything else is rejected (PUT 400 / resolver fallback to
+ * `/admin`).
+ *
+ * Bearer-gated on `parachute:host:admin`, mirroring `handleApiSettingsHubOrigin`
+ * — same Bearer parsing, scope-check posture, and error vocabulary.
+ */
+
+import type { Database } from "bun:sqlite";
+import {
+  type RootRedirectSource,
+  getRootRedirect,
+  isSafeRedirectPath,
+  resolveRootRedirectDetailed,
+  setRootRedirect,
+} from "./hub-settings.ts";
+import { validateAccessToken } from "./jwt-sign.ts";
+
+/** Scope required on the bearer token to call either endpoint. */
+export const API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE = "parachute:host:admin";
+
+export interface ApiSettingsRootRedirectDeps {
+  db: Database;
+  /** Issuer the bearer token must validate against (the hub's resolved issuer). */
+  issuer: string;
+  /**
+   * Env seam for the resolver's env layer. Defaults to `process.env`. Threaded
+   * so the dispatcher (and tests) can resolve `PARACHUTE_HUB_ROOT_REDIRECT`
+   * deterministically.
+   */
+  env?: NodeJS.ProcessEnv;
+}
+
+interface GetResponseBody {
+  /** Raw stored value from hub_settings.root_redirect, or null. */
+  root_redirect: string | null;
+  /** Resolved target applied to the bare-`/` 302 (precedence-aware, guarded). */
+  resolved: string;
+  /** Which precedence layer the resolved value came from. */
+  source: RootRedirectSource;
+}
+
+interface PutResponseBody {
+  /** Echo of the now-stored value (null if cleared). */
+  root_redirect: string | null;
+}
+
+/**
+ * Validation outcome. The "normalized" branch is what gets passed to
+ * setRootRedirect — string (a safe path) or null (clear the row).
+ */
+type ValidateOutcome = { ok: true; normalized: string | null } | { ok: false; description: string };
+
+/**
+ * Validate the body's `root_redirect` field. Accepts:
+ *   - `null` (or empty string) → clear the stored value, revert to env/default.
+ *   - A safe SAME-ORIGIN relative path per `isSafeRedirectPath`.
+ * Everything else → 400 with an operator-friendly description.
+ */
+export function validateRootRedirect(value: unknown): ValidateOutcome {
+  if (value === null) return { ok: true, normalized: null };
+  if (typeof value !== "string") {
+    return {
+      ok: false,
+      description: `root_redirect must be a string or null (got ${typeof value})`,
+    };
+  }
+  // Empty string is the canonical "clear" shape — store as null (mirrors
+  // setHubOrigin's footgun guard; an empty Location would be meaningless).
+  if (value.length === 0) return { ok: true, normalized: null };
+  if (!isSafeRedirectPath(value)) {
+    return {
+      ok: false,
+      description:
+        "root_redirect must be a same-origin relative path (start with a single `/`, no `//`/`/\\`/scheme, no whitespace, and not `/` itself)",
+    };
+  }
+  return { ok: true, normalized: value };
+}
+
+export async function handleApiSettingsRootRedirect(
+  req: Request,
+  deps: ApiSettingsRootRedirectDeps,
+): Promise<Response> {
+  if (req.method !== "GET" && req.method !== "PUT") {
+    return jsonError(405, "method_not_allowed", "use GET or PUT");
+  }
+
+  // Bearer presence + parsing — identical shape to api-settings-hub-origin
+  // for consistency across hub-internal admin endpoints.
+  const auth = req.headers.get("authorization");
+  if (!auth || !auth.startsWith("Bearer ")) {
+    return jsonError(401, "unauthenticated", "Authorization: Bearer <token> required");
+  }
+  const bearer = auth.slice("Bearer ".length).trim();
+  if (!bearer) {
+    return jsonError(401, "unauthenticated", "empty bearer token");
+  }
+
+  // Bearer validation + scope check.
+  try {
+    const validated = await validateAccessToken(deps.db, bearer, deps.issuer);
+    if (typeof validated.payload.sub !== "string" || validated.payload.sub.length === 0) {
+      return jsonError(401, "unauthenticated", "bearer token has no sub claim");
+    }
+    const scopes =
+      typeof validated.payload.scope === "string"
+        ? validated.payload.scope.split(/\s+/).filter((s) => s.length > 0)
+        : [];
+    if (!scopes.includes(API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE)) {
+      return jsonError(
+        403,
+        "insufficient_scope",
+        `bearer token lacks ${API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE}`,
+      );
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return jsonError(401, "unauthenticated", `bearer token invalid — ${msg}`);
+  }
+
+  if (req.method === "GET") {
+    const resolved = resolveRootRedirectDetailed(deps.db, { env: deps.env });
+    const body: GetResponseBody = {
+      root_redirect: getRootRedirect(deps.db),
+      resolved: resolved.value,
+      source: resolved.source,
+    };
+    return new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  }
+
+  // PUT — parse + validate body.
+  let parsed: unknown;
+  try {
+    parsed = await req.json();
+  } catch {
+    return jsonError(400, "invalid_request", "request body must be JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return jsonError(400, "invalid_request", "request body must be a JSON object");
+  }
+  if (!("root_redirect" in parsed)) {
+    return jsonError(400, "invalid_request", "request body must include a `root_redirect` field");
+  }
+  const result = validateRootRedirect((parsed as { root_redirect: unknown }).root_redirect);
+  if (!result.ok) {
+    return jsonError(400, "invalid_root_redirect", result.description);
+  }
+
+  setRootRedirect(deps.db, result.normalized);
+
+  const body: PutResponseBody = { root_redirect: result.normalized };
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function jsonError(status: number, code: string, description: string): Response {
+  return new Response(JSON.stringify({ error: code, error_description: description }), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}

package/src/commands/hub.ts

@@ -32,7 +32,12 @@ import { validateHubOrigin } from "../api-settings-hub-origin.ts";
 import { restart } from "../commands/lifecycle.ts";
 import { CONFIG_DIR } from "../config.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
-import { setHubOrigin } from "../hub-settings.ts";
+import {
+  DEFAULT_ROOT_REDIRECT,
+  isSafeRedirectPath,
+  setHubOrigin,
+  setRootRedirect,
+} from "../hub-settings.ts";
 import { type CommandResult, type Runner, defaultRunner } from "../tailscale/run.ts";
 import { isLoopbackOrigin } from "../vault-hub-origin-env.ts";
 
@@ -347,6 +352,81 @@ async function runCaddyReload(run: Runner): Promise<CommandResult> {
   return run(["systemctl", "reload", "caddy"]);
 }
 
+/**
+ * `parachute hub set-root-redirect <path>` — persist the operator's bare-`/`
+ * redirect target into `hub_settings.root_redirect` (tier-1 in
+ * `resolveRootRedirect`). Lets a headless box (the canonical use case is a
+ * custom-domain hub fronting a team surface) flip its landing page from `/admin`
+ * to a surface without a browser session OR a redeploy.
+ *
+ * `--clear` deletes the row, reverting to the env / `/admin` default.
+ *
+ * The path is validated through `isSafeRedirectPath` — the SAME open-redirect
+ * guard the admin PUT enforces — so the CLI can never plant an off-origin
+ * `Location` target either. Returns 0 on success, 1 on a usage / validation /
+ * DB-write failure.
+ */
+export async function hubSetRootRedirect(
+  args: readonly string[],
+  deps: HubCommandDeps = {},
+): Promise<number> {
+  const configDir = deps.configDir ?? CONFIG_DIR;
+  const log = deps.log ?? ((line) => console.log(line));
+  const err = (line: string) => console.error(line);
+  const openDb = deps.openDb ?? ((dir: string) => openHubDb(hubDbPath(dir)));
+
+  const clear = args.includes("--clear");
+  const positional = args.filter((a) => !a.startsWith("-"));
+
+  if (clear) {
+    if (positional.length > 0) {
+      err("parachute hub set-root-redirect: --clear takes no path argument");
+      return 1;
+    }
+    const db = openDb(configDir);
+    try {
+      setRootRedirect(db, null);
+    } finally {
+      db.close();
+    }
+    log(
+      `✓ Cleared the root redirect — \`/\` reverts to env / the ${DEFAULT_ROOT_REDIRECT} default.`,
+    );
+    return 0;
+  }
+
+  const raw = positional[0];
+  if (raw === undefined) {
+    err("usage: parachute hub set-root-redirect <path>   (or --clear)");
+    err("example: parachute hub set-root-redirect /surface/reading-room");
+    return 1;
+  }
+  if (positional.length > 1) {
+    err(`parachute hub set-root-redirect: unexpected argument "${positional[1]}"`);
+    err("usage: parachute hub set-root-redirect <path>   (or --clear)");
+    return 1;
+  }
+
+  if (!isSafeRedirectPath(raw)) {
+    err(`parachute hub set-root-redirect: "${raw}" is not a safe same-origin path`);
+    err("  It must start with a single `/` (no `//`, `/\\`, scheme, or whitespace) and");
+    err("  not be `/` itself. Example: /surface/reading-room");
+    return 1;
+  }
+
+  const db = openDb(configDir);
+  try {
+    setRootRedirect(db, raw);
+  } finally {
+    db.close();
+  }
+
+  log(`✓ Bare \`/\` now redirects to ${raw}.`);
+  log("  Stored in hub_settings.root_redirect — takes effect on the next request,");
+  log("  no restart needed. Clear it with: parachute hub set-root-redirect --clear");
+  return 0;
+}
+
 /**
  * `parachute hub <subcommand>` dispatcher. Mirrors `auth`'s shape (a thin
  * router over subcommand handlers, each catching its own errors).
@@ -367,6 +447,16 @@ export async function hub(args: readonly string[], deps: HubCommandDeps = {}): P
       return 1;
     }
   }
+  if (sub === "set-root-redirect") {
+    try {
+      return await hubSetRootRedirect(args.slice(1), deps);
+    } catch (err) {
+      console.error(
+        `parachute hub set-root-redirect: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return 1;
+    }
+  }
   console.error(`parachute hub: unknown subcommand "${sub}"`);
   console.error("");
   console.error(hubHelp());
@@ -378,6 +468,7 @@ export function hubHelp(): string {
 
 Usage:
   parachute hub set-origin <url> [--no-caddy] [--no-restart]
+  parachute hub set-root-redirect <path> | --clear
 
 Subcommands:
   set-origin <url>    Persist the canonical public origin (OAuth issuer) to the
@@ -401,9 +492,19 @@ Subcommands:
                       Caddyfile rewrite + reload, or --no-restart to skip the
                       module restart.
 
+  set-root-redirect <path>
+                      Point the bare \`/\` 302 at a same-origin path instead of the
+                      default /admin (e.g. a team surface). Stored in
+                      hub_settings.root_redirect; takes effect on the next request,
+                      no restart. The path must start with a single \`/\` (no \`//\`,
+                      \`/\\\`, scheme, or whitespace). Pass --clear to revert to the
+                      env / /admin default. (Env equivalent: PARACHUTE_HUB_ROOT_REDIRECT.)
+
 Examples:
   parachute hub set-origin https://box.sslip.io
   parachute hub set-origin https://parachute.example.com
   parachute hub set-origin https://parachute.example.com --no-caddy
+  parachute hub set-root-redirect /surface/reading-room
+  parachute hub set-root-redirect --clear
 `;
 }

package/src/hub-server.ts

@@ -87,6 +87,7 @@
  *   /api/modules/:short/uninstall (POST)       → stop child + bun remove + drop row (sync)
  *   /api/modules/operations/:id   (GET)        → poll async op status
  *   /api/settings/hub-origin      (GET + PUT)  → canonical hub URL (host:admin)
+ *   /api/settings/root-redirect   (GET + PUT)  → bare-`/` redirect target (host:admin)
  *   /api/auth/mint-token          (POST)       → CLI/automation token mint (bearer)
  *   /api/auth/revoke-token        (POST)       → revoke registry-row token by jti
  *   /api/auth/tokens              (GET)        → paginated registry list
@@ -217,6 +218,7 @@ import { handleApiReady } from "./api-ready.ts";
 import { REVOCATION_LIST_MOUNT, handleRevocationList } from "./api-revocation-list.ts";
 import { handleApiRevokeToken } from "./api-revoke-token.ts";
 import { handleApiSettingsHubOrigin } from "./api-settings-hub-origin.ts";
+import { handleApiSettingsRootRedirect } from "./api-settings-root-redirect.ts";
 import { handleApiTokens } from "./api-tokens.ts";
 import {
   handleCreateUser,
@@ -246,7 +248,7 @@ import {
   startDbPathLivenessTimer,
 } from "./hub-db-liveness.ts";
 import { hubDbPath, openHubDb } from "./hub-db.ts";
-import { getHubOrigin } from "./hub-settings.ts";
+import { getHubOrigin, resolveRootRedirect } from "./hub-settings.ts";
 import { type RenderHubOpts, renderHub } from "./hub.ts";
 import { pemToJwk } from "./jwks.ts";
 import {
@@ -2479,23 +2481,32 @@ export function hubFetch(
         );
       }
 
-      // Bare `/` → `/admin` (admin-shell IA, R1). The home page and the admin
-      // SPA used to be two disconnected surfaces; `/` now funnels straight into
-      // the single coherent admin shell, whose Home/Overview carries the
-      // discovery content (hub-native sections, modules, user surfaces) that
-      // used to live here.
+      // Bare `/` → configurable target (default `/admin`, the admin-shell IA).
+      // The home page and the admin SPA used to be two disconnected surfaces;
+      // `/` funnels straight into the single coherent admin shell, whose
+      // Home/Overview carries the discovery content (hub-native sections,
+      // modules, user surfaces) that used to live here.
+      //
+      // The target is operator-configurable (resolveRootRedirect): a hub_settings
+      // `root_redirect` row → `PARACHUTE_HUB_ROOT_REDIRECT` env → `/admin`
+      // default. Lets an operator point their hub's root at a surface (e.g. a
+      // team reading-room) instead of the admin shell, without redeploying. The
+      // resolver re-validates every layer through the same-origin guard
+      // (`isSafeRedirectPath`) so a stored/env value can NEVER produce an open
+      // redirect — an unsafe value is ignored and falls back to `/admin`.
       //
       // Ordering matters: this sits AFTER the fresh-hub wizard funnel above
-      // (so a brand-new operator still lands on `/admin/setup`, not a 404 inside
-      // the shell) and AFTER the pre-admin lockout (so an admin-less hub still
-      // 503s API callers correctly). 302 (not 301) — `/` is reclaimed for
-      // future use, but a permanent redirect would get cached and we may want
-      // `/` back later.
+      // (so a brand-new operator still lands on `/admin/setup`, not a surface
+      // that can't work yet) and AFTER the pre-admin lockout (so an admin-less
+      // hub still 503s API callers correctly). 302 (not 301) — the target is
+      // operator-mutable, so a permanent/cached redirect would strand visitors
+      // on a stale destination after the operator flips it.
       //
-      // The signed-out path is preserved: a signed-out visitor lands on
-      // `/admin`, where the SPA's AuthIndicator shows a "Sign in" link that
-      // round-trips through `/login?next=/admin/...` and back. We don't pin the
-      // redirect on session state — the shell handles both auth states itself.
+      // The signed-out path is preserved when the target is `/admin`: a
+      // signed-out visitor lands on `/admin`, where the SPA's AuthIndicator
+      // shows a "Sign in" link that round-trips through `/login?next=/admin/...`
+      // and back. We don't pin the redirect on session state — the shell
+      // handles both auth states itself.
       //
       // `/hub.html` is INTENTIONALLY excluded: it still renders the discovery
       // page (used by the static `parachute expose --set-path=/` disk file and
@@ -2503,7 +2514,7 @@ export function hubFetch(
       if (pathname === "/") {
         return new Response(null, {
           status: 302,
-          headers: { location: "/admin" },
+          headers: { location: resolveRootRedirect(getDb ? getDb() : null) },
         });
       }
 
@@ -3178,6 +3189,18 @@ export function hubFetch(
         });
       }
 
+      // Bare-`/` redirect target (configurable; default `/admin`). Admin SPA /
+      // CLI reads + writes the operator-set landing page. Same Bearer/scope
+      // posture as hub-origin; the open-redirect guard lives in the handler +
+      // resolver.
+      if (pathname === "/api/settings/root-redirect") {
+        if (!getDb) return dbNotConfigured();
+        return handleApiSettingsRootRedirect(req, {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+        });
+      }
+
       // Module operation poll surface — pre-empts the /api/modules/:short/*
       // routes below so `/api/modules/operations/<uuid>` doesn't accidentally
       // match a parseModulesPath("/operations") and fall through.

package/src/hub-settings.ts

@@ -106,7 +106,23 @@ export type HubSettingKey =
   // Idle timeout for the admin screen-lock, in seconds. Optional override of
   // the built-in default (DEFAULT_ADMIN_LOCK_IDLE_SECONDS). Stored as a
   // stringified integer; absent / unparseable falls back to the default.
-  | "admin_lock_idle_seconds";
+  | "admin_lock_idle_seconds"
+  // hub: operator-settable target for the bare-`/` 302. Lets an operator
+  // point their hub's root at a surface (e.g. a team reading-room surface)
+  // instead of the default `/admin`. Stored as a SAME-ORIGIN relative path
+  // (must start with a single `/`, never `//` / `/\` / a scheme — see
+  // `isSafeRedirectPath`); validated on write (admin PUT + CLI) AND re-checked
+  // on read so a hand-edited sqlite row can never produce an open redirect.
+  //
+  // Precedence on each request (resolveRootRedirect): this row, then
+  // `PARACHUTE_HUB_ROOT_REDIRECT` env, then the `/admin` default. DB-first
+  // (unlike `module_install_channel`'s env-first) so an operator can flip the
+  // landing page from the admin SPA / CLI without a redeploy — the headline
+  // use case (custom-domain hub fronting a team surface). The fresh-hub
+  // wizard funnel + pre-admin 503 lockout run BEFORE this redirect, so a
+  // not-yet-set-up hub still lands on setup, not a surface that can't work
+  // yet.
+  | "root_redirect";
 
 export type SetupExposeMode = "localhost" | "tailnet" | "public";
 
@@ -431,3 +447,149 @@ export function setNotesRedirectDisabled(db: Database, value: boolean): void {
     deleteSetting(db, "notes_redirect_disabled");
   }
 }
+
+// --- domain helpers: configurable bare-`/` redirect target ----------------
+
+/** Env override for the bare-`/` redirect target. Below the DB row, above the default. */
+export const PARACHUTE_HUB_ROOT_REDIRECT_ENV = "PARACHUTE_HUB_ROOT_REDIRECT";
+
+/** Fallback when neither DB row nor env is set — the admin shell (unchanged behavior). */
+export const DEFAULT_ROOT_REDIRECT = "/admin";
+
+/**
+ * Open-redirect guard for the configurable bare-`/` redirect target.
+ *
+ * The resolved value lands verbatim in a `Location:` header on the `/` 302,
+ * so an off-origin value would be a textbook open redirect. To be accepted it
+ * must be a SAME-ORIGIN relative path:
+ *
+ *   - starts with a single `/` (a site-relative path). This alone rejects
+ *     `https://evil.com`, `javascript:…`, and bare hostnames.
+ *   - second char is NOT `/` (a protocol-relative `//evil.com` sends the
+ *     browser to another origin) and NOT `\` (browsers normalize the
+ *     backslash, so `/\evil.com` resolves like `//evil.com`).
+ *   - contains no ASCII control chars or whitespace — a CR/LF would enable
+ *     header injection, and tab/newline are stripped by some browsers which
+ *     could re-expose a hidden `//` authority.
+ *   - resolves same-origin against a placeholder base (belt-and-suspenders:
+ *     `new URL(value, base).origin === base`) — catches any scheme/authority
+ *     shape the prefix checks missed.
+ *   - does NOT resolve to pathname `/` — that would re-enter this very route
+ *     and 302-loop forever (`/`, `/?x`, `/#y` all rejected).
+ *
+ * A query string / fragment on a real path is allowed (stays same-origin).
+ * Returns false for non-strings, empty, and every off-origin shape.
+ */
+export function isSafeRedirectPath(value: unknown): value is string {
+  if (typeof value !== "string" || value.length === 0) return false;
+  if (value[0] !== "/") return false;
+  if (value[1] === "/" || value[1] === "\\") return false;
+  // Reject whitespace (\t \n \r space + Unicode separators U+2028/U+2029) and
+  // ASCII control chars. A CR/LF would enable header injection; stripped
+  // whitespace could re-expose a hidden `//` authority. `\s` covers the
+  // whitespace family (incl. Unicode); the charCode scan covers the remaining
+  // non-whitespace control chars (0x00-0x1f, 0x7f) without a control-char
+  // regex literal.
+  if (/\s/u.test(value)) return false;
+  for (let i = 0; i < value.length; i++) {
+    const c = value.charCodeAt(i);
+    if (c < 0x20 || c === 0x7f) return false;
+  }
+  try {
+    const base = "http://parachute.invalid";
+    const resolved = new URL(value, base);
+    if (resolved.origin !== base) return false;
+    // pathname "/" would match the bare-`/` route again -> infinite redirect.
+    if (resolved.pathname === "/") return false;
+  } catch {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Read the operator-set bare-`/` redirect target from hub_settings. Returns
+ * the raw stored value (or `null` when absent) WITHOUT re-validating — callers
+ * that need a safe value go through `resolveRootRedirect`, which re-checks the
+ * guard. The raw read is what the admin GET surfaces so the operator sees
+ * exactly what's stored (even if a hand-edit made it unsafe → ignored on use).
+ */
+export function getRootRedirect(db: Database): string | null {
+  return getSetting(db, "root_redirect") ?? null;
+}
+
+/**
+ * Write or clear the bare-`/` redirect target. Passing `null`/empty deletes
+ * the row, reverting to env / default precedence (mirrors `setHubOrigin`).
+ * The caller MUST have validated via `isSafeRedirectPath` — this trusts the
+ * input (typed-callsite contract); `resolveRootRedirect` re-guards on read as
+ * defense-in-depth regardless.
+ */
+export function setRootRedirect(db: Database, value: string | null): void {
+  if (value === null || value === "") {
+    deleteSetting(db, "root_redirect");
+    return;
+  }
+  setSetting(db, "root_redirect", value);
+}
+
+/** Which precedence layer the resolved redirect came from. */
+export type RootRedirectSource = "db" | "env" | "default";
+
+export interface ResolvedRootRedirect {
+  /** The safe same-origin path the `/` 302 should target. */
+  value: string;
+  /** Which layer it came from (for admin-UI attribution). */
+  source: RootRedirectSource;
+}
+
+/**
+ * Resolve the bare-`/` redirect target with source attribution.
+ *
+ * Precedence: hub_settings.root_redirect → `PARACHUTE_HUB_ROOT_REDIRECT` env
+ * → `/admin` default. Every layer is re-validated through `isSafeRedirectPath`;
+ * an unsafe value at any layer is warned + skipped so the chain can never
+ * produce an open redirect (worst case falls all the way to `/admin`).
+ *
+ * `db` may be `null` (hub-server running without state) — the DB layer is then
+ * skipped and resolution starts from env. The `env` / `warn` knobs are test
+ * seams (production uses `process.env` + `console.warn`).
+ */
+export function resolveRootRedirectDetailed(
+  db: Database | null,
+  opts: { env?: NodeJS.ProcessEnv; warn?: (msg: string) => void } = {},
+): ResolvedRootRedirect {
+  const env = opts.env ?? process.env;
+  const warn = opts.warn ?? ((msg: string) => console.warn(msg));
+
+  // 1. DB row (operator-set via the admin PUT / `parachute hub set-root-redirect`).
+  if (db) {
+    const fromDb = getSetting(db, "root_redirect");
+    if (fromDb !== undefined) {
+      if (isSafeRedirectPath(fromDb)) return { value: fromDb, source: "db" };
+      warn(
+        `[hub-settings] root_redirect="${fromDb}" in hub_settings is not a safe same-origin path — ignoring (falling through to env/default).`,
+      );
+    }
+  }
+
+  // 2. Env override.
+  const fromEnv = env[PARACHUTE_HUB_ROOT_REDIRECT_ENV];
+  if (typeof fromEnv === "string" && fromEnv.length > 0) {
+    if (isSafeRedirectPath(fromEnv)) return { value: fromEnv, source: "env" };
+    warn(
+      `[hub-settings] ${PARACHUTE_HUB_ROOT_REDIRECT_ENV}="${fromEnv}" is not a safe same-origin path — falling back to "${DEFAULT_ROOT_REDIRECT}".`,
+    );
+  }
+
+  // 3. Default — unchanged behavior.
+  return { value: DEFAULT_ROOT_REDIRECT, source: "default" };
+}
+
+/** Convenience: just the resolved path (see `resolveRootRedirectDetailed`). */
+export function resolveRootRedirect(
+  db: Database | null,
+  opts: { env?: NodeJS.ProcessEnv; warn?: (msg: string) => void } = {},
+): string {
+  return resolveRootRedirectDetailed(db, opts).value;
+}