@openparachute/hub 0.7.0 → 0.7.2-rc.1

package/src/oauth-handlers.ts

@@ -38,6 +38,7 @@ import {
   type OAuthClient,
   type RegisteredClient,
   approveClient,
+  expandRedirectUrisForHubOrigins,
   getClient,
   isValidRedirectUri,
   registerClient,
@@ -71,6 +72,7 @@ import { isHttpsRequest } from "./request-protocol.ts";
 import { narrowResourceVaultScopes, resolveResourceVault } from "./resource-binding.ts";
 import { isNonRequestableScope, isRequestableScope, scopeIsAdmin } from "./scope-explanations.ts";
 import { findUnknownScopes, loadDeclaredScopes } from "./scope-registry.ts";
+import { shortNameForManifest } from "./service-spec.ts";
 import {
   type ServicesManifest,
   // Hot-path OAuth flows use the lenient reader so a single malformed
@@ -391,13 +393,20 @@ function oauthErrorRedirect(
 
 /**
  * Optional first-party modules whose scopes `FIRST_PARTY_SCOPES` carries
- * statically (it's `Object.keys(SCOPE_EXPLANATIONS)`), paired with the
- * services.json entry that means "installed." Vault + hub are core and always
+ * statically (it's `Object.keys(SCOPE_EXPLANATIONS)`), paired with the module
+ * SHORT name that means "installed." Vault + hub are core and always
  * advertised; these are the modules a hub may not have.
+ *
+ * Keyed on the SHORT name (resolved from each services.json row via
+ * `shortNameForManifest`) rather than the raw manifest name so a row written
+ * under a legacy manifest name still counts as installed — e.g. an un-upgraded
+ * `parachute-channel` row aliases to short `agent` (channel→agent rename
+ * 2026-06-17), so `agent:send` is still correctly advertised until the daemon
+ * re-registers under `parachute-agent`.
  */
-const OPTIONAL_MODULE_SCOPES: ReadonlyArray<readonly [prefix: string, service: string]> = [
-  ["scribe:", "parachute-scribe"],
-  ["channel:", "parachute-channel"],
+const OPTIONAL_MODULE_SCOPES: ReadonlyArray<readonly [prefix: string, short: string]> = [
+  ["scribe:", "scribe"],
+  ["agent:", "agent"],
 ];
 
 /**
@@ -406,20 +415,22 @@ const OPTIONAL_MODULE_SCOPES: ReadonlyArray<readonly [prefix: string, service: s
  * module isn't installed.
  *
  * Why: `FIRST_PARTY_SCOPES` is static, so a vault-only hub still advertised
- * `scribe:*` + `channel:send`. Discovery clients list the advertised catalog
+ * `scribe:*` + `agent:send`. Discovery clients list the advertised catalog
  * verbatim — claude.ai's connector UI showed a friend connecting ONE vault a
- * request for Scribe + Channel access the hub can't even honor. So advertise an
+ * request for Scribe + Agent access the hub can't even honor. So advertise an
  * optional module's scopes only when its service is present in services.json.
  * (Trims the ADVERTISEMENT only; issuance/validation still use the full
  * `loadDeclaredScopes` set, and the per-vault PRM stays vault-narrowed.)
  */
 function advertisedScopes(declared: ReadonlySet<string>, manifest: ServicesManifest): string[] {
-  const installed = new Set(manifest.services.map((s) => s.name));
+  const installedShorts = new Set(
+    manifest.services.map((s) => shortNameForManifest(s.name) ?? s.name),
+  );
   return Array.from(declared)
     .filter(isRequestableScope)
     .filter((scope) => {
-      for (const [prefix, service] of OPTIONAL_MODULE_SCOPES) {
-        if (scope.startsWith(prefix) && !installed.has(service)) return false;
+      for (const [prefix, short] of OPTIONAL_MODULE_SCOPES) {
+        if (scope.startsWith(prefix) && !installedShorts.has(short)) return false;
       }
       return true;
     });
@@ -888,11 +899,11 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
   //   1. The consent screen — and the session-less "App not yet approved"
   //      page (`pendingClientResponse`) — shows ONLY that vault's scopes
   //      instead of the whole-hub catalog. Narrowing DROPS non-vault scopes
-  //      (`scribe:*`, `channel:send`, `hub:admin`) outright: the token this
+  //      (`scribe:*`, `agent:send`, `hub:admin`) outright: the token this
   //      flow mints is stamped `aud=vault.<name>`, so they're unusable inside
   //      it and only inflate the consent surface — the exact "scary consent"
   //      a friend hit connecting Claude to ONE vault (scribe isn't even
-  //      installed; `channel:send` is meaningless to them).
+  //      installed; `agent:send` is meaningless to them).
   //   2. The minted token carries the named scope, so `inferAudience` stamps
   //      `aud=vault.<name>` and a current-line vault accepts it (an unnamed
   //      `vault:read` token is rejected by `findBroadVaultScopes`).
@@ -2546,10 +2557,26 @@ export async function handleRegister(
   }
   const confidential = body.token_endpoint_auth_method === "client_secret_post";
   const scopes = (body.scope ?? "").split(" ").filter((s) => s.length > 0);
+  // Cross-hub-origin expansion (surface#118). A hub-served module (surface,
+  // notes) registers at install time knowing only the loopback hub origin;
+  // once exposed, the browser computes its redirect_uri from the PUBLIC hub
+  // origin, which strict authorize-time matching would reject. We expand each
+  // submitted URI rooted at one of THIS hub's known origins onto every other
+  // known hub origin, so a loopback-registered hub-served client is valid on
+  // the public origin too. FOREIGN-origin redirect_uris (a separate-origin
+  // surface on its own domain) are stored verbatim — never expanded onto hub
+  // origins, never dropped — preserving the strict anti-open-redirect
+  // invariant. Authorize-time matching stays exact-match
+  // (`requireRegisteredRedirectUri`); this only ever ADDS correct hub-origin
+  // URIs the operator already controls.
+  const expandedRedirectUris = expandRedirectUrisForHubOrigins(
+    redirectUris,
+    resolveBoundOrigins(deps),
+  );
   let registered: RegisteredClient;
   try {
     registered = registerClient(db, {
-      redirectUris,
+      redirectUris: expandedRedirectUris,
       scopes,
       clientName: body.client_name,
       confidential,

package/src/operator-token.ts

@@ -104,7 +104,7 @@ export const OPERATOR_TOKEN_SCOPE_SETS: Readonly<Record<OperatorScopeSet, readon
     "parachute:host:vault",
     "vault:admin",
     "scribe:admin",
-    "channel:send",
+    "agent:send",
   ],
 };
 

package/src/origin-check.ts

@@ -180,17 +180,25 @@ const MUTATION_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
  * mutation under `/admin/*`; keep this list in sync with the dispatch in
  * `hub-server.ts`):
  *
- *   - `POST /admin/connections` + `DELETE /admin/connections/<id>`
- *     (connection provision/teardown — the seam's canonical consumers are
- *     channel's admin page and the hub SPA, both same-origin `fetch()` with
- *     `credentials: "include"`)
+ *   - `POST /admin/connections` + `DELETE /admin/connections/<id>` +
+ *     `POST /admin/connections/<id>/approve`
+ *     (connection provision/teardown/claim-approval — the seam's canonical
+ *     consumers are the agent module'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.)
+ *   - `POST /admin/grants/<id>/approve` + `POST /admin/grants/<id>/revoke`
+ *     (agent-connector grant approval/revoke — operator cookie-authed in the
+ *     hub SPA, 4b-1. The `PUT /admin/grants` + `GET /admin/grants[/...]`
+ *     siblings are host-admin-Bearer-authed and pass 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/host-admin-token`, `/admin/agent-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).

package/src/resource-binding.ts

@@ -117,15 +117,15 @@ function decodeVaultName(segment: string): string | null {
  *   - already-named `vault:<other>:<verb>` is LEFT UNTOUCHED — a client that
  *     explicitly named a different vault is not silently re-pointed; the
  *     downstream picker / assignment defenses decide whether that's allowed.
- *   - non-vault scopes (`scribe:*`, `channel:send`, `hub:admin`, …) are
+ *   - non-vault scopes (`scribe:*`, `agent:send`, `hub:admin`, …) are
  *     DROPPED. This flow mints a token stamped `aud=vault.<name>` (RFC 8707),
- *     so a scribe/channel/hub scope inside it is unusable — keeping it only
+ *     so a scribe/agent/hub scope inside it is unusable — keeping it only
  *     inflates the consent surface a friend sees when connecting ONE vault.
  *     That "scary consent" is the failure mode this module exists to kill
  *     (see the header docstring): the verb-narrowing alone left the foreign
  *     scopes riding through, so a client that over-requests the whole-hub
  *     catalog (claude.ai reads it from the AS-metadata `scopes_supported`)
- *     still surfaced `scribe:admin` + `channel:send` on the consent screen.
+ *     still surfaced `scribe:admin` + `agent:send` on the consent screen.
  *     A client that genuinely wants a scribe token runs a separate flow
  *     naming the scribe resource.
  *
@@ -137,7 +137,7 @@ export function narrowResourceVaultScopes(scopes: readonly string[], vaultName:
   const out: string[] = [];
   for (const s of scopes) {
     const parts = s.split(":");
-    if (parts[0] !== "vault") continue; // drop scribe:/channel:/hub:/… — foreign to a vault-audience token
+    if (parts[0] !== "vault") continue; // drop scribe:/agent:/hub:/… — foreign to a vault-audience token
     const verb = parts[1];
     if (parts.length === 2 && verb && VAULT_VERBS.has(verb)) {
       out.push(`vault:${vaultName}:${verb}`);

package/src/scope-explanations.ts

@@ -45,7 +45,7 @@ export const SCOPE_EXPLANATIONS: Record<string, ScopeExplanation> = {
     label: "Full vault access plus configuration changes (rotate tokens, change settings).",
     level: "admin",
   },
-  // Optional-module scopes (scribe / channel). These are in FIRST_PARTY_SCOPES
+  // Optional-module scopes (scribe / agent). These are in FIRST_PARTY_SCOPES
   // (= Object.keys(this map)) but the modules may not be installed — so they're
   // GATED in `OPTIONAL_MODULE_SCOPES` (oauth-handlers.ts) and only advertised in
   // `scopes_supported` when the service is in services.json. If you add scopes
@@ -59,8 +59,8 @@ export const SCOPE_EXPLANATIONS: Record<string, ScopeExplanation> = {
     label: "Manage Scribe configuration (provider keys, models, quotas).",
     level: "admin",
   },
-  "channel:send": {
-    label: "Post messages to your Channel.",
+  "agent:send": {
+    label: "Post messages to your Agent.",
     level: "send",
   },
   "hub:admin": {

package/src/service-spec.ts

@@ -8,7 +8,7 @@ import type { ServiceEntry } from "./services-manifest.ts";
  *
  *   1939  parachute-hub      internal static + proxy, CLI-managed
  *   1940  parachute-vault    committed core
- *   1941  parachute-channel  exploration (may retire)
+ *   1941  parachute-agent    exploration (renamed from parachute-channel)
  *   1942  parachute-notes    committed core (PWA bundle)
  *   1943  parachute-scribe   committed core
  *   1944–1949  unassigned
@@ -64,7 +64,7 @@ export interface PortReservation {
 export const PORT_RESERVATIONS: readonly PortReservation[] = [
   { port: 1939, name: "parachute-hub", status: "assigned" },
   { port: 1940, name: "parachute-vault", status: "assigned" },
-  { port: 1941, name: "parachute-channel", status: "assigned" },
+  { port: 1941, name: "parachute-agent", status: "assigned" },
   { port: 1942, name: "parachute-notes", status: "assigned" },
   { port: 1943, name: "parachute-scribe", status: "assigned" },
   { port: 1944, name: "unassigned", status: "reserved" },
@@ -110,7 +110,7 @@ export interface FirstPartyExtras {
   /**
    * Does the service gate its endpoints behind auth today? Drives
    * `effectivePublicExposure`'s default for api/tool services. True for
-   * vault/channel; conservatively false for scribe until its auth-gate ships.
+   * vault/agent; conservatively false for scribe until its auth-gate ships.
    */
   readonly hasAuth?: boolean;
   /**
@@ -260,9 +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). 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
+// services.json row at boot (vault#356, scribe#50, runner#3). Agent
+// (renamed from channel 2026-06-17) followed in the 2026-06-09 hub-module-
+// boundary migration (D3) — it ships `.parachute/module.json` and
+// self-registers (channel#34 era, pre-rename), 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
@@ -321,7 +322,7 @@ const NOTES_FALLBACK: FirstPartyFallback = {
  * Indexed by short name (the `parachute install <X>` token).
  *
  * Only notes remains — see the block comment above for the rationale
- * (vault/scribe/runner/channel now self-register and ship their own
+ * (vault/scribe/runner/agent 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`, …).
@@ -332,7 +333,7 @@ export const FIRST_PARTY_FALLBACKS: Record<string, FirstPartyFallback> = {
 
 /**
  * Minimal install-time registry for first-party modules whose FALLBACK has
- * retired (vault / scribe / runner as of hub#310; channel as of the
+ * retired (vault / scribe / runner as of hub#310; agent 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
@@ -457,28 +458,26 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
       hasAuth: true,
     },
   },
-  channel: {
-    short: "channel",
-    package: "@openparachute/channel",
-    manifestName: "parachute-channel",
+  agent: {
+    short: "agent",
+    package: "@openparachute/agent",
+    manifestName: "parachute-agent",
     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.
+    displayName: "Agent",
+    // Mirrors agent's own module.json (the canonical fields below do too —
+    // keep in sync if agent's declaration changes). Renamed from `channel`
+    // 2026-06-17 (parachute-channel → parachute-agent); the module is the
+    // same webhook-fan-out + MCP bridge daemon, on the same port 1941.
     tagline: "Chat with your Claude Code sessions — a channel per session.",
-    canonicalPaths: ["/channel"],
+    canonicalPaths: ["/agent"],
     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).
+      // as scribe / vault / runner. The bare binary IS the daemon (agent's
+      // package.json bin maps `parachute-agent` → src/daemon.ts).
+      startCmd: () => ["parachute-agent"],
+      // Agent gates its endpoints behind hub-issued JWTs (agent:* scopes).
       hasAuth: true,
     },
   },
@@ -535,15 +534,20 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
  *     reappear silently on legacy installs.
  */
 export const RETIRED_MODULES: Record<string, { retiredAt: string; replacement?: string }> = {
-  agent: {
-    retiredAt: "2026-05-20",
-    replacement: "parachute-surface or parachute-runner (depending on use case)",
-  },
-  // 2026-05-20 retirement caught both forms of legacy rows.
-  "parachute-agent": {
-    retiredAt: "2026-05-20",
-    replacement: "parachute-surface or parachute-runner (depending on use case)",
-  },
+  // NOTE (2026-06-17, channel→agent rename): the `agent` / `parachute-agent`
+  // names were retired here on 2026-05-20 (the Claude-in-containers module).
+  // They are NOW RE-ASSIGNED to the renamed channel module (parachute-channel
+  // → parachute-agent). Keeping these as RETIRED entries would make
+  // `dropRetiredModuleRows` drop the NEW agent module's services.json row on
+  // load — breaking the live module. The names are no longer retired; they
+  // belong to the active agent module. The retired containers code now lives
+  // under `parachute-agent-legacy` (GitHub) and is not installable, so there
+  // is no live `agent` daemon to GC. (The historical `claw → agent`
+  // migration in services-manifest.ts still rewrites stale paraclaw rows to
+  // `name: "agent"` — they now resolve to the LIVE agent module's mount,
+  // which is harmless / arguably correct since paraclaw was the original
+  // "agent".)
+  //
   // The `parachute-app` row name retires 2026-05-27 along with the
   // app → surface rename (patterns#102). Operators upgrading from
   // 0.5.13-stable will have a `parachute-app` row in services.json
@@ -637,7 +641,7 @@ export function knownServices(): string[] {
  * 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
+ * else (agent / runner / notes / unknown third-party) defaults to
  * `experimental`. **Show all; never hide** — `focus` only groups + labels.
  */
 const FOCUS_DEFAULTS: Record<string, ModuleFocus> = {
@@ -645,7 +649,7 @@ const FOCUS_DEFAULTS: Record<string, ModuleFocus> = {
   scribe: "core",
   hub: "core",
   surface: "core",
-  channel: "experimental",
+  agent: "experimental",
   runner: "experimental",
   notes: "experimental",
 };
@@ -668,7 +672,7 @@ export function focusForShort(short: string, declared?: ModuleFocus): ModuleFocu
  * `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) then KNOWN_MODULES (vault / scribe / runner / agent / surface).
  *
  * `notes` is intentionally included — it's still resolvable (vendored fallback)
  * for legacy installs; it surfaces as `experimental` and isn't pushed as a
@@ -727,7 +731,7 @@ export function canonicalPortForManifest(manifestName: string): number | undefin
  * 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 / channel / surface — post
+ * KNOWN_MODULES shorts (vault / scribe / runner / agent / surface — post
  * FALLBACK retirement) return a **minimal** spec carrying `package`, `manifestName`,
  * and the imperative `extras` fields
  * (`init`, `hasAuth`, `urlForEntry`, `postInstallFooter`). They do NOT carry
@@ -821,14 +825,23 @@ export async function getSpecFromInstallDir(
  * their install — without this alias, `parachute start/stop/logs/status`
  * silently skip those rows. Remove after launch, alongside the `lens →
  * notes` install alias.
+ *
+ * `parachute-channel` → `agent` (2026-06-17): the channel module was renamed
+ * to agent (parachute-channel → parachute-agent). Operators with an
+ * un-upgraded `services.json` carry a `name: "parachute-channel"` row; this
+ * alias keeps `shortNameForManifest("parachute-channel") === "agent"` so the
+ * legacy row still resolves to the live agent module for routing + lifecycle
+ * until the daemon re-registers under `parachute-agent`. Remove after one
+ * release cycle, alongside the `channel → agent` install alias.
  */
 const LEGACY_MANIFEST_ALIASES: Record<string, string> = {
   "parachute-lens": "notes",
+  "parachute-channel": "agent",
 };
 
 /** Short name for a given manifest name, e.g. `parachute-vault` → `vault`.
  *  Consults both FIRST_PARTY_FALLBACKS (notes) and KNOWN_MODULES
- *  (vault / scribe / runner / channel / surface — post-FALLBACK-retirement).
+ *  (vault / scribe / runner / agent / 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)) {
@@ -841,13 +854,13 @@ export function shortNameForManifest(manifestName: string): string | undefined {
 }
 
 /**
- * Find a services.json row by its SHORT name (e.g. `"channel"`), resolving each
- * row's manifest name (`parachute-channel`) back through `shortNameForManifest`.
+ * Find a services.json row by its SHORT name (e.g. `"agent"`), resolving each
+ * row's manifest name (`parachute-agent`) 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
+ * exact mismatch (`s.name === "agent"` vs a `parachute-agent` row) is what
+ * surfaced a spurious "agent module is not installed" when wiring the agent
  * connection sink. Resolve through the short↔manifest map instead. Returns the
  * first match, or undefined when no installed row maps to `short`.
  *
@@ -855,7 +868,7 @@ export function shortNameForManifest(manifestName: string): string | undefined {
  * 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).
+ * helper is for single-instance modules (agent / scribe / runner / surface).
  */
 export function findServiceByShort<T extends { name: string }>(
   services: readonly T[],

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;
 }