@openparachute/hub 0.5.13 → 0.5.14-rc.10

package/src/resource-binding.ts

@@ -0,0 +1,134 @@
+/**
+ * RFC 8707 (Resource Indicators for OAuth 2.0) resource-binding helpers.
+ *
+ * An MCP client connecting to a single vault (`<origin>/vault/<name>/mcp`)
+ * discovers the hub as its authorization server via the RFC 9728 challenge
+ * (`WWW-Authenticate: Bearer resource_metadata=…`) → per-vault Protected
+ * Resource Metadata. A spec-following client then sends the `resource`
+ * parameter on `/oauth/authorize` naming that exact MCP endpoint.
+ *
+ * Before this module the hub dropped `resource` on the floor: the consent
+ * screen advertised the ENTIRE scope catalog (every vault + hub:admin +
+ * scribe:admin …) and the minted token's audience was derived purely from
+ * the operator's manual vault-picker choice. Two failures fell out:
+ *
+ *   1. Scary consent — a friend connecting to ONE vault saw the whole hub's
+ *      scope surface.
+ *   2. Broad-scope rejection — an unnamed `vault:read` token (the shape a
+ *      client gets when it never picks a specific vault) is REJECTED by a
+ *      current-line vault (`findBroadVaultScopes`), because hub-issued tokens
+ *      must carry resource-narrowed `vault:<name>:<verb>` scopes + a matching
+ *      `aud=vault.<name>`.
+ *
+ * This module consumes `resource` end-to-end: when it resolves to a per-vault
+ * MCP resource we derive `<name>`, narrow the consent scope list to that
+ * vault's named scopes, lock the picker to `<name>`, and mint named scopes so
+ * `inferAudience` stamps `aud=vault.<name>`.
+ *
+ * Source of truth for scope shape: `parachute-patterns/patterns/oauth-scopes.md`.
+ */
+
+import { VAULT_VERBS } from "./jwt-audience.ts";
+
+/**
+ * Two recognised per-vault resource shapes, both rooted at the hub origin:
+ *
+ *   - the MCP endpoint:  `<origin>/vault/<name>/mcp`  (the canonical RFC 8707
+ *     resource indicator the PRM `resource` field advertises and a spec-
+ *     following client echoes back);
+ *   - the PRM document:  `<origin>/vault/<name>/.well-known/oauth-protected-resource`
+ *     (some clients send the metadata URL itself as the resource).
+ *
+ * A trailing slash and any query/fragment are tolerated. Capture group 1 is
+ * the vault instance name (same `[^/]+` shape `vaultInstanceNameFor` derives
+ * from a `/vault/<name>` path).
+ */
+const VAULT_MCP_PATH_RE = /^\/vault\/([^/]+)\/mcp\/?$/;
+const VAULT_PRM_PATH_RE = /^\/vault\/([^/]+)\/\.well-known\/oauth-protected-resource\/?$/;
+
+/**
+ * Resolve the RFC 8707 `resource` parameter to a vault instance name, or null
+ * when it isn't a per-vault MCP resource (absent, malformed, off-origin, or a
+ * non-vault path). Off-origin resources return null deliberately: we only
+ * narrow consent for resources the hub itself fronts, so a `resource` naming
+ * some third party's URL can't drive the vault-narrowing path.
+ *
+ * `boundOrigins` is the hub's own origin set (issuer + loopback + tailnet +
+ * funnel — same set the same-origin CSRF gate uses). A resource whose origin
+ * isn't in that set is treated as not-ours.
+ *
+ * The vault name is NOT validated against the live services.json here — that
+ * check stays where it already lives (the consent picker / submit defenses).
+ * This helper's only job is shape recognition + name extraction.
+ */
+export function resolveResourceVault(
+  resource: string | null | undefined,
+  boundOrigins: readonly string[],
+): string | null {
+  if (!resource) return null;
+  let parsed: URL;
+  try {
+    parsed = new URL(resource);
+  } catch {
+    return null;
+  }
+  if (!boundOrigins.includes(parsed.origin)) return null;
+  const mcp = VAULT_MCP_PATH_RE.exec(parsed.pathname);
+  if (mcp?.[1]) return decodeVaultName(mcp[1]);
+  const prm = VAULT_PRM_PATH_RE.exec(parsed.pathname);
+  if (prm?.[1]) return decodeVaultName(prm[1]);
+  return null;
+}
+
+/** Canonical vault-name shape — mirrors `VAULT_SCOPED_RE`'s name group. */
+const VAULT_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * Decode a captured path segment into a vault name, returning null when it
+ * isn't a well-formed vault name. Two failure modes both fall through to the
+ * unbound flow (no narrowing, no junk mint):
+ *
+ *   - malformed percent-escape (`%GG`) → `decodeURIComponent` throws → null.
+ *     A bad `resource` must degrade gracefully, not 500 the authorize handler.
+ *   - decoded value isn't `[a-zA-Z0-9_-]+` → null. The `[^/]+` path capture
+ *     admits anything between slashes; a crafted `resource=…/vault/%2F..%2Fadmin/mcp`
+ *     decodes to `/../admin`, which would otherwise mint a token stamped
+ *     `aud=vault./../admin`. Harmless (the resource server rejects it) but it's
+ *     audit-log noise + a minting path for non-vault names. Anchoring the name
+ *     to the canonical shape closes it. Matches `VAULT_SCOPED_RE`'s name group
+ *     so what we accept here is exactly what a vault scope can name.
+ */
+function decodeVaultName(segment: string): string | null {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(segment);
+  } catch {
+    return null;
+  }
+  return VAULT_NAME_RE.test(decoded) ? decoded : null;
+}
+
+/**
+ * Rewrite the requested scope list for a resource-bound vault flow.
+ *
+ *   - unnamed `vault:<verb>`        → `vault:<name>:<verb>` (the narrow,
+ *     audience-correct shape vault accepts);
+ *   - 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:transcribe`, `hub:admin`, …) pass through
+ *     unchanged — resource-binding only narrows the vault verbs.
+ *
+ * Idempotent: a scope already shaped `vault:<name>:<verb>` for THIS name is
+ * returned as-is, so re-running over a narrowed list is a no-op.
+ */
+export function narrowResourceVaultScopes(scopes: readonly string[], vaultName: string): string[] {
+  return scopes.map((s) => {
+    const parts = s.split(":");
+    const verb = parts[1];
+    if (parts.length === 2 && parts[0] === "vault" && verb && VAULT_VERBS.has(verb)) {
+      return `vault:${vaultName}:${verb}`;
+    }
+    return s;
+  });
+}

package/src/scope-attenuation.ts

@@ -0,0 +1,85 @@
+/**
+ * Capability attenuation — the shared authority model behind both the
+ * mint side (`/api/auth/mint-token`, hub#452) and the revoke side
+ * (`/api/auth/revoke-token`). The two endpoints are symmetric: you may
+ * revoke exactly what you could have minted.
+ *
+ * `canGrant(bearerScopes, scope)` answers: could a bearer holding
+ * `bearerScopes` mint a token carrying `scope`? It is the single source of
+ * truth for "is `scope` within this bearer's authority" — mint uses it to
+ * gate what a request may issue; revoke uses it to gate what a request may
+ * tear down (every recorded scope on the target jti must be `canGrant`-able).
+ *
+ * `hasMintingAuthority(bearerScopes)` is the cheap entry gate: does the
+ * bearer hold ANY authority at all (host:auth, host:admin, or some
+ * `vault:<*>:admin`)? A bearer with none can neither mint nor revoke via
+ * attenuation, so both endpoints 403 it before any per-scope work.
+ *
+ * Pure functions — no DB, no I/O — so they're trivially testable and both
+ * handlers stay thin.
+ */
+import { isNonRequestableScope, isVaultAdminScope, vaultScopeName } from "./scope-explanations.ts";
+
+/**
+ * Bearer scope that authorises minting any *requestable* scope (rule 1 of the
+ * attenuation model). The operator's admin scope-set carries this; a narrow
+ * `--scope-set=auth` operator token carries it too.
+ */
+export const MINT_HOST_AUTH_SCOPE = "parachute:host:auth";
+/**
+ * Bearer scope that authorises minting `vault:<name>:admin` (rule 2).
+ * `parachute:host:admin` already implies box-wide administration of every
+ * vault on the hub, so minting a vault-pinned admin from it is a privilege
+ * *reduction* (de-escalation), not an escalation — see the design doc
+ * `2026-05-28-operator-mintable-vault-admin.md`.
+ */
+export const MINT_HOST_ADMIN_SCOPE = "parachute:host:admin";
+
+/**
+ * Capability attenuation: can a bearer holding `bearerScopes` mint a token
+ * carrying `requestedScope`? True iff the requested scope is a subset of the
+ * bearer's own authority under one of three rules:
+ *
+ *   1. requestable + bearer has `parachute:host:auth`;
+ *   2. `vault:<N>:admin` + bearer has `parachute:host:admin`;
+ *   3. `vault:<N>:<verb>` + bearer has `vault:<N>:admin` (same `<N>`).
+ *
+ * Pure function — no DB, no I/O — so it's trivially testable and the guard in
+ * each handler is a single `scopes.filter((s) => !canGrant(bearerScopes, s))`.
+ *
+ * On the revoke side this is the symmetric rule: a target jti is revocable by
+ * a non-host:auth bearer iff EVERY one of its recorded scopes is `canGrant`-able
+ * — i.e. the bearer could have minted that token, so it may also tear it down.
+ * Cross-vault and host-authority targets are never `canGrant`-able by a mere
+ * `vault:<N>:admin` bearer, so it can neither mint nor revoke them.
+ */
+export function canGrant(bearerScopes: string[], requestedScope: string): boolean {
+  // Rule 1 — host:auth mints any requestable scope.
+  if (!isNonRequestableScope(requestedScope) && bearerScopes.includes(MINT_HOST_AUTH_SCOPE)) {
+    return true;
+  }
+  // Rule 2 — host:admin attenuates to a named vault's admin.
+  if (isVaultAdminScope(requestedScope) && bearerScopes.includes(MINT_HOST_ADMIN_SCOPE)) {
+    return true;
+  }
+  // Rule 3 — vault:<N>:admin attenuates to any same-vault subset (incl. admin).
+  const requestedVault = vaultScopeName(requestedScope);
+  if (requestedVault !== null && bearerScopes.includes(`vault:${requestedVault}:admin`)) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Does the bearer hold ANY minting authority? Entry gate before per-scope
+ * checks — a bearer with none (e.g. a read-only token) can mint (or revoke
+ * via attenuation) nothing, so both endpoints 403 it early rather than
+ * walking every scope to the same end.
+ */
+export function hasMintingAuthority(bearerScopes: string[]): boolean {
+  return (
+    bearerScopes.includes(MINT_HOST_AUTH_SCOPE) ||
+    bearerScopes.includes(MINT_HOST_ADMIN_SCOPE) ||
+    bearerScopes.some((s) => isVaultAdminScope(s))
+  );
+}

package/src/scope-explanations.ts

@@ -138,17 +138,106 @@ export const NON_REQUESTABLE_SCOPES: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * Per-vault `vault:<name>:admin` scopes are also non-requestable: they let
- * the holder mint, revoke, and rotate tokens for a specific vault instance,
- * which is operator-only territory. Like `parachute:host:admin`, these are
- * minted by a session-cookie-gated hub endpoint (`/admin/vault-admin-token/:name`),
- * never by the public OAuth flow.
+ * Per-vault `vault:<name>:admin` scopes are also non-requestable via the
+ * public OAuth flow: they let the holder mint, revoke, and rotate tokens
+ * for a specific vault instance, which is operator-only territory.
+ *
+ * They are mintable by operator-proving local paths, all of which require
+ * already-established authority (never third-party consent):
+ *   - the session-cookie-gated `/admin/vault-admin-token/:name` endpoint
+ *     (the vault SPA's Manage link + setup wizard); and
+ *   - `POST /api/auth/mint-token` under the capability-attenuation model —
+ *     a `parachute:host:admin` bearer (box-wide → one-vault) or a
+ *     `vault:<name>:admin` bearer (same-vault subset). The same model governs
+ *     `POST /api/auth/revoke-token` (revoke what you could mint). See
+ *     `canGrant` in `scope-attenuation.ts` and the guards in
+ *     `api-mint-token.ts` / `api-revoke-token.ts`.
  *
  * Pattern-based because the set is open-ended — every vault instance the
  * operator creates implies a new scope, and we don't want to enumerate them.
  */
 const VAULT_ADMIN_RE = /^vault:[a-zA-Z0-9_-]+:admin$/;
 
+/**
+ * Any per-vault scope: `vault:<name>:<verb>` for verb ∈ {read, write, admin}.
+ * Captures the name in group 1 and the verb in group 2. Used by the
+ * mint-token capability-attenuation model to recognise the scopes a
+ * `vault:<name>:admin` bearer may attenuate to (same-vault subsets).
+ */
+const VAULT_SCOPED_RE = /^vault:([a-zA-Z0-9_-]+):(read|write|admin)$/;
+
+/**
+ * True when `scope` is a per-vault admin scope (`vault:<name>:admin`).
+ * Exported so the mint-token path can recognise the one non-requestable
+ * scope it conditionally admits for `parachute:host:admin` bearers.
+ */
+export function isVaultAdminScope(scope: string): boolean {
+  return VAULT_ADMIN_RE.test(scope);
+}
+
+/**
+ * Extract the vault name from ANY per-vault scope (`vault:<name>:<verb>` for
+ * verb ∈ {read, write, admin}), or null if the scope isn't per-vault-scoped.
+ * Used by the mint-token attenuation model to (a) match a `vault:<name>:admin`
+ * bearer against same-vault requested scopes, and (b) derive the `vault_scope`
+ * pin for every vault-scoped mint regardless of verb.
+ */
+export function vaultScopeName(scope: string): string | null {
+  const m = VAULT_SCOPED_RE.exec(scope);
+  return m ? (m[1] ?? null) : null;
+}
+
+/**
+ * Mint-time shape guard: reject scopes that LOOK like a *named* per-vault scope
+ * (`vault:<name>:<verb>`, three+ colon-segments, first segment `vault`
+ * case-insensitively to catch `VAULT:…`) but are malformed — i.e. they don't
+ * match the strict `vault:<name>:<read|write|admin>` shape (`VAULT_SCOPED_RE`).
+ *
+ * Returns true for (i.e. ADMITS):
+ *   - well-formed named scopes `vault:<name>:<read|write|admin>`;
+ *   - the canonical *unnamed* two-segment scopes `vault:read|write|admin`
+ *     (legitimate OAuth/consent forms — keys in `SCOPE_EXPLANATIONS`, narrowed
+ *     to a named vault at consent time) and any other non-three-segment
+ *     `vault`-prefixed string — those aren't attempting the named shape, so
+ *     they're out of this guard's remit and keep their existing behaviour;
+ *   - every non-vault scope (`scribe:transcribe`, `parachute:host:*`, …).
+ *
+ * Returns false for (i.e. REJECTS) only a `vault`-prefixed string with three
+ * or more colon-segments that fails `VAULT_SCOPED_RE`:
+ *   `vault:work:ADMIN` (uppercase verb), `vault::admin` (empty name),
+ *   `vault:work:read:admin` (extra segment), `VAULT:work:admin` (uppercase
+ *   resource).
+ *
+ * Why this exists (defensive hygiene — adversarial audit, 2026-05-28): a
+ * `parachute:host:auth` bearer can today mint those four malformed strings.
+ * `isNonRequestableScope`'s strict regexes don't match them, so `canGrant`
+ * rule 1 admits them as "requestable" — the mint succeeds (200) carrying the
+ * literal junk string and writes a registry row. They grant ZERO access today
+ * (the vault consumer's `decomposeVaultScope` is case-sensitive + anchored and
+ * rejects all four), so this is NOT exploitable now. The value is (a) registry
+ * hygiene (no junk rows) and (b) a backstop against a FUTURE consumer-
+ * normalization regression — if vault ever started case-folding scope verbs,
+ * those junk tokens could silently become live admin. A strict mint-time shape
+ * check closes that door now.
+ *
+ * Orthogonal to authority: this is an input-shape check applied to ALL mint
+ * callers (host:auth, host:admin, vault:<name>:admin) before any `canGrant`
+ * attenuation. It does not affect non-vault scopes or the unnamed `vault:<verb>`
+ * forms.
+ */
+export function isWellFormedOrNonVaultScope(scope: string): boolean {
+  const segments = scope.split(":");
+  // Only constrain the *named* per-vault shape: first segment names the vault
+  // resource (case-insensitive, to catch `VAULT:`) AND there are three or more
+  // segments (an attempt at `vault:<name>:<verb>`). The unnamed two-segment
+  // forms (`vault:read|write|admin`) and a bare `vault` are out of remit.
+  const firstSegment = segments[0] ?? "";
+  if (firstSegment.toLowerCase() !== "vault" || segments.length < 3) {
+    return true;
+  }
+  return VAULT_SCOPED_RE.test(scope);
+}
+
 /** True when the scope is non-requestable via the public OAuth flow. */
 export function isNonRequestableScope(scope: string): boolean {
   return NON_REQUESTABLE_SCOPES.has(scope) || VAULT_ADMIN_RE.test(scope);

package/src/service-spec.ts

@@ -68,7 +68,7 @@ export const PORT_RESERVATIONS: readonly PortReservation[] = [
   // fallback-port walker (`assignPort` in port-assign.ts) from handing this
   // port out to a colliding third-party module. The matching KNOWN_MODULES
   // row carries the canonicalPort + paths for status/expose surfaces.
-  { port: 1946, name: "parachute-app", status: "assigned" },
+  { port: 1946, name: "parachute-surface", status: "assigned" },
   { port: 1947, name: "unassigned", status: "reserved" },
   { port: 1948, name: "unassigned", status: "reserved" },
   { port: 1949, name: "unassigned", status: "reserved" },
@@ -281,7 +281,7 @@ const NOTES_FALLBACK: FirstPartyFallback = {
     name: "notes",
     manifestName: "parachute-notes",
     displayName: "Notes",
-    tagline: "Notes PWA — daemon deprecated 2026-05-22; install `app` for the current path.",
+    tagline: "Notes PWA — daemon deprecated 2026-05-22; install `surface` for the current path.",
     port: 1942,
     paths: ["/notes"],
     health: "/notes/health",
@@ -462,28 +462,29 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
       hasAuth: true,
     },
   },
-  app: {
-    short: "app",
-    package: "@openparachute/app",
-    manifestName: "parachute-app",
+  surface: {
+    short: "surface",
+    package: "@openparachute/surface",
+    manifestName: "parachute-surface",
     canonicalPort: 1946,
-    displayName: "App",
+    displayName: "Surface",
     // Tagline telegraphs the auto-bootstrap so wizard + admin-SPA copy explain
-    // the architecture: installing `app` brings Notes (and other UIs) along
-    // via the Phase 2.1 bootstrap-default-apps step. The notes-daemon path
-    // still exists as a back-compat install (CURATED_MODULES still lists
-    // `notes`) but `app` is the recommended first install post-vault.
-    tagline: "Host module for Parachute UIs — auto-installs Notes on first boot.",
-    canonicalPaths: ["/app", "/.parachute"],
-    canonicalHealth: "/app/healthz",
+    // the architecture: installing `surface` brings Notes (and other UIs)
+    // along via the Phase 2.1 bootstrap-default-apps step. The notes-daemon
+    // path still exists as a back-compat install (CURATED_MODULES still
+    // lists `notes`) but `surface` is the recommended first install
+    // post-vault. Renamed from `app` 2026-05-27 per patterns#102.
+    tagline: "Host module for Parachute surfaces — auto-installs Notes on first boot.",
+    canonicalPaths: ["/surface", "/.parachute"],
+    canonicalHealth: "/surface/healthz",
     canonicalStripPrefix: false,
     extras: {
       // Backward-compat startCmd — same rationale as scribe / vault / runner
       // above. Post-self-register, lifecycle reads module.json's startCmd via
       // `composeKnownModuleSpec` and that path wins.
-      startCmd: () => ["parachute-app", "serve"],
-      // App's admin + per-UI surfaces gate behind hub-issued JWTs (design
-      // doc §6 same-hub auto-trust + scope `app:admin`). Surfaces in
+      startCmd: () => ["parachute-surface", "serve"],
+      // Surface's admin + per-UI surfaces gate behind hub-issued JWTs (design
+      // doc §6 same-hub auto-trust + scope `surface:admin`). Surfaces in
       // `parachute status` as auth-required by default, same posture as vault
       // + runner.
       hasAuth: true,
@@ -516,7 +517,27 @@ export const KNOWN_MODULES: Record<string, KnownModule> = {
 export const RETIRED_MODULES: Record<string, { retiredAt: string; replacement?: string }> = {
   agent: {
     retiredAt: "2026-05-20",
-    replacement: "parachute-app or parachute-runner (depending on use case)",
+    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)",
+  },
+  // 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
+  // pointing at the now-removed @openparachute/app package; this entry
+  // drops it on load + steers them at `parachute install surface`.
+  // The short-name `app` form is included for legacy rows that used
+  // the short name as the `name` field.
+  app: {
+    retiredAt: "2026-05-27",
+    replacement: "parachute-surface (renamed from parachute-app — `parachute install surface`)",
+  },
+  "parachute-app": {
+    retiredAt: "2026-05-27",
+    replacement: "parachute-surface (renamed from parachute-app — `parachute install surface`)",
   },
 };