@openparachute/hub 0.6.3 → 0.6.4-rc.10

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/commands/wizard.ts

@@ -255,6 +255,14 @@ interface WizardStateSnapshot {
   hasVault: boolean;
   hasExposeMode: boolean;
   requireBootstrapToken: boolean;
+  /**
+   * The actual bootstrap token, present ONLY when the wizard-state probe ran
+   * over loopback (the on-box operator's own shell — hub#576). The hub returns
+   * it so the CLI wizard can satisfy the first-claim gate transparently without
+   * the operator copy-pasting it from the startup logs. Absent on any
+   * public/tailnet probe.
+   */
+  bootstrapToken?: string;
   csrfToken: string;
   /** Optional URL to redirect to (when state is fully done — 301 to /login). */
   redirectTo?: string;
@@ -294,7 +302,7 @@ async function fetchWizardState(
     );
   }
   const body = res.json as Partial<WizardStateSnapshot> & { csrfToken?: string };
-  return {
+  const snapshot: WizardStateSnapshot = {
     step: body.step ?? "welcome",
     hasAdmin: Boolean(body.hasAdmin),
     hasVault: Boolean(body.hasVault),
@@ -302,6 +310,12 @@ async function fetchWizardState(
     requireBootstrapToken: Boolean(body.requireBootstrapToken),
     csrfToken: typeof body.csrfToken === "string" ? body.csrfToken : (jar.csrf ?? ""),
   };
+  // hub#576: the loopback probe carries the actual token. Thread it through so
+  // the account step can submit it without prompting the operator.
+  if (typeof body.bootstrapToken === "string" && body.bootstrapToken.length > 0) {
+    snapshot.bootstrapToken = body.bootstrapToken;
+  }
+  return snapshot;
 }
 
 /**
@@ -422,7 +436,27 @@ async function walkAccountStep(
     log(`  ✗ ${pwErr}`);
     return 1;
   }
-  let bootstrap = opts.bootstrapToken ?? process.env.PARACHUTE_BOOTSTRAP_TOKEN;
+  // Token resolution order (hub#576):
+  //   1. Explicit `--bootstrap-token` flag / `opts.bootstrapToken` (init passes
+  //      this when it fetched the token from the loopback probe).
+  //   2. `PARACHUTE_BOOTSTRAP_TOKEN` env.
+  //   3. The token carried on the loopback wizard-state probe itself — the
+  //      common on-box `parachute init` path: the hub handed us the value
+  //      because we reached it over loopback, so we satisfy the gate
+  //      transparently with no operator action.
+  //   4. Prompt — the fallback when none of the above apply (e.g. a remote
+  //      `parachute init --cli-wizard` against a public hub, where the probe
+  //      didn't carry the token). The operator reads it from the startup logs.
+  // Treat an empty / whitespace value at any level as "absent" so a falsy
+  // `PARACHUTE_BOOTSTRAP_TOKEN=` (exported-but-empty) doesn't suppress the
+  // loopback-probe token and silently submit a blank token.
+  const firstNonEmpty = (...vals: Array<string | undefined>): string | undefined =>
+    vals.find((v) => typeof v === "string" && v.trim().length > 0);
+  let bootstrap = firstNonEmpty(
+    opts.bootstrapToken,
+    process.env.PARACHUTE_BOOTSTRAP_TOKEN,
+    state.bootstrapToken,
+  );
   if (state.requireBootstrapToken && !bootstrap) {
     log("");
     log("  This hub is in container/serve mode and minted a one-time");

package/src/grants.ts

@@ -188,6 +188,119 @@ export function isCoveredByGrantForClientName(
   return true;
 }
 
+const VAULT_SCOPE_PREFIX_RE = /^vault:([^:]+):/;
+
+/**
+ * Fixed `client_id`s the hub mints for its OWN first-party browser surfaces.
+ * A grant carrying one of these is a browser sign-in (the operator opened the
+ * admin SPA, the account-home friend surface, etc.) — NOT "the operator
+ * connected an AI to their vault." See `userHasExternalAiGrant` (hub#583).
+ *
+ *   - `parachute-hub-spa`   — hub admin SPA + vault admin SPA mints
+ *     (`admin-host-admin-token.ts`, `admin-vault-admin-token.ts`,
+ *     `account-vault-admin-token.ts`).
+ *   - `parachute-account`   — account-home friend-vault token mints
+ *     (`account-vault-token.ts`).
+ */
+const FIRST_PARTY_BROWSER_CLIENT_IDS = new Set(["parachute-hub-spa", "parachute-account"]);
+
+/**
+ * `client_name`s of first-party browser SPAs that register dynamically via DCR
+ * (so their `client_id` is generated per-registration and can't be enumerated).
+ * Notes registers with `client_name: "Notes"` (the @openparachute/notes-ui PWA
+ * signing into a vault). Matched case-insensitively. See hub#583.
+ */
+const FIRST_PARTY_BROWSER_CLIENT_NAMES = new Set(["notes"]);
+
+/**
+ * True when a grant belongs to one of the hub's own first-party browser
+ * surfaces (admin SPA, account home, Notes PWA) rather than an external AI/MCP
+ * client (Claude, Cursor, …). Used to keep a browser sign-in from
+ * false-positiving the "you've connected your AI" onboarding signal (hub#583).
+ *
+ * Discriminates two ways because first-party surfaces register two ways: the
+ * hub-minted SPAs use fixed `client_id`s; DCR-registered SPAs (Notes) get a
+ * generated id but a stable `client_name`.
+ */
+export function isFirstPartyBrowserClient(
+  clientId: string,
+  clientName: string | null | undefined,
+): boolean {
+  if (FIRST_PARTY_BROWSER_CLIENT_IDS.has(clientId)) return true;
+  if (clientName && FIRST_PARTY_BROWSER_CLIENT_NAMES.has(clientName.trim().toLowerCase())) {
+    return true;
+  }
+  return false;
+}
+
+interface GrantWithClientNameRow extends GrantRow {
+  client_name: string | null;
+}
+
+/**
+ * True when the user has approved at least one EXTERNAL AI/MCP client (Claude,
+ * Cursor, etc.) whose granted scopes touch `vaultName` — i.e. "has this person
+ * actually wired up an AI to this vault yet?" (hub#583).
+ *
+ * Stricter than {@link userHasVaultGrant}: it excludes grants from the hub's
+ * own first-party browser surfaces (admin SPA, account home, Notes PWA). Those
+ * are OAuth clients too — signing into Notes writes a vault-scoped grant — so
+ * the coarse "any vault grant" signal lit up the `/account/` onboarding
+ * checklist's "✓ You're connected" line even when no AI was ever connected.
+ * This is the detection the checklist should use.
+ *
+ * Trade-off: this fetches ALL of the user's grants (joined to `clients` for
+ * `client_name`) and filters in JS, rather than pushing the first-party
+ * exclusion into a WHERE clause. Fine at current scale — a user has a handful
+ * of grants, and the scope/client-name discrimination is awkward to express in
+ * SQL (scopes are a space-joined column, first-party names are an in-process
+ * set). If the grants table grows large per-user, add an index on
+ * `grants(user_id)` (already the PK prefix) and consider a `client_name`-aware
+ * WHERE filter.
+ */
+export function userHasExternalAiGrant(db: Database, userId: string, vaultName: string): boolean {
+  const rows = db
+    .prepare(
+      `SELECT g.user_id, g.client_id, g.scopes, g.granted_at, c.client_name
+         FROM grants g
+         LEFT JOIN clients c ON g.client_id = c.client_id
+        WHERE g.user_id = ?`,
+    )
+    .all(userId) as GrantWithClientNameRow[];
+  for (const row of rows) {
+    if (isFirstPartyBrowserClient(row.client_id, row.client_name)) continue;
+    const scopes = row.scopes.split(" ").filter((s) => s.length > 0);
+    for (const s of scopes) {
+      const m = s.match(VAULT_SCOPE_PREFIX_RE);
+      if (m && m[1] === vaultName) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * True when the user has approved at least one OAuth client whose granted
+ * scopes touch `vaultName` (any `vault:<name>:<verb>` scope). This is the
+ * "has this person actually connected an AI to this vault yet?" signal — the
+ * `/account/` onboarding checklist uses it to mark the "Connect your AI" step
+ * done (a grant row only lands once the user has clicked through the consent
+ * screen for a client wired to this vault).
+ *
+ * Mirrors the per-grant vault filter in `admin-grants.ts`; kept here so the
+ * detection lives next to the rest of the grants helpers and can be unit-tested
+ * without the admin route harness.
+ */
+export function userHasVaultGrant(db: Database, userId: string, vaultName: string): boolean {
+  const grants = listGrantsForUser(db, userId);
+  for (const g of grants) {
+    for (const s of g.scopes) {
+      const m = s.match(VAULT_SCOPE_PREFIX_RE);
+      if (m && m[1] === vaultName) return true;
+    }
+  }
+  return false;
+}
+
 /** All grants for a user, ordered most-recent first. Used by `parachute auth list-grants`. */
 export function listGrantsForUser(db: Database, userId: string): Grant[] {
   const rows = db

package/src/help.ts

@@ -42,7 +42,7 @@ export function installHelp(): string {
   return `parachute install — install and register a Parachute service
 
 Usage:
-  parachute install <service> [--channel rc|latest] [--tag <name>] [--no-start]
+  parachute install <service> [--channel rc|latest] [--tag <name>] [--no-start] [--interactive]
   parachute install all       [--channel rc|latest] [--tag <name>] [--no-start]
   parachute install scribe    [--scribe-provider <name>] [--scribe-key <key>]
 
@@ -52,7 +52,10 @@ Services:
 
 What it does:
   1. bun add -g @openparachute/<service>[@<tag>]
-  2. run any service-specific init (e.g. \`parachute-vault init\`)
+  2. register + start the module under the hub supervisor (LIGHT by default —
+     no interactive interview; for vault: no vault-name / MCP / token prompts
+     and no competing standalone daemon). Pass \`--interactive\` to run the
+     service's own full setup (e.g. \`parachute-vault init\`) instead.
   3. assign a canonical port (1939–1949) and reflect it in
      \`~/.parachute/services.json\` — the single source of truth at boot
      (services follow a 4-tier resolvePort ladder; services.json wins).
@@ -73,6 +76,15 @@ Flags:
                             Skipped if the package is already \`bun link\`-ed locally.
   --no-start                skip the post-install daemon start. For piped / CI
                             installs that own their own process model.
+  --interactive             run the module's full interactive setup instead of
+                            the light default. For vault: the vault-name /
+                            "install MCP in Claude Code?" / "mint a token?"
+                            interview + its own standalone daemon registration.
+                            On a supervised hub that standalone daemon can RACE
+                            the supervisor for the module's port (EADDRINUSE
+                            crash-loop, #580) — prefer the light default + manage
+                            from the admin UI unless you specifically want the
+                            old interview.
   --scribe-provider <name>  set scribe's transcription provider non-interactively.
                             Known: parakeet-mlx (default), onnx-asr, whisper, groq, openai.
                             Skips the interactive picker.
@@ -89,9 +101,10 @@ Environment:
                             and \`--tag\`. Defaults to \`latest\` when unset.
 
 Examples:
-  parachute install vault                                   # installs, runs init, starts vault
+  parachute install vault                                   # light: installs + starts vault, points you at the admin UI
+  parachute install vault --interactive                     # full interactive vault init (name / MCP / token prompts)
   parachute install surface                                 # installs surface (auto-bootstraps Notes)
-  parachute install notes                                   # back-compat: legacy notes-daemon (Phase 2 deprecating)
+  parachute install notes                                   # legacy notes-daemon — deprecated; use \`parachute install surface\` instead
   parachute install scribe                                  # installs, prompts for provider, starts scribe
   parachute install scribe --scribe-provider groq --scribe-key gsk_…
                                                             # non-interactive scribe setup
@@ -147,7 +160,7 @@ Flags:
   --no-expose-prompt        skip the exposure question; fall through to localhost URL
   --expose <choice>         non-interactive exposure override:
                               none       — stay loopback-only
-                              tailnet    — set up Tailscale Funnel (private to your tailnet)
+                              tailnet    — set up Tailscale serve (private to your tailnet)
                               cloudflare — set up Cloudflare Tunnel (your own domain)
   --cli-wizard              skip the "browser or CLI?" prompt and walk the wizard
                             in this terminal (hub#168 Cut 4)

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 {