@openparachute/hub 0.7.0 → 0.7.2-rc.1

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";
 
 /**

package/src/cli.ts

@@ -939,7 +939,19 @@ async function main(argv: string[]): Promise<number> {
       // after `vault` (including --help) is passed through verbatim.
       if (rest.length === 0) return await mod.dispatchVault(["--help"]);
 
-      // Everything under `vault` forwards transparently to `parachute-vault`.
+      // Intercept the delete verbs BEFORE the transparent passthrough (B3):
+      // `parachute vault remove <name>` must route through the hub's identity
+      // cascade (`DELETE /vaults/<name>`), NOT forward verbatim to
+      // `parachute-vault remove` (mechanics-only — orphans hub-side tokens,
+      // grants, user_vaults rows). `rm` is a convenience alias to the same path.
+      const sub = rest[0];
+      if (sub === "remove" || sub === "rm") {
+        const rm = await loadCommand("vault-remove", () => import("./commands/vault-remove.ts"));
+        if (!rm) return 1;
+        return await rm.vaultRemove(rest.slice(1));
+      }
+
+      // Everything else under `vault` forwards transparently to `parachute-vault`.
       // `vault tokens create` used to route through a guided interactive
       // wrapper, but the pvt_* DROP (vault#412 / hub#466) removed that vault
       // subcommand — it now exits 1 with migration guidance. Access tokens are

package/src/clients.ts

@@ -215,6 +215,94 @@ export function requireRegisteredRedirectUri(client: OAuthClient, candidate: str
   return candidate;
 }
 
+/**
+ * Cross-hub-origin redirect_uri expansion for hub-served DCR clients
+ * (surface#118; the "hub assist" half of the fix).
+ *
+ * THE PROBLEM. A hub-served module (surface-host, notes) registers its OAuth
+ * client at install time, when the only origin it knows is the loopback hub
+ * URL (`http://127.0.0.1:1939`). Once the operator runs `parachute expose`,
+ * the browser loads the surface from the PUBLIC hub origin and the
+ * surface-client runtime computes its `redirect_uri` from `window.location.
+ * origin` (the public one) — which was never registered. Authorize-time
+ * matching is deliberately strict exact-match (`requireRegisteredRedirectUri`,
+ * RFC 8252 anti-open-redirect), so the public-origin redirect_uri is rejected
+ * ("Redirect mismatch") and no off-localhost user can sign in.
+ *
+ * THE FIX. At DCR time, for each submitted redirect_uri WHOSE ORIGIN IS ONE
+ * OF THE HUB'S OWN KNOWN ORIGINS (issuer, expose-state hubOrigin, platform
+ * origin, loopback aliases — i.e. the same set `buildHubBoundOrigins`
+ * produces), ALSO register the same PATH on every OTHER known hub origin. A
+ * loopback-registered hub-served client thus becomes valid on the public hub
+ * origin too, without ever loosening the strict authorize-time match.
+ *
+ * THE INVARIANT (no open redirect). Expansion ONLY ever produces URIs rooted
+ * at the hub's OWN known origins. A submitted redirect_uri whose origin is
+ * FOREIGN — a separate-origin surface on its own domain (e.g. my-vault-ui at
+ * `https://notes.example`), a third-party app — is stored VERBATIM: not
+ * expanded onto any hub origin, and not dropped. Only hub-origin-rooted URIs
+ * receive the cross-origin fan-out. Because authorize-time matching stays
+ * strict exact-match against this stored set, an attacker who registers a
+ * foreign redirect_uri gets back exactly what they submitted (no hub-origin
+ * variant minted for them), and a hub-origin-rooted URI only ever fans out to
+ * other hub origins the operator already controls.
+ *
+ * Order-preserving + de-duplicated: the originally-submitted URIs come first
+ * (preserving caller order), with the synthesized hub-origin variants
+ * appended in a stable order; duplicates are collapsed.
+ */
+export function expandRedirectUrisForHubOrigins(
+  submitted: readonly string[],
+  hubOrigins: readonly string[],
+): string[] {
+  // Parse the hub's known origins into a Set for membership tests. Malformed
+  // entries are skipped — the function fails safe (no expansion) rather than
+  // throwing.
+  const hubOriginSet = new Set<string>();
+  for (const raw of hubOrigins) {
+    try {
+      hubOriginSet.add(new URL(raw).origin);
+    } catch {
+      // Skip malformed hub origin.
+    }
+  }
+
+  // Preserve submitted order + dedupe; append synthesized variants after.
+  const out: string[] = [];
+  const seen = new Set<string>();
+  const push = (uri: string) => {
+    if (seen.has(uri)) return;
+    seen.add(uri);
+    out.push(uri);
+  };
+
+  // 1) Every submitted URI is stored as-is (foreign + hub-origin alike). This
+  //    is what guarantees a foreign redirect_uri is never dropped.
+  for (const uri of submitted) push(uri);
+
+  // 2) For each submitted URI rooted at a hub origin, synthesize the same path
+  //    on every OTHER hub origin. Foreign-origin URIs are skipped here — they
+  //    never spawn a hub-origin variant (the open-redirect guard).
+  if (hubOriginSet.size > 1) {
+    for (const uri of submitted) {
+      let parsed: URL;
+      try {
+        parsed = new URL(uri);
+      } catch {
+        continue;
+      }
+      if (!hubOriginSet.has(parsed.origin)) continue; // foreign → no expansion
+      const pathSuffix = `${parsed.pathname}${parsed.search}${parsed.hash}`;
+      for (const origin of hubOriginSet) {
+        if (origin === parsed.origin) continue;
+        push(`${origin}${pathSuffix}`);
+      }
+    }
+  }
+
+  return out;
+}
+
 export function verifyClientSecret(client: OAuthClient, presented: string): boolean {
   if (!client.clientSecretHash) return false;
   const presentedHash = createHash("sha256").update(presented).digest("hex");

package/src/commands/install.ts

@@ -125,9 +125,16 @@ export function resolveInstallChannel(opts: {
  * install lens` during the ~3-day window keeps working. Remove after
  * launch sinks in and `parachute install lens` has stopped appearing
  * in support threads.
+ *
+ * `channel → agent` (2026-06-17): parachute-channel was renamed to
+ * parachute-agent. `parachute install channel` keeps resolving to the
+ * agent module for one release cycle so operators mid-upgrade aren't
+ * stranded. Remove alongside the `parachute-channel → agent` legacy
+ * manifest alias in service-spec.ts.
  */
 const SERVICE_ALIASES: Record<string, string> = {
   lens: "notes",
+  channel: "agent",
 };
 
 export interface InstallOpts {