@openparachute/hub 0.5.14-rc.8 → 0.6.0

package/src/commands/wizard.ts

@@ -76,8 +76,9 @@ export interface RunCliWizardOpts {
   sleep?: (ms: number) => Promise<void>;
   /**
    * Non-interactive escape hatch: pre-supply the account-step answers.
-   * Username defaults to `admin` when unset; password is required (no
-   * default, no prompt → exit-with-error). Mirrors the
+   * Username defaults to `owner` when unset (aligned with
+   * `parachute auth set-password` + the operator.token convention); password
+   * is required (no default, no prompt → exit-with-error). Mirrors the
    * `PARACHUTE_INITIAL_ADMIN_*` env-seed shape.
    */
   accountUsername?: string;
@@ -400,8 +401,11 @@ async function walkAccountStep(
   log("  Set up the operator account that owns this hub.");
   let username = opts.accountUsername;
   if (username === undefined) {
-    const raw = (await opts.prompt("  username [admin]: ")).trim();
-    username = raw === "" ? "admin" : raw;
+    // Default to "owner" — aligns with `parachute auth set-password` and the
+    // operator.token convention (the earliest-created user is the operator).
+    // The web wizard lets the operator name it freely; so does this prompt.
+    const raw = (await opts.prompt("  username [owner]: ")).trim();
+    username = raw === "" ? "owner" : raw;
   }
   let password = opts.accountPassword;
   if (password === undefined) {

package/src/env-file.ts

@@ -68,6 +68,16 @@ export function upsertEnvLine(lines: string[], key: string, value: string): stri
   return next;
 }
 
+/**
+ * Drop every `KEY=…` line for `key`, preserving the order of the rest.
+ * Returns a new array; the input is untouched. No-op (returns a copy) when
+ * the key isn't present.
+ */
+export function removeEnvLine(lines: string[], key: string): string[] {
+  const prefix = `${key}=`;
+  return lines.filter((line) => !line.startsWith(prefix));
+}
+
 export function writeEnvFile(path: string, lines: readonly string[]): void {
   mkdirSync(dirname(path), { recursive: true });
   const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;

package/src/help.ts

@@ -194,7 +194,7 @@ Flags:
                                  http://127.0.0.1:1939). \`parachute init\`
                                  passes this in when chaining; standalone
                                  callers supply it explicitly.
-  --account-username <name>      pre-supply the admin username (default: admin)
+  --account-username <name>      pre-supply the admin username (default: owner)
   --account-password <pw>        pre-supply the admin password (required when
                                  non-interactive)
   --bootstrap-token <token>      one-time bootstrap token when the hub is in
@@ -326,6 +326,7 @@ Usage:
   parachute expose public  --tailnet
   parachute expose public  --cloudflare --domain <hostname>
   parachute expose public  off --cloudflare
+  parachute expose cloudflare --domain <hostname>           # alias for the above
 
 Status:
   tailnet is the supported exposure shape. The hub's OAuth + per-module
@@ -381,6 +382,7 @@ Examples:
   parachute expose public off                              # stop the Funnel
   parachute expose public --cloudflare --domain vault.example.com
                                                            # stable URL via cloudflared
+  parachute expose cloudflare --domain vault.example.com   # alias for the line above
   parachute expose public off --cloudflare                 # stop the cloudflared tunnel
 
 Tailscale Funnel constraints:

package/src/hub-db.ts

@@ -2,7 +2,8 @@
  * 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).
+ * clients + auth-codes + grants + browser sessions (v3), and TOTP 2FA
+ * enrollment on the users row (v11, hub#473).
  *
  * Each open() runs `migrate()` to bring the schema up to date. A
  * `schema_version` table records every applied migration so re-opens are
@@ -320,6 +321,43 @@ const MIGRATIONS: readonly Migration[] = [
       ALTER TABLE users DROP COLUMN assigned_vault;
     `,
   },
+  {
+    version: 11,
+    sql: `
+      -- Real TOTP 2FA at the hub login layer (hub#473). Three nullable
+      -- columns on \`users\`:
+      --
+      --   * totp_secret (TEXT, nullable) — the base32-encoded RFC 6238 TOTP
+      --     secret. NULL means "2FA not enrolled" — the canonical "is 2FA on
+      --     for this user?" signal. Stored as the plaintext base32 string
+      --     (not encrypted at rest): hub.db already holds the argon2id
+      --     password hashes AND the OAuth signing private keys in plaintext
+      --     PEM (signing_keys.private_key_pem), so the TOTP secret sits at
+      --     the same operator-local trust boundary — encrypting one column
+      --     while leaving the signing key in the clear would be security
+      --     theatre. A future at-rest-encryption pass (hub#474 follow-up)
+      --     would cover all three (password hashes are already one-way; the
+      --     signing key + TOTP secret are the recoverable secrets).
+      --   * totp_backup_codes (TEXT, nullable) — JSON array of argon2id-HASHED
+      --     single-use recovery codes. Same hash family as passwords
+      --     (@node-rs/argon2). Plaintext codes are shown to the user exactly
+      --     once at enrollment and never stored. A code is removed from the
+      --     array when consumed. NULL / "[]" means "no backup codes left."
+      --   * totp_enrolled_at (TEXT, nullable) — ISO-8601 timestamp of the
+      --     last successful enrollment. NULL until first enroll; informational
+      --     (admin UI / account page "2FA enabled since …").
+      --
+      -- Backfill: every existing user pre-dates this migration and gets NULL
+      -- for all three — i.e. "2FA not enrolled." Their /login flow stays
+      -- password-only (the login handler only requires a TOTP step when
+      -- totp_secret IS NOT NULL), so existing operators keep signing in
+      -- exactly as before. No backfill UPDATE needed — the column default is
+      -- NULL.
+      ALTER TABLE users ADD COLUMN totp_secret TEXT;
+      ALTER TABLE users ADD COLUMN totp_backup_codes TEXT;
+      ALTER TABLE users ADD COLUMN totp_enrolled_at TEXT;
+    `,
+  },
 ];
 
 export function openHubDb(path: string = hubDbPath()): Database {

package/src/hub-server.ts

@@ -67,11 +67,20 @@
  *   /api/users/<id>               (DELETE)     → hard-delete user + revoke tokens (host:admin)
  *   /api/users/<id>/reset-password (POST)      → admin-initiated password reset (host:admin)
  *   /login                        (GET + POST) → operator password login
+ *   /login/2fa                    (POST)       → second-factor (TOTP/backup) step
+ *                                                 (hub#473; reached after a correct
+ *                                                 password for a 2FA-enrolled user)
  *   /logout                       (POST)       → end admin session
  *   /account/change-password      (GET + POST) → user self-service change-password
  *                                                 (force-redirect target for users
  *                                                 with password_changed=false; also
  *                                                 reachable directly to rotate)
+ *   /account/2fa                  (GET + POST) → user self-service 2FA enroll/disenroll
+ *                                                 (hub#473; QR + backup codes)
+ *   /account/vault-token/<name>   (POST)       → friend mints a scoped
+ *                                                 vault:<name>:read|write bearer for
+ *                                                 an ASSIGNED vault (headless clients;
+ *                                                 session + assignment + scope-capped)
  *   /admin/config*                             → 301 → /admin/vaults (legacy
  *                                                portal retired post-SPA-rework)
  *
@@ -108,11 +117,13 @@ import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import pkg from "../package.json" with { type: "json" };
+import { handleAccountVaultTokenPost } from "./account-vault-token.ts";
 import { handleApproveClient, handleGetClient } from "./admin-clients.ts";
 import { handleListGrants, handleRevokeGrant } from "./admin-grants.ts";
 import {
   handleAdminLoginGet,
   handleAdminLoginPost,
+  handleAdminLoginTotpPost,
   handleAdminLogoutPost,
 } from "./admin-handlers.ts";
 import { handleHostAdminToken } from "./admin-host-admin-token.ts";
@@ -199,6 +210,7 @@ import {
 } from "./setup-wizard.ts";
 import { getAllPublicKeys } from "./signing-keys.ts";
 import type { Supervisor } from "./supervisor.ts";
+import { handleTwoFactorGet, handleTwoFactorPost } from "./two-factor-handlers.ts";
 import { getUserById, userCount } from "./users.ts";
 import {
   WELL_KNOWN_DIR,
@@ -2029,6 +2041,17 @@ export function hubFetch(
       return new Response("method not allowed", { status: 405 });
     }
 
+    // /login/2fa — second-factor step (hub#473). POST-only: reached only
+    // after a correct password POST for a 2FA-enrolled user handed back a
+    // pending-login cookie + rendered the challenge page. A bare GET (e.g.
+    // browser back button) has no form to render usefully, so 405 → the
+    // operator restarts at /login.
+    if (pathname === "/login/2fa") {
+      if (!getDb) return dbNotConfigured();
+      if (req.method === "POST") return handleAdminLoginTotpPost(getDb(), req);
+      return new Response("method not allowed", { status: 405 });
+    }
+
     if (pathname === "/logout") {
       if (!getDb) return dbNotConfigured();
       if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
@@ -2056,6 +2079,35 @@ export function hubFetch(
       return new Response("method not allowed", { status: 405 });
     }
 
+    // /account/2fa — user self-service TOTP 2FA enroll / disenroll (hub#473).
+    // Both GET (render state) and POST (start/confirm/disable) require an
+    // active session; the handler does the session check + 302 to /login when
+    // missing, same posture as /account/change-password.
+    if (pathname === "/account/2fa") {
+      if (!getDb) return dbNotConfigured();
+      const twoFactorDeps = { db: getDb() };
+      if (req.method === "GET") return handleTwoFactorGet(req, twoFactorDeps);
+      if (req.method === "POST") return handleTwoFactorPost(req, twoFactorDeps);
+      return new Response("method not allowed", { status: 405 });
+    }
+
+    // /account/vault-token/<name> — friend-facing scoped vault token mint.
+    // POST-only, session-gated, assignment-capped: a non-admin friend mints a
+    // `vault:<name>:read|write` bearer for a vault they're ASSIGNED to, for
+    // scripts / headless clients that can't do browser OAuth. The handler
+    // enforces session → assignment → scope-cap (never `:admin`, never a
+    // vault outside the assignment, never a broader verb than the role
+    // grants) + CSRF + per-user rate limit. Must precede the `/account/`
+    // match below (more specific prefix). See `account-vault-token.ts`.
+    if (pathname.startsWith("/account/vault-token/")) {
+      if (!getDb) return dbNotConfigured();
+      if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
+      const vaultName = decodeURIComponent(pathname.slice("/account/vault-token/".length));
+      const db = getDb();
+      const hubOrigin = resolveIssuer(req, db, configuredIssuer);
+      return handleAccountVaultTokenPost(req, vaultName, { db, hubOrigin });
+    }
+
     // /account/ — friend-facing user home (multi-user Phase 1 follow-up).
     // Companion to the first-admin gate on `/admin/host-admin-token`: a
     // signed-in non-admin (friend) lands here instead of bouncing against

package/src/hub.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { brandMarkSvg, CANONICAL_TAGLINE, WORDMARK_TEXT } from "./brand.ts";
+import { CANONICAL_TAGLINE, WORDMARK_TEXT, brandMarkSvg } from "./brand.ts";
 import { CONFIG_DIR } from "./config.ts";
 import { CSRF_FIELD_NAME } from "./csrf.ts";
 
@@ -84,15 +84,34 @@ function buildHtml({ session }: RenderHubOpts): string {
   const authBlock = session
     ? renderSignedIn(session.displayName, session.csrfToken)
     : renderSignedOut();
-  return HTML_TEMPLATE.replace("<!--AUTH-INDICATOR-->", authBlock);
+  // Gate the verbose discovery sections (Get started / Services / Admin)
+  // and their data-loading script on auth state. A signed-out visitor sees
+  // a clean, minimal landing — brand + tagline + a clear "Sign in" call —
+  // not the hub's service catalog, vault listings, or admin links. The
+  // detail un-gates the moment they sign in (the server already knows auth
+  // state from the session cookie, so this stays a no-JS-required,
+  // session-aware render). Operator feedback from a live multi-user deploy:
+  // the signed-out page exposed too much to anonymous visitors.
+  const body = session ? SIGNED_IN_BODY : SIGNED_OUT_BODY;
+  const script = session ? DISCOVERY_SCRIPT : "";
+  return HTML_TEMPLATE.replace("<!--AUTH-INDICATOR-->", authBlock)
+    .replace("<!--DISCOVERY-BODY-->", body)
+    .replace("<!--DISCOVERY-SCRIPT-->", script);
 }
 
 function renderSignedIn(displayName: string, csrfToken: string): string {
   // Inline POST form so sign-out works without JS. Submit button is
   // styled as a text link via `.auth-signout` so the visual weight
   // matches the surrounding "Signed in as <name>" text.
+  //
+  // The "Account" link is the single breadcrumb to `/account/` — the
+  // self-service home where any signed-in user (admin or invited
+  // member) can change their password, see their vault, and sign out.
+  // Without it, a friend who's been handed credentials has no way to
+  // discover the change-password surface after the first-login prompt.
   return `<div class="auth-indicator">
       <span class="muted">Signed in as <strong>${escapeHtml(displayName)}</strong></span>
+      <a href="/account/" class="auth-account">Account</a>
       <form method="POST" action="/logout" class="auth-signout-form">
         <input type="hidden" name="${CSRF_FIELD_NAME}" value="${escapeAttr(csrfToken)}" />
         <button type="submit" class="auth-signout">Sign out</button>
@@ -203,7 +222,7 @@ const HTML_TEMPLATE = `<!doctype html>
     margin: 0;
     display: inline;
   }
-  .auth-signout, .auth-signin {
+  .auth-signout, .auth-signin, .auth-account {
     background: none;
     border: none;
     padding: 0;
@@ -214,10 +233,10 @@ const HTML_TEMPLATE = `<!doctype html>
     text-decoration-thickness: 1px;
     text-underline-offset: 2px;
   }
-  .auth-signout:hover, .auth-signin:hover {
+  .auth-signout:hover, .auth-signin:hover, .auth-account:hover {
     color: var(--accent-hover);
   }
-  a.auth-signin {
+  a.auth-signin, a.auth-account {
     /* Anchor needs explicit reset since the a element has its own
        color/decoration. */
     border-bottom: none;
@@ -262,6 +281,34 @@ const HTML_TEMPLATE = `<!doctype html>
     font-size: 0.92rem;
     margin: 0 0 1.25rem;
   }
+  /* Signed-out landing: a single centered "Sign in" call under the brand.
+     Minimal by design — the service catalog + admin surfaces stay hidden
+     until the visitor authenticates. */
+  .signed-out-cta {
+    text-align: center;
+    margin-bottom: 0;
+  }
+  .signed-out-lede {
+    color: var(--fg-muted);
+    font-size: 1.05rem;
+    margin: 0 0 1.5rem;
+  }
+  .btn-signin {
+    display: inline-block;
+    background: var(--accent);
+    color: var(--card-bg);
+    font-family: var(--sans);
+    font-size: 1rem;
+    font-weight: 500;
+    text-decoration: none;
+    padding: 0.65rem 1.6rem;
+    border-radius: 8px;
+    transition: background 0.15s ease, transform 0.15s ease;
+  }
+  .btn-signin:hover {
+    background: var(--accent-hover);
+    transform: translateY(-1px);
+  }
   .grid {
     display: grid;
     gap: 1.25rem;
@@ -371,7 +418,22 @@ const HTML_TEMPLATE = `<!doctype html>
     <h1>${WORDMARK_TEXT}</h1>
     <p class="tagline">${CANONICAL_TAGLINE}</p>
   </header>
+<!--DISCOVERY-BODY-->
+  <footer>
+    <a href="/.well-known/parachute.json">discovery</a>
+  </footer>
+</main>
+<!--DISCOVERY-SCRIPT-->
+</body>
+</html>
+`;
 
+// The verbose discovery body — the service catalog, admin surfaces, and the
+// "Get started" CTA. Rendered ONLY for a signed-in visitor (`buildHtml`
+// selects this vs SIGNED_OUT_BODY on `session`). Anonymous visitors get the
+// slim landing below instead, so the hub's internal surface isn't exposed
+// pre-auth.
+const SIGNED_IN_BODY = `
   <section class="section" id="get-started-section" hidden>
     <h2>Get started</h2>
     <p class="section-sub">Jump straight into what you came here for.</p>
@@ -391,12 +453,21 @@ const HTML_TEMPLATE = `<!doctype html>
     <p class="section-sub">Manage this hub — vaults, permissions, tokens.</p>
     <div class="grid" id="admin-grid"></div>
   </section>
+`;
 
-  <footer>
-    <a href="/.well-known/parachute.json">discovery</a>
-  </footer>
-</main>
-<script>
+// The slim signed-out landing. Brand + tagline (in the header above) plus a
+// single clear "Sign in" call — no service catalog, no vault listings, no
+// admin links. Keep it tasteful and minimal; the detail un-gates on sign-in.
+const SIGNED_OUT_BODY = `
+  <section class="section signed-out-cta" id="signed-out-cta">
+    <p class="signed-out-lede">Sign in to reach your vault and the services on this hub.</p>
+    <a href="/login?next=/" class="btn-signin" data-testid="signed-out-signin">Sign in →</a>
+  </section>
+`;
+
+// The data-loading script for the signed-in discovery body. Emitted only
+// when signed in (the signed-out body has nothing for it to populate).
+const DISCOVERY_SCRIPT = `<script>
 (async () => {
   const servicesGrid = document.getElementById('services-grid');
   const adminGrid = document.getElementById('admin-grid');
@@ -607,7 +678,4 @@ const HTML_TEMPLATE = `<!doctype html>
 
   void loadServices();
 })();
-</script>
-</body>
-</html>
-`;
+</script>`;