@openparachute/hub 0.5.14-rc.8 → 0.6.0

package/src/services-manifest.ts

@@ -185,6 +185,39 @@ export interface ServiceEntry {
    * with display metadata attached.
    */
   uis?: Record<string, UiSubUnit>;
+  /**
+   * Last `parachute start` failure that's still actionable, persisted so a
+   * *subsequent* `parachute status` (a separate invocation that only reads
+   * this manifest) + the admin SPA can surface it. Today the only writer is
+   * the lifecycle start preflight when a startCmd binary is missing from PATH
+   * (`@openparachute/depcheck` `MissingDependencyError.toWire()`): the row
+   * shows "failed to start — <binary> not installed" with the install info
+   * instead of a bare orphan-timeout. Cleared on the next successful start.
+   *
+   * Stored as the structured `missing_dependency` wire so the SPA can render
+   * the dedicated install card; `parachute status` reads `error_description`.
+   * Validated as a pass-through object (shape owned by depcheck) rather than
+   * re-typed field-by-field here.
+   */
+  lastStartError?: ServiceEntryStartError;
+}
+
+/**
+ * Persisted start-failure detail on a ServiceEntry. Mirrors depcheck's
+ * `MissingDependencyWire` for the missing-dependency case; `error_type` is
+ * left open so a future non-dependency start failure could reuse the field.
+ */
+export interface ServiceEntryStartError {
+  error_type: string;
+  error_description: string;
+  /** Present for `error_type: "missing_dependency"`. */
+  binary?: string;
+  why?: string | null;
+  docs_url?: string | null;
+  install?: { darwin?: string; linux?: string; generic?: string };
+  sysadmin_hint?: string;
+  /** ISO timestamp of when the failure was recorded. */
+  at?: string;
 }
 
 export interface ServicesManifest {
@@ -251,6 +284,7 @@ function validateEntry(raw: unknown, where: string): ServiceEntry {
   }
   const uis = e.uis;
   const validatedUis = validateUis(uis, where);
+  const validatedStartError = validateStartError(e.lastStartError, where);
   const entry: ServiceEntry = { name, port, paths: paths as string[], health, version };
   if (displayName !== undefined) entry.displayName = displayName;
   if (tagline !== undefined) entry.tagline = tagline;
@@ -258,9 +292,48 @@ function validateEntry(raw: unknown, where: string): ServiceEntry {
   if (installDir !== undefined) entry.installDir = installDir;
   if (stripPrefix !== undefined) entry.stripPrefix = stripPrefix;
   if (validatedUis !== undefined) entry.uis = validatedUis;
+  if (validatedStartError !== undefined) entry.lastStartError = validatedStartError;
   return entry;
 }
 
+/**
+ * Validate the optional `lastStartError` field. `undefined` round-trips
+ * unchanged. A present value must be an object carrying the two required
+ * string fields (`error_type`, `error_description`); the remaining fields
+ * (the missing-dependency detail) pass through with light type-narrowing so
+ * the SPA install card has them, but we never hard-fail an otherwise-valid
+ * row on a malformed start-error — it's diagnostic metadata, not a contract
+ * field. A malformed value is dropped rather than thrown.
+ */
+function validateStartError(raw: unknown, _where: string): ServiceEntryStartError | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const r = raw as Record<string, unknown>;
+  if (typeof r.error_type !== "string" || typeof r.error_description !== "string") {
+    return undefined;
+  }
+  const out: ServiceEntryStartError = {
+    error_type: r.error_type,
+    error_description: r.error_description,
+  };
+  if (typeof r.binary === "string") out.binary = r.binary;
+  if (typeof r.why === "string" || r.why === null) out.why = r.why as string | null;
+  if (typeof r.docs_url === "string" || r.docs_url === null) {
+    out.docs_url = r.docs_url as string | null;
+  }
+  if (r.install && typeof r.install === "object" && !Array.isArray(r.install)) {
+    const ins = r.install as Record<string, unknown>;
+    const install: { darwin?: string; linux?: string; generic?: string } = {};
+    if (typeof ins.darwin === "string") install.darwin = ins.darwin;
+    if (typeof ins.linux === "string") install.linux = ins.linux;
+    if (typeof ins.generic === "string") install.generic = ins.generic;
+    out.install = install;
+  }
+  if (typeof r.sysadmin_hint === "string") out.sysadmin_hint = r.sysadmin_hint;
+  if (typeof r.at === "string") out.at = r.at;
+  return out;
+}
+
 /**
  * Validate the optional `uis` map on a ServiceEntry. `undefined` round-trips
  * unchanged (the field is optional); a present map must be a plain object
@@ -763,3 +836,42 @@ export function findService(
   // missed.
   return readManifestLenient(path).services.find((s) => s.name === name);
 }
+
+/**
+ * Persist a `lastStartError` onto the named row so a later `parachute status`
+ * + the admin SPA surface it. No-op if the row isn't present (e.g. a service
+ * that failed to start before its first self-registration wrote a row — the
+ * inline `parachute start` message already told the operator). Lenient read
+ * so a malformed sibling row doesn't block recording an unrelated failure.
+ */
+export function recordStartError(
+  name: string,
+  err: ServiceEntryStartError,
+  path: string = SERVICES_MANIFEST_PATH,
+): void {
+  if (!existsSync(path)) return;
+  const current = readManifestLenient(path);
+  const idx = current.services.findIndex((s) => s.name === name);
+  if (idx < 0) return;
+  const row = current.services[idx];
+  if (!row) return;
+  current.services[idx] = {
+    ...row,
+    lastStartError: { ...err, at: err.at ?? new Date().toISOString() },
+  };
+  writeManifest(current, path);
+}
+
+/** Clear a row's persisted `lastStartError` (called on a successful start).
+ * No-op when the row is absent or already clean. */
+export function clearStartError(name: string, path: string = SERVICES_MANIFEST_PATH): void {
+  if (!existsSync(path)) return;
+  const current = readManifestLenient(path);
+  const idx = current.services.findIndex((s) => s.name === name);
+  if (idx < 0) return;
+  const row = current.services[idx];
+  if (!row || row.lastStartError === undefined) return;
+  const { lastStartError: _drop, ...rest } = row;
+  current.services[idx] = rest;
+  writeManifest(current, path);
+}

package/src/setup-wizard.ts

@@ -55,6 +55,7 @@ import {
   renderCsrfHiddenInput,
   verifyCsrfToken,
 } from "./csrf.ts";
+import { type ExposeState, readExposeState } from "./expose-state.ts";
 import {
   SETUP_EXPOSE_MODES,
   type SetupExposeMode,
@@ -207,13 +208,41 @@ export interface DerivedWizardState {
  */
 export const FIRST_VAULT_SHORT: CuratedModuleShort = "vault";
 
+/**
+ * Map a live exposure layer (`expose-state.json`) onto the wizard's
+ * `setup_expose_mode`. The two enums overlap exactly on the layers the
+ * exposure file can carry: `ExposeLayer` is `tailnet | public`, both of
+ * which are valid `SetupExposeMode` values. (There's no `localhost`
+ * exposure layer — running nothing is the absence of a state file, which
+ * `readExposeState` reports as `undefined`, so a missing/unexposed hub
+ * never seeds and the wizard still asks.)
+ *
+ * Returns `undefined` when no exposure is live (or the reader throws on
+ * a malformed file — we swallow that and fall through to "still ask"
+ * rather than crashing the wizard GET).
+ */
+function exposeModeFromLiveState(read: () => ExposeState | undefined): SetupExposeMode | undefined {
+  let state: ExposeState | undefined;
+  try {
+    state = read();
+  } catch {
+    // A corrupt expose-state.json shouldn't brick the wizard. Treat it
+    // as "no live exposure" and let the operator answer the step.
+    return undefined;
+  }
+  if (!state) return undefined;
+  // `ExposeLayer` ⊆ `SetupExposeMode` ("tailnet" | "public").
+  return state.layer;
+}
+
 /**
  * Read DB + services.json to decide which step the wizard should render.
  * Idempotent — re-running after partial setup picks up where it left
  * off. Mostly read-only, with one specific write: on Render (or any
- * platform `detectAutoExposeMode` recognizes), the first call auto-
- * seeds `setup_expose_mode = "public"` so the wizard skips the expose
- * step. Subsequent calls find the setting present and are read-only.
+ * platform `detectAutoExposeMode` recognizes), OR when a live tailscale
+ * exposure (`expose-state.json`) is already up, the first call auto-
+ * seeds `setup_expose_mode` so the wizard skips the expose step.
+ * Subsequent calls find the setting present and are read-only.
  */
 export function deriveWizardState(deps: {
   db: Database;
@@ -224,6 +253,15 @@ export function deriveWizardState(deps: {
    * SetupWizardDeps.env.
    */
   env?: Record<string, string | undefined>;
+  /**
+   * Optional injected reader for the live exposure state
+   * (`~/.parachute/expose-state.json`). Defaults to the real
+   * `readExposeState`. Mirrors the `init.ts` seam (`readExposeStateFn`)
+   * so tests can drive the "a tailnet layer is already live" branch
+   * without writing a real state file. When `setup_expose_mode` is
+   * unset, the live exposure layer auto-seeds the setting (see below).
+   */
+  readExposeStateFn?: () => ExposeState | undefined;
 }): DerivedWizardState {
   const hasAdmin = userCount(deps.db) > 0;
   // The wizard's first-vault provisioning uses the curated `vault` short,
@@ -252,6 +290,23 @@ export function deriveWizardState(deps: {
   ) {
     setSetting(deps.db, "setup_expose_mode", "public");
   }
+  // hub#406 team-onboarding bug: `setup_expose_mode` (the wizard's
+  // answer) and `expose-state.json` (the live tailscale exposure) are
+  // orthogonal axes. An operator who ran `parachute expose tailnet`
+  // before opening the wizard has a live tailnet layer but no
+  // `setup_expose_mode` setting — so the wizard re-asked "how will this
+  // hub be reached?" even though tailnet was already up. Auto-seed the
+  // setting from the live exposure layer (tailnet→"tailnet",
+  // public→"public") so the answered-by-action case is treated as
+  // satisfied, mirroring the Render/Fly auto-seed above. Reading the
+  // live state is injected for testability (defaults to the real
+  // reader); a malformed/missing file falls through to "still ask."
+  if (getSetting(deps.db, "setup_expose_mode") === undefined) {
+    const seeded = exposeModeFromLiveState(deps.readExposeStateFn ?? readExposeState);
+    if (seeded !== undefined) {
+      setSetting(deps.db, "setup_expose_mode", seeded);
+    }
+  }
   const hasExposeMode = getSetting(deps.db, "setup_expose_mode") !== undefined;
   let step: WizardStep;
   // Note: `"account"` is a visual-only step in the progress header —
@@ -314,6 +369,14 @@ export interface SetupWizardDeps {
    * without mutating the real process env.
    */
   env?: Record<string, string | undefined>;
+  /**
+   * Test seam: inject the live-exposure reader `deriveWizardState`
+   * consults to auto-seed `setup_expose_mode` from a live
+   * `parachute expose tailnet|public` (hub#406). Production omits this
+   * and the real `readExposeState` is used. Mirrors `init.ts`'s
+   * `readExposeStateFn` seam.
+   */
+  readExposeStateFn?: () => ExposeState | undefined;
 }
 
 /**
@@ -446,7 +509,11 @@ export interface RenderAccountStepProps {
 export function renderAccountStep(props: RenderAccountStepProps): string {
   const { csrfToken, errorMessage, username, requireBootstrapToken, bootstrapToken } = props;
   const error = errorMessage ? `<p class="error-banner">${escapeHtml(errorMessage)}</p>` : "";
-  const usernameAttr = username ? ` value="${escapeAttr(username)}"` : "";
+  // Pre-fill "owner" on a fresh render (no prior submission) so the web wizard's
+  // default matches the CLI paths (`set-password`, `setup-wizard`) + the
+  // operator.token convention. Operators can still type any name. On a
+  // validation-failure re-render we echo back what they typed instead.
+  const usernameAttr = ` value="${escapeAttr(username ?? "owner")}"`;
   const tokenAttr = bootstrapToken ? ` value="${escapeAttr(bootstrapToken)}"` : "";
   // Bootstrap-token field comes FIRST when required. An operator who
   // missed the log line is stopped here rather than after filling
@@ -1232,9 +1299,12 @@ function renderMcpTile(
     <h2>Connect Claude Code (MCP)</h2>
     <p>Wire <code>vault:${safeVault}</code> into Claude Code as an MCP server:</p>
     <pre>${escapeHtml(bareCmd)}</pre>
-    <p class="fine">Mint an operator token at
-      <a href="/admin/tokens"><code>/admin/tokens</code></a> and append
-      <code>--header "Authorization: Bearer pvt_..."</code> on first use.</p>
+    <p class="fine">No token needed — the command triggers browser OAuth on
+      first use (you sign in to this hub and approve access). For headless
+      clients that can't do the browser flow, mint a hub token at
+      <a href="/admin/tokens"><code>/admin/tokens</code></a> (or with
+      <code>parachute auth mint-token</code>) and append
+      <code>--header "Authorization: Bearer &lt;token&gt;"</code>.</p>
   </div>`;
 }
 

package/src/tailscale/run.ts

@@ -1,3 +1,5 @@
+import { ensureExecutable, rethrowIfMissing } from "@openparachute/depcheck";
+
 export interface CommandResult {
   code: number;
   stdout: string;
@@ -7,19 +9,34 @@ export interface CommandResult {
 export type Runner = (cmd: readonly string[]) => Promise<CommandResult>;
 
 export async function defaultRunner(cmd: readonly string[]): Promise<CommandResult> {
+  // Pre-flight the binary so a missing `tailscale` surfaces the friendly
+  // install UX (`@openparachute/depcheck`) instead of a raw spawn throw —
+  // closes the no-hint gap where `parachute expose tailnet` on a box without
+  // tailscale died with `Executable not found in $PATH: "tailscale"`.
+  // `cmd[0]` is always present for a real call; guard for the empty edge.
+  const binary = cmd[0];
+  if (binary) ensureExecutable(binary);
   // Inherit env so `tailscale` sees PATH (and HOME for state dir). Bun.spawn
   // defaults to empty env — see api-modules-ops.ts:defaultRun for rationale.
-  const proc = Bun.spawn([...cmd], {
-    stdout: "pipe",
-    stderr: "pipe",
-    env: process.env,
-  });
-  const [stdout, stderr, code] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-    proc.exited,
-  ]);
-  return { code, stdout, stderr };
+  try {
+    const proc = Bun.spawn([...cmd], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: process.env,
+    });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    return { code, stdout, stderr };
+  } catch (err) {
+    // Belt-and-suspenders: a spawn that slips past the pre-flight (binary
+    // removed between which() and spawn, or a race) still surfaces the
+    // friendly MissingDependencyError rather than the raw spawn throw.
+    if (binary) rethrowIfMissing(err, binary);
+    throw err;
+  }
 }
 
 export class TailscaleError extends Error {

package/src/totp.ts

@@ -0,0 +1,201 @@
+import { createHash } from "node:crypto";
+/**
+ * TOTP (RFC 6238) primitives + single-use backup codes for hub-login 2FA
+ * (hub#473). The pure crypto layer — no DB, no HTTP. The persistence layer
+ * (`two-factor-store.ts`) reads/writes these against `users` in hub.db; the
+ * login + enroll handlers compose both.
+ *
+ * Approach ported from `parachute-vault/src/two-factor.ts` (the deprecated
+ * vault impl), with two deliberate hub-side changes:
+ *
+ *   - Storage is hub.db's `users` row, not vault's `config.yaml`. That lives
+ *     in `two-factor-store.ts`; this file stays storage-agnostic.
+ *   - Backup codes are hashed with **argon2id** (`@node-rs/argon2`), the same
+ *     hasher hub uses for passwords (`users.ts`), rather than vault's bcrypt.
+ *     One hash family across the hub keeps the dependency surface minimal and
+ *     matches the brief ("same hash as passwords").
+ *
+ * TOTP parameters (interop default — what Google Authenticator / 1Password /
+ * Authy expect): SHA-1, 6 digits, 30s period. Validation accepts a ±1 window
+ * (≈90s effective tolerance) for clock drift. A given (secret, counter) is
+ * single-use within its acceptance lifetime — replays inside the window are
+ * rejected via an in-memory cache.
+ */
+import { hash as argonHash, verify as argonVerify } from "@node-rs/argon2";
+import * as OTPAuth from "otpauth";
+
+/** Issuer label shown in the authenticator app + encoded in the otpauth URI. */
+export const TOTP_ISSUER = "Parachute Hub";
+/** Number of single-use backup codes minted per enrollment. */
+export const BACKUP_CODE_COUNT = 10;
+/** Length (characters) of each backup code. */
+const BACKUP_CODE_LENGTH = 10;
+/** TOTP secret size in bytes (20 = 160 bits, the RFC 6238 / RFC 4226 default). */
+const TOTP_SECRET_BYTES = 20;
+
+function makeTotp(secretBase32: string, label: string): OTPAuth.TOTP {
+  return new OTPAuth.TOTP({
+    issuer: TOTP_ISSUER,
+    label,
+    algorithm: "SHA1",
+    digits: 6,
+    period: 30,
+    secret: OTPAuth.Secret.fromBase32(secretBase32),
+  });
+}
+
+export interface GeneratedSecret {
+  /** Base32-encoded secret — show to the user for manual authenticator entry. */
+  secret: string;
+  /** `otpauth://totp/...` URI — encode as a QR code for scanning. */
+  otpauthUrl: string;
+}
+
+/**
+ * Generate a fresh TOTP secret + its `otpauth://` provisioning URI. `label`
+ * is the account label rendered in the authenticator app (typically the
+ * username). Does NOT persist anything — the caller stores the returned
+ * `secret` only after the user confirms a code (proving the authenticator
+ * was set up correctly).
+ */
+export function generateTotpSecret(label: string): GeneratedSecret {
+  const secret = new OTPAuth.Secret({ size: TOTP_SECRET_BYTES }).base32;
+  const totp = makeTotp(secret, label);
+  return { secret, otpauthUrl: totp.toString() };
+}
+
+/** Build the `otpauth://` URI for an existing secret (e.g. re-display during enroll). */
+export function otpauthUrlFor(secretBase32: string, label: string): string {
+  return makeTotp(secretBase32, label).toString();
+}
+
+/**
+ * In-memory cache of recently-used TOTP counters, to reject replay inside the
+ * ±1 acceptance window. Key = "sha256(secret):counter"; value = expiry ms.
+ * Bounded — entries auto-expire ~2 min after their window closes. Process-
+ * local (a restart clears it, which is itself fine: the window is 90s).
+ */
+const usedTotpCounters = new Map<string, number>();
+
+function gcUsedTotp(now: number): void {
+  for (const [k, exp] of usedTotpCounters) {
+    if (exp < now) usedTotpCounters.delete(k);
+  }
+}
+
+/**
+ * Verify a 6-digit TOTP code against `secretBase32`. Accepts ±1 window
+ * (prev / current / next 30s period). A given (secret, counter) is single-use
+ * within its acceptance lifetime — replays are rejected.
+ *
+ * `markUsed`: set false in tests that want to verify the same code twice.
+ * Defaults to true in production so a captured code can't be replayed inside
+ * its ~90s validity window.
+ */
+export function verifyTotpCode(secretBase32: string, code: string, markUsed = true): boolean {
+  const trimmed = code.trim().replace(/\s+/g, "");
+  if (!/^\d{6}$/.test(trimmed)) return false;
+  try {
+    const totp = makeTotp(secretBase32, "owner");
+    const delta = totp.validate({ token: trimmed, window: 1 });
+    if (delta === null) return false;
+
+    const now = Date.now();
+    gcUsedTotp(now);
+    const counter = Math.floor(now / 30_000) + delta;
+    // Hash the secret so the in-memory replay cache never holds the plaintext
+    // TOTP secret as a map key (defense in depth against heap dumps / logs).
+    const secretHash = createHash("sha256").update(secretBase32).digest("hex");
+    const key = `${secretHash}:${counter}`;
+    if (usedTotpCounters.has(key)) return false;
+    if (markUsed) {
+      // Expire the entry a bit after the outer edge of the acceptance window.
+      usedTotpCounters.set(key, now + 120_000);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Test-only: reset the replay-protection cache between cases. */
+export function _resetTotpReplayCache(): void {
+  usedTotpCounters.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Backup codes
+// ---------------------------------------------------------------------------
+
+function randomBackupCode(): string {
+  // Lowercase alphanumeric minus ambiguous glyphs (0/o, 1/l/i). Read-aloud
+  // friendly + unambiguous when typed back in. Formatted as two 5-char groups
+  // (`abcde-fghij`) for legibility; the hyphen is cosmetic and stripped on
+  // verify so the user can type it with or without.
+  const alphabet = "abcdefghjkmnpqrstuvwxyz23456789";
+  const bytes = crypto.getRandomValues(new Uint8Array(BACKUP_CODE_LENGTH));
+  let out = "";
+  for (let i = 0; i < BACKUP_CODE_LENGTH; i++) {
+    out += alphabet[bytes[i]! % alphabet.length];
+    if (i === 4) out += "-";
+  }
+  return out;
+}
+
+/** Normalize a backup code for hashing / comparison: lowercase, no whitespace, no hyphens. */
+export function normalizeBackupCode(code: string): string {
+  return code
+    .trim()
+    .toLowerCase()
+    .replace(/[\s-]+/g, "");
+}
+
+export interface GeneratedBackupCodes {
+  /** Plaintext codes to show the user ONCE (hyphenated for display). */
+  codes: string[];
+  /** argon2id hashes of the normalized codes — what gets stored. */
+  hashes: string[];
+}
+
+/**
+ * Generate {@link BACKUP_CODE_COUNT} fresh backup codes + their argon2id
+ * hashes. The plaintext `codes` are displayed once at enrollment; only the
+ * `hashes` are persisted (as a JSON array). Each code is hashed in its
+ * normalized form so display-formatting (hyphen) never affects verification.
+ */
+export async function generateBackupCodes(): Promise<GeneratedBackupCodes> {
+  const codes: string[] = [];
+  const hashes: string[] = [];
+  for (let i = 0; i < BACKUP_CODE_COUNT; i++) {
+    const code = randomBackupCode();
+    codes.push(code);
+    hashes.push(await argonHash(normalizeBackupCode(code)));
+  }
+  return { codes, hashes };
+}
+
+/**
+ * Check a submitted backup code against a stored hash list. Returns the
+ * **index** of the matching hash (so the caller can splice it out and persist
+ * the shorter list — single-use consumption), or `-1` for no match.
+ *
+ * Pure: does NOT mutate the input list or persist anything. Consumption +
+ * persistence is the store layer's job (`two-factor-store.ts`), which holds
+ * the DB transaction so verify-then-consume is atomic against concurrent
+ * login attempts.
+ */
+export async function findBackupCodeIndex(
+  code: string,
+  hashes: readonly string[],
+): Promise<number> {
+  const normalized = normalizeBackupCode(code);
+  if (!normalized) return -1;
+  for (let i = 0; i < hashes.length; i++) {
+    try {
+      if (await argonVerify(hashes[i]!, normalized)) return i;
+    } catch {
+      // Corrupt / non-argon hash — skip.
+    }
+  }
+  return -1;
+}