@openparachute/hub 0.3.0-rc.1 → 0.5.1

package/src/help.ts

@@ -6,15 +6,17 @@ export function topLevelHelp(): string {
   return `parachute ${pkg.version} — top-level CLI for the Parachute ecosystem
 
 Usage:
+  parachute setup                   interactive walk-through: install services + configure
   parachute install <service>       install and register a service
                                     services: ${services}
   parachute status                  show installed services, process state, health
   parachute start   [service]       start all services (or one) in the background
   parachute stop    [service]       stop all services (or one) — SIGTERM then SIGKILL
   parachute restart [service]       stop + start
+  parachute upgrade [service]       pull / re-install + restart (skips if no changes)
   parachute logs <service> [-f]     print service logs; -f to tail
-  parachute expose tailnet [off]    HTTPS across your tailnet
-  parachute expose public  [off]    HTTPS on the public internet (Funnel)
+  parachute expose tailnet [off]    HTTPS across your tailnet (supported)
+  parachute expose public  [off]    HTTPS on the public internet (exploratory)
   parachute migrate [--dry-run]     archive legacy files at ecosystem root
   parachute auth <cmd>              identity (set password, manage 2FA)
   parachute vault <args...>         vault-specific ops (tokens, 2fa, config, init,
@@ -80,6 +82,47 @@ Aliases:
 `;
 }
 
+export function setupHelp(): string {
+  return `parachute setup — interactive walk-through to install + configure services
+
+Usage:
+  parachute setup [--tag <name>] [--no-start]
+
+What it does:
+  1. surveys ~/.parachute/services.json — already-installed services are
+     reported, then skipped from the picker
+  2. shows a numbered multi-select for the remaining first-party services
+     (vault, notes, scribe; channel is exploratory and only offered by name)
+  3. pre-collects all interactive answers up front so the installs can run
+     without further prompting:
+       - vault: vault name (default \`default\`)
+       - scribe: transcription provider + API key for cloud providers
+  4. iterates \`parachute install <svc>\` per pick, threading the collected
+     answers and the shared --tag / --no-start flags
+  5. prints a summary banner with the running URLs (hub, vault, notes, scribe)
+     and a hint for connecting Claude Code
+
+Behavior:
+  - Partial success is preserved: if one install fails, prior successful
+    installs are NOT rolled back. The exit code reflects the FIRST failure
+    (root cause), so subsequent fallout doesn't mask the original problem.
+  - Non-TTY / piped invocations should use \`parachute install <svc>\` per
+    service instead — \`setup\` assumes a terminal for the prompts.
+  - Selection accepts numbers (\`1,3\`), names (\`vault, notes\`), or \`all\`.
+
+Flags:
+  --tag <name>     npm dist-tag or exact version, applied to every install
+                   in this walk-through (e.g. \`--tag rc\`)
+  --no-start       skip the post-install daemon start for every service.
+                   For CI / scripted bring-up.
+
+Examples:
+  parachute setup                   # interactive walk-through
+  parachute setup --tag rc          # bootstrap to the rc dist-tag
+  parachute setup --no-start        # install without auto-starting (CI)
+`;
+}
+
 export function statusHelp(): string {
   return `parachute status — show installed services, process state, and health
 
@@ -116,19 +159,34 @@ export function exposeHelp(): string {
 Usage:
   parachute expose tailnet [off]
   parachute expose public  [off]
+  parachute expose public  --tailnet
   parachute expose public  --cloudflare --domain <hostname>
   parachute expose public  off --cloudflare
 
-Interactive:
-  Run in a terminal with no flags, \`parachute expose public\` walks you
-  through provider selection (Tailscale Funnel vs. Cloudflare Tunnel),
-  offers to install missing dependencies on macOS, and prompts for the
-  Cloudflare hostname when needed. Piped / non-TTY invocations keep the
-  scripted behavior: default to Tailscale, flags override.
+Status:
+  tailnet is the supported exposure shape. The hub's OAuth + per-module
+  scope work is being designed against tailnet first (already auth'd at
+  the network layer, every user's tailnet is their own).
+  public is exploratory — the flag still works for early testers, but
+  the public-internet posture (DNS, cross-internet OAuth, Funnel quirks)
+  hasn't been hardened. Prefer tailnet until public re-enters the
+  documented narrative post-OAuth.
+
+Provider auto-detect (\`expose public\`):
+  - In a terminal with no provider flag, walks an interactive picker
+    (Tailscale Funnel vs. Cloudflare Tunnel), offers to install missing
+    dependencies on macOS, and prompts for the Cloudflare hostname when
+    needed.
+  - In a non-TTY (CI / piped), detects which provider is set up:
+      * exactly one configured → uses it.
+      * both configured        → fails with a hint at --tailnet/--cloudflare.
+      * neither configured     → fails with install pointers for both.
+    \`--skip-provider-check\` bypasses detection and falls through to
+    today's Tailscale-Funnel default (CI escape hatch).
 
 Layers:
-  tailnet    HTTPS across your tailnet (tailscale serve)
-  public     HTTPS on the public internet
+  tailnet    HTTPS across your tailnet (tailscale serve) — supported
+  public     HTTPS on the public internet — exploratory
              - default: Tailscale Funnel (no domain needed, *.ts.net URL)
              - --cloudflare + --domain: named Cloudflare tunnel on your own
                domain (stable URL, free, no bandwidth caps)
@@ -137,17 +195,25 @@ Tailscale and Cloudflare modes share no state. Either can be up without the
 other. Inside each mode, switching on/off is idempotent.
 
 Flags:
-  --hub-origin <url>    override the OAuth issuer URL advertised to clients
-                        (default: https://<fqdn> when exposed, else http://127.0.0.1:<hub-port>)
-  --cloudflare          use a named Cloudflare tunnel for the public layer
-                        (requires --domain)
-  --domain <hostname>   fully-qualified hostname to route through the tunnel
-                        (e.g. vault.example.com). The apex must be a zone on
-                        your Cloudflare account.
+  --hub-origin <url>      override the OAuth issuer URL advertised to clients
+                          (default: https://<fqdn> when exposed, else http://127.0.0.1:<hub-port>)
+  --tailnet               pin \`expose public\` to Tailscale Funnel,
+                          bypassing the picker / auto-detect
+  --cloudflare            pin \`expose public\` to a named Cloudflare tunnel
+                          (requires --domain)
+  --domain <hostname>     fully-qualified hostname to route through the tunnel
+                          (e.g. vault.example.com). The apex must be a zone on
+                          your Cloudflare account.
+  --tunnel-name <name>    Cloudflare tunnel name (default: \`parachute\`).
+                          Use to coexist multiple named tunnels on one box.
+  --skip-provider-check   bypass non-TTY auto-detect, default to Tailscale
+                          Funnel as before. Intended for CI / scripts whose
+                          environment is already pre-flighted.
 
 Examples:
   parachute expose tailnet                                 # tailnet HTTPS
-  parachute expose public                                  # Funnel: *.ts.net URL
+  parachute expose public                                  # auto-pick / picker
+  parachute expose public --tailnet                        # force Tailscale Funnel
   parachute expose public off                              # stop the Funnel
   parachute expose public --cloudflare --domain vault.example.com
                                                            # stable URL via cloudflared
@@ -177,6 +243,7 @@ export function startHelp(): string {
 Usage:
   parachute start                   start every installed service
   parachute start <service>         start just that one
+  parachute start hub               start the internal hub (port 1939)
 
 What it does:
   For each target service, spawns its start command detached, redirects
@@ -187,16 +254,23 @@ What it does:
   If a stale PID file exists (process died without cleanup), it's cleared
   and the service starts fresh.
 
+  \`parachute start hub\` brings up the internal hub directly (normally
+  spawned implicitly by \`parachute expose\`). Useful when restarting a
+  hub that crashed without an active expose layer.
+
 Flags:
   --hub-origin <url>    override PARACHUTE_HUB_ORIGIN passed to services
-                        (default: current expose-state hub origin, else loopback)
+                        (default: current expose-state hub origin, else loopback).
+                        For \`start hub\`, also doubles as the hub's --issuer.
 
 Examples:
   parachute start                   bring everything up
   parachute start vault             just vault
+  parachute start hub               just the internal hub
   parachute logs vault              watch what just started
 
 Start commands by service:
+  hub       bun <cli>/hub-server.ts --port <picked> ...
   vault     parachute-vault serve
   scribe    parachute-scribe serve
   channel   parachute-channel daemon
@@ -210,6 +284,7 @@ export function stopHelp(): string {
 Usage:
   parachute stop                    stop every installed service
   parachute stop <service>          stop just that one
+  parachute stop hub                stop the internal hub
 
 What it does:
   Sends SIGTERM, waits up to 10s for a clean exit, then escalates to
@@ -217,9 +292,13 @@ What it does:
 
   No-op if the service wasn't running.
 
+  Bare \`parachute stop\` (no service) does NOT stop the hub — that's
+  managed by the active expose layer (or \`parachute stop hub\` directly).
+
 Examples:
   parachute stop                    stop everything before sleep
   parachute stop vault              just vault
+  parachute stop hub                just the internal hub
 `;
 }
 
@@ -229,18 +308,53 @@ export function restartHelp(): string {
 Usage:
   parachute restart                 restart every installed service
   parachute restart <service>       restart just that one
+  parachute restart hub             restart the internal hub
 
 What it does:
   Equivalent to \`parachute stop <svc> && parachute start <svc>\`.
 `;
 }
 
+export function upgradeHelp(): string {
+  return `parachute upgrade — pull / re-install + restart in one step
+
+Usage:
+  parachute upgrade                 upgrade every installed service
+  parachute upgrade <service>       upgrade just that one
+  parachute upgrade [svc] --tag <name>
+                                    npm-installed services only — pin a dist-tag
+                                    (default: latest). Ignored when bun-linked.
+
+What it does:
+  Detects whether the target service is bun-linked from a local checkout
+  (the dev-mode shape) or npm-installed from a published artifact:
+
+    bun-linked  git pull --ff-only in the checkout, bun install if
+                package.json/bun.lock changed, bun run build for frontend
+                modules with a build script, then \`parachute restart\`.
+                Refuses on a dirty working tree — commit or stash first.
+
+    npm         bun add -g <pkg>@<tag>, then \`parachute restart\` if the
+                installed version actually moved.
+
+  Idempotent: if the source didn't change (HEAD unchanged after pull, or
+  package.json version unchanged after bun add -g), the restart is skipped.
+  Re-running on an up-to-date install is a fast no-op.
+
+Examples:
+  parachute upgrade                 sweep every installed service
+  parachute upgrade vault           just vault
+  parachute upgrade vault --tag rc  pin the rc dist-tag (npm path only)
+`;
+}
+
 export function logsHelp(): string {
   return `parachute logs — print service logs
 
 Usage:
   parachute logs <service>          print the last 200 lines
   parachute logs <service> -f       tail the log (like \`tail -f\`)
+  parachute logs hub                logs for the internal hub
 
 Log file:
   ~/.parachute/<service>/logs/<service>.log

package/src/hub-control.ts

@@ -3,6 +3,7 @@ import { createServer } from "node:net";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CONFIG_DIR } from "./config.ts";
+import { hubDbPath } from "./hub-db.ts";
 import {
   type AliveFn,
   clearPid,
@@ -123,6 +124,14 @@ export interface EnsureHubOpts {
   reservedPorts?: Iterable<number>;
   /** How long to wait after spawn before claiming readiness. Short — tests set to 0. */
   readyWaitMs?: number;
+  /**
+   * Public origin to use as the OAuth `iss` claim and as the base for the
+   * authorization-server metadata document. Forwarded to the hub server as
+   * `--issuer <url>`. When omitted, the hub falls back to the request's own
+   * origin — fine for loopback testing, wrong under tailscale where the
+   * request origin is `http://127.0.0.1:<port>`.
+   */
+  issuer?: string;
   log?: (line: string) => void;
 }
 
@@ -180,6 +189,9 @@ export async function ensureHubRunning(opts: EnsureHubOpts = {}): Promise<Ensure
     String(chosenPort),
     "--well-known-dir",
     wellKnownDir,
+    "--db",
+    hubDbPath(configDir),
+    ...(opts.issuer ? ["--issuer", opts.issuer] : []),
   ];
   const pid = spawner.spawn(cmd, logFile);
   writePid(HUB_SVC, pid, configDir);

package/src/hub-db.ts

@@ -0,0 +1,164 @@
+/**
+ * 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).
+ *
+ * Each open() runs `migrate()` to bring the schema up to date. A
+ * `schema_version` table records every applied migration so re-opens are
+ * cheap and idempotent. Migrations are append-only — never edit a prior
+ * entry; add a new one with a higher number.
+ */
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CONFIG_DIR } from "./config.ts";
+
+export function hubDbPath(configDir: string = CONFIG_DIR): string {
+  return join(configDir, "hub.db");
+}
+
+interface Migration {
+  version: number;
+  sql: string;
+}
+
+const MIGRATIONS: readonly Migration[] = [
+  {
+    version: 1,
+    sql: `
+      CREATE TABLE signing_keys (
+        kid TEXT PRIMARY KEY,
+        public_key_pem TEXT NOT NULL,
+        private_key_pem TEXT NOT NULL,
+        algorithm TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        retired_at TEXT
+      );
+      CREATE INDEX signing_keys_active ON signing_keys (retired_at)
+        WHERE retired_at IS NULL;
+    `,
+  },
+  {
+    version: 2,
+    sql: `
+      CREATE TABLE users (
+        id TEXT PRIMARY KEY,
+        username TEXT UNIQUE NOT NULL,
+        password_hash TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+      CREATE TABLE tokens (
+        jti TEXT PRIMARY KEY,
+        user_id TEXT NOT NULL REFERENCES users(id),
+        client_id TEXT NOT NULL,
+        scopes TEXT NOT NULL,
+        refresh_token_hash TEXT,
+        expires_at TEXT NOT NULL,
+        revoked_at TEXT,
+        created_at TEXT NOT NULL
+      );
+      CREATE INDEX tokens_user ON tokens (user_id);
+      CREATE INDEX tokens_active_refresh ON tokens (refresh_token_hash)
+        WHERE refresh_token_hash IS NOT NULL AND revoked_at IS NULL;
+    `,
+  },
+  {
+    version: 3,
+    sql: `
+      CREATE TABLE clients (
+        client_id TEXT PRIMARY KEY,
+        client_secret_hash TEXT,
+        redirect_uris TEXT NOT NULL,
+        scopes TEXT NOT NULL,
+        client_name TEXT,
+        registered_at TEXT NOT NULL
+      );
+      CREATE TABLE auth_codes (
+        code TEXT PRIMARY KEY,
+        client_id TEXT NOT NULL REFERENCES clients(client_id),
+        user_id TEXT NOT NULL REFERENCES users(id),
+        redirect_uri TEXT NOT NULL,
+        scopes TEXT NOT NULL,
+        code_challenge TEXT NOT NULL,
+        code_challenge_method TEXT NOT NULL,
+        expires_at TEXT NOT NULL,
+        used_at TEXT,
+        created_at TEXT NOT NULL
+      );
+      CREATE TABLE grants (
+        user_id TEXT NOT NULL REFERENCES users(id),
+        client_id TEXT NOT NULL REFERENCES clients(client_id),
+        scopes TEXT NOT NULL,
+        granted_at TEXT NOT NULL,
+        PRIMARY KEY (user_id, client_id)
+      );
+      CREATE TABLE sessions (
+        id TEXT PRIMARY KEY,
+        user_id TEXT NOT NULL REFERENCES users(id),
+        expires_at TEXT NOT NULL,
+        created_at TEXT NOT NULL
+      );
+      CREATE INDEX sessions_user ON sessions (user_id);
+    `,
+  },
+  {
+    version: 4,
+    sql: `
+      -- DCR approval gate (closes #74). Public DCR was unauthenticated before
+      -- this migration; pre-existing rows are grandfathered as 'approved' so
+      -- already-trusted clients keep working. New rows default to 'pending'
+      -- unless the registrant authenticates with an operator token carrying
+      -- hub:admin scope.
+      ALTER TABLE clients ADD COLUMN status TEXT NOT NULL DEFAULT 'pending';
+      UPDATE clients SET status = 'approved';
+      CREATE INDEX clients_status ON clients (status);
+    `,
+  },
+  {
+    version: 5,
+    sql: `
+      -- Refresh-token rotation + replay detection (closes #73). Each chain
+      -- of rotated refresh tokens shares a family_id; replaying a revoked
+      -- refresh token in a family signals theft and revokes every row in
+      -- that family (RFC 6819 §5.2.2.3). Pre-existing rows are backfilled
+      -- with their own jti as the family — grandfathered as singletons so
+      -- in-flight tokens keep working without spurious family revocation.
+      ALTER TABLE tokens ADD COLUMN family_id TEXT;
+      UPDATE tokens SET family_id = jti WHERE family_id IS NULL;
+      CREATE INDEX tokens_family ON tokens (family_id) WHERE family_id IS NOT NULL;
+    `,
+  },
+];
+
+export function openHubDb(path: string = hubDbPath()): Database {
+  mkdirSync(dirname(path), { recursive: true });
+  const db = new Database(path);
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA foreign_keys = ON");
+  migrate(db);
+  return db;
+}
+
+export function migrate(db: Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_version (
+      version INTEGER PRIMARY KEY,
+      applied_at TEXT NOT NULL
+    );
+  `);
+  const applied = new Set<number>(
+    (db.query("SELECT version FROM schema_version").all() as { version: number }[]).map(
+      (r) => r.version,
+    ),
+  );
+  const insert = db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (?, ?)");
+  for (const m of MIGRATIONS) {
+    if (applied.has(m.version)) continue;
+    db.transaction(() => {
+      db.exec(m.sql);
+      insert.run(m.version, new Date().toISOString());
+    })();
+  }
+}