@openparachute/hub 0.7.6 → 0.7.7-rc.12

package/src/hub-server.ts

@@ -24,15 +24,25 @@
  *   /admin/login, /admin/logout                → 301 → /login, /logout
  *
  *   # Notes-as-app migration Phase 2 (parachute-app design doc §16).
+ *   # `/surface/notes` = the legacy notes-ui mount (existing installs);
+ *   # `/surface/parachute` = the app's surface mount post-W2-12 rename.
  *   /notes, /notes/, /notes/*                  → 301 → /surface/notes[/...]
  *                                                (opt-out via
  *                                                 hub_settings.notes_redirect_disabled)
+ *   /surface/notes[/...]                       → 301 → /surface/parachute[/...]
+ *                                                CONDITIONAL (W2-12, dispatched just
+ *                                                before the generic services proxy):
+ *                                                only when uis{} mounts show
+ *                                                /surface/notes gone + /surface/parachute
+ *                                                present — inert on existing notes-ui
+ *                                                installs (surface-notes-alias.ts)
  *
  *   # Discovery + well-known.
  *   /, /hub.html                               → hub.html (the discovery page)
  *   /.well-known/parachute.json                → built dynamically from services.json
  *   /.well-known/parachute-revocation.json     → revoked-jti list (hub#212 Phase 1)
  *   /.well-known/jwks.json                     → JWKS from hub.db
+ *   /.well-known/parachute-account             → account-door capabilities descriptor (public, H2)
  *   /.well-known/oauth-authorization-server    → RFC 8414 metadata (issuer, endpoints)
  *
  *   # OAuth issuer.
@@ -49,10 +59,15 @@
  *                                                 tokens/grants/user_vaults/invites/
  *                                                 connections sweep, CLI remove,
  *                                                 supervisor restart)
+ *   # /account/* — the Bearer-gated account-door REST facade (Phase 2, H2).
+ *   # account:self:admin OR parachute:host:admin (mutations); +:read (reads).
+ *   /account                      (GET)        → account bootstrap {id,email,door} (Bearer only)
+ *   /account/vaults               (GET/POST)   → list / create vault (create returns vault_token)
+ *   /account/vaults/<name>        (DELETE)     → teardown (wraps /vaults/<name> cascade)
+ *   /account/vaults/<name>/token  (POST)       → per-vault scoped token mint
+ *   /account/vaults/<name>/caps   (GET/PUT)    → read / set the storage cap
  *   /admin/host-admin-token       (GET)        → SPA bearer mint (cookie-gated)
  *   /admin/vault-admin-token/<n>  (GET)        → per-vault bearer mint (cookie-gated)
- *   /admin/agent-token            (GET)        → agent UI bearer mint (cookie-gated)
- *   /admin/channel-token          (GET)        → 301 → /admin/agent-token (legacy; channel→agent rename 2026-06-17)
  *   /admin/module-token/<short>   (GET)        → generic module config-UI bearer mint <short>:admin (cookie-gated)
  *   /api/connections/catalog      (GET)        → events/actions across installed modules (cookie-gated)
  *   /admin/connections            (POST/GET)   → connection provision/list (cookie-gated; POST CSRF-belted)
@@ -106,6 +121,13 @@
  *                                                 (hub#473; reached after a correct
  *                                                 password for a 2FA-enrolled user)
  *   /logout                       (POST)       → end admin session
+ *   /account/session               (GET)        → same-origin boot oracle {signed_in,
+ *                                                 csrf,...} (hub-parity P1); cookie-gated,
+ *                                                 NOT Bearer — mounted ABOVE the
+ *                                                 force-change-password gate below (a pure
+ *                                                 state oracle, so a pre-rotation user can
+ *                                                 still read it to drive the rotation
+ *                                                 ceremony itself)
  *   /account/change-password      (GET + POST) → user self-service change-password
  *                                                 (force-redirect target for users
  *                                                 with password_changed=false; also
@@ -114,8 +136,16 @@
  *                                                 + the per-vault proxy is hard-gated
  *                                                 per-request on password_changed===true
  *                                                 (forceChangePasswordGate); only this
- *                                                 route and /logout stay reachable
+ *                                                 route, /logout, and /account/session
+ *                                                 (P1, also above the gate) stay reachable
  *                                                 pre-rotation.
+ *   /account/token                (POST)       → cookie→account-bearer mint (App
+ *                                                 campaign Phase 2 H1): session cookie →
+ *                                                 short-lived JWT carrying the account
+ *                                                 superset {account:self:admin,
+ *                                                 parachute:host:admin, parachute:host:auth}
+ *                                                 aud="account"; first-admin-gated,
+ *                                                 CSRF + same-origin belt; stateless
  *   /account/2fa                  (GET + POST) → user self-service 2FA enroll/disenroll
  *                                                 (hub#473; QR + backup codes)
  *   /account/vault-token/<name>   (POST)       → friend mints a scoped
@@ -163,7 +193,21 @@ 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 {
+  ACCOUNT_MUTATION_SCOPES,
+  type AccountApiDeps,
+  handleAccountCapabilities,
+  handleAccountCreateVault,
+  handleAccountGetVaultCaps,
+  handleAccountListVaults,
+  handleAccountMintVaultToken,
+  handleAccountRoot,
+  handleAccountSetVaultCaps,
+  requireAnyScope,
+} from "./account-api.ts";
+import { type AccountSessionDeps, handleAccountSession } from "./account-session.ts";
 import { handleAccountSetupGet, handleAccountSetupPost } from "./account-setup.ts";
+import { handleAccountToken } from "./account-token.ts";
 import { handleAccountVaultAdminTokenPost } from "./account-vault-admin-token.ts";
 import { handleAccountVaultTokenPost } from "./account-vault-token.ts";
 import {
@@ -171,7 +215,8 @@ import {
   handleAgentGrants,
   handleOAuthGrantCallback,
 } from "./admin-agent-grants.ts";
-import { handleAgentToken } from "./admin-agent-token.ts";
+
+import { adminAuthErrorResponse } from "./admin-auth.ts";
 import { handleApproveClient, handleDeleteClient, handleGetClient } from "./admin-clients.ts";
 import {
   type ConnectionsDeps,
@@ -295,6 +340,7 @@ import {
 } from "./setup-wizard.ts";
 import { getAllPublicKeys } from "./signing-keys.ts";
 import type { Supervisor } from "./supervisor.ts";
+import { isSurfaceNotesPath, maybeRedirectSurfaceNotes } from "./surface-notes-alias.ts";
 import { handleTwoFactorGet, handleTwoFactorPost } from "./two-factor-handlers.ts";
 import { getUserById, userCount } from "./users.ts";
 import { sanitizePublicOrigin } from "./vault-hub-origin-env.ts";
@@ -2312,27 +2358,6 @@ export function hubFetch(
         }
       }
 
-      // `/channel/*` 301-redirects to `/agent/*` — back-compat for the
-      // 2026-06-17 channel→agent module rename. Operator bookmarks, an
-      // un-upgraded chat/config UI's deep links, and any externally-shared
-      // `/channel/mcp/<name>` URL keep resolving for one release cycle while
-      // the module's canonical mount moves to `/agent`. Method-agnostic, same
-      // shape as the `/notes/*` redirect above (the agent's read-write surface
-      // is its own daemon API, not the hub mount, so a re-issued GET is fine).
-      // Matches `/channel` exactly and any `/channel/...` subpath, but NOT a
-      // longer-prefix module like a hypothetical `/channelthing` — the guard is
-      // exact-or-slash-delimited. Query string is preserved. (The generic
-      // services-proxy fallthrough below would otherwise 404 a `/channel/*`
-      // request once the module self-registers under `/agent`.)
-      if (pathname === "/channel" || pathname.startsWith("/channel/")) {
-        const dest = new URL(req.url);
-        dest.pathname = `/agent${pathname.slice("/channel".length)}`;
-        return new Response("", {
-          status: 301,
-          headers: { location: dest.pathname + dest.search },
-        });
-      }
-
       // CORS preflight for the public OAuth + discovery surface. Browsers
       // issue OPTIONS before any non-simple cross-origin request — third-party
       // SPAs hitting `/oauth/register` (RFC 7591 DCR), `/oauth/token`,
@@ -2812,6 +2837,30 @@ export function hubFetch(
         return new Response(res.body, { status: res.status, headers: merged });
       }
 
+      // GET /.well-known/parachute-account — the account-door capabilities
+      // descriptor (Phase 2, H2). Public, no auth, wildcard CORS (the app pulls
+      // it cross-origin to render honestly per door: billing:false + plans:[] on
+      // self-host means no upgrade UI). See account-api.handleAccountCapabilities.
+      if (pathname === "/.well-known/parachute-account") {
+        const corsHeaders = {
+          "access-control-allow-origin": "*",
+          "access-control-allow-methods": "GET, OPTIONS",
+        };
+        if (req.method === "OPTIONS") {
+          return new Response(null, { status: 204, headers: corsHeaders });
+        }
+        if (!getDb) {
+          return new Response('{"error":"account descriptor unavailable: db not configured"}', {
+            status: 503,
+            headers: { "content-type": "application/json", ...corsHeaders },
+          });
+        }
+        const res = handleAccountCapabilities(req, { db: getDb(), issuer: oauthDeps(req).issuer });
+        const merged = new Headers(res.headers);
+        for (const [k, v] of Object.entries(corsHeaders)) merged.set(k, v);
+        return new Response(res.body, { status: res.status, headers: merged });
+      }
+
       // OAuth surface — every handler return is wrapped in `applyCorsHeaders`
       // so third-party SPAs can fetch these endpoints cross-origin (the entire
       // point of OAuth DCR: arbitrary SPAs register → authorize → exchange
@@ -3001,31 +3050,13 @@ export function hubFetch(
         });
       }
 
-      // Back-compat: the agent module's admin-token mint moved from
-      // `/admin/channel-token` to `/admin/agent-token` in the 2026-06-17
-      // channel→agent rename. 301-redirect the old path so operator bookmarks
-      // + any un-upgraded UI fallback keep working for one release cycle.
-      if (pathname === "/admin/channel-token") {
-        const dest = new URL(req.url);
-        dest.pathname = "/admin/agent-token";
-        return Response.redirect(dest.toString(), 301);
-      }
-
-      if (pathname === "/admin/agent-token") {
-        if (!getDb) return dbNotConfigured();
-        return handleAgentToken(req, {
-          db: getDb(),
-          issuer: oauthDeps(req).issuer,
-        });
-      }
-
       // Generic per-module config-UI bearer mint (2026-06-09 modular-UI
       // architecture, P3). `<short>:admin` for any single-audience module —
       // the admin scope each module-owned config UI needs to call its own
-      // endpoints. Cookie-gated to the first-admin operator, exactly like
-      // /admin/agent-token + /admin/vault-admin-token. Gated on
-      // self-registration (services.json row + readable module.json) with the
-      // bootstrap registries as a fallback (boundary C5) — a genuinely
+      // endpoints. Cookie-gated to the first-admin operator, matching the
+      // host/vault admin-token endpoints. Gated on self-registration
+      // (services.json row + readable module.json) with the bootstrap
+      // registries as a fallback (boundary C5) — a genuinely
       // third-party module mints here with zero hub code changes. Vault is
       // per-instance and routed to /admin/vault-admin-token/<name> instead.
       if (pathname.startsWith("/admin/module-token/")) {
@@ -3043,9 +3074,7 @@ export function hubFetch(
 
       // Note: the legacy `/admin/channels` bespoke vault-channel orchestration
       // endpoint (pre-Connections, hub#624 era) was retired in boundary D1 —
-      // superseded by the general engine below. The agent module's own admin
-      // page (renamed from channel 2026-06-17) drives `/admin/connections` +
-      // `/admin/agent-token`.
+      // superseded by the general engine below.
 
       // Connections — the GENERAL module event→action engine (2026-06-09
       // modular-UI architecture, P5). `/api/connections/catalog` (GET) returns
@@ -3348,7 +3377,7 @@ export function hubFetch(
       // the 2026-06-09 modular-UI architecture P3. Config is module-owned +
       // hub-framed now: the Modules page "Configure" action opens the module's
       // OWN config UI (`configUiUrl`), which mints its admin Bearer from the
-      // cookie-gated `/admin/module-token/<short>` (or `/admin/agent-token`).
+      // cookie-gated `/admin/module-token/<short>`.
 
       // Per-module action endpoints: /api/modules/:short/{install,restart,upgrade,uninstall}.
       if (pathname.startsWith("/api/modules/")) {
@@ -3699,6 +3728,20 @@ export function hubFetch(
         return new Response("method not allowed", { status: 405 });
       }
 
+      // /account/session — the same-origin boot oracle (hub-parity P1). A
+      // PURE STATE ORACLE, not a mutating surface, so it is mounted ABOVE the
+      // force-change-password gate immediately below: a pre-rotation user
+      // must still be able to read `{signed_in, csrf}` to drive the rotation
+      // ceremony itself, rather than get walled off before it can even ask.
+      // `/account/token` (below the gate) stays gated — a pre-rotation user
+      // hits its 403 `force_change_password` there instead. See
+      // `account-session.ts`.
+      if (pathname === "/account/session") {
+        if (!getDb) return dbNotConfigured();
+        const sessionDeps: AccountSessionDeps = { db: getDb() };
+        return handleAccountSession(req, sessionDeps);
+      }
+
       // Per-request force-change-password gate (P0-1 / hub#469). CHOKE POINT 1:
       // every `/account/*` route BELOW this line is gated. `/logout` and
       // `/account/change-password` (the rotation/exit path) ran above and already
@@ -3721,6 +3764,27 @@ export function hubFetch(
         if (gate) return gate;
       }
 
+      // /account/token — cookie→account-bearer mint (Parachute App campaign,
+      // Phase 2 H1). POST-only. Exchanges the `parachute_hub_session` cookie for
+      // a short-lived JWT carrying the account superset
+      // {account:self:admin, parachute:host:admin, parachute:host:auth} with
+      // aud="account" — the same-origin app's bootstrap into holding the account
+      // credential (it never touches /oauth/authorize, so never hits consent).
+      // First-admin-gated (account ≡ box), CSRF double-submit + the same-origin
+      // Origin belt below. Stateless (no tokens row); revocation = logout.
+      if (pathname === "/account/token") {
+        if (!getDb) return dbNotConfigured();
+        // Origin belt (hub#632 posture): a cookie-authed POST mint gets the
+        // strict same-origin check as defense-in-depth over the body's CSRF
+        // token. A Bearer-authed caller (none expected here) would bypass the
+        // belt but still fail the cookie-only session gate inside the handler.
+        {
+          const rejected = assertSameOriginForCookieMutation(req, oauthDeps(req).hubBoundOrigins());
+          if (rejected) return rejected;
+        }
+        return handleAccountToken(req, { db: getDb(), issuer: oauthDeps(req).issuer });
+      }
+
       // /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
@@ -3777,6 +3841,115 @@ export function hubFetch(
         });
       }
 
+      // ====================================================================
+      // /account/* — the Bearer-gated account-door REST facade (Phase 2, H2).
+      // The normalized account API both doors mount (the hosted cloud door
+      // mounts the twin). Bearer-authed, machine-to-machine — no session
+      // cookie — so these precede the session-cookie `/account/vault-token/`
+      // + `/account/` HTML routes below. Mutations accept account:self:admin
+      // OR parachute:host:admin; reads also accept account:self:read. See
+      // `account-api.ts`.
+      // ====================================================================
+      if (pathname === "/account/vaults") {
+        if (!getDb) return dbNotConfigured();
+        const accountDeps: AccountApiDeps = {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
+          manifestPath,
+        };
+        if (req.method === "GET") return handleAccountListVaults(req, accountDeps);
+        if (req.method === "POST") return handleAccountCreateVault(req, accountDeps);
+        return new Response("method not allowed", { status: 405 });
+      }
+      if (pathname.startsWith("/account/vaults/")) {
+        if (!getDb) return dbNotConfigured();
+        const rest = pathname.slice("/account/vaults/".length);
+        const accountDeps: AccountApiDeps = {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
+          manifestPath,
+        };
+        // POST /account/vaults/<name>/token — per-vault scoped token mint.
+        if (rest.endsWith("/token")) {
+          const name = decodeURIComponent(rest.slice(0, -"/token".length));
+          return handleAccountMintVaultToken(req, name, accountDeps);
+        }
+        // GET/PUT /account/vaults/<name>/caps — read / set the storage cap.
+        if (rest.endsWith("/caps")) {
+          const name = decodeURIComponent(rest.slice(0, -"/caps".length));
+          if (req.method === "GET") return handleAccountGetVaultCaps(req, name, accountDeps);
+          if (req.method === "PUT") return handleAccountSetVaultCaps(req, name, accountDeps);
+          return new Response("method not allowed", { status: 405 });
+        }
+        // DELETE /account/vaults/<name> — teardown via the full identity
+        // cascade. Gate with the account-scope set here (accept account:self:admin
+        // OR parachute:host:admin), then delegate to `handleDeleteVault`, which
+        // re-gates parachute:host:admin — the superset account token carries it,
+        // so this is belt-and-suspenders, not a second authorization.
+        if (req.method === "DELETE") {
+          const name = decodeURIComponent(rest);
+          if (!name || name.includes("/")) return new Response("not found", { status: 404 });
+          try {
+            await requireAnyScope(
+              getDb(),
+              req,
+              ACCOUNT_MUTATION_SCOPES,
+              oauthDeps(req).hubBoundOrigins(),
+            );
+          } catch (err) {
+            return adminAuthErrorResponse(err);
+          }
+          const services = readManifestLenient(manifestPath).services;
+          const agentEntry = findServiceByShort(services, "agent");
+          const agentOrigin = agentEntry ? `http://127.0.0.1:${agentEntry.port}` : null;
+          const resolveVaultOrigin = (vaultName: string): string | null => {
+            const match = findVaultUpstream(
+              readManifestLenient(manifestPath).services,
+              `/vault/${vaultName}`,
+            );
+            return match ? `http://127.0.0.1:${match.port}` : null;
+          };
+          const supervisor = deps?.supervisor;
+          return handleDeleteVault(req, name, {
+            db: getDb(),
+            issuer: oauthDeps(req).issuer,
+            knownIssuers: oauthDeps(req).hubBoundOrigins(),
+            manifestPath,
+            connectionsStorePath:
+              deps?.connectionsStorePath ?? join(CONFIG_DIR, "connections.json"),
+            agentOrigin,
+            resolveVaultOrigin,
+            resolveModuleOrigin: makeResolveModuleOrigin(manifestPath),
+            ...(supervisor
+              ? {
+                  restartVaultModule: async () => {
+                    await supervisor.restart("vault");
+                  },
+                }
+              : {}),
+          });
+        }
+        return new Response("method not allowed", { status: 405 });
+      }
+      // GET /account (Bearer) — account bootstrap {id,email,door} (the
+      // door-contract's AccountBootstrap). Only intercepts when an
+      // Authorization header is present, so the cookie-authed HTML account
+      // home at `/account`/`/account/` below stays unaffected.
+      if (
+        (pathname === "/account" || pathname === "/account/") &&
+        req.headers.get("authorization")
+      ) {
+        if (!getDb) return dbNotConfigured();
+        return handleAccountRoot(req, {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          knownIssuers: oauthDeps(req).hubBoundOrigins(),
+          manifestPath,
+        });
+      }
+
       // /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
@@ -3967,6 +4140,28 @@ export function hubFetch(
       // `/`, `/admin/*`, `/oauth/*`, `/.well-known/*`, `/hub/*`, `/vault/*`,
       // `/api/*` are excluded by ordering, not by an explicit denylist (#182).
       //
+      // W2-12 — conditional `/surface/notes/*` → `/surface/parachute/*`
+      // alias, the "never 404 an old bookmark after an in-place upgrade"
+      // safety net for the app's notes→parachute surface-identity rename.
+      // Fires ONLY when the manifest's `uis{}` sub-units show the legacy
+      // `/surface/notes` mount gone AND a `/surface/parachute` mount
+      // present (see surface-notes-alias.ts for the full condition +
+      // inert-today proof). On every existing notes-ui install the
+      // condition fails and dispatch falls through to the generic proxy
+      // below unchanged. Reads the same lenient manifest source
+      // `resolveUiMount` consumes — hoisted to one read shared by both.
+      const manifestServices = readManifestLenient(manifestPath).services;
+      if (isSurfaceNotesPath(pathname)) {
+        const aliasTarget = maybeRedirectSurfaceNotes(pathname, url.search, manifestServices);
+        if (aliasTarget !== undefined) {
+          logNotesRedirect(pathname, aliasTarget);
+          return new Response("", {
+            status: 301,
+            headers: { location: aliasTarget },
+          });
+        }
+      }
+
       // H3 — per-UI audience gate. When the path falls under a declared UI
       // sub-unit (a `uis{}` entry on the matched service row — surface-hosted
       // UI mounts like /surface/<name>/*), the sub-unit's audience is
@@ -3981,7 +4176,7 @@ export function hubFetch(
       // which also means a 'surface'/'public' mount on a loopback-only row
       // stays unreachable from tailnet/funnel: exposure is orthogonal to
       // audience.
-      const uiMatch = resolveUiMount(readManifestLenient(manifestPath).services, pathname);
+      const uiMatch = resolveUiMount(manifestServices, pathname);
       if (uiMatch) {
         const cloaked =
           effectivePublicExposure(uiMatch.entry) === "loopback" &&

package/src/hub-settings.ts

@@ -92,6 +92,16 @@ export type HubSettingKey =
   // the deprecation window. Stored as the literal string "true" /
   // "false"; any other value parses as "redirect on" (the migration
   // default — operators must opt out, not opt in).
+  //
+  // Mount vocabulary post-W2-12: `/surface/notes` is the LEGACY notes-ui
+  // mount (what existing installs serve — this redirect's target);
+  // `/surface/parachute` is the app's surface mount under its renamed
+  // identity. A separate CONDITIONAL alias (surface-notes-alias.ts, no
+  // hub_settings row — it keys off the manifest's uis{} mounts) bridges
+  // `/surface/notes/*` → `/surface/parachute/*` only on installs where
+  // the legacy mount is gone and the new one exists, so the two
+  // redirects compose for post-rename installs: /notes/x →
+  // /surface/notes/x → /surface/parachute/x.
   | "notes_redirect_disabled"
   // Admin-UI screen-lock PIN (hub admin-lock feature). The argon2id hash of
   // the operator's lock PIN. Absent row = lock feature OFF (today's behavior
@@ -122,7 +132,21 @@ export type HubSettingKey =
   // wizard funnel + pre-admin 503 lockout run BEFORE this redirect, so a
   // not-yet-set-up hub still lands on setup, not a surface that can't work
   // yet.
-  | "root_redirect";
+  | "root_redirect"
+  // hub-parity P2 (Q2): the RAW token of the newest PUBLIC (multi-use,
+  // `max_uses > 1`) invite — persisted so `GET /.well-known/parachute-account`
+  // can advertise `signup_path` without being able to reconstruct it from the
+  // `invites` table (which stores only `sha256(token)`, see invites.ts's
+  // module doc). Written by `api-invites.ts`'s `handleCreateInvite` right
+  // after a successful multi-use `issueInvite`; read (and lazily cleared once
+  // stale) by `invites.ts`'s `activePublicSignupPath`.
+  //
+  // This does NOT weaken the hash-only posture of single-use friend invites
+  // (`max_uses === 1`, the default) — those NEVER write this row. A
+  // multi-use link is, by construction, the operator's deliberately PUBLIC
+  // signup page (minted to broadcast), so persisting its raw token is no
+  // more sensitive than the link itself already being handed out widely.
+  | "public_signup_token";
 
 export type SetupExposeMode = "localhost" | "tailnet" | "public";
 

package/src/hub.ts

@@ -541,43 +541,76 @@ const DISCOVERY_SCRIPT = `<script>
   /**
    * Render the "Get started" section (hub#342) above the Services grid.
    *
-   * One hardcoded target, conditional on its prerequisite being installed:
-   *   - "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)
+   * Driven by the uis[] sub-unit arrays the well-known doc already carries
+   * (W2-12 — retires the hardcoded "Open Notes" → /surface/notes/ tile):
+   * one tile per ACTIVE uis[] entry across every services[] row, each
+   * carrying its own displayName + tagline + mount path. Under the app's
+   * notes→parachute surface-identity rename this stays correct whichever
+   * mount an install serves — an existing notes-ui install renders its
+   * "notes" entry at /surface/notes, a post-rename install renders its
+   * "parachute" entry at /surface/parachute, no hub-side name knowledge
+   * required. Entries named "parachute" / "notes" sort first (they're the
+   * end-user "browse my content" CTA — the audience that needs the
+   * strongest above-the-fold prompt); the rest follow alphabetically.
    *
-   * The earlier "Browse Vault" tile retired in workstream C (2026-05-25)
-   * once vault declared uiUrl in its module.json (per patterns#96). With
-   * the multi-instance prefix lifted into buildWellKnown, every vault
-   * instance now renders its own tile in the Services grid below — one
-   * per instance, with the actual instance name in the discovery doc
-   * rather than a hub-side guess at "first vault."
-   *
-   * Notes stays here because Notes is the end-user CTA (the audience
-   * that needs the strongest above-the-fold prompt); the Services grid
-   * positions it equally with admin tiles, which underweights the
-   * "browse my content" path for a returning operator.
+   * Legacy fallback: a surface-host row that predates uis{}
+   * self-registration carries no uis[] even while it serves notes-ui at
+   * /surface/notes (the hub proxies /surface/* blind — mounts are
+   * surface-host's on-disk state, not the manifest's). When no uis[]
+   * entries exist anywhere but parachute-surface IS installed, keep
+   * rendering the pre-W2-12 "Open Notes" tile so those installs' discovery
+   * page is untouched. The fallback dies naturally the first time the
+   * surface-host re-registers with uis{}.
    *
-   * If the prerequisite is not met (fresh install pre-wizard, no app)
-   * the section stays hidden. The hardcoded shape mirrors the wizard's
-   * own done-screen "Start using your vault" tile — same architectural
-   * shape (single obvious entry point) at a different surface.
+   * The earlier "Browse Vault" tile retired in workstream C (2026-05-25)
+   * once vault declared uiUrl in its module.json (per patterns#96) — vault
+   * instances render in the Services grid below.
    *
-   * Not driven by /api/modules because discovery is unauth — the
-   * services list from /.well-known/parachute.json is sufficient
-   * (it carries the same install-detection signal we need, no
-   * Bearer required).
+   * If nothing qualifies (fresh install pre-wizard, no app) the section
+   * stays hidden. Not driven by /api/modules because discovery is unauth —
+   * the services list from /.well-known/parachute.json is sufficient (it
+   * carries the uis[] fan-out, no Bearer required).
    */
   function renderGetStarted(services) {
     if (!getStartedGrid || !getStartedSection) return;
-    const tiles = [];
-    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: '/surface/notes/',
-      });
+    const uiEntries = [];
+    const seenPaths = new Set();
+    for (const svc of services) {
+      if (!svc || !Array.isArray(svc.uis)) continue;
+      for (const ui of svc.uis) {
+        if (!ui || typeof ui.path !== 'string' || ui.path === '') continue;
+        // Absent status means active (services-manifest.ts UiSubUnitStatus).
+        if (ui.status && ui.status !== 'active') continue;
+        // Multi-path parent rows repeat the same uis[] on every path —
+        // de-duplicate by mount (well-known.ts's documented consumer duty).
+        if (seenPaths.has(ui.path)) continue;
+        seenPaths.add(ui.path);
+        uiEntries.push(ui);
+      }
+    }
+    const rank = (ui) => (ui.name === 'parachute' ? 0 : ui.name === 'notes' ? 1 : 2);
+    uiEntries.sort(
+      (a, b) =>
+        rank(a) - rank(b) ||
+        (a.displayName || a.name || '').localeCompare(b.displayName || b.name || ''),
+    );
+    const tiles = uiEntries.map((ui) => ({
+      title: ui.displayName || ui.name || ui.path,
+      desc: ui.tagline || '',
+      // Trailing slash keeps relative asset URLs resolving under the mount
+      // (same reason the retired hardcode pointed at /surface/notes/).
+      href: ui.path.endsWith('/') ? ui.path : ui.path + '/',
+    }));
+    if (tiles.length === 0) {
+      // Legacy fallback (see docstring): pre-uis surface-host installs.
+      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: '/surface/notes/',
+        });
+      }
     }
     if (tiles.length === 0) {
       getStartedSection.setAttribute('hidden', '');

package/src/invites.ts

@@ -57,6 +57,7 @@
  */
 import type { Database } from "bun:sqlite";
 import { createHash, randomBytes } from "node:crypto";
+import { deleteSetting, getSetting } from "./hub-settings.ts";
 
 /** Default invite lifetime — long enough to deliver out-of-band (no email), short enough to bound a leaked link. */
 export const DEFAULT_INVITE_TTL_SECONDS = 7 * 24 * 60 * 60;
@@ -502,3 +503,44 @@ export function revokeInvitesForVault(
     .run(now.toISOString(), vaultName);
   return Number(res.changes);
 }
+
+/**
+ * Q2 (hub-parity P2) — the account descriptor's conditional `signup_path`.
+ * The hub cannot derive a redemption URL from the `invites` table (only
+ * `sha256(token)` is stored, never the raw value — see the module doc), so
+ * this reads back the ONE raw token persisted at mint time for a
+ * deliberately PUBLIC (multi-use) invite (`api-invites.ts`'s
+ * `handleCreateInvite`, which writes `hub_settings.public_signup_token`
+ * after `issueInvite` when `maxUses > 1`) and re-validates it's still live.
+ *
+ * Returns `/account/setup/<token>` when the persisted invite is still
+ * `"pending"`, still multi-use (`maxUses > 1`), AND provisioning
+ * (`provisionVault` — each redeemer gets their own new vault); `null` on ANY
+ * miss (never set, redeemed, revoked, exhausted, expired, or a non-provisioning
+ * shared-vault link) — and lazily clears the stale setting in that case. No
+ * separate revoke/exhaust/expire hook is needed: `inviteStatus` already derives
+ * all four terminal states from the invite's own columns, so every miss flows
+ * through this one status check.
+ *
+ * The `maxUses > 1` AND `provisionVault` re-checks are defense-in-depth mirrors
+ * of `handleCreateInvite`'s write condition (which only persists for a
+ * multi-use provisioning link): even a hand-edited settings row pointing at a
+ * single-use OR a shared-vault (`provision_vault=false`) invite must never be
+ * advertised as public signup — a shared-vault link would leak team-vault write
+ * on the anonymous, wildcard-CORS descriptor.
+ */
+export function activePublicSignupPath(db: Database, now: Date = new Date()): string | null {
+  const raw = getSetting(db, "public_signup_token");
+  if (!raw) return null;
+  const invite = findInviteByRawToken(db, raw);
+  if (
+    !invite ||
+    inviteStatus(invite, now) !== "pending" ||
+    invite.maxUses <= 1 ||
+    !invite.provisionVault
+  ) {
+    deleteSetting(db, "public_signup_token");
+    return null;
+  }
+  return `/account/setup/${encodeURIComponent(raw)}`;
+}

package/src/module-ops-client.ts

@@ -376,7 +376,8 @@ export async function fetchModuleStates(deps: DriveModuleOpDeps): Promise<Module
   try {
     res = await doFetch(`${baseUrl}/api/modules`, {
       method: "GET",
-      // `/api/modules` parses the scheme-cased `Bearer ` prefix; match it exactly.
+      // `/api/modules` parses the Bearer scheme case-insensitively (RFC 7235,
+      // V1.4/C1.3 parity); we still emit the canonical `Bearer ` prefix.
       headers: { authorization: `Bearer ${bearer}` },
       // Bound the read so a wedged hub handler degrades `status` rather than
       // hanging it. AbortSignal.timeout fires `AbortError` once the ceiling