@openparachute/hub 0.6.5-rc.8 → 0.7.1

package/src/origin-check.ts

@@ -29,6 +29,7 @@
  * case. CSRF + session gates upstream are the real auth defense — this is
  * a belt for browser flows where the legitimate Origin/Referer got dropped.
  */
+import { parseSessionCookie } from "./sessions.ts";
 
 /**
  * Build the bound-origin set from the hub's configuration. Returns
@@ -161,3 +162,111 @@ export function isSameOriginRequest(req: Request, boundOrigins: readonly string[
   }
   return false;
 }
+
+// ===========================================================================
+// CSRF belt for cookie-gated /admin/* JSON mutation endpoints (hub#632,
+// 2026-06-09 hub-module-boundary Phase C1)
+// ===========================================================================
+
+/** Methods the belt gates. GET/HEAD/OPTIONS are read-shaped and pass. */
+const MUTATION_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+
+/**
+ * Strict same-origin belt for cookie-authenticated JSON mutations — the
+ * defense-in-depth layer over `SameSite=Lax` on the hub's cookie-gated JSON
+ * mutation endpoints (hub#632; hub-module-boundary charter, trust statement).
+ *
+ * BELTED ENDPOINTS (the explicit enumeration — every cookie-gated JSON
+ * mutation under `/admin/*`; keep this list in sync with the dispatch in
+ * `hub-server.ts`):
+ *
+ *   - `POST /admin/connections` + `DELETE /admin/connections/<id>` +
+ *     `POST /admin/connections/<id>/approve`
+ *     (connection provision/teardown/claim-approval — the seam's canonical
+ *     consumers are channel's admin page and the hub SPA, both same-origin
+ *     `fetch()` with `credentials: "include"`. The Bearer-authed
+ *     `/<id>/renew` + `/<id>/claim` siblings pass the belt via the
+ *     Authorization carve-out below.)
+ *
+ * (The legacy `POST/DELETE /admin/channels` pair was belted here until
+ * boundary D1 retired the endpoint — superseded by `/admin/connections`.)
+ *
+ * NOT belted, and why:
+ *   - GET/HEAD/OPTIONS — read-shaped; the mint GETs
+ *     (`/admin/host-admin-token`, `/admin/channel-token`,
+ *     `/admin/module-token/<short>`, `/admin/vault-admin-token/<name>`)
+ *     enforce GET-only with a 405 and their response bodies are unreadable
+ *     cross-origin (no CORS on these routes).
+ *   - Bearer-authed requests — a cross-site page cannot attach an
+ *     `Authorization` header without a CORS preflight these routes never
+ *     approve, so a request carrying one is not a browser CSRF. The
+ *     downstream auth gate still validates the credential; this belt sits
+ *     only on the cookie path.
+ *   - Server-rendered form posts (`/login`, `/logout`, `/admin/setup/*`,
+ *     `/oauth/authorize` approve) — already carry the double-submit CSRF
+ *     token (`csrf.ts`) and/or `isSameOriginRequest`; not double-gated here.
+ *   - `/vaults` (POST) + `/vaults/<name>` (DELETE) — Bearer
+ *     `parachute:host:admin` gated, CSRF-immune.
+ *   - `/api/*` — Bearer-gated. `/oauth/*` — spec-shaped, own protections.
+ *
+ * Stricter than `isSameOriginRequest` ON PURPOSE: no Referer fallback and —
+ * critically — no Host-header fallback. The Host fallback exists for
+ * server-rendered form flows where the double-submit token is the real
+ * defense and headers got proxy-stripped (#245). These JSON endpoints carry
+ * NO token, so a Host fallback would be a genuine bypass: an attacker form
+ * post under `referrer-policy: no-referrer` arrives with `Origin: null` and
+ * no Referer, and the Host header always names the target. Browsers send a
+ * real `Origin` on every non-GET `fetch()` (same-origin included — default
+ * `mode: "cors"` is exempt from referrer-policy Origin masking), so every
+ * legitimate consumer of these endpoints passes tier 1. `Origin: null` and
+ * malformed values are affirmative mismatches; a missing header on a
+ * cookie-authed mutation is rejected with its own error code
+ * (`csrf_origin_required`) naming the fix (send Origin, or use a Bearer).
+ *
+ * Returns `null` when the request may proceed, or a 403 JSON `Response`
+ * when the belt rejects. Rejections are logged (method, path, origin — no
+ * cookies, no tokens).
+ */
+export function assertSameOriginForCookieMutation(
+  req: Request,
+  boundOrigins: readonly string[],
+): Response | null {
+  if (!MUTATION_METHODS.has(req.method.toUpperCase())) return null;
+  // Authorization present → not a browser CSRF (custom headers require a
+  // CORS preflight no /admin/* route approves). The endpoint's own gate
+  // validates the credential — API clients with Bearers never see the belt.
+  if (req.headers.get("authorization")) return null;
+  // No session cookie → no ambient credential to ride; the endpoint's own
+  // gate returns its usual 401. Presence is enough here — a forged/stale
+  // session id fails downstream regardless of what the belt decides.
+  if (!parseSessionCookie(req.headers.get("cookie"))) return null;
+
+  const pathname = new URL(req.url).pathname;
+  const origin = req.headers.get("origin");
+  if (!origin) {
+    console.warn(`csrf belt: rejected cookie-authed ${req.method} ${pathname} — no Origin header`);
+    return csrfBeltError(
+      "csrf_origin_required",
+      "cookie-authenticated mutations require an Origin header matching the hub origin; browser fetch() sends it automatically — non-browser clients should authenticate with a Bearer token instead",
+    );
+  }
+  if (origin !== "null") {
+    try {
+      if (new Set(boundOrigins).has(new URL(origin).origin)) return null;
+    } catch {
+      // Malformed Origin — fall through to the mismatch rejection.
+    }
+  }
+  console.warn(`csrf belt: rejected cookie-authed ${req.method} ${pathname} — origin=${origin}`);
+  return csrfBeltError(
+    "csrf_origin_mismatch",
+    "request Origin does not match this hub's origin — cross-site mutations are not allowed on cookie-authenticated endpoints",
+  );
+}
+
+function csrfBeltError(code: string, description: string): Response {
+  return new Response(JSON.stringify({ error: code, error_description: description }), {
+    status: 403,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}

package/src/proxy-error-ui.ts

@@ -47,7 +47,7 @@ export const TRANSIENT_MAX_ATTEMPTS = 5;
 export const ADMIN_MODULES_URL = "/admin/modules";
 
 /** JSON error vocabulary. Matches the snake_case shape used elsewhere
- * in the hub's API (`api-modules-config.ts` etc.) for consistency. */
+ * in the hub's API (`api-modules.ts` etc.) for consistency. */
 export const ERROR_TYPE_TRANSIENT = "upstream_starting";
 export const ERROR_TYPE_PERSISTENT = "upstream_unreachable";
 

package/src/service-spec.ts

@@ -1,5 +1,5 @@
 import { fileURLToPath } from "node:url";
-import { type ModuleManifest, readModuleManifest } from "./module-manifest.ts";
+import { type ModuleFocus, type ModuleManifest, readModuleManifest } from "./module-manifest.ts";
 import type { ServiceEntry } from "./services-manifest.ts";
 
 /**
@@ -126,8 +126,8 @@ export interface FirstPartyExtras {
  * The CLI prefers the installed module's own `.parachute/module.json` when
  * present and falls back to this embedded manifest otherwise. The plan is
  * to delete each fallback as its upstream module starts shipping the real
- * file — see the `// FALLBACK: Delete when ...` markers below for the
- * specific upstream reference per entry.
+ * file — see the `// FALLBACK: Delete when ...` marker below for the
+ * specific upstream reference.
  *
  * Third-party modules never have a fallback; they ship `module.json` or
  * the install hard-errors.
@@ -260,7 +260,10 @@ export function composeServiceSpec(opts: {
 //
 // As of 2026-05-21 (hub#310), vault / scribe / runner have all retired their
 // FALLBACK entries: each ships `module.json` AND self-registers its
-// services.json row at boot (vault#356, scribe#50, runner#3). Hub reads the
+// services.json row at boot (vault#356, scribe#50, runner#3). Channel
+// followed in the 2026-06-09 hub-module-boundary migration (D3) — it ships
+// `.parachute/module.json` and self-registers (channel#34 era), so its
+// vendored manifest retired to a KNOWN_MODULES row. Hub reads the
 // canonical fields from services.json (operator-authoritative) and falls
 // through to `<installDir>/.parachute/module.json` when a lifecycle command
 // needs a static manifest. The `KNOWN_MODULES` registry below carries just
@@ -272,11 +275,10 @@ export function composeServiceSpec(opts: {
 // What remains in FIRST_PARTY_FALLBACKS:
 //   - notes: still a frontend with a hub-side static-serve shim (`notes-serve.ts`)
 //     — its startCmd is composed from the services.json entry's port + mount,
-//     which is hub-side logic, not something notes itself runs.
-//   - channel: exploration tier; may retire before it ever ships module.json,
-//     so the vendored fallback is fine.
+//     which is hub-side logic, not something notes itself runs. (The archive
+//     isn't done — notes-daemon Phase 3 retirement hasn't landed.)
 //
-// Both remaining entries keep their "FALLBACK: Delete when …" markers so the
+// The remaining entry keeps its "FALLBACK: Delete when …" marker so the
 // next cleanup pass is a one-grep operation.
 // ---------------------------------------------------------------------------
 
@@ -314,44 +316,24 @@ const NOTES_FALLBACK: FirstPartyFallback = {
   },
 };
 
-// FALLBACK: Delete when @openparachute/channel ships .parachute/module.json
-// (parachute-channel repo: file follow-up after parachute-hub#56 lands;
-// channel is exploration tier — may be retired before module.json ships).
-const CHANNEL_FALLBACK: FirstPartyFallback = {
-  package: "@openparachute/channel",
-  manifest: {
-    name: "channel",
-    manifestName: "parachute-channel",
-    displayName: "Channel",
-    tagline: "Notification fan-out across modules.",
-    port: 1941,
-    paths: ["/channel"],
-    health: "/channel/health",
-    startCmd: ["parachute-channel", "daemon"],
-  },
-  extras: {
-    hasAuth: true,
-  },
-};
-
 /**
  * Vendored manifests + extras for first-party modules that still need them.
  * Indexed by short name (the `parachute install <X>` token).
  *
- * Only notes + channel remain — see the block comment above for the rationale
- * (vault/scribe/runner now self-register and ship their own module.json).
- * Other code paths consult both this table AND `KNOWN_MODULES` (which carries
- * the post-self-register-retirement entries) via the helpers in this file
- * (`shortNameForManifest`, `knownServices`, …).
+ * Only notes remains — see the block comment above for the rationale
+ * (vault/scribe/runner/channel now self-register and ship their own
+ * module.json). Other code paths consult both this table AND `KNOWN_MODULES`
+ * (which carries the post-self-register-retirement entries) via the helpers
+ * in this file (`shortNameForManifest`, `knownServices`, …).
  */
 export const FIRST_PARTY_FALLBACKS: Record<string, FirstPartyFallback> = {
   notes: NOTES_FALLBACK,
-  channel: CHANNEL_FALLBACK,
 };
 
 /**
  * Minimal install-time registry for first-party modules whose FALLBACK has
- * retired (vault / scribe / runner as of hub#310). Hub uses this for:
+ * retired (vault / scribe / runner as of hub#310; channel as of the
+ * 2026-06-09 hub-module-boundary migration, D3). Hub uses this for:
  *
  *   1. **Install bootstrap**: mapping `parachute install <short>` to the npm
  *      package to `bun add -g`. Pre-install there's no module.json on disk
@@ -475,6 +457,31 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
       hasAuth: true,
     },
   },
+  channel: {
+    short: "channel",
+    package: "@openparachute/channel",
+    manifestName: "parachute-channel",
+    canonicalPort: 1941,
+    displayName: "Channel",
+    // Mirrors channel's own module.json (the canonical fields below do too —
+    // keep in sync if channel's declaration changes). The retired FALLBACK's
+    // copy ("Notification fan-out across modules.", health "/channel/health",
+    // startCmd ["parachute-channel", "daemon"]) predated channel's
+    // module.json + self-registration and had drifted on all three.
+    tagline: "Chat with your Claude Code sessions — a channel per session.",
+    canonicalPaths: ["/channel"],
+    canonicalHealth: "/health",
+    canonicalStripPrefix: true,
+    extras: {
+      // Backward-compat startCmd for rows without installDir — same rationale
+      // as scribe / vault / runner. The bare binary IS the daemon (channel's
+      // package.json bin maps `parachute-channel` → src/daemon.ts); the old
+      // vendored `["parachute-channel", "daemon"]` subcommand is stale.
+      startCmd: () => ["parachute-channel"],
+      // Channel gates its endpoints behind hub-issued JWTs (channel:* scopes).
+      hasAuth: true,
+    },
+  },
   surface: {
     short: "surface",
     package: "@openparachute/surface",
@@ -625,6 +632,66 @@ export function knownServices(): string[] {
   return [...Object.keys(FIRST_PARTY_FALLBACKS), ...Object.keys(KNOWN_MODULES)];
 }
 
+/**
+ * Default discovery tier per short name (2026-06-09 modular-UI architecture).
+ * The hub PREFERS a module's manifest-declared `focus`; this map is the
+ * fallback when `module.json` omits it (and the bootstrap value before a
+ * module is installed). vault / scribe / hub / surface are `core`; everything
+ * else (channel / runner / notes / unknown third-party) defaults to
+ * `experimental`. **Show all; never hide** — `focus` only groups + labels.
+ */
+const FOCUS_DEFAULTS: Record<string, ModuleFocus> = {
+  vault: "core",
+  scribe: "core",
+  hub: "core",
+  surface: "core",
+  channel: "experimental",
+  runner: "experimental",
+  notes: "experimental",
+};
+
+/**
+ * Resolve a short name's discovery tier. When `declared` (the module's
+ * `module.json` `focus`) is present it wins; otherwise fall back to
+ * `FOCUS_DEFAULTS`, defaulting any unlisted short to `experimental`. Never
+ * returns undefined — the Modules screen always has a tier to group by.
+ */
+export function focusForShort(short: string, declared?: ModuleFocus): ModuleFocus {
+  if (declared !== undefined) return declared;
+  return FOCUS_DEFAULTS[short] ?? "experimental";
+}
+
+/**
+ * The set of short names the hub knows how to discover, display, and install
+ * from its bootstrap registries — `KNOWN_MODULES` ∪ `FIRST_PARTY_FALLBACKS`.
+ * This is the SELF-REGISTRATION-driven discovery surface that replaces the old
+ * `CURATED_MODULES` whitelist (2026-06-09 modular-UI architecture, P2): every
+ * module the hub can resolve a package/manifest for is discoverable + installable,
+ * regardless of `focus` tier. Deduped, with FIRST_PARTY_FALLBACKS shorts first
+ * (notes) then KNOWN_MODULES (vault / scribe / runner / channel / surface).
+ *
+ * `notes` is intentionally included — it's still resolvable (vendored fallback)
+ * for legacy installs; it surfaces as `experimental` and isn't pushed as a
+ * fresh install. Callers that want only the "recommended fresh-install" subset
+ * can filter by `focus === "core"`.
+ */
+export function discoverableShorts(): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const short of [...Object.keys(FIRST_PARTY_FALLBACKS), ...Object.keys(KNOWN_MODULES)]) {
+    if (seen.has(short)) continue;
+    seen.add(short);
+    out.push(short);
+  }
+  return out;
+}
+
+/** True iff `short` is a module the hub can resolve a package/manifest for
+ *  (the install-path gate, replacing the `CURATED_MODULES` whitelist). */
+export function isKnownModuleShort(short: string): boolean {
+  return short in FIRST_PARTY_FALLBACKS || short in KNOWN_MODULES;
+}
+
 /**
  * Canonical port assignment for a known short name, or `undefined` for
  * third-party services we don't have a fallback for. Drives the
@@ -656,12 +723,12 @@ export function canonicalPortForManifest(manifestName: string): number | undefin
 /**
  * Resolve the runtime spec for a known short name.
  *
- * FIRST_PARTY_FALLBACKS shorts (notes / channel) return a fully-composed
+ * FIRST_PARTY_FALLBACKS shorts (notes) return a fully-composed
  * spec with embedded manifest + extras — the vendored manifest is the
  * source of truth pre-install and the install path preserves it through.
  *
- * KNOWN_MODULES shorts (vault / scribe / runner — post hub#310 FALLBACK
- * retirement) return a **minimal** spec carrying `package`, `manifestName`,
+ * KNOWN_MODULES shorts (vault / scribe / runner / channel / surface — post
+ * FALLBACK retirement) return a **minimal** spec carrying `package`, `manifestName`,
  * and the imperative `extras` fields
  * (`init`, `hasAuth`, `urlForEntry`, `postInstallFooter`). They do NOT carry
  * `startCmd` or `seedEntry` — those come from `<installDir>/.parachute/module.json`
@@ -760,9 +827,9 @@ const LEGACY_MANIFEST_ALIASES: Record<string, string> = {
 };
 
 /** Short name for a given manifest name, e.g. `parachute-vault` → `vault`.
- *  Consults both FIRST_PARTY_FALLBACKS (notes / channel) and KNOWN_MODULES
- *  (vault / scribe / runner — post-FALLBACK-retirement). Returns undefined
- *  for unknown manifests. */
+ *  Consults both FIRST_PARTY_FALLBACKS (notes) and KNOWN_MODULES
+ *  (vault / scribe / runner / channel / surface — post-FALLBACK-retirement).
+ *  Returns undefined for unknown manifests. */
 export function shortNameForManifest(manifestName: string): string | undefined {
   for (const [short, fb] of Object.entries(FIRST_PARTY_FALLBACKS)) {
     if (fb.manifest.manifestName === manifestName) return short;
@@ -773,6 +840,30 @@ export function shortNameForManifest(manifestName: string): string | undefined {
   return LEGACY_MANIFEST_ALIASES[manifestName];
 }
 
+/**
+ * Find a services.json row by its SHORT name (e.g. `"channel"`), resolving each
+ * row's manifest name (`parachute-channel`) back through `shortNameForManifest`.
+ *
+ * services.json rows carry the MANIFEST name, not the bare short — so a direct
+ * `s.name === short` comparison silently misses every first-party module. That
+ * exact mismatch (`s.name === "channel"` vs a `parachute-channel` row) is what
+ * surfaced a spurious "channel module is not installed" when wiring the channel
+ * connection sink. Resolve through the short↔manifest map instead. Returns the
+ * first match, or undefined when no installed row maps to `short`.
+ *
+ * NOTE: multi-instance vault rows (`parachute-vault-<name>`) are NOT resolvable
+ * here — `shortNameForManifest` only knows the canonical `parachute-vault`, so
+ * `findServiceByShort(services, "vault")` returns undefined even when a vault is
+ * installed. Vault rows are resolved by mount path via `findVaultUpstream`; this
+ * helper is for single-instance modules (channel / scribe / runner / surface).
+ */
+export function findServiceByShort<T extends { name: string }>(
+  services: readonly T[],
+  short: string,
+): T | undefined {
+  return services.find((s) => shortNameForManifest(s.name) === short);
+}
+
 /**
  * Compose a `ServiceSpec` from a `KNOWN_MODULES` entry plus the static
  * manifest data the caller has on hand (typically read from

package/src/services-manifest.ts

@@ -71,6 +71,38 @@ function normalizeUiSubUnitStatus(value: string): UiSubUnitStatus | undefined {
   return UI_SUB_UNIT_STATUS_ALIASES[value];
 }
 
+/**
+ * Who may load a UI sub-unit through the hub proxy (H3, surface-runtime
+ * design §12 — fixes parachute-surface#88, where `public` was declared but
+ * never enforced):
+ *
+ *   "public"    — anyone; no hub identity required (chrome strip off — H5).
+ *   "hub-users" — a valid hub session cookie OR a hub-issued Bearer whose
+ *                 scopes satisfy the surface's `scopes_required` (the OR
+ *                 keeps installed PWAs working). THE DEFAULT when absent.
+ *   "operator"  — the first-admin session only.
+ *   "surface"   — the surface backend owns admission END-TO-END; the hub
+ *                 proxy passes every request through (backed surfaces —
+ *                 kit-authenticated via @openparachute/surface-server: hub
+ *                 JWTs / capability links / anon, deny-by-default). Chrome
+ *                 strip off like `public` — capability-link invitees are
+ *                 NOT hub users.
+ *
+ * Enforced at the hub proxy BEFORE forwarding (`src/audience-gate.ts`).
+ * Legacy boolean `public` on the wire is accepted one alias window:
+ * `public: true` → `"public"`, `public: false` → default. Fail-closed: an
+ * unrecognized `audience` value rejects the row (the lenient manifest read
+ * then drops it — unroutable beats accidentally public). Version-skew
+ * corollary: a surface declaring `audience: "surface"` registered against a
+ * hub OLDER than this value's introduction gets its row rejected by that
+ * same fail-closed rule — the mount 404s until the hub is upgraded. The
+ * surface-side meta-schema ships the value with a hub-version requirement
+ * note for exactly this reason.
+ */
+export type UiAudience = "public" | "hub-users" | "operator" | "surface";
+
+const UI_AUDIENCE_VALUES: readonly UiAudience[] = ["public", "hub-users", "operator", "surface"];
+
 /**
  * A sub-unit beneath a module — used today by parachute-app to surface each
  * hosted UI as its own discoverable row under the App module, and the shape
@@ -129,6 +161,20 @@ export interface UiSubUnit {
   oauthClientId?: string;
   /** UI sub-unit lifecycle state. Absent → discovery treats as "active". */
   status?: UiSubUnitStatus;
+  /**
+   * Audience exposure (H3). Absent → "hub-users". The legacy boolean
+   * `public` field is normalized into this on read (true → "public") for
+   * one alias window. See {@link UiAudience}.
+   */
+  audience?: UiAudience;
+  /**
+   * OAuth scopes the UI declares as required (surface-host stamps these from
+   * the surface's meta.json `scopes_required`, e.g. `["vault:*:read"]` —
+   * `*` is a single-segment wildcard). The audience gate's Bearer branch
+   * checks a presented token's scopes against these. Snake_case to match
+   * the wire shape surface already writes.
+   */
+  scopes_required?: string[];
 }
 
 export interface ServiceEntry {
@@ -170,6 +216,16 @@ export interface ServiceEntry {
    *     bridges the gap. Tracked in parachute-scribe (separate issue).
    */
   stripPrefix?: boolean;
+  /**
+   * When `true`, the module's daemon accepts WebSocket upgrades and the hub's
+   * Bun-native upgrade bridge (H1, surface-runtime design) will forward
+   * `Upgrade: websocket` requests on this module's mounts to it. DENY BY
+   * DEFAULT: absent/false means an upgrade request to this mount is refused
+   * (426) without ever reaching the daemon. Modules declare this on their
+   * `.parachute/module.json` (the install-time contract) and carry it onto
+   * their self-registered services.json row; the hub honors either source.
+   */
+  websocket?: boolean;
   /**
    * Sub-units hosted under this module — parachute-app's bag of UIs, and
    * the shape vault is expected to adopt for per-instance metadata in a
@@ -282,6 +338,10 @@ function validateEntry(raw: unknown, where: string): ServiceEntry {
   if (stripPrefix !== undefined && typeof stripPrefix !== "boolean") {
     throw new ServicesManifestError(`${where}: "stripPrefix" must be a boolean if present`);
   }
+  const websocket = e.websocket;
+  if (websocket !== undefined && typeof websocket !== "boolean") {
+    throw new ServicesManifestError(`${where}: "websocket" must be a boolean if present`);
+  }
   const uis = e.uis;
   const validatedUis = validateUis(uis, where);
   const validatedStartError = validateStartError(e.lastStartError, where);
@@ -291,6 +351,7 @@ function validateEntry(raw: unknown, where: string): ServiceEntry {
   if (publicExposure !== undefined) entry.publicExposure = publicExposure as PublicExposure;
   if (installDir !== undefined) entry.installDir = installDir;
   if (stripPrefix !== undefined) entry.stripPrefix = stripPrefix;
+  if (websocket !== undefined) entry.websocket = websocket;
   if (validatedUis !== undefined) entry.uis = validatedUis;
   if (validatedStartError !== undefined) entry.lastStartError = validatedStartError;
   return entry;
@@ -405,12 +466,48 @@ function validateUiSubUnit(raw: unknown, where: string): UiSubUnit {
     }
     normalizedStatus = norm;
   }
+  // Audience (H3). Explicit `audience` wins; the legacy boolean `public` is
+  // accepted as an alias for one release window (true → "public"; false →
+  // the default, i.e. no field). FAIL-CLOSED on malformed values: throwing
+  // here makes the lenient manifest read drop the whole row — an unroutable
+  // surface beats one that silently falls open to the wrong audience.
+  let audience: UiAudience | undefined;
+  if (u.audience !== undefined) {
+    if (
+      typeof u.audience !== "string" ||
+      !(UI_AUDIENCE_VALUES as readonly string[]).includes(u.audience)
+    ) {
+      throw new ServicesManifestError(
+        `${where}: "audience" must be "public" | "hub-users" | "operator" | "surface" if present (got ${JSON.stringify(u.audience)})`,
+      );
+    }
+    audience = u.audience as UiAudience;
+  } else if (u.public !== undefined) {
+    if (typeof u.public !== "boolean") {
+      throw new ServicesManifestError(`${where}: legacy "public" must be a boolean if present`);
+    }
+    if (u.public) audience = "public";
+  }
+  let scopesRequired: string[] | undefined;
+  if (u.scopes_required !== undefined) {
+    if (
+      !Array.isArray(u.scopes_required) ||
+      u.scopes_required.some((s) => typeof s !== "string" || s.length === 0)
+    ) {
+      throw new ServicesManifestError(
+        `${where}: "scopes_required" must be an array of non-empty strings if present`,
+      );
+    }
+    scopesRequired = u.scopes_required as string[];
+  }
   const out: UiSubUnit = { displayName, path };
   if (tagline !== undefined) out.tagline = tagline;
   if (iconUrl !== undefined) out.iconUrl = iconUrl;
   if (version !== undefined) out.version = version;
   if (oauthClientId !== undefined) out.oauthClientId = oauthClientId;
   if (normalizedStatus !== undefined) out.status = normalizedStatus;
+  if (audience !== undefined) out.audience = audience;
+  if (scopesRequired !== undefined) out.scopes_required = scopesRequired;
   return out;
 }
 

package/src/setup-wizard.ts

@@ -199,6 +199,16 @@ export interface DerivedWizardState {
   hasAdmin: boolean;
   /** Whether the first vault (curated) has been provisioned in services.json. */
   hasVault: boolean;
+  /**
+   * Whether a REAL vault instance exists (a non-placeholder services.json
+   * row) — `hasVault` minus the `setup_vault_skipped` marker. The
+   * re-enterable vault step (B5, 2026-06-09 hub-module-boundary) keys on
+   * this: an operator who skipped the wizard's vault step has
+   * `hasVault === true` but `hasRealVault === false`, and the
+   * `/admin/setup?step=vault` deep-link (Home's "create your first vault"
+   * card) must still reach the create/import form.
+   */
+  hasRealVault: boolean;
   /**
    * Whether the operator has answered the "how will this hub be reached?"
    * question (the expose step, hub#268 Item 2). When admin + vault both
@@ -290,6 +300,14 @@ export function deriveWizardState(deps: {
   // phantom `vaults[]` row at SEED_VERSION); both surfaces must agree that a
   // placeholder is not a real vault.
   const vaultIsPlaceholder = vaultEntry !== undefined && vaultEntry.version === SEED_VERSION;
+  // INVARIANT (B5 re-enterable vault step): hasRealVault means "a real
+  // instance row exists" — placeholder excluded here, skip-marker excluded
+  // below (skip flips hasVault, never hasRealVault). THREE sites key on this
+  // same placeholder logic and must move together: this derivation,
+  // handleSetupGet's `?step=vault` re-entry gate, and handleSetupVaultPost's
+  // already-provisioned short-circuit. Changing one without the others
+  // either re-opens a provisioning form over a real vault or dead-ends the
+  // post-skip re-entry path.
   const hasRealVault = vaultEntry !== undefined && !vaultIsPlaceholder;
   // hub#168 Cut 2: `setup_vault_skipped === "true"` advances the wizard
   // past the vault step even when no vault row exists. The operator
@@ -339,7 +357,7 @@ export function deriveWizardState(deps: {
   else if (!hasVault) step = "vault";
   else if (!hasExposeMode) step = "expose";
   else step = "done";
-  return { step, hasAdmin, hasVault, hasExposeMode };
+  return { step, hasAdmin, hasVault, hasRealVault, hasExposeMode };
 }
 
 // --- handler types -------------------------------------------------------
@@ -724,7 +742,7 @@ export function renderVaultStep(props: RenderVaultStepProps): string {
         <h2>What's next</h2>
         <p>You'll land on a success screen with copy-paste MCP install
           instructions for Claude Code and a link to the admin UI, where
-          you can rename or add additional vaults.</p>
+          you can add more vaults.</p>
       </section>
       <section class="preview">
         <p class="preview-label">About to create</p>
@@ -735,8 +753,8 @@ export function renderVaultStep(props: RenderVaultStepProps): string {
         </div>
         <p class="preview-fine">
           The name shows up in the MCP URL (<code>/vault/&lt;name&gt;/mcp</code>)
-          and on the admin UI. You can rename or add vaults later from
-          <code>/admin/vaults</code>.
+          and on the admin UI. You can add or manage vaults later from the
+          vault module's own admin at <code>/vault/admin/</code>.
         </p>
       </section>
       ${error}
@@ -1696,6 +1714,41 @@ export function handleSetupGet(req: Request, deps: SetupWizardDeps): Response {
   };
   if (csrf.setCookie) extraHeaders["set-cookie"] = csrf.setCookie;
 
+  // Re-enterable vault step (B5, 2026-06-09 hub-module-boundary migration).
+  // A wizard-skip leaves the vault MODULE installed with no instances and no
+  // daemon (hub#607's zero-instances state) — and `setup_vault_skipped`
+  // makes `hasVault` true, so a plain GET resumes at expose/done and the
+  // create form is unreachable. The hub-side "create your first vault"
+  // affordance (Home's vault card + the legacy /admin/vaults empty state)
+  // deep-links `?step=vault`, which re-enters the create/import form as long
+  // as no REAL vault instance exists. Session-gated: post-account the box
+  // has an admin, and re-opening a provisioning form to a drive-by GET
+  // would leak setup state (the POST is session+CSRF-gated either way).
+  // With a real vault present the param is ignored and the normal flow
+  // (expose step / 301 → /login) runs.
+  //
+  // INVARIANT: this gate keys on `hasRealVault` (deriveWizardState) — the
+  // same placeholder logic handleSetupVaultPost's short-circuit uses. The
+  // three sites must move together; see the derivation comment in
+  // deriveWizardState.
+  if (url.searchParams.get("step") === "vault" && state.hasAdmin && !state.hasRealVault) {
+    const session = findActiveSession(deps.db, req);
+    if (!session) {
+      // Preserve the CSRF set-cookie across the bounce — same shape as the
+      // `?just_finished=1` session gate below.
+      const redirectHeaders: Record<string, string> = {
+        location: `/login?next=${encodeURIComponent("/admin/setup?step=vault")}`,
+      };
+      if (csrf.setCookie) redirectHeaders["set-cookie"] = csrf.setCookie;
+      return new Response(null, { status: 302, headers: redirectHeaders });
+    }
+    const cloudHost = detectAutoExposeMode(deps.env ?? process.env) === "public";
+    return new Response(renderVaultStep({ csrfToken: csrf.token, cloudHost }), {
+      status: 200,
+      headers: extraHeaders,
+    });
+  }
+
   // Setup fully complete (including expose-mode choice) — redirect to
   // /login unless we're rendering the success page once. The success
   // page sets `?just_finished=1` and the session cookie is on the
@@ -2168,9 +2221,18 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
       "Sign in to continue setup. (The wizard sets a session cookie on step 2; clearing cookies between steps will land you here.)",
     );
   }
-  // Already done — short-circuit to the done step.
+  // Already done — short-circuit to the done step. Keyed on hasRealVault
+  // (NOT hasVault): the `setup_vault_skipped` marker satisfies hasVault, but
+  // a skipped box has no instance and the re-entered vault step (B5,
+  // `?step=vault`) must be able to POST create/import — `mode=create` below
+  // clears the skip marker; `mode=skip` just re-sets it (idempotent).
+  //
+  // INVARIANT: same placeholder logic as deriveWizardState's hasRealVault
+  // derivation and handleSetupGet's `?step=vault` re-entry gate — the three
+  // sites must move together; see the derivation comment in
+  // deriveWizardState.
   const state = deriveWizardState(deps);
-  if (state.hasVault) {
+  if (state.hasRealVault) {
     if (form.isJson) {
       return jsonOkResponse({ step: "expose", message: "vault already provisioned" });
     }

package/src/users.ts

@@ -466,6 +466,17 @@ export function setUserVaults(
   return true;
 }
 
+/**
+ * Vault-delete cascade step (B1, 2026-06-09 hub-module-boundary): drop every
+ * `user_vaults` assignment row for the deleted vault, across all users.
+ * Exact `=` comparison on `vault_name` — no pattern matching. Returns the
+ * number of rows deleted.
+ */
+export function removeVaultAssignments(db: Database, vaultName: string): number {
+  const res = db.prepare("DELETE FROM user_vaults WHERE vault_name = ?").run(vaultName);
+  return Number(res.changes);
+}
+
 /**
  * Updates the password for an existing user. Throws `UserNotFoundError` if
  * the id has no row. Single-user-mode flows look up by username first and