@openparachute/hub 0.5.10 → 0.5.12-rc.2

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

@@ -2300,3 +2300,395 @@ describe("typed vault name (hub#267)", () => {
     expect(html).toContain('id="preview-vault-name">BAD<');
   });
 });
+
+// --- bootstrap token gate (first-boot-path hardening, Issue 1) -----------
+
+describe("bootstrap token gate (handleSetupAccountPost)", () => {
+  let h: Harness;
+  beforeEach(async () => {
+    h = makeHarness();
+    _resetOperationsRegistryForTests();
+    const { _resetBootstrapTokenForTests } = await import("../bootstrap-token.ts");
+    _resetBootstrapTokenForTests();
+  });
+  afterEach(async () => {
+    h.cleanup();
+    const { _resetBootstrapTokenForTests } = await import("../bootstrap-token.ts");
+    _resetBootstrapTokenForTests();
+  });
+
+  test("GET /admin/setup renders the bootstrap-token field when a token is active", async () => {
+    const { generateBootstrapToken } = await import("../bootstrap-token.ts");
+    generateBootstrapToken();
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const res = handleSetupGet(req("/admin/setup"), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        issuer: "https://hub.example",
+        registry: getDefaultOperationsRegistry(),
+      });
+      const html = await res.text();
+      expect(html).toContain('name="bootstrap_token"');
+      // The callout names what the field is + where to find the value.
+      expect(html).toContain("Bootstrap token");
+      expect(html).toContain("startup logs");
+      // Form action unchanged.
+      expect(html).toContain('action="/admin/setup/account"');
+    } finally {
+      db.close();
+    }
+  });
+
+  test("GET /admin/setup omits the bootstrap-token field when no token is active", () => {
+    // No `generateBootstrapToken` call this test — the in-memory slot is
+    // undefined, mirroring on-box CLI mode (no `parachute serve` wizard).
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const res = handleSetupGet(req("/admin/setup"), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        issuer: "https://hub.example",
+        registry: getDefaultOperationsRegistry(),
+      });
+      const html = res.text() as unknown as Promise<string>;
+      return html.then((body) => {
+        expect(body).not.toContain('name="bootstrap_token"');
+        // Bootstrap callout is also absent — operator gets the
+        // pre-hardening shape on the on-box CLI surface.
+        expect(body).not.toContain("Bootstrap token");
+        expect(body).toContain('action="/admin/setup/account"');
+      });
+    } finally {
+      db.close();
+    }
+  });
+
+  test("POST /admin/setup/account with correct bootstrap_token creates admin + consumes token", async () => {
+    const { generateBootstrapToken, getBootstrapToken } = await import("../bootstrap-token.ts");
+    const token = generateBootstrapToken();
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const get = handleSetupGet(req("/admin/setup"), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        issuer: "https://hub.example",
+        registry: getDefaultOperationsRegistry(),
+      });
+      const csrf = setCookie(get, CSRF_COOKIE_NAME) ?? "";
+      const form = formBody({
+        bootstrap_token: token,
+        username: "ops",
+        password: "correct horse battery",
+        password_confirm: "correct horse battery",
+        [CSRF_FIELD_NAME]: csrf,
+      });
+      const post = await handleSetupAccountPost(
+        req("/admin/setup/account", {
+          method: "POST",
+          body: form.body,
+          headers: { ...form.headers, cookie: `${CSRF_COOKIE_NAME}=${csrf}` },
+        }),
+        {
+          db,
+          manifestPath: h.manifestPath,
+          configDir: h.dir,
+          issuer: "https://hub.example",
+          registry: getDefaultOperationsRegistry(),
+        },
+      );
+      expect(post.status).toBe(303);
+      expect(userCount(db)).toBe(1);
+      // Token consumed: in-memory slot is undefined.
+      expect(getBootstrapToken()).toBeUndefined();
+    } finally {
+      db.close();
+    }
+  });
+
+  test("POST /admin/setup/account with wrong bootstrap_token returns 401 + no admin row", async () => {
+    const { generateBootstrapToken } = await import("../bootstrap-token.ts");
+    generateBootstrapToken();
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const get = handleSetupGet(req("/admin/setup"), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        issuer: "https://hub.example",
+        registry: getDefaultOperationsRegistry(),
+      });
+      const csrf = setCookie(get, CSRF_COOKIE_NAME) ?? "";
+      const form = formBody({
+        bootstrap_token: "parachute-bootstrap-WRONG-WRONG-WRONG-WRONG-WRONG-WRONG-x",
+        username: "ops",
+        password: "correct horse battery",
+        password_confirm: "correct horse battery",
+        [CSRF_FIELD_NAME]: csrf,
+      });
+      const post = await handleSetupAccountPost(
+        req("/admin/setup/account", {
+          method: "POST",
+          body: form.body,
+          headers: { ...form.headers, cookie: `${CSRF_COOKIE_NAME}=${csrf}` },
+        }),
+        {
+          db,
+          manifestPath: h.manifestPath,
+          configDir: h.dir,
+          issuer: "https://hub.example",
+          registry: getDefaultOperationsRegistry(),
+        },
+      );
+      expect(post.status).toBe(401);
+      // The form re-renders with the token field present + an error
+      // banner; the wrong token value is NOT echoed back.
+      const html = await post.text();
+      expect(html).toContain('name="bootstrap_token"');
+      expect(html).toContain("Wrong bootstrap token");
+      expect(html).not.toContain("WRONG-WRONG-WRONG");
+      // Username is preserved so the operator doesn't have to retype.
+      expect(html).toContain('value="ops"');
+      // No admin row was created.
+      expect(userCount(db)).toBe(0);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("POST /admin/setup/account with MISSING bootstrap_token returns 401", async () => {
+    const { generateBootstrapToken } = await import("../bootstrap-token.ts");
+    generateBootstrapToken();
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const get = handleSetupGet(req("/admin/setup"), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        issuer: "https://hub.example",
+        registry: getDefaultOperationsRegistry(),
+      });
+      const csrf = setCookie(get, CSRF_COOKIE_NAME) ?? "";
+      const form = formBody({
+        // Deliberately omit `bootstrap_token`.
+        username: "ops",
+        password: "correct horse battery",
+        password_confirm: "correct horse battery",
+        [CSRF_FIELD_NAME]: csrf,
+      });
+      const post = await handleSetupAccountPost(
+        req("/admin/setup/account", {
+          method: "POST",
+          body: form.body,
+          headers: { ...form.headers, cookie: `${CSRF_COOKIE_NAME}=${csrf}` },
+        }),
+        {
+          db,
+          manifestPath: h.manifestPath,
+          configDir: h.dir,
+          issuer: "https://hub.example",
+          registry: getDefaultOperationsRegistry(),
+        },
+      );
+      expect(post.status).toBe(401);
+      expect(userCount(db)).toBe(0);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("POST /admin/setup/account after admin already claimed returns 410 Gone", async () => {
+    const { generateBootstrapToken } = await import("../bootstrap-token.ts");
+    // First claim: generate token + create admin. Then a stale POST
+    // arrives — the token has been consumed AND an admin row exists.
+    generateBootstrapToken();
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "first-admin", "strong-password", { passwordChanged: true });
+      // Re-mint a fresh bootstrap token to simulate the case where the
+      // operator restarts the hub after admin creation. (Normally the
+      // serve.ts gate prevents this — we test the defensive layer.)
+      generateBootstrapToken();
+      const get = handleSetupGet(req("/admin/setup"), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        issuer: "https://hub.example",
+        registry: getDefaultOperationsRegistry(),
+      });
+      const csrf = setCookie(get, CSRF_COOKIE_NAME) ?? "";
+      const form = formBody({
+        bootstrap_token: "parachute-bootstrap-doesnt-matter-admin-already-exists-xxx",
+        username: "interloper",
+        password: "another password",
+        password_confirm: "another password",
+        [CSRF_FIELD_NAME]: csrf,
+      });
+      const post = await handleSetupAccountPost(
+        req("/admin/setup/account", {
+          method: "POST",
+          body: form.body,
+          headers: { ...form.headers, cookie: `${CSRF_COOKIE_NAME}=${csrf}` },
+        }),
+        {
+          db,
+          manifestPath: h.manifestPath,
+          configDir: h.dir,
+          issuer: "https://hub.example",
+          registry: getDefaultOperationsRegistry(),
+        },
+      );
+      expect(post.status).toBe(410);
+      const html = await post.text();
+      expect(html).toContain("Admin already claimed");
+      // No second user row was created.
+      expect(userCount(db)).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("on-box CLI flow (no token) creates admin normally — historical shape preserved", async () => {
+    // Critical back-compat: when no token has been generated (the
+    // historical wizard path: `parachute expose` doesn't enter wizard
+    // mode), the account POST works exactly as before. This pins the
+    // existing behavior post-refactor.
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const get = handleSetupGet(req("/admin/setup"), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        issuer: "https://hub.example",
+        registry: getDefaultOperationsRegistry(),
+      });
+      const csrf = setCookie(get, CSRF_COOKIE_NAME) ?? "";
+      const form = formBody({
+        username: "ops",
+        password: "correct horse battery",
+        password_confirm: "correct horse battery",
+        [CSRF_FIELD_NAME]: csrf,
+      });
+      const post = await handleSetupAccountPost(
+        req("/admin/setup/account", {
+          method: "POST",
+          body: form.body,
+          headers: { ...form.headers, cookie: `${CSRF_COOKIE_NAME}=${csrf}` },
+        }),
+        {
+          db,
+          manifestPath: h.manifestPath,
+          configDir: h.dir,
+          issuer: "https://hub.example",
+          registry: getDefaultOperationsRegistry(),
+        },
+      );
+      expect(post.status).toBe(303);
+      expect(userCount(db)).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+
+  // hub#297 reviewer-nit fold 3: pin the concurrent-claim race property.
+  //
+  // The wizard's account-claim POST has two layers of race-protection
+  // (chain documented inline below). The vault-POST analogue (idempotent
+  // short-circuit when supervisor.start is already running) has a test
+  // at setup-wizard.test.ts:N2 (`handleSetupVaultPost` — idempotent on
+  // concurrent POSTs); this is the missing partner pin for the account
+  // step.
+  //
+  // Race-protection chain:
+  //   1. First POST takes the token via verifyBootstrapToken (constant-
+  //      time check returns true), enters the createUser branch, and
+  //      consumes the token via consumeBootstrapToken AFTER the row
+  //      commits.
+  //   2. Second POST (if it arrives before the first finishes):
+  //      a. If the first POST hasn't consumed the token yet, both
+  //         POSTs pass verifyBootstrapToken. They race into createUser;
+  //         SQLite's UNIQUE constraint on `users.username` makes the
+  //         second `INSERT INTO users` throw. The handler's `catch`
+  //         block re-renders the form with a 400 + "username may
+  //         already be taken" banner — and crucially does NOT create
+  //         a second admin row.
+  //      b. If the first POST has already consumed the token, the
+  //         second POST's verifyBootstrapToken returns false (token
+  //         slot is undefined). 401 + form re-render.
+  //   3. Either way: exactly one admin row at rest, token consumed.
+  test("concurrent claim with the same token + username yields exactly one admin row (race property)", async () => {
+    const { generateBootstrapToken, getBootstrapToken } = await import("../bootstrap-token.ts");
+    const token = generateBootstrapToken();
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const get = handleSetupGet(req("/admin/setup"), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        issuer: "https://hub.example",
+        registry: getDefaultOperationsRegistry(),
+      });
+      const csrf = setCookie(get, CSRF_COOKIE_NAME) ?? "";
+      const formA = formBody({
+        bootstrap_token: token,
+        username: "ops",
+        password: "correct horse battery",
+        password_confirm: "correct horse battery",
+        [CSRF_FIELD_NAME]: csrf,
+      });
+      // Two POSTs share the same body, same CSRF, same token, same
+      // username. Promise.all fires them as concurrently as the bun
+      // runtime allows; the deterministic interleaving covered here
+      // is: both pass CSRF (same cookie), both pass token verify (if
+      // they race before the first one's consume), both reach
+      // createUser, and exactly one INSERT wins.
+      const deps = {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        issuer: "https://hub.example",
+        registry: getDefaultOperationsRegistry(),
+      };
+      const post = (label: string) =>
+        handleSetupAccountPost(
+          req(`/admin/setup/account?race=${label}`, {
+            method: "POST",
+            body: formA.body,
+            headers: { ...formA.headers, cookie: `${CSRF_COOKIE_NAME}=${csrf}` },
+          }),
+          deps,
+        );
+
+      const [resA, resB] = await Promise.all([post("a"), post("b")]);
+
+      // Property 1: exactly one POST landed at the 303 success branch.
+      const successes = [resA, resB].filter((r) => r.status === 303);
+      const failures = [resA, resB].filter((r) => r.status !== 303);
+      expect(successes.length).toBe(1);
+      expect(failures.length).toBe(1);
+
+      // Property 2: the failure is either a 400 (UNIQUE collision via
+      // createUser → catch block) OR a 401 (token already consumed by
+      // the first POST → verifyBootstrapToken returned false on this
+      // one). Both are valid race outcomes; we don't pin which —
+      // the schedule is non-deterministic at the bun runtime layer.
+      const failStatus = failures[0]?.status;
+      expect(failStatus === 400 || failStatus === 401).toBe(true);
+
+      // Property 3: exactly one admin row exists in the users table.
+      expect(userCount(db)).toBe(1);
+
+      // Property 4: the bootstrap token is consumed (cannot be reused
+      // by a later POST). Even in the schedule where the second POST
+      // failed via UNIQUE (token wasn't consumed by the failing path —
+      // it was consumed by the succeeding path), the token slot is
+      // empty after both promises settle.
+      expect(getBootstrapToken()).toBeUndefined();
+    } finally {
+      db.close();
+    }
+  });
+});

package/src/api-modules-ops.ts

@@ -34,12 +34,14 @@
 
 import type { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
 import { CURATED_MODULES, type CuratedModuleShort } from "./api-modules.ts";
 import { getModuleInstallChannel } from "./hub-settings.ts";
 import { validateAccessToken } from "./jwt-sign.ts";
 import { FIRST_PARTY_FALLBACKS, type ServiceSpec, composeServiceSpec } from "./service-spec.ts";
-import { findService, readManifest, removeService } from "./services-manifest.ts";
+import { findService, readManifest, removeService, upsertService } from "./services-manifest.ts";
 import type { ModuleState, SpawnRequest, Supervisor } from "./supervisor.ts";
+import { regenerateWellKnown } from "./well-known.ts";
 
 /**
  * Scope required for every POST + operation-poll endpoint here.
@@ -186,6 +188,20 @@ export interface ApiModulesOpsDeps {
    * inside `Bun.spawn` at child spawn time; we don't mutate `process.env`.
    */
   spawnEnv?: Record<string, string>;
+  /**
+   * Override the on-disk path for the regenerated `/.well-known/parachute.json`
+   * (test seam). Production writes to `WELL_KNOWN_PATH`; tests point at a
+   * tmp file so assertions can read the resulting doc without touching the
+   * operator's real config dir.
+   */
+  wellKnownPath?: string;
+  /**
+   * Reader for `<installDir>/.parachute/module.json` used by the well-known
+   * regen. Production reads from disk; tests inject a fake. Mirrors the
+   * hub-server `readModuleManifest` seam so the disk regen and the
+   * per-request HTTP build stay aligned.
+   */
+  readModuleManifest?: Parameters<typeof regenerateWellKnown>[0]["readModuleManifest"];
 }
 
 interface PathMatch {
@@ -266,6 +282,61 @@ function defaultRun(cmd: readonly string[]): Promise<number> {
   return proc.exited;
 }
 
+/**
+ * Stamp `installDir` on the services.json row for `spec.manifestName` when
+ * the package's globally-installed path can be resolved. Idempotent —
+ * no-ops when the row already carries the same `installDir`, when no row
+ * exists, or when `findGlobalInstall` can't locate the package (e.g. in
+ * tests with no global install).
+ *
+ * Mirrors the same stamp `parachute install <svc>` does in
+ * `commands/install.ts`. Without it, the discovery page's
+ * `loadServiceUiMetadata` resolver in `hub-server.ts` skips the entry (it
+ * reads `module.json` from `installDir`), so `uiUrl` never lands on the
+ * row + the new module's tile never renders on `/`.
+ */
+function stampInstallDir(spec: ServiceSpec, deps: ApiModulesOpsDeps): void {
+  const findGlobalInstall = deps.findGlobalInstall;
+  if (!findGlobalInstall) return;
+  const pkgJson = findGlobalInstall(spec.package);
+  if (!pkgJson) return;
+  const installDir = dirname(pkgJson);
+  const entry = findService(spec.manifestName, deps.manifestPath);
+  if (!entry || entry.installDir === installDir) return;
+  upsertService({ ...entry, installDir }, deps.manifestPath);
+}
+
+/**
+ * Regenerate `/.well-known/parachute.json` on disk after a state-changing
+ * module op (install / upgrade / uninstall). Wraps `regenerateWellKnown`
+ * with the deps-aware defaults — issuer for canonicalOrigin, deps-overridable
+ * paths + manifest reader. Errors land in the operation log rather than
+ * throwing back to the caller; the on-disk doc is a debug / inspection
+ * artifact, not the live discovery source, so a regen failure shouldn't
+ * mask the op's actual outcome.
+ */
+async function regenAfterOp(
+  opId: string,
+  registry: OperationsRegistry,
+  deps: ApiModulesOpsDeps,
+): Promise<void> {
+  try {
+    const regenOpts: Parameters<typeof regenerateWellKnown>[0] = {
+      manifestPath: deps.manifestPath,
+      canonicalOrigin: deps.issuer,
+    };
+    if (deps.wellKnownPath !== undefined) regenOpts.wellKnownPath = deps.wellKnownPath;
+    if (deps.readModuleManifest !== undefined) {
+      regenOpts.readModuleManifest = deps.readModuleManifest;
+    }
+    const { path } = await regenerateWellKnown(regenOpts);
+    registry.update(opId, {}, `regenerated ${path}`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    registry.update(opId, {}, `well-known regen failed: ${msg}`);
+  }
+}
+
 /**
  * Spawn the supervised child for `short`, using the spec's startCmd
  * and the current services.json entry (so notes' port-derived
@@ -392,6 +463,14 @@ export async function runInstall(
     }
   }
 
+  // Stamp installDir on the row so the discovery page's `uiUrl` /
+  // `displayName` resolver can find `<installDir>/.parachute/module.json`.
+  // Mirrors `parachute install <svc>` — without this, the new module's
+  // tile never renders on `/` because `loadServiceUiMetadata` skips
+  // installDir-less rows. (Doing this BEFORE the spawn so the supervisor
+  // also sees the updated row if it consults services.json post-spawn.)
+  stampInstallDir(spec, deps);
+
   // Spawn the child via the supervisor. Boot-spawn semantics apply.
   const state = await spawnSupervised(short, spec, deps);
   if (!state) {
@@ -402,6 +481,14 @@ export async function runInstall(
     );
     return;
   }
+
+  // Regenerate the on-disk well-known doc so the inspection artifact
+  // tracks the just-installed module's row. The HTTP path serves a
+  // per-request build, so the discovery page picks up the new module
+  // either way; this keeps `~/.parachute/well-known/parachute.json` in
+  // sync for tooling that reads it directly.
+  await regenAfterOp(opId, registry, deps);
+
   registry.update(opId, { status: "succeeded" }, `${short} installed + spawned (pid ${state.pid})`);
 }
 
@@ -485,6 +572,11 @@ async function runUpgrade(
     registry.update(opId, {}, `bun add reported exit ${code} but package landed at ${probed}`);
   }
 
+  // Re-stamp installDir after upgrade — a major-version bump may relocate
+  // the package on disk (e.g. node_modules layout change). Idempotent
+  // when the path is stable.
+  stampInstallDir(spec, deps);
+
   const state = await deps.supervisor.restart(short);
   if (!state) {
     registry.update(
@@ -494,6 +586,13 @@ async function runUpgrade(
     );
     return;
   }
+
+  // Refresh the on-disk well-known so the version field on the upgraded
+  // module's row reflects the new install. The HTTP path rebuilds per
+  // request, so the discovery page tracks the new version regardless;
+  // this keeps the inspection artifact aligned.
+  await regenAfterOp(opId, registry, deps);
+
   registry.update(
     opId,
     { status: "succeeded" },
@@ -540,6 +639,26 @@ export async function handleUninstall(
   const code = await run(["bun", "remove", "-g", spec.package]);
   log.push(`bun remove -g ${spec.package} exited ${code}`);
 
+  // 4. Refresh the on-disk well-known so the uninstalled module no
+  // longer appears in the inspection artifact. The HTTP path rebuilds
+  // per request, so live discovery drops the entry immediately; this
+  // is the disk-side equivalent.
+  try {
+    const regenOpts: Parameters<typeof regenerateWellKnown>[0] = {
+      manifestPath: deps.manifestPath,
+      canonicalOrigin: deps.issuer,
+    };
+    if (deps.wellKnownPath !== undefined) regenOpts.wellKnownPath = deps.wellKnownPath;
+    if (deps.readModuleManifest !== undefined) {
+      regenOpts.readModuleManifest = deps.readModuleManifest;
+    }
+    const { path } = await regenerateWellKnown(regenOpts);
+    log.push(`regenerated ${path}`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.push(`well-known regen failed: ${msg}`);
+  }
+
   return jsonOk({ short, log });
 }