@openparachute/hub 0.7.4-rc.2 → 0.7.4-rc.20

package/src/commands/hub.ts

@@ -32,7 +32,12 @@ import { validateHubOrigin } from "../api-settings-hub-origin.ts";
 import { restart } from "../commands/lifecycle.ts";
 import { CONFIG_DIR } from "../config.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
-import { setHubOrigin } from "../hub-settings.ts";
+import {
+  DEFAULT_ROOT_REDIRECT,
+  isSafeRedirectPath,
+  setHubOrigin,
+  setRootRedirect,
+} from "../hub-settings.ts";
 import { type CommandResult, type Runner, defaultRunner } from "../tailscale/run.ts";
 import { isLoopbackOrigin } from "../vault-hub-origin-env.ts";
 
@@ -347,6 +352,81 @@ async function runCaddyReload(run: Runner): Promise<CommandResult> {
   return run(["systemctl", "reload", "caddy"]);
 }
 
+/**
+ * `parachute hub set-root-redirect <path>` — persist the operator's bare-`/`
+ * redirect target into `hub_settings.root_redirect` (tier-1 in
+ * `resolveRootRedirect`). Lets a headless box (the canonical use case is a
+ * custom-domain hub fronting a team surface) flip its landing page from `/admin`
+ * to a surface without a browser session OR a redeploy.
+ *
+ * `--clear` deletes the row, reverting to the env / `/admin` default.
+ *
+ * The path is validated through `isSafeRedirectPath` — the SAME open-redirect
+ * guard the admin PUT enforces — so the CLI can never plant an off-origin
+ * `Location` target either. Returns 0 on success, 1 on a usage / validation /
+ * DB-write failure.
+ */
+export async function hubSetRootRedirect(
+  args: readonly string[],
+  deps: HubCommandDeps = {},
+): Promise<number> {
+  const configDir = deps.configDir ?? CONFIG_DIR;
+  const log = deps.log ?? ((line) => console.log(line));
+  const err = (line: string) => console.error(line);
+  const openDb = deps.openDb ?? ((dir: string) => openHubDb(hubDbPath(dir)));
+
+  const clear = args.includes("--clear");
+  const positional = args.filter((a) => !a.startsWith("-"));
+
+  if (clear) {
+    if (positional.length > 0) {
+      err("parachute hub set-root-redirect: --clear takes no path argument");
+      return 1;
+    }
+    const db = openDb(configDir);
+    try {
+      setRootRedirect(db, null);
+    } finally {
+      db.close();
+    }
+    log(
+      `✓ Cleared the root redirect — \`/\` reverts to env / the ${DEFAULT_ROOT_REDIRECT} default.`,
+    );
+    return 0;
+  }
+
+  const raw = positional[0];
+  if (raw === undefined) {
+    err("usage: parachute hub set-root-redirect <path>   (or --clear)");
+    err("example: parachute hub set-root-redirect /surface/reading-room");
+    return 1;
+  }
+  if (positional.length > 1) {
+    err(`parachute hub set-root-redirect: unexpected argument "${positional[1]}"`);
+    err("usage: parachute hub set-root-redirect <path>   (or --clear)");
+    return 1;
+  }
+
+  if (!isSafeRedirectPath(raw)) {
+    err(`parachute hub set-root-redirect: "${raw}" is not a safe same-origin path`);
+    err("  It must start with a single `/` (no `//`, `/\\`, scheme, or whitespace) and");
+    err("  not be `/` itself. Example: /surface/reading-room");
+    return 1;
+  }
+
+  const db = openDb(configDir);
+  try {
+    setRootRedirect(db, raw);
+  } finally {
+    db.close();
+  }
+
+  log(`✓ Bare \`/\` now redirects to ${raw}.`);
+  log("  Stored in hub_settings.root_redirect — takes effect on the next request,");
+  log("  no restart needed. Clear it with: parachute hub set-root-redirect --clear");
+  return 0;
+}
+
 /**
  * `parachute hub <subcommand>` dispatcher. Mirrors `auth`'s shape (a thin
  * router over subcommand handlers, each catching its own errors).
@@ -367,6 +447,16 @@ export async function hub(args: readonly string[], deps: HubCommandDeps = {}): P
       return 1;
     }
   }
+  if (sub === "set-root-redirect") {
+    try {
+      return await hubSetRootRedirect(args.slice(1), deps);
+    } catch (err) {
+      console.error(
+        `parachute hub set-root-redirect: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return 1;
+    }
+  }
   console.error(`parachute hub: unknown subcommand "${sub}"`);
   console.error("");
   console.error(hubHelp());
@@ -378,6 +468,7 @@ export function hubHelp(): string {
 
 Usage:
   parachute hub set-origin <url> [--no-caddy] [--no-restart]
+  parachute hub set-root-redirect <path> | --clear
 
 Subcommands:
   set-origin <url>    Persist the canonical public origin (OAuth issuer) to the
@@ -401,9 +492,19 @@ Subcommands:
                       Caddyfile rewrite + reload, or --no-restart to skip the
                       module restart.
 
+  set-root-redirect <path>
+                      Point the bare \`/\` 302 at a same-origin path instead of the
+                      default /admin (e.g. a team surface). Stored in
+                      hub_settings.root_redirect; takes effect on the next request,
+                      no restart. The path must start with a single \`/\` (no \`//\`,
+                      \`/\\\`, scheme, or whitespace). Pass --clear to revert to the
+                      env / /admin default. (Env equivalent: PARACHUTE_HUB_ROOT_REDIRECT.)
+
 Examples:
   parachute hub set-origin https://box.sslip.io
   parachute hub set-origin https://parachute.example.com
   parachute hub set-origin https://parachute.example.com --no-caddy
+  parachute hub set-root-redirect /surface/reading-room
+  parachute hub set-root-redirect --clear
 `;
 }

package/src/commands/init.ts

@@ -52,6 +52,7 @@ import { issueOperatorToken, readOperatorTokenFile } from "../operator-token.ts"
 import { type AliveFn, defaultAlive, processState } from "../process-state.ts";
 import { findService, readManifestLenient } from "../services-manifest.ts";
 import { listUsers } from "../users.ts";
+import { validateVaultName } from "../vault-name.ts";
 import { type InstallOpts, install as defaultInstall } from "./install.ts";
 
 /** The three options the exposure prompt offers — also the `--expose` flag's domain. */
@@ -202,6 +203,44 @@ export interface InitOpts {
    * already known so there's no question to ask).
    */
   noWizardPrompt?: boolean;
+  /**
+   * Vault name to create as part of `parachute init --vault-name <name>`
+   * (#478 Part 2). When set, init creates the first vault via
+   * `createFirstVaultImpl` immediately after Step 1.5 (operator-token
+   * guarantee), before the admin-URL resolution. Validated with
+   * `validateVaultName` in the CLI before reaching here.
+   *
+   * Idempotency lives in `parachute-vault create`, NOT in a services.json
+   * precheck: `create <name>` exits 0 + creates when `<name>` is new, and
+   * exits non-zero ("Vault \"<name>\" already exists.") on a re-run. We
+   * therefore ALWAYS attempt the create when this field is set and treat a
+   * non-zero exit as non-fatal (warn + continue). A services.json
+   * `parachute-vault` row is the MODULE-installed marker (Step 0.5 seeds it
+   * via `spec.seedEntry` on EVERY fresh install), not an instance marker —
+   * keying idempotency off it would silently no-op the create on the exact
+   * fresh-box path this feature targets.
+   *
+   * Without this field (the default), init makes NO vault — the wizard
+   * owns Create/Import/Skip as before. The --no-browser / scripted path
+   * remains vault-free unless --vault-name is explicitly passed.
+   */
+  vaultName?: string;
+  /**
+   * Test seam: injectable impl for the `--vault-name` create step (#478
+   * Part 2). This IS the whole create implementation — tests swap the
+   * entire function for a stub that records the call without touching a
+   * live vault binary. It takes the vault name plus a ctx carrying a
+   * runner shim, and returns an exit code (0 = success).
+   *
+   * The production default (`defaultCreateFirstVault`) uses that runner to
+   * shell out `["parachute-vault", "create", name]`, following the `Runner`
+   * type pattern established across every command that shells out:
+   * `readonly string[] => Promise<number>`.
+   */
+  createFirstVaultImpl?: (
+    name: string,
+    ctx: { runner: (cmd: readonly string[]) => Promise<number> },
+  ) => Promise<number>;
   /**
    * Canonical public hub origin (the OAuth issuer / `iss` claim). Persisted to
    * `hub_settings.hub_origin` BEFORE the hub unit starts + modules spawn, so
@@ -599,6 +638,38 @@ async function defaultFetchBootstrapToken(loopbackUrl: string): Promise<string |
   }
 }
 
+/**
+ * Default runner shim for the `--vault-name` create step (#478 Part 2).
+ * Shells out `parachute-vault create <name>` via Bun.spawn, inheriting
+ * the operator's full env (so PARACHUTE_HOME, PATH, etc. pass through).
+ *
+ * This is the same pattern every other command that shells out uses — a
+ * `Runner` (`readonly string[] => Promise<number>`) so tests can inject a
+ * stub without touching the real vault binary.
+ */
+async function defaultRunner(cmd: readonly string[]): Promise<number> {
+  const proc = Bun.spawn([...cmd], {
+    stdio: ["inherit", "inherit", "inherit"],
+    env: process.env,
+  });
+  return await proc.exited;
+}
+
+/**
+ * Default impl for the `--vault-name` first-vault create step (#478 Part 2).
+ * Invokes `parachute-vault create <name>` via the injectable runner. The
+ * `parachute-vault` binary must already be on PATH (guaranteed by Step 0.5's
+ * vault-module install). Exit code is forwarded directly — callers log the
+ * outcome and continue (a non-zero create doesn't abort init; the operator
+ * can re-run `parachute vault create <name>` or use the wizard to retry).
+ */
+async function defaultCreateFirstVault(
+  name: string,
+  ctx: { runner: (cmd: readonly string[]) => Promise<number> },
+): Promise<number> {
+  return await ctx.runner(["parachute-vault", "create", name]);
+}
+
 /**
  * Prompt for the wizard-choice question (hub#168 Cut 4). Returns the
  * picked option, or `undefined` if the operator quit. Default is
@@ -735,6 +806,7 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   const runCliWizardImpl = opts.runCliWizardImpl ?? defaultRunCliWizard;
   const fetchBootstrapTokenImpl = opts.fetchBootstrapTokenImpl ?? defaultFetchBootstrapToken;
   const setHubOriginImpl = opts.setHubOriginImpl ?? defaultSetHubOrigin;
+  const createFirstVaultImpl = opts.createFirstVaultImpl ?? defaultCreateFirstVault;
 
   log("Parachute init — getting your hub set up.");
   log("");
@@ -885,6 +957,42 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   // to the wizard regardless.
   await guaranteeOperatorToken({ configDir, hubPort, log });
 
+  // Step 1.6 (#478 Part 2): if `--vault-name <name>` was given, create the
+  // first vault now — after the hub is up (Step 1) and the operator token is
+  // guaranteed (Step 1.5). The vault module was installed at Step 0.5, so
+  // `parachute-vault` is on PATH.
+  //
+  // We ALWAYS attempt the create when `--vault-name` is set. Idempotency lives
+  // in `parachute-vault create` itself, NOT in a services.json precheck:
+  //   - `create <name>` exits 0 + creates the vault when `<name>` is new.
+  //   - `create <name>` exits non-zero ("Vault \"<name>\" already exists.") when
+  //     that exact name already exists (a benign re-run).
+  //
+  // We DON'T precheck the services.json `parachute-vault` row: Step 0.5's
+  // `install("vault", { noCreate: true })` seeds that row via `spec.seedEntry`
+  // on EVERY fresh install (the module-installed marker — see install.ts's
+  // InstallOpts doc), so on the exact fresh-box path this feature targets the
+  // row is ALWAYS present and a row-keyed precheck would silently no-op the
+  // create. The row marks "module installed", not "instance exists" — only the
+  // create command's own exit reliably distinguishes the two.
+  //
+  // A non-zero exit is non-fatal: warn + continue. It could mean the vault
+  // already exists (a fine re-run) OR a genuine creation failure — init's
+  // contract is hub up → wizard regardless, so we never abort here. The
+  // operator can check `parachute status` / re-run `parachute vault create`.
+  if (opts.vaultName !== undefined) {
+    log(`Creating vault "${opts.vaultName}"…`);
+    const createCode = await createFirstVaultImpl(opts.vaultName, { runner: defaultRunner });
+    if (createCode === 0) {
+      log(`✓ Vault "${opts.vaultName}" created.`);
+    } else {
+      log(
+        `⚠ \`parachute-vault create ${opts.vaultName}\` exited ${createCode} — the vault may already exist, or creation failed. Check \`parachute status\` / re-run \`parachute vault create ${opts.vaultName}\`.`,
+      );
+    }
+    log("");
+  }
+
   // Step 2: exposure chain. Skipped when already exposed, in non-TTY,
   // or when --no-expose-prompt was passed. `--expose <choice>` jumps
   // straight to the corresponding chain without asking.

package/src/commands/vault-remove.ts

@@ -31,14 +31,18 @@
  * `parachute:host:admin` — exactly the scope the endpoint gates on. This is the
  * same read-never-mint credential path `parachute start/stop/restart <svc>` use.
  *
- * ## The 409 guardrail (load-bearing)
+ * ## Last-vault handling (#678)
  *
- * On a `409 last_vault` the endpoint refuses (deleting the last vault would let
- * vault's boot silently resurrect a fresh `default`). We print the endpoint's
- * message + note the raw escape hatch (`parachute-vault remove <name> --yes`)
- * which SKIPS the cascade, then return NON-ZERO. We MUST NOT fall through to
- * spawning `parachute-vault` ourselves: a "helpful" fall-through would re-open
- * the exact orphaning bug B3 closes. The test locks this invariant.
+ * The last/only vault is deleted IDENTICALLY to any other vault: the endpoint
+ * runs the full cascade-then-delete and returns 200. There is no special-case
+ * here. (Older builds refused the last vault with a `409 last_vault` and steered
+ * the operator to the raw `parachute-vault remove --yes` — but that escape hatch
+ * SKIPS the cascade, orphaning the very identity artifacts B3 set out to clean
+ * up. hub#678 removed that refusal: vault's boot can no longer silently
+ * resurrect a fresh first vault because vault's CLI writes an
+ * `auto_create: false` marker on last-vault removal and the boot gate honors
+ * it.) This command therefore needs no 409 branch — the 200 path renders the
+ * cascade summary for the last vault just like every other delete.
  */
 
 import { CONFIG_DIR } from "../config.ts";
@@ -56,8 +60,9 @@ import {
 
 /**
  * Injectable seams. Production wires the real operator-token bearer resolver +
- * the global `fetch`; tests inject fakes to assert the request shape + lock the
- * 409 guardrail without a live hub or a real socket.
+ * the global `fetch`; tests inject fakes to assert the request shape + that
+ * destruction always goes through the hub endpoint (never a direct
+ * `parachute-vault` spawn) without a live hub or a real socket.
  */
 export interface VaultRemoveDeps {
   /**
@@ -84,6 +89,7 @@ interface CascadeSummaryWire {
   grants_dropped?: number;
   user_vaults_removed?: number;
   invites_invalidated?: number;
+  vault_cap_removed?: boolean;
   connections_torn_down?: number;
   orphaned_channels?: unknown;
   vault_removed?: boolean;
@@ -151,6 +157,7 @@ function renderCascadeSummary(
   log(`  grants dropped:        ${n(c.grants_dropped)}`);
   log(`  user_vaults removed:   ${n(c.user_vaults_removed)}`);
   log(`  invites invalidated:   ${n(c.invites_invalidated)}`);
+  log(`  storage cap removed:   ${c.vault_cap_removed === true ? "yes" : "no"}`);
   log(`  connections torn down: ${n(c.connections_torn_down)}`);
   log(`  vault removed:         ${c.vault_removed === true ? "yes" : "no"}`);
   log(`  vault module restarted:${c.module_restarted === true ? " yes" : " no"}`);
@@ -302,21 +309,6 @@ export async function vaultRemove(args: string[], deps: VaultRemoveDeps = {}): P
     return 0;
   }
 
-  if (res.status === 409 && error === "last_vault") {
-    // CRITICAL GUARDRAIL: print + exit non-zero. Do NOT fall through to spawning
-    // `parachute-vault` — that would re-open the orphaned-identity bug B3 closes.
-    logError(`parachute vault remove: ${error_description}`);
-    logError("");
-    logError(
-      `The raw mechanics-only path \`parachute-vault remove ${name} --yes\` can delete the last vault,`,
-    );
-    logError(
-      "but it SKIPS the identity cascade — live tokens, grants, and user_vaults rows for that",
-    );
-    logError("vault would be left orphaned. Create another vault first if you can.");
-    return 1;
-  }
-
   if (res.status === 400 && error === "confirm_mismatch") {
     // Pass the hub's confirm message through.
     logError(`parachute vault remove: ${error_description}`);

package/src/cors.ts

@@ -89,8 +89,9 @@
  *     leaking the wrong ACAO and breaking CORS in unpredictable ways.
  *     Critical for cache correctness.
  *
- *   Access-Control-Allow-Methods: GET, POST, OPTIONS
- *     The union of methods the in-scope route family supports. Per-route
+ *   Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
+ *     The union of methods the in-scope route family supports (DELETE for the
+ *     RFC 7592 `DELETE /oauth/clients/<id>` deregistration, hub#640). Per-route
  *     could be narrower (e.g. /oauth/token is POST-only), but advertising
  *     the union is the simpler shape and browsers don't enforce a per-route
  *     check anyway — the *actual* request method gates execution at the
@@ -137,7 +138,10 @@ const CORS_STATIC_RESPONSE_HEADERS: Readonly<Record<string, string>> = {
  * `corsPreflightResponse`.
  */
 const CORS_STATIC_PREFLIGHT_HEADERS: Readonly<Record<string, string>> = {
-  "access-control-allow-methods": "GET, POST, OPTIONS",
+  // DELETE is in the union for RFC 7592 client deregistration
+  // (`DELETE /oauth/clients/<id>`, hub#640). A cross-origin browser caller
+  // (vs the server-side surface daemon) would otherwise fail the preflight.
+  "access-control-allow-methods": "GET, POST, DELETE, OPTIONS",
   "access-control-allow-headers": "Authorization, Content-Type, X-Requested-With",
   "access-control-max-age": "86400",
 };

package/src/help.ts

@@ -17,6 +17,7 @@ Usage:
   parachute install <service>       install and register a service
                                     services: ${services}
   parachute status                  show installed services, run state, health
+  parachute doctor                  run health checks + tell you the one thing to fix
   parachute start   [service]       start a module via the supervisor (or ensure the hub is up)
   parachute stop    [service]       stop a module via the supervisor (or stop the hub unit)
   parachute restart [service]       restart a module via the supervisor (or restart the hub unit)
@@ -134,6 +135,7 @@ Usage:
                  [--expose none|tailnet|cloudflare]
                  [--channel rc|latest]
                  [--hub-origin <url>]
+                 [--vault-name <name>]
                  [--cli-wizard | --browser-wizard]
 
 What it does:
@@ -178,6 +180,14 @@ Flags:
                             accepting it in one pass. For reverse-proxy /
                             Caddy-direct boxes that bind loopback but are reached
                             over a public HTTPS URL (e.g. https://<ip>.sslip.io).
+  --vault-name <name>       create the first vault in one shot (#478 Part 2).
+                            Runs \`parachute-vault create <name>\` after the hub
+                            is up. Non-fatal on re-run — \`create\` exits
+                            non-zero if the vault already exists, and that's
+                            tolerated. Must be a valid vault name: lowercase
+                            alphanumeric + hyphens/underscores, 2–32 chars.
+                            Without this flag, the wizard owns vault creation
+                            (the default experience is unchanged).
   --cli-wizard              skip the "browser or CLI?" prompt and walk the wizard
                             in this terminal (hub#168 Cut 4)
   --browser-wizard          skip the prompt and open the browser wizard directly
@@ -190,7 +200,9 @@ Examples:
   parachute init --expose tailnet             # CI/scripted: chain straight into Tailscale
   parachute init --no-browser                 # don't shell out to open / xdg-open
   parachute init --cli-wizard                 # walk the wizard in this terminal (hub#168)
-  parachute init --channel rc                  # rc box: install the vault module from @rc
+  parachute init --channel rc                 # rc box: install the vault module from @rc
+  parachute init --vault-name default --no-browser
+                                              # CI/scripted: hub + first vault in one pass
 `;
 }
 
@@ -356,6 +368,58 @@ Example:
 `;
 }
 
+export function doctorHelp(): string {
+  return `parachute doctor — health / diagnostics for your Parachute install
+
+Usage:
+  parachute doctor [--json]
+  parachute doctor --fix [--yes]
+
+What it does:
+  Runs a set of independent health checks and prints a grouped report
+  (✓ pass / ⚠ warn / ✗ fail), each with a one-line detail and — where there
+  is one — a copy-pasteable fix-it command. The single command that answers
+  "is my Parachute healthy, and if not, what's the one thing to fix?"
+
+  Checks (each PASSES on a fresh / fully-current install — doctor positively
+  detects a known-bad condition and never treats "not configured" as broken):
+    - Hub supervisor reachable on :1939 (/health).
+    - Each CONFIGURED module alive via its loopback /health (2xx or 401 = live).
+    - services.json parses + required fields valid (a missing file is the
+      fresh pre-install state, not a failure).
+    - Services on canonical ports — flags any KNOWN module whose port has
+      drifted off its canonical slot, or two services sharing one port
+      (legacy services.json written before the validation gate). A
+      third-party service with no canonical port is never flagged.
+    - operator.token exists, parses, and its issuer matches the hub (the
+      recurring "not signed in to the hub" / issuer-mismatch class).
+    - Each first-party module bin is executable (catches the lost-+x-bit
+      start-failure class).
+    - Migration: legacy detached install? known cruft at the ecosystem root?
+      (allowlist detectors only — a fresh root flags nothing).
+    - Exposure: if exposed, is the public origin reachable? If not exposed,
+      "loopback only" is reported as benign info, never a warning.
+    - Version freshness (cosmetic) — drift is WARN at most, never a failure.
+
+Flags:
+  --json     emit a single JSON object instead of the human report
+  --fix      repair canonical-port drift in services.json — and ONLY that.
+             It is NOT a "fix everything" flag; every other check stays
+             report-only. Shows the old→new diff first, then confirms before
+             writing (a TTY prompts; --yes skips the prompt; a non-TTY without
+             --yes bails without writing). Idempotent: a clean file is a no-op.
+             Duplicate-port collisions are reported, not auto-resolved.
+  --yes      skip the --fix confirmation prompt (required to apply in a
+             non-interactive shell)
+
+Exit codes:
+  0   no failures (warnings are advisory and still exit 0); --fix: applied or
+      nothing-to-fix
+  1   one or more checks failed; or --fix bailed (non-TTY without --yes /
+      aborted at the prompt / unreadable services.json)
+`;
+}
+
 export function exposeHelp(): string {
   return `parachute expose — route your services behind HTTPS on a network layer
 

package/src/hub-db.ts

@@ -558,6 +558,20 @@ const MIGRATIONS: readonly Migration[] = [
       );
     `,
   },
+  {
+    version: 16,
+    sql: `
+      -- Index tokens by client_id for the OAuth client GC reaper (#640). The
+      -- reaper's gate runs a correlated NOT EXISTS (SELECT 1 FROM tokens WHERE
+      -- client_id = ? AND ...) per candidate client; tokens previously had no
+      -- client_id index (only user_id / refresh_token_hash / family_id /
+      -- revoked_at / subject), so each check was a full tokens-table walk. Under
+      -- the DCR reconnect churn this GC targets — thousands of dead token rows
+      -- accumulating before a sweep — that is O(total tokens) per client. This
+      -- makes it O(tokens for that client). IF NOT EXISTS so re-opens are inert.
+      CREATE INDEX IF NOT EXISTS tokens_client ON tokens (client_id);
+    `,
+  },
 ];
 
 export function openHubDb(path: string = hubDbPath()): Database {