@openparachute/hub 0.5.14-rc.1 → 0.5.14-rc.10

package/README.md

@@ -61,33 +61,122 @@ Operators who want env-var-driven seeding (CI, scripted deploys) can still set `
 
 ## First 5 minutes
 
+One command gets you from a fresh install to the setup wizard:
+
 ```sh
 # 1. Install the hub (one line — installs the `parachute` binary)
 bun add -g @openparachute/hub
 
-# 2. Install a service (runs `bun add -g @openparachute/vault` + `parachute-vault init`)
-parachute install vault
+# 2. parachute init — the unified front door (laptop, EC2, any VPS).
+#    It starts the hub, offers to expose it, always installs the vault
+#    module, then drops you into the setup wizard.
+parachute init
+```
 
-# 3. Start the service in the background (PID + logs tracked under ~/.parachute/vault/)
-parachute start vault
+`parachute init` is idempotent — every re-run is safe. End to end it:
+
+1. **Starts the hub** if it isn't already running (port `1939`).
+2. **Offers to expose it** so you can reach the wizard from other devices. In a
+   terminal you pick: stay loopback-only, your **tailnet** (`tailscale serve` —
+   private to your own Tailscale devices), or a **Cloudflare Tunnel** (public
+   HTTPS on your own domain). The default highlights "no thanks — loopback" on a
+   laptop and pre-selects Cloudflare on an SSH'd server. Skip with
+   `--no-expose-prompt`, or pin non-interactively with
+   `--expose none|tailnet|cloudflare`.
+3. **Installs the vault module** — always — so the wizard can offer
+   create / import / skip. No vault *instance* is created yet; that's the
+   wizard's call.
+4. **Drops you into the setup wizard.** Browser by default (opens
+   `/admin/setup`); pick the in-terminal walk-through with `--cli-wizard`, or
+   force the browser with `--browser-wizard`. It prints the canonical admin URL
+   either way — loopback when you're not exposed, the tailnet / Cloudflare FQDN
+   when you are.
+
+The wizard walks the same three steps in the browser and the CLI:
+
+- **Account** — create the admin operator for this hub (username + password).
+- **Vault** — *create* a fresh vault (default name `default`), *import* one from
+  a git repo (a previously-exported Parachute vault on any HTTPS / SSH remote;
+  PAT optional for private repos), or *skip* and create one later. The vault
+  module is installed regardless of which you pick.
+- **Expose** — record how this hub is reached (localhost / tailnet / public) so
+  the done screen surfaces the right URLs.
+
+The done screen hands you a copy-pasteable `claude mcp add` command (with a
+freshly-minted operator token), a link to start using your vault, and the admin
+UI. Verify the stack any time:
 
-# 4. Check it landed — reads ~/.parachute/services.json, shows process state + probes health
+```sh
 parachute status
 # SERVICE          PORT  VERSION  PROCESS  PID    UPTIME  HEALTH  LATENCY
-# parachute-vault  1940  0.2.4    running  12345  12s     ok      2ms
+# parachute-hub    1939  0.5.14   running  12344  20s     ok      1ms
+# parachute-vault  1940  0.4.5    running  12345  12s     ok      2ms
+```
 
-# 5. Use it. Vault is up on 127.0.0.1:1940; Claude Code picked up the MCP
-#    on your next session. Point any other local MCP client (Codex, Goose,
-#    OpenCode, Cursor, Zed, Cline, your own agent) at:
-#      http://127.0.0.1:1940/vault/default/mcp
+Vault is up on `127.0.0.1:1940`; Claude Code picks up the MCP on your next
+session. Point any other local MCP client (Codex, Goose, OpenCode, Cursor, Zed,
+Cline, your own agent) at `http://127.0.0.1:1940/vault/<name>/mcp`.
 
-# 6. Expose across your tailnet — HTTPS, MagicDNS, only your devices.
-#    The supported exposure shape today; public-internet exposure is
-#    exploratory (see "Public exposure" below).
-parachute expose tailnet
+### Want the wizard in the terminal instead of the browser?
+
+```sh
+parachute init --cli-wizard
 ```
 
-Tear down with `parachute expose tailnet off`. The public layer (`expose public off`) tears down independently — `off` only affects the layer you name.
+…or drive the wizard directly against an already-running hub:
+
+```sh
+parachute setup-wizard --hub-url http://127.0.0.1:1939
+```
+
+`setup-wizard` is the in-terminal mirror of `/admin/setup` — same handlers, same
+Account → Vault → Expose walk. Every prompt has a paired flag for scripted /
+non-interactive setup (`--account-username`, `--account-password`,
+`--vault-mode create|import|skip`, `--vault-name`, `--vault-import-url`,
+`--expose-mode localhost|tailnet|public`, …); run `parachute setup-wizard --help`
+for the full list.
+
+### Prefer to drive installs by hand?
+
+`parachute init` → wizard is the recommended path, but the per-module commands
+still work and are additive:
+
+```sh
+parachute install vault   # install + register + create first vault + start one module
+parachute setup           # older interactive multi-pick: survey + install vault/notes/scribe
+parachute start vault     # PID + logs tracked under ~/.parachute/vault/
+```
+
+### Expose across your tailnet
+
+```sh
+parachute expose tailnet  # HTTPS, MagicDNS, only your devices (the supported shape today)
+```
+
+Tear down with `parachute expose tailnet off`. The public layer (`expose public off`) tears down independently — `off` only affects the layer you name. Public-internet exposure is exploratory (see "Public exposure" below).
+
+### Onboarding a team member
+
+Want to give a friend or teammate their own account on your hub? The flow is
+self-service end to end:
+
+1. **Create the user.** In the admin UI, open **Users → Create User**: pick a
+   username, set a temporary password, and (optionally) assign one or more
+   vaults. The success banner echoes the exact sign-in URL.
+2. **Hand them three things:** your hub's sign-in URL (`<hub-origin>/login`),
+   their username, and the temporary password you set.
+3. **They sign in and set their own password.** On first sign-in they're
+   prompted to change it — they can't reach the rest of the hub until they do.
+4. **Later changes are self-service.** A signed-in user changes their password
+   anytime from their account home at `/account/` (reachable via the **Account**
+   link in the top-right once signed in).
+5. **You can reset it for them.** If they're locked out, the **Reset password**
+   button on the Users row sets a new temporary password and re-arms the
+   force-change-on-next-sign-in prompt.
+
+The first admin (the wizard / env-seeded account) is unrestricted and can't be
+deleted or reset from the Users page — it changes its own password at
+`/account/change-password` directly.
 
 ## Service lifecycle
 
@@ -313,6 +402,11 @@ Public-internet exposure (`parachute expose public`) is exploratory — see "Pub
 Run `parachute --help` for the top-level list, and `parachute <subcommand> --help` for details on any individual command.
 
 ```
+parachute init                    fresh-install front door: start hub, offer expose,
+                                  install vault module, open the setup wizard
+parachute setup-wizard --hub-url <url>
+                                  in-terminal mirror of /admin/setup (Account/Vault/Expose)
+parachute setup                   older interactive multi-pick service installer
 parachute install <service>       install and register a service
 parachute status                  show installed services, process state, health
 parachute start   [service]       start services in the background

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.5.14-rc.1",
+  "version": "0.5.14-rc.10",
   "description": "parachute \u2014 the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/account-home-ui.test.ts

@@ -4,8 +4,9 @@
  * tests pin the load-bearing shape:
  *
  *   - Assigned-vault branch: Notes CTA href encodes the hub+vault URL,
- *     vault name shows in the body, hub origin appears as inline code
- *     in the custom-client disclosure.
+ *     vault name shows in the body, AND a per-tile MCP connect block
+ *     surfaces the endpoint + `claude mcp add` command (OAuth, no token)
+ *     with copy buttons — the multi-user friend-connect surface.
  *   - Admin (no assigned vault) branch: link to /admin/ visible.
  *   - Defensive third branch (non-admin + no vault): "ask the operator"
  *     copy renders.
@@ -13,7 +14,11 @@
  *     change-password link.
  */
 import { describe, expect, test } from "bun:test";
-import { renderAccountHome } from "../account-home-ui.ts";
+import {
+  accountClaudeMcpAddCommand,
+  accountMcpEndpoint,
+  renderAccountHome,
+} from "../account-home-ui.ts";
 
 const HUB_ORIGIN = "https://hub.example";
 const CSRF = "test-csrf-token";
@@ -22,7 +27,7 @@ describe("renderAccountHome", () => {
   test("assigned-vault branch — Notes CTA carries the encoded hub+vault URL", () => {
     const html = renderAccountHome({
       username: "alice",
-      assignedVault: "alice",
+      assignedVaults: ["alice"],
       passwordChanged: true,
       hubOrigin: HUB_ORIGIN,
       isFirstAdmin: false,
@@ -38,9 +43,19 @@ describe("renderAccountHome", () => {
     expect(html).toContain(`https://notes.parachute.computer/add?url=${encodedVaultUrl}`);
     expect(html).toContain('target="_blank"');
     expect(html).toContain('rel="noopener"');
-    // Hub origin renders as inline <code> in the custom-client disclosure.
-    expect(html).toContain(`<code>${HUB_ORIGIN}</code>`);
-    expect(html).toContain("Use a custom client");
+    // The friend-connect surface: MCP endpoint + `claude mcp add` command,
+    // each with a copy button. OAuth path (no token in the command).
+    expect(html).toContain(`${HUB_ORIGIN}/vault/alice/mcp`);
+    expect(html).toContain(
+      `claude mcp add --transport http parachute-alice ${HUB_ORIGIN}/vault/alice/mcp`,
+    );
+    expect(html).toContain('data-testid="copy-mcp-endpoint"');
+    expect(html).toContain('data-testid="copy-mcp-add-command"');
+    // The connect command must NOT embed a token — the OAuth path needs none.
+    expect(html).not.toContain("--header");
+    expect(html).not.toContain("Authorization: Bearer");
+    // Copy-button progressive-enhancement script is present.
+    expect(html).toContain("navigator.clipboard");
   });
 
   test("assigned-vault branch — trailing slash on hubOrigin is normalized", () => {
@@ -49,7 +64,7 @@ describe("renderAccountHome", () => {
     // renderer must produce a clean `/vault/<name>` join either way.
     const html = renderAccountHome({
       username: "alice",
-      assignedVault: "alice",
+      assignedVaults: ["alice"],
       passwordChanged: true,
       hubOrigin: `${HUB_ORIGIN}/`,
       isFirstAdmin: false,
@@ -57,15 +72,16 @@ describe("renderAccountHome", () => {
     });
     const cleanEncoded = encodeURIComponent(`${HUB_ORIGIN}/vault/alice`);
     expect(html).toContain(`https://notes.parachute.computer/add?url=${cleanEncoded}`);
-    // The inline-code display also drops the trailing slash.
-    expect(html).toContain(`<code>${HUB_ORIGIN}</code>`);
-    expect(html).not.toContain(`<code>${HUB_ORIGIN}/</code>`);
+    // The MCP endpoint + connect command also drop the trailing slash — no
+    // `//vault` double-slash sneaks in.
+    expect(html).toContain(`${HUB_ORIGIN}/vault/alice/mcp`);
+    expect(html).not.toContain(`${HUB_ORIGIN}//vault`);
   });
 
   test("admin branch — null assignedVault + isFirstAdmin renders an /admin/ link", () => {
     const html = renderAccountHome({
       username: "admin",
-      assignedVault: null,
+      assignedVaults: [],
       passwordChanged: true,
       hubOrigin: HUB_ORIGIN,
       isFirstAdmin: true,
@@ -85,7 +101,7 @@ describe("renderAccountHome", () => {
     // state via hand-edit or migration race.
     const html = renderAccountHome({
       username: "ghost",
-      assignedVault: null,
+      assignedVaults: [],
       passwordChanged: true,
       hubOrigin: HUB_ORIGIN,
       isFirstAdmin: false,
@@ -102,7 +118,7 @@ describe("renderAccountHome", () => {
   test("account card — change-password link and sign-out form are present", () => {
     const html = renderAccountHome({
       username: "alice",
-      assignedVault: "alice",
+      assignedVaults: ["alice"],
       passwordChanged: true,
       hubOrigin: HUB_ORIGIN,
       isFirstAdmin: false,
@@ -120,21 +136,70 @@ describe("renderAccountHome", () => {
     expect(html).toContain("<code>alice</code>");
   });
 
+  test("multi-vault branch — renders one tile per assigned vault (Phase 2 PR 2)", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["personal", "family"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+    });
+    // Plural heading.
+    expect(html).toContain("Your vaults");
+    // Each vault name appears.
+    expect(html).toContain("<strong>personal</strong>");
+    expect(html).toContain("<strong>family</strong>");
+    // One CTA per vault with the right encoded URL.
+    const personalEncoded = encodeURIComponent(`${HUB_ORIGIN}/vault/personal`);
+    const familyEncoded = encodeURIComponent(`${HUB_ORIGIN}/vault/family`);
+    expect(html).toContain(`https://notes.parachute.computer/add?url=${personalEncoded}`);
+    expect(html).toContain(`https://notes.parachute.computer/add?url=${familyEncoded}`);
+    // One per-vault MCP connect block per tile (endpoint + command).
+    expect(html).toContain(`${HUB_ORIGIN}/vault/personal/mcp`);
+    expect(html).toContain(`${HUB_ORIGIN}/vault/family/mcp`);
+    expect(html).toContain(
+      `claude mcp add --transport http parachute-personal ${HUB_ORIGIN}/vault/personal/mcp`,
+    );
+    expect(html).toContain(
+      `claude mcp add --transport http parachute-family ${HUB_ORIGIN}/vault/family/mcp`,
+    );
+    // Two tiles → two copy-endpoint buttons.
+    expect(html.split('data-testid="copy-mcp-endpoint"').length - 1).toBe(2);
+    // The copy script is emitted once at the section level, not per-tile.
+    expect(html.split("<script>").length - 1).toBe(1);
+  });
+
+  test("accountMcpEndpoint / accountClaudeMcpAddCommand build the canonical shapes", () => {
+    expect(accountMcpEndpoint("https://hub.example", "work")).toBe(
+      "https://hub.example/vault/work/mcp",
+    );
+    expect(accountClaudeMcpAddCommand("https://hub.example", "work")).toBe(
+      "claude mcp add --transport http parachute-work https://hub.example/vault/work/mcp",
+    );
+  });
+
   test("escapes hostile content in username and vault name", () => {
     // Defense-in-depth: usernames pass validateUsername (lowercase alnum
     // + `_-`), so HTML metacharacters won't normally make it through. But
     // the renderer is a pure function over arbitrary string input and the
     // escape is load-bearing if the validator ever loosens.
     const html = renderAccountHome({
-      username: "<script>",
-      assignedVault: "<vault>",
+      username: "<script>alert(1)</script>",
+      assignedVaults: ["<vault>"],
       passwordChanged: true,
       hubOrigin: HUB_ORIGIN,
       isFirstAdmin: false,
       csrfToken: CSRF,
     });
-    expect(html).not.toContain("<script>");
-    expect(html).toContain("&lt;script&gt;");
+    // The injected username/vault metacharacters are escaped — the only
+    // `<script>` tag in the output is the page's own copy-button helper, so
+    // we assert on the injected payload specifically rather than a blanket
+    // "no <script>" (the connect block legitimately emits one).
+    expect(html).not.toContain("<script>alert(1)</script>");
+    expect(html).toContain("&lt;script&gt;alert(1)&lt;/script&gt;");
     expect(html).toContain("&lt;vault&gt;");
+    // The escaped vault name also flows into the connect command + endpoint.
+    expect(html).toContain("parachute-&lt;vault&gt;");
   });
 });

package/src/__tests__/admin-vault-admin-token.test.ts

@@ -160,7 +160,7 @@ describe("handleVaultAdminToken", () => {
     // whole reason this gate exists.
     await createUser(harness.db, "operator", "hunter2-admin");
     const friend = await createUser(harness.db, "friend", "hunter2-friend", {
-      assignedVault: "work",
+      assignedVaults: ["work"],
       allowMulti: true,
     });
     const session = createSession(harness.db, { userId: friend.id });
@@ -182,7 +182,7 @@ describe("handleVaultAdminToken", () => {
     // happy path when there are friends in the DB.
     const admin = await createUser(harness.db, "operator", "hunter2-admin");
     await createUser(harness.db, "friend", "hunter2-friend", {
-      assignedVault: "work",
+      assignedVaults: ["work"],
       allowMulti: true,
     });
     const session = createSession(harness.db, { userId: admin.id });

package/src/__tests__/admin-vaults.test.ts

@@ -8,11 +8,21 @@ import { signAccessToken } from "../jwt-sign.ts";
 import { upsertService, writeManifest } from "../services-manifest.ts";
 import { rotateSigningKey } from "../signing-keys.ts";
 
-/** Build the JSON shape parachute-vault create --json emits (PR #184). */
-function vaultCreateJson(name: string, token = `pvt_${name}_token`): string {
+/**
+ * Build the JSON shape `parachute-vault create --json` emits (PR #184).
+ * Post the pvt_* DROP the `token` is a hub-issued access JWT (scoped
+ * `vault:<name>:admin`), and may be the empty string when the vault
+ * couldn't mint — in which case `token_guidance` carries the reason.
+ */
+function vaultCreateJson(
+  name: string,
+  token = `hubjwt.${name}.access`,
+  tokenGuidance?: string,
+): string {
   return JSON.stringify({
     name,
     token,
+    ...(tokenGuidance ? { token_guidance: tokenGuidance } : {}),
     paths: {
       vault_dir: `/home/test/.parachute/vault/${name}`,
       vault_db: `/home/test/.parachute/vault/${name}/vault.db`,
@@ -404,7 +414,7 @@ describe("POST /vaults — orchestration", () => {
           );
           return {
             exitCode: 0,
-            stdout: vaultCreateJson("work", "pvt_supersecret"),
+            stdout: vaultCreateJson("work", "hubjwt.work.access"),
             stderr: "",
           };
         };
@@ -420,7 +430,7 @@ describe("POST /vaults — orchestration", () => {
           token?: string;
           paths?: { vault_dir: string; vault_db: string; vault_config: string };
         };
-        expect(body.token).toBe("pvt_supersecret");
+        expect(body.token).toBe("hubjwt.work.access");
         expect(body.paths).toEqual({
           vault_dir: "/home/test/.parachute/vault/work",
           vault_db: "/home/test/.parachute/vault/work/vault.db",
@@ -434,6 +444,62 @@ describe("POST /vaults — orchestration", () => {
     }
   });
 
+  test("201 forwards an empty token + token_guidance when the vault couldn't mint (post-DROP)", async () => {
+    // The vault emits `token: ""` + a `token_guidance` reason when no hub
+    // origin was reachable to mint against (e.g. loopback create). The hub
+    // must forward both verbatim so the SPA can render the
+    // created-but-no-token state instead of confusing it with a re-POST.
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        upsertService(
+          {
+            name: "parachute-vault",
+            port: 1940,
+            paths: ["/vault/default"],
+            health: "/health",
+            version: "0.3.5",
+          },
+          h.manifestPath,
+        );
+        const runCommand = async (_cmd: readonly string[]): Promise<RunResult> => {
+          upsertService(
+            {
+              name: "parachute-vault",
+              port: 1940,
+              paths: ["/vault/default", "/vault/work"],
+              health: "/health",
+              version: "0.3.5",
+            },
+            h.manifestPath,
+          );
+          return {
+            exitCode: 0,
+            stdout: vaultCreateJson("work", "", "no hub origin reachable to mint against"),
+            stderr: "",
+          };
+        };
+        const res = await call({
+          db,
+          manifestPath: h.manifestPath,
+          body: { name: "work" },
+          runCommand,
+        });
+        // Still a fresh create — HTTP 201, NOT 200.
+        expect(res.status).toBe(201);
+        const body = (await res.json()) as { token?: string; token_guidance?: string };
+        expect(body.token).toBe("");
+        expect(body.token_guidance).toBe("no hub origin reachable to mint against");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("500 when `parachute-vault create --json` exits 0 but stdout is unparseable", async () => {
     const h = makeHarness();
     try {

package/src/__tests__/api-account.test.ts

@@ -757,7 +757,7 @@ describe("handleAccountHomeGet", () => {
     const friend = await createUser(harness.db, "alice", "alice-passphrase", {
       allowMulti: true,
       passwordChanged: true,
-      assignedVault: "alice",
+      assignedVaults: ["alice"],
     });
     const session = createSession(harness.db, { userId: friend.id });
     const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000));
@@ -774,7 +774,7 @@ describe("handleAccountHomeGet", () => {
     expect(html).toContain(`https://notes.parachute.computer/add?url=${encoded}`);
   });
 
-  test("200 + admin branch when the first-admin signs in (assignedVault=null)", async () => {
+  test("200 + admin branch when the first-admin signs in (no vault assignments)", async () => {
     // The first-created user with no vault pin is the admin posture.
     const admin = await createUser(harness.db, "admin", "admin-passphrase", {
       passwordChanged: true,