@openparachute/hub 0.6.1-rc.2 → 0.6.1-rc.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.6.1-rc.2",
+  "version": "0.6.1-rc.3",
   "description": "parachute \u2014 the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/oauth-handlers.test.ts

@@ -95,7 +95,10 @@ function fixtureLoadServicesManifest(): ServicesManifest {
 
 describe("authorizationServerMetadata", () => {
   test("emits RFC 8414 fields rooted at the issuer", async () => {
-    const res = authorizationServerMetadata({ issuer: ISSUER });
+    const res = authorizationServerMetadata({
+      issuer: ISSUER,
+      loadServicesManifest: fixtureLoadServicesManifest,
+    });
     expect(res.status).toBe(200);
     const body = (await res.json()) as Record<string, unknown>;
     expect(body.issuer).toBe(ISSUER);
@@ -110,15 +113,21 @@ describe("authorizationServerMetadata", () => {
     const scopesSupported = body.scopes_supported as string[];
     expect(scopesSupported).toContain("vault:read");
     expect(scopesSupported).toContain("vault:admin");
-    expect(scopesSupported).toContain("scribe:transcribe");
+    expect(scopesSupported).toContain("scribe:transcribe"); // scribe is in the fixture manifest
     expect(scopesSupported).toContain("hub:admin");
+    // channel isn't in the fixture manifest → its scopes aren't advertised
+    // (hub#…: optional-module scopes only surface when the module is installed).
+    expect(scopesSupported).not.toContain("channel:send");
   });
 
   test("does NOT advertise non-requestable operator-only scopes", async () => {
     // #96: parachute:host:admin is operator-only. RFC 8414 §2 frames
     // scopes_supported as scopes a client *can* request — advertising what
     // we always reject would mislead clients.
-    const res = authorizationServerMetadata({ issuer: ISSUER });
+    const res = authorizationServerMetadata({
+      issuer: ISSUER,
+      loadServicesManifest: fixtureLoadServicesManifest,
+    });
     const body = (await res.json()) as Record<string, unknown>;
     const scopesSupported = body.scopes_supported as string[];
     expect(scopesSupported).not.toContain("parachute:host:admin");
@@ -143,6 +152,7 @@ describe("authorizationServerMetadata", () => {
     const res = authorizationServerMetadata({
       issuer: ISSUER,
       loadDeclaredScopes: () => declared,
+      loadServicesManifest: fixtureLoadServicesManifest,
     });
     const body = (await res.json()) as Record<string, unknown>;
     const scopesSupported = body.scopes_supported as string[];
@@ -157,11 +167,84 @@ describe("authorizationServerMetadata", () => {
     // NON_REQUESTABLE filter still applies even when the scope is declared
     expect(scopesSupported).not.toContain("parachute:host:admin");
   });
+
+  test("advertises an optional module's scopes only when it's installed", async () => {
+    // FIRST_PARTY_SCOPES carries scribe:* + channel:send statically. On a
+    // vault-only hub they must NOT be advertised — a discovery client (e.g.
+    // claude.ai's connector UI) lists the catalog verbatim, so a friend
+    // connecting one vault was shown Scribe + Channel access the hub can't
+    // honor. Vault + hub are core and always advertised.
+    const declared = new Set<string>([
+      "vault:read",
+      "vault:write",
+      "vault:admin",
+      "scribe:transcribe",
+      "scribe:admin",
+      "channel:send",
+      "hub:admin",
+    ]);
+    const vaultOnly = {
+      services: [
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/health",
+          version: "0.5.1",
+        },
+      ],
+    };
+    const res = authorizationServerMetadata({
+      issuer: ISSUER,
+      loadDeclaredScopes: () => declared,
+      loadServicesManifest: () => vaultOnly as unknown as ServicesManifest,
+    });
+    const scopes = ((await res.json()) as Record<string, unknown>).scopes_supported as string[];
+    // core scopes survive
+    expect(scopes).toContain("vault:read");
+    expect(scopes).toContain("vault:admin");
+    expect(scopes).toContain("hub:admin");
+    // uninstalled optional-module scopes are dropped
+    expect(scopes).not.toContain("scribe:transcribe");
+    expect(scopes).not.toContain("scribe:admin");
+    expect(scopes).not.toContain("channel:send");
+
+    // ...but once scribe is installed, its scopes ARE advertised again.
+    const withScribe = {
+      services: [
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/health",
+          version: "0.5.1",
+        },
+        {
+          name: "parachute-scribe",
+          port: 1943,
+          paths: ["/scribe"],
+          health: "/health",
+          version: "0.4.5",
+        },
+      ],
+    };
+    const res2 = authorizationServerMetadata({
+      issuer: ISSUER,
+      loadDeclaredScopes: () => declared,
+      loadServicesManifest: () => withScribe as unknown as ServicesManifest,
+    });
+    const scopes2 = ((await res2.json()) as Record<string, unknown>).scopes_supported as string[];
+    expect(scopes2).toContain("scribe:transcribe");
+    expect(scopes2).not.toContain("channel:send"); // channel still not installed
+  });
 });
 
 describe("protectedResourceMetadata (RFC 9728, closes hub#393)", () => {
   test("emits the required RFC 9728 fields rooted at the issuer", async () => {
-    const res = protectedResourceMetadata({ issuer: ISSUER });
+    const res = protectedResourceMetadata({
+      issuer: ISSUER,
+      loadServicesManifest: fixtureLoadServicesManifest,
+    });
     expect(res.status).toBe(200);
     expect(res.headers.get("content-type")).toMatch(/application\/json/);
     const body = (await res.json()) as Record<string, unknown>;
@@ -185,6 +268,7 @@ describe("protectedResourceMetadata (RFC 9728, closes hub#393)", () => {
     const res = protectedResourceMetadata({
       issuer: ISSUER,
       loadDeclaredScopes: () => declared,
+      loadServicesManifest: fixtureLoadServicesManifest,
     });
     const body = (await res.json()) as Record<string, unknown>;
     const scopes = body.scopes_supported as string[];
@@ -3904,7 +3988,10 @@ describe("refresh-token rotation + /oauth/revoke (#73)", () => {
   });
 
   test("authorizationServerMetadata advertises revocation_endpoint", async () => {
-    const res = authorizationServerMetadata({ issuer: ISSUER });
+    const res = authorizationServerMetadata({
+      issuer: ISSUER,
+      loadServicesManifest: fixtureLoadServicesManifest,
+    });
     const body = (await res.json()) as Record<string, unknown>;
     expect(body.revocation_endpoint).toBe(`${ISSUER}/oauth/revoke`);
   });

package/src/oauth-handlers.ts

@@ -388,13 +388,53 @@ function oauthErrorRedirect(
  *
  * Closes hub#393.
  */
+
+/**
+ * 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
+ * advertised; these are the modules a hub may not have.
+ */
+const OPTIONAL_MODULE_SCOPES: ReadonlyArray<readonly [prefix: string, service: string]> = [
+  ["scribe:", "parachute-scribe"],
+  ["channel:", "parachute-channel"],
+];
+
+/**
+ * The scope set to advertise in `scopes_supported` (RFC 8414 + RFC 9728): the
+ * requestable declared scopes, minus any OPTIONAL module's scopes when that
+ * 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
+ * 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
+ * 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));
+  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;
+      }
+      return true;
+    });
+}
+
 export function protectedResourceMetadata(deps: OAuthDeps): Response {
   const iss = deps.issuer;
   const declared = (deps.loadDeclaredScopes ?? loadDeclaredScopes)();
   return jsonResponse({
     resource: iss,
     authorization_servers: [iss],
-    scopes_supported: Array.from(declared).filter(isRequestableScope),
+    scopes_supported: advertisedScopes(
+      declared,
+      (deps.loadServicesManifest ?? readServicesManifest)(),
+    ),
     bearer_methods_supported: ["header"],
     resource_documentation: "https://parachute.computer",
     // Intentional omission: `resource_signing_alg_values_supported` +
@@ -435,7 +475,10 @@ export function authorizationServerMetadata(deps: OAuthDeps): Response {
     // — RFC 8414 §2 frames `scopes_supported` as "the OAuth 2.0 [...] scope
     // values that this authorization server supports" for clients to request.
     // Advertising what we always reject would mislead clients.
-    scopes_supported: Array.from(declared).filter(isRequestableScope),
+    scopes_supported: advertisedScopes(
+      declared,
+      (deps.loadServicesManifest ?? readServicesManifest)(),
+    ),
   });
 }
 

package/src/scope-explanations.ts

@@ -45,6 +45,12 @@ 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
+  // (= 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
+  // for another optional module here, add a matching gate there too, or a
+  // vault-only hub will over-advertise them (the bug behind hub#489).
   "scribe:transcribe": {
     label: "Send audio to Scribe for transcription.",
     level: "write",