@openparachute/hub 0.5.10 → 0.5.12-rc.2

package/src/api-settings-hub-origin.ts

@@ -0,0 +1,253 @@
+/**
+ * `GET|PUT /api/settings/hub-origin` — operator-settable canonical hub
+ * URL (hub#298).
+ *
+ * The stored value is the OAuth issuer claim hub stamps into every JWT.
+ * Precedence chain (per `resolveIssuer` in hub-server.ts):
+ *
+ *   1. hub_settings.hub_origin (this endpoint writes here)
+ *   2. PARACHUTE_HUB_ORIGIN env / --issuer flag
+ *   3. request origin (local-dev fallback)
+ *
+ * The endpoint surfaces both the stored value *and* the resolved value
+ * + source so the SPA can render "current: https://… (from env)" while
+ * the input shows the empty stored row. That separation matters: an
+ * operator looking at the SPA needs to tell "this hub already has a
+ * canonical URL configured via env" apart from "no canonical URL —
+ * tokens carry the request origin."
+ *
+ * Bearer-gated on `parachute:host:admin` (same scope as
+ * `/api/modules/channel`): flipping the issuer claim invalidates any
+ * tokens already in circulation against the prior issuer, so it's a
+ * destructive-ish operator-only action.
+ *
+ * URL validation on PUT:
+ *   - Must parse via `new URL()`.
+ *   - Scheme must be `http:` or `https:` (no `file:`, no protocol-
+ *     relative). Bare hostnames don't parse without a scheme and are
+ *     rejected upstream by URL.
+ *   - Must have a hostname (rejects `https:///path`).
+ *   - No trailing slash (the stored value is concatenated into JWT iss
+ *     claims + well-known URLs — a trailing slash would produce
+ *     `https://host//.well-known/…`).
+ *   - No path / query / fragment (only origin shape allowed).
+ *
+ * The shape mirrors `handleApiModulesChannel` for consistency — same
+ * Bearer parsing, same scope-check posture, same error vocabulary.
+ */
+
+import type { Database } from "bun:sqlite";
+import type { IssuerSource } from "./hub-server.ts";
+import { getHubOrigin, setHubOrigin } from "./hub-settings.ts";
+import { validateAccessToken } from "./jwt-sign.ts";
+
+/** Scope required on the bearer token to call either endpoint. */
+export const API_SETTINGS_HUB_ORIGIN_REQUIRED_SCOPE = "parachute:host:admin";
+
+export interface ApiSettingsHubOriginDeps {
+  db: Database;
+  issuer: string;
+  /**
+   * The currently-resolved issuer + its source layer. Computed by the
+   * dispatcher (which has the request + `configuredIssuer` already in
+   * hand) and threaded through so this handler doesn't have to re-do
+   * the precedence walk. Returned on GET.
+   */
+  resolvedIssuer: string;
+  resolvedSource: IssuerSource;
+}
+
+interface GetResponseBody {
+  /** Stored value from hub_settings.hub_origin, or null. */
+  hub_origin: string | null;
+  /** Resolved issuer applied to this request (precedence-aware). */
+  resolved_issuer: string;
+  /** Which precedence layer the resolved value came from. */
+  source: IssuerSource;
+}
+
+interface PutResponseBody {
+  /** Echo of the now-stored value (null if cleared). */
+  hub_origin: string | null;
+}
+
+/**
+ * Validation outcome. The "normalized" branch is what gets passed to
+ * setHubOrigin — string or null. Errors carry the field name + a short
+ * description that flows into the 400 error_description for an
+ * operator-friendly message.
+ */
+type ValidateOutcome = { ok: true; normalized: string | null } | { ok: false; description: string };
+
+/**
+ * Validate the body's `hub_origin` field. Accepts:
+ *   - `null` → clear the stored value, revert to env/request precedence.
+ *   - A `http:` or `https:` URL string with a hostname, no trailing slash,
+ *     no path/query/fragment.
+ * Everything else → 400.
+ */
+export function validateHubOrigin(value: unknown): ValidateOutcome {
+  if (value === null) return { ok: true, normalized: null };
+  if (typeof value !== "string") {
+    return {
+      ok: false,
+      description: `hub_origin must be a string or null (got ${typeof value})`,
+    };
+  }
+  if (value.length === 0) {
+    // Empty string is a footgun shape — store as null instead. We don't
+    // want a row that resolveIssuer would skip as falsy while
+    // resolveIssuerSource claims "from settings."
+    return { ok: true, normalized: null };
+  }
+  if (value.endsWith("/")) {
+    return {
+      ok: false,
+      description: "hub_origin must not have a trailing slash",
+    };
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return {
+      ok: false,
+      description: "hub_origin must be a valid URL",
+    };
+  }
+  // Reject embedded credentials explicitly. The normalization step below
+  // re-stringifies as `protocol + "//" + host`, which would silently strip
+  // any user:pass component — an operator who typos credentials in
+  // wouldn't notice the strip. Surface it as a hard error instead.
+  if (parsed.username || parsed.password) {
+    return {
+      ok: false,
+      description: "hub_origin must not include credentials",
+    };
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return {
+      ok: false,
+      description: `hub_origin scheme must be http: or https: (got ${parsed.protocol})`,
+    };
+  }
+  if (!parsed.hostname) {
+    return {
+      ok: false,
+      description: "hub_origin must have a hostname",
+    };
+  }
+  // Disallow path/query/fragment — the stored value is concatenated
+  // into iss claims and well-known URLs. `new URL("https://host")`
+  // returns `pathname === "/"` so accept that as the canonical empty.
+  if (parsed.pathname !== "" && parsed.pathname !== "/") {
+    return {
+      ok: false,
+      description: "hub_origin must not include a path",
+    };
+  }
+  if (parsed.search) {
+    return {
+      ok: false,
+      description: "hub_origin must not include a query string",
+    };
+  }
+  if (parsed.hash) {
+    return {
+      ok: false,
+      description: "hub_origin must not include a fragment",
+    };
+  }
+  // Normalize: URL stringifies host-only inputs with a trailing slash
+  // (`new URL("https://host").toString() === "https://host/"`). The
+  // stored shape is the bare origin — strip it back out.
+  const normalized = `${parsed.protocol}//${parsed.host}`;
+  return { ok: true, normalized };
+}
+
+export async function handleApiSettingsHubOrigin(
+  req: Request,
+  deps: ApiSettingsHubOriginDeps,
+): 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-modules
+  // 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_HUB_ORIGIN_REQUIRED_SCOPE)) {
+      return jsonError(
+        403,
+        "insufficient_scope",
+        `bearer token lacks ${API_SETTINGS_HUB_ORIGIN_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 body: GetResponseBody = {
+      hub_origin: getHubOrigin(deps.db),
+      resolved_issuer: deps.resolvedIssuer,
+      source: deps.resolvedSource,
+    };
+    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 (!("hub_origin" in parsed)) {
+    return jsonError(400, "invalid_request", "request body must include a `hub_origin` field");
+  }
+  const result = validateHubOrigin((parsed as { hub_origin: unknown }).hub_origin);
+  if (!result.ok) {
+    return jsonError(400, "invalid_hub_origin", result.description);
+  }
+
+  setHubOrigin(deps.db, result.normalized);
+
+  const body: PutResponseBody = { hub_origin: 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/bootstrap-token.ts

@@ -0,0 +1,153 @@
+/**
+ * Bootstrap token for first-boot wizard claim (hub#297).
+ *
+ * On a fresh deploy with no admin row AND no `PARACHUTE_INITIAL_ADMIN_*`
+ * env-seed, the hub enters "wizard mode" — the `/admin/setup` URL is
+ * unauthenticated and the first POST to `/admin/setup/account` claims
+ * the admin. On a public-reachable deploy (Render, Fly, a tailnet with
+ * funnel on) the URL is reachable the moment the platform provisions
+ * the hostname, so an attacker who beats the operator to the form can
+ * claim the admin themselves. Same shape HashiCorp Vault hardens with
+ * its `vault operator init` unseal-key dance.
+ *
+ * This module is the gate. On hub start in wizard mode:
+ *
+ *   1. `generateBootstrapToken()` produces a fresh `parachute-bootstrap-<rand>`
+ *      string. It lives in this module's in-memory state — never persisted,
+ *      regenerated on every process restart so a leaked stale value can't
+ *      claim a hub that's already been restarted past its window.
+ *   2. The caller logs it prominently on the startup banner so the
+ *      operator (the only one with shell access to the box / Render logs)
+ *      can copy it into the wizard form.
+ *   3. The wizard's account form prompts for the token; the POST handler
+ *      calls `verifyBootstrapToken(...)` (constant-time compare) before
+ *      letting `createUser` run. Wrong token → 401; right token →
+ *      `consumeBootstrapToken()` clears the in-memory value so a later
+ *      racer can't reuse it.
+ *
+ * Env-seeded admins (`PARACHUTE_INITIAL_ADMIN_USERNAME` +
+ * `PARACHUTE_INITIAL_ADMIN_PASSWORD`) bypass the token entirely — they've
+ * claimed the hub by setting env vars on the platform, so the wizard's
+ * account step is never reached. The token is generated only when
+ * `seedInitialAdminIfNeeded` returns `"needs-setup"`.
+ *
+ * Threading: the wizard reads the token via a getter injected into
+ * `SetupWizardDeps`, not via a direct module import. That keeps tests
+ * able to drive a known token without touching process state, and keeps
+ * the on-box CLI (`parachute expose`) able to skip token-gating entirely
+ * (it never enters wizard mode — the on-box operator already has shell
+ * access to call `parachute auth create-admin`).
+ */
+
+import { randomBytes, timingSafeEqual } from "node:crypto";
+
+const BOOTSTRAP_TOKEN_PREFIX = "parachute-bootstrap-";
+
+/**
+ * Module-scoped, mutable. Set by `generateBootstrapToken` / `setBootstrapToken`,
+ * read by `getBootstrapToken`, cleared by `consumeBootstrapToken` (on
+ * successful claim) or `clearBootstrapToken` (test cleanup). Never written
+ * to disk. Re-generated on every hub start when the wizard-mode condition
+ * holds; absent otherwise (env-seed path or admin-exists path skips
+ * generation altogether).
+ */
+let currentToken: string | undefined;
+
+/**
+ * Generate a fresh bootstrap token and stash it. Returns the full
+ * `parachute-bootstrap-<rand>` string. The random tail is 32 bytes
+ * base64url-encoded (~43 chars), so the full token is ~63 chars —
+ * comfortably unguessable, not so long the operator can't copy it.
+ *
+ * Idempotent within a single boot: calling twice replaces the prior
+ * value. In practice the caller (`commands/serve.ts`) only calls once
+ * during the wizard-mode branch of `seedInitialAdminIfNeeded`, so this
+ * mostly matters for tests that re-init the module between cases.
+ */
+export function generateBootstrapToken(): string {
+  // 32 bytes of randomness → 43 base64url chars (no padding). Plenty of
+  // entropy (256 bits) against any attacker who can guess at line rate.
+  const raw = randomBytes(32);
+  const tail = raw.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  currentToken = `${BOOTSTRAP_TOKEN_PREFIX}${tail}`;
+  return currentToken;
+}
+
+/**
+ * Read the current bootstrap token. Returns `undefined` when:
+ *   - no token has been generated this boot (env-seeded admin or
+ *     admin-already-exists path); OR
+ *   - the token has been consumed by a successful admin-claim POST.
+ *
+ * Callers can use the `undefined` signal to render the form without a
+ * token field (the env-seed-no-vault flow under Issue 2 — admin already
+ * exists, wizard is just for vault provisioning, no token needed).
+ */
+export function getBootstrapToken(): string | undefined {
+  return currentToken;
+}
+
+/**
+ * Constant-time compare an operator-supplied string against the current
+ * bootstrap token. Returns `false` when no token is active OR when the
+ * supplied value doesn't match. Inputs of different length short-circuit
+ * to `false` without touching `timingSafeEqual` — `timingSafeEqual`
+ * throws on length-mismatched buffers, but length itself is non-secret
+ * (the token format is fixed) so we don't need a constant-time length
+ * check.
+ *
+ * Empty / non-string input returns `false`. The caller's API is "did the
+ * operator type the right token?"; missing-and-wrong are the same UX.
+ */
+export function verifyBootstrapToken(supplied: string | null | undefined): boolean {
+  if (currentToken === undefined) return false;
+  if (typeof supplied !== "string" || supplied.length === 0) return false;
+  if (supplied.length !== currentToken.length) return false;
+  const a = Buffer.from(supplied, "utf8");
+  const b = Buffer.from(currentToken, "utf8");
+  // Defense in depth: timingSafeEqual asserts same length and throws
+  // otherwise. We've already length-checked above, so the throw can only
+  // fire if `supplied` carries a multi-byte unicode scalar that encodes
+  // to a different number of UTF-8 bytes than its `.length`. Safer to
+  // wrap than to leak a stack trace into the operator's response.
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+/**
+ * Consume the bootstrap token after a successful admin-claim. Subsequent
+ * `verifyBootstrapToken` calls return `false`; `getBootstrapToken`
+ * returns `undefined`. Use this on the success branch of the account
+ * POST so a racing attacker who saw the right token in the operator's
+ * over-the-shoulder screencast can't replay it.
+ */
+export function consumeBootstrapToken(): void {
+  currentToken = undefined;
+}
+
+/**
+ * Test seam: clear the in-memory token without going through the
+ * "claim" path. Production callers should never touch this — the
+ * lifecycle is "generate on wizard-mode boot, consume on successful
+ * admin claim." Tests that drive multiple wizard scenarios in one
+ * process need a way to reset the module between cases.
+ *
+ * Same effect as `consumeBootstrapToken` today, but kept as a separate
+ * surface so future changes (e.g. "log a warning on explicit consume,
+ * not on test cleanup") don't muddle the two intents.
+ */
+export function _resetBootstrapTokenForTests(): void {
+  currentToken = undefined;
+}
+
+/**
+ * Test seam: directly set the in-memory token to a known value so
+ * tests can construct a request with the expected token without going
+ * through `generateBootstrapToken` (and the random tail it produces).
+ * Production callers always use `generateBootstrapToken`.
+ */
+export function _setBootstrapTokenForTests(token: string): void {
+  currentToken = token;
+}
+
+export { BOOTSTRAP_TOKEN_PREFIX };

package/src/commands/serve.ts

@@ -26,6 +26,7 @@
 
 import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { generateBootstrapToken } from "../bootstrap-token.ts";
 // NOTE: CONFIG_DIR/WELL_KNOWN_DIR/SERVICES_MANIFEST_PATH are evaluated at
 // import time from process.env.PARACHUTE_HOME. The `env` parameter on
 // `serve()` cannot reroute them — set PARACHUTE_HOME before importing for
@@ -75,6 +76,31 @@ export interface ServeResult {
 
 const DEFAULT_PORT = 1939;
 
+/**
+ * Build the startup banner line.
+ *
+ * `0.0.0.0` is a bind-host meta-address — the kernel uses it to mean "listen
+ * on all interfaces," but Chrome and other browsers refuse to navigate to it
+ * (and any cross-resource fetch that mixes `0.0.0.0` with `localhost` trips
+ * cross-origin checks). Operators who paste the banner URL into a browser
+ * need the loopback form. When the operator has explicitly chosen a
+ * hostname via `PARACHUTE_BIND_HOST` (e.g. `127.0.0.1`, a LAN IP), we
+ * honour their choice and print it directly — they know what they wired.
+ */
+export function formatListeningBanner(args: {
+  hostname: string;
+  port: number;
+  configDir: string;
+  dbPath: string;
+  issuer?: string;
+  adminBootstrap: string;
+}): string {
+  const { hostname, port, configDir, dbPath, issuer, adminBootstrap } = args;
+  const displayHost = hostname === "0.0.0.0" ? "localhost" : hostname;
+  const boundNote = hostname === "0.0.0.0" ? ` (bound on all interfaces: 0.0.0.0:${port})` : "";
+  return `parachute serve: listening on http://${displayHost}:${port}${boundNote} (PARACHUTE_HOME=${configDir}, db=${dbPath}, issuer=${issuer ?? "<request-origin>"}, admin=${adminBootstrap})`;
+}
+
 function parsePort(raw: string | undefined): number | undefined {
   if (raw === undefined || raw === "") return undefined;
   const n = Number.parseInt(raw, 10);
@@ -111,6 +137,31 @@ export async function seedInitialAdminIfNeeded(
   return "seeded";
 }
 
+/**
+ * Format the multi-line wizard-mode banner the operator must see in
+ * startup logs to claim the freshly-deployed hub. The token MUST be
+ * surfaced visibly enough that an operator scrolling Render's log tab
+ * spots it on the first scan — that's the design tension behind the
+ * line-spacing and the `[wizard]` prefix on every line.
+ *
+ * Threaded out as a pure function so tests can lock the shape; the
+ * banner is the security-critical interface (an operator who misses
+ * the token can't proceed; an attacker who reads it before the
+ * operator wins the race).
+ */
+export function formatBootstrapTokenBanner(token: string): string {
+  return [
+    "[wizard] No admin exists — wizard mode active. To claim ownership of this hub:",
+    "[wizard]   1. Visit http://localhost:1939/admin/setup (or your deployed URL)",
+    "[wizard]   2. Paste this bootstrap token into the form:",
+    "[wizard]",
+    `[wizard]   ${token}`,
+    "[wizard]",
+    "[wizard] This token grants permission to create the first admin. It expires when",
+    "[wizard] admin is created OR when hub restarts.",
+  ].join("\n");
+}
+
 /**
  * Run the hub fetch loop in the foreground. Resolves when `Bun.serve` is
  * bound; the returned `stop()` shuts the server down for tests.
@@ -150,6 +201,12 @@ export async function serve(opts: ServeOpts = {}): Promise<{
     log(
       "parachute serve: no admin account configured. Set PARACHUTE_INITIAL_ADMIN_USERNAME + PARACHUTE_INITIAL_ADMIN_PASSWORD, or visit /admin/setup once the hub is reachable.",
     );
+    // Mint a bootstrap token + log it. The wizard's account POST will
+    // require this token, so an attacker who beats the operator to the
+    // freshly-provisioned URL still can't claim the admin row without
+    // shell access to the platform's startup logs.
+    const token = generateBootstrapToken();
+    log(formatBootstrapTokenBanner(token));
   }
 
   const supervisor = opts.supervisor ?? new Supervisor();
@@ -194,7 +251,14 @@ export async function serve(opts: ServeOpts = {}): Promise<{
   });
 
   log(
-    `parachute serve: listening on http://${hostname}:${port} (PARACHUTE_HOME=${CONFIG_DIR}, db=${dbPath}, issuer=${issuer ?? "<request-origin>"}, admin=${adminBootstrap})`,
+    formatListeningBanner({
+      hostname,
+      port,
+      configDir: CONFIG_DIR,
+      dbPath,
+      issuer,
+      adminBootstrap,
+    }),
   );
 
   return {