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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.6.1-rc.1",
+  "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__/auth.test.ts

@@ -1696,7 +1696,76 @@ describe("parachute auth mint-token", () => {
       expect(stdout.trim().split(".").length).toBe(3);
       expect(stderr).toContain("--ttl is deprecated");
       expect(stderr).toContain("--expires-in");
-      expect(stderr).toContain("0.6.0");
+      expect(stderr).toContain("future release");
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("--ephemeral mints a short-lived (1h) token", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = {
+        dbPath: tmp.dbPath,
+        configDir: tmp.dir,
+        isInteractive: () => false,
+      };
+      await captureOutput(() => auth(["set-password", "--password", "pw"], deps));
+      const { code, stdout } = await captureOutput(() =>
+        auth(["mint-token", "--scope", "vault:default:read", "--ephemeral"], deps),
+      );
+      expect(code).toBe(0);
+      const token = stdout.trim();
+      const db = openHubDb(tmp.dbPath);
+      try {
+        const validated = await validateAccessToken(db, token);
+        const exp = validated.payload.exp as number;
+        const iat = validated.payload.iat as number;
+        expect(exp - iat).toBe(60 * 60);
+      } finally {
+        db.close();
+      }
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("--ephemeral is mutually exclusive with --expires-in", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = {
+        dbPath: tmp.dbPath,
+        configDir: tmp.dir,
+        isInteractive: () => false,
+      };
+      await captureOutput(() => auth(["set-password", "--password", "pw"], deps));
+      const { code, stdout, stderr } = await captureOutput(() =>
+        auth(["mint-token", "--scope", "vault:read", "--ephemeral", "--expires-in", "3600"], deps),
+      );
+      expect(code).toBe(1);
+      expect(stderr).toContain("--ephemeral");
+      // No token leaked to stdout on the conflict error.
+      expect(stdout).toBe("");
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("--ephemeral is mutually exclusive with the deprecated --ttl too", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = {
+        dbPath: tmp.dbPath,
+        configDir: tmp.dir,
+        isInteractive: () => false,
+      };
+      await captureOutput(() => auth(["set-password", "--password", "pw"], deps));
+      const { code, stdout, stderr } = await captureOutput(() =>
+        auth(["mint-token", "--scope", "vault:read", "--ephemeral", "--ttl", "1h"], deps),
+      );
+      expect(code).toBe(1);
+      expect(stderr).toContain("--ephemeral");
+      expect(stdout).toBe("");
     } finally {
       tmp.cleanup();
     }

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/commands/auth.ts

@@ -120,10 +120,13 @@ Usage:
                                        Mint a fresh ~/.parachute/operator.token
                                        (set = install|start|expose|auth|vault|admin,
                                        default admin)
-  parachute auth mint-token --scope <scope> [--aud <aud>] [--expires-in <seconds>]
+  parachute auth mint-token --scope <scope> [--aud <aud>]
+                                            [--ephemeral | --expires-in <seconds>]
                                             [--sub <sub>] [--permissions <json>]
                                        Mint a scope-narrow JWT against the
                                        operator's identity (stdout = JWT).
+                                       --ephemeral = short-lived (1h), ideal for
+                                       scripting; default lifetime is 90d.
                                        --ttl <duration> is the deprecated
                                        alias (use --expires-in seconds).
   parachute auth revoke-token <jti>    Mark a registry-row token revoked
@@ -194,6 +197,12 @@ audience defaults via the same inference rule the OAuth flow uses
 colon-prefixed scope's namespace, fallback \`hub\`). Lifetime defaults
 to 90d, caps at 365d.
 
+--ephemeral mints a short-lived (1h) token — the right default for
+scripting, where the credential only needs to outlive the script run.
+Prefer it over a long-lived token for one-off automation:
+\`parachute auth mint-token --scope vault:default:read --ephemeral\`.
+Mutually exclusive with --expires-in / --ttl.
+
 --scope accepts space-separated multi-scope (e.g.
 \`--scope "vault:default:read agent:wovenboulder:invoke"\`).
 
@@ -201,7 +210,7 @@ to 90d, caps at 365d.
 \`--expires-in 86400\` for 1 day). The legacy \`--ttl\` flag accepts a
 duration suffix (\`90d\` / \`24h\` / \`30m\` / \`60s\`) and is supported as
 a deprecated alias; passing it emits a one-line stderr deprecation
-notice. \`--ttl\` will be removed in 0.6.0.
+notice. \`--ttl\` will be removed in a future release.
 
 --permissions accepts a JSON object encoding fine-grained constraints
 beyond OAuth scope (e.g.
@@ -748,6 +757,8 @@ interface MintTokenFlags {
   permissions?: string;
   /** True when --ttl was used (deprecated alias). Triggers a one-line stderr warning. */
   ttlDeprecationSeen?: boolean;
+  /** --ephemeral: short-lived token (EPHEMERAL_TTL_SECONDS), the scripting default. */
+  ephemeral?: boolean;
   error?: string;
 }
 
@@ -759,6 +770,7 @@ function parseMintTokenFlags(args: readonly string[]): MintTokenFlags {
   let sub: string | undefined;
   let permissions: string | undefined;
   let ttlDeprecationSeen = false;
+  let ephemeral = false;
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === "--scope") {
@@ -805,6 +817,8 @@ function parseMintTokenFlags(args: readonly string[]): MintTokenFlags {
     } else if (a?.startsWith("--permissions=")) {
       permissions = a.slice("--permissions=".length);
       if (!permissions) return { error: "--permissions requires a value" };
+    } else if (a === "--ephemeral") {
+      ephemeral = true;
     } else {
       return { error: `unknown flag "${a}"` };
     }
@@ -812,11 +826,21 @@ function parseMintTokenFlags(args: readonly string[]): MintTokenFlags {
   if (ttl !== undefined && expiresIn !== undefined) {
     return { error: "pass --expires-in OR --ttl, not both (--ttl is the deprecated alias)" };
   }
-  return { scope, aud, ttl, expiresIn, sub, permissions, ttlDeprecationSeen };
+  if (ephemeral && (ttl !== undefined || expiresIn !== undefined)) {
+    return {
+      error: "pass --ephemeral OR an explicit lifetime (--expires-in/--ttl), not both",
+    };
+  }
+  return { scope, aud, ttl, expiresIn, sub, permissions, ttlDeprecationSeen, ephemeral };
 }
 
 const MINT_TOKEN_TTL_DEFAULT_SECONDS = 90 * 24 * 60 * 60;
 const MINT_TOKEN_TTL_MAX_SECONDS = 365 * 24 * 60 * 60;
+// --ephemeral: short-lived token for scripting, where the credential only needs
+// to outlive the script run. 1h is long enough to mint → iterate → run, short
+// enough that a leaked scripting token isn't a standing liability like the 90d
+// default would be.
+const EPHEMERAL_TTL_SECONDS = 60 * 60;
 
 /**
  * Parse a Go-ish duration string: integer + one of d/h/m/s. Caps at 365d.
@@ -870,7 +894,7 @@ async function runMintToken(args: readonly string[], deps: AuthDeps): Promise<nu
   if (!flags.scope) {
     console.error("parachute auth mint-token: --scope is required");
     console.error(
-      "usage: parachute auth mint-token --scope <scope> [--aud <aud>] [--expires-in <seconds>] [--sub <sub>] [--permissions <json>]",
+      "usage: parachute auth mint-token --scope <scope> [--aud <aud>] [--ephemeral | --expires-in <seconds>] [--sub <sub>] [--permissions <json>]",
     );
     return 1;
   }
@@ -918,7 +942,11 @@ async function runMintToken(args: readonly string[], deps: AuthDeps): Promise<nu
   }
 
   let ttlSeconds = MINT_TOKEN_TTL_DEFAULT_SECONDS;
-  if (flags.expiresIn) {
+  if (flags.ephemeral) {
+    // Short-lived scripting default — takes precedence (the parse layer already
+    // rejected --ephemeral alongside an explicit --expires-in/--ttl).
+    ttlSeconds = EPHEMERAL_TTL_SECONDS;
+  } else if (flags.expiresIn) {
     const parsed = parseExpiresIn(flags.expiresIn);
     if ("error" in parsed) {
       console.error(`parachute auth mint-token: ${parsed.error}`);
@@ -935,7 +963,7 @@ async function runMintToken(args: readonly string[], deps: AuthDeps): Promise<nu
   }
   if (flags.ttlDeprecationSeen) {
     console.error(
-      "parachute auth mint-token: --ttl is deprecated; use --expires-in <seconds> instead (will be removed in 0.6.0)",
+      "parachute auth mint-token: --ttl is deprecated; use --expires-in <seconds> instead (will be removed in a future release)",
     );
   }
 

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",