@openparachute/hub 0.7.4-rc.8 → 0.7.4

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/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)
@@ -367,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 {