@openparachute/hub 0.6.2 → 0.6.3-rc.2

package/src/port-probe.ts

@@ -0,0 +1,50 @@
+/**
+ * Loopback TCP-port readiness probe — the tiny "is something listening on
+ * 127.0.0.1:<port>?" primitive shared by the detached `commands/lifecycle.ts`
+ * start path and the in-process `supervisor.ts` (design 2026-06-01 §6.5).
+ *
+ * Factored out of `lifecycle.ts` so the supervisor can reach the probe without
+ * importing all of lifecycle's heavy graph (hub-db, operator-token,
+ * services-manifest, …) into a module that hub-server / proxy-state / the
+ * module-ops API all depend on. `lifecycle.ts` re-exports `defaultPortListening`
+ * + `PortListeningFn` so its public API is unchanged; both files share THIS
+ * one implementation, so they can't drift.
+ *
+ * `node:net` rather than `Bun.connect` because the latter has no clean
+ * "connection refused → false" without a custom socket handler, and the net
+ * Socket's `error`/`connect` events map directly onto the boolean we want.
+ */
+
+import { Socket } from "node:net";
+
+/**
+ * "Is something listening on this TCP port on loopback?" seam. Pairs with the
+ * spawn-then-die settle to catch the alive-but-never-bound failure shape
+ * (hub#487): a service that lives long enough to clear a liveness check but
+ * never binds its port (port already held by an orphan / a bun-linked
+ * resolution failure that lingers). Tests inject a deterministic stub;
+ * production uses {@link defaultPortListening}.
+ */
+export type PortListeningFn = (port: number) => Promise<boolean>;
+
+/**
+ * Connect-probe: open a TCP socket to 127.0.0.1:<port> and see if it's
+ * accepted. A successful connect means *something* is listening; we close
+ * immediately. Connection refused / timeout means nothing is bound yet.
+ */
+export const defaultPortListening: PortListeningFn = (port) =>
+  new Promise((resolve) => {
+    const socket = new Socket();
+    let settled = false;
+    const done = (listening: boolean) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(listening);
+    };
+    socket.setTimeout(1000);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+    socket.connect(port, "127.0.0.1");
+  });

package/src/process-state.ts

@@ -11,6 +11,13 @@ import { CONFIG_DIR } from "./config.ts";
  * `pid file present` + `process.kill(pid, 0)` succeeds. A stale PID file
  * (process died without cleanup) reads as stopped; writers of the PID
  * file own removing it on clean shutdown.
+ *
+ * Phase 5b retired the detached module/hub spawners that *wrote* per-service
+ * pidfiles. The pidfile READERS (`readPid` / `processState`) are deliberately
+ * kept (design §7.5) so the migrate detector (`hasPriorDetachedInstall`) can
+ * still see a prior detached install for one release. `writePid` / `clearPid`
+ * remain too — `serve` (hub-server.ts) writes its own `hub` pidfile so
+ * `parachute stop hub` / `migrate` can find a serve-mode hub.
  */
 
 export function serviceDir(svc: string, configDir: string = CONFIG_DIR): string {
@@ -70,12 +77,21 @@ export const defaultAlive: AliveFn = (pid: number) => {
 };
 
 /**
- * Three-state rather than two so we don't lie about services we can't see:
+ * Three-state, kept for legacy detection only.
+ *
+ * Phase 5b retired the detached spawners that wrote per-service pidfiles, so in
+ * the steady (supervised) state no module has a pidfile and module run-state
+ * comes from the supervisor (`supervisor.list()`), not from here. This reader
+ * survives so the `migrate` detector (`hasPriorDetachedInstall`) can still
+ * recognize a pre-cutover box, and so `serve` / `parachute stop hub` can find a
+ * serve-mode hub's own `hub` pidfile.
  *
  * - `running` — PID file present, `kill(pid, 0)` succeeds.
  * - `stopped` — PID file present, process gone (stale pidfile, or cleanly shut down).
- * - `unknown` — no PID file. Service may be externally managed (user ran
- *   `parachute-vault serve` directly, or legacy launchd-era). Don't claim stopped.
+ * - `unknown` — no PID file. In a supervised install this is the normal case
+ *   for modules (no pidfile is written); the "externally-managed / legacy
+ *   launchd-era" reading is now purely about detecting a *prior detached*
+ *   install, not a live signal. Don't claim stopped.
  */
 export interface ProcessState {
   status: "running" | "stopped" | "unknown";

package/src/setup-wizard.ts

@@ -67,7 +67,13 @@ import {
 } from "./hub-settings.ts";
 import { signAccessToken } from "./jwt-sign.ts";
 import { escapeHtml } from "./oauth-ui.ts";
-import { mintOperatorToken } from "./operator-token.ts";
+import {
+  type IssueOperatorTokenResult,
+  type MintOperatorTokenOpts,
+  issueOperatorToken,
+  mintOperatorToken,
+  readOperatorTokenFile,
+} from "./operator-token.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
 import { findService, readManifestLenient } from "./services-manifest.ts";
 import {
@@ -377,6 +383,22 @@ export interface SetupWizardDeps {
    * `readExposeStateFn` seam.
    */
   readExposeStateFn?: () => ExposeState | undefined;
+  /**
+   * Test seam for the fresh-box operator-token closure (design §3.1 /
+   * Phase 3b Deliverable A). After the wizard creates the first admin, it
+   * persists `~/.parachute/operator.token` so the box has a CLI operator
+   * credential the moment it gains an admin — without it, the Phase 3b
+   * per-module verbs (`parachute start/stop/restart <svc>` driving the
+   * supervisor) would 401 on a freshly-bootstrapped box. Production omits
+   * this and uses the real {@link issueOperatorToken}; tests inject a stub
+   * to assert the call (or to make it throw and prove a token-write failure
+   * never fails account creation).
+   */
+  issueOperatorToken?: (
+    db: Database,
+    userId: string,
+    opts: MintOperatorTokenOpts & { dir?: string },
+  ) => Promise<IssueOperatorTokenResult>;
 }
 
 /**
@@ -1888,6 +1910,16 @@ export async function handleSetupAccountPost(
     // any racer who saw it over the operator's shoulder during the
     // window between log-print and form-submit.
     if (requireToken) consumeBootstrapToken();
+    // Fresh-box operator-token closure (design §3.1 / Phase 3b Deliverable A).
+    // The box now has its first admin — persist `operator.token` so it has a
+    // CLI operator credential immediately. Without it, the Phase 3b per-module
+    // verbs (start/stop/restart <svc> driving the supervisor over the
+    // module-ops API) would 401 on a box bootstrapped purely through the
+    // wizard. Runs AFTER the admin row + bootstrap-token are committed so a
+    // half-written admin never gains a token; guarded so an existing token is
+    // never clobbered; wrapped so a token-write failure NEVER fails the
+    // account creation the operator just completed.
+    await ensureOperatorTokenForFirstAdmin(deps, user.id);
     const session = createSession(deps.db, { userId: user.id });
     const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000), {
       secure: isHttpsRequest(req),
@@ -1927,6 +1959,53 @@ export async function handleSetupAccountPost(
   }
 }
 
+/**
+ * Persist `~/.parachute/operator.token` for the just-created first admin
+ * (design §3.1 / Phase 3b Deliverable A). The 3a reviewer flagged that a fresh
+ * `init`→wizard flow ends with NO operator token on disk, so the Phase 3b
+ * per-module verbs — `parachute start/stop/restart <svc>`, which now drive the
+ * supervisor over the host-admin-gated module-ops API — would 401 on such a
+ * box. Minting the token here makes the box have a CLI operator credential the
+ * moment it gains an admin.
+ *
+ * Three invariants:
+ *   - Mints under the `admin` scope-set (the default), which carries
+ *     `parachute:host:admin` — exactly the scope `api-modules-ops.ts` gates on.
+ *     `issueOperatorToken` writes it 0600 (`writeOperatorTokenFile`).
+ *   - Guarded by `readOperatorTokenFile() === null`: never clobber a token an
+ *     operator already minted (`auth set-password` / `rotate-operator`, or a
+ *     prior init).
+ *   - Wrapped in try/catch so a token-write failure NEVER fails the account
+ *     creation the operator just completed — they have an admin row + session
+ *     either way, and `parachute auth rotate-operator` is the documented
+ *     recovery for a missing token.
+ *
+ * Uses `deps.issuer` as the `iss` claim — the same pre-resolved origin the rest
+ * of the wizard's mints use (`handleSetupExposePost`). The hub-server derives
+ * that origin the same way `commands/auth.ts:resolveHubIssuer` does — semantically
+ * equivalent, structurally different: this path takes a pre-resolved `deps.issuer`
+ * while `auth.ts` reads expose-state inline at call time. `start hub` self-heals a
+ * stale `iss` later if the box is exposed after init (hub#481), so an
+ * init-at-loopback mint is correct here.
+ */
+async function ensureOperatorTokenForFirstAdmin(
+  deps: SetupWizardDeps,
+  userId: string,
+): Promise<void> {
+  const issue = deps.issueOperatorToken ?? issueOperatorToken;
+  try {
+    const existing = await readOperatorTokenFile(deps.configDir);
+    if (existing !== null) return;
+    await issue(deps.db, userId, { issuer: deps.issuer, dir: deps.configDir });
+  } catch (err) {
+    // Non-fatal: the admin + session were already committed. Log for the
+    // operator's debugging; they can recover with `parachute auth
+    // rotate-operator` from a shell on the box.
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`[setup-wizard] operator-token closure skipped for new admin: ${msg}`);
+  }
+}
+
 /**
  * Static error page surfaced when an `/admin/setup/account` POST arrives
  * after the bootstrap token has already been consumed by a successful