@openparachute/hub 0.5.14-rc.9 → 0.6.1-rc.1

package/README.md

@@ -155,6 +155,29 @@ parachute expose tailnet  # HTTPS, MagicDNS, only your devices (the supported sh
 
 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
 
 `parachute start`, `stop`, `restart`, and `logs` manage services as background processes — no launchd, no manual `bun serve`, no hunting for PIDs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.5.14-rc.9",
+  "version": "0.6.1-rc.1",
   "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"');
   });
 });