@openparachute/hub 0.5.13 → 0.5.14-rc.1

package/src/api-account.ts

@@ -48,6 +48,8 @@
 import type { Database } from "bun:sqlite";
 import { hash as argonHash } from "@node-rs/argon2";
 import { type ChangePasswordMode, renderChangePassword } from "./account-change-password-ui.ts";
+import { renderAccountHome } from "./account-home-ui.ts";
+import { POST_LOGIN_DEFAULT } from "./admin-handlers.ts";
 import { renderAdminError } from "./admin-login-ui.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
 import { changePasswordRateLimiter } from "./rate-limit.ts";
@@ -57,6 +59,7 @@ import {
   PASSWORD_MAX_LEN,
   UserNotFoundError,
   getUserById,
+  isFirstAdmin,
   validatePassword,
   verifyPassword,
 } from "./users.ts";
@@ -69,12 +72,10 @@ export interface ApiAccountDeps {
 
 /**
  * Where to land after a successful password change when no `next` param
- * is present. Matches `POST_LOGIN_DEFAULT` in `admin-handlers.ts` — the
- * admin SPA's vault list. Kept as a local const (not imported) so this
- * file doesn't accidentally couple to admin-handlers' internals; if the
- * default ever diverges the two should reconcile via a shared config.
+ * is present. Re-exported from `admin-handlers.ts` so login + change-
+ * password share a single source of truth (reviewer fold on hub#425).
  */
-const POST_CHANGE_DEFAULT = "/admin/vaults";
+const POST_CHANGE_DEFAULT = POST_LOGIN_DEFAULT;
 
 function safeNext(raw: string | null | undefined): string {
   if (!raw) return POST_CHANGE_DEFAULT;
@@ -234,7 +235,20 @@ export async function handleAccountChangePasswordPost(
   const currentPassword = String(form.get("current_password") ?? "");
   const newPassword = String(form.get("new_password") ?? "");
   const confirmPassword = String(form.get("new_password_confirm") ?? "");
-  const next = safeNext(String(form.get("next") ?? ""));
+  // Friend-facing redirect: non-admin users who would otherwise land in the
+  // admin SPA (because POST_CHANGE_DEFAULT = /admin/vaults) get bounced to
+  // /account/ directly. Without this, the SPA loads, hits 403 on its host-
+  // admin-token mint, then redirects to /account/ via the SPA's auth.ts —
+  // a visible two-hop flash for the friend. The login-redirect path
+  // (admin-handlers.ts:118) does the same rewrite at sign-in time; this
+  // mirrors it for the change-password POST. (hub#425 reviewer fold —
+  // operator runbook accuracy: the doc said "lands at /account/", but
+  // without this fix the user briefly sees the admin shell.)
+  const rawNext = safeNext(String(form.get("next") ?? ""));
+  const next =
+    !isFirstAdmin(deps.db, user.id) && (rawNext === "/admin" || rawNext.startsWith("/admin/"))
+      ? "/account/"
+      : rawNext;
   const mode = modeFor(user.passwordChanged);
 
   // Rate-limit gate (hub#282). Fires *after* CSRF (so a junk cross-site
@@ -437,6 +451,58 @@ export async function handleAccountChangePasswordPost(
   });
 }
 
+/**
+ * GET /account/ — friend-facing user home (multi-user Phase 1 follow-up).
+ *
+ * Companion surface to the first-admin gate on
+ * `/admin/host-admin-token`: friend users who can't reach the admin
+ * SPA need a coherent landing page that shows their assigned vault, a
+ * sign-out form, and a link to rotate their password. The admin lands
+ * here too (via the SPA's 403 redirect path) but mostly bounces back
+ * to `/admin/` immediately — for admins this is a "wait, what?" exit
+ * ramp.
+ *
+ * Auth: requires an active session. Session-less requests 302 to
+ * `/login?next=/account/` — same posture as `handleAccountChangePasswordGet`.
+ *
+ * `hubOrigin` is passed in by the route handler (resolved per-request
+ * via `resolveIssuer` in `hub-server.ts`). The page uses it to build
+ * the canonical Notes "Open" CTA URL and to show as inline code in
+ * the "use a custom client" disclosure.
+ */
+export interface AccountHomeDeps extends ApiAccountDeps {
+  /** Canonical hub origin for this request (e.g. `https://my-hub.example`). */
+  hubOrigin: string;
+}
+
+export function handleAccountHomeGet(req: Request, deps: AccountHomeDeps): Response {
+  const session = findActiveSession(deps.db, req);
+  if (!session) {
+    return redirect(`/login?next=${encodeURIComponent("/account/")}`);
+  }
+  const user = getUserById(deps.db, session.userId);
+  if (!user) {
+    // Stale session pointing at a deleted user — hand back to /login;
+    // the orphaned session row will time out on its own.
+    return redirect("/login");
+  }
+  const adminFlag = isFirstAdmin(deps.db, user.id);
+  const csrf = ensureCsrfToken(req);
+  const extra: Record<string, string> = csrf.setCookie ? { "set-cookie": csrf.setCookie } : {};
+  return htmlResponse(
+    renderAccountHome({
+      username: user.username,
+      assignedVault: user.assignedVault,
+      passwordChanged: user.passwordChanged,
+      hubOrigin: deps.hubOrigin,
+      isFirstAdmin: adminFlag,
+      csrfToken: csrf.token,
+    }),
+    200,
+    extra,
+  );
+}
+
 /**
  * Flip `users.password_changed` from 0 to 1 for the given user.
  * Idempotent — running against an already-`true` row is a no-op.

package/src/api-modules.ts

@@ -88,7 +88,7 @@ export const API_MODULES_REQUIRED_SCOPE = "parachute:host:auth";
  * the pre-app architecture; scribe + runner come last because they
  * depend on a working vault + app to be useful).
  */
-export const CURATED_MODULES = ["vault", "app", "notes", "scribe", "runner"] as const;
+export const CURATED_MODULES = ["vault", "surface", "notes", "scribe", "runner"] as const;
 export type CuratedModuleShort = (typeof CURATED_MODULES)[number];
 
 export interface ApiModulesDeps {
@@ -385,8 +385,8 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
         //     (e.g. `/vault/default` + `/admin/` → `/vault/default/admin/`).
         //   - Single-instance modules (app, scribe, runner) declare a
         //     full hub-origin path that ALREADY includes the mount
-        //     (e.g. `/app/admin/`, `/scribe/admin`); the mount must NOT
-        //     be prepended again or the result is `/app/app/admin/`
+        //     (e.g. `/surface/admin/`, `/scribe/admin`); the mount must NOT
+        //     be prepended again or the result is `/app/surface/admin/`
         //     (the audit bug caught 2026-05-25 on the SPA's Services
         //     dropdown).
         // Detect by checking if candidate is already mount-prefixed.

package/src/api-users.ts

@@ -9,18 +9,23 @@
  *
  * Surfaces:
  *
- *   GET    /api/users             list users (host:admin)
- *   POST   /api/users             create user (host:admin)
- *   DELETE /api/users/:id         hard-delete user (host:admin)
- *   GET    /api/users/vaults      vault-name list for the assigned-vault
- *                                 dropdown (host:admin)
+ *   GET    /api/users                       list users (host:admin)
+ *   POST   /api/users                       create user (host:admin)
+ *   DELETE /api/users/:id                   hard-delete user (host:admin)
+ *   POST   /api/users/:id/reset-password    admin password reset (host:admin)
+ *   GET    /api/users/vaults                vault-name list for the
+ *                                           assigned-vault dropdown
+ *                                           (host:admin)
  *
  * Wire shape is snake_case (matches `/api/grants`, `/api/auth/tokens`).
  * Responses never include `password_hash` — hashes never leave the DB.
  *
- * Phase 1 deliberately ships only list / create / delete. Editing a user
- * (reassign vault, reset password) is Phase 2 work — Phase 1's admin
- * recovery shape is "delete + re-create" per the design doc's §6.
+ * Phase 1 shipped list / create / delete. Phase 2 PR 1 adds admin
+ * password reset (this file's `handleResetUserPassword`) — the highest-
+ * pain operator UX gap from Phase 1 was "friend forgot their password
+ * → operator has to delete+recreate," which is destructive-feeling
+ * even though vaults are independent of accounts. Reassign-vault and
+ * other edits land in later Phase 2 PRs.
  *
  * Auth: every endpoint requires a bearer token carrying the
  * `parachute:host:admin` scope. Same gate as `/api/grants`, `/vaults`,
@@ -45,9 +50,12 @@ import {
   UsernameTakenError,
   createUser,
   deleteUser,
+  getFirstAdminId,
   getUserById,
   getUserByUsernameCI,
+  isFirstAdmin,
   listUsers,
+  resetUserPassword,
   validatePassword,
   validateUsername,
 } from "./users.ts";
@@ -324,10 +332,13 @@ export async function handleDeleteUser(
   // by a state conflict — RFC 7231 §6.5.3 fits cleaner than §6.5.8.
   // Either is defensible; the wire `error` string is the part the SPA
   // matches on for the "first admin can't be deleted" surface).
-  const firstAdminRow = deps.db
-    .query<{ id: string }, []>("SELECT id FROM users ORDER BY created_at ASC LIMIT 1")
-    .get();
-  if (firstAdminRow && firstAdminRow.id === userId) {
+  //
+  // The `getFirstAdminId` helper (users.ts) is the single source of
+  // truth for "who is the admin" — same SELECT also gates the SPA
+  // bearer-mint endpoint (admin-host-admin-token.ts) and drives the
+  // non-admin login-redirect default.
+  const firstAdminId = getFirstAdminId(deps.db);
+  if (firstAdminId && firstAdminId === userId) {
     return jsonError(
       403,
       "first_admin_undeletable",
@@ -381,6 +392,156 @@ export async function handleListVaults(req: Request, deps: ApiUsersDeps): Promis
   });
 }
 
+// ---------------------------------------------------------------------------
+// POST /api/users/:id/reset-password — admin-initiated password reset
+// ---------------------------------------------------------------------------
+
+interface ResetPasswordBody {
+  new_password: string;
+}
+
+async function parseResetPasswordBody(
+  req: Request,
+): Promise<{ ok: true; body: ResetPasswordBody } | ParseErr> {
+  const ctype = req.headers.get("content-type") ?? "";
+  if (!ctype.toLowerCase().includes("application/json")) {
+    return {
+      ok: false,
+      status: 400,
+      error: "invalid_request",
+      description: "Content-Type must be application/json",
+    };
+  }
+  let raw: unknown;
+  try {
+    raw = await req.json();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      status: 400,
+      error: "invalid_request",
+      description: `invalid JSON body: ${msg}`,
+    };
+  }
+  if (!raw || typeof raw !== "object") {
+    return {
+      ok: false,
+      status: 400,
+      error: "invalid_request",
+      description: "request body must be a JSON object",
+    };
+  }
+  const obj = raw as Record<string, unknown>;
+  const newPassword = obj.new_password;
+  if (typeof newPassword !== "string" || newPassword.length === 0) {
+    return {
+      ok: false,
+      status: 400,
+      error: "invalid_request",
+      description: '"new_password" must be a non-empty string',
+    };
+  }
+  // Same CPU-DoS cap as `parseCreateBody` — bound the payload BEFORE
+  // argon2id touches it. 413 (request entity too large) is the canonical
+  // RFC 7231 status for "body fits, but a specific field exceeds policy."
+  if (newPassword.length > PASSWORD_MAX_LEN) {
+    return {
+      ok: false,
+      status: 413,
+      error: "password_too_long",
+      description: `password length must be ≤ ${PASSWORD_MAX_LEN} characters`,
+    };
+  }
+  return { ok: true, body: { new_password: newPassword } };
+}
+
+/**
+ * POST /api/users/:id/reset-password — admin sets a new temp password
+ * for a non-admin user. The user is force-redirected through
+ * `/account/change-password` on next sign-in (same rail as admin-created
+ * users), so the admin's chosen value is genuinely a "temporary one-
+ * time handoff" string rather than a long-lived password.
+ *
+ * Order of checks (mirrors `handleDeleteUser` for the first-admin gate
+ * and `handleCreateUser` for the parse / validate pipeline):
+ *
+ *   1. Method gate (405 on non-POST).
+ *   2. Bearer carries `parachute:host:admin` (401 / 403 via `requireScope`).
+ *   3. Parse + cap body (400 on shape, 413 on > PASSWORD_MAX_LEN).
+ *   4. Target user exists (404 `not_found`).
+ *   5. Target is NOT the first admin (403 `cannot_reset_first_admin`).
+ *      Admin self-service uses `/account/change-password`; admin-reset
+ *      is for friends only. Mirrors the first-admin-undeletable rail.
+ *   6. `validatePassword(new_password)` (400 `invalid_password`).
+ *   7. `resetUserPassword` — rotates hash, flips `password_changed=0`,
+ *      revokes the user's still-active tokens, all in one tx.
+ *
+ * Response on success: `200 { ok: true, user: <wire shape> }`. We
+ * deliberately don't echo the password — the admin already typed it
+ * and will hand it to the friend out-of-band (Signal, in-person —
+ * same as the create-user default-password flow).
+ */
+export async function handleResetUserPassword(
+  req: Request,
+  userId: string,
+  deps: ApiUsersDeps,
+): Promise<Response> {
+  if (req.method !== "POST") {
+    return jsonError(405, "method_not_allowed", "use POST");
+  }
+  try {
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+  } catch (err) {
+    return adminAuthErrorResponse(err as AdminAuthError);
+  }
+  const parsed = await parseResetPasswordBody(req);
+  if (!parsed.ok) {
+    return jsonError(parsed.status, parsed.error, parsed.description);
+  }
+  const target = getUserById(deps.db, userId);
+  if (!target) {
+    return jsonError(404, "not_found", `no user with id "${userId}"`);
+  }
+  // First-admin protection. The earliest-created row is the wizard or
+  // env-seeded admin by construction (Phase 1 has no role model). Reset
+  // by admin would be a self-action — the admin should use the normal
+  // `/account/change-password` rotate flow instead, which requires
+  // knowing the current password (genuine credential rotation, not a
+  // recovery reset). Pairs with the first-admin-undeletable rail above.
+  if (isFirstAdmin(deps.db, userId)) {
+    return jsonError(
+      403,
+      "cannot_reset_first_admin",
+      "the first admin must use /account/change-password directly — admin password reset is for friend accounts",
+    );
+  }
+  const validity = validatePassword(parsed.body.new_password);
+  if (!validity.valid) {
+    return jsonError(
+      400,
+      "invalid_password",
+      "password must be at least 12 characters (passphrase-friendly; no complexity rules)",
+    );
+  }
+  // `resetUserPassword` is idempotent on a missing row — returns false
+  // when the target vanished between `getUserById` and this call. Same
+  // race-tolerant 404 as `handleDeleteUser` for that path.
+  const ok = await resetUserPassword(deps.db, userId, parsed.body.new_password);
+  if (!ok) {
+    return jsonError(404, "not_found", `no user with id "${userId}"`);
+  }
+  console.log(`password reset by admin: id=${userId} username=${target.username}`);
+  // Re-read so the response carries the updated `password_changed=false`
+  // + bumped `updated_at`. Cheap (single SELECT). Saves the SPA a refetch
+  // to see the row's "pending first login" badge come back.
+  const fresh = getUserById(deps.db, userId);
+  return new Response(JSON.stringify({ ok: true, user: fresh ? toWire(fresh) : null }), {
+    status: 200,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
 function describeUsernameReason(reason: "format" | "length" | "reserved"): string {
   switch (reason) {
     case "length":

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/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-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,7 @@ import {
   handleDeleteUser,
   handleListUsers,
   handleListVaults,
+  handleResetUserPassword,
 } from "./api-users.ts";
 import { buildChromeForRequest, injectChromeIntoResponse } from "./chrome-strip.ts";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "./config.ts";
@@ -266,10 +272,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 +1121,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 +1201,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 +1910,26 @@ 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,
+        });
+      }
+    }
     if (pathname.startsWith("/api/users/")) {
       if (!getDb) return dbNotConfigured();
       const id = decodeURIComponent(pathname.slice("/api/users/".length));
@@ -1961,6 +1983,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 +2072,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}`;
 }
 
 /**