@openparachute/hub 0.7.4-rc.2 → 0.7.4-rc.21

package/src/hub-server.ts

@@ -69,9 +69,11 @@
  *   # "CSRF-belted" = strict same-origin Origin check on cookie-authed
  *   # mutations (hub#632, boundary C1) — origin-check.ts
  *   # `assertSameOriginForCookieMutation` carries the canonical enumeration.
- *   /api/me                       (GET)        → who-am-I (session+CSRF or hasSession:false)
+ *   /api/me                       (GET)        → who-am-I (session+CSRF+two_factor_enabled or hasSession:false)
  *   /api/admin-lock               (GET)        → screen-lock status (cookie-gated; first-admin)
  *   /api/admin-lock/{set,change,remove,unlock,lock,heartbeat} (POST) → manage the optional admin idle PIN lock (cookie-gated; CSRF)
+ *   /api/account/2fa/{start,confirm,disable} (POST) → self-service 2FA for the SPA (cookie-gated; CSRF; self-only) — hub#85
+ *   /api/account/password         (POST)       → self-service password change for the SPA (cookie-gated; CSRF; self-only) — hub#85
  *   /api/hub                      (GET)        → hub version + uptime + install-source (host:admin)
  *   /api/hub/upgrade              (POST)       → SPA-driven hub self-upgrade → 202 + detached helper (host:admin, §5.3/D4)
  *   /api/hub/upgrade/status       (GET)        → poll the on-disk hub-upgrade status (host:admin)
@@ -85,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
@@ -169,7 +172,7 @@ import {
   handleOAuthGrantCallback,
 } from "./admin-agent-grants.ts";
 import { handleAgentToken } from "./admin-agent-token.ts";
-import { handleApproveClient, handleGetClient } from "./admin-clients.ts";
+import { handleApproveClient, handleDeleteClient, handleGetClient } from "./admin-clients.ts";
 import {
   type ConnectionsDeps,
   handleConnections,
@@ -186,6 +189,7 @@ import { handleHostAdminToken } from "./admin-host-admin-token.ts";
 import { handleModuleToken } from "./admin-module-token.ts";
 import { handleVaultAdminToken } from "./admin-vault-admin-token.ts";
 import { handleCreateVault, handleDeleteVault } from "./admin-vaults.ts";
+import { handleApiAccount } from "./api-account-2fa.ts";
 import {
   handleAccountChangePasswordGet,
   handleAccountChangePasswordPost,
@@ -214,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,
@@ -243,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 {
@@ -2476,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
@@ -2500,7 +2514,7 @@ export function hubFetch(
       if (pathname === "/") {
         return new Response(null, {
           status: 302,
-          headers: { location: "/admin" },
+          headers: { location: resolveRootRedirect(getDb ? getDb() : null) },
         });
       }
 
@@ -2764,6 +2778,34 @@ export function hubFetch(
         return applyCorsHeaders(req, await handleRevoke(getDb(), req, oauthDeps(req)));
       }
 
+      // RFC 7592 client deregistration: DELETE /oauth/clients/<id> (hub#640).
+      // Mounted at this TOP-LEVEL `/oauth/clients/` prefix — NOT under
+      // `/api/oauth/clients/` — because that's the path parachute-surface's
+      // remove-flow actually calls (`packages/surface-host/src/dcr.ts` fires a
+      // best-effort DELETE on every Notes/Claude reconnect, carrying the
+      // operator token as a Bearer). Without it the hub 404'd every such
+      // DELETE and orphaned a `clients` row per reconnect. Operator-bearer-
+      // gated (parachute:host:admin) inside handleDeleteClient; 204 on delete,
+      // 404 if absent. CORS-wrapped + OPTIONS-preflighted like its OAuth
+      // siblings (the top-of-dispatch isCorsAllowedRoute("/oauth/") preempts
+      // the preflight). The GET/approve sub-paths stay on `/api/oauth/clients/`
+      // (the SPA-facing admin surface) below.
+      if (pathname.startsWith("/oauth/clients/")) {
+        if (!getDb) return applyCorsHeaders(req, dbNotConfigured());
+        const clientId = decodeURIComponent(pathname.slice("/oauth/clients/".length));
+        if (!clientId || clientId.includes("/")) {
+          return applyCorsHeaders(req, new Response("not found", { status: 404 }));
+        }
+        return applyCorsHeaders(
+          req,
+          await handleDeleteClient(req, clientId, {
+            db: getDb(),
+            issuer: oauthDeps(req).issuer,
+            knownIssuers: oauthDeps(req).hubBoundOrigins(),
+          }),
+        );
+      }
+
       // Agent-connector OAuth-client callback (Phase 4b-2). The operator's
       // browser is redirected here by a REMOTE issuer after consenting to a
       // `kind:mcp` grant. Standalone server-rendered route — NOT under /admin/*,
@@ -2801,6 +2843,7 @@ export function hubFetch(
         return handleCreateVault(req, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
         });
       }
 
@@ -2827,6 +2870,7 @@ export function hubFetch(
         return handleDeleteVault(req, name, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
           manifestPath,
           connectionsStorePath: deps?.connectionsStorePath ?? join(CONFIG_DIR, "connections.json"),
           agentOrigin,
@@ -2983,6 +3027,10 @@ export function hubFetch(
         const agentGrantsDeps: AgentGrantsDeps = {
           db: getDb(),
           hubOrigin: oauthDeps(req).issuer,
+          // hub#516 parity: validate the module's host-admin bearer `iss`
+          // against the hub's known-origin set (PUT /admin/grants is the only
+          // bearer-gated route here; the POST /approve|/revoke are cookie-authed).
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
           storePath: deps?.agentGrantsStorePath ?? join(CONFIG_DIR, "agent-grants.json"),
           flowsStorePath:
             deps?.agentOAuthFlowsStorePath ?? join(CONFIG_DIR, "agent-oauth-flows.json"),
@@ -3044,6 +3092,24 @@ export function hubFetch(
         return handleAdminLock(req, subpath, { db: getDb() });
       }
 
+      // JSON self-service account surfaces for the admin SPA "My account" page
+      // (hub#85): password change + 2FA enroll/confirm/disable. Self-only
+      // (acts on `session.userId`, never a client-supplied id) — ANY signed-in
+      // user, not just the first admin. Same cookie + CSRF + same-origin
+      // posture as /api/admin-lock above (NOT the host-admin Bearer posture —
+      // a user managing their own credentials needs no admin scope). The
+      // server-rendered /account/2fa + /account/change-password pages stay for
+      // the no-JS / friend-facing path; these are the JSON twins.
+      if (pathname.startsWith("/api/account/")) {
+        if (!getDb) return dbNotConfigured();
+        {
+          const rejected = assertSameOriginForCookieMutation(req, oauthDeps(req).hubBoundOrigins());
+          if (rejected) return rejected;
+        }
+        const subpath = pathname.slice("/api/account".length);
+        return handleApiAccount(req, subpath, { db: getDb() });
+      }
+
       // SPA-driven hub self-upgrade (design 2026-06-01 §5.3 / D4). Dedicated
       // endpoint — the hub is NOT a supervised module (no /api/modules/hub/*),
       // so it gets its own route. Checked BEFORE the `/api/hub` exact match
@@ -3057,6 +3123,7 @@ export function hubFetch(
         return handleHubUpgrade(req, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
           configDir: CONFIG_DIR,
         });
       }
@@ -3065,6 +3132,7 @@ export function hubFetch(
         return handleHubUpgradeStatus(req, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
           configDir: CONFIG_DIR,
         });
       }
@@ -3077,6 +3145,7 @@ export function hubFetch(
         return handleApiHub(req, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
         });
       }
 
@@ -3112,6 +3181,7 @@ export function hubFetch(
         return handleApiModulesChannel(req, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
         });
       }
 
@@ -3125,11 +3195,25 @@ export function hubFetch(
         return handleApiSettingsHubOrigin(req, {
           db,
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
           resolvedIssuer: resolveIssuer(req, db, configuredIssuer, loadExposeHubOrigin),
           resolvedSource: resolveIssuerSource(db, configuredIssuer, loadExposeHubOrigin),
         });
       }
 
+      // 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,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
+        });
+      }
+
       // 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.
@@ -3229,6 +3313,7 @@ export function hubFetch(
         return handleApiMintToken(req, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
           knownVaultNames: mintKnownVaultNames,
         });
       }
@@ -3238,6 +3323,7 @@ export function hubFetch(
         return handleApiRevokeToken(req, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
         });
       }
 
@@ -3246,6 +3332,7 @@ export function hubFetch(
         return handleApiTokens(req, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
         });
       }
 
@@ -3254,6 +3341,7 @@ export function hubFetch(
         return handleListGrants(req, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
         });
       }
 
@@ -3266,6 +3354,7 @@ export function hubFetch(
         return handleRevokeGrant(req, clientId, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
         });
       }
 
@@ -3288,6 +3377,7 @@ export function hubFetch(
           return handleApproveClient(req, clientId, {
             db: getDb(),
             issuer: oauthDeps(req).issuer,
+            knownIssuers: oauthDeps(req).hubBoundOrigins(),
           });
         }
         const clientId = decodeURIComponent(tail);
@@ -3297,6 +3387,7 @@ export function hubFetch(
         return handleGetClient(req, clientId, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
         });
       }
 
@@ -3312,6 +3403,7 @@ export function hubFetch(
         const usersDeps = {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
           manifestPath,
         };
         if (req.method === "GET") return handleListUsers(req, usersDeps);
@@ -3323,6 +3415,7 @@ export function hubFetch(
         return handleListVaults(req, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
           manifestPath,
         });
       }
@@ -3342,6 +3435,7 @@ export function hubFetch(
           return handleResetUserPassword(req, id, {
             db: getDb(),
             issuer: oauthDeps(req).issuer,
+            knownIssuers: oauthDeps(req).hubBoundOrigins(),
             manifestPath,
           });
         }
@@ -3360,6 +3454,7 @@ export function hubFetch(
           return handleUpdateUserVaults(req, id, {
             db: getDb(),
             issuer: oauthDeps(req).issuer,
+            knownIssuers: oauthDeps(req).hubBoundOrigins(),
             manifestPath,
           });
         }
@@ -3373,6 +3468,7 @@ export function hubFetch(
         return handleDeleteUser(req, id, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
           manifestPath,
         });
       }
@@ -3382,7 +3478,12 @@ export function hubFetch(
       // lists (status-annotated), DELETE /:id revokes by sha256 hash.
       if (pathname === "/api/invites") {
         if (!getDb) return dbNotConfigured();
-        const invitesDeps = { db: getDb(), issuer: oauthDeps(req).issuer, manifestPath };
+        const invitesDeps = {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
+          manifestPath,
+        };
         if (req.method === "GET") return handleListInvites(req, invitesDeps);
         if (req.method === "POST") return handleCreateInvite(req, invitesDeps);
         return new Response("method not allowed", { status: 405 });
@@ -3396,6 +3497,7 @@ export function hubFetch(
         return handleRevokeInvite(req, id, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
           manifestPath,
         });
       }
@@ -3408,6 +3510,7 @@ export function hubFetch(
         return handleListVaultCaps(req, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
           manifestPath,
         });
       }
@@ -3420,6 +3523,7 @@ export function hubFetch(
         return handleSetVaultCap(req, name, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
           manifestPath,
         });
       }
@@ -3824,13 +3928,57 @@ async function decorateWithChrome(
   if (setCookie && out !== res) {
     const headers = new Headers(out.headers);
     headers.append("set-cookie", setCookie);
-    return new Response(out.body, {
-      status: out.status,
-      statusText: out.statusText,
-      headers,
-    });
+    return withProxySecurityHeaders(
+      new Response(out.body, {
+        status: out.status,
+        statusText: out.statusText,
+        headers,
+      }),
+    );
   }
-  return out;
+  // hub#643: every exit runs through the security-header step, which self-
+  // gates on content-type — so a non-HTML pass-through (`out === res`, e.g. a
+  // 502 proxy error or a JSON/asset body) is returned unchanged, preserving
+  // the pre-existing behavior for those responses.
+  return withProxySecurityHeaders(out);
+}
+
+/**
+ * hub#643 (Tier-1): stamp non-script security headers on proxied `text/html`
+ * pages — the per-vault `/vault/<name>/*` proxy and the generic
+ * services-mount `/<mount>/*` proxy both flow through `decorateWithChrome`,
+ * so this is the single chokepoint that covers a module / surface page.
+ *
+ *   - `X-Content-Type-Options: nosniff` — stops content-type sniffing.
+ *   - `Content-Security-Policy: frame-ancestors 'self'; object-src 'none';
+ *     base-uri 'self'` — clickjacking (external framing) + plugin + base-tag
+ *     hardening.
+ *
+ * Deliberately NO `script-src`: a strict script-src would white-screen
+ * self-built GitHub-hosted surfaces (the primary surface story) and
+ * inline-script module pages. The opt-in strict script-src CSP is Tier-2,
+ * explicitly deferred (hub#643 stays open).
+ *
+ * Header-only: we never buffer the body. Only `text/html` responses are
+ * decorated, so JSON / `.js` / CSS / image assets proxied through the same
+ * path are left untouched. Existing headers are preserved (a fresh Headers
+ * copy is mutated); we set (not append) so a re-decorated response can't
+ * accumulate duplicates.
+ */
+function withProxySecurityHeaders(res: Response): Response {
+  const contentType = res.headers.get("content-type") ?? "";
+  if (!contentType.toLowerCase().includes("text/html")) return res;
+  const headers = new Headers(res.headers);
+  headers.set("x-content-type-options", "nosniff");
+  headers.set(
+    "content-security-policy",
+    "frame-ancestors 'self'; object-src 'none'; base-uri 'self'",
+  );
+  return new Response(res.body, {
+    status: res.status,
+    statusText: res.statusText,
+    headers,
+  });
 }
 
 if (import.meta.main) {

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;
+}

package/src/jwt-sign.ts

@@ -483,11 +483,26 @@ export interface ValidatedAccessToken {
  * this hub advertises — the same check vault performs against its own
  * `PARACHUTE_HUB_ORIGIN`. Defense in depth: tokens forged or replayed from
  * a different issuer get rejected at validation as well as issuance.
+ *
+ * `expectedIssuer` accepts a single string OR a SET of allowed issuers
+ * (`readonly string[]`), handed straight to jose's `issuer` option (which
+ * accepts `string | string[]`): the `iss` claim must equal the string, or be
+ * a member of the set. The set form is for the hub's own self-issued
+ * credentials, whose `iss` may be ANY origin the hub legitimately answers on
+ * (loopback ∪ expose-state ∪ platform ∪ per-request issuer — see
+ * `buildHubBoundOrigins`), so an origin switch doesn't reject a credential
+ * minted under a still-valid prior origin. SECURITY: this is ONLY an additive
+ * membership relaxation on `iss`. jose verifies the JWS signature against the
+ * hub's own public key FIRST and UNCONDITIONALLY — only tokens this hub
+ * minted can verify — before the `iss` claim is ever compared to the set. The
+ * set must come only from `buildHubBoundOrigins` (the hub's own origins),
+ * never a raw request Host. An empty/omitted value skips the `iss` check
+ * (signature-only); a single string is byte-identical to the prior behavior.
  */
 export async function validateAccessToken(
   db: Database,
   token: string,
-  expectedIssuer?: string,
+  expectedIssuer?: string | readonly string[],
 ): Promise<ValidatedAccessToken> {
   const header = decodeProtectedHeader(token);
   const kid = header.kid;
@@ -495,11 +510,15 @@ export async function validateAccessToken(
   const match = getAllPublicKeys(db).find((k) => k.kid === kid);
   if (!match) throw new Error(`validateAccessToken: unknown or expired kid ${kid}`);
   const pub = await importSPKI(match.publicKeyPem, SIGNING_ALGORITHM);
-  const { payload } = await jwtVerify(
-    token,
-    pub,
-    expectedIssuer ? { issuer: expectedIssuer } : undefined,
-  );
+  // `undefined` → no `iss` pin (signature-only, the internal-caller default).
+  // A string or a non-empty set is handed straight to jose, which checks
+  // membership AFTER the signature verify above. An empty array is passed
+  // through too and so fails closed (no `iss` can match) — same posture as
+  // `validateHostAdminToken`; callers offering an empty origin set get a
+  // rejection, not a silent widening.
+  const issuerOption =
+    expectedIssuer === undefined ? undefined : { issuer: expectedIssuer as string | string[] };
+  const { payload } = await jwtVerify(token, pub, issuerOption);
   // RFC 7009 revocation enforcement (#73). OAuth-issued tokens carry a
   // tokens row keyed by jti; if that row is marked revoked, the JWT is
   // dead even though its signature + expiry are still valid. Tokens that