@cursor/july 0.1.29 → 0.1.31

package/dist/files-backends/agent-store-presigned-url.js

@@ -0,0 +1,347 @@
+/**
+ * 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.
+ */
+export class PresignedUrlRejectedError extends Error {
+    constructor(options) {
+        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) {
+    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) {
+    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) {
+    const allowed = new Set(allowedHosts.map(host => host.toLowerCase()));
+    return (url) => {
+        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 = [
+    "agent-stores.s3.us-east-1.amazonaws.com",
+    "agent-stores.s3.amazonaws.com",
+];
+const PLAYGROUND_AGENT_STORE_BUCKET_HOSTS = [
+    "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() {
+    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) {
+    const trimmed = backendUrl.trim();
+    if (trimmed === "") {
+        return false;
+    }
+    return trimmed.includes("localhost") || trimmed.includes("lclhst.build");
+}
+function isPlaygroundAgentStoreBackendUrl(backendUrl) {
+    try {
+        const hostname = new URL(backendUrl).hostname.toLowerCase();
+        return (hostname === "playground.cursor.sh" ||
+            hostname.endsWith(".playground.cursor.sh"));
+    }
+    catch (_a) {
+        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) {
+    if (isLocalAgentStoreBackendUrl(backendUrl)) {
+        return createLocalDevAgentStorePresignedUrlValidator();
+    }
+    if (isPlaygroundAgentStoreBackendUrl(backendUrl)) {
+        return createHostAllowlistValidator(PLAYGROUND_AGENT_STORE_BUCKET_HOSTS);
+    }
+    return createBcsPresignedUrlValidator();
+}
+function createLocalDevAgentStorePresignedUrlValidator() {
+    const bcsValidator = createBcsPresignedUrlValidator();
+    return (url) => {
+        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) {
+    assertSafeAuthority(url);
+    const hostname = stripIPv6Brackets(url.hostname);
+    if (url.protocol === "http:" && isLoopbackHostName(hostname)) {
+        return;
+    }
+    defaultPresignedUrlValidator(url);
+}
+function assertSafeAuthority(url) {
+    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) {
+    try {
+        const parsed = typeof url === "string" ? new URL(url) : url;
+        return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+    }
+    catch (_a) {
+        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) {
+    let parsed;
+    try {
+        parsed = new URL(args.rawUrl);
+    }
+    catch (_a) {
+        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) {
+    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) {
+    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) {
+    return hostname.startsWith("[") && hostname.endsWith("]")
+        ? hostname.slice(1, -1)
+        : hostname;
+}
+function isIPv4Address(hostname) {
+    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) {
+    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) {
+    // Loose check — just enough to route the host to the IPv6 classifier.
+    return hostname.includes(":");
+}
+function isPrivateOrInternalIPv6(hostname) {
+    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) {
+    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;
+}

package/dist/files-backends/cursor-hosted.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Cursor-managed durable files for hosted agents — the backend that puts
+ * `ctx.host.files` bytes in an Agent Store on S3.
+ *
+ * One credential throughout: the engine's pod `CURSOR_API_KEY`. It authorizes
+ * every call, and the bytes then move between this process and presigned S3
+ * URLs. File contents never transit the control plane, so a large artifact
+ * costs S3 bandwidth rather than backend memory.
+ *
+ * Everything goes through the public API under `/v0/agent-serve-files`, the same
+ * surface any API-key holder gets. This process is an ordinary client of it —
+ * there is no private endpoint, no second base URL, and nothing here that only
+ * works because the caller happens to be an Agent Serve engine. That matters
+ * beyond tidiness: a self-hosted deployment, a CI job, or a customer script can
+ * drive the same store with the same requests.
+ *
+ * Two things follow. There is no Agent Store token: a token narrows an identity
+ * to one store and one capability, which is what a caller that cannot hold a
+ * credential needs (an in-pod FUSE daemon). This process holds the credential
+ * the token would be minted from, so a token bought a round trip, an expiry to
+ * manage, and a second auth path, and no privilege reduction. And there is no
+ * direct call to the store service: the API layer owns the policy, and the
+ * engine never addresses it.
+ *
+ * There is also no store lookup. Every request names this deployment's file
+ * store by the `agentStoreSourceId` the deploy pipeline pinned into the pod
+ * env as `AGENT_SERVE_STORE_SOURCE_ID` — provisioning the store at the same
+ * time, so by boot the store exists and the id resolves. The id is an
+ * address, not a credential: the server maps it to a store and authorizes
+ * every call against the deployment's own live service account, so holding
+ * it grants nothing, and this process never learns a store id it could use
+ * to ask for anyone else's.
+ *
+ * Locally, point `CURSOR_API_BASE_URL` at a backend that serves
+ * `/v0/agent-serve-files` and use a deployment SA key; off hosting the
+ * local-disk sink is the default instead.
+ *
+ * Writes are conditional. The store rejects unconditional writes, so every
+ * `put` first learns the current etag: `new` for a path we believe is absent,
+ * `etag` to replace what we last observed. A raced write comes back 412 and
+ * surfaces as {@link FileConflictError}, which is why this backend reports
+ * `etags: true` and `host.files.capabilities.conflictDetection` is honestly
+ * true.
+ */
+import { type FileSink, type FileSinkBody } from "../files.js";
+/**
+ * Pinned by the deploy pipeline for every Cursor-managed deployment — which
+ * provisions the file store it names in the same step — and reserved from
+ * user secrets. Its presence is the signal that a durable store exists and
+ * the hosted control plane is reachable; a deployment without one (no
+ * service account yet) has no store, and this backend is not selected.
+ */
+export declare const AGENT_SERVE_STORE_SOURCE_ID_ENV_VAR = "AGENT_SERVE_STORE_SOURCE_ID";
+/**
+ * True on Cursor-managed hosting with a provisioned file store.
+ *
+ * Keyed on the store source id alone, deliberately: the credential is not part
+ * of the test. If it were, a missing or regressed `CURSOR_API_KEY` would
+ * silently select pod-local disk on a hosted pod and accept writes that vanish
+ * with the pod. Instead the store is detected, and a missing credential fails
+ * loudly when the sink is used.
+ */
+export declare function isCursorHostedFilesAvailable(env?: NodeJS.ProcessEnv): boolean;
+export interface CursorHostedFilesOptions {
+    /** Control-plane base URL (default: `CURSOR_API_BASE_URL`, else api.cursor.com). */
+    baseUrl?: string;
+    /** Bearer credential (default: `CURSOR_API_KEY`). */
+    apiKey?: string;
+    /** File store to address (default: `AGENT_SERVE_STORE_SOURCE_ID`). */
+    storeSourceId?: string;
+    /** Test seam; defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+type HostedFilesMethods = Omit<FileSink, "get"> & {
+    /** Narrower than {@link FileSink.get}: this backend always reports the etag. */
+    get(key: string): Promise<FileSinkBody | undefined>;
+};
+/**
+ * Cursor-hosted {@link FileSink}, selected on Cursor-managed hosting.
+ *
+ * Stateless apart from the etag cache below: every request names this
+ * deployment's store by its pinned source id, so there is nothing to
+ * resolve, hold, or invalidate.
+ */
+export declare function cursorHostedFiles(options?: CursorHostedFilesOptions): HostedFilesMethods;
+export {};
+//# sourceMappingURL=cursor-hosted.d.ts.map

package/dist/files-backends/cursor-hosted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-hosted.d.ts","sourceRoot":"","sources":["../../src/files-backends/cursor-hosted.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,YAAY,EAGlB,MAAM,aAAa,CAAC;AAWrB;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC,gCACjB,CAAC;AAgBhC;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAGT;AAED,MAAM,WAAW,wBAAwB;IACvC,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAuCD,KAAK,kBAAkB,GAAG,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG;IAChD,gFAAgF;IAChF,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,kBAAkB,CA8VpB"}