@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/playground-proxy.ts

@@ -1,564 +0,0 @@
-/**
- * Loopback reverse proxy that injects engine / bearer auth so a normal
- * browser can use the hosted (or remote) playground SPA.
- *
- * Hosted engines sit behind short-lived `engineAccess` headers that a
- * browser cannot set; alias tokens are header-only too. This proxy binds
- * `127.0.0.1` only and forwards every request upstream with those headers.
- *
- * Access is gated by a per-proxy `accessToken` (query on first hit → HttpOnly
- * cookie): other local processes cannot upgrade to injected credentials just
- * by knowing the port. Mutating requests also require Origin/Referer to match
- * this proxy's own origin so another `http://127.0.0.1:<port>` page cannot
- * CSRF the cookie (cookies are host-scoped across ports). Absolute-form
- * request-targets are rejected so injected headers never leave the configured
- * upstream.
- *
- * When `refreshUpstream` is provided (e.g. short-lived upstream tokens),
- * credentials are re-minted shortly before `expiresAt` and once on upstream
- * 401 so a long playground session does not require restarting the CLI.
- */
-
-import { randomBytes } from "node:crypto";
-import {
-  createServer,
-  request as httpRequest,
-  type IncomingMessage,
-  type RequestOptions,
-  type Server,
-  type ServerResponse,
-} from "node:http";
-import { request as httpsRequest } from "node:https";
-import type { AddressInfo } from "node:net";
-import { URL } from "node:url";
-import { openBrowser } from "./open-browser.js";
-
-export { openBrowser };
-
-const HOP_BY_HOP = new Set([
-  "connection",
-  "keep-alive",
-  "proxy-authenticate",
-  "proxy-authorization",
-  "te",
-  "trailers",
-  "transfer-encoding",
-  "upgrade",
-  "host",
-  "content-length",
-]);
-
-/** Origin / Fetch-Metadata: the proxy already checked origin; upstream Host is rewritten. */
-const BROWSER_PROVENANCE = new Set([
-  "origin",
-  "referer",
-  "sec-fetch-site",
-  "sec-fetch-mode",
-  "sec-fetch-dest",
-  "sec-fetch-user",
-]);
-
-/** Re-mint when the port token is within this window of expiry. */
-const ACCESS_EXPIRY_LEEWAY_MS = 5 * 60 * 1000;
-
-const PROXY_COOKIE = "agentkit_playground_proxy";
-const PROXY_TOKEN_QUERY = "proxyToken";
-
-export interface PlaygroundProxyHandle {
-  /** e.g. `http://127.0.0.1:54321` (no trailing slash). */
-  localUrl: string;
-  port: number;
-  /** Random token required via query (first hit) or cookie thereafter. */
-  accessToken: string;
-  /**
-   * Build a browser entry URL for `/playground` that includes the access
-   * token (and optional sessionId).
-   */
-  playgroundUrl: (sessionId?: string) => string;
-  close: () => Promise<void>;
-}
-
-export interface PlaygroundUpstreamAccess {
-  upstreamUrl: string;
-  headers?: Record<string, string>;
-  expiresAt?: string;
-}
-
-export interface StartPlaygroundProxyArgs {
-  /** Upstream agent base URL (engineAccess or --url). */
-  upstreamUrl: string;
-  /** Headers injected on every upstream request (engine tokens, wake, …). */
-  headers?: Record<string, string>;
-  /** Optional bearer for local servers that require it. */
-  bearerToken?: string;
-  /** Initial engineAccess expiry (ISO); enables proactive refresh. */
-  expiresAt?: string;
-  /**
-   * Re-mint upstream URL + headers. Single-flighted across concurrent browser
-   * requests; called near expiry and once on 401.
-   */
-  refreshUpstream?: () => Promise<PlaygroundUpstreamAccess>;
-  /** Bind port; `0` = ephemeral. */
-  port?: number;
-  /** Injected for tests. */
-  createServerImpl?: typeof createServer;
-  /** Injected clock for expiry tests. */
-  now?: () => number;
-  /** Injected token for tests (defaults to a random 32-byte value). */
-  accessToken?: string;
-}
-
-interface UpstreamState {
-  upstream: URL;
-  injectHeaders: Record<string, string>;
-  expiresAtMs: number | undefined;
-}
-
-/**
- * Start a loopback proxy. Resolves once listening.
- */
-export async function startPlaygroundProxy(
-  args: StartPlaygroundProxyArgs,
-): Promise<PlaygroundProxyHandle> {
-  const upstream = parseUpstreamUrl(args.upstreamUrl);
-  const state: UpstreamState = {
-    upstream,
-    injectHeaders: buildInjectHeaders(args.headers, args.bearerToken),
-    expiresAtMs: parseExpiresAtMs(args.expiresAt),
-  };
-  const accessToken = args.accessToken ?? randomBytes(32).toString("base64url");
-  const now = args.now ?? Date.now;
-  let refreshInFlight: Promise<void> | undefined;
-  /** Set after listen; used for Origin CSRF checks. */
-  let proxyOrigin = "";
-
-  const ensureFreshAccess = async (force: boolean): Promise<void> => {
-    if (args.refreshUpstream === undefined) {
-      return;
-    }
-    const expired =
-      state.expiresAtMs !== undefined && now() >= state.expiresAtMs - ACCESS_EXPIRY_LEEWAY_MS;
-    if (!force && !expired) {
-      return;
-    }
-    if (refreshInFlight !== undefined) {
-      await refreshInFlight;
-      return;
-    }
-    refreshInFlight = (async () => {
-      const next = await args.refreshUpstream!();
-      state.upstream = parseUpstreamUrl(next.upstreamUrl);
-      state.injectHeaders = buildInjectHeaders(next.headers, args.bearerToken);
-      state.expiresAtMs = parseExpiresAtMs(next.expiresAt);
-    })().finally(() => {
-      refreshInFlight = undefined;
-    });
-    await refreshInFlight;
-  };
-
-  const create = args.createServerImpl ?? createServer;
-  const server: Server = create((req, res) => {
-    void handleProxyRequest({
-      req,
-      res,
-      getState: () => state,
-      ensureFreshAccess,
-      canRefresh: args.refreshUpstream !== undefined,
-      accessToken,
-      proxyOrigin: () => proxyOrigin,
-    }).catch((error: unknown) => {
-      if (res.headersSent) {
-        if (!res.writableEnded) {
-          res.end();
-        }
-        return;
-      }
-      const message = error instanceof Error ? error.message : String(error);
-      res.writeHead(502, { "content-type": "text/plain; charset=utf-8" });
-      res.end(`Playground proxy error: ${message}`);
-    });
-  });
-
-  await new Promise<void>((resolve, reject) => {
-    server.once("error", reject);
-    server.listen(args.port ?? 0, "127.0.0.1", () => {
-      server.off("error", reject);
-      resolve();
-    });
-  });
-
-  const address = server.address() as AddressInfo;
-  const localUrl = `http://127.0.0.1:${address.port}`;
-  proxyOrigin = localUrl;
-
-  return {
-    localUrl,
-    port: address.port,
-    accessToken,
-    playgroundUrl: (sessionId?: string) => {
-      const url = new URL(`${localUrl}/playground`);
-      url.searchParams.set(PROXY_TOKEN_QUERY, accessToken);
-      if (sessionId !== undefined && sessionId.trim() !== "") {
-        url.searchParams.set("sessionId", sessionId.trim());
-      }
-      return url.toString();
-    },
-    close: () =>
-      new Promise<void>((resolve, reject) => {
-        // Drop keep-alive / streamed playground connections so Ctrl-C
-        // does not hang waiting for active sockets.
-        server.closeAllConnections();
-        server.close(error => {
-          if (error) {
-            reject(error);
-            return;
-          }
-          resolve();
-        });
-      }),
-  };
-}
-
-function parseUpstreamUrl(raw: string): URL {
-  const upstream = new URL(raw.replace(/\/$/, ""));
-  if (upstream.protocol !== "http:" && upstream.protocol !== "https:") {
-    throw new Error(`Unsupported upstream protocol: ${upstream.protocol}`);
-  }
-  return upstream;
-}
-
-function parseExpiresAtMs(expiresAt: string | undefined): number | undefined {
-  if (expiresAt === undefined || expiresAt.trim() === "") {
-    return undefined;
-  }
-  const ms = Date.parse(expiresAt);
-  return Number.isFinite(ms) ? ms : undefined;
-}
-
-function buildInjectHeaders(
-  headers: Record<string, string> | undefined,
-  bearerToken: string | undefined,
-): Record<string, string> {
-  const out: Record<string, string> = { ...(headers ?? {}) };
-  if (bearerToken !== undefined && bearerToken.trim() !== "") {
-    out.authorization = `Bearer ${bearerToken.trim()}`;
-  }
-  return out;
-}
-
-async function readRequestBody(req: IncomingMessage): Promise<Buffer> {
-  const chunks: Buffer[] = [];
-  for await (const chunk of req) {
-    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
-  }
-  return Buffer.concat(chunks);
-}
-
-async function handleProxyRequest(args: {
-  req: IncomingMessage;
-  res: ServerResponse;
-  getState: () => UpstreamState;
-  ensureFreshAccess: (force: boolean) => Promise<void>;
-  canRefresh: boolean;
-  accessToken: string;
-  proxyOrigin: () => string;
-}): Promise<void> {
-  const { req, res, getState, ensureFreshAccess, canRefresh, accessToken, proxyOrigin } = args;
-  const pathWithQuery = req.url ?? "/";
-
-  const pathParse = parseProxyPath(pathWithQuery);
-  if (!pathParse.ok) {
-    res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
-    res.end("Absolute-form request targets are not allowed");
-    return;
-  }
-
-  const auth = authorizeLocalRequest({
-    pathWithQuery: pathParse.path,
-    cookieHeader: req.headers.cookie,
-    accessToken,
-  });
-  if (auth.kind === "deny") {
-    res.writeHead(401, { "content-type": "text/plain; charset=utf-8" });
-    res.end("Playground proxy requires the session access token");
-    return;
-  }
-  if (auth.kind === "bootstrap") {
-    res.writeHead(302, {
-      location: auth.redirectPath,
-      "set-cookie": auth.setCookie,
-      "cache-control": "no-store",
-    });
-    res.end();
-    return;
-  }
-
-  const method = req.method ?? "GET";
-  if (
-    !isTrustedBrowserOrigin({
-      method,
-      origin: headerString(req.headers.origin),
-      referer: headerString(req.headers.referer),
-      secFetchSite: headerString(req.headers["sec-fetch-site"]),
-      proxyOrigin: proxyOrigin(),
-    })
-  ) {
-    res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
-    res.end("Playground proxy rejected cross-origin request");
-    return;
-  }
-
-  let body: Buffer;
-  try {
-    body = await readRequestBody(req);
-  } catch {
-    if (!res.headersSent) {
-      res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
-      res.end("Playground proxy failed to read request body");
-    }
-    return;
-  }
-
-  const forward = (state: UpstreamState, deferWriteOnUnauthorized: boolean): Promise<number> =>
-    forwardOnce({
-      method,
-      pathWithQuery: pathParse.path,
-      inboundHeaders: req.headers,
-      body,
-      state,
-      res,
-      deferWriteOnUnauthorized,
-    });
-
-  try {
-    await ensureFreshAccess(false);
-    let status = await forward(getState(), canRefresh);
-    if (status === 401 && canRefresh) {
-      await ensureFreshAccess(true);
-      // Retry once; always write this response (even if still 401).
-      status = await forward(getState(), false);
-    }
-    void status;
-  } catch (error) {
-    if (!res.headersSent) {
-      const message = error instanceof Error ? error.message : String(error);
-      res.writeHead(502, { "content-type": "text/plain; charset=utf-8" });
-      res.end(`Playground proxy upstream error: ${message}`);
-    } else if (!res.writableEnded) {
-      res.end();
-    }
-  }
-}
-
-/**
- * Cookies are host-scoped across ports on 127.0.0.1, so SameSite=Strict alone
- * does not stop CSRF from another loopback origin. Require the browser's
- * Origin (or Referer / Sec-Fetch-Site: same-origin) to match this proxy for
- * mutating methods. Safe methods stay cookie-gated only (no side effects).
- */
-function isTrustedBrowserOrigin(args: {
-  method: string;
-  origin: string | undefined;
-  referer: string | undefined;
-  secFetchSite: string | undefined;
-  proxyOrigin: string;
-}): boolean {
-  const method = args.method.toUpperCase();
-  if (method === "GET" || method === "HEAD" || method === "OPTIONS") {
-    return true;
-  }
-  if (args.proxyOrigin === "") {
-    return false;
-  }
-  if (args.origin === args.proxyOrigin) {
-    return true;
-  }
-  if (
-    args.referer !== undefined &&
-    (args.referer === args.proxyOrigin || args.referer.startsWith(`${args.proxyOrigin}/`))
-  ) {
-    return true;
-  }
-  // Some same-origin fetches omit Origin; modern browsers still send this.
-  if (args.secFetchSite === "same-origin") {
-    return true;
-  }
-  return false;
-}
-
-function headerString(value: string | string[] | undefined): string | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-  return Array.isArray(value) ? value[0] : value;
-}
-
-function authorizeLocalRequest(args: {
-  pathWithQuery: string;
-  cookieHeader: string | string[] | undefined;
-  accessToken: string;
-}):
-  | { kind: "allow" }
-  | { kind: "deny" }
-  | { kind: "bootstrap"; redirectPath: string; setCookie: string } {
-  const cookieToken = readCookie(args.cookieHeader, PROXY_COOKIE);
-  if (cookieToken === args.accessToken) {
-    return { kind: "allow" };
-  }
-
-  const url = new URL(args.pathWithQuery, "http://127.0.0.1");
-  const queryToken = url.searchParams.get(PROXY_TOKEN_QUERY);
-  if (queryToken === args.accessToken) {
-    url.searchParams.delete(PROXY_TOKEN_QUERY);
-    const redirectPath = `${url.pathname}${url.search}`;
-    return {
-      kind: "bootstrap",
-      redirectPath,
-      setCookie: `${PROXY_COOKIE}=${args.accessToken}; Path=/; HttpOnly; SameSite=Strict`,
-    };
-  }
-  return { kind: "deny" };
-}
-
-function readCookie(header: string | string[] | undefined, name: string): string | undefined {
-  if (header === undefined) {
-    return undefined;
-  }
-  const raw = Array.isArray(header) ? header.join("; ") : header;
-  for (const part of raw.split(";")) {
-    const trimmed = part.trim();
-    const eq = trimmed.indexOf("=");
-    if (eq <= 0) continue;
-    if (trimmed.slice(0, eq) === name) {
-      return trimmed.slice(eq + 1);
-    }
-  }
-  return undefined;
-}
-
-async function forwardOnce(args: {
-  method: string;
-  pathWithQuery: string;
-  inboundHeaders: IncomingMessage["headers"];
-  body: Buffer;
-  state: UpstreamState;
-  res: ServerResponse;
-  deferWriteOnUnauthorized: boolean;
-}): Promise<number> {
-  const { method, pathWithQuery, inboundHeaders, body, state, res } = args;
-  const target = buildTargetUrl(pathWithQuery, state.upstream);
-
-  const outboundHeaders: Record<string, string | string[] | undefined> = {};
-  for (const [name, value] of Object.entries(inboundHeaders)) {
-    if (value === undefined) continue;
-    const lower = name.toLowerCase();
-    if (HOP_BY_HOP.has(lower)) continue;
-    if (lower === "authorization") continue;
-    // Do not forward the loopback session cookie upstream.
-    if (lower === "cookie") continue;
-    if (BROWSER_PROVENANCE.has(lower)) continue;
-    outboundHeaders[name] = value;
-  }
-  for (const [name, value] of Object.entries(state.injectHeaders)) {
-    outboundHeaders[name] = value;
-  }
-  outboundHeaders.host = target.host;
-  outboundHeaders["content-length"] = String(body.byteLength);
-
-  const isHttps = target.protocol === "https:";
-  const requestFn = isHttps ? httpsRequest : httpRequest;
-  const options: RequestOptions = {
-    protocol: target.protocol,
-    hostname: target.hostname,
-    port: target.port === "" ? (isHttps ? 443 : 80) : Number(target.port),
-    method,
-    path: `${target.pathname}${target.search}`,
-    headers: outboundHeaders,
-  };
-
-  return await new Promise<number>((resolve, reject) => {
-    const upstreamReq = requestFn(options, upstreamRes => {
-      const status = upstreamRes.statusCode ?? 502;
-      if (status === 401 && args.deferWriteOnUnauthorized) {
-        // Drain so the socket can be reused; caller will refresh + retry.
-        upstreamRes.resume();
-        upstreamRes.on("end", () => resolve(status));
-        upstreamRes.on("error", () => resolve(status));
-        return;
-      }
-
-      const responseHeaders: Record<string, string | string[] | undefined> = {
-        ...upstreamRes.headers,
-      };
-      for (const hop of HOP_BY_HOP) {
-        delete responseHeaders[hop];
-      }
-      res.writeHead(status, responseHeaders);
-      upstreamRes.pipe(res);
-      upstreamRes.on("end", () => resolve(status));
-      upstreamRes.on("error", () => {
-        if (!res.writableEnded) {
-          res.end();
-        }
-        resolve(status);
-      });
-    });
-
-    upstreamReq.on("error", error => {
-      reject(error);
-    });
-
-    res.on("close", () => {
-      if (!res.writableEnded) {
-        upstreamReq.destroy();
-      }
-    });
-
-    upstreamReq.end(body);
-  });
-}
-
-/**
- * Build an upstream URL that always keeps the configured host/port.
- * Absolute-form or protocol-relative request-targets must not retarget
- * outbound requests (injected engine/bearer credentials would follow).
- */
-function buildTargetUrl(pathWithQuery: string, upstream: URL): URL {
-  const pathParse = parseProxyPath(pathWithQuery);
-  const relative = pathParse.ok ? pathParse.path : "/";
-  const target = new URL(relative, upstream);
-  // Force authority back onto the configured upstream even if `new URL`
-  // accepted an absolute/protocol-relative request-target.
-  target.protocol = upstream.protocol;
-  target.hostname = upstream.hostname;
-  target.port = upstream.port;
-  target.username = "";
-  target.password = "";
-
-  // Preserve upstream pathname prefix when the base URL has one
-  // (unusual for engineAccess; kept for `--url` mounts).
-  if (upstream.pathname !== "/" && upstream.pathname !== "") {
-    const basePath = upstream.pathname.replace(/\/$/, "");
-    if (!pathnameHasPrefix(target.pathname, basePath)) {
-      target.pathname = target.pathname === "/" ? `${basePath}/` : `${basePath}${target.pathname}`;
-    }
-  }
-  return target;
-}
-
-/** Reject absolute / scheme-relative request-targets; keep path + query only. */
-function parseProxyPath(pathWithQuery: string): { ok: true; path: string } | { ok: false } {
-  const raw = pathWithQuery.trim();
-  if (raw === "") {
-    return { ok: true, path: "/" };
-  }
-  // Absolute-form ("http://evil/…") or protocol-relative ("//evil/…").
-  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/u.test(raw) || raw.startsWith("//")) {
-    return { ok: false };
-  }
-  return { ok: true, path: raw.startsWith("/") ? raw : `/${raw}` };
-}
-
-function pathnameHasPrefix(pathname: string, basePath: string): boolean {
-  return pathname === basePath || pathname.startsWith(`${basePath}/`);
-}