@vellumai/assistant 0.6.2 → 0.6.4

package/src/__tests__/oauth2-gateway-transport.test.ts

@@ -83,6 +83,7 @@ mock.module("../inbound/platform-callback-registration.js", () => ({
 // Track token exchange request
 let lastTokenRequestBody: URLSearchParams | null = null;
 let lastTokenRequestHeaders: Record<string, string> = {};
+let lastTokenRequestRawBody: string | null = null;
 
 // Mock fetch for token exchange
 let mockTokenResponse: {
@@ -112,7 +113,12 @@ globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
   if (url.includes("token")) {
     // Capture request body and headers for assertions
     if (init?.body) {
-      lastTokenRequestBody = new URLSearchParams(init.body as string);
+      lastTokenRequestRawBody = String(init.body);
+      try {
+        lastTokenRequestBody = new URLSearchParams(init.body as string);
+      } catch {
+        lastTokenRequestBody = null;
+      }
     }
     if (init?.headers) {
       lastTokenRequestHeaders = init.headers as Record<string, string>;
@@ -135,13 +141,18 @@ globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
 // Import module under test AFTER mocks are in place
 // ---------------------------------------------------------------------------
 
-import { type OAuth2Config, startOAuth2Flow } from "../security/oauth2.js";
+import {
+  type OAuth2Config,
+  refreshOAuth2Token,
+  startOAuth2Flow,
+} from "../security/oauth2.js";
 
 const BASE_OAUTH_CONFIG: OAuth2Config = {
-  authUrl: "https://provider.example.com/authorize",
-  tokenUrl: "https://provider.example.com/token",
+  authorizeUrl: "https://provider.example.com/authorize",
+  tokenExchangeUrl: "https://provider.example.com/token",
   scopes: ["read", "write"],
   clientId: "test-client-id",
+  scopeSeparator: " ",
 };
 
 beforeEach(() => {
@@ -150,6 +161,7 @@ beforeEach(() => {
   pendingCallbacks.clear();
   lastTokenRequestBody = null;
   lastTokenRequestHeaders = {};
+  lastTokenRequestRawBody = null;
   mockTokenResponse = {
     ok: true,
     status: 200,
@@ -203,15 +215,19 @@ describe("OAuth2 gateway transport", () => {
     test("falls back to loopback transport when ingress.publicBaseUrl is not configured", async () => {
       mockPublicBaseUrl = "";
 
-      let capturedAuthUrl = "";
+      let resolveOpenUrl!: (url: string) => void;
+      const openUrlPromise = new Promise<string>((resolve) => {
+        resolveOpenUrl = resolve;
+      });
       const flowPromise = startOAuth2Flow(BASE_OAUTH_CONFIG, {
         openUrl: (url) => {
-          capturedAuthUrl = url;
+          resolveOpenUrl(url);
         },
       });
 
-      // Give the loopback server time to start
-      await new Promise((r) => setTimeout(r, 50));
+      // Wait for the loopback server to bind and build the auth URL.
+      // Awaiting the openUrl callback instead of a fixed timer avoids CI-load flakes.
+      const capturedAuthUrl = await openUrlPromise;
 
       // Auth URL should use a localhost redirect_uri
       expect(capturedAuthUrl).toContain("redirect_uri=");
@@ -219,9 +235,9 @@ describe("OAuth2 gateway transport", () => {
       expect(capturedAuthUrl).toContain(encodeURIComponent("/oauth/callback"));
 
       // Extract the redirect_uri and simulate the callback
-      const authUrl = new URL(capturedAuthUrl);
-      const redirectUri = authUrl.searchParams.get("redirect_uri")!;
-      const state = authUrl.searchParams.get("state")!;
+      const authorizeUrl = new URL(capturedAuthUrl);
+      const redirectUri = authorizeUrl.searchParams.get("redirect_uri")!;
+      const state = authorizeUrl.searchParams.get("state")!;
 
       // Make a request to the loopback server with the auth code
       const callbackUrl = `${redirectUri}?code=loopback-auth-code&state=${state}`;
@@ -282,9 +298,9 @@ describe("OAuth2 gateway transport", () => {
       expect(capturedAuthUrl).not.toContain("gw.example.com");
 
       // Simulate callback to loopback server
-      const authUrl = new URL(capturedAuthUrl);
-      const redirectUri = authUrl.searchParams.get("redirect_uri")!;
-      const state = authUrl.searchParams.get("state")!;
+      const authorizeUrl = new URL(capturedAuthUrl);
+      const redirectUri = authorizeUrl.searchParams.get("redirect_uri")!;
+      const state = authorizeUrl.searchParams.get("state")!;
       await fetch(`${redirectUri}?code=explicit-loopback-code&state=${state}`);
 
       const result = await flowPromise;
@@ -405,9 +421,9 @@ describe("OAuth2 gateway transport", () => {
       expect(capturedAuthUrl).toContain("code_challenge=");
       expect(capturedAuthUrl).toContain("code_challenge_method=S256");
 
-      const authUrl = new URL(capturedAuthUrl);
-      const redirectUri = authUrl.searchParams.get("redirect_uri")!;
-      const state = authUrl.searchParams.get("state")!;
+      const authorizeUrl = new URL(capturedAuthUrl);
+      const redirectUri = authorizeUrl.searchParams.get("redirect_uri")!;
+      const state = authorizeUrl.searchParams.get("state")!;
 
       const resp = await fetch(
         `${redirectUri}?code=loopback-code&state=${state}`,
@@ -440,9 +456,9 @@ describe("OAuth2 gateway transport", () => {
 
       await urlReadyPromise;
 
-      const authUrl = new URL(capturedAuthUrl);
-      const redirectUri = authUrl.searchParams.get("redirect_uri")!;
-      const state = authUrl.searchParams.get("state")!;
+      const authorizeUrl = new URL(capturedAuthUrl);
+      const redirectUri = authorizeUrl.searchParams.get("redirect_uri")!;
+      const state = authorizeUrl.searchParams.get("state")!;
 
       // Fire callback without awaiting — immediately check flowPromise rejection
       fetch(`${redirectUri}?error=access_denied&state=${state}`).catch(
@@ -473,8 +489,8 @@ describe("OAuth2 gateway transport", () => {
 
       await urlReadyPromise;
 
-      const authUrl = new URL(capturedAuthUrl);
-      const redirectUri = authUrl.searchParams.get("redirect_uri")!;
+      const authorizeUrl = new URL(capturedAuthUrl);
+      const redirectUri = authorizeUrl.searchParams.get("redirect_uri")!;
 
       // Send callback with wrong state
       const resp = await fetch(
@@ -484,7 +500,7 @@ describe("OAuth2 gateway transport", () => {
 
       // The flow should still be waiting (not resolved)
       // Send the correct callback to clean up
-      const state = authUrl.searchParams.get("state")!;
+      const state = authorizeUrl.searchParams.get("state")!;
       await fetch(`${redirectUri}?code=correct-code&state=${state}`);
 
       const result = await flowPromise;
@@ -516,9 +532,9 @@ describe("OAuth2 gateway transport", () => {
 
       await urlReadyPromise;
 
-      const authUrl = new URL(capturedAuthUrl);
-      const redirectUri = authUrl.searchParams.get("redirect_uri")!;
-      const state = authUrl.searchParams.get("state")!;
+      const authorizeUrl = new URL(capturedAuthUrl);
+      const redirectUri = authorizeUrl.searchParams.get("redirect_uri")!;
+      const state = authorizeUrl.searchParams.get("state")!;
 
       // Fire callback without awaiting — immediately check flowPromise rejection
       fetch(`${redirectUri}?code=code-that-fails&state=${state}`).catch(
@@ -653,4 +669,422 @@ describe("OAuth2 gateway transport", () => {
       expect(lastTokenRequestBody!.has("client_secret")).toBe(false);
     });
   });
+
+  describe("scope separator", () => {
+    test("authorize URL joins scopes with space when scopeSeparator is ' '", async () => {
+      mockPublicBaseUrl = "https://gw.example.com";
+
+      let capturedAuthUrl = "";
+      const flowPromise = startOAuth2Flow(
+        BASE_OAUTH_CONFIG,
+        {
+          openUrl: (url) => {
+            capturedAuthUrl = url;
+          },
+        },
+        { callbackTransport: "gateway" },
+      );
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      // URLSearchParams encodes spaces as '+' in query strings (application/x-www-form-urlencoded)
+      expect(capturedAuthUrl).toContain("scope=read+write");
+
+      const entries = Array.from(pendingCallbacks.entries());
+      entries[0][1].resolve("space-separator-code");
+      await flowPromise;
+    });
+
+    test("authorize URL joins scopes with comma when scopeSeparator is ','", async () => {
+      mockPublicBaseUrl = "https://gw.example.com";
+
+      const commaConfig: OAuth2Config = {
+        ...BASE_OAUTH_CONFIG,
+        scopeSeparator: ",",
+      };
+
+      let capturedAuthUrl = "";
+      const flowPromise = startOAuth2Flow(
+        commaConfig,
+        {
+          openUrl: (url) => {
+            capturedAuthUrl = url;
+          },
+        },
+        { callbackTransport: "gateway" },
+      );
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      // Comma-encoded scopes
+      expect(capturedAuthUrl).toContain("scope=read%2Cwrite");
+
+      const entries = Array.from(pendingCallbacks.entries());
+      entries[0][1].resolve("comma-separator-code");
+      await flowPromise;
+    });
+
+    test("token response with comma-separated scope splits into individual scopes when scopeSeparator is ','", async () => {
+      mockPublicBaseUrl = "https://gw.example.com";
+      mockTokenResponse = {
+        ok: true,
+        status: 200,
+        body: {
+          access_token: "test-access-token",
+          refresh_token: "test-refresh-token",
+          expires_in: 3600,
+          scope: "read,write,issues:create",
+          token_type: "Bearer",
+        },
+      };
+
+      const commaConfig: OAuth2Config = {
+        ...BASE_OAUTH_CONFIG,
+        scopeSeparator: ",",
+      };
+
+      const flowPromise = startOAuth2Flow(
+        commaConfig,
+        { openUrl: () => {} },
+        { callbackTransport: "gateway" },
+      );
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      const entries = Array.from(pendingCallbacks.entries());
+      entries[0][1].resolve("comma-token-code");
+
+      const result = await flowPromise;
+      expect(result.grantedScopes).toEqual(["read", "write", "issues:create"]);
+    });
+
+    test("token response with whitespace around comma separators is trimmed", async () => {
+      mockPublicBaseUrl = "https://gw.example.com";
+      mockTokenResponse = {
+        ok: true,
+        status: 200,
+        body: {
+          access_token: "test-access-token",
+          refresh_token: "test-refresh-token",
+          expires_in: 3600,
+          scope: " read , write ",
+          token_type: "Bearer",
+        },
+      };
+
+      const commaConfig: OAuth2Config = {
+        ...BASE_OAUTH_CONFIG,
+        scopeSeparator: ",",
+      };
+
+      const flowPromise = startOAuth2Flow(
+        commaConfig,
+        { openUrl: () => {} },
+        { callbackTransport: "gateway" },
+      );
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      const entries = Array.from(pendingCallbacks.entries());
+      entries[0][1].resolve("comma-whitespace-code");
+
+      const result = await flowPromise;
+      expect(result.grantedScopes).toEqual(["read", "write"]);
+    });
+
+    test("default-space provider still parses comma-separated token response scopes (GitHub/Slack compat)", async () => {
+      // Providers like GitHub and Slack use space as their authorize-URL
+      // separator but return comma-separated scopes in token responses.
+      // The defensive split MUST tolerate that without requiring providers
+      // to opt into scopeSeparator: ",".
+      mockPublicBaseUrl = "https://gw.example.com";
+      mockTokenResponse = {
+        ok: true,
+        status: 200,
+        body: {
+          access_token: "test-access-token",
+          refresh_token: "test-refresh-token",
+          expires_in: 3600,
+          scope: "repo,read:user,notifications",
+          token_type: "Bearer",
+        },
+      };
+
+      // BASE_OAUTH_CONFIG uses the default " " separator.
+      const flowPromise = startOAuth2Flow(
+        BASE_OAUTH_CONFIG,
+        { openUrl: () => {} },
+        { callbackTransport: "gateway" },
+      );
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      const entries = Array.from(pendingCallbacks.entries());
+      entries[0][1].resolve("github-style-code");
+
+      const result = await flowPromise;
+      expect(result.grantedScopes).toEqual([
+        "repo",
+        "read:user",
+        "notifications",
+      ]);
+    });
+
+    test("default-space provider parses space-separated token response scopes", async () => {
+      mockPublicBaseUrl = "https://gw.example.com";
+      mockTokenResponse = {
+        ok: true,
+        status: 200,
+        body: {
+          access_token: "test-access-token",
+          refresh_token: "test-refresh-token",
+          expires_in: 3600,
+          scope: "read write admin",
+          token_type: "Bearer",
+        },
+      };
+
+      const flowPromise = startOAuth2Flow(
+        BASE_OAUTH_CONFIG,
+        { openUrl: () => {} },
+        { callbackTransport: "gateway" },
+      );
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      const entries = Array.from(pendingCallbacks.entries());
+      entries[0][1].resolve("space-token-code");
+
+      const result = await flowPromise;
+      expect(result.grantedScopes).toEqual(["read", "write", "admin"]);
+    });
+  });
+
+  describe("tokenExchangeBodyFormat", () => {
+    test("sends JSON body when tokenExchangeBodyFormat is 'json'", async () => {
+      mockPublicBaseUrl = "https://gw.example.com";
+
+      const jsonConfig: OAuth2Config = {
+        ...BASE_OAUTH_CONFIG,
+        clientSecret: "test-client-secret",
+        tokenExchangeBodyFormat: "json",
+      };
+
+      const flowPromise = startOAuth2Flow(
+        jsonConfig,
+        { openUrl: () => {} },
+        { callbackTransport: "gateway" },
+      );
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      const entries = Array.from(pendingCallbacks.entries());
+      entries[0][1].resolve("json-body-code");
+
+      await flowPromise;
+
+      // Content-Type should be application/json
+      expect(lastTokenRequestHeaders["Content-Type"]).toBe("application/json");
+
+      // Body should be valid JSON
+      expect(lastTokenRequestRawBody).not.toBeNull();
+      const parsed = JSON.parse(lastTokenRequestRawBody!);
+      expect(parsed.grant_type).toBe("authorization_code");
+      expect(parsed.client_id).toBe("test-client-id");
+      expect(parsed.client_secret).toBe("test-client-secret");
+      expect(parsed.code).toBe("json-body-code");
+      expect(parsed.code_verifier).toBeTruthy();
+    });
+
+    test("sends form-encoded body by default (tokenExchangeBodyFormat omitted)", async () => {
+      mockPublicBaseUrl = "https://gw.example.com";
+
+      const flowPromise = startOAuth2Flow(
+        BASE_OAUTH_CONFIG,
+        { openUrl: () => {} },
+        { callbackTransport: "gateway" },
+      );
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      const entries = Array.from(pendingCallbacks.entries());
+      entries[0][1].resolve("form-body-code");
+
+      await flowPromise;
+
+      // Content-Type should be form-encoded
+      expect(lastTokenRequestHeaders["Content-Type"]).toBe(
+        "application/x-www-form-urlencoded",
+      );
+
+      // Body should be parseable as URLSearchParams
+      expect(lastTokenRequestBody).not.toBeNull();
+      expect(lastTokenRequestBody!.get("grant_type")).toBe(
+        "authorization_code",
+      );
+      expect(lastTokenRequestBody!.get("client_id")).toBe("test-client-id");
+    });
+
+    test("sends form-encoded body when tokenExchangeBodyFormat is explicitly 'form'", async () => {
+      mockPublicBaseUrl = "https://gw.example.com";
+
+      const formConfig: OAuth2Config = {
+        ...BASE_OAUTH_CONFIG,
+        tokenExchangeBodyFormat: "form",
+      };
+
+      const flowPromise = startOAuth2Flow(
+        formConfig,
+        { openUrl: () => {} },
+        { callbackTransport: "gateway" },
+      );
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      const entries = Array.from(pendingCallbacks.entries());
+      entries[0][1].resolve("explicit-form-code");
+
+      await flowPromise;
+
+      // Content-Type should be form-encoded
+      expect(lastTokenRequestHeaders["Content-Type"]).toBe(
+        "application/x-www-form-urlencoded",
+      );
+
+      // Body should be parseable as URLSearchParams
+      expect(lastTokenRequestBody).not.toBeNull();
+      expect(lastTokenRequestBody!.get("grant_type")).toBe(
+        "authorization_code",
+      );
+    });
+
+    test("JSON body format works with client_secret_basic auth method", async () => {
+      mockPublicBaseUrl = "https://gw.example.com";
+
+      const jsonBasicConfig: OAuth2Config = {
+        ...BASE_OAUTH_CONFIG,
+        clientSecret: "test-client-secret",
+        tokenEndpointAuthMethod: "client_secret_basic",
+        tokenExchangeBodyFormat: "json",
+      };
+
+      const flowPromise = startOAuth2Flow(
+        jsonBasicConfig,
+        { openUrl: () => {} },
+        { callbackTransport: "gateway" },
+      );
+
+      await new Promise((r) => setTimeout(r, 10));
+
+      const entries = Array.from(pendingCallbacks.entries());
+      entries[0][1].resolve("json-basic-code");
+
+      await flowPromise;
+
+      // Content-Type should be application/json
+      expect(lastTokenRequestHeaders["Content-Type"]).toBe("application/json");
+
+      // Should have Basic Auth header
+      const expectedCredentials = Buffer.from(
+        "test-client-id:test-client-secret",
+      ).toString("base64");
+      expect(lastTokenRequestHeaders["Authorization"]).toBe(
+        `Basic ${expectedCredentials}`,
+      );
+
+      // Body should be valid JSON without client_id/client_secret
+      const parsed = JSON.parse(lastTokenRequestRawBody!);
+      expect(parsed.grant_type).toBe("authorization_code");
+      expect(parsed.client_id).toBeUndefined();
+      expect(parsed.client_secret).toBeUndefined();
+      expect(parsed.code_verifier).toBeTruthy();
+    });
+  });
+
+  describe("refreshOAuth2Token", () => {
+    test("sends JSON body when tokenExchangeBodyFormat is 'json'", async () => {
+      const result = await refreshOAuth2Token(
+        "https://provider.example.com/token",
+        "test-client-id",
+        "test-refresh-token",
+        "test-client-secret",
+        undefined, // tokenEndpointAuthMethod defaults to client_secret_post
+        "json",
+      );
+
+      // Content-Type should be application/json
+      expect(lastTokenRequestHeaders["Content-Type"]).toBe("application/json");
+
+      // Body should be valid JSON with refresh_token grant
+      expect(lastTokenRequestRawBody).not.toBeNull();
+      const parsed = JSON.parse(lastTokenRequestRawBody!);
+      expect(parsed.grant_type).toBe("refresh_token");
+      expect(parsed.refresh_token).toBe("test-refresh-token");
+      expect(parsed.client_id).toBe("test-client-id");
+      expect(parsed.client_secret).toBe("test-client-secret");
+
+      // Result should contain the tokens
+      expect(result.accessToken).toBe("test-access-token");
+      expect(result.refreshToken).toBe("test-refresh-token");
+    });
+
+    test("sends form-encoded body by default", async () => {
+      const result = await refreshOAuth2Token(
+        "https://provider.example.com/token",
+        "test-client-id",
+        "test-refresh-token",
+        "test-client-secret",
+      );
+
+      // Content-Type should be form-encoded
+      expect(lastTokenRequestHeaders["Content-Type"]).toBe(
+        "application/x-www-form-urlencoded",
+      );
+
+      // Body should be parseable as URLSearchParams
+      expect(lastTokenRequestBody).not.toBeNull();
+      expect(lastTokenRequestBody!.get("grant_type")).toBe("refresh_token");
+      expect(lastTokenRequestBody!.get("refresh_token")).toBe(
+        "test-refresh-token",
+      );
+      expect(lastTokenRequestBody!.get("client_id")).toBe("test-client-id");
+      expect(lastTokenRequestBody!.get("client_secret")).toBe(
+        "test-client-secret",
+      );
+
+      expect(result.accessToken).toBe("test-access-token");
+    });
+
+    test("JSON body format works with client_secret_basic auth method", async () => {
+      const result = await refreshOAuth2Token(
+        "https://provider.example.com/token",
+        "test-client-id",
+        "test-refresh-token",
+        "test-client-secret",
+        "client_secret_basic",
+        "json",
+      );
+
+      // Content-Type should be application/json
+      expect(lastTokenRequestHeaders["Content-Type"]).toBe("application/json");
+
+      // Should have Basic Auth header
+      const expectedCredentials = Buffer.from(
+        "test-client-id:test-client-secret",
+      ).toString("base64");
+      expect(lastTokenRequestHeaders["Authorization"]).toBe(
+        `Basic ${expectedCredentials}`,
+      );
+
+      // Body should be valid JSON without client_id/client_secret (basic auth puts them in header)
+      expect(lastTokenRequestRawBody).not.toBeNull();
+      const parsed = JSON.parse(lastTokenRequestRawBody!);
+      expect(parsed.grant_type).toBe("refresh_token");
+      expect(parsed.refresh_token).toBe("test-refresh-token");
+      expect(parsed.client_id).toBeUndefined();
+      expect(parsed.client_secret).toBeUndefined();
+
+      expect(result.accessToken).toBe("test-access-token");
+    });
+  });
 });