Advertise refresh-token grant in OAuth client metadata (#1974)

* Advertise refresh-token grant in OAuth client metadata

* Test OAuth metadata through connection and tool use

* Test queue timeout with a controlled clock

---------

Co-authored-by: Rhys Sullivan <39114868+RhysSullivan@users.noreply.github.com>

Author: baggiiiie

.changeset/cimd-refresh-token.md

@@ -0,0 +1,10 @@
+---
+"@executor-js/api": patch
+---
+
+Advertise refresh-token support in OAuth client ID metadata documents.
+
+OAuth providers may reject the `offline_access` scope when the client's
+metadata declares only the authorization-code grant. Hosted and local client
+metadata now declare both `authorization_code` and `refresh_token`, matching
+Executor's dynamic client registration behavior.

e2e/selfhost/mcp-oauth-cimd-connect.test.ts

@@ -20,7 +20,7 @@ import { visit } from "../src/surfaces/browser";
 const api = composePluginApi([mcpHttpPlugin()] as const);
 
 scenario(
-  "MCP OAuth · advertised CIMD starts authorization without dynamic registration",
+  "MCP OAuth · CIMD advertises refresh support and completes connection without dynamic registration",
   { timeout: 180_000 },
   Effect.scoped(
     Effect.gen(function* () {
@@ -30,7 +30,7 @@ scenario(
       const oauth = yield* OAuthTestServer;
       const server = yield* serveMcpServerWithOAuth(
         () => makeGreetingMcpServer({ name: "cimd-connect-mcp" }),
-        { path: "/mcp" },
+        { path: "/mcp", scopes: ["read", "offline_access"] },
       );
       const identity = yield* target.newIdentity();
       const client = yield* makeApiClient(api, identity);
@@ -69,17 +69,68 @@ scenario(
               authorize,
               "the popup reached the discovered authorization endpoint",
             ).toBeDefined();
-            const clientId = authorize?.query["client_id"];
-            createdClientId = clientId;
+            expect(
+              (authorize?.query["scope"] ?? "").split(" "),
+              "authorization requests the resource's offline access scope",
+            ).toContain("offline_access");
+            const clientId = authorize?.query["client_id"] ?? "";
+            createdClientId = clientId || undefined;
             expect(
               clientId,
               "authorization uses Executor's metadata document as client_id",
             ).toMatch(/^https?:\/\/[^/]+\/api\/oauth\/client-id-metadata\/.+\.json$/);
-            await popup.close();
+            const metadataResponse = await page.request.get(clientId);
+            expect(metadataResponse.status(), "the client metadata document is reachable").toBe(
+              200,
+            );
+            expect(
+              await metadataResponse.json(),
+              "the client declares the grant required by offline_access",
+            ).toMatchObject({
+              grant_types: ["authorization_code", "refresh_token"],
+            });
+            expect(authorize).toBeDefined();
+            // oxlint-disable-next-line executor/no-try-catch-or-throw, executor/no-error-constructor -- test boundary: authorization must exist before completing the flow
+            if (authorize === undefined) throw new Error("Missing authorization request");
+            const completed = await Effect.runPromise(
+              oauth.completeAuthorizationCodeFlow({ authorizationUrl: authorize.url }),
+            );
+            await popup.goto(completed.callbackUrl);
+            await page
+              .getByRole("heading", { name: /Add connection/ })
+              .waitFor({ state: "hidden" });
+            await popup.close().catch(() => undefined);
           });
         });
 
+        const connections = yield* client.connections.list({ query: { integration: slug } });
+        expect(connections, "the OAuth callback saved the connection").toHaveLength(1);
+        const tools = yield* client.tools.list({ query: { integration: slug } });
+        expect(
+          tools.some((tool) => tool.name === "simple_echo"),
+          "authenticated discovery finds the upstream tool",
+        ).toBe(true);
+
+        const invoked = yield* client.executions.execute({
+          payload: {
+            code: `return await ${tools[0]?.address}({});`,
+            autoApprove: true,
+          },
+        });
+        expect(invoked.status).toBe("completed");
+        expect(invoked.text, "the connected tool runs through authenticated MCP").toContain(
+          "mcp-ok",
+        );
+
         const requests = yield* oauth.requests;
+        expect(
+          requests.some(
+            (request) =>
+              request.path === "/token" &&
+              new URLSearchParams(request.body).get("grant_type") === "authorization_code",
+          ),
+          "the callback exchanged the code using the advertised client",
+        ).toBe(true);
         expect(
           requests.filter((request) => request.method === "POST" && request.path === "/register"),
           "CIMD wins when the server also advertises DCR",
@@ -105,5 +156,12 @@ scenario(
         ),
       );
     }),
-  ).pipe(Effect.provide(OAuthTestServer.layer({ clientIdMetadataDocumentSupported: true }))),
+  ).pipe(
+    Effect.provide(
+      OAuthTestServer.layer({
+        clientIdMetadataDocumentSupported: true,
+        scopes: ["read", "offline_access"],
+      }),
+    ),
+  ),
 );

packages/core/api/src/server/oauth-client-metadata.test.ts

@@ -19,6 +19,7 @@ describe("OAuth client ID metadata document", () => {
       "http://100.81.219.45:42384/api/oauth/client-id-metadata/acme.json",
     );
     expect(metadata.redirect_uris).toEqual(["http://100.81.219.45:42384/api/oauth/callback"]);
+    expect(metadata.grant_types).toEqual(["authorization_code", "refresh_token"]);
     expect(metadata.token_endpoint_auth_method).toBe("none");
     expect(metadata.application_type).toBe("web");
   });
@@ -63,6 +64,7 @@ describe("OAuth client ID metadata document", () => {
       "http://localhost/api/oauth/callback",
       "http://[::1]/api/oauth/callback",
     ]);
+    expect(metadata.grant_types).toEqual(["authorization_code", "refresh_token"]);
     expect(metadata.application_type).toBe("native");
   });
 

packages/core/api/src/server/oauth-client-metadata.ts

@@ -9,6 +9,10 @@ export const OAUTH_CLIENT_ID_METADATA_DOCUMENT_TARGET_PATH_PREFIX =
 export const OAUTH_CLIENT_ID_METADATA_DOCUMENT_DEFAULT_TARGET = "default" as const;
 export const OAUTH_CLIENT_ID_METADATA_DOCUMENT_LOCAL_TARGET = "local" as const;
 
+// Keep CIMD aligned with DCR: providers may reject `offline_access` unless the
+// client declares that it can use the refresh-token grant.
+const OAUTH_CLIENT_GRANT_TYPES = ["authorization_code", "refresh_token"] as const;
+
 type MetadataTarget =
   | typeof OAUTH_CLIENT_ID_METADATA_DOCUMENT_DEFAULT_TARGET
   | typeof OAUTH_CLIENT_ID_METADATA_DOCUMENT_LOCAL_TARGET
@@ -19,7 +23,7 @@ interface OAuthClientIdMetadataDocument {
   readonly client_name: string;
   readonly client_uri: string;
   readonly redirect_uris: readonly string[];
-  readonly grant_types: readonly ["authorization_code"];
+  readonly grant_types: typeof OAUTH_CLIENT_GRANT_TYPES;
   readonly response_types: readonly ["code"];
   readonly token_endpoint_auth_method: "none";
   readonly application_type: "web" | "native";
@@ -129,7 +133,7 @@ export const oauthClientIdMetadataDocumentFromRequest = ({
       client_name: "Executor Local",
       client_uri: url.origin,
       redirect_uris: localLoopbackRedirectUris(mountPrefix),
-      grant_types: ["authorization_code"],
+      grant_types: OAUTH_CLIENT_GRANT_TYPES,
       response_types: ["code"],
       token_endpoint_auth_method: "none",
       application_type: "native",
@@ -150,7 +154,7 @@ export const oauthClientIdMetadataDocumentFromRequest = ({
     client_name: "Executor",
     client_uri: url.origin,
     redirect_uris: [redirectUri.toString()],
-    grant_types: ["authorization_code"],
+    grant_types: OAUTH_CLIENT_GRANT_TYPES,
     response_types: ["code"],
     token_endpoint_auth_method: "none",
     application_type: "web",