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

package/src/hub-settings.ts

@@ -133,6 +133,25 @@ export type HubSettingKey =
   // not-yet-set-up hub still lands on setup, not a surface that can't work
   // yet.
   | "root_redirect"
+  // hub: how the hub answers its origin root. `"redirect"` (default / absent)
+  // is the historical behavior — the bare `/` 302s to `root_redirect` (a safe
+  // same-origin path, default `/admin`). `"serve-app"` makes the hub SERVE the
+  // installed Parachute app's built bundle AT the origin root (index.html at
+  // `/`, its assets from the same dist, SPA-fallback for HTML deep links) — the
+  // same front-door experience as the hosted door, no redirect hop. The app's
+  // build is root-based (absolute `/assets`, PWA scope `/`, root OAuth redirect
+  // URIs) so serving its dist verbatim at `/` is asset-correct with no rebuild.
+  //
+  // Precedence on each request (resolveRootMode): this row, then
+  // `PARACHUTE_HUB_ROOT_MODE` env, then the `"redirect"` default. DB-first (like
+  // `root_redirect`) so an operator can flip the front door from the admin SPA /
+  // CLI without a redeploy. When `serve-app` is set but the app isn't installed
+  // (its dist can't be resolved), the hub FALLS BACK to redirect behavior (using
+  // `root_redirect` → env → `/admin`) with a one-time log line — so an operator
+  // who set the mode before installing the app never sees a broken root. The
+  // fresh-hub wizard funnel + pre-admin 503 lockout still run BEFORE this, so a
+  // not-yet-set-up hub lands on setup, never a half-working app shell.
+  | "root_mode"
   // hub-parity P2 (Q2): the RAW token of the newest PUBLIC (multi-use,
   // `max_uses > 1`) invite — persisted so `GET /.well-known/parachute-account`
   // can advertise `signup_path` without being able to reconstruct it from the
@@ -617,3 +636,121 @@ export function resolveRootRedirect(
 ): string {
   return resolveRootRedirectDetailed(db, opts).value;
 }
+
+// --- domain helpers: root mode (redirect vs serve the app at `/`) ---------
+
+/**
+ * How the hub answers its origin root.
+ *
+ *   - `"redirect"` — historical behavior: the bare `/` 302s to the resolved
+ *     `root_redirect` (default `/admin`). Every unclaimed path keeps the
+ *     branded 404.
+ *   - `"serve-app"` — the hub serves the installed Parachute app's built
+ *     bundle AT the origin root (index.html at `/`, its assets from the same
+ *     dist, SPA-fallback for HTML deep links), matching the hosted door's
+ *     front-door experience. Falls back to `redirect` when the app isn't
+ *     installed (dist unresolvable).
+ */
+export type RootMode = "redirect" | "serve-app";
+
+/** Exported so the API handler + the CLI can share validation. */
+export const ROOT_MODES: readonly RootMode[] = ["redirect", "serve-app"];
+
+export function isRootMode(s: unknown): s is RootMode {
+  return typeof s === "string" && ROOT_MODES.includes(s as RootMode);
+}
+
+/** Env override for the root mode. Below the DB row, above the default. */
+export const PARACHUTE_HUB_ROOT_MODE_ENV = "PARACHUTE_HUB_ROOT_MODE";
+
+/** Fallback when neither DB row nor env is set — historical redirect behavior. */
+export const DEFAULT_ROOT_MODE: RootMode = "redirect";
+
+/**
+ * Read the raw stored root mode from hub_settings (or `null` when absent),
+ * WITHOUT applying env / default precedence — mirrors `getRootRedirect`. The
+ * admin GET surfaces this raw value so the operator sees exactly what's stored.
+ */
+export function getRootMode(db: Database): RootMode | null {
+  const raw = getSetting(db, "root_mode");
+  if (raw === undefined) return null;
+  return isRootMode(raw) ? raw : null;
+}
+
+/**
+ * Write or clear the root mode. Passing `null` (or the `"redirect"` default)
+ * deletes the row, reverting to env / default precedence — the absent-row
+ * state IS the redirect default, so leaving an explicit `"redirect"` in the
+ * row would be a footgun if a future default flip ever made absence mean
+ * something else (mirrors `setRootRedirect` / `setHubOrigin` semantics). The
+ * caller must have validated via `isRootMode`; the typed signature enforces it
+ * at TypeScript-clean call sites.
+ */
+export function setRootMode(db: Database, mode: RootMode | null): void {
+  if (mode === null || mode === DEFAULT_ROOT_MODE) {
+    deleteSetting(db, "root_mode");
+    return;
+  }
+  setSetting(db, "root_mode", mode);
+}
+
+/** Which precedence layer the resolved mode came from. */
+export type RootModeSource = "db" | "env" | "default";
+
+export interface ResolvedRootMode {
+  /** The mode the origin root should apply. */
+  value: RootMode;
+  /** Which layer it came from (for admin-UI attribution + install set-if-unset). */
+  source: RootModeSource;
+}
+
+/**
+ * Resolve the root mode with source attribution.
+ *
+ * Precedence: hub_settings.root_mode → `PARACHUTE_HUB_ROOT_MODE` env →
+ * `"redirect"` default. An invalid value at any layer is warned + skipped so a
+ * hand-edited row / typo'd env can never wedge the root (worst case falls to
+ * the redirect default — today's behavior).
+ *
+ * `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 resolveRootModeDetailed(
+  db: Database | null,
+  opts: { env?: NodeJS.ProcessEnv; warn?: (msg: string) => void } = {},
+): ResolvedRootMode {
+  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-mode`).
+  if (db) {
+    const fromDb = getSetting(db, "root_mode");
+    if (fromDb !== undefined) {
+      if (isRootMode(fromDb)) return { value: fromDb, source: "db" };
+      warn(
+        `[hub-settings] root_mode="${fromDb}" in hub_settings is not a valid mode (expected one of ${ROOT_MODES.join(", ")}) — ignoring (falling through to env/default).`,
+      );
+    }
+  }
+
+  // 2. Env override.
+  const fromEnv = env[PARACHUTE_HUB_ROOT_MODE_ENV];
+  if (typeof fromEnv === "string" && fromEnv.length > 0) {
+    if (isRootMode(fromEnv)) return { value: fromEnv, source: "env" };
+    warn(
+      `[hub-settings] ${PARACHUTE_HUB_ROOT_MODE_ENV}="${fromEnv}" is not a valid mode — falling back to "${DEFAULT_ROOT_MODE}".`,
+    );
+  }
+
+  // 3. Default — historical redirect behavior.
+  return { value: DEFAULT_ROOT_MODE, source: "default" };
+}
+
+/** Convenience: just the resolved mode (see `resolveRootModeDetailed`). */
+export function resolveRootMode(
+  db: Database | null,
+  opts: { env?: NodeJS.ProcessEnv; warn?: (msg: string) => void } = {},
+): RootMode {
+  return resolveRootModeDetailed(db, opts).value;
+}

package/src/root-serve.ts

@@ -0,0 +1,156 @@
+#!/usr/bin/env bun
+
+/**
+ * Serving the Parachute app AT the hub's origin root (`root_mode = serve-app`).
+ *
+ * When an operator flips the root mode to `serve-app` (or a fresh hub installs
+ * the app during setup), the hub answers its own origin root with the installed
+ * `@openparachute/parachute-app` bundle instead of 302-ing to `/admin`. This is
+ * the self-hosted mirror of the hosted door: hit your box's URL, land in the
+ * app — no redirect hop.
+ *
+ * Why this is asset-correct with no rebuild: the app's Vite build is ROOT-based
+ * (absolute `/assets/*`, PWA scope `/`, OAuth redirect URIs at the origin root).
+ * The `/app` service mount serves the SAME dist through the `notes-serve.ts`
+ * shim with a `/app` prefix-strip; here we serve that identical dist verbatim at
+ * `/`, which is exactly the origin the build assumes. So `serveAppAtRoot` and
+ * the `/app` mount hand back byte-identical bundle files — the only difference
+ * is the URL prefix.
+ *
+ * Precedence is the caller's job (hub-server.ts): the fresh-hub setup wizard
+ * funnel and the pre-admin 503 lockout run BEFORE the root `/` handler, and
+ * every hub-owned route (/admin, /oauth, /.well-known, /vault, /git, /api,
+ * service mounts) dispatches BEFORE the SPA-fallback tail. This module only
+ * decides "given an already-unclaimed GET, does the app dist answer it?".
+ *
+ * NO chrome injection ever rides a root-served response — the app owns its whole
+ * page (same posture as the public/surface chrome opt-out). We build the
+ * responses here directly rather than routing through `decorateWithChrome`.
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { resolveNotesDistFrom } from "./notes-serve.ts";
+
+/** The npm package whose built `dist/` is the app front door. */
+export const APP_PACKAGE = "@openparachute/parachute-app";
+
+/**
+ * Namespaces that keep the hub's branded 404 even in serve-app mode. These are
+ * hub / protocol surfaces, never app client-side routes, so an SPA shell there
+ * would be wrong — and would mask a genuine 404 for an API/OAuth/well-known
+ * typo. (Real dist files never live under these prefixes anyway; this makes the
+ * "don't shell it" decision explicit rather than incidental.)
+ */
+export const ROOT_SERVE_RESERVED_PREFIXES: readonly string[] = [
+  "/api/",
+  "/oauth/",
+  "/.well-known/",
+];
+
+/**
+ * Build a resolver for the installed app's `dist/` directory.
+ *
+ * Resolution goes through the SAME `resolveNotesDistFrom` machinery the `/app`
+ * mount's static-serve shim uses (so root-serve and `/app` resolve to one dist).
+ * A SUCCESSFUL resolution is memoized for the process lifetime — a resolved dist
+ * path doesn't move while the hub runs, and re-walking `Bun.resolveSync` on every
+ * asset request would be needless work. A FAILURE is NOT cached: an operator who
+ * set `serve-app` before installing the app, then runs `parachute install app`,
+ * is picked up on the next request without a hub restart (dynamic recovery).
+ *
+ * `resolve` is the test seam (defaults to the real package resolution). Return
+ * value is the dist dir, or `null` when the app can't be resolved (not installed
+ * / ships no `dist/`).
+ */
+export function makeAppDistResolver(
+  resolve: () => string = () => resolveNotesDistFrom({ pkg: APP_PACKAGE }),
+): () => string | null {
+  let cached: string | null = null;
+  return () => {
+    if (cached !== null) return cached;
+    try {
+      cached = resolve();
+      return cached;
+    } catch {
+      return null;
+    }
+  };
+}
+
+/** MIME overrides Bun.file doesn't infer (mirrors notes-serve.ts). */
+function mimeFor(path: string): string | undefined {
+  // Without this the PWA install prompt sees text/html for the manifest + bails.
+  if (path.endsWith(".webmanifest")) return "application/manifest+json";
+  return undefined;
+}
+
+/**
+ * Answer an already-unclaimed request from the app's root-based `dist/`, or
+ * return `null` to tell the caller to fall through to its normal handling
+ * (the `/` 302 fallback, or the branded 404 tail).
+ *
+ * Contract:
+ *   - non-GET                                     → null (fall through)
+ *   - a reserved hub/protocol prefix              → null (keep the branded 404)
+ *   - GET + an existing file under dist           → that file (asset-correct MIME)
+ *   - GET `/` or a trailing-slash "dir" request   → dist/index.html (SPA shell)
+ *   - GET + no file + Accept: text/html           → dist/index.html (SPA deep link)
+ *   - GET + no file + non-HTML (API probe, etc.)  → null (branded 404)
+ *
+ * `dist` is a resolved directory (from `makeAppDistResolver`); if its
+ * `index.html` has since vanished (app uninstalled after a successful resolve)
+ * we return `null` rather than serving a broken shell.
+ */
+export function serveAppAtRoot(dist: string, req: Request, pathname: string): Response | null {
+  // Only GET is served (HEAD/POST/etc. keep the caller's default — a non-GET to
+  // an unclaimed path stays a 404, and a non-GET `/` keeps its 302).
+  if (req.method !== "GET") return null;
+
+  // Hub/protocol namespaces are never the app's — leave their 404 branded.
+  for (const prefix of ROOT_SERVE_RESERVED_PREFIXES) {
+    if (pathname.startsWith(prefix)) return null;
+  }
+
+  const indexHtml = join(dist, "index.html");
+  // The resolved bundle lost its shell (uninstalled mid-flight) → fall through.
+  if (!existsSync(indexHtml)) return null;
+
+  const spaShell = () =>
+    new Response(Bun.file(indexHtml), {
+      headers: { "content-type": "text/html; charset=utf-8" },
+    });
+
+  // Bare root or a trailing-slash "directory" request → the SPA shell.
+  if (pathname === "/" || pathname.endsWith("/")) return spaShell();
+
+  // An existing dist file: /assets/*, /icon.svg, /manifest.webmanifest, /sw.js …
+  // Malformed percent-encoding (e.g. `/foo%`, `/assets/%ZZ`) makes
+  // `decodeURIComponent` throw a URIError. Catch it and fall through to the
+  // branded 404 (redirect-mode parity) — WITHOUT the guard the throw escapes to
+  // the dispatch outer catch, which classifies a non-DB error as "other" and
+  // re-throws → a bare 500. This path is reachable pre-auth on a public expose,
+  // so a garbage-encoded asset URL must 404, never 500.
+  let decodedPath: string;
+  try {
+    decodedPath = decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+  // Path-traversal guard: the joined path must stay strictly under dist/.
+  const filePath = join(dist, decodedPath);
+  if (filePath.startsWith(`${dist}/`) && existsSync(filePath) && statSync(filePath).isFile()) {
+    const mime = mimeFor(filePath);
+    return new Response(
+      Bun.file(filePath),
+      mime ? { headers: { "content-type": mime } } : undefined,
+    );
+  }
+
+  // No matching file. Serve the SPA shell ONLY for HTML navigations (a deep link
+  // like /some-note the app routes client-side). A browser navigation sends
+  // `Accept: text/html`; a non-HTML unclaimed request (API probe, a missing
+  // asset fetched with `Accept: */*`) falls through to the branded 404.
+  const wantsHtml = (req.headers.get("accept") ?? "").includes("text/html");
+  return wantsHtml ? spaShell() : null;
+}

package/src/service-spec.ts

@@ -382,8 +382,9 @@ const APP_FALLBACK: FirstPartyFallback = {
     postInstallFooter: () => [
       "",
       "Open your Parachute at <origin>/app — it signs in with your hub account.",
-      "The hub's front page (`/`) now opens the app too, unless you've already",
-      "set a custom root redirect (`parachute hub set-root-redirect` or the admin SPA).",
+      "The hub's front page (`/`) now serves the app directly too, unless you've",
+      "already customized the root (`parachute hub set-root-mode` / `set-root-redirect`",
+      "or the admin SPA).",
     ],
   },
 };