@cursor/july 0.1.19 → 0.1.21

package/src/internal/cursor/backend-client.test.ts

@@ -0,0 +1,591 @@
+import { describe, expect, it } from "vitest";
+import {
+  CursorBackendClient,
+  CursorBackendError,
+  createUserApiKeyWithSessionToken,
+  revokeMintedUserApiKey,
+} from "./backend-client.js";
+
+const BACKEND = "https://backend.example";
+
+/** A JWT-shaped token whose exp claim is one hour out. */
+function fakeJwt(expiresInSeconds = 3600): string {
+  const claims = Buffer.from(
+    JSON.stringify({ exp: Math.floor(Date.now() / 1000) + expiresInSeconds })
+  ).toString("base64url");
+  return `header.${claims}.signature`;
+}
+
+interface SeenRequest {
+  url: string;
+  headers: Record<string, string>;
+  body: unknown;
+}
+
+/**
+ * Fake Cursor backend: implements the API-key exchange plus a handler per
+ * DashboardService method, recording every request it sees.
+ */
+function fakeBackend(
+  handlers: Record<string, (body: unknown) => Response | Promise<Response>>,
+  options: { accessToken?: string; failExchanges?: number } = {}
+): { fetchImpl: typeof fetch; seen: SeenRequest[]; exchanges: () => number } {
+  const seen: SeenRequest[] = [];
+  let exchangeCount = 0;
+  const fetchImpl = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(input);
+    const body =
+      typeof init?.body === "string" && init.body !== ""
+        ? (JSON.parse(init.body) as unknown)
+        : undefined;
+    seen.push({
+      url,
+      headers: Object.fromEntries(new Headers(init?.headers).entries()),
+      body,
+    });
+    if (url.endsWith("/auth/exchange_user_api_key")) {
+      exchangeCount++;
+      if (
+        options.failExchanges !== undefined &&
+        exchangeCount <= options.failExchanges
+      ) {
+        return new Response("{}", { status: 401 });
+      }
+      return Response.json({
+        accessToken: options.accessToken ?? fakeJwt(),
+        refreshToken: "r",
+      });
+    }
+    const method = url.split("/").pop() ?? "";
+    const handler = handlers[method];
+    if (handler === undefined) {
+      return new Response(JSON.stringify({ message: "no handler" }), {
+        status: 404,
+      });
+    }
+    return handler(body);
+  }) as typeof fetch;
+  return { fetchImpl, seen, exchanges: () => exchangeCount };
+}
+
+describe("CursorBackendClient", () => {
+  it("exchanges the API key once and reuses the access token across RPCs", async () => {
+    const backend = fakeBackend({
+      GetMe: () => Response.json({ authId: "auth0|1", email: "a@b.co" }),
+    });
+    const client = new CursorBackendClient({
+      backendUrl: BACKEND,
+      apiKey: "crsr_key",
+      fetchImpl: backend.fetchImpl,
+    });
+
+    expect(await client.getMe()).toMatchObject({ email: "a@b.co" });
+    expect(await client.getMe()).toMatchObject({ email: "a@b.co" });
+    expect(backend.exchanges()).toBe(1);
+
+    const exchange = backend.seen[0];
+    expect(exchange?.url).toBe(`${BACKEND}/auth/exchange_user_api_key`);
+    expect(exchange?.headers.authorization).toBe("Bearer crsr_key");
+    const rpc = backend.seen[1];
+    expect(rpc?.url).toBe(`${BACKEND}/aiserver.v1.DashboardService/GetMe`);
+    expect(rpc?.headers.authorization).toMatch(/^Bearer header\./);
+    expect(rpc?.headers["x-request-id"]).toBeTruthy();
+  });
+
+  it("re-exchanges once when an RPC comes back 401", async () => {
+    let getMeCalls = 0;
+    const backend = fakeBackend({
+      GetMe: () => {
+        getMeCalls++;
+        if (getMeCalls === 1) {
+          return new Response("{}", { status: 401 });
+        }
+        return Response.json({ authId: "auth0|1" });
+      },
+    });
+    const client = new CursorBackendClient({
+      backendUrl: BACKEND,
+      apiKey: "crsr_key",
+      fetchImpl: backend.fetchImpl,
+    });
+    expect(await client.getMe()).toMatchObject({ authId: "auth0|1" });
+    expect(backend.exchanges()).toBe(2);
+  });
+
+  it("surfaces a sign-in hint when the API key itself is rejected", async () => {
+    const backend = fakeBackend({}, { failExchanges: 10 });
+    const client = new CursorBackendClient({
+      backendUrl: BACKEND,
+      apiKey: "crsr_bad",
+      fetchImpl: backend.fetchImpl,
+    });
+    await expect(client.getMe()).rejects.toThrow(/agent-serve login/);
+  });
+
+  it("mints a scoped GitHub token directly from the account API key", async () => {
+    const expiresAt = new Date(Date.now() + 45 * 60_000).toISOString();
+    const backend = fakeBackend({
+      "github-token": (body) => {
+        expect(body).toEqual({
+          repos: ["acme/widgets"],
+          permissions: "pr-write",
+        });
+        return Response.json({ token: "ghs_scoped", expiresAt });
+      },
+    });
+    const client = new CursorBackendClient({
+      backendUrl: BACKEND,
+      apiKey: "crsr_key",
+      fetchImpl: backend.fetchImpl,
+    });
+
+    await expect(client.getGithubToken(["acme/widgets"])).resolves.toEqual({
+      token: "ghs_scoped",
+      expiresAt,
+    });
+    expect(backend.exchanges()).toBe(0);
+    expect(backend.seen[0]?.url).toBe(`${BACKEND}/v0/scm-events/github-token`);
+    expect(backend.seen[0]?.headers.authorization).toBe("Bearer crsr_key");
+  });
+
+  it("requests a read-only GitHub token when permissions is read", async () => {
+    const expiresAt = new Date(Date.now() + 45 * 60_000).toISOString();
+    const backend = fakeBackend({
+      "github-token": (body) => {
+        expect(body).toEqual({
+          repos: ["acme/widgets"],
+          permissions: "read",
+        });
+        return Response.json({ token: "ghs_readonly", expiresAt });
+      },
+    });
+    const client = new CursorBackendClient({
+      backendUrl: BACKEND,
+      apiKey: "crsr_key",
+      fetchImpl: backend.fetchImpl,
+    });
+
+    await expect(
+      client.getGithubToken(["acme/widgets"], { permissions: "read" })
+    ).resolves.toEqual({
+      token: "ghs_readonly",
+      expiresAt,
+    });
+  });
+
+  it("requests a contents-write GitHub token when opted up", async () => {
+    const expiresAt = new Date(Date.now() + 45 * 60_000).toISOString();
+    const backend = fakeBackend({
+      "github-token": (body) => {
+        expect(body).toEqual({
+          repos: ["acme/widgets"],
+          permissions: "contents-write",
+        });
+        return Response.json({ token: "ghs_push", expiresAt });
+      },
+    });
+    const client = new CursorBackendClient({
+      backendUrl: BACKEND,
+      apiKey: "crsr_key",
+      fetchImpl: backend.fetchImpl,
+    });
+
+    await expect(
+      client.getGithubToken(["acme/widgets"], {
+        permissions: "contents-write",
+      })
+    ).resolves.toEqual({
+      token: "ghs_push",
+      expiresAt,
+    });
+  });
+
+  it("keeps GitHub-connection denials distinct from API-key rejections", async () => {
+    const backend = fakeBackend({
+      "github-token": () =>
+        Response.json(
+          {
+            error:
+              "No GitHub connection found for this Cursor account. Connect GitHub in the Cursor dashboard (Integrations) and try again.",
+          },
+          { status: 403 }
+        ),
+    });
+    const client = new CursorBackendClient({
+      backendUrl: BACKEND,
+      apiKey: "crsr_key",
+      fetchImpl: backend.fetchImpl,
+    });
+
+    const error = await client.getGithubToken(["acme/widgets"]).catch((e) => e);
+    expect(error).toMatchObject({
+      name: "CursorBackendError",
+      status: 403,
+    });
+    expect(String(error.message)).toMatch(/GitHub connection/i);
+    expect(String(error.message)).not.toMatch(
+      /agent-serve login|API key was rejected/
+    );
+  });
+
+  it("honors Retry-After on GitHub token rate limits", async () => {
+    const backend = fakeBackend({
+      "github-token": () =>
+        new Response(JSON.stringify({ error: "rate limited" }), {
+          status: 429,
+          headers: {
+            "content-type": "application/json",
+            "retry-after": "120",
+          },
+        }),
+    });
+    const client = new CursorBackendClient({
+      backendUrl: BACKEND,
+      apiKey: "crsr_key",
+      fetchImpl: backend.fetchImpl,
+    });
+
+    await expect(client.getGithubToken(["acme/widgets"])).rejects.toMatchObject(
+      {
+        name: "CursorBackendError",
+        status: 429,
+        retryAfterMs: 120_000,
+        message: expect.stringMatching(/rate limited/i),
+      }
+    );
+  });
+
+  it("lists account MCP tools with normalized schemas", async () => {
+    const backend = fakeBackend({
+      ListSandMcpTools: (body) => {
+        expect(body).toEqual({ serverIdentifiers: ["Linear"] });
+        return Response.json({
+          servers: [
+            {
+              serverIdentifier: "Linear",
+              status: "connected",
+              tools: [
+                {
+                  name: "Linear-list_issues",
+                  description: "List issues.",
+                  inputSchema: {
+                    type: "object",
+                    properties: { query: { type: "string" } },
+                  },
+                },
+                { name: "Linear-create_issue" },
+              ],
+            },
+            { serverIdentifier: "Notion", status: "needsAuth" },
+          ],
+        });
+      },
+    });
+    const client = new CursorBackendClient({
+      backendUrl: BACKEND,
+      apiKey: "crsr_key",
+      fetchImpl: backend.fetchImpl,
+    });
+
+    const servers = await client.listAccountMcpTools(["Linear"]);
+    expect(servers).toHaveLength(2);
+    expect(servers[0]?.tools[0]).toMatchObject({
+      name: "Linear-list_issues",
+      description: "List issues.",
+    });
+    // Missing schema defaults to an open object so MCP clients accept it.
+    expect(servers[0]?.tools[1]?.inputSchema).toEqual({
+      type: "object",
+      properties: {},
+    });
+    expect(servers[1]).toMatchObject({ status: "needsAuth", tools: [] });
+  });
+
+  it("converts success results (text, image, structured content)", async () => {
+    const backend = fakeBackend({
+      ExecuteSandMcpTool: (body) => {
+        expect(body).toMatchObject({
+          serverIdentifier: "Linear",
+          toolName: "Linear-list_issues",
+          args: { query: "bug" },
+        });
+        expect((body as { toolCallId?: string }).toolCallId).toBeTruthy();
+        return Response.json({
+          result: {
+            success: {
+              content: [
+                { text: { text: "2 issues" } },
+                { image: { data: "aGk=", mimeType: "image/png" } },
+              ],
+              isError: false,
+              structuredContent: { total: 2 },
+            },
+          },
+        });
+      },
+    });
+    const client = new CursorBackendClient({
+      backendUrl: BACKEND,
+      apiKey: "crsr_key",
+      fetchImpl: backend.fetchImpl,
+    });
+
+    const result = await client.executeAccountMcpTool({
+      serverIdentifier: "Linear",
+      toolName: "Linear-list_issues",
+      args: { query: "bug" },
+    });
+    expect(result).toEqual({
+      content: [
+        { type: "text", text: "2 issues" },
+        { type: "image", data: "aGk=", mimeType: "image/png" },
+      ],
+      isError: false,
+      structuredContent: { total: 2 },
+    });
+  });
+
+  it("tolerates proto-JSON omitting default-valued content fields", async () => {
+    // The backend's proto-JSON omits default values, so an empty text chunk
+    // arrives as `{"text": {}}` — it must parse as "" rather than fail.
+    const backend = fakeBackend({
+      ExecuteSandMcpTool: () =>
+        Response.json({
+          result: { success: { content: [{ text: {} }, { image: {} }] } },
+        }),
+    });
+    const client = new CursorBackendClient({
+      backendUrl: BACKEND,
+      apiKey: "crsr_key",
+      fetchImpl: backend.fetchImpl,
+    });
+    const result = await client.executeAccountMcpTool({
+      serverIdentifier: "s",
+      toolName: "t",
+      args: {},
+    });
+    expect(result).toEqual({
+      content: [
+        { type: "text", text: "" },
+        { type: "image", data: "" },
+      ],
+      isError: false,
+    });
+  });
+
+  it.each([
+    [{ error: { error: "server exploded" } }, /server exploded/],
+    [{ permissionDenied: { error: "not allowed" } }, /not allowed/],
+    [{ rejected: { reason: "readonly session" } }, /readonly session/],
+    [
+      { toolNotFound: { name: "nope", availableTools: ["a", "b"] } },
+      /Unknown tool "nope"\. Available: a, b\./,
+    ],
+    [
+      { serverNotFound: { name: "gone", availableServers: [] } },
+      /Unknown MCP server "gone"/,
+    ],
+    [{}, /returned no result/],
+  ])("converts failure results to error text: %j", async (result, pattern) => {
+    const backend = fakeBackend({
+      ExecuteSandMcpTool: () => Response.json({ result }),
+    });
+    const client = new CursorBackendClient({
+      backendUrl: BACKEND,
+      apiKey: "crsr_key",
+      fetchImpl: backend.fetchImpl,
+    });
+    const outcome = await client.executeAccountMcpTool({
+      serverIdentifier: "s",
+      toolName: "t",
+      args: {},
+    });
+    expect(outcome.isError).toBe(true);
+    expect(outcome.content[0]).toMatchObject({ type: "text" });
+    expect((outcome.content[0] as { text: string }).text).toMatch(pattern);
+  });
+
+  it("clears a rejected token after a retry still returns 401", async () => {
+    let getMeCalls = 0;
+    const backend = fakeBackend({
+      GetMe: () => {
+        getMeCalls++;
+        return new Response("{}", { status: 401 });
+      },
+    });
+    const client = new CursorBackendClient({
+      backendUrl: BACKEND,
+      apiKey: "crsr_key",
+      fetchImpl: backend.fetchImpl,
+    });
+    await expect(client.getMe()).rejects.toThrow(/GetMe failed \(401\)/);
+    expect(backend.exchanges()).toBe(2);
+    expect(getMeCalls).toBe(2);
+  });
+
+  it("surfaces Connect error messages from failed RPCs", async () => {
+    const backend = fakeBackend({
+      ListSandMcpTools: () =>
+        new Response(
+          JSON.stringify({ code: "permission_denied", message: "MCP off" }),
+          { status: 403 }
+        ),
+    });
+    const client = new CursorBackendClient({
+      backendUrl: BACKEND,
+      apiKey: "crsr_key",
+      fetchImpl: backend.fetchImpl,
+    });
+    await expect(client.listAccountMcpTools([])).rejects.toThrow(
+      /ListSandMcpTools failed \(403\): MCP off/
+    );
+  });
+});
+
+describe("createUserApiKeyWithSessionToken", () => {
+  it("mints a key with the session bearer and returns it", async () => {
+    const seen: SeenRequest[] = [];
+    const fetchImpl = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      seen.push({
+        url: String(input),
+        headers: Object.fromEntries(new Headers(init?.headers).entries()),
+        body: JSON.parse(String(init?.body)) as unknown,
+      });
+      return Response.json({ apiKey: "crsr_minted" });
+    }) as typeof fetch;
+
+    const apiKey = await createUserApiKeyWithSessionToken({
+      backendUrl: BACKEND,
+      sessionToken: "session-jwt",
+      keyName: "agent-serve (host)",
+      fetchImpl,
+    });
+    expect(apiKey).toBe("crsr_minted");
+    expect(seen[0]?.url).toBe(
+      `${BACKEND}/aiserver.v1.DashboardService/CreateUserApiKey`
+    );
+    expect(seen[0]?.headers.authorization).toBe("Bearer session-jwt");
+    expect(seen[0]?.body).toEqual({ name: "agent-serve (host)" });
+  });
+
+  it("carries the backend status through on failure (team admin policy)", async () => {
+    const fetchImpl = (async () =>
+      new Response(
+        JSON.stringify({
+          message: "Only team admins can create user API keys",
+        }),
+        { status: 401 }
+      )) as typeof fetch;
+    const attempt = createUserApiKeyWithSessionToken({
+      backendUrl: BACKEND,
+      sessionToken: "session-jwt",
+      keyName: "x",
+      fetchImpl,
+    });
+    await expect(attempt).rejects.toThrow(/Only team admins/);
+    await expect(attempt).rejects.toBeInstanceOf(CursorBackendError);
+  });
+});
+
+describe("revokeMintedUserApiKey", () => {
+  it("authenticates cleanup with the browser session token", async () => {
+    const backend = fakeBackend({
+      ListUserApiKeys: () =>
+        Response.json({
+          apiKeys: [
+            {
+              id: 9,
+              name: "agent-serve (host)",
+              maskedKey: "crsr_...mint",
+              createdAt: 100,
+            },
+          ],
+        }),
+      RevokeUserApiKey: (body) => {
+        expect(body).toEqual({ id: 9 });
+        return Response.json({});
+      },
+    });
+
+    await revokeMintedUserApiKey({
+      backendUrl: BACKEND,
+      keyName: "agent-serve (host)",
+      apiKey:
+        "crsr_0123456789abcdef0123456789abcdef0123456789abcdef0123456789mint",
+      sessionToken: "session-jwt",
+      fetchImpl: backend.fetchImpl,
+    });
+
+    expect(backend.exchanges()).toBe(0);
+    const list = backend.seen.find((req) =>
+      req.url.endsWith("/ListUserApiKeys")
+    );
+    expect(list?.headers.authorization).toBe("Bearer session-jwt");
+  });
+
+  it("revokes by masked key match, not an older same-named key", async () => {
+    const backend = fakeBackend({
+      ListUserApiKeys: () =>
+        Response.json({
+          apiKeys: [
+            {
+              id: 1,
+              name: "agent-serve (host)",
+              maskedKey: "crsr_...old1",
+              createdAt: 100,
+            },
+            {
+              id: 2,
+              name: "agent-serve (host)",
+              maskedKey: "crsr_...new2",
+              createdAt: 200,
+            },
+          ],
+        }),
+      RevokeUserApiKey: (body) => {
+        expect(body).toEqual({ id: 2 });
+        return Response.json({});
+      },
+    });
+
+    await revokeMintedUserApiKey({
+      backendUrl: BACKEND,
+      keyName: "agent-serve (host)",
+      apiKey:
+        "crsr_0123456789abcdef0123456789abcdef0123456789abcdef0123456789new2",
+      sessionToken: "session-jwt",
+      fetchImpl: backend.fetchImpl,
+    });
+  });
+
+  it("skips revoke when the minted key is not listed yet", async () => {
+    const backend = fakeBackend({
+      ListUserApiKeys: () =>
+        Response.json({
+          apiKeys: [
+            {
+              id: 1,
+              name: "agent-serve (host)",
+              maskedKey: "crsr_...old1",
+              createdAt: 100,
+            },
+          ],
+        }),
+      RevokeUserApiKey: () => {
+        throw new Error("should not revoke");
+      },
+    });
+
+    await revokeMintedUserApiKey({
+      backendUrl: BACKEND,
+      keyName: "agent-serve (host)",
+      apiKey:
+        "crsr_0123456789abcdef0123456789abcdef0123456789abcdef0123456789new2",
+      sessionToken: "session-jwt",
+      fetchImpl: backend.fetchImpl,
+    });
+    expect(
+      backend.seen.some((req) => req.url.endsWith("/RevokeUserApiKey"))
+    ).toBe(false);
+  });
+});