@cursor/july 0.1.1

package/src/internal/cursor/credentials.ts

@@ -0,0 +1,401 @@
+/**
+ * Cursor account credentials for the agent-serve host.
+ *
+ * Exactly one kind of secret exists at runtime: a **personal Cursor user API
+ * key**. Two ways to obtain it, one code path after that:
+ *
+ * - `agent-serve login` runs the same PKCE browser flow as `cursor-agent`
+ *   and Sand, then uses the short-lived session once to mint a named,
+ *   dashboard-revocable user API key — only the key is stored.
+ * - `CURSOR_API_KEY` (or `serve({ apiKey })`) wins over the stored key, so
+ *   CI and hosted deployments stay env-driven.
+ *
+ * There is deliberately no session-token storage, refresh-token rotation, or
+ * cross-tool credential sharing here: short-lived access tokens are minted
+ * on demand from the API key (see `backend-client.ts`).
+ */
+
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { CLI_COMMAND_NAME } from "../distribution.js";
+
+export const DEFAULT_CURSOR_BACKEND_URL = "https://api2.cursor.sh";
+const DEFAULT_CURSOR_WEBSITE_URL = "https://cursor.com";
+
+/** Backend API base URL (`CURSOR_API_BASE_URL` override for local dev). */
+export function cursorBackendUrl(): string {
+  return trimTrailingSlash(
+    process.env.CURSOR_API_BASE_URL ?? DEFAULT_CURSOR_BACKEND_URL
+  );
+}
+
+/** Website base URL for the login deep link (`CURSOR_WEBSITE_URL` override). */
+export function cursorWebsiteUrl(): string {
+  return trimTrailingSlash(
+    process.env.CURSOR_WEBSITE_URL ?? DEFAULT_CURSOR_WEBSITE_URL
+  );
+}
+
+function trimTrailingSlash(url: string): string {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+
+// ============================================================================
+// Stored credential (one file, one secret)
+// ============================================================================
+
+const storedCredentialsSchema: z.ZodObject<
+  { backendUrl: z.ZodString; apiKey: z.ZodString },
+  "strip"
+> = z.object({
+  /** Backend the key was minted against; keys never cross backends. */
+  backendUrl: z.string(),
+  apiKey: z.string().min(1),
+});
+
+export type StoredCredentials = z.infer<typeof storedCredentialsSchema>;
+
+/**
+ * `~/.config/agent-serve/credentials.json` (0600), honoring
+ * `XDG_CONFIG_HOME`. `AGENT_SERVE_CONFIG_DIR` pins the directory outright
+ * (tests, containers).
+ */
+export function credentialsFilePath(): string {
+  const configDir =
+    process.env.AGENT_SERVE_CONFIG_DIR ??
+    join(
+      process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"),
+      "agent-serve"
+    );
+  return join(configDir, "credentials.json");
+}
+
+export async function readStoredCredentials(): Promise<
+  StoredCredentials | undefined
+> {
+  let raw: string;
+  try {
+    raw = await readFile(credentialsFilePath(), "utf8");
+  } catch {
+    return undefined;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    // Corrupt file — treat as signed out; login rewrites it.
+    return undefined;
+  }
+  const credentials = storedCredentialsSchema.safeParse(parsed);
+  if (!credentials.success) {
+    return undefined;
+  }
+  return {
+    backendUrl: trimTrailingSlash(credentials.data.backendUrl),
+    apiKey: credentials.data.apiKey,
+  };
+}
+
+export async function writeStoredCredentials(
+  credentials: StoredCredentials
+): Promise<void> {
+  const path = credentialsFilePath();
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await writeFile(path, `${JSON.stringify(credentials, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  // writeFile mode only applies on create; clamp pre-existing files too.
+  await chmod(path, 0o600);
+}
+
+export async function clearStoredCredentials(): Promise<boolean> {
+  try {
+    await rm(credentialsFilePath());
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ============================================================================
+// Resolution (option > env > stored login)
+// ============================================================================
+
+export type ApiKeySource = "option" | "env" | "login";
+
+export interface ResolvedApiKey {
+  apiKey: string;
+  source: ApiKeySource;
+  backendUrl: string;
+}
+
+/**
+ * Resolve the account API key for `backendUrl` (defaults to the active
+ * backend): explicit option → `CURSOR_API_KEY` → stored login. A stored key
+ * minted against a different backend is ignored rather than sent to the
+ * wrong host.
+ */
+export async function resolveApiKey(options?: {
+  apiKey?: string;
+  backendUrl?: string;
+}): Promise<ResolvedApiKey | undefined> {
+  const backendUrl = options?.backendUrl ?? cursorBackendUrl();
+  if (options?.apiKey !== undefined && options.apiKey.trim() !== "") {
+    return { apiKey: options.apiKey.trim(), source: "option", backendUrl };
+  }
+  const envKey = process.env.CURSOR_API_KEY;
+  if (envKey !== undefined && envKey.trim() !== "") {
+    return { apiKey: envKey.trim(), source: "env", backendUrl };
+  }
+  const stored = await readStoredCredentials();
+  if (stored !== undefined && stored.backendUrl === backendUrl) {
+    return { apiKey: stored.apiKey, source: "login", backendUrl };
+  }
+  return undefined;
+}
+
+/** One-line hint for "no credentials" errors, shared across surfaces. */
+export const SIGN_IN_HINT: string = `Run \`${CLI_COMMAND_NAME} login\` (or set CURSOR_API_KEY / pass serve({ apiKey })).`;
+
+// ============================================================================
+// PKCE browser login (mirrors cursor-agent / Sand)
+// ============================================================================
+
+const loginPollResponseSchema = z.object({ accessToken: z.string() });
+
+export interface LoginStart {
+  /** URL the user opens in a browser to approve the login. */
+  loginUrl: string;
+  uuid: string;
+  verifier: string;
+}
+
+/**
+ * Build the `/loginDeepControl` deep link and its PKCE material. The portal
+ * completes the login and the backend holds the resulting session until
+ * {@link pollForLoginTokens} picks it up with the verifier.
+ */
+export function startBrowserLogin(): LoginStart {
+  const verifier = randomBytes(32).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  const uuid = randomUUID();
+  const url = new URL("/loginDeepControl", `${cursorWebsiteUrl()}/`);
+  url.searchParams.set("challenge", challenge);
+  url.searchParams.set("uuid", uuid);
+  url.searchParams.set("mode", "login");
+  url.searchParams.set("redirectTarget", "cli");
+  return { loginUrl: url.toString(), uuid, verifier };
+}
+
+/** Backend pending-login 404 body from `respondToPollLogin` ("still waiting"). */
+const POLL_PENDING_BODY = "Not found";
+
+/**
+ * Why the poll stopped. Distinct cases because collapsing them into
+ * "timed out or was cancelled" turned an unsupported-verb 404 into an
+ * unfalsifiable "login is slow" report.
+ */
+export type LoginPollResult =
+  | { status: "signed_in"; accessToken: string }
+  | { status: "cancelled" }
+  | { status: "timed_out" }
+  | { status: "failed"; message: string };
+
+/**
+ * Poll `/auth/poll` until the browser login completes.
+ *
+ * **POST, with the verifier in the JSON body.** The verifier is redeemable:
+ * anyone holding it (plus the uuid) can complete the login and mint a durable
+ * user API key, so it must not reach a URL — not the backend's access log, not
+ * a proxy's request log, not a terminal. `POST /auth/poll` exists for exactly
+ * this reason.
+ *
+ * A backend that predates that route answers POST with a route-not-found 404.
+ * Those get one sticky fallback to `GET /auth/poll?uuid=…&verifier=…` — the
+ * shape the vscode client and Sand already use — so the login still works
+ * while the backend catches up. The fallback puts the verifier in the query
+ * string, which is the exposure POST was added to remove, so it warns; it
+ * disappears on its own once the backend serves POST.
+ */
+export async function pollForLoginTokens(args: {
+  uuid: string;
+  verifier: string;
+  backendUrl?: string;
+  signal?: AbortSignal;
+  /** Notified once if the backend forces the GET fallback. */
+  logger?: (line: string) => void;
+  /** Test seam; defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+  /** Test seam; defaults to 150 (~24 minutes with the backoff below). */
+  maxAttempts?: number;
+}): Promise<LoginPollResult> {
+  const backendUrl = trimTrailingSlash(args.backendUrl ?? cursorBackendUrl());
+  const fetchImpl = args.fetchImpl ?? fetch;
+  const redact = (text: string): string =>
+    truncate(redactVerifier(text, args.verifier));
+
+  const postUrl = `${backendUrl}/auth/poll`;
+  // Only built if the backend leaves us no choice (see the doc comment).
+  const getUrl = (): string => {
+    const url = new URL("/auth/poll", `${backendUrl}/`);
+    url.searchParams.set("uuid", args.uuid);
+    url.searchParams.set("verifier", args.verifier);
+    return url.toString();
+  };
+
+  const maxAttempts = args.maxAttempts ?? 150;
+  let useGet = false;
+  let consecutiveErrors = 0;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    if (isAborted(args.signal)) {
+      return { status: "cancelled" };
+    }
+    try {
+      const response = useGet
+        ? await fetchImpl(getUrl(), {
+            method: "GET",
+            headers: { accept: "application/json" },
+            ...(args.signal === undefined ? {} : { signal: args.signal }),
+          })
+        : await fetchImpl(postUrl, {
+            method: "POST",
+            headers: {
+              accept: "application/json",
+              "content-type": "application/json",
+            },
+            body: JSON.stringify({ uuid: args.uuid, verifier: args.verifier }),
+            ...(args.signal === undefined ? {} : { signal: args.signal }),
+          });
+
+      if (response.status === 404) {
+        const body = (await response.text()).trim();
+        if (!useGet && body !== POLL_PENDING_BODY) {
+          // Any 404 on POST that is not the pending marker means this backend
+          // has no POST route. Retry the same attempt over GET rather than
+          // guessing at body shapes; GET's handling below is deliberately
+          // lenient, so an unrecognized body cannot strand the login.
+          useGet = true;
+          args.logger?.(
+            `${backendUrl} has no POST /auth/poll; falling back to GET, which puts the single-use login verifier in the request URL (and the backend's access log). It will use POST once the backend deploys that route.`
+          );
+          continue;
+        }
+        if (useGet && isRouteNotFoundBody(body)) {
+          // Neither verb is served — polling harder cannot fix that.
+          return {
+            status: "failed",
+            message: `${backendUrl} serves neither POST nor GET /auth/poll (404: ${redact(body)})`,
+          };
+        }
+        // Pending: the browser sign-in has not landed yet. On GET this is
+        // deliberately lenient — treating an unrecognized 404 body as fatal is
+        // what made an earlier poll die on its first attempt and call it a
+        // timeout.
+        consecutiveErrors = 0;
+      } else if (!response.ok) {
+        consecutiveErrors++;
+        if (consecutiveErrors >= 3) {
+          return {
+            status: "failed",
+            message: `${backendUrl}/auth/poll kept failing (${response.status}: ${redact((await response.text()).trim())})`,
+          };
+        }
+      } else {
+        const body = loginPollResponseSchema.safeParse(await response.json());
+        if (body.success && body.data.accessToken !== "") {
+          return { status: "signed_in", accessToken: body.data.accessToken };
+        }
+        return {
+          status: "failed",
+          message: `${backendUrl}/auth/poll returned 200 without an accessToken`,
+        };
+      }
+    } catch (error) {
+      if (isAborted(args.signal)) {
+        return { status: "cancelled" };
+      }
+      consecutiveErrors++;
+      if (consecutiveErrors >= 3) {
+        return {
+          status: "failed",
+          message: `could not reach ${backendUrl}/auth/poll (${redact(
+            error instanceof Error ? error.message : String(error)
+          )})`,
+        };
+      }
+    }
+    await sleep(Math.min(1000 * 1.2 ** attempt, 10_000), args.signal);
+  }
+  return { status: "timed_out" };
+}
+
+/**
+ * Fastify's route-not-found envelope: `{"message":"Route GET:/auth/poll not
+ * found",…}`. Distinct from the backend's pending marker ({@link
+ * POLL_PENDING_BODY}), and the only 404 shape on the GET path that is fatal.
+ */
+function isRouteNotFoundBody(body: string): boolean {
+  if (!body.startsWith("{")) {
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(body) as { message?: unknown };
+    return (
+      typeof parsed.message === "string" &&
+      /^Route \w+:/.test(parsed.message) &&
+      parsed.message.includes("not found")
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Keep the verifier out of anything user-visible. Fastify's 404 body echoes the
+ * whole request URL — `Route GET:/auth/poll?uuid=…&verifier=… not found` — so
+ * echoing a poll response verbatim would print a redeemable secret into the
+ * terminal, CI logs, and pasted bug reports.
+ */
+function redactVerifier(text: string, verifier: string): string {
+  if (verifier === "") {
+    return text;
+  }
+  let redacted = text.split(verifier).join("[verifier redacted]");
+  const encoded = encodeURIComponent(verifier);
+  if (encoded !== verifier) {
+    redacted = redacted.split(encoded).join("[verifier redacted]");
+  }
+  return redacted;
+}
+
+function truncate(value: string, max = 200): string {
+  return value.length <= max ? value : `${value.slice(0, max)}…`;
+}
+
+// Reads the abort flag through a call boundary so repeated checks across an
+// `await` aren't collapsed by control-flow narrowing (the signal is mutated
+// by another task, so `aborted` really can flip mid-loop).
+function isAborted(signal?: AbortSignal): boolean {
+  return signal?.aborted === true;
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted === true) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/internal/cursor-event-relay.ts

@@ -0,0 +1,281 @@
+/**
+ * Pulls `/v0/scm-events` into agent-serve: register repos+events, long-poll
+ * with a durable offset under `<stateDir>/offset.json`. Registration-gated
+ * so consumption never starts unsubscribed. Shared streams: durable
+ * consumer id + repo/event filtering skip sibling deliveries.
+ *
+ * The long-poll lifecycle (consumer id, registration-gated consume loop,
+ * anchor/offset/backoff) lives in the shared {@link CursorRelayCore}; this
+ * module is the GitHub adapter over it. {@link RelayOffsetStore} and
+ * {@link compareStreamOffsets} are re-exported for stability.
+ */
+
+import {
+  CursorRelayCore,
+  type RelayAdapter,
+  RelayOffsetStore,
+} from "./cursor-relay-core.js";
+
+export { RelayOffsetStore };
+
+/** PR snapshot from scm-events compact metadata (Sand-style; no raw body). */
+export type CursorScmPullRequestMeta = {
+  number: number;
+  url: string;
+  title?: string;
+  body?: string | null;
+  draft?: boolean;
+  authorLogin?: string;
+  headRef?: string;
+  headSha?: string;
+  baseRef?: string;
+  baseSha?: string;
+};
+
+/** One event delivered by `GET /v0/scm-events` (metadata only). */
+export interface CursorScmEvent {
+  offset: string;
+  provider: string;
+  eventName: string;
+  deliveryId?: string;
+  repo: string;
+  receivedAtMs: number;
+  /** Webhook `action` when present. */
+  action?: string;
+  /** PR number when the delivery is PR-scoped. */
+  prNumber?: number;
+  /** Canonical PR URL when known. */
+  prUrl?: string;
+  /**
+   * Richer PR snapshot when the backend saw `body.pull_request`. Enough to
+   * stub a Zod-valid GitHub `pull_request` webhook body.
+   */
+  pullRequest?: CursorScmPullRequestMeta;
+  /** GitHub-side event time from the payload, when present. */
+  occurredAtMs?: number;
+}
+
+interface SubscriptionStatus {
+  provider: string;
+  repo: string;
+  isSubscribed: boolean;
+  detail?: string;
+}
+
+export interface CursorEventRelayOptions {
+  baseUrl: string;
+  apiKey: string;
+  repos: readonly string[];
+  events: readonly string[];
+  stateDir: string;
+  /** Called for each matching event; failures are logged, not retried. */
+  dispatch: (event: CursorScmEvent) => Promise<void>;
+  logger: (line: string) => void;
+  /** Test seam. Defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+  /** Test seam: override long-poll wait (default 25s). */
+  pollWaitMs?: number;
+}
+
+/** Human-readable cursor-events log fragment: event, repo/PR, times, delivery. */
+export function formatCursorScmEventLog(event: {
+  eventName: string;
+  repo: string;
+  action?: string;
+  prNumber?: number;
+  prUrl?: string;
+  receivedAtMs: number;
+  occurredAtMs?: number;
+  deliveryId?: string;
+}): string {
+  const action =
+    event.action !== undefined && event.action !== "" ? `.${event.action}` : "";
+  const pr =
+    event.prUrl !== undefined
+      ? event.prUrl
+      : event.prNumber !== undefined
+        ? `${event.repo}#${event.prNumber}`
+        : event.repo;
+  const received = new Date(event.receivedAtMs).toISOString();
+  const occurred =
+    event.occurredAtMs !== undefined
+      ? ` occurred=${new Date(event.occurredAtMs).toISOString()}`
+      : "";
+  const delivery = event.deliveryId ?? "no delivery id";
+  return `${event.eventName}${action} on ${pr} received=${received}${occurred} (${delivery})`;
+}
+
+/**
+ * Minimal GitHub webhook body from an SCM-events metadata envelope.
+ * When `pullRequest` has title + head/base refs+shas, emits a Zod-valid
+ * `pull_request` object for `onPullRequest`; otherwise identity-only stubs.
+ */
+export function scmMetadataToGitHubPayload(event: {
+  repo: string;
+  action?: string;
+  prNumber?: number;
+  prUrl?: string;
+  pullRequest?: CursorScmPullRequestMeta;
+}): Record<string, unknown> {
+  const slash = event.repo.indexOf("/");
+  const owner = slash === -1 ? "" : event.repo.slice(0, slash);
+  const name = slash === -1 ? event.repo : event.repo.slice(slash + 1);
+  const repoUrl = `https://github.com/${event.repo}`;
+  const prMeta = event.pullRequest;
+  const prNumber = prMeta?.number ?? event.prNumber;
+  const prUrl =
+    prMeta?.url ??
+    event.prUrl ??
+    (prNumber !== undefined ? `${repoUrl}/pull/${prNumber}` : undefined);
+
+  const payload: Record<string, unknown> = {
+    repository: {
+      full_name: event.repo,
+      name,
+      html_url: repoUrl,
+      owner: { login: owner },
+    },
+  };
+  payload.action = event.action;
+
+  const title = prMeta?.title;
+  const headRef = prMeta?.headRef;
+  const headSha = prMeta?.headSha;
+  const baseRef = prMeta?.baseRef;
+  const canStubTypedPr =
+    prNumber !== undefined &&
+    prUrl !== undefined &&
+    title !== undefined &&
+    headRef !== undefined &&
+    headSha !== undefined &&
+    baseRef !== undefined;
+
+  if (canStubTypedPr) {
+    const pullRequest: Record<string, unknown> = {
+      number: prNumber,
+      html_url: prUrl,
+      title,
+      body: prMeta?.body,
+      draft: prMeta?.draft,
+      head: { ref: headRef, sha: headSha },
+      base: { ref: baseRef, sha: prMeta?.baseSha },
+    };
+    if (prMeta?.authorLogin !== undefined) {
+      pullRequest.user = { login: prMeta.authorLogin };
+    }
+    payload.pull_request = pullRequest;
+    payload.issue = {
+      number: prNumber,
+      html_url: prUrl,
+      pull_request: {},
+    };
+    return payload;
+  }
+
+  if (prNumber !== undefined) {
+    payload.pull_request = {
+      number: prNumber,
+      html_url: prUrl ?? `${repoUrl}/pull/${prNumber}`,
+    };
+    payload.issue = {
+      number: prNumber,
+      html_url: prUrl ?? `${repoUrl}/pull/${prNumber}`,
+      pull_request: {},
+    };
+  }
+  return payload;
+}
+
+/**
+ * GitHub SCM-events relay: a thin {@link CursorRelayCore} adapter. Consumers
+ * keep the same `new CursorEventRelay(options).start()/.stop()` surface.
+ */
+export class CursorEventRelay {
+  private readonly core: CursorRelayCore<CursorScmEvent>;
+  /**
+   * Normalized repos the server confirmed for THIS consumer. The stream is
+   * shared with sibling consumers of the same principal, so only events for
+   * these repos may dispatch.
+   */
+  private subscribedRepos = new Set<string>();
+  private readonly loggedSkippedRepos = new Set<string>();
+
+  constructor(private readonly options: CursorEventRelayOptions) {
+    const adapter: RelayAdapter<CursorScmEvent> = {
+      logPrefix: "cursor-events",
+      subscribePath: "/v0/scm-events/subscriptions",
+      pollPath: "/v0/scm-events",
+      buildRegistrationBody: (consumerId) => ({
+        consumerId,
+        subscriptions: this.options.repos.map((repo) => ({
+          provider: "github",
+          repo,
+          events: [...this.options.events],
+        })),
+      }),
+      applyRegistrationResponse: (json) => {
+        const result = json as { repos?: SubscriptionStatus[] };
+        const statuses = result.repos ?? [];
+        this.subscribedRepos = new Set(
+          statuses
+            .filter((status) => status.isSubscribed)
+            .map((status) => status.repo)
+        );
+        const lines: string[] = [];
+        for (const status of statuses.filter((s) => !s.isSubscribed)) {
+          lines.push(
+            `not subscribed to ${status.repo}: ${status.detail ?? "unknown reason"}`
+          );
+        }
+        if (this.subscribedRepos.size > 0) {
+          lines.push(
+            `subscribed to ${[...this.subscribedRepos].join(", ")} for events: ${this.options.events.join(", ")}`
+          );
+        }
+        return lines;
+      },
+      shouldDispatch: (event) => this.shouldDispatch(event),
+      dispatch: (event) => this.options.dispatch(event),
+    };
+    this.core = new CursorRelayCore<CursorScmEvent>({
+      baseUrl: options.baseUrl,
+      apiKey: options.apiKey,
+      stateDir: options.stateDir,
+      adapter,
+      logger: options.logger,
+      ...(options.fetchImpl === undefined
+        ? {}
+        : { fetchImpl: options.fetchImpl }),
+      ...(options.pollWaitMs === undefined
+        ? {}
+        : { pollWaitMs: options.pollWaitMs }),
+    });
+  }
+
+  /**
+   * Whether an event from the shared stream belongs to THIS consumer: the
+   * repo must be one the server confirmed for us and the event kind one the
+   * mounted channels declared. Anything else came from a sibling consumer's
+   * subscription and must not fire this host's hooks.
+   */
+  private shouldDispatch(event: CursorScmEvent): boolean {
+    if (!this.subscribedRepos.has(event.repo)) {
+      if (!this.loggedSkippedRepos.has(event.repo)) {
+        this.loggedSkippedRepos.add(event.repo);
+        this.options.logger(
+          `[agent-serve] cursor-events: skipping events for ${event.repo}: not in this host's subscription (another consumer of this API key likely subscribed it)`
+        );
+      }
+      return false;
+    }
+    return this.options.events.includes(event.eventName);
+  }
+
+  start(): void {
+    this.core.start();
+  }
+
+  async stop(): Promise<void> {
+    await this.core.stop();
+  }
+}