@openparachute/hub 0.5.13 → 0.5.14-rc.2

package/src/chrome-strip.ts

@@ -13,7 +13,7 @@
  * (above that threshold the response is almost certainly not an HTML shell
  * anyway — SPA index.html files are < 16 KB in this ecosystem).
  *
- * Opt-out: hub-side path-prefix deny list. The Notes PWA at `/app/notes/*`
+ * Opt-out: hub-side path-prefix deny list. The Notes PWA at `/surface/notes/*`
  * is the canonical opt-out — it owns its own chrome (see design-system §7
  * "Where NOT to inject" + AUDIT §4: "Notes is the proof this can work: own
  * application, looks distinctively Notes, reads as Parachute because the
@@ -22,7 +22,7 @@
  * Why path-based and not module-declared:
  *   - Notes is a `uis[]` sub-unit of parachute-app, not its own module —
  *     adding `chrome: "off"` to parachute-app's module.json would suppress
- *     chrome on `/app/admin/*` too (wrong: that surface SHOULD get chrome).
+ *     chrome on `/surface/admin/*` too (wrong: that surface SHOULD get chrome).
  *   - The per-uis well-known fan-out (workstream C/4) is in flight but the
  *     hub side doesn't yet thread per-uis metadata into proxy dispatch.
  *   - HTML meta-tag peeking adds parsing overhead on every response.
@@ -46,10 +46,10 @@ import { CSRF_FIELD_NAME, ensureCsrfToken } from "./csrf.ts";
  * prefix" or "pathname startsWith prefix" — the same shape as
  * `findServiceUpstream`'s mount comparison.
  *
- * `/app/notes/` covers the Notes PWA bundled by parachute-app. Notes is a
+ * `/surface/notes/` covers the Notes PWA bundled by parachute-app. Notes is a
  * destination, not chrome; it owns its own header (see design-system.md §7).
  */
-export const CHROME_OPT_OUT_PREFIXES: readonly string[] = ["/app/notes/"];
+export const CHROME_OPT_OUT_PREFIXES: readonly string[] = ["/surface/notes/"];
 
 /**
  * Buffer size cap. Responses larger than this are passed through unchanged.
@@ -208,8 +208,8 @@ function renderSignedOutCluster(nextPath: string): string {
  * when any opt-out prefix matches (`pathname === prefix` or
  * `pathname startsWith prefix`).
  *
- * Match shape mirrors `findServiceUpstream` so an opt-out for `"/app/notes/"`
- * suppresses chrome for `/app/notes`, `/app/notes/`, and every sub-path.
+ * Match shape mirrors `findServiceUpstream` so an opt-out for `"/surface/notes/"`
+ * suppresses chrome for `/surface/notes`, `/surface/notes/`, and every sub-path.
  */
 export function shouldInjectChrome(
   pathname: string,

package/src/commands/install.ts

@@ -1,8 +1,8 @@
-import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { createConnection } from "node:net";
-import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { autoWireScribeAuth } from "../auto-wire.ts";
+import { bunGlobalPrefixes, isLinked as defaultIsLinkedShared } from "../bun-link.ts";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import {
   type ModuleManifest,
@@ -260,25 +260,12 @@ async function defaultRunner(cmd: readonly string[]): Promise<number> {
   return await proc.exited;
 }
 
-function bunGlobalPrefixes(): string[] {
-  const prefixes: string[] = [];
-  const fromEnv = process.env.BUN_INSTALL;
-  if (fromEnv) prefixes.push(join(fromEnv, "install", "global", "node_modules"));
-  prefixes.push(join(homedir(), ".bun", "install", "global", "node_modules"));
-  return prefixes;
-}
-
-function defaultIsLinked(pkg: string): boolean {
-  for (const prefix of bunGlobalPrefixes()) {
-    const path = join(prefix, ...pkg.split("/"));
-    try {
-      if (lstatSync(path).isSymbolicLink()) return true;
-    } catch {
-      // Not present at this prefix; try the next.
-    }
-  }
-  return false;
-}
+// `bunGlobalPrefixes` + `defaultIsLinked` were extracted to `src/bun-link.ts`
+// so the wizard's parallel install path (`api-modules-ops.ts:runInstall`) can
+// reuse the same detection — the two paths diverging is the bug class hub#433
+// fixed (smoke 2026-05-27, finding 1). `defaultIsLinkedShared` is imported at
+// module scope; alias kept for the in-function local-shadow convention below.
+const defaultIsLinked = defaultIsLinkedShared;
 
 function defaultLinkedPath(pkg: string): string | null {
   // bun has two install shapes for "linked-style" globals:

package/src/commands/status.ts

@@ -56,9 +56,18 @@ export async function probe(
   try {
     const res = await fetchImpl(url, { signal: controller.signal });
     const latencyMs = Math.round(performance.now() - start);
+    // A 401 is the service replying "I'm up but this endpoint requires auth"
+    // — that's strictly healthy from a liveness perspective. Vault's
+    // canonical health path `/vault/<name>/health` is auth-gated; without
+    // this carve-out, `parachute status` shows vault as "failing" on every
+    // fresh install (first impression UX disaster despite vault being fine).
+    // 5xx → unhealthy; 200-class → healthy; 401 → healthy + auth-gated.
+    // Other 4xx (404 / 400 / etc.) still count as unhealthy — those mean
+    // the configured health path doesn't exist or is shaped wrong.
+    const healthy = res.ok || res.status === 401;
     return {
       entry,
-      healthy: res.ok,
+      healthy,
       statusCode: res.status,
       latencyMs,
     };

package/src/help.ts

@@ -82,7 +82,7 @@ Environment:
 
 Examples:
   parachute install vault                                   # installs, runs init, starts vault
-  parachute install app                                     # installs app (auto-bootstraps Notes)
+  parachute install surface                                 # installs surface (auto-bootstraps Notes)
   parachute install notes                                   # back-compat: legacy notes-daemon (Phase 2 deprecating)
   parachute install scribe                                  # installs, prompts for provider, starts scribe
   parachute install scribe --scribe-provider groq --scribe-key gsk_…
@@ -188,7 +188,7 @@ Example:
   parachute-vault  1940  0.2.4    active  12345  2h 13m  2ms      bun-linked → parachute-vault @ 8aa167b
     → http://127.0.0.1:1940/vault/default/mcp
   parachute-app    1946  0.2.0    active  12346  2h 12m  3ms      npm (0.2.0-rc.4)
-    → http://127.0.0.1:1946/app/notes
+    → http://127.0.0.1:1946/surface/notes
 `;
 }
 

package/src/hub-db.ts

@@ -278,6 +278,48 @@ const MIGRATIONS: readonly Migration[] = [
       UPDATE clients SET same_hub = 0;
     `,
   },
+  {
+    version: 10,
+    sql: `
+      -- Multi-user Phase 2 PR 2 (hub#252 follow-up, design
+      -- 2026-05-20-multi-user-phase-1.md §Phase 2). Lifts the single
+      -- \`users.assigned_vault TEXT\` column into a many-to-many
+      -- \`user_vaults\` table so one user can have access to multiple
+      -- vaults (e.g. a personal vault + a family-shared vault).
+      --
+      -- Schema:
+      --   * (user_id, vault_name) composite PK — one row per (user, vault).
+      --     ON DELETE CASCADE on user_id so user deletion drops the
+      --     assignments without us having to clean up manually.
+      --   * \`role\` TEXT DEFAULT 'write' — reserved for forward-compat per-
+      --     vault role granularity. Phase 1 had no role model; this column
+      --     gives later PRs a column to land scope-narrowing in without a
+      --     second migration. All backfilled rows default to 'write'.
+      --   * index on \`vault_name\` for the inverse lookup ("who has access
+      --     to vault X?") — useful when admin removes a vault and we want
+      --     to warn about pinned users.
+      --
+      -- Backfill: every existing row in \`users\` with a non-null
+      -- \`assigned_vault\` becomes a single (user_id, vault_name) row in
+      -- \`user_vaults\`. Rows with NULL \`assigned_vault\` (admin posture)
+      -- get no \`user_vaults\` entry — they remain "no narrowing" per
+      -- vaultScopeForUser semantics. After backfill the \`assigned_vault\`
+      -- column is dropped.
+      CREATE TABLE user_vaults (
+        user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+        vault_name TEXT NOT NULL,
+        role TEXT NOT NULL DEFAULT 'write',
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (user_id, vault_name)
+      );
+      CREATE INDEX user_vaults_vault ON user_vaults (vault_name);
+      INSERT INTO user_vaults (user_id, vault_name, role, created_at)
+      SELECT id, assigned_vault, 'write', created_at
+      FROM users
+      WHERE assigned_vault IS NOT NULL;
+      ALTER TABLE users DROP COLUMN assigned_vault;
+    `,
+  },
 ];
 
 export function openHubDb(path: string = hubDbPath()): Database {

package/src/hub-server.ts

@@ -23,7 +23,7 @@
  *   /admin/login, /admin/logout                → 301 → /login, /logout
  *
  *   # Notes-as-app migration Phase 2 (parachute-app design doc §16).
- *   /notes, /notes/, /notes/*                  → 301 → /app/notes[/...]
+ *   /notes, /notes/, /notes/*                  → 301 → /surface/notes[/...]
  *                                                (opt-out via
  *                                                 hub_settings.notes_redirect_disabled)
  *
@@ -65,6 +65,7 @@
  *   /api/users                    (GET + POST) → list / create user (host:admin)
  *   /api/users/vaults             (GET)        → vault-name list for assigned-vault picker (host:admin)
  *   /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
  *   /logout                       (POST)       → end admin session
  *   /account/change-password      (GET + POST) → user self-service change-password
@@ -117,7 +118,11 @@ import {
 import { handleHostAdminToken } from "./admin-host-admin-token.ts";
 import { handleVaultAdminToken } from "./admin-vault-admin-token.ts";
 import { handleCreateVault } from "./admin-vaults.ts";
-import { handleAccountChangePasswordGet, handleAccountChangePasswordPost } from "./api-account.ts";
+import {
+  handleAccountChangePasswordGet,
+  handleAccountChangePasswordPost,
+  handleAccountHomeGet,
+} from "./api-account.ts";
 import { handleApiHub } from "./api-hub.ts";
 import { handleApiMe } from "./api-me.ts";
 import { handleApiMintToken } from "./api-mint-token.ts";
@@ -141,6 +146,8 @@ import {
   handleDeleteUser,
   handleListUsers,
   handleListVaults,
+  handleResetUserPassword,
+  handleUpdateUserVaults,
 } from "./api-users.ts";
 import { buildChromeForRequest, injectChromeIntoResponse } from "./chrome-strip.ts";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "./config.ts";
@@ -266,10 +273,7 @@ export function parseArgs(argv: string[], env: NodeJS.ProcessEnv = process.env):
   if (hostname === undefined) hostname = env.PARACHUTE_BIND_HOST || "127.0.0.1";
   if (wellKnownDir === undefined) wellKnownDir = WELL_KNOWN_DIR;
   if (issuer === undefined) {
-    const fromEnv =
-      env.PARACHUTE_HUB_ORIGIN ??
-      env.RENDER_EXTERNAL_URL ??
-      flyDefaultOrigin(env);
+    const fromEnv = env.PARACHUTE_HUB_ORIGIN ?? env.RENDER_EXTERNAL_URL ?? flyDefaultOrigin(env);
     if (fromEnv) issuer = fromEnv.replace(/\/+$/, "") || undefined;
   }
   return { port, hostname, wellKnownDir, dbPath: dbPath ?? hubDbPath(), issuer };
@@ -1118,8 +1122,7 @@ export function hubFetch(
           // browser POSTs and must be trusted even when the operator's
           // configured issuer points elsewhere. See origin-check.ts
           // jsdoc for the failure case this closes.
-          platformOrigin:
-            process.env.RENDER_EXTERNAL_URL ?? flyDefaultOrigin(process.env),
+          platformOrigin: process.env.RENDER_EXTERNAL_URL ?? flyDefaultOrigin(process.env),
         }),
     };
   };
@@ -1199,7 +1202,7 @@ export function hubFetch(
     }
 
     // Notes-as-app migration Phase 2 (parachute-app design doc §16).
-    // `/notes/*` 301-redirects to `/app/notes/*` so legacy bookmarks land on
+    // `/notes/*` 301-redirects to `/surface/notes/*` so legacy bookmarks land on
     // the apps-hosted Notes. Default-on; operators on notes-as-module-only
     // installs can opt out via `hub_settings.notes_redirect_disabled = true`
     // (see hub-settings.ts). The opt-out exists so a legacy operator
@@ -1908,6 +1911,44 @@ export function hubFetch(
         manifestPath,
       });
     }
+    // Phase 2 PR 1 — `/api/users/:id/reset-password` (admin-initiated
+    // password reset for non-admin users). Routed BEFORE the per-id DELETE
+    // catch-all so the trailing `/reset-password` segment isn't mistaken
+    // for part of a user id. Same `host:admin` Bearer gate as the other
+    // /api/users surfaces.
+    {
+      const resetMatch = pathname.match(/^\/api\/users\/([^/]+)\/reset-password$/);
+      if (resetMatch) {
+        if (!getDb) return dbNotConfigured();
+        const id = decodeURIComponent(resetMatch[1] ?? "");
+        if (!id) {
+          return new Response("not found", { status: 404 });
+        }
+        return handleResetUserPassword(req, id, {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          manifestPath,
+        });
+      }
+    }
+    // Phase 2 PR 2 — `/api/users/:id/vaults` (replace a user's vault
+    // assignments). Routed before the per-id DELETE catch-all so the
+    // trailing `/vaults` segment isn't mistaken for part of a user id.
+    {
+      const vaultsMatch = pathname.match(/^\/api\/users\/([^/]+)\/vaults$/);
+      if (vaultsMatch) {
+        if (!getDb) return dbNotConfigured();
+        const id = decodeURIComponent(vaultsMatch[1] ?? "");
+        if (!id) {
+          return new Response("not found", { status: 404 });
+        }
+        return handleUpdateUserVaults(req, id, {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          manifestPath,
+        });
+      }
+    }
     if (pathname.startsWith("/api/users/")) {
       if (!getDb) return dbNotConfigured();
       const id = decodeURIComponent(pathname.slice("/api/users/".length));
@@ -1961,6 +2002,24 @@ export function hubFetch(
       return new Response("method not allowed", { status: 405 });
     }
 
+    // /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
+    // a 403 wall on the admin SPA. Admin users also land here when they
+    // hit `/account/` directly, with a "you're the administrator → /admin/"
+    // exit ramp. Bare `/account` 301-redirects to `/account/` so links
+    // without the trailing slash work.
+    if (pathname === "/account" || pathname === "/account/") {
+      if (req.method !== "GET") return new Response("method not allowed", { status: 405 });
+      if (pathname === "/account") {
+        return new Response(null, { status: 301, headers: { location: "/account/" } });
+      }
+      if (!getDb) return dbNotConfigured();
+      const db = getDb();
+      const hubOrigin = resolveIssuer(req, db, configuredIssuer);
+      return handleAccountHomeGet(req, { db, hubOrigin });
+    }
+
     // Legacy `/admin/config` (server-rendered module-config portal, #46)
     // retired post-SPA-rework. 301 → the SPA home so any bookmark or stale
     // post-login redirect lands somewhere useful. The route stays here in
@@ -2032,7 +2091,7 @@ export function hubFetch(
  * Inject the persistent chrome strip (workstream G) into a proxied response.
  *
  * Skips the rewrite when the response is non-200, non-HTML, on an opt-out
- * path (e.g. `/app/notes/*`), or larger than `MAX_INJECT_SIZE_BYTES`.
+ * path (e.g. `/surface/notes/*`), or larger than `MAX_INJECT_SIZE_BYTES`.
  * `injectChromeIntoResponse` is the no-side-effects implementation; this
  * wrapper threads in the session-aware chrome HTML and a `set-cookie`
  * append when a fresh CSRF cookie was minted.

package/src/hub-settings.ts

@@ -71,7 +71,7 @@ export type HubSettingKey =
   | "hub_origin"
   // Notes-as-app migration Phase 2 (parachute-app design doc §16).
   // When unset (default) or "false", hub serves a 301 redirect from
-  // `/notes/*` → `/app/notes/*` so existing bookmarks transparently
+  // `/notes/*` → `/surface/notes/*` so existing bookmarks transparently
   // follow the operator to the apps-hosted Notes. When "true", the
   // redirect is skipped and `/notes/*` falls through to the existing
   // services.json-driven proxy — the escape hatch for operators
@@ -372,7 +372,7 @@ export function setHubOrigin(db: Database, value: string | null): void {
 // --- domain helpers: notes-as-app redirect (parachute-app §16 Phase 2) ----
 
 /**
- * Read whether the `/notes/*` → `/app/notes/*` redirect is disabled. Default
+ * Read whether the `/notes/*` → `/surface/notes/*` redirect is disabled. Default
  * is `false` (redirect on) — Phase 2 migrates operators to apps-hosted
  * Notes, so the bookmark-friendly path is the default-on behavior. Only an
  * operator running notes-as-a-module without parachute-app installed should

package/src/hub.ts

@@ -471,9 +471,9 @@ const HTML_TEMPLATE = `<!doctype html>
    * Render the "Get started" section (hub#342) above the Services grid.
    *
    * One hardcoded target, conditional on its prerequisite being installed:
-   *   - "Open Notes" → /app/notes/  (requires parachute-app installed;
-   *     App auto-bootstraps Notes-as-UI per parachute-app §17, so the
-   *     mere presence of App means /app/notes/ is live)
+   *   - "Open Notes" → /surface/notes/  (requires parachute-surface installed;
+   *     Surface auto-bootstraps Notes-as-UI per parachute-surface §17, so the
+   *     mere presence of Surface means /surface/notes/ is live)
    *
    * The earlier "Browse Vault" tile retired in workstream C (2026-05-25)
    * once vault declared uiUrl in its module.json (per patterns#96). With
@@ -500,12 +500,12 @@ const HTML_TEMPLATE = `<!doctype html>
   function renderGetStarted(services) {
     if (!getStartedGrid || !getStartedSection) return;
     const tiles = [];
-    const hasApp = services.some((s) => s && s.name === 'parachute-app');
-    if (hasApp) {
+    const hasSurface = services.some((s) => s && s.name === 'parachute-surface');
+    if (hasSurface) {
       tiles.push({
         title: 'Open Notes',
         desc: 'Browse + capture in the Notes app — reads from your vault.',
-        href: '/app/notes/',
+        href: '/surface/notes/',
       });
     }
     if (tiles.length === 0) {

package/src/notes-redirect.ts

@@ -2,9 +2,9 @@
  * Notes-as-app migration Phase 2 (parachute-app design doc §16).
  *
  * When parachute-app ships and Notes installs as `parachute-app add
- * @openparachute/notes-ui --name notes --path /app/notes`, operators with
+ * @openparachute/notes-ui --name notes --path /surface/notes`, operators with
  * existing `/notes/*` bookmarks need a transparent bridge. The hub serves a
- * 301 redirect from `/notes/*` → `/app/notes/*` so:
+ * 301 redirect from `/notes/*` → `/surface/notes/*` so:
  *
  *   - cached operator URLs (notes PWA install banners, browser history,
  *     in-vault links) keep working
@@ -44,14 +44,14 @@ export function isLegacyNotesPath(pathname: string): boolean {
  * string. The query is preserved verbatim; the fragment isn't visible
  * server-side (clients reassemble it after following the redirect).
  *
- * The transform is purely path-rewrite — `/notes` → `/app/notes`, `/notes/`
- * → `/app/notes/`, `/notes/foo/bar` → `/app/notes/foo/bar`.
+ * The transform is purely path-rewrite — `/notes` → `/surface/notes`, `/notes/`
+ * → `/surface/notes/`, `/notes/foo/bar` → `/surface/notes/foo/bar`.
  */
 export function buildNotesRedirectTarget(pathname: string, search: string): string {
   // Slice off the leading "/notes" — what remains is either "" (bare /notes),
   // "/" (trailing slash), or "/<rest>" (sub-path).
   const tail = pathname.slice("/notes".length);
-  return `/app/notes${tail}${search}`;
+  return `/surface/notes${tail}${search}`;
 }
 
 /**