pi-provider-cursor-ask 0.1.0

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "pi-provider-cursor-ask",
+  "version": "0.1.0",
+  "description": "Standalone Cursor provider for focused Pi advisor and review workflows.",
+  "author": "zhcsyncer",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhcsyncer/pi-extensions.git",
+    "directory": "providers/pi-provider-cursor-ask"
+  },
+  "homepage": "https://github.com/zhcsyncer/pi-extensions/tree/main/providers/pi-provider-cursor-ask#readme",
+  "bugs": {
+    "url": "https://github.com/zhcsyncer/pi-extensions/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-provider",
+    "cursor",
+    "oauth",
+    "advisor",
+    "review"
+  ],
+  "files": [
+    "LICENSE",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "UPSTREAM_CHANGELOG.md",
+    "UPSTREAM_SOURCE.md",
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup --silent",
+    "prepare": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests",
+    "lint:fix": "eslint src tests --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "security-check": "tsx scripts/security-check.ts",
+    "proto:gen": "buf generate",
+    "proto:sync": "tsx scripts/proto-sync.ts",
+    "proto:check": "tsx scripts/proto-check.ts",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "test:legacy": "tsx scripts/test-model-routing.ts && tsx scripts/test-thinking-levels.ts && tsx scripts/test-usage.ts && tsx scripts/test-context-mode-normalize.ts && tsx scripts/test-cli-auth.ts",
+    "smoke:auth": "node --import tsx scripts/smoke-auth.mjs",
+    "smoke:models": "node --import tsx scripts/smoke-models.mjs",
+    "smoke:stream": "node --import tsx scripts/smoke-stream.mjs",
+    "smoke:wire": "node --import tsx scripts/smoke-wire.mjs",
+    "check": "pnpm typecheck && pnpm lint && pnpm format:check && pnpm security-check && pnpm proto:check && pnpm test && pnpm test:legacy && pnpm build"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "2.13.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@bufbuild/buf": "1.72.0",
+    "@bufbuild/protoc-gen-es": "2.13.0",
+    "@earendil-works/pi-ai": "0.84.0",
+    "@earendil-works/pi-coding-agent": "0.84.0",
+    "@earendil-works/pi-tui": "0.84.0",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^10.7.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.7.0",
+    "prettier": "^3.9.5",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.64.0",
+    "vitest": "^3.2.4"
+  }
+}

package/src/auth/cli-credentials.ts

@@ -0,0 +1,275 @@
+import { existsSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+
+const execFileAsync = promisify(execFile);
+import { systemCredentialsAllowed } from "./consent.js";
+import { getCursorAccessTokenFromEnv, getTokenExpiry, refreshCursorToken } from "./oauth.js";
+import { isRefreshKnownBad, markRefreshFailed, markRefreshSucceeded } from "./refresh-guard.js";
+import { CredentialSource } from "../types/enums.js";
+
+export { CredentialSource };
+
+export interface CursorTokenResult {
+  accessToken: string;
+  source: CredentialSource;
+}
+
+/** Raw token pair as stored by the Cursor CLI or IDE, before any validation. */
+interface StoredTokens {
+  accessToken?: string;
+  refreshToken?: string;
+}
+
+/** Windows account that owns this WSL session — never scan sibling profiles. */
+export function windowsUsernameFromEnv(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const profile = env.USERPROFILE?.trim();
+  if (profile) {
+    const normalized = profile.replace(/\\/g, "/");
+    const match = /\/Users\/([^/]+)/i.exec(normalized);
+    const fromProfile = match?.[1]?.trim();
+    if (
+      fromProfile &&
+      fromProfile !== "Public" &&
+      fromProfile !== "Default" &&
+      !fromProfile.startsWith(".")
+    ) {
+      return fromProfile;
+    }
+  }
+  const username = env.USERNAME?.trim();
+  if (username && username !== "Public" && username !== "Default" && !username.startsWith(".")) {
+    return username;
+  }
+  return undefined;
+}
+
+function isUsable(token: string | undefined): token is string {
+  if (!token) return false;
+  try {
+    return Date.now() < getTokenExpiry(token);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Exchange a refresh token, honouring the failure back-off.
+ *
+ * Returns undefined without touching the network when this exact token failed
+ * recently — a stale Cursor CLI entry otherwise costs seconds on every launch.
+ */
+async function tryRefresh(refreshToken: string | undefined): Promise<string | undefined> {
+  if (!refreshToken || isRefreshKnownBad(refreshToken)) return undefined;
+  try {
+    const refreshed = await refreshCursorToken(refreshToken);
+    markRefreshSucceeded(refreshToken);
+    return refreshed.access;
+  } catch {
+    markRefreshFailed(refreshToken);
+    return undefined;
+  }
+}
+
+/** Reads the raw Cursor CLI token pair from the macOS Keychain. */
+async function readKeychainTokens(): Promise<StoredTokens> {
+  if (platform() !== "darwin") return {};
+
+  // Run both Keychain lookups concurrently — they are independent reads.
+  const [accessResult, refreshResult] = await Promise.allSettled([
+    execFileAsync(
+      "security",
+      ["find-generic-password", "-s", "cursor-access-token", "-a", "cursor-user", "-w"],
+      { encoding: "utf8", timeout: 2000 },
+    ),
+    execFileAsync(
+      "security",
+      ["find-generic-password", "-s", "cursor-refresh-token", "-a", "cursor-user", "-w"],
+      { encoding: "utf8", timeout: 2000 },
+    ),
+  ]);
+
+  const tokens: StoredTokens = {};
+  if (accessResult.status === "fulfilled") {
+    const raw = accessResult.value.stdout.trim();
+    if (raw) tokens.accessToken = raw;
+  }
+  if (refreshResult.status === "fulfilled") {
+    const raw = refreshResult.value.stdout.trim();
+    if (raw) tokens.refreshToken = raw;
+  }
+  return tokens;
+}
+
+/**
+ * Reads token from macOS Keychain (security CLI).
+ * Uses async execFile so Keychain reads don't block the event loop.
+ */
+export async function getCursorKeychainToken(): Promise<CursorTokenResult | undefined> {
+  const { accessToken, refreshToken } = await readKeychainTokens();
+  if (isUsable(accessToken)) return { accessToken, source: CredentialSource.CliKeychain };
+  const refreshed = await tryRefresh(refreshToken);
+  return refreshed
+    ? { accessToken: refreshed, source: CredentialSource.CliKeychainRefresh }
+    : undefined;
+}
+
+// Cache the DatabaseSync constructor at module level so repeated vscdb lookups
+// don't pay the dynamic-import cost each time.
+let _databaseSyncCache:
+  | (new (
+      path: string,
+      options?: { readOnly?: boolean },
+    ) => { prepare(sql: string): { get(): unknown }; close(): void })
+  | null
+  | undefined = undefined;
+
+async function getDatabaseSync() {
+  if (_databaseSyncCache !== undefined) return _databaseSyncCache ?? undefined;
+  try {
+    const mod = await import("node:sqlite");
+    _databaseSyncCache = mod.DatabaseSync as unknown as typeof _databaseSyncCache;
+    return _databaseSyncCache ?? undefined;
+  } catch {
+    _databaseSyncCache = null;
+    return undefined;
+  }
+}
+
+/** Reads the raw Cursor IDE token pair from state.vscdb. */
+async function readVscdbTokens(): Promise<StoredTokens> {
+  const DatabaseSyncClass = await getDatabaseSync();
+  if (!DatabaseSyncClass) return {};
+
+  const dbPaths: string[] = [];
+  const home = homedir();
+
+  if (platform() === "darwin") {
+    dbPaths.push(join(home, "Library/Application Support/Cursor/User/globalStorage/state.vscdb"));
+  } else if (platform() === "win32") {
+    if (process.env.APPDATA) {
+      dbPaths.push(join(process.env.APPDATA, "Cursor/User/globalStorage/state.vscdb"));
+    }
+  } else {
+    // Linux / WSL
+    dbPaths.push(join(home, ".config/Cursor/User/globalStorage/state.vscdb"));
+    const wslHost = Boolean(
+      process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP || existsSync("/mnt/c/Users"),
+    );
+    if (wslHost) {
+      const windowsUser = windowsUsernameFromEnv(process.env);
+      if (windowsUser) {
+        dbPaths.push(
+          join(
+            "/mnt/c/Users",
+            windowsUser,
+            "AppData/Roaming/Cursor/User/globalStorage/state.vscdb",
+          ),
+        );
+      }
+    }
+  }
+
+  // Prefer the first profile that yields a usable access token; otherwise keep
+  // the first refresh token seen so a single expired profile still has a path
+  // back to a live session.
+  const fallback: StoredTokens = {};
+  for (const dbPath of dbPaths) {
+    try {
+      const db = new DatabaseSyncClass(dbPath, { readOnly: true });
+      let accessRow: { value?: string } | undefined;
+      let refreshRow: { value?: string } | undefined;
+      try {
+        accessRow = db
+          .prepare("SELECT value FROM ItemTable WHERE key = 'cursorAuth/accessToken'")
+          .get() as { value?: string } | undefined;
+        refreshRow = db
+          .prepare("SELECT value FROM ItemTable WHERE key = 'cursorAuth/refreshToken'")
+          .get() as { value?: string } | undefined;
+      } finally {
+        db.close();
+      }
+
+      const accessToken = typeof accessRow?.value === "string" ? accessRow.value.trim() : undefined;
+      const refreshToken =
+        typeof refreshRow?.value === "string" ? refreshRow.value.trim() : undefined;
+
+      if (isUsable(accessToken)) return { accessToken, refreshToken };
+      if (!fallback.refreshToken && refreshToken) fallback.refreshToken = refreshToken;
+      if (!fallback.accessToken && accessToken) fallback.accessToken = accessToken;
+    } catch {
+      // Database missing or unreadable
+    }
+  }
+  return fallback;
+}
+
+/**
+ * Reads token from Cursor IDE state.vscdb.
+ */
+export async function getCursorVscdbToken(): Promise<CursorTokenResult | undefined> {
+  const { accessToken, refreshToken } = await readVscdbTokens();
+  if (isUsable(accessToken)) return { accessToken, source: CredentialSource.IdeVscdb };
+  const refreshed = await tryRefresh(refreshToken);
+  return refreshed
+    ? { accessToken: refreshed, source: CredentialSource.IdeVscdbRefresh }
+    : undefined;
+}
+
+/**
+ * Full credential resolution cascade:
+ * 1. CURSOR_ACCESS_TOKEN env var
+ * 2. macOS Keychain (Cursor CLI) — gated by system-credential consent
+ * 3. Cursor IDE state.vscdb — gated by system-credential consent
+ *
+ * Both system sources are read concurrently and every *local* token is checked
+ * before any network exchange is attempted. That ordering matters: a stale CLI
+ * keychain entry used to trigger a doomed ~2.6s refresh on the startup path
+ * even though the IDE database held a valid token two milliseconds away.
+ *
+ * Opt out of Keychain/vscdb scraping with PI_CURSOR_SYSTEM_CREDENTIALS=0.
+ */
+export async function resolveSystemCursorAccessToken(options?: {
+  forceRefresh?: boolean;
+}): Promise<CursorTokenResult | undefined> {
+  const envToken = getCursorAccessTokenFromEnv();
+  if (envToken) {
+    // Env tokens cannot be refreshed here; still prefer them when present.
+    if (!options?.forceRefresh || isUsable(envToken)) {
+      return { accessToken: envToken, source: CredentialSource.Env };
+    }
+  }
+
+  if (!systemCredentialsAllowed()) {
+    return undefined;
+  }
+
+  const [keychain, vscdb] = await Promise.all([readKeychainTokens(), readVscdbTokens()]);
+
+  const cached: CursorTokenResult | undefined = isUsable(keychain.accessToken)
+    ? { accessToken: keychain.accessToken, source: CredentialSource.CliKeychain }
+    : isUsable(vscdb.accessToken)
+      ? { accessToken: vscdb.accessToken, source: CredentialSource.IdeVscdb }
+      : undefined;
+
+  // Fast path: a locally stored token is still valid, so no network at all.
+  if (cached && !options?.forceRefresh) return cached;
+
+  const keychainRefreshed = await tryRefresh(keychain.refreshToken);
+  if (keychainRefreshed) {
+    return { accessToken: keychainRefreshed, source: CredentialSource.CliKeychainRefresh };
+  }
+
+  // Skip a second identical exchange when the CLI mirrored its token into the IDE.
+  if (vscdb.refreshToken && vscdb.refreshToken !== keychain.refreshToken) {
+    const vscdbRefreshed = await tryRefresh(vscdb.refreshToken);
+    if (vscdbRefreshed)
+      return { accessToken: vscdbRefreshed, source: CredentialSource.IdeVscdbRefresh };
+  }
+
+  // forceRefresh could not improve on what we already had — keep it rather than
+  // reporting "not logged in" for a token that is still valid.
+  return cached;
+}

package/src/auth/consent.ts

@@ -0,0 +1,25 @@
+/**
+ * Consent / opt-out for reusing Cursor CLI / IDE system credentials.
+ *
+ * Default: allow system credential reuse (Keychain + state.vscdb + WSL host).
+ * Opt out with PI_CURSOR_SYSTEM_CREDENTIALS=0|false|off|deny.
+ * Force-enable with PI_CURSOR_SYSTEM_CREDENTIALS=1|true|on|allow.
+ */
+import { SystemCredentialPolicy } from "../types/enums.js";
+import { isFalsyEnv, isTruthyEnv } from "../utils/util.js";
+
+export { SystemCredentialPolicy, type SystemCredentialPolicyType } from "../types/enums.js";
+
+export function resolveSystemCredentialPolicy(
+  envValue: string | undefined = process.env.PI_CURSOR_SYSTEM_CREDENTIALS,
+): SystemCredentialPolicy {
+  if (!envValue?.trim()) return SystemCredentialPolicy.Allow;
+  if (isFalsyEnv(envValue)) return SystemCredentialPolicy.Deny;
+  if (isTruthyEnv(envValue)) return SystemCredentialPolicy.Allow;
+  // Unknown values fail closed so misconfiguration never silently scrapes credentials.
+  return SystemCredentialPolicy.Deny;
+}
+
+export function systemCredentialsAllowed(envValue?: string): boolean {
+  return resolveSystemCredentialPolicy(envValue) === SystemCredentialPolicy.Allow;
+}

package/src/auth/index.ts

@@ -0,0 +1,23 @@
+export {
+  generateCursorAuthParams,
+  pollCursorAuth,
+  refreshCursorToken,
+  getTokenExpiry,
+  getCursorAccessTokenFromEnv,
+  createCursorAuthClient,
+  type CursorAuthParams,
+  type CursorCredentials,
+} from "./oauth.js";
+export {
+  resolveSystemCursorAccessToken,
+  getCursorKeychainToken,
+  getCursorVscdbToken,
+  windowsUsernameFromEnv,
+  type CredentialSource,
+  type CursorTokenResult,
+} from "./cli-credentials.js";
+export {
+  systemCredentialsAllowed,
+  resolveSystemCredentialPolicy,
+  type SystemCredentialPolicy,
+} from "./consent.js";

package/src/auth/oauth.ts

@@ -0,0 +1,282 @@
+/**
+ * Cursor OAuth authentication via PKCE.
+ *
+ * Flow:
+ * 1. Generate PKCE verifier + challenge
+ * 2. Open browser to cursor.com/loginDeepControl
+ * 3. Poll api2.cursor.sh/auth/poll until tokens arrive
+ * 4. Refresh via api2.cursor.sh/auth/exchange_user_api_key
+ *
+ * Based on https://github.com/ephraimduncan/opencode-cursor by Ephraim Duncan.
+ */
+
+import { redactSecrets } from "../utils/security.js";
+
+const CURSOR_LOGIN_URL = "https://cursor.com/loginDeepControl";
+const CURSOR_POLL_URL = "https://api2.cursor.sh/auth/poll";
+const CURSOR_REFRESH_URL = "https://api2.cursor.sh/auth/exchange_user_api_key";
+const POLL_MAX_ATTEMPTS = 150;
+const POLL_BASE_DELAY = 1000;
+const POLL_MAX_DELAY = 10_000;
+const POLL_BACKOFF_MULTIPLIER = 1.2;
+const AUTH_REQUEST_TIMEOUT_MS = 15_000;
+
+function authRequestSignal(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
+function parseTokenResponse(
+  value: unknown,
+  endpoint: string,
+): {
+  accessToken: string;
+  refreshToken?: string;
+} {
+  if (!value || typeof value !== "object") {
+    throw new Error(`${endpoint} returned an invalid token response`);
+  }
+  const record = value as Record<string, unknown>;
+  if (typeof record.accessToken !== "string" || !record.accessToken.trim()) {
+    throw new Error(`${endpoint} returned no access token`);
+  }
+  if (record.refreshToken !== undefined && typeof record.refreshToken !== "string") {
+    throw new Error(`${endpoint} returned an invalid refresh token`);
+  }
+  return {
+    accessToken: record.accessToken,
+    ...(typeof record.refreshToken === "string" ? { refreshToken: record.refreshToken } : {}),
+  };
+}
+
+// ── PKCE ──
+
+async function generatePKCE(): Promise<{ verifier: string; challenge: string }> {
+  const verifierBytes = new Uint8Array(96);
+  crypto.getRandomValues(verifierBytes);
+  const verifier = Buffer.from(verifierBytes).toString("base64url");
+
+  const data = new TextEncoder().encode(verifier);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const challenge = Buffer.from(hashBuffer).toString("base64url");
+
+  return { verifier, challenge };
+}
+
+// ── Login params ──
+
+export interface CursorAuthParams {
+  verifier: string;
+  challenge: string;
+  uuid: string;
+  loginUrl: string;
+}
+
+export interface CursorAuthClientDependencies {
+  fetch?: typeof fetch;
+  generatePkce?: () => Promise<{ verifier: string; challenge: string; uuid?: string }>;
+  randomUUID?: () => string;
+  sleep?: (ms: number) => Promise<void>;
+  requestTimeoutMs?: number;
+}
+
+export interface CursorAuthLoginCallbacks {
+  onAuth(payload: { url: string }): void | Promise<void>;
+}
+
+export function createCursorAuthClient(deps: CursorAuthClientDependencies = {}) {
+  const fetchImpl = deps.fetch ?? fetch;
+  const requestTimeoutMs = deps.requestTimeoutMs ?? AUTH_REQUEST_TIMEOUT_MS;
+  const sleepImpl =
+    deps.sleep ??
+    ((ms: number) =>
+      new Promise<void>((resolve) => {
+        setTimeout(resolve, ms);
+      }));
+  const generatePkceImpl: () => Promise<{ verifier: string; challenge: string; uuid?: string }> =
+    deps.generatePkce ?? generatePKCE;
+  const randomUUIDImpl = deps.randomUUID ?? (() => crypto.randomUUID());
+
+  async function sleepForPoll(ms: number, signal?: AbortSignal): Promise<void> {
+    if (!signal) {
+      await sleepImpl(ms);
+      return;
+    }
+    if (signal.aborted) throw new Error("Cursor authentication polling aborted");
+    let rejectAbort: ((reason: Error) => void) | undefined;
+    const aborted = new Promise<never>((_resolve, reject) => {
+      rejectAbort = reject;
+    });
+    const onAbort = () => rejectAbort?.(new Error("Cursor authentication polling aborted"));
+    signal.addEventListener("abort", onAbort, { once: true });
+    try {
+      await Promise.race([sleepImpl(ms), aborted]);
+    } finally {
+      signal.removeEventListener("abort", onAbort);
+    }
+  }
+
+  async function generateParams(): Promise<CursorAuthParams> {
+    const { verifier, challenge, uuid: injectedUuid } = await generatePkceImpl();
+    const uuid = injectedUuid ?? randomUUIDImpl();
+
+    const params = new URLSearchParams({
+      challenge,
+      uuid,
+      mode: "login",
+      redirectTarget: "cli",
+    });
+
+    const loginUrl = `${CURSOR_LOGIN_URL}?${params.toString()}`;
+    return { verifier, challenge, uuid, loginUrl };
+  }
+
+  async function poll(
+    uuid: string,
+    verifier: string,
+    options?: { signal?: AbortSignal },
+  ): Promise<{ accessToken: string; refreshToken: string }> {
+    let delay = POLL_BASE_DELAY;
+    let consecutiveErrors = 0;
+
+    for (let attempt = 0; attempt < POLL_MAX_ATTEMPTS; attempt++) {
+      await sleepForPoll(delay, options?.signal);
+
+      try {
+        const response = await fetchImpl(`${CURSOR_POLL_URL}?uuid=${uuid}&verifier=${verifier}`, {
+          signal: authRequestSignal(options?.signal, requestTimeoutMs),
+        });
+
+        if (response.status === 404) {
+          consecutiveErrors = 0;
+          delay = Math.min(delay * POLL_BACKOFF_MULTIPLIER, POLL_MAX_DELAY);
+          continue;
+        }
+
+        if (response.ok) {
+          const data = parseTokenResponse(await response.json(), "Cursor authentication polling");
+          if (!data.refreshToken) {
+            throw new Error("Cursor authentication polling returned no refresh token");
+          }
+          return {
+            accessToken: data.accessToken,
+            refreshToken: data.refreshToken,
+          };
+        }
+
+        throw new Error(`Poll failed: ${response.status}`);
+      } catch (error) {
+        if (options?.signal?.aborted) {
+          throw new Error("Cursor authentication polling aborted", { cause: error });
+        }
+        consecutiveErrors++;
+        if (consecutiveErrors >= 3) {
+          throw new Error("Too many consecutive errors during Cursor auth polling", {
+            cause: error,
+          });
+        }
+      }
+    }
+
+    throw new Error("Cursor authentication polling timeout");
+  }
+
+  async function refreshToken(
+    refreshToken: string,
+    options?: { signal?: AbortSignal },
+  ): Promise<CursorCredentials> {
+    const response = await fetchImpl(CURSOR_REFRESH_URL, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${refreshToken}`,
+        "Content-Type": "application/json",
+      },
+      body: "{}",
+      signal: authRequestSignal(options?.signal, requestTimeoutMs),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Cursor token refresh failed: ${redactSecrets(error)}`);
+    }
+
+    const data = parseTokenResponse(await response.json(), "Cursor token refresh");
+
+    return {
+      access: data.accessToken,
+      refresh: data.refreshToken || refreshToken,
+      expires: getTokenExpiry(data.accessToken),
+    };
+  }
+
+  async function login(
+    callbacks: CursorAuthLoginCallbacks,
+    options?: { signal?: AbortSignal },
+  ): Promise<CursorCredentials> {
+    const { verifier, uuid, loginUrl } = await generateParams();
+    await callbacks.onAuth({ url: loginUrl });
+    const { accessToken, refreshToken } = await poll(uuid, verifier, options);
+    return {
+      access: accessToken,
+      refresh: refreshToken,
+      expires: getTokenExpiry(accessToken),
+    };
+  }
+
+  return {
+    generateParams,
+    login,
+    poll,
+    refreshToken,
+  };
+}
+
+export async function generateCursorAuthParams(): Promise<CursorAuthParams> {
+  return createCursorAuthClient().generateParams();
+}
+
+// ── Poll for auth completion ──
+
+export async function pollCursorAuth(
+  uuid: string,
+  verifier: string,
+  options?: { signal?: AbortSignal },
+): Promise<{ accessToken: string; refreshToken: string }> {
+  return createCursorAuthClient().poll(uuid, verifier, options);
+}
+
+// ── Token refresh ──
+
+export interface CursorCredentials {
+  access: string;
+  refresh: string;
+  expires: number;
+}
+
+export async function refreshCursorToken(
+  refreshToken: string,
+  options?: { signal?: AbortSignal },
+): Promise<CursorCredentials> {
+  return createCursorAuthClient().refreshToken(refreshToken, options);
+}
+
+// ── JWT expiry extraction ──
+
+export function getCursorAccessTokenFromEnv(): string | undefined {
+  const token = process.env.CURSOR_ACCESS_TOKEN?.trim();
+  return token || undefined;
+}
+
+export function getTokenExpiry(token: string): number {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3 || !parts[1]) {
+      return Date.now() + 3600 * 1000;
+    }
+    const decoded = JSON.parse(atob(parts[1].replace(/-/g, "+").replace(/_/g, "/")));
+    if (decoded && typeof decoded === "object" && typeof decoded.exp === "number") {
+      return decoded.exp * 1000 - 5 * 60 * 1000;
+    }
+  } catch {}
+  return Date.now() + 3600 * 1000;
+}