@openparachute/hub 0.7.0 → 0.7.1

package/src/admin-login-ui.ts

@@ -161,8 +161,18 @@ export interface InviteSetupProps {
   /**
    * When the invite pins a vault name the redeemer can't choose one — we show
    * it read-only. When null the redeemer names their own vault (a text field).
+   * With `provisionVault: false` a pinned name is a SHARED-VAULT invite: the
+   * redeemer is being given `role` access to the operator's existing vault.
    */
   pinnedVaultName: string | null;
+  /**
+   * When the invite pre-names the account, the username is shown read-only
+   * and ENFORCED server-side (the redeem handler ignores the form field).
+   * Null = the redeemer picks their own.
+   */
+  pinnedUsername: string | null;
+  /** The `user_vaults` role redemption grants ('read' | 'write') — shown on the shared-vault row. */
+  role: string;
   /** Whether redemption provisions a vault at all (shows the vault row iff true). */
   provisionVault: boolean;
   username?: string;
@@ -177,15 +187,55 @@ export interface InviteSetupProps {
  * same `/account/setup/<token>` path. Reuses the shared login chrome.
  */
 export function renderInviteSetup(props: InviteSetupProps): string {
-  const { token, csrfToken, pinnedVaultName, provisionVault, username, vaultName, errorMessage } =
-    props;
+  const {
+    token,
+    csrfToken,
+    pinnedVaultName,
+    pinnedUsername,
+    role,
+    provisionVault,
+    username,
+    vaultName,
+    errorMessage,
+  } = props;
   const error = errorMessage ? `<p class="error-banner">${escapeHtml(errorMessage)}</p>` : "";
   const usernameAttr = username ? ` value="${escapeAttr(username)}"` : "";
 
-  // Vault row: shown only when the invite provisions a vault. Pinned → a
-  // read-only display of the name the admin chose (redeemer can't squat names).
-  // Unpinned → a text field the redeemer fills.
+  // Username row: pre-named → read-only display (the server ENFORCES the
+  // invite's username; the disabled input never submits and the handler
+  // ignores the field anyway). Unpinned → the normal pick-a-name field.
+  const usernameRow =
+    pinnedUsername !== null
+      ? `
+        <label class="field">
+          <span class="field-label">Username</span>
+          <input type="text" value="${escapeAttr(pinnedUsername)}" readonly disabled />
+          <span class="field-hint">Your hub operator chose this username for you.</span>
+        </label>`
+      : `
+        <label class="field">
+          <span class="field-label">Username</span>
+          <input type="text" name="username" id="username" autocomplete="username" autofocus
+            required minlength="2" maxlength="32"
+            pattern="[a-z0-9_-]+" title="lowercase letters, digits, _ - (2–32 chars)"
+            spellcheck="false" autocapitalize="off"${usernameAttr} />
+          <span class="field-hint">lowercase letters, digits, <code>_</code>, <code>-</code></span>
+        </label>`;
+
+  // Vault row. Provisioning invites show the new vault's name (pinned →
+  // read-only; unpinned → a text field the redeemer fills). A shared-vault
+  // invite (no provisioning + a pinned name) shows what the redeemer is
+  // being given access to, including the role.
   let vaultRow = "";
+  if (!provisionVault && pinnedVaultName !== null) {
+    const roleLabel = role === "read" ? "read-only" : "read &amp; write";
+    vaultRow = `
+        <label class="field">
+          <span class="field-label">Shared vault</span>
+          <input type="text" value="${escapeAttr(pinnedVaultName)}" readonly disabled />
+          <span class="field-hint">You're being given ${roleLabel} access to this existing vault.</span>
+        </label>`;
+  }
   if (provisionVault) {
     if (pinnedVaultName !== null) {
       vaultRow = `
@@ -240,21 +290,20 @@ export function renderInviteSetup(props: InviteSetupProps): string {
       <div class="card-header">
         ${header()}
         <h1>Claim your invite</h1>
-        <p class="subtitle">Pick a username and password to create your Parachute account${
-          provisionVault ? " and your own vault" : ""
+        <p class="subtitle">${
+          pinnedUsername !== null ? "Pick a password" : "Pick a username and password"
+        } to create your Parachute account${
+          provisionVault
+            ? " and your own vault"
+            : pinnedVaultName !== null
+              ? " with access to a shared vault"
+              : ""
         }.</p>
       </div>
       ${error}
       <form method="POST" action="/account/setup/${escapeAttr(token)}" class="auth-form">
         ${renderCsrfHiddenInput(csrfToken)}
-        <label class="field">
-          <span class="field-label">Username</span>
-          <input type="text" name="username" id="username" autocomplete="username" autofocus
-            required minlength="2" maxlength="32"
-            pattern="[a-z0-9_-]+" title="lowercase letters, digits, _ - (2–32 chars)"
-            spellcheck="false" autocapitalize="off"${usernameAttr} />
-          <span class="field-hint">lowercase letters, digits, <code>_</code>, <code>-</code></span>
-        </label>
+        ${usernameRow}
         <label class="field">
           <span class="field-label">Password</span>
           <input type="password" name="password" autocomplete="new-password"

package/src/admin-vaults.ts

@@ -541,6 +541,12 @@ export interface DeleteVaultDeps {
   channelOrigin: string | null;
   /** Resolve a vault's loopback origin from services.json (trigger teardown). */
   resolveVaultOrigin: (vaultName: string) => string | null;
+  /**
+   * Resolve a module's loopback origin by short name (H4 — best-effort
+   * credential-removal notification during connection teardown). Optional:
+   * absent → the notification step records a warning, revocation still runs.
+   */
+  resolveModuleOrigin?: (short: string) => string | null;
   /** Test seam: run `parachute-vault remove` — same Runner seam as create. */
   runCommand?: CreateVaultDeps["runCommand"];
   /**
@@ -755,6 +761,9 @@ export async function handleDeleteVault(
     hubOrigin: deps.issuer,
     modules: [], // teardown never consults the catalog
     resolveVaultOrigin: deps.resolveVaultOrigin,
+    ...(deps.resolveModuleOrigin !== undefined
+      ? { resolveModuleOrigin: deps.resolveModuleOrigin }
+      : {}),
     channelOrigin: deps.channelOrigin,
     storePath: deps.connectionsStorePath,
     ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),

package/src/api-invites.ts

@@ -19,6 +19,7 @@
 import type { Database } from "bun:sqlite";
 import { type AdminAuthError, adminAuthErrorResponse, requireScope } from "./admin-auth.ts";
 import { HOST_ADMIN_SCOPE } from "./admin-vaults.ts";
+import { SERVICES_MANIFEST_PATH } from "./config.ts";
 import {
   DEFAULT_INVITE_TTL_SECONDS,
   type Invite,
@@ -28,8 +29,11 @@ import {
   issueInvite,
   listInvites,
   revokeInvite,
+  usernameReservedByPendingInvite,
 } from "./invites.ts";
+import { getUserByUsernameCI, validateUsername } from "./users.ts";
 import { VAULT_NAME_CHARSET_RE } from "./vault-name.ts";
+import { listVaultNamesFromPath } from "./vault-names.ts";
 
 export interface ApiInvitesDeps {
   db: Database;
@@ -49,6 +53,7 @@ interface InviteWireShape {
   id: string;
   status: InviteStatus;
   vault_name: string | null;
+  username: string | null;
   role: string;
   provision_vault: boolean;
   default_mirror: string | null;
@@ -64,6 +69,7 @@ function toWire(invite: Invite, status: InviteStatus): InviteWireShape {
     id: invite.tokenHash,
     status,
     vault_name: invite.vaultName,
+    username: invite.username,
     role: invite.role,
     provision_vault: invite.provisionVault,
     default_mirror: invite.defaultMirror,
@@ -89,6 +95,7 @@ function redeemUrl(issuer: string, rawToken: string): string {
 
 interface CreateInviteBody {
   vaultName: string | null;
+  username: string | null;
   role: string;
   provisionVault: boolean;
   defaultMirror: string | null;
@@ -162,6 +169,37 @@ async function parseCreateBody(
     vaultName = rawVault;
   }
 
+  // username — optional. null/omitted = redeemer picks their own. Validated
+  // with the SAME vocabulary as /api/users (charset + length + reserved).
+  let username: string | null = null;
+  const rawUsername =
+    Object.hasOwn(obj, "username") && obj.username !== undefined ? obj.username : undefined;
+  if (rawUsername !== undefined && rawUsername !== null) {
+    if (typeof rawUsername !== "string" || rawUsername.length === 0) {
+      return {
+        ok: false,
+        status: 400,
+        error: "invalid_request",
+        description: '"username" must be a non-empty string or null',
+      };
+    }
+    const u = validateUsername(rawUsername);
+    if (!u.valid) {
+      return {
+        ok: false,
+        status: 400,
+        error: "invalid_username",
+        description:
+          u.reason === "length"
+            ? "username must be 2-32 characters long"
+            : u.reason === "reserved"
+              ? "username is reserved (admin, root, system, setup, parachute, hub)"
+              : "username must contain only lowercase letters, digits, hyphens, and underscores ([a-z0-9_-])",
+      };
+    }
+    username = u.name;
+  }
+
   // role — default 'write' (owner).
   let role = "write";
   const rawRole = obj.role;
@@ -245,7 +283,10 @@ async function parseCreateBody(
     expiresInSeconds = Math.floor(rawExpiry);
   }
 
-  return { ok: true, body: { vaultName, role, provisionVault, defaultMirror, expiresInSeconds } };
+  return {
+    ok: true,
+    body: { vaultName, username, role, provisionVault, defaultMirror, expiresInSeconds },
+  };
 }
 
 /** POST /api/invites — create an invite, return the single-emit URL + token. */
@@ -262,33 +303,72 @@ export async function handleCreateInvite(req: Request, deps: ApiInvitesDeps): Pr
   }
   const parsed = await parseCreateBody(req);
   if (!parsed.ok) return jsonError(parsed.status, parsed.error, parsed.description);
-  const { vaultName, role, provisionVault, defaultMirror, expiresInSeconds } = parsed.body;
+  const { vaultName, username, role, provisionVault, defaultMirror, expiresInSeconds } =
+    parsed.body;
+  const now = (deps.now ?? (() => new Date()))();
 
-  // SECURITY: a pinned vault_name with provision_vault=false would assign the
-  // redeeming user to a PRE-EXISTING vault as owner-admin — a cross-tenant
-  // breach, since the owner-vs-shared role split isn't built. Shared-vault
-  // invites aren't supported yet, so reject this combination outright (defense
-  // in depth — the redeem path rejects it too). The supported shapes are:
-  // provision_vault=true (+ optional pinned name → provisions THAT name), or
-  // provision_vault=false with NO name (account-only, assignedVaults=[]).
-  if (vaultName !== null && !provisionVault) {
+  // Shape gates over the three supported invite shapes:
+  //
+  //   1. provision_vault=true (+ optional pinned NEW name) — redemption
+  //      provisions a fresh vault for the redeemer. Role must be 'write':
+  //      the redeemer is the vault's ONLY user, so a read-only sole user
+  //      would leave the new vault permanently un-writable.
+  //   2. provision_vault=false + vault_name — SHARED-VAULT invite: redemption
+  //      assigns the redeemer to the admin's EXISTING vault at `role` ('read'
+  //      or 'write'). The vault must exist NOW (services.json) — pinning a
+  //      nonexistent name is a typo, not a future reservation. Issuing is
+  //      host:admin-gated, the same authority that can already assign any
+  //      user to any vault via POST /api/users — the invite only packages
+  //      that assignment as a deliverable link. The vault-delete cascade
+  //      (`revokeInvitesForVault`) revokes pending shared invites when the
+  //      pinned vault is deleted, and the redeem path re-checks existence.
+  //   3. provision_vault=false with NO name — account-only (assignedVaults=[]).
+  if (provisionVault && role !== "write") {
     return jsonError(
       400,
       "invalid_request",
-      "shared-vault invites (provision_vault=false with a vault_name) aren't supported yet — omit vault_name for an account-only invite, or set provision_vault=true to provision a new vault",
+      'a provisioned vault\'s sole user must hold write — use role "write", or share an existing vault (provision_vault=false + vault_name) for read-only access',
     );
   }
+  if (vaultName !== null && !provisionVault) {
+    const manifestPath = deps.manifestPath ?? SERVICES_MANIFEST_PATH;
+    const known = new Set(listVaultNamesFromPath(manifestPath));
+    if (!known.has(vaultName)) {
+      return jsonError(
+        400,
+        "vault_not_found",
+        `vault "${vaultName}" is not registered on this hub — shared-vault invites must name an existing vault`,
+      );
+    }
+  }
+
+  // Pre-named username: catch collisions at MINT time (the redeem-time check
+  // stays authoritative, but an enforced name that's already taken makes the
+  // link dead-on-arrival — fail fast for the admin instead).
+  if (username !== null) {
+    if (getUserByUsernameCI(deps.db, username) !== null) {
+      return jsonError(409, "username_taken", `username "${username}" is already in use`);
+    }
+    if (usernameReservedByPendingInvite(deps.db, username, now)) {
+      return jsonError(
+        409,
+        "username_reserved",
+        `username "${username}" is already reserved by another pending invite — revoke that invite first or pick a different name`,
+      );
+    }
+  }
 
   const issued = issueInvite(deps.db, {
     createdBy: authUserId,
     vaultName,
+    username,
     role,
     provisionVault,
     defaultMirror,
     expiresInSeconds,
     ...(deps.now !== undefined ? { now: deps.now } : {}),
   });
-  const status = inviteStatus(issued.invite, (deps.now ?? (() => new Date()))());
+  const status = inviteStatus(issued.invite, now);
   return new Response(
     JSON.stringify({
       invite: toWire(issued.invite, status),

package/src/audience-gate.ts

@@ -0,0 +1,268 @@
+/**
+ * Per-UI audience gate (H3, surface-runtime design §12 — fixes
+ * parachute-surface#88: the `public` flag existed but nothing enforced it).
+ *
+ * A module's services.json row may carry a `uis{}` map of hosted UI
+ * sub-units; each sub-unit now declares an `audience`
+ * (`public | hub-users | operator | surface`, default `hub-users`). The HUB
+ * PROXY enforces it BEFORE forwarding — surface-host serves whatever the
+ * proxy lets through, exactly like the publicExposure cloak.
+ *
+ * Scope discipline: the gate covers the SURFACE UI MOUNTS specifically (the
+ * uis sub-unit paths), not every module path — a module's own APIs keep
+ * their own auth (vault validates Bearers, scribe validates its token, …).
+ * The gate also runs before WebSocket upgrades on a gated mount (threaded
+ * into `maybeUpgradeWebSocket`).
+ *
+ * The four audiences:
+ *
+ *   public    — pass (and the chrome strip is disabled — H5: public readers
+ *               aren't hub users).
+ *   hub-users — a valid hub session cookie OR a valid hub-issued Bearer
+ *               whose scopes satisfy the sub-unit's `scopes_required`. The
+ *               OR keeps installed PWAs working: a standalone PWA holds
+ *               OAuth tokens, not a hub session. Bearer validation reuses
+ *               the hub#516 seam (signature/expiry/revocation via the JWKS,
+ *               `iss` ∈ the hub's bound-origin set — a PWA token carries the
+ *               public origin while the proxied request may resolve the
+ *               loopback issuer).
+ *   operator  — the first-admin session only. A Bearer never satisfies this
+ *               tier (operator surfaces are interactive; the session is the
+ *               operator's presence).
+ *   surface   — pass: the surface backend owns admission END-TO-END
+ *               (backed surfaces — parachute-surface runtime, surfaces with
+ *               their own server entry, kit-authenticated via
+ *               @openparachute/surface-server: hub JWTs / capability links /
+ *               anon, deny-by-default with a public conformance suite). The
+ *               hub gating these would add a SECOND auth layer that BLOCKS
+ *               the surface's own audience plane — e.g. the docs-editor's
+ *               capability-link invitees are NOT hub users by design, so a
+ *               hub-users gate would 302 them to /login before the surface's
+ *               own auth ever ran. Chrome strip follows the `public`
+ *               precedent (disabled — the visitors are mostly capability
+ *               invitees, not hub users), and WS upgrades pass through too
+ *               (the gate threads into `maybeUpgradeWebSocket`; null = no
+ *               deny = the upgrade proceeds to the capability check).
+ *
+ * Deny shape: document requests (GET + Accept: text/html, no session) get a
+ * 302 to `/login?next=<path>`; everything else gets 401/403 JSON. A
+ * signed-in-but-insufficient caller (non-admin on an operator surface, or a
+ * Bearer missing the required scopes) gets 403, not a login redirect.
+ *
+ * Exposure layers are ORTHOGONAL to the audience: the `publicExposure`
+ * cloak runs at the service-row level BEFORE this gate (dispatch skips the
+ * gate entirely on a cloaked row so the 404 stays indistinguishable from
+ * not-installed). A `surface`-audience mount on a loopback-only row is
+ * therefore still unreachable from tailnet/funnel — exactly like `public`.
+ *
+ * Fail-closed posture: malformed `audience` metadata never reaches this
+ * module — `services-manifest.ts` validation rejects the row and the lenient
+ * read drops it (the mount 404s). An absent DB (hub booted stateless) denies
+ * every audience that needs an identity store: `hub-users` and `operator`.
+ * `public` and `surface` still pass — neither consults hub identity
+ * (`surface` self-auths every request; denying it on absent DB would break
+ * the surface for zero security gain). Version skew: a surface declaring
+ * `audience: "surface"` registered against an OLDER hub (pre-dating the
+ * value) gets its row rejected by manifest validation — the mount 404s
+ * until the hub upgrades; the surface-side meta-schema ships the value
+ * separately with a hub-version requirement note.
+ */
+
+import type { Database } from "bun:sqlite";
+import { validateHostAdminToken } from "./host-admin-token-validation.ts";
+import type { ServiceEntry, UiAudience, UiSubUnit } from "./services-manifest.ts";
+import { findActiveSession } from "./sessions.ts";
+import { isFirstAdmin } from "./users.ts";
+
+/** A pathname resolved to the UI sub-unit that hosts it. */
+export interface UiMountMatch {
+  readonly entry: ServiceEntry;
+  readonly uiKey: string;
+  readonly ui: UiSubUnit;
+  /** The normalized mount path (no trailing slash) the match keyed on. */
+  readonly mount: string;
+  /** The effective audience (default applied). */
+  readonly audience: UiAudience;
+}
+
+/** The effective audience for a sub-unit — absent means `hub-users`. */
+export function effectiveUiAudience(ui: UiSubUnit): UiAudience {
+  return ui.audience ?? "hub-users";
+}
+
+/**
+ * Resolve which UI sub-unit (across every service's `uis{}` map) a pathname
+ * falls under. Longest-prefix match, same comparison shape as
+ * `findServiceUpstream` (trailing slashes normalized; `pathname === mount`
+ * or `pathname.startsWith(mount + "/")`). Returns undefined when the path is
+ * not under any declared UI — module API paths, undeclared mounts, and
+ * legacy flat rows are NOT gated here.
+ */
+export function resolveUiMount(
+  services: readonly ServiceEntry[],
+  pathname: string,
+): UiMountMatch | undefined {
+  let best: UiMountMatch | undefined;
+  for (const entry of services) {
+    if (!entry.uis) continue;
+    for (const [uiKey, ui] of Object.entries(entry.uis)) {
+      const norm = ui.path.replace(/\/+$/, "") || "/";
+      if (pathname === norm || pathname.startsWith(`${norm}/`)) {
+        if (!best || norm.length > best.mount.length) {
+          best = { entry, uiKey, ui, mount: norm, audience: effectiveUiAudience(ui) };
+        }
+      }
+    }
+  }
+  return best;
+}
+
+/**
+ * Does one bearer scope satisfy one required-scope pattern?
+ *
+ * Patterns are colon-segmented with `*` as a single-segment wildcard —
+ * `vault:*:read` matches `vault:default:read`. One asymmetry is deliberate:
+ * the broad UNNAMED form (`vault:read`) satisfies `vault:*:<verb>` — a token
+ * carrying any-vault read authority is strictly wider than one pinned vault,
+ * so refusing it would deny a caller that holds MORE than required.
+ */
+export function scopeMatchesPattern(pattern: string, scope: string): boolean {
+  const p = pattern.split(":");
+  const s = scope.split(":");
+  if (p.length === s.length) {
+    return p.every((seg, i) => seg === "*" || seg === s[i]);
+  }
+  // Broad unnamed form: vault:<verb> ⊇ vault:*:<verb>.
+  if (p.length === 3 && s.length === 2 && p[1] === "*") {
+    return p[0] === s[0] && p[2] === s[1];
+  }
+  return false;
+}
+
+/**
+ * Do the bearer's scopes satisfy the sub-unit's requirement? EVERY pattern
+ * in `scopes_required` must be matched by at least one bearer scope ("a
+ * Bearer whose scopes include the surface's scopes"). An empty/absent
+ * requirement means any valid hub-issued Bearer passes — the surface
+ * declared no scope shape, so hub identity alone is the bar.
+ */
+export function scopesSatisfyRequirement(
+  required: readonly string[] | undefined,
+  bearerScopes: readonly string[],
+): boolean {
+  if (!required || required.length === 0) return true;
+  return required.every((pattern) => bearerScopes.some((s) => scopeMatchesPattern(pattern, s)));
+}
+
+export interface AudienceGateDeps {
+  /** Hub DB — absent (stateless boot) denies every hub-gated audience
+   *  (`hub-users` / `operator`); `public` and `surface` pass without it. */
+  db: Database | undefined;
+  /**
+   * The hub's bound-origin set for Bearer `iss` validation (the hub#516
+   * seam — PWA tokens carry the public origin while the request may resolve
+   * loopback). Lazy: only consulted on the Bearer branch.
+   */
+  knownIssuers: () => readonly string[];
+}
+
+function wantsDocument(req: Request): boolean {
+  return req.method === "GET" && (req.headers.get("accept") ?? "").includes("text/html");
+}
+
+function loginRedirect(req: Request): Response {
+  const url = new URL(req.url);
+  const next = encodeURIComponent(url.pathname + url.search);
+  return new Response(null, {
+    status: 302,
+    headers: { location: `/login?next=${next}`, "cache-control": "no-store" },
+  });
+}
+
+function denyJson(status: number, error: string, description: string): Response {
+  return new Response(JSON.stringify({ error, error_description: description }), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+/**
+ * Enforce a sub-unit's audience for a request. Returns `null` when the
+ * request may proceed to the proxy, or the deny Response (302 login for
+ * anonymous document requests; 401/403 JSON otherwise).
+ */
+export async function gateUiAudience(
+  req: Request,
+  audience: UiAudience,
+  ui: UiSubUnit,
+  deps: AudienceGateDeps,
+): Promise<Response | null> {
+  if (audience === "public") return null;
+
+  // `surface` — pass through unconditionally (incl. on an absent DB, below):
+  // the surface backend authenticates EVERY request itself (deny-by-default
+  // kit auth: hub JWTs / capability links / anon). A hub-side deny here
+  // would block the surface's own audience plane — its capability-link
+  // invitees are not hub users by design.
+  if (audience === "surface") return null;
+
+  // Fail closed without a DB: no identity store, no way to admit anyone to
+  // a hub-gated (`hub-users` / `operator`) surface.
+  if (!deps.db) {
+    return wantsDocument(req)
+      ? loginRedirect(req)
+      : denyJson(401, "unauthenticated", "this surface requires a hub identity");
+  }
+  const db = deps.db;
+
+  const session = findActiveSession(db, req);
+
+  if (audience === "operator") {
+    if (session && isFirstAdmin(db, session.userId)) return null;
+    if (session) {
+      return denyJson(
+        403,
+        "not_admin",
+        "this surface is restricted to the hub operator — your account home is at /account/",
+      );
+    }
+    return wantsDocument(req)
+      ? loginRedirect(req)
+      : denyJson(401, "unauthenticated", "this surface requires the hub operator's session");
+  }
+
+  // audience === "hub-users"
+  if (session) return null;
+
+  const auth = req.headers.get("authorization");
+  if (auth?.startsWith("Bearer ")) {
+    const token = auth.slice("Bearer ".length).trim();
+    try {
+      const validated = await validateHostAdminToken(db, token, [...deps.knownIssuers()]);
+      const bearerScopes =
+        typeof validated.payload.scope === "string"
+          ? validated.payload.scope.split(/\s+/).filter((s) => s.length > 0)
+          : [];
+      if (scopesSatisfyRequirement(ui.scopes_required, bearerScopes)) return null;
+      return denyJson(
+        403,
+        "insufficient_scope",
+        `this surface requires scopes: ${(ui.scopes_required ?? []).join(", ")}`,
+      );
+    } catch (err) {
+      return denyJson(
+        401,
+        "unauthenticated",
+        `bearer token invalid — ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  return wantsDocument(req)
+    ? loginRedirect(req)
+    : denyJson(
+        401,
+        "unauthenticated",
+        "this surface requires a hub session or a hub-issued bearer token",
+      );
+}

package/src/chrome-strip.ts

@@ -19,6 +19,13 @@
  * application, looks distinctively Notes, reads as Parachute because the
  * tokens are continuous").
  *
+ * H5 (surface-runtime design): the opt-out generalized — when a UI
+ * sub-unit's declared `audience` resolves `public` at the proxy's audience
+ * gate (H3), the dispatch passes that mount as an extra opt-out prefix
+ * (hub-server `decorateWithChrome`). Public readers aren't hub users; the
+ * identity chrome never rides their pages. The static list below remains
+ * for hub-users surfaces that own their own chrome (Notes).
+ *
  * Why path-based and not module-declared:
  *   - Notes is a `uis[]` sub-unit of parachute-app, not its own module —
  *     adding `chrome: "off"` to parachute-app's module.json would suppress
@@ -38,7 +45,7 @@
  * defense is cheap and protects future refactors).
  */
 
-import { brandMarkSvg, WORDMARK_TEXT } from "./brand.ts";
+import { WORDMARK_TEXT, brandMarkSvg } from "./brand.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken } from "./csrf.ts";
 
 /**