@openparachute/hub 0.3.0-rc.1 → 0.5.0

package/src/admin-handlers.ts

@@ -0,0 +1,365 @@
+/**
+ * HTTP handlers for the hub admin surface — login (`/admin/login`) and the
+ * config portal (`/admin/config`, `/admin/config/<name>`). Sessions ride the
+ * same `parachute_hub_session` cookie that the OAuth login mints, since PR
+ * #112 widened the cookie path from `/oauth/` to `/`.
+ *
+ * Every state-changing POST is double-submit-CSRF protected
+ * (`parachute_hub_csrf` cookie + `__csrf` form field, constant-time compare),
+ * and every authenticated GET issues a 302 to `/admin/login?next=<path>`
+ * when no session is found rather than rendering an inline login form —
+ * keeps each route's intent clean and lets the operator bookmark
+ * `/admin/config` without thinking about state.
+ */
+import type { Database } from "bun:sqlite";
+import {
+  type AdminConfigModuleView,
+  type ModuleStatus,
+  renderAdminConfigPage,
+  renderAdminError,
+  renderAdminLogin,
+} from "./admin-config-ui.ts";
+import {
+  type ConfigurableModule,
+  configPathFor,
+  discoverConfigurableModules,
+  readModuleConfig,
+  validateAndCoerce,
+  writeModuleConfig,
+} from "./admin-config.ts";
+import { restart as lifecycleRestart } from "./commands/lifecycle.ts";
+import { CONFIG_DIR } from "./config.ts";
+import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
+import type { ModuleManifest } from "./module-manifest.ts";
+import {
+  type ServicesManifest,
+  readManifest as readServicesManifest,
+} from "./services-manifest.ts";
+import {
+  SESSION_TTL_MS,
+  buildSessionClearCookie,
+  buildSessionCookie,
+  createSession,
+  deleteSession,
+  findSession,
+  parseSessionCookie,
+} from "./sessions.ts";
+import { getUserByUsername, verifyPassword } from "./users.ts";
+
+export interface AdminDeps {
+  /** Resolves the installed-services manifest (production: `services-manifest.readManifest`). */
+  loadServicesManifest?: () => ServicesManifest;
+  /** Per-module `.parachute/module.json` reader (production: `module-manifest.readModuleManifest`). */
+  readManifest?: (installDir: string) => Promise<ModuleManifest | null>;
+  /** `~/.parachute` (defaults to `CONFIG_DIR`). Module configs land at `<configDir>/<name>/config.json`. */
+  configDir?: string;
+  /** Test seam — defaults to `commands/lifecycle.restart`. */
+  restartService?: (name: string) => Promise<number>;
+  /** Test seam — defaults to logging to stderr. */
+  log?: (line: string) => void;
+  /** Test seam — defaults to real clock. */
+  now?: () => Date;
+}
+
+function htmlResponse(body: string, status = 200, extra: Record<string, string> = {}): Response {
+  return new Response(body, {
+    status,
+    headers: { "content-type": "text/html; charset=utf-8", ...extra },
+  });
+}
+
+function redirect(location: string, extra: Record<string, string> = {}): Response {
+  return new Response(null, { status: 302, headers: { location, ...extra } });
+}
+
+// --- session gate ----------------------------------------------------------
+
+/**
+ * Return the active session for this request, or null. Caller decides what
+ * to do on null — most paths should redirect to `/admin/login?next=<path>`.
+ */
+function activeSession(db: Database, req: Request) {
+  const sid = parseSessionCookie(req.headers.get("cookie"));
+  return sid ? findSession(db, sid) : null;
+}
+
+function loginRedirect(req: Request, extra: Record<string, string> = {}): Response {
+  const url = new URL(req.url);
+  const next = `${url.pathname}${url.search}`;
+  return redirect(`/admin/login?next=${encodeURIComponent(next)}`, extra);
+}
+
+function safeNext(raw: string | null): string {
+  if (!raw) return "/admin/config";
+  // Only allow same-origin paths — never honor an absolute URL or scheme.
+  if (!raw.startsWith("/") || raw.startsWith("//")) return "/admin/config";
+  return raw;
+}
+
+// --- /admin/login ----------------------------------------------------------
+
+export function handleAdminLoginGet(_db: Database, req: Request): Response {
+  const url = new URL(req.url);
+  const next = safeNext(url.searchParams.get("next"));
+  const csrf = ensureCsrfToken(req);
+  const extra: Record<string, string> = csrf.setCookie ? { "set-cookie": csrf.setCookie } : {};
+  return htmlResponse(renderAdminLogin({ next, csrfToken: csrf.token }), 200, extra);
+}
+
+export async function handleAdminLoginPost(db: Database, req: Request): Promise<Response> {
+  const form = await req.formData();
+  const formCsrf = form.get(CSRF_FIELD_NAME);
+  if (!verifyCsrfToken(req, typeof formCsrf === "string" ? formCsrf : null)) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Invalid form submission",
+        message: "The form's CSRF token did not match. Reload the page and try again.",
+      }),
+      400,
+    );
+  }
+  const username = String(form.get("username") ?? "");
+  const password = String(form.get("password") ?? "");
+  const next = safeNext(String(form.get("next") ?? ""));
+  const csrfToken = typeof formCsrf === "string" ? formCsrf : "";
+  if (!username || !password) {
+    return htmlResponse(
+      renderAdminLogin({ next, csrfToken, errorMessage: "Username and password are required." }),
+      400,
+    );
+  }
+  const user = getUserByUsername(db, username);
+  if (!user) {
+    return htmlResponse(
+      renderAdminLogin({ next, csrfToken, errorMessage: "Invalid credentials." }),
+      401,
+    );
+  }
+  const ok = await verifyPassword(user, password);
+  if (!ok) {
+    return htmlResponse(
+      renderAdminLogin({ next, csrfToken, errorMessage: "Invalid credentials." }),
+      401,
+    );
+  }
+  const session = createSession(db, { userId: user.id });
+  const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000));
+  return redirect(next, { "set-cookie": cookie });
+}
+
+// --- /admin/logout ---------------------------------------------------------
+
+/**
+ * POST-only — logout is state-changing, so it rides the same double-submit
+ * CSRF discipline as login + config posts. Without CSRF, a malicious
+ * cross-origin form could log the operator out (annoyance, not catastrophe,
+ * but the safety belt is already on the bus).
+ *
+ * Always idempotent: clearing the cookie succeeds even if there's no
+ * matching session row. Returns 302 → /admin/login so the operator lands
+ * back on the form ready to re-authenticate.
+ */
+export async function handleAdminLogoutPost(db: Database, req: Request): Promise<Response> {
+  const form = await req.formData();
+  const formCsrf = form.get(CSRF_FIELD_NAME);
+  if (!verifyCsrfToken(req, typeof formCsrf === "string" ? formCsrf : null)) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Invalid form submission",
+        message: "The form's CSRF token did not match. Reload the page and try again.",
+      }),
+      400,
+    );
+  }
+  const sid = parseSessionCookie(req.headers.get("cookie"));
+  if (sid) deleteSession(db, sid);
+  return redirect("/admin/login", { "set-cookie": buildSessionClearCookie() });
+}
+
+// --- /admin/config ---------------------------------------------------------
+
+export async function handleAdminConfigGet(
+  db: Database,
+  req: Request,
+  deps: AdminDeps = {},
+): Promise<Response> {
+  const session = activeSession(db, req);
+  if (!session) return loginRedirect(req);
+
+  const csrf = ensureCsrfToken(req);
+  const setCookieExtra: Record<string, string> = csrf.setCookie
+    ? { "set-cookie": csrf.setCookie }
+    : {};
+
+  const modules = await loadModuleViews(deps);
+  const flash = parseFlash(req);
+  if (flash) applyFlashTo(modules, flash);
+  return htmlResponse(
+    renderAdminConfigPage({ modules, csrfToken: csrf.token }),
+    200,
+    setCookieExtra,
+  );
+}
+
+export async function handleAdminConfigPost(
+  db: Database,
+  req: Request,
+  moduleName: string,
+  deps: AdminDeps = {},
+): Promise<Response> {
+  const session = activeSession(db, req);
+  if (!session) return loginRedirect(req);
+
+  const form = await req.formData();
+  const formCsrf = form.get(CSRF_FIELD_NAME);
+  if (!verifyCsrfToken(req, typeof formCsrf === "string" ? formCsrf : null)) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Invalid form submission",
+        message: "The form's CSRF token did not match. Reload the page and try again.",
+      }),
+      400,
+    );
+  }
+
+  const modules = await discoverConfigurableModules(discoverDeps(deps));
+  const target = modules.find((m) => m.name === moduleName);
+  if (!target) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Unknown module",
+        message: `No installed module named "${moduleName}" declares a config schema on this hub.`,
+      }),
+      404,
+    );
+  }
+
+  const csrfToken = typeof formCsrf === "string" ? formCsrf : "";
+  const submitted = collectFormValues(form, target);
+  const result = validateAndCoerce(submitted, target.schema);
+  if (!result.ok) {
+    return rerenderWithStatus(deps, target, csrfToken, {
+      fieldErrors: result.errors,
+      pending: submitted,
+      errorMessage: "Some fields need attention before this config can be saved.",
+    });
+  }
+
+  try {
+    writeModuleConfig(target.configPath, result.data ?? {});
+  } catch (err) {
+    return rerenderWithStatus(deps, target, csrfToken, {
+      pending: submitted,
+      errorMessage: `Failed to write ${target.configPath}: ${err instanceof Error ? err.message : String(err)}`,
+    });
+  }
+
+  const restartFn = deps.restartService ?? defaultRestart(deps);
+  let restartCode = 0;
+  try {
+    restartCode = await restartFn(target.name);
+  } catch (err) {
+    return successRedirect(target.name, "saved-restart-failed", err);
+  }
+  if (restartCode !== 0) return successRedirect(target.name, "saved-restart-failed");
+  return successRedirect(target.name, "saved");
+}
+
+function defaultRestart(deps: AdminDeps): (name: string) => Promise<number> {
+  return (name) =>
+    lifecycleRestart(name, {
+      configDir: deps.configDir ?? CONFIG_DIR,
+      log: deps.log,
+    });
+}
+
+function discoverDeps(deps: AdminDeps) {
+  const out: Parameters<typeof discoverConfigurableModules>[0] = {
+    loadServicesManifest: deps.loadServicesManifest ?? readServicesManifest,
+    configDir: deps.configDir ?? CONFIG_DIR,
+  };
+  if (deps.readManifest) out.readManifest = deps.readManifest;
+  return out;
+}
+
+async function loadModuleViews(deps: AdminDeps): Promise<AdminConfigModuleView[]> {
+  const modules = await discoverConfigurableModules(discoverDeps(deps));
+  return modules.map((module) => {
+    const { data, parseError } = readModuleConfig(module.configPath);
+    const view: AdminConfigModuleView = { module, current: data };
+    if (parseError) view.parseError = parseError;
+    return view;
+  });
+}
+
+function collectFormValues(
+  form: Awaited<ReturnType<Request["formData"]>>,
+  module: ConfigurableModule,
+): Record<string, string | boolean | undefined> {
+  const out: Record<string, string | boolean | undefined> = {};
+  for (const [key, prop] of Object.entries(module.schema.properties)) {
+    if (prop.type === "boolean") {
+      // Unchecked checkboxes don't appear in form data — absence = false.
+      out[key] = form.has(key);
+      continue;
+    }
+    const v = form.get(key);
+    out[key] = typeof v === "string" ? v : undefined;
+  }
+  return out;
+}
+
+// --- flash + redirect helpers ---------------------------------------------
+
+const FLASH_PARAM = "_status";
+const FLASH_MODULE_PARAM = "_module";
+
+function successRedirect(moduleName: string, status: string, err?: unknown): Response {
+  const target = new URL("/admin/config", "http://placeholder");
+  target.searchParams.set(FLASH_PARAM, status);
+  target.searchParams.set(FLASH_MODULE_PARAM, moduleName);
+  if (err) target.searchParams.set("_err", err instanceof Error ? err.message : String(err));
+  target.hash = `module-${moduleName}`;
+  return redirect(`${target.pathname}${target.search}${target.hash}`);
+}
+
+function parseFlash(req: Request): { module: string; status: string; errMessage?: string } | null {
+  const url = new URL(req.url);
+  const status = url.searchParams.get(FLASH_PARAM);
+  const mod = url.searchParams.get(FLASH_MODULE_PARAM);
+  if (!status || !mod) return null;
+  const errMessage = url.searchParams.get("_err") ?? undefined;
+  const out: { module: string; status: string; errMessage?: string } = { module: mod, status };
+  if (errMessage) out.errMessage = errMessage;
+  return out;
+}
+
+function applyFlashTo(
+  views: AdminConfigModuleView[],
+  flash: { module: string; status: string; errMessage?: string },
+): void {
+  const view = views.find((v) => v.module.name === flash.module);
+  if (!view) return;
+  if (flash.status === "saved") {
+    view.status = { successMessage: `Saved and restarted ${view.module.displayName}.` };
+    return;
+  }
+  if (flash.status === "saved-restart-failed") {
+    const tail = flash.errMessage ? ` (${flash.errMessage})` : "";
+    view.status = {
+      errorMessage: `Saved ${view.module.displayName} config but the restart did not succeed${tail}. Run \`parachute restart ${view.module.name}\` and check logs.`,
+    };
+  }
+}
+
+async function rerenderWithStatus(
+  deps: AdminDeps,
+  target: ConfigurableModule,
+  csrfToken: string,
+  status: ModuleStatus,
+): Promise<Response> {
+  const views = await loadModuleViews(deps);
+  const view = views.find((v) => v.module.name === target.name);
+  if (view) view.status = status;
+  return htmlResponse(renderAdminConfigPage({ modules: views, csrfToken }), 422);
+}

package/src/admin-host-admin-token.ts

@@ -0,0 +1,83 @@
+/**
+ * `GET /admin/host-admin-token` — exchange a valid admin session cookie for a
+ * short-lived JWT carrying `parachute:host:admin`.
+ *
+ * Why this exists: the hub's vault-management SPA (served under `/hub/`)
+ * needs a Bearer to call admin endpoints like `POST /vaults`, but
+ * `parachute:host:admin` is in `NON_REQUESTABLE_SCOPES` — the public
+ * `/oauth/authorize` endpoint refuses to mint it so third-party apps can't
+ * acquire cross-vault provisioning capability via consent.
+ *
+ * The local mint path now has two surfaces:
+ *   1. `parachute auth ...` — operator-token file (~1y, on-disk, mode 0600).
+ *   2. THIS endpoint — short-lived JWT (10 min) handed to the SPA in memory.
+ *
+ * Both paths require already-proved local-operator identity:
+ *   - operator-token mint runs as the operator's unix user.
+ *   - this endpoint requires a valid `parachute_hub_session` cookie, which
+ *     was set by `/admin/login` after a password check.
+ *
+ * Tokens minted here are deliberately NOT persisted in the `tokens` table
+ * (no refresh, no revocation tracking). They expire on their own; the SPA
+ * re-fetches when the JWT is about to lapse.
+ */
+import type { Database } from "bun:sqlite";
+import { signAccessToken } from "./jwt-sign.ts";
+import { findSession, parseSessionCookie } from "./sessions.ts";
+
+/** Short TTL — page-snapshot threats can't carry the token forever. */
+export const HOST_ADMIN_TOKEN_TTL_SECONDS = 10 * 60;
+const HOST_ADMIN_AUDIENCE = "hub";
+const HOST_ADMIN_CLIENT_ID = "parachute-hub-spa";
+export const HOST_ADMIN_SCOPES = ["parachute:host:admin"] as const;
+
+export interface MintHostAdminTokenDeps {
+  db: Database;
+  /** Hub origin — written into JWT `iss`. */
+  issuer: string;
+}
+
+export async function handleHostAdminToken(
+  req: Request,
+  deps: MintHostAdminTokenDeps,
+): Promise<Response> {
+  if (req.method !== "GET") {
+    return jsonError(405, "method_not_allowed", "use GET");
+  }
+  const sid = parseSessionCookie(req.headers.get("cookie"));
+  const session = sid ? findSession(deps.db, sid) : null;
+  if (!session) {
+    return jsonError(401, "unauthenticated", "no admin session — sign in at /admin/login first");
+  }
+  const minted = await signAccessToken(deps.db, {
+    sub: session.userId,
+    scopes: [...HOST_ADMIN_SCOPES],
+    audience: HOST_ADMIN_AUDIENCE,
+    clientId: HOST_ADMIN_CLIENT_ID,
+    issuer: deps.issuer,
+    ttlSeconds: HOST_ADMIN_TOKEN_TTL_SECONDS,
+  });
+  return new Response(
+    JSON.stringify({
+      token: minted.token,
+      expires_at: minted.expiresAt,
+      scopes: HOST_ADMIN_SCOPES,
+    }),
+    {
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        // No browser cache — token rotates per-fetch, and a stale 200 from a
+        // back/forward navigation could hand the SPA a long-expired JWT.
+        "cache-control": "no-store",
+      },
+    },
+  );
+}
+
+function jsonError(status: number, error: string, description: string): Response {
+  return new Response(JSON.stringify({ error, error_description: description }), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}

package/src/admin-vault-admin-token.ts

@@ -0,0 +1,98 @@
+/**
+ * `GET /admin/vault-admin-token/<name>` — exchange a valid admin session
+ * cookie for a short-lived JWT carrying `vault:<name>:admin`.
+ *
+ * Why this exists: the per-vault admin SPA (vault#216 / vault PR #219) needs
+ * a Bearer to call vault-internal admin endpoints (token mint/revoke,
+ * config edits). `vault:<name>:admin` is non-requestable from the public
+ * `/oauth/authorize` flow (`scope-explanations.ts:isNonRequestableScope`)
+ * — only the local session-cookie path can mint it.
+ *
+ * The minted JWT is handed to the vault SPA via a URL fragment on redirect
+ * (`<vault-url><managementUrl>#token=<jwt>`). Vault's admin SPA bootstraps
+ * by reading `location.hash`, stashing the token in module-scoped state,
+ * and replaceState-ing the fragment off the URL.
+ *
+ * Validation: `<name>` must match a vault instance currently in services.json.
+ * That keeps a forged URL from minting `vault:does-not-exist:admin` and
+ * masking a typo as a real (but unusable) credential. Resolved via the
+ * already-built well-known doc — same source of truth the SPA's vault list
+ * reads.
+ */
+import type { Database } from "bun:sqlite";
+import { signAccessToken } from "./jwt-sign.ts";
+import { findSession, parseSessionCookie } from "./sessions.ts";
+
+/** Short TTL — matches host-admin-token. SPA re-fetches on near-expiry. */
+export const VAULT_ADMIN_TOKEN_TTL_SECONDS = 10 * 60;
+const VAULT_ADMIN_CLIENT_ID = "parachute-hub-spa";
+
+/** Same shape as the manifest name validator — keeps URL-injection out. */
+const VAULT_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+
+export interface MintVaultAdminTokenDeps {
+  db: Database;
+  /** Hub origin — written into JWT `iss`. */
+  issuer: string;
+  /** Names of currently-installed vault instances; the request name must be in this set. */
+  knownVaultNames: ReadonlySet<string>;
+}
+
+export async function handleVaultAdminToken(
+  req: Request,
+  vaultName: string,
+  deps: MintVaultAdminTokenDeps,
+): Promise<Response> {
+  if (req.method !== "GET") {
+    return jsonError(405, "method_not_allowed", "use GET");
+  }
+  if (!VAULT_NAME_RE.test(vaultName)) {
+    return jsonError(400, "invalid_request", `vault name "${vaultName}" is not a valid identifier`);
+  }
+  if (!deps.knownVaultNames.has(vaultName)) {
+    return jsonError(404, "not_found", `no vault named "${vaultName}" in this hub`);
+  }
+  const sid = parseSessionCookie(req.headers.get("cookie"));
+  const session = sid ? findSession(deps.db, sid) : null;
+  if (!session) {
+    return jsonError(401, "unauthenticated", "no admin session — sign in at /admin/login first");
+  }
+  const scope = `vault:${vaultName}:admin`;
+  // Per-vault audience: vault validates the JWT's `aud` claim against
+  // `vault.<name>` derived from its own URL-bound config (vault src/auth.ts
+  // line ~167 — `expectedAudience: vault.${vaultConfig.name}`). Same shape
+  // as `inferAudience` in oauth-handlers.ts for the public OAuth flow, so
+  // hub-minted and OAuth-minted tokens are indistinguishable to vault. A
+  // single `audience: "hub"` constant here was wrong end-to-end and broke
+  // every Manage-button click against the vault SPA (PR #173 follow-up).
+  const audience = `vault.${vaultName}`;
+  const minted = await signAccessToken(deps.db, {
+    sub: session.userId,
+    scopes: [scope],
+    audience,
+    clientId: VAULT_ADMIN_CLIENT_ID,
+    issuer: deps.issuer,
+    ttlSeconds: VAULT_ADMIN_TOKEN_TTL_SECONDS,
+  });
+  return new Response(
+    JSON.stringify({
+      token: minted.token,
+      expires_at: minted.expiresAt,
+      scopes: [scope],
+    }),
+    {
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        "cache-control": "no-store",
+      },
+    },
+  );
+}
+
+function jsonError(status: number, error: string, description: string): Response {
+  return new Response(JSON.stringify({ error, error_description: description }), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}