@cursor/july 0.1.1

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

@@ -0,0 +1,614 @@
+/**
+ * Minimal Connect-JSON client for the handful of `aiserver.v1.DashboardService`
+ * RPCs agent-serve needs — `GetMe`, `ListSandMcpTools`, `ExecuteSandMcpTool`,
+ * and the login-time key lifecycle (`CreateUserApiKey`, `ListUserApiKeys`,
+ * `RevokeUserApiKey`).
+ *
+ * Plain `fetch` POSTs with proto-JSON bodies and zod-validated responses:
+ * agent-serve is a published package and should not pull the generated
+ * proto tree in for a few unary calls.
+ *
+ * Auth: the client holds the account API key and exchanges it on demand for
+ * a short-lived access token (`POST /auth/exchange_user_api_key`, ~1h),
+ * cached until shortly before expiry and re-exchanged once on a 401.
+ */
+
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+
+const CLIENT_VERSION = "agent-serve-0.1.0";
+const EXCHANGE_PATH = "/auth/exchange_user_api_key";
+const SERVICE_PREFIX = "/aiserver.v1.DashboardService";
+/** Re-exchange when the cached token is within this window of expiry. */
+const TOKEN_EXPIRY_LEEWAY_MS = 5 * 60 * 1000;
+/** Fallback token lifetime when the JWT `exp` claim cannot be parsed. */
+const FALLBACK_TOKEN_LIFETIME_MS = 30 * 60 * 1000;
+const LIST_TIMEOUT_MS = 60_000;
+/** Backend-executed tools call out to third-party servers; be generous. */
+const EXECUTE_TIMEOUT_MS = 120_000;
+
+export class CursorBackendError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number
+  ) {
+    super(message);
+    this.name = "CursorBackendError";
+  }
+}
+
+// ============================================================================
+// Response schemas (proto-JSON, camelCase; default-valued fields are omitted)
+// ============================================================================
+
+const getMeResponseSchema: z.ZodObject<
+  {
+    authId: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    firstName: z.ZodOptional<z.ZodString>;
+    lastName: z.ZodOptional<z.ZodString>;
+    teamId: z.ZodOptional<z.ZodNumber>;
+    teamName: z.ZodOptional<z.ZodString>;
+  },
+  "strip"
+> = z.object({
+  authId: z.string().optional(),
+  email: z.string().optional(),
+  firstName: z.string().optional(),
+  lastName: z.string().optional(),
+  teamId: z.number().optional(),
+  teamName: z.string().optional(),
+});
+export type CursorIdentity = z.infer<typeof getMeResponseSchema>;
+
+const createUserApiKeyResponseSchema = z.object({
+  apiKey: z.string().min(1),
+});
+
+const mcpToolSchema = z.object({
+  name: z.string(),
+  providerIdentifier: z.string().optional(),
+  toolName: z.string().optional(),
+  description: z.string().optional(),
+  /** `google.protobuf.Value` — an arbitrary JSON Schema object. */
+  inputSchema: z.unknown().optional(),
+});
+
+const listSandMcpToolsResponseSchema = z.object({
+  servers: z
+    .array(
+      z.object({
+        serverIdentifier: z.string(),
+        /** "connected" | "needsAuth" | "error" | "loading" */
+        status: z.string(),
+        tools: z.array(mcpToolSchema).optional(),
+      })
+    )
+    .optional(),
+});
+
+export interface AccountMcpTool {
+  /** Fully-qualified tool name (`<server>-<tool>`), the execution key. */
+  name: string;
+  description: string;
+  /** JSON Schema for the tool input (defaulted when the server omits it). */
+  inputSchema: Record<string, unknown>;
+}
+
+export interface AccountMcpServer {
+  serverIdentifier: string;
+  status: string;
+  tools: AccountMcpTool[];
+}
+
+/**
+ * Proto-JSON of `agent.v1.McpResult` (oneof → exactly one field set).
+ * Inner strings default to `""` because proto-JSON omits default-valued
+ * fields — `McpTextContent{text: ""}` arrives as `{"text": {}}`.
+ */
+const mcpResultSchema = z.object({
+  success: z
+    .object({
+      content: z
+        .array(
+          z.object({
+            text: z.object({ text: z.string().default("") }).optional(),
+            image: z
+              .object({
+                data: z.string().default(""),
+                mimeType: z.string().optional(),
+              })
+              .optional(),
+          })
+        )
+        .optional(),
+      isError: z.boolean().optional(),
+      structuredContent: z.record(z.unknown()).optional(),
+    })
+    .optional(),
+  error: z.object({ error: z.string().optional() }).optional(),
+  rejected: z.object({ reason: z.string().optional() }).optional(),
+  permissionDenied: z.object({ error: z.string().optional() }).optional(),
+  toolNotFound: z
+    .object({
+      name: z.string().optional(),
+      availableTools: z.array(z.string()).optional(),
+    })
+    .optional(),
+  serverNotFound: z
+    .object({
+      name: z.string().optional(),
+      availableServers: z.array(z.string()).optional(),
+    })
+    .optional(),
+});
+
+const executeResponseSchema = z.object({
+  result: mcpResultSchema.optional(),
+});
+
+/** Normalized tool-call outcome, shaped like an MCP `CallToolResult`. */
+export interface AccountMcpCallResult {
+  content: Array<
+    | { type: "text"; text: string }
+    | { type: "image"; data: string; mimeType?: string }
+  >;
+  isError: boolean;
+  structuredContent?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Shared request machinery (used by the client and the login-time mint)
+// ============================================================================
+
+/** One DashboardService Connect-JSON POST; auth is the caller's bearer. */
+async function dashboardRpc(args: {
+  fetchImpl: typeof fetch;
+  backendUrl: string;
+  method: string;
+  bearer: string;
+  body: unknown;
+  timeoutMs: number;
+}): Promise<Response> {
+  try {
+    return await args.fetchImpl(
+      `${args.backendUrl}${SERVICE_PREFIX}/${args.method}`,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${args.bearer}`,
+          "x-ghost-mode": "true",
+          "x-cursor-client-version": CLIENT_VERSION,
+          "x-cursor-client-type": "agent-serve",
+          "x-request-id": randomUUID(),
+        },
+        body: JSON.stringify(args.body ?? {}),
+        signal: AbortSignal.timeout(args.timeoutMs),
+      }
+    );
+  } catch (error) {
+    throw new CursorBackendError(
+      `Cursor backend request ${args.method} failed: ${describeError(error)}`
+    );
+  }
+}
+
+/** Drain and parse an RPC response; maps non-2xx to a CursorBackendError. */
+async function parseRpcResponse(
+  method: string,
+  response: Response
+): Promise<unknown> {
+  const text = await response.text();
+  if (!response.ok) {
+    throw new CursorBackendError(
+      `Cursor backend ${method} failed (${response.status}): ${connectErrorMessage(text)}`,
+      response.status
+    );
+  }
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new CursorBackendError(
+      `Cursor backend ${method} returned a non-JSON response.`
+    );
+  }
+}
+
+// ============================================================================
+// Client
+// ============================================================================
+
+export interface CursorBackendClientOptions {
+  backendUrl: string;
+  apiKey: string;
+  logger?: (line: string) => void;
+  /** Test seam; defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+export class CursorBackendClient {
+  private readonly backendUrl: string;
+  private readonly apiKey: string;
+  private readonly logger: (line: string) => void;
+  private readonly fetchImpl: typeof fetch;
+  private token: { value: string; expiresAtMs: number } | undefined;
+  private tokenExchange: Promise<string> | undefined;
+
+  constructor(options: CursorBackendClientOptions) {
+    this.backendUrl = options.backendUrl.endsWith("/")
+      ? options.backendUrl.slice(0, -1)
+      : options.backendUrl;
+    this.apiKey = options.apiKey;
+    this.logger = options.logger ?? (() => {});
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+
+  /** Who this API key acts as. */
+  async getMe(): Promise<CursorIdentity> {
+    return getMeResponseSchema.parse(await this.rpc("GetMe", {}));
+  }
+
+  /**
+   * The account's MCP connectors with live status and backend-prefixed tool
+   * definitions. `serverIdentifiers` restricts discovery (empty = all
+   * HTTP/SSE servers on the account).
+   */
+  async listAccountMcpTools(
+    serverIdentifiers: readonly string[]
+  ): Promise<AccountMcpServer[]> {
+    const raw = await this.rpc(
+      "ListSandMcpTools",
+      { serverIdentifiers: [...serverIdentifiers] },
+      LIST_TIMEOUT_MS
+    );
+    const parsed = listSandMcpToolsResponseSchema.parse(raw);
+    return (parsed.servers ?? []).map((server) => ({
+      serverIdentifier: server.serverIdentifier,
+      status: server.status,
+      tools: (server.tools ?? []).map((tool) => ({
+        name: tool.name,
+        description: tool.description ?? "",
+        inputSchema: normalizeInputSchema(tool.inputSchema),
+      })),
+    }));
+  }
+
+  /**
+   * Execute one connector tool **on the Cursor backend** with the account's
+   * stored OAuth credentials. `toolName` is the fully-qualified name from
+   * {@link listAccountMcpTools}.
+   */
+  async executeAccountMcpTool(args: {
+    serverIdentifier: string;
+    toolName: string;
+    args: Record<string, unknown>;
+  }): Promise<AccountMcpCallResult> {
+    const raw = await this.rpc(
+      "ExecuteSandMcpTool",
+      {
+        serverIdentifier: args.serverIdentifier,
+        toolName: args.toolName,
+        args: args.args,
+        toolCallId: randomUUID(),
+      },
+      EXECUTE_TIMEOUT_MS
+    );
+    const parsed = executeResponseSchema.parse(raw);
+    return toCallResult(parsed.result ?? {});
+  }
+
+  private async rpc(
+    method: string,
+    body: unknown,
+    timeoutMs = LIST_TIMEOUT_MS
+  ): Promise<unknown> {
+    const bearer = await this.getAccessToken();
+    const first = await dashboardRpc({
+      fetchImpl: this.fetchImpl,
+      backendUrl: this.backendUrl,
+      method,
+      bearer,
+      body,
+      timeoutMs,
+    });
+    if (first.status !== 401) {
+      return parseRpcResponse(method, first);
+    }
+    // The token aged out server-side. Drain the rejected body (keeps the
+    // connection reusable), drop the token — unless a concurrent retry
+    // already minted a newer one — and retry once.
+    await drainResponseBody(first);
+    if (this.token?.value === bearer) {
+      this.token = undefined;
+    }
+    const retryBearer = await this.getAccessToken();
+    const second = await dashboardRpc({
+      fetchImpl: this.fetchImpl,
+      backendUrl: this.backendUrl,
+      method,
+      bearer: retryBearer,
+      body,
+      timeoutMs,
+    });
+    if (second.status === 401 && this.token?.value === retryBearer) {
+      // The freshly minted token was rejected too; do not keep serving it.
+      this.token = undefined;
+    }
+    return parseRpcResponse(method, second);
+  }
+
+  private getAccessToken(): Promise<string> {
+    if (
+      this.token !== undefined &&
+      Date.now() < this.token.expiresAtMs - TOKEN_EXPIRY_LEEWAY_MS
+    ) {
+      return Promise.resolve(this.token.value);
+    }
+    // Single-flight: concurrent tool calls share one exchange.
+    if (this.tokenExchange === undefined) {
+      this.tokenExchange = this.exchangeApiKey().finally(() => {
+        this.tokenExchange = undefined;
+      });
+    }
+    return this.tokenExchange;
+  }
+
+  private async exchangeApiKey(): Promise<string> {
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${this.backendUrl}${EXCHANGE_PATH}`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.apiKey}`,
+        },
+        body: "{}",
+        signal: AbortSignal.timeout(30_000),
+      });
+    } catch (error) {
+      throw new CursorBackendError(
+        `Could not reach the Cursor backend at ${this.backendUrl}: ${describeError(error)}`
+      );
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      throw new CursorBackendError(
+        response.status === 401
+          ? "The Cursor API key was rejected. Run `agent-serve login` again or update CURSOR_API_KEY."
+          : `Cursor API key exchange failed (${response.status}).`,
+        response.status
+      );
+    }
+    const body = accessTokenResponseSchema.safeParse(safeJsonParse(text));
+    if (!body.success || body.data.accessToken === "") {
+      throw new CursorBackendError(
+        "Cursor API key exchange returned no access token."
+      );
+    }
+    this.token = {
+      value: body.data.accessToken,
+      expiresAtMs: jwtExpiryMs(body.data.accessToken),
+    };
+    this.logger("[agent-serve] cursor account: minted a fresh access token");
+    return body.data.accessToken;
+  }
+}
+
+/**
+ * Mint a named user API key from a short-lived login session token. Used
+ * exactly once per `agent-serve login`; the session token is then discarded.
+ */
+export async function createUserApiKeyWithSessionToken(args: {
+  backendUrl: string;
+  sessionToken: string;
+  keyName: string;
+  fetchImpl?: typeof fetch;
+}): Promise<string> {
+  const response = await dashboardRpc({
+    fetchImpl: args.fetchImpl ?? fetch,
+    backendUrl: args.backendUrl.endsWith("/")
+      ? args.backendUrl.slice(0, -1)
+      : args.backendUrl,
+    method: "CreateUserApiKey",
+    bearer: args.sessionToken,
+    body: { name: args.keyName },
+    timeoutMs: 30_000,
+  });
+  const raw = await parseRpcResponse("CreateUserApiKey", response);
+  return createUserApiKeyResponseSchema.parse(raw).apiKey;
+}
+
+const API_KEY_PREFIX = "crsr_";
+
+/** Matches dashboard `maskApiKey` (`crsr_...abcd`). */
+function maskApiKey(apiKey: string): string {
+  return `${API_KEY_PREFIX}...${apiKey.slice(-4)}`;
+}
+
+const listUserApiKeysResponseSchema = z.object({
+  apiKeys: z
+    .array(
+      z.object({
+        id: z.number(),
+        name: z.string(),
+        maskedKey: z.string().optional(),
+      })
+    )
+    .optional(),
+});
+
+/**
+ * Best-effort cleanup when `login` mints a key but fails before storing it,
+ * authenticated with the browser session token that minted it. The key is
+ * identified by its masked suffix in `ListUserApiKeys` — never by name alone,
+ * so replica lag after `CreateUserApiKey` can only skip the cleanup, not
+ * revoke an older same-named key.
+ */
+export async function revokeMintedUserApiKey(args: {
+  backendUrl: string;
+  keyName: string;
+  /** The raw minted key; selects the exact list row via `maskedKey`. */
+  apiKey: string;
+  /** Session token from the PKCE login; the bearer for list + revoke. */
+  sessionToken: string;
+  fetchImpl?: typeof fetch;
+}): Promise<void> {
+  const fetchImpl = args.fetchImpl ?? fetch;
+  const backendUrl = args.backendUrl.endsWith("/")
+    ? args.backendUrl.slice(0, -1)
+    : args.backendUrl;
+
+  const listResponse = await dashboardRpc({
+    fetchImpl,
+    backendUrl,
+    method: "ListUserApiKeys",
+    bearer: args.sessionToken,
+    body: {},
+    timeoutMs: 30_000,
+  });
+  const listed = listUserApiKeysResponseSchema.parse(
+    await parseRpcResponse("ListUserApiKeys", listResponse)
+  );
+  const masked = maskApiKey(args.apiKey);
+  const match = (listed.apiKeys ?? []).find(
+    (key) => key.name === args.keyName && key.maskedKey === masked
+  );
+  if (match === undefined) {
+    // CreateUserApiKey writes the primary while ListUserApiKeys may read a
+    // lagging replica — skip rather than touch any other key.
+    return;
+  }
+  const revokeResponse = await dashboardRpc({
+    fetchImpl,
+    backendUrl,
+    method: "RevokeUserApiKey",
+    bearer: args.sessionToken,
+    body: { id: match.id },
+    timeoutMs: 30_000,
+  });
+  await drainResponseBody(revokeResponse);
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+const accessTokenResponseSchema = z.object({ accessToken: z.string() });
+
+function safeJsonParse(text: string): unknown {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeInputSchema(schema: unknown): Record<string, unknown> {
+  if (typeof schema === "object" && schema !== null && !Array.isArray(schema)) {
+    return schema as Record<string, unknown>;
+  }
+  return { type: "object", properties: {} };
+}
+
+type McpResultJson = z.infer<typeof mcpResultSchema>;
+
+function toCallResult(result: McpResultJson): AccountMcpCallResult {
+  if (result.success !== undefined) {
+    const content: AccountMcpCallResult["content"] = [];
+    for (const item of result.success.content ?? []) {
+      if (item.text !== undefined) {
+        content.push({ type: "text", text: item.text.text });
+      } else if (item.image !== undefined) {
+        content.push({
+          type: "image",
+          data: item.image.data,
+          ...(item.image.mimeType === undefined
+            ? {}
+            : { mimeType: item.image.mimeType }),
+        });
+      }
+    }
+    return {
+      content,
+      isError: result.success.isError === true,
+      ...(result.success.structuredContent === undefined
+        ? {}
+        : { structuredContent: result.success.structuredContent }),
+    };
+  }
+  return {
+    content: [{ type: "text", text: describeFailure(result) }],
+    isError: true,
+  };
+}
+
+function describeFailure(result: McpResultJson): string {
+  if (result.error !== undefined) {
+    return result.error.error ?? "The tool call failed.";
+  }
+  if (result.permissionDenied !== undefined) {
+    return result.permissionDenied.error ?? "Permission denied.";
+  }
+  if (result.rejected !== undefined) {
+    return `The tool call was rejected${
+      result.rejected.reason === undefined ? "" : `: ${result.rejected.reason}`
+    }.`;
+  }
+  if (result.toolNotFound !== undefined) {
+    return `Unknown tool "${result.toolNotFound.name ?? ""}". Available: ${
+      (result.toolNotFound.availableTools ?? []).join(", ") || "(none)"
+    }.`;
+  }
+  if (result.serverNotFound !== undefined) {
+    return `Unknown MCP server "${result.serverNotFound.name ?? ""}". Available: ${
+      (result.serverNotFound.availableServers ?? []).join(", ") || "(none)"
+    }.`;
+  }
+  return "The tool call returned no result.";
+}
+
+/** Best-effort human-readable message from a Connect error JSON body. */
+function connectErrorMessage(bodyText: string): string {
+  const parsed = safeJsonParse(bodyText);
+  if (
+    typeof parsed === "object" &&
+    parsed !== null &&
+    typeof (parsed as { message?: unknown }).message === "string" &&
+    (parsed as { message: string }).message !== ""
+  ) {
+    return (parsed as { message: string }).message;
+  }
+  return bodyText.slice(0, 300) || "(empty response body)";
+}
+
+function jwtExpiryMs(token: string): number {
+  try {
+    const payload = token.split(".")[1];
+    if (payload === undefined) {
+      throw new Error("not a JWT");
+    }
+    const claims = JSON.parse(
+      Buffer.from(payload, "base64url").toString("utf8")
+    ) as { exp?: unknown };
+    if (typeof claims.exp === "number") {
+      return claims.exp * 1000;
+    }
+  } catch {
+    // Opaque token — assume a conservative lifetime.
+  }
+  return Date.now() + FALLBACK_TOKEN_LIFETIME_MS;
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Release undici/fetch connection slots on responses we will not parse. */
+async function drainResponseBody(response: Response): Promise<void> {
+  try {
+    await response.arrayBuffer();
+  } catch {
+    // Best-effort; the socket may already be closed.
+  }
+}