@cursor/july 0.1.30 → 0.1.31

package/src/files-backends/agent-store-presigned-url.ts

@@ -0,0 +1,402 @@
+/**
+ * Vendored from `@anysphere/agent-store-sync` `presigned-url.ts` so the
+ * published `@cursor/july` tarball does not depend on that private workspace
+ * package (not on npm). Keep in sync when the source validator changes.
+ */
+
+// Validators the engine runs against every server-returned presigned URL
+// before fetching, so a compromised transport can't turn inbound sync
+// into an SSRF gadget. Production wiring should pin the bucket host via
+// `createHostAllowlistValidator` on top of the strict default.
+
+export type PresignedUrlValidator = (url: URL) => void;
+
+export type PresignedUrlRejectionCode =
+  | "scheme_not_allowed"
+  | "userinfo_not_allowed"
+  | "host_not_allowed"
+  | "private_host_not_allowed";
+
+export interface PresignedUrlRejectionOptions {
+  code: PresignedUrlRejectionCode;
+  message: string;
+  url?: string;
+}
+
+export class PresignedUrlRejectedError extends Error {
+  public readonly code: PresignedUrlRejectionCode;
+  /** The host that triggered the rejection (never the full URL). */
+  public readonly url: string | undefined;
+
+  constructor(options: PresignedUrlRejectionOptions) {
+    super(options.message);
+    this.name = "PresignedUrlRejectedError";
+    this.code = options.code;
+    this.url = options.url;
+  }
+}
+
+/**
+ * Strict default: accepts `https:` URLs to an AWS S3 endpoint with no
+ * userinfo and no private/internal address. Rejects DNS hosts that
+ * resolve into the private IP space and IPv4-mapped IPv6 literals.
+ */
+export function defaultPresignedUrlValidator(url: URL): void {
+  assertSafeAuthority(url);
+  if (url.protocol !== "https:") {
+    throw new PresignedUrlRejectedError({
+      code: "scheme_not_allowed",
+      message: `Refused presigned URL with non-https scheme: ${url.protocol}`,
+      url: redactPresignedUrlString(url),
+    });
+  }
+  const hostname = stripIPv6Brackets(url.hostname);
+  if (isLocalOrInternalHost(hostname)) {
+    throw new PresignedUrlRejectedError({
+      code: "private_host_not_allowed",
+      message: `Refused https presigned URL with private/internal host: ${hostname}`,
+      url: redactPresignedUrlString(url),
+    });
+  }
+  if (!isAwsS3Hostname(hostname)) {
+    throw new PresignedUrlRejectedError({
+      code: "host_not_allowed",
+      message: `Refused presigned URL whose host is not an AWS S3 endpoint: ${hostname}`,
+      url: redactPresignedUrlString(url),
+    });
+  }
+}
+
+/**
+ * True when `hostname` is an AWS S3 object-storage endpoint:
+ * `*.amazonaws.com` with at least one label in
+ * {@link S3_OBJECT_LABELS}. Covers modern virtual-host, path-style,
+ * dualstack, accelerate, and FIPS URLs. Rejects the S3-named control
+ * planes (`s3-control`, `s3-outposts`, `s3-object-lambda`) and the
+ * legacy regional virtual-host form AWS deprecated in 2019, both of
+ * which would otherwise let a tampered presign issuer turn the sync
+ * client into a signed-request gadget against non-storage APIs.
+ */
+export function isAwsS3Hostname(hostname: string): boolean {
+  const lowered = hostname.toLowerCase();
+  if (lowered !== "amazonaws.com" && !lowered.endsWith(".amazonaws.com")) {
+    return false;
+  }
+  const labels = lowered.split(".");
+  return labels.some(label => S3_OBJECT_LABELS.has(label));
+}
+
+const S3_OBJECT_LABELS = new Set(["s3", "s3-accelerate", "s3-fips"]);
+
+/**
+ * Like {@link defaultPresignedUrlValidator} plus a case-insensitive
+ * exact-match check against `allowedHosts` (no subdomain wildcards).
+ */
+export function createHostAllowlistValidator(
+  allowedHosts: readonly string[]
+): PresignedUrlValidator {
+  const allowed = new Set(allowedHosts.map(host => host.toLowerCase()));
+  return (url: URL): void => {
+    defaultPresignedUrlValidator(url);
+    if (!allowed.has(url.hostname.toLowerCase())) {
+      throw new PresignedUrlRejectedError({
+        code: "host_not_allowed",
+        message: `Refused presigned URL whose host is not in the allowlist: ${url.hostname}`,
+        url: redactPresignedUrlString(url),
+      });
+    }
+  };
+}
+
+/**
+ * Virtual-host S3 endpoints for the production `agent-stores` bucket
+ * (matches backend `getAgentStoreBucket()` in
+ * `backend/server/src/agent-stores/utils/agentStoreS3.ts`, which presigns
+ * with a `us-east-1` `S3Client` and the SDK's default virtual-host
+ * addressing). Both the regional form emitted by modern AWS SDK v3 and
+ * the legacy global form are listed so a presign issuer upgrade or
+ * downgrade can't trip the allowlist. Path-style (`s3.amazonaws.com/agent-stores/…`)
+ * is intentionally not listed: the server never sets `forcePathStyle`,
+ * and admitting bare `s3.amazonaws.com` would re-open the "any bucket"
+ * gap this allowlist exists to close.
+ */
+export const BCS_AGENT_STORE_BUCKET_HOSTS: readonly string[] = [
+  "agent-stores.s3.us-east-1.amazonaws.com",
+  "agent-stores.s3.amazonaws.com",
+];
+
+const PLAYGROUND_AGENT_STORE_BUCKET_HOSTS: readonly string[] = [
+  "agent-stores-928182716709-us-west-2-an.s3.us-west-2.amazonaws.com",
+  "agent-stores-928182716709-us-west-2-an.s3.amazonaws.com",
+];
+
+/**
+ * Production validator for the BCS agent-store sync transport: strict
+ * default (https, S3 endpoint, no private hosts, no userinfo) plus the
+ * {@link BCS_AGENT_STORE_BUCKET_HOSTS} pin. Pre-built so callers don't
+ * accidentally pass {@link defaultPresignedUrlValidator}, which would
+ * accept any AWS S3 bucket on the internet and let a buggy or
+ * compromised presign issuer redirect sync traffic away from the real
+ * `agent-stores` bucket.
+ */
+export function createBcsPresignedUrlValidator(): PresignedUrlValidator {
+  return createHostAllowlistValidator(BCS_AGENT_STORE_BUCKET_HOSTS);
+}
+
+/**
+ * True when `backendUrl` targets a local dev backend (localhost or
+ * lclhst.build). Matches IDE checks in `cursor-always-local` /
+ * `cursorCredsService`.
+ */
+export function isLocalAgentStoreBackendUrl(backendUrl: string): boolean {
+  const trimmed = backendUrl.trim();
+  if (trimmed === "") {
+    return false;
+  }
+  return trimmed.includes("localhost") || trimmed.includes("lclhst.build");
+}
+
+function isPlaygroundAgentStoreBackendUrl(backendUrl: string): boolean {
+  try {
+    const hostname = new URL(backendUrl).hostname.toLowerCase();
+    return (
+      hostname === "playground.cursor.sh" ||
+      hostname.endsWith(".playground.cursor.sh")
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Presign validator for the sync client. Production/staging and playground
+ * backends are pinned to their respective agent-store buckets. For a local dev API (see
+ * {@link isLocalAgentStoreBackendUrl}), allow `http:` to loopback only
+ * (LocalStack) and still pin all other URLs to {@link BCS_AGENT_STORE_BUCKET_HOSTS}.
+ */
+export function createAgentStorePresignedUrlValidatorForBackend(
+  backendUrl: string
+): PresignedUrlValidator {
+  if (isLocalAgentStoreBackendUrl(backendUrl)) {
+    return createLocalDevAgentStorePresignedUrlValidator();
+  }
+  if (isPlaygroundAgentStoreBackendUrl(backendUrl)) {
+    return createHostAllowlistValidator(PLAYGROUND_AGENT_STORE_BUCKET_HOSTS);
+  }
+  return createBcsPresignedUrlValidator();
+}
+
+function createLocalDevAgentStorePresignedUrlValidator(): PresignedUrlValidator {
+  const bcsValidator = createBcsPresignedUrlValidator();
+  return (url: URL): void => {
+    assertSafeAuthority(url);
+    const hostname = stripIPv6Brackets(url.hostname);
+    if (url.protocol === "http:" && isLoopbackHostName(hostname)) {
+      return;
+    }
+    bcsValidator(url);
+  };
+}
+
+/**
+ * Like {@link defaultPresignedUrlValidator} plus `http://localhost` /
+ * `127.0.0.1` / `[::1]` (any port) for LocalStack-backed unit tests.
+ * Non-loopback `https:` URLs fall through to the strict default (any S3
+ * bucket). Do not use for IDE wiring — use
+ * {@link createAgentStorePresignedUrlValidatorForBackend} instead.
+ */
+export function localhostPermissivePresignedUrlValidator(url: URL): void {
+  assertSafeAuthority(url);
+  const hostname = stripIPv6Brackets(url.hostname);
+  if (url.protocol === "http:" && isLoopbackHostName(hostname)) {
+    return;
+  }
+  defaultPresignedUrlValidator(url);
+}
+
+function assertSafeAuthority(url: URL): void {
+  if (url.username !== "" || url.password !== "") {
+    throw new PresignedUrlRejectedError({
+      code: "userinfo_not_allowed",
+      message: "Refused presigned URL with embedded userinfo",
+      url: redactPresignedUrlString(url),
+    });
+  }
+}
+
+/**
+ * Strip the query string and userinfo from a presigned URL so the AWS
+ * SigV4 signature never reaches error messages or telemetry.
+ */
+export function redactPresignedUrlString(url: URL | string): string {
+  try {
+    const parsed = typeof url === "string" ? new URL(url) : url;
+    return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+  } catch {
+    return "<unparseable-presigned-url>";
+  }
+}
+
+/**
+ * Parse and validate a server-returned presigned URL before fetch. Uses
+ * {@link relPath} in error text (never the raw URL) so SigV4 credentials
+ * cannot leak into messages.
+ */
+export function assertPresignedUrlSafe(args: {
+  readonly rawUrl: string;
+  readonly relPath: string;
+  readonly validatePresignedUrl: PresignedUrlValidator;
+}): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(args.rawUrl);
+  } catch {
+    throw new Error(`Refusing unparseable presigned URL for ${args.relPath}`);
+  }
+  try {
+    args.validatePresignedUrl(parsed);
+  } catch (error) {
+    throw new Error(
+      `Refusing presigned URL for ${args.relPath}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+      { cause: error instanceof Error ? error : undefined }
+    );
+  }
+}
+
+function isLoopbackHostName(hostname: string): boolean {
+  const lowered = hostname.toLowerCase();
+  return (
+    lowered === "localhost" ||
+    lowered === "ip6-localhost" ||
+    lowered === "127.0.0.1" ||
+    lowered === "::1" ||
+    lowered === "0:0:0:0:0:0:0:1"
+  );
+}
+
+function isLocalOrInternalHost(hostname: string): boolean {
+  if (hostname.length === 0) {
+    return true;
+  }
+  if (isLoopbackHostName(hostname)) {
+    return true;
+  }
+  if (isIPv4Address(hostname)) {
+    return isPrivateOrInternalIPv4(hostname);
+  }
+  if (isIPv6Address(hostname)) {
+    return isPrivateOrInternalIPv6(hostname);
+  }
+  // DNS hostnames can't be classified without resolving; the caller
+  // relies on transport-level allowlists for those.
+  return false;
+}
+
+function stripIPv6Brackets(hostname: string): string {
+  return hostname.startsWith("[") && hostname.endsWith("]")
+    ? hostname.slice(1, -1)
+    : hostname;
+}
+
+function isIPv4Address(hostname: string): boolean {
+  const parts = hostname.split(".");
+  if (parts.length !== 4) {
+    return false;
+  }
+  return parts.every(part => {
+    if (part.length === 0 || part.length > 3) {
+      return false;
+    }
+    if (!/^\d+$/.test(part)) {
+      return false;
+    }
+    const n = Number(part);
+    return Number.isInteger(n) && n >= 0 && n <= 255;
+  });
+}
+
+function isPrivateOrInternalIPv4(hostname: string): boolean {
+  const [a, b] = hostname.split(".").map(Number);
+  if (a === undefined || b === undefined) {
+    return true;
+  }
+  // RFC1918, loopback, link-local, multicast, unspecified, broadcast,
+  // carrier-grade NAT, and reserved blocks.
+  if (a === 0) return true;
+  if (a === 10) return true;
+  if (a === 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  if (a >= 224 && a <= 239) return true;
+  if (a >= 240) return true;
+  return false;
+}
+
+function isIPv6Address(hostname: string): boolean {
+  // Loose check — just enough to route the host to the IPv6 classifier.
+  return hostname.includes(":");
+}
+
+function isPrivateOrInternalIPv6(hostname: string): boolean {
+  const lowered = hostname.toLowerCase();
+  if (lowered === "::" || lowered === "::1") {
+    return true;
+  }
+  // IPv4-mapped IPv6 (RFC4291) routes back through the IPv4 classifier
+  // so `[::ffff:169.254.169.254]` can't slip past the private-IP check.
+  const mapped = extractIPv4MappedAddress(lowered);
+  if (mapped !== undefined) {
+    return isPrivateOrInternalIPv4(mapped);
+  }
+  // ULA fc00::/7, link-local fe80::/10, multicast ff00::/8.
+  if (lowered.startsWith("fc") || lowered.startsWith("fd")) {
+    return true;
+  }
+  if (lowered.startsWith("fe8") || lowered.startsWith("fe9")) {
+    return true;
+  }
+  if (lowered.startsWith("fea") || lowered.startsWith("feb")) {
+    return true;
+  }
+  if (lowered.startsWith("ff")) {
+    return true;
+  }
+  return false;
+}
+
+// Convert an IPv4-mapped IPv6 literal (`::ffff:a.b.c.d` or
+// `::ffff:hhhh:hhhh`) to its dotted-quad form. Returns undefined otherwise.
+function extractIPv4MappedAddress(hostname: string): string | undefined {
+  const dotted = hostname.match(
+    /^(?:0:0:0:0:0|::):?ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i
+  );
+  if (dotted) {
+    return dotted[1];
+  }
+  if (hostname.startsWith("::ffff:")) {
+    const tail = hostname.slice("::ffff:".length);
+    if (isIPv4Address(tail)) {
+      return tail;
+    }
+    const hex = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+    if (hex) {
+      const high = Number.parseInt(hex[1], 16);
+      const low = Number.parseInt(hex[2], 16);
+      if (
+        Number.isFinite(high) &&
+        Number.isFinite(low) &&
+        high >= 0 &&
+        high <= 0xffff &&
+        low >= 0 &&
+        low <= 0xffff
+      ) {
+        return `${(high >> 8) & 0xff}.${high & 0xff}.${(low >> 8) & 0xff}.${low & 0xff}`;
+      }
+    }
+  }
+  return undefined;
+}