@openparachute/hub 0.6.3 → 0.6.4-rc.1

package/src/commands/serve.ts

@@ -26,17 +26,21 @@
 
 import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { selfHealScribeAuth } from "../auto-wire.ts";
 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
 // path isolation.
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
+import { readExposeState } from "../expose-state.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { hubFetch } from "../hub-server.ts";
 import { writeHubFile } from "../hub.ts";
+import { enrichedPath } from "../spawn-path.ts";
 import { Supervisor } from "../supervisor.ts";
 import { createUser, userCount } from "../users.ts";
+import { sanitizePublicOrigin } from "../vault-hub-origin-env.ts";
 import { WELL_KNOWN_DIR } from "../well-known.ts";
 import { bootSupervisedModules } from "./serve-boot.ts";
 
@@ -101,6 +105,22 @@ export function formatListeningBanner(args: {
   return `parachute serve: listening on http://${displayHost}:${port}${boundNote} (PARACHUTE_HOME=${configDir}, db=${dbPath}, issuer=${issuer ?? "<request-origin>"}, admin=${adminBootstrap})`;
 }
 
+/**
+ * Map a `Bun.serve` bind failure to a clear "another supervisor is running"
+ * message when it's a port-in-use error, or `null` for any other error (so the
+ * caller re-throws the original). Keeps a duplicate-supervisor start from
+ * surfacing as a raw `EADDRINUSE` stack — the operator's actionable next step
+ * is "stop the other instance," not a backtrace. See hub#536. Exported for
+ * testing (the bind itself isn't seam-injectable).
+ */
+export function hubPortConflictMessage(err: unknown, port: number): string | null {
+  const msg = err instanceof Error ? err.message : String(err);
+  if (/EADDRINUSE|address already in use|in use/i.test(msg)) {
+    return `parachute serve: hub port ${port} is already in use — another hub/supervisor is running. Refusing to start a duplicate supervisor (it would fight the live one over module ports). Stop the other instance first, then retry.`;
+  }
+  return null;
+}
+
 function parsePort(raw: string | undefined): number | undefined {
   if (raw === undefined || raw === "") return undefined;
   const n = Number.parseInt(raw, 10);
@@ -124,7 +144,21 @@ function parsePort(raw: string | undefined): number | undefined {
  *      operator can't know the URL at deploy time. Without this, supervised
  *      modules' iss-validation breaks on hub-minted tokens (iss-mismatch
  *      every time).
- *   4. None (returns undefined). Hub falls back to per-request derivation
+ *   4. `expose-state.json`'s `hubOrigin` — the canonical public origin a
+ *      live tailscale/cloudflare exposure recorded (e.g.
+ *      `https://parachute.taildf9ce2.ts.net`). This is the load-bearing
+ *      tier for the **owner-operated reboot-persistent path**: the launchd
+ *      plist / systemd unit that keeps `parachute serve` alive carries no
+ *      `PARACHUTE_HUB_ORIGIN` env, so on every reboot the hub would
+ *      otherwise boot issuer-less (tier 5), stamp `iss` from the per-request
+ *      origin, and inject nothing into children — vault then defaults to
+ *      loopback and rejects hub-minted tokens with `unexpected "iss" claim
+ *      value` until it restarts. Reading the exposed origin off disk makes
+ *      `iss` deterministic across reboots with zero operator action. Guarded
+ *      to a non-loopback `http(s)` origin (a loopback value here would
+ *      re-pin the degraded mode; expose-state should never carry one, but we
+ *      defend anyway).
+ *   5. None (returns undefined). Hub falls back to per-request derivation
  *      via `resolveIssuer` in hub-server.ts — works for `/.well-known`
  *      discovery but supervised modules with cached iss expectations
  *      won't have a static value to validate against, so OAuth flows
@@ -136,18 +170,60 @@ function parsePort(raw: string | undefined): number | undefined {
  *
  * Trailing slashes are stripped for canonical-form comparison; empty
  * strings collapse to undefined.
+ *
+ * `readExpose` is injectable so tests exercise the expose-state tier
+ * without touching the real `~/.parachute`. The default reads
+ * `expose-state.json` and swallows a malformed-file throw (a corrupt state
+ * file must never crash startup — fall through to the request-origin mode);
+ * the `readExpose()` call is additionally try/catch-wrapped here so even an
+ * injected non-swallowing reader can't crash startup.
+ *
+ * KNOWN ASTERISK (tracked in #532): this resolves the issuer at boot, so a
+ * child module spawned during a *pre-expose* boot — hub started before the
+ * first-ever `parachute expose` — gets no `PARACHUTE_HUB_ORIGIN` injected
+ * until it's restarted after the exposure exists. Once an exposure is
+ * recorded, every subsequent reboot picks it up here automatically. The
+ * remaining gap (rebuild the live spawn-env on `supervisor.restart` so the
+ * first exposure propagates to already-running children without a manual
+ * restart) is the deferred #532 follow-up; not implemented in this PR.
  */
 export function resolveStartupIssuer(
   opts: { issuer?: string },
   env: NodeJS.ProcessEnv,
+  readExpose: () => string | undefined = defaultReadExposeHubOrigin,
 ): string | undefined {
   const flyOrigin = flyDefaultOriginFromEnv(env);
-  return (
-    (opts.issuer ?? env.PARACHUTE_HUB_ORIGIN ?? env.RENDER_EXTERNAL_URL ?? flyOrigin)?.replace(
-      /\/+$/,
-      "",
-    ) || undefined
-  );
+  const explicit = (
+    opts.issuer ??
+    env.PARACHUTE_HUB_ORIGIN ??
+    env.RENDER_EXTERNAL_URL ??
+    flyOrigin
+  )?.replace(/\/+$/, "");
+  if (explicit) return explicit;
+  // No flag / env / platform origin set — fall back to the exposed origin
+  // recorded on disk. `sanitizePublicOrigin` applies the same non-loopback
+  // http(s) guard as the hub-server chokepoint (#531) so a stray loopback
+  // value never pins the degraded request-origin mode.
+  let raw: string | undefined;
+  try {
+    raw = readExpose();
+  } catch {
+    return undefined;
+  }
+  return sanitizePublicOrigin(raw);
+}
+
+/**
+ * Read `expose-state.json`'s `hubOrigin` for the startup-issuer fallback,
+ * swallowing a malformed-file throw. Kept separate so it can be passed as
+ * the default `readExpose` arg and stubbed in tests.
+ */
+function defaultReadExposeHubOrigin(): string | undefined {
+  try {
+    return readExposeState()?.hubOrigin;
+  } catch {
+    return undefined;
+  }
 }
 
 /**
@@ -242,6 +318,16 @@ export async function serve(opts: ServeOpts = {}): Promise<{
   const env = opts.env ?? process.env;
   const log = opts.log ?? ((line) => console.log(line));
 
+  // PATH enrichment (hub launchd-PATH regression): the launchd/systemd hub unit
+  // bakes a minimal PATH. Enrich the hub's OWN process PATH so its `Bun.which`
+  // probes (cloudflared / tailscale detection, etc.) see operator-tool dirs
+  // (`$HOME/.local/bin`, brew bin) too — and so any child that inherits raw
+  // `process.env` (not the explicit per-child env) starts from the enriched
+  // PATH. The per-child spawn env is enriched independently in
+  // `buildModuleSpawnRequest` / `spawnSupervised`. See `spawn-path.ts`. Only
+  // mutate the live process env, never a test-injected `opts.env`.
+  if (!opts.env) process.env.PATH = enrichedPath(process.env);
+
   const envPort = parsePort(env.PORT);
   const port = opts.port ?? envPort ?? DEFAULT_PORT;
   const issuer = resolveStartupIssuer(opts, env);
@@ -276,8 +362,71 @@ export async function serve(opts: ServeOpts = {}): Promise<{
 
   const supervisor = opts.supervisor ?? new Supervisor();
 
-  // Boot already-installed modules from services.json. In a container,
-  // this is the path that re-spawns vault / notes / scribe after a
+  // Claim the hub port FIRST — before booting a single supervised module. If
+  // another hub/supervisor already owns it, `Bun.serve` throws here and we
+  // exit immediately. The prior order (boot modules, *then* bind) let a
+  // duplicate `serve` spawn + port-race the live hub's children over their
+  // module ports before it ever hit the hub-port conflict — the
+  // dual-supervisor crash loop in hub#536. Binding first makes a duplicate
+  // fail fast and cleanly, leaving the live hub's children untouched.
+  let server: ReturnType<typeof Bun.serve>;
+  try {
+    server = Bun.serve({
+      port,
+      hostname,
+      // Hold idle keep-alive connections for Bun's maximum 255s so reverse-
+      // proxy edges (Render, Cloudflare, fly.io) don't race us when reusing
+      // pooled connections. See `src/hub-server.ts` for the full rationale —
+      // this is the active code path for `bun src/cli.ts serve` (the Docker
+      // CMD), so the fix has to land here too. Closes hub#399.
+      idleTimeout: 255,
+      fetch: hubFetch(WELL_KNOWN_DIR, {
+        getDb: () => db,
+        issuer,
+        loopbackPort: port,
+        supervisor,
+      }),
+    });
+  } catch (err) {
+    const conflict = hubPortConflictMessage(err, port);
+    if (conflict) throw new Error(conflict);
+    throw err;
+  }
+
+  log(
+    formatListeningBanner({
+      hostname,
+      port,
+      configDir: CONFIG_DIR,
+      dbPath,
+      issuer,
+      adminBootstrap,
+    }),
+  );
+
+  // Self-heal scribe's auth token from vault's .env (item H) BEFORE booting
+  // modules, so scribe's first boot below reads the synced config. Closes the
+  // "scribe installed pre-auto-wire boots auth-OPEN over loopback" gap: every
+  // `serve` start re-syncs scribe's `auth.required_token` to vault's
+  // SCRIBE_AUTH_TOKEN. Fully idempotent — no-op when there's nothing to sync or
+  // the two already match; logs only when it heals. Mirrors the issuer
+  // self-heal pattern in vault-hub-origin-env.ts. Skipped in tests via
+  // `opts.skipModuleBoot` (which also gates the boot it feeds).
+  if (!opts.skipModuleBoot) {
+    try {
+      selfHealScribeAuth({ configDir: CONFIG_DIR, log });
+    } catch (err) {
+      // A self-heal failure must never block the hub from starting — scribe
+      // just keeps whatever auth state it had. Log and move on.
+      log(
+        `parachute serve: scribe auth self-heal failed (${err instanceof Error ? err.message : String(err)}); continuing.`,
+      );
+    }
+  }
+
+  // Boot already-installed modules from services.json — now that we own the
+  // hub port (above), we're guaranteed to be the sole supervisor. In a
+  // container, this is the path that re-spawns vault / notes / scribe after a
   // restart — the persistent disk preserved both the install (in
   // `$BUN_INSTALL/install/global/node_modules`) and the row that says
   // "this module is registered + active." Idempotent: the supervisor
@@ -304,34 +453,6 @@ export async function serve(opts: ServeOpts = {}): Promise<{
     }
   }
 
-  const server = Bun.serve({
-    port,
-    hostname,
-    // Hold idle keep-alive connections for Bun's maximum 255s so reverse-
-    // proxy edges (Render, Cloudflare, fly.io) don't race us when reusing
-    // pooled connections. See `src/hub-server.ts` for the full rationale —
-    // this is the active code path for `bun src/cli.ts serve` (the Docker
-    // CMD), so the fix has to land here too. Closes hub#399.
-    idleTimeout: 255,
-    fetch: hubFetch(WELL_KNOWN_DIR, {
-      getDb: () => db,
-      issuer,
-      loopbackPort: port,
-      supervisor,
-    }),
-  });
-
-  log(
-    formatListeningBanner({
-      hostname,
-      port,
-      configDir: CONFIG_DIR,
-      dbPath,
-      issuer,
-      adminBootstrap,
-    }),
-  );
-
   return {
     result: {
       port,

package/src/commands/status.ts

@@ -20,6 +20,7 @@ import {
 import {
   type DriveModuleOpDeps,
   type ModuleStatesResult,
+  type ModuleStateSnapshot,
   NoOperatorTokenError,
   OperatorTokenExpiredError,
   fetchModuleStates as fetchModuleStatesImpl,
@@ -487,10 +488,17 @@ async function buildSupervisorRows(args: BuildSupervisorRowsArgs): Promise<Statu
     }
   }
 
-  const stateByShort = new Map<string, ModuleStatesResult["modules"][number]>();
+  const stateByShort = new Map<string, ModuleStateSnapshot>();
   for (const m of states?.modules ?? []) {
     if (m.short) stateByShort.set(m.short, m);
   }
+  // Fall back to the full `supervised` snapshot for modules the curated
+  // `modules` catalog omits — e.g. the `surface` UI host, which the supervisor
+  // runs but isn't a curated installable. Without this it'd map to `inactive`
+  // despite running (hub#539). Curated entries already in the map win (richer).
+  for (const m of states?.supervised ?? []) {
+    if (m.short && !stateByShort.has(m.short)) stateByShort.set(m.short, m);
+  }
 
   const rows: StatusRow[] = manifest.services.map((entry) => {
     const base = manifestRowBase(entry, installSourceDeps);

package/src/hub-db.ts

@@ -2,8 +2,9 @@
  * Hub-local SQLite database. Opens `~/.parachute/hub.db` (overridable via
  * `$PARACHUTE_HOME`). Holds everything the hub owns as the ecosystem's OAuth
  * issuer — signing keys (v1), users + opaque refresh tokens (v2), OAuth
- * clients + auth-codes + grants + browser sessions (v3), and TOTP 2FA
- * enrollment on the users row (v11, hub#473).
+ * clients + auth-codes + grants + browser sessions (v3), TOTP 2FA
+ * enrollment on the users row (v11, hub#473), and one-time invite links
+ * (v12, the `invites` table).
  *
  * Each open() runs `migrate()` to bring the schema up to date. A
  * `schema_version` table records every applied migration so re-opens are
@@ -358,6 +359,73 @@ const MIGRATIONS: readonly Migration[] = [
       ALTER TABLE users ADD COLUMN totp_enrolled_at TEXT;
     `,
   },
+  {
+    version: 12,
+    sql: `
+      -- One-time, expiring invite links (design
+      -- 2026-06-04-individual-users-and-vault-operations.md §7). An admin
+      -- generates a link; the recipient opens it, picks a username +
+      -- password, and gets their OWN freshly-provisioned vault as owner.
+      --
+      -- The row stores sha256(token), NOT the raw token. Invites are
+      -- longer-lived than the 60s OAuth auth-codes (default 7-day expiry),
+      -- so a DB read must not be enough to replay the link — the raw token
+      -- is emitted exactly once at creation and never persisted, exactly
+      -- like the bootstrap token. Lookup hashes the URL token and selects
+      -- by the hash; the hash is the primary key.
+      --
+      -- Columns:
+      --   * token (TEXT PK)        — sha256(raw token), hex. Never the raw value.
+      --   * created_by (TEXT)      — admin user id that issued the invite
+      --                              (FK users.id; ON DELETE SET NULL so
+      --                              deleting the issuer doesn't orphan-block
+      --                              the audit row).
+      --   * vault_name (TEXT)      — nullable. When set, the invite pins the
+      --                              vault name (redeemer can't squat names).
+      --                              When NULL + provision_vault=1 the redeemer
+      --                              names their own vault at redeem time.
+      --   * role (TEXT DEFAULT 'write') — the user_vaults role the redeemed
+      --                              user gets on their vault. 'write' = owner
+      --                              (full vault admin per vaultVerbsForRole).
+      --                              Carried so the shared-into-existing-vault
+      --                              case is a later policy change, not a
+      --                              migration.
+      --   * provision_vault (INTEGER) — 1 = provision a NEW vault for the
+      --                              redeemer (the primary flow); 0 = account
+      --                              only / assign an existing vault.
+      --   * default_mirror (TEXT)  — nullable; wires the §3 default-mirror knob
+      --                              ('internal' | 'off') through to the
+      --                              provisioned vault. NULL = vault's own
+      --                              default.
+      --   * expires_at (TEXT)      — ISO-8601; redeem rejects past this.
+      --   * used_at (TEXT)         — ISO-8601 stamp set at redeem. Single-use:
+      --                              a second redeem sees this set and is
+      --                              rejected. Stamped only AFTER the user row
+      --                              commits, so a createUser failure leaves
+      --                              the invite re-usable.
+      --   * redeemed_user_id (TEXT) — the user id the invite created (FK
+      --                              users.id; ON DELETE SET NULL).
+      --   * revoked_at (TEXT)      — ISO-8601 stamp when the admin revokes the
+      --                              invite before redemption.
+      --   * created_at (TEXT)      — ISO-8601.
+      --
+      -- No backfill — no invites pre-date this migration.
+      CREATE TABLE invites (
+        token TEXT PRIMARY KEY,
+        created_by TEXT REFERENCES users(id) ON DELETE SET NULL,
+        vault_name TEXT,
+        role TEXT NOT NULL DEFAULT 'write',
+        provision_vault INTEGER NOT NULL DEFAULT 1,
+        default_mirror TEXT,
+        expires_at TEXT NOT NULL,
+        used_at TEXT,
+        redeemed_user_id TEXT REFERENCES users(id) ON DELETE SET NULL,
+        revoked_at TEXT,
+        created_at TEXT NOT NULL
+      );
+      CREATE INDEX invites_created_at ON invites (created_at);
+    `,
+  },
 ];
 
 export function openHubDb(path: string = hubDbPath()): Database {