@openparachute/hub 0.5.14-rc.8 → 0.6.0

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.8",
+  "version": "0.6.0",
   "description": "parachute \u2014 the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {
@@ -37,13 +37,17 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "@types/qrcode": "^1.5.6"
   },
   "peerDependencies": {
     "typescript": "^5"
   },
   "dependencies": {
     "@node-rs/argon2": "^2.0.2",
-    "jose": "^6.2.2"
+    "@openparachute/depcheck": "0.1.0",
+    "jose": "^6.2.2",
+    "otpauth": "^9.5.0",
+    "qrcode": "^1.5.4"
   }
 }

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";
@@ -27,6 +32,7 @@ describe("renderAccountHome", () => {
       hubOrigin: HUB_ORIGIN,
       isFirstAdmin: false,
       csrfToken: CSRF,
+      twoFactorEnabled: false,
     });
     // Welcome header includes the username.
     expect(html).toContain("Welcome, alice");
@@ -38,9 +44,36 @@ 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");
+    // Friendlier framing: the block leads with "connect your AI assistant"
+    // rather than MCP jargon up top.
+    expect(html).toContain('data-testid="connect-ai-heading"');
+    expect(html).toContain("Connect your AI");
+    // BOTH connect methods render as distinct, labelled blocks.
+    expect(html).toContain('data-testid="connect-method-claude-code"');
+    expect(html).toContain("Claude Code");
+    expect(html).toContain('data-testid="connect-method-claude-ai"');
+    expect(html).toContain("Claude.ai");
+    // The Claude.ai path mirrors the install.njk canonical phrasing
+    // (Settings → Connectors → Add custom connector, paste the endpoint).
+    expect(html).toContain("Connectors");
+    expect(html).toContain("Add custom connector");
+    // A brief "any other MCP client" line is present (no bloat — just one).
+    expect(html).toContain('data-testid="connect-any-client-hint"');
+    // Notes CTA still present, now framed as the browser-UI option.
+    expect(html).toContain('data-testid="open-notes-cta"');
   });
 
   test("assigned-vault branch — trailing slash on hubOrigin is normalized", () => {
@@ -54,12 +87,14 @@ describe("renderAccountHome", () => {
       hubOrigin: `${HUB_ORIGIN}/`,
       isFirstAdmin: false,
       csrfToken: CSRF,
+      twoFactorEnabled: false,
     });
     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", () => {
@@ -70,6 +105,7 @@ describe("renderAccountHome", () => {
       hubOrigin: HUB_ORIGIN,
       isFirstAdmin: true,
       csrfToken: CSRF,
+      twoFactorEnabled: false,
     });
     expect(html).toContain("Welcome, admin");
     expect(html).toContain("hub administrator");
@@ -90,13 +126,19 @@ describe("renderAccountHome", () => {
       hubOrigin: HUB_ORIGIN,
       isFirstAdmin: false,
       csrfToken: CSRF,
+      twoFactorEnabled: false,
     });
     expect(html).toContain("Welcome, ghost");
-    expect(html).toContain("Ask the hub operator");
+    // The message explains WHY there's nothing to connect (no vault yet) and
+    // gives a clear next step — not just a bare "ask your admin".
+    expect(html).toContain("Ask the hub operator to assign you a vault");
+    expect(html).toContain("don't have a vault yet");
     // No /admin/ link in this branch — they have no admin role.
     expect(html).not.toContain('href="/admin/"');
     // No Notes CTA.
     expect(html).not.toContain("notes.parachute.computer/add");
+    // No connect block — you can't connect a vault you don't have.
+    expect(html).not.toContain('data-testid="mcp-connect"');
   });
 
   test("account card — change-password link and sign-out form are present", () => {
@@ -107,6 +149,7 @@ describe("renderAccountHome", () => {
       hubOrigin: HUB_ORIGIN,
       isFirstAdmin: false,
       csrfToken: CSRF,
+      twoFactorEnabled: false,
     });
     // Change-password link points at the existing /account/change-password
     // route (server-rendered HTML, separate handler).
@@ -120,6 +163,37 @@ describe("renderAccountHome", () => {
     expect(html).toContain("<code>alice</code>");
   });
 
+  test("account card — 2FA status reflects twoFactorEnabled (hub#473)", () => {
+    const off = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["alice"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+    });
+    expect(off).toContain('data-testid="2fa-status"');
+    expect(off).toContain(">Off<");
+    // Off → "Set up two-factor" affordance.
+    expect(off).toContain('data-testid="setup-2fa-link"');
+    expect(off).toContain('href="/account/2fa"');
+
+    const on = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["alice"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: true,
+    });
+    expect(on).toContain(">On<");
+    // On → "Manage two-factor" affordance.
+    expect(on).toContain('data-testid="manage-2fa-link"');
+    expect(on).toContain('href="/account/2fa"');
+  });
+
   test("multi-vault branch — renders one tile per assigned vault (Phase 2 PR 2)", () => {
     const html = renderAccountHome({
       username: "alice",
@@ -128,6 +202,7 @@ describe("renderAccountHome", () => {
       hubOrigin: HUB_ORIGIN,
       isFirstAdmin: false,
       csrfToken: CSRF,
+      twoFactorEnabled: false,
     });
     // Plural heading.
     expect(html).toContain("Your vaults");
@@ -139,8 +214,28 @@ describe("renderAccountHome", () => {
     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}`);
-    // Hub origin block appears once at the section level, not per tile.
-    expect(html.split(`<code>${HUB_ORIGIN}</code>`).length - 1).toBe(1);
+    // 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", () => {
@@ -149,15 +244,156 @@ describe("renderAccountHome", () => {
     // 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>",
+      username: "<script>alert(1)</script>",
       assignedVaults: ["<vault>"],
       passwordChanged: true,
       hubOrigin: HUB_ORIGIN,
       isFirstAdmin: false,
       csrfToken: CSRF,
+      twoFactorEnabled: false,
     });
-    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;");
+  });
+
+  // --- friend vault-token mint affordance (the new surface) ----------------
+
+  test("mint affordance — read+write tile offers both verbs, POSTs to the right path", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["work"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      mintableVerbs: { work: ["read", "write"] },
+    });
+    // The collapsible mint block is present, framed as secondary (headless).
+    expect(html).toContain('data-testid="token-mint"');
+    expect(html).toContain("Mint an access token");
+    expect(html).toContain("for scripts / headless clients");
+    // Both verb radios render.
+    expect(html).toContain('data-testid="mint-verb-read"');
+    expect(html).toContain('data-testid="mint-verb-write"');
+    // Form POSTs to the per-vault endpoint with the CSRF token embedded.
+    expect(html).toContain('action="/account/vault-token/work"');
+    expect(html).toContain('method="POST"');
+    expect(html).toContain('data-testid="mint-form"');
+    expect(html).toContain(CSRF);
+    // Recommends the no-token path as default.
+    expect(html).toContain("no-token");
+  });
+
+  test("mint affordance — a read-only role offers ONLY the read verb", () => {
+    // Today every assignment is write-role, but the renderer is verb-blind to
+    // the role: it shows exactly the verbs it's handed. A read-only cap must
+    // never surface a write radio (the server would reject it anyway).
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["work"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      mintableVerbs: { work: ["read"] },
+    });
+    expect(html).toContain('data-testid="mint-verb-read"');
+    expect(html).not.toContain('data-testid="mint-verb-write"');
+  });
+
+  test("mint affordance — never offers an admin verb", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["work"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      mintableVerbs: { work: ["read", "write"] },
+    });
+    expect(html).not.toContain('value="admin"');
+    expect(html).not.toContain('data-testid="mint-verb-admin"');
+  });
+
+  test("mint affordance — absent when no mintable verbs (admin / no-vault / unmapped role)", () => {
+    // Admin branch: no tiles at all, so no mint block.
+    const admin = renderAccountHome({
+      username: "admin",
+      assignedVaults: [],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: true,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+    });
+    expect(admin).not.toContain('data-testid="token-mint"');
+    // Assigned vault but empty verb list (fail-closed unknown role) → no block.
+    const empty = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["work"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      mintableVerbs: { work: [] },
+    });
+    expect(empty).not.toContain('data-testid="token-mint"');
+  });
+
+  test("minted-token banner — shows the token once with a save-it warning, no revoke claim", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["work"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      mintableVerbs: { work: ["read", "write"] },
+      mintedToken: {
+        vaultName: "work",
+        verb: "read",
+        token: "eyJhbGciOi.FAKE.TOKEN",
+        expiresInDays: 90,
+      },
+    });
+    expect(html).toContain('data-testid="minted-token-banner"');
+    expect(html).toContain("eyJhbGciOi.FAKE.TOKEN");
+    expect(html).toContain('data-testid="copy-minted-token"');
+    // Explicit "won't be shown again" + the scope + the TTL.
+    expect(html).toContain("won't be shown again");
+    expect(html).toContain("vault:work:read");
+    expect(html).toContain("90 days");
+    // No false revoke-yourself promise (no friend-facing revoke today).
+    expect(html).toContain("ask the hub operator");
+  });
+
+  test("mint error banner — surfaces an inline authorization error", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["work"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      mintableVerbs: { work: ["read", "write"] },
+      mintError: 'You\'re not assigned to a vault named "other".',
+    });
+    expect(html).toContain('data-testid="mint-error-banner"');
+    expect(html).toContain("not assigned");
+    // Error render must NOT also show a token.
+    expect(html).not.toContain('data-testid="minted-token-banner"');
   });
 });