@cursor/july 0.1.1 → 0.1.2

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

@@ -30,7 +30,8 @@ const EXECUTE_TIMEOUT_MS = 120_000;
 export class CursorBackendError extends Error {
   constructor(
     message: string,
-    readonly status?: number
+    readonly status?: number,
+    readonly retryAfterMs?: number
   ) {
     super(message);
     this.name = "CursorBackendError";
@@ -65,6 +66,16 @@ const createUserApiKeyResponseSchema = z.object({
   apiKey: z.string().min(1),
 });
 
+export interface CursorGithubToken {
+  token: string;
+  expiresAt: string;
+}
+
+const githubTokenResponseSchema: z.ZodType<CursorGithubToken> = z.object({
+  token: z.string().min(1),
+  expiresAt: z.string().datetime(),
+});
+
 const mcpToolSchema = z.object({
   name: z.string(),
   providerIdentifier: z.string().optional(),
@@ -298,6 +309,50 @@ export class CursorBackendClient {
     return toCallResult(parsed.result ?? {});
   }
 
+  /** Mint a short-lived GitHub token scoped to the requested repositories. */
+  async getGithubToken(
+    repos: readonly string[],
+    options?: { permissions?: "read" | "pr-write" | "contents-write" }
+  ): Promise<CursorGithubToken> {
+    const permissions = options?.permissions ?? "pr-write";
+    let response: Response;
+    try {
+      response = await this.fetchImpl(
+        `${this.backendUrl}/v0/scm-events/github-token`,
+        {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${this.apiKey}`,
+          },
+          body: JSON.stringify({ repos: [...repos], permissions }),
+          signal: AbortSignal.timeout(30_000),
+        }
+      );
+    } catch (error) {
+      throw new CursorBackendError(
+        `Cursor GitHub credential request failed: ${describeError(error)}`
+      );
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      throw new CursorBackendError(
+        describeGithubTokenHttpFailure(response.status, text),
+        response.status,
+        retryAfterMsFromResponse(response)
+      );
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text) as unknown;
+    } catch {
+      throw new CursorBackendError(
+        "Cursor backend returned a non-JSON GitHub credential response."
+      );
+    }
+    return githubTokenResponseSchema.parse(parsed);
+  }
+
   private async rpc(
     method: string,
     body: unknown,
@@ -582,6 +637,53 @@ function connectErrorMessage(bodyText: string): string {
   return bodyText.slice(0, 300) || "(empty response body)";
 }
 
+const MAX_GITHUB_TOKEN_RETRY_AFTER_MS = 60 * 60_000;
+
+/**
+ * Prefer the backend's actionable denial message. Only a true 401 on this
+ * route means the Cursor API key itself was rejected — GitHub-connection
+ * problems arrive as 403 with a server `error` string.
+ */
+function describeGithubTokenHttpFailure(
+  status: number,
+  bodyText: string
+): string {
+  const detail = githubTokenErrorFromBody(bodyText);
+  if (status === 401) {
+    return `The Cursor API key was rejected${
+      detail === undefined ? "" : `: ${detail}`
+    }. Run \`agent-serve login\` again or update CURSOR_API_KEY.`;
+  }
+  if (detail !== undefined) {
+    return detail;
+  }
+  return `Cursor GitHub credential request failed (${status}).`;
+}
+
+function githubTokenErrorFromBody(bodyText: string): string | undefined {
+  const parsed = safeJsonParse(bodyText);
+  if (typeof parsed !== "object" || parsed === null) {
+    return undefined;
+  }
+  const error = (parsed as { error?: unknown }).error;
+  if (typeof error === "string" && error !== "") {
+    return error;
+  }
+  const message = (parsed as { message?: unknown }).message;
+  if (typeof message === "string" && message !== "") {
+    return message;
+  }
+  return undefined;
+}
+
+function retryAfterMsFromResponse(response: Response): number | undefined {
+  const retryAfter = Number(response.headers.get("retry-after") ?? "");
+  if (!Number.isFinite(retryAfter) || retryAfter <= 0) {
+    return undefined;
+  }
+  return Math.min(retryAfter * 1000, MAX_GITHUB_TOKEN_RETRY_AFTER_MS);
+}
+
 function jwtExpiryMs(token: string): number {
   try {
     const payload = token.split(".")[1];

package/src/internal/cursor/github-credentials.ts

@@ -0,0 +1,248 @@
+/**
+ * Short-lived GitHub credentials minted from the host's Cursor account.
+ *
+ * The token stays in memory. `GH_TOKEN` is updated for child `gh` processes,
+ * while Octokit callers use {@link getToken} so long-lived clients refresh
+ * without being rebuilt.
+ */
+
+import type { CursorGithubRepoScope } from "../../channels/github/cursor-account.js";
+import type { CursorBackendClient } from "./backend-client.js";
+import { CursorBackendError } from "./backend-client.js";
+
+const REFRESH_LEEWAY_MS = 5 * 60_000;
+const REFRESH_RETRY_MS = 60_000;
+const FAILURE_CACHE_TTL_MS = 60_000;
+const MAX_RETRY_AFTER_MS = 60 * 60_000;
+const MIN_TIMER_DELAY_MS = 1_000;
+
+type GithubTokenClient = Pick<CursorBackendClient, "getGithubToken">;
+
+export interface CursorGithubCredentialProviderOptions {
+  client: GithubTokenClient;
+  scope: CursorGithubRepoScope;
+  logger?: (line: string) => void;
+  /** Test seam. */
+  now?: () => number;
+}
+
+interface CachedGithubToken {
+  token: string;
+  expiresAtMs: number;
+  refreshAtMs: number;
+}
+
+interface CachedFailure {
+  message: string;
+  retryAtMs: number;
+}
+
+export class CursorGithubCredentialProvider {
+  private readonly client: GithubTokenClient;
+  private readonly repos: string[];
+  private readonly permissions: CursorGithubRepoScope["permissions"];
+  private readonly logger: (line: string) => void;
+  private readonly now: () => number;
+  private cached: CachedGithubToken | undefined;
+  private failure: CachedFailure | undefined;
+  private refreshPromise: Promise<string> | undefined;
+  private refreshTimer: ReturnType<typeof setTimeout> | undefined;
+  private started = false;
+  private stopped = false;
+  private previousGhToken: string | undefined;
+  private installedGhToken: string | undefined;
+
+  constructor(options: CursorGithubCredentialProviderOptions) {
+    this.client = options.client;
+    this.repos = [...options.scope.repos];
+    this.permissions = options.scope.permissions;
+    this.logger = options.logger ?? (() => {});
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  async start(): Promise<void> {
+    if (this.stopped) {
+      throw new Error("Cursor account GitHub credentials have been stopped.");
+    }
+    if (this.started) {
+      return;
+    }
+    this.previousGhToken = process.env.GH_TOKEN;
+    this.started = true;
+    try {
+      const token = await this.getToken();
+      this.installGhToken(token);
+      this.scheduleRefresh();
+    } catch (error) {
+      this.started = false;
+      this.restoreGhToken();
+      throw error;
+    }
+  }
+
+  async getToken(): Promise<string> {
+    if (this.stopped) {
+      throw new Error("Cursor account GitHub credentials have been stopped.");
+    }
+    const now = this.now();
+    if (this.cached !== undefined && now >= this.cached.expiresAtMs) {
+      // Expired leases must not be served; drop them so the next mint is clean.
+      this.cached = undefined;
+      this.restoreGhToken();
+    }
+    if (this.cached !== undefined && now < this.cached.refreshAtMs) {
+      return this.cached.token;
+    }
+    if (
+      this.failure !== undefined &&
+      now < this.failure.retryAtMs &&
+      this.cached === undefined
+    ) {
+      throw new Error(this.failure.message);
+    }
+    if (this.refreshPromise === undefined) {
+      this.refreshPromise = this.refresh().finally(() => {
+        this.refreshPromise = undefined;
+      });
+    }
+    return this.refreshPromise;
+  }
+
+  stop(): void {
+    this.started = false;
+    this.stopped = true;
+    if (this.refreshTimer !== undefined) {
+      clearTimeout(this.refreshTimer);
+      this.refreshTimer = undefined;
+    }
+    this.cached = undefined;
+    this.failure = undefined;
+    this.restoreGhToken();
+  }
+
+  private async refresh(): Promise<string> {
+    try {
+      const result = await this.client.getGithubToken(this.repos, {
+        permissions: this.permissions,
+      });
+      if (this.stopped) {
+        throw new Error("Cursor account GitHub credentials have been stopped.");
+      }
+      const expiresAtMs = Date.parse(result.expiresAt);
+      if (
+        !Number.isFinite(expiresAtMs) ||
+        expiresAtMs <= this.now() + REFRESH_LEEWAY_MS
+      ) {
+        throw new Error(
+          "Cursor backend returned an invalid GitHub credential expiry."
+        );
+      }
+      this.failure = undefined;
+      this.cached = {
+        token: result.token,
+        expiresAtMs,
+        refreshAtMs: expiresAtMs - REFRESH_LEEWAY_MS,
+      };
+      if (this.started) {
+        this.installGhToken(result.token);
+        this.scheduleRefresh();
+      }
+      this.logger(
+        `[agent-serve] GitHub auth: refreshed Cursor account credential for ${this.repos.length} repo(s)`
+      );
+      return result.token;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (this.cached !== undefined && this.now() < this.cached.expiresAtMs) {
+        this.logger(
+          `[agent-serve] GitHub auth: Cursor account credential refresh failed; using the current lease: ${message}`
+        );
+        this.cached.refreshAtMs = Math.min(
+          this.cached.expiresAtMs,
+          this.now() + REFRESH_RETRY_MS
+        );
+        if (this.started) {
+          this.scheduleRetry();
+        }
+        return this.cached.token;
+      }
+      // Hard failure with no usable lease: evict any stale cache and back off.
+      this.cached = undefined;
+      this.restoreGhToken();
+      this.failure = {
+        message,
+        retryAtMs: this.now() + failureBackoffMs(error),
+      };
+      if (this.started) {
+        this.scheduleRetry();
+      }
+      throw error instanceof Error ? error : new Error(message);
+    }
+  }
+
+  private scheduleRefresh(): void {
+    if (!this.started || this.cached === undefined) {
+      return;
+    }
+    this.replaceTimer(
+      Math.max(MIN_TIMER_DELAY_MS, this.cached.refreshAtMs - this.now())
+    );
+  }
+
+  private scheduleRetry(): void {
+    if (!this.started) {
+      return;
+    }
+    const delayMs =
+      this.failure !== undefined
+        ? Math.max(MIN_TIMER_DELAY_MS, this.failure.retryAtMs - this.now())
+        : REFRESH_RETRY_MS;
+    this.replaceTimer(delayMs);
+  }
+
+  private replaceTimer(delayMs: number): void {
+    if (this.refreshTimer !== undefined) {
+      clearTimeout(this.refreshTimer);
+    }
+    this.refreshTimer = setTimeout(() => {
+      void this.getToken().catch((error: unknown) => {
+        this.logger(
+          `[agent-serve] GitHub auth: Cursor account credential refresh failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+        this.scheduleRetry();
+      });
+    }, delayMs);
+    this.refreshTimer.unref?.();
+  }
+
+  private installGhToken(token: string): void {
+    process.env.GH_TOKEN = token;
+    this.installedGhToken = token;
+  }
+
+  private restoreGhToken(): void {
+    if (
+      this.installedGhToken !== undefined &&
+      process.env.GH_TOKEN === this.installedGhToken
+    ) {
+      if (this.previousGhToken === undefined) {
+        delete process.env.GH_TOKEN;
+      } else {
+        process.env.GH_TOKEN = this.previousGhToken;
+      }
+    }
+    this.installedGhToken = undefined;
+  }
+}
+
+function failureBackoffMs(error: unknown): number {
+  if (error instanceof CursorBackendError && error.retryAfterMs !== undefined) {
+    return Math.min(
+      Math.max(error.retryAfterMs, FAILURE_CACHE_TTL_MS),
+      MAX_RETRY_AFTER_MS
+    );
+  }
+  return FAILURE_CACHE_TTL_MS;
+}