diff --git a/docs/decisions.md b/docs/decisions.md index d4d8fa0..da3ea91 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -1624,3 +1624,58 @@ behind it, and what a reviewer should check. IDs are stable; append, do not renu - Inside DeepSeek Harness the request still ends in `dsh` after the parentheses (D-087) while servers that read only that part are in use; the agent segment says `dsh` too. + +## D-093 Requests honor HTTPS_PROXY, HTTP_PROXY and NO_PROXY + +- Node's fetch ignores the proxy variables unless Node itself was started + with `NODE_USE_ENV_PROXY=1` (22.21+, 24+). Cursor's sandbox allows the + network only through a proxy it names in those variables, so every command + there failed at its first request (`oauth_network`), and the Meshy plugin + had to start the CLI with `NODE_USE_ENV_PROXY=1`, which needs a newer Node + than the CLI requires. +- At start, before any request, the CLI reads `https_proxy`, `HTTPS_PROXY`, + `http_proxy`, `HTTP_PROXY` and `no_proxy`, `NO_PROXY` (lowercase first, as + curl and undici do). When either proxy is set it installs a global + dispatcher once, so every fetch goes through it: the API, sign-in, + downloads, input URL checks, and the update check's child process, which + starts through the same entry point. Without a proxy variable nothing + changes. +- The dispatcher is undici's `EnvHttpProxyAgent`. `https:` URLs use + `HTTPS_PROXY` (a CONNECT tunnel) and fall back to `HTTP_PROXY`. `http:` URLs + go to an `http://` proxy as plain forwarded requests, as curl sends them, so + a proxy that only forwards still works. undici tunnels through an + `https://` proxy for every URL; curl would forward `http:` there, and the + only `http:` targets are a custom `MESHY_BASE_URL_*` (usually this machine, + which goes direct) and an input URL a user gives; Ark accepted this limit + on 2026-11-09 rather than a hand-written forwarding client. `NO_PROXY` is + passed as given, so `*` still means every host. +- This machine always goes direct: `localhost`, `127.0.0.0/8` and `::1`, as + Go's `net/http` does (Ark, 2026-11-09). A custom `MESHY_BASE_URL_*` on + loopback is a development server, and its credential would otherwise cross + the proxy in the clear. `NO_PROXY` cannot express a range, so a thin + dispatcher in front sends loopback hosts to a plain agent and everything + else to `EnvHttpProxyAgent`. +- A proxy value undici cannot use (not `http://` or `https://`, no host, a + query, a bad escape) does not fall back to going direct: every request + fails before it leaves, with an error that names the variable and never its + value, which may hold a password. The check builds the proxy agent undici + would build, so nothing it accepts is refused. Local commands still run. + Sign-in and downloads report the same message, and sign-in points at the + proxy variables rather than at another way to sign in. +- A request the proxy refuses (a CONNECT answered other than 200, a forwarded + request answered 407), or whose `https://` proxy fails the certificate check + (a name mismatch, which undici wraps as `UND_ERR_PRX_TLS`; an untrusted or + expired certificate, which arrives as its own errno), never reached Meshy: + the transport records it as never sent (`not_submitted`), not as a + submission whose outcome is unknown, and the error says it was the proxy. + Other TLS failures with the proxy (an `https://` proxy URL pointing at a + plain HTTP port, say) are still recorded as unknown, the conservative side. + undici reports refusals only by message; `tests/proxy.test.ts` pins the + messages of the version in the lockfile. +- undici is a dependency for this alone. Node's own `http.setGlobalProxyFromEnv` + does the same, but Node 22 does not have it (24.20 does); one code path + covers every Node the CLI supports (22.12+), and the global dispatcher is + what Node's built-in fetch uses on both 22 and 24. +- The transport's own rules are unchanged: it still follows no redirect and + refuses a URL outside its base. The proxy only carries the request, and for + `https:` URLs it sees a CONNECT tunnel, not the request. diff --git a/docs/usage.md b/docs/usage.md index e36f0ba..99b43a9 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -541,6 +541,7 @@ URI is accepted when its bytes are a GLB. | `MESHY_LOG_LEVEL` | `warn` | | `MESHY_CLI_CLIENT` | unset — a tool that runs meshy-cli for its users names itself here (for example `meshy-dcc/0.2.2 (blender)`); appended to the User-Agent of every request. Inside DeepSeek Harness (`DSH_SHELL=1`) it defaults to `dsh` | | `MESHY_CLI_AGENT` | unset — the AI agent running meshy-cli is detected from the variables it sets on its commands (Cursor, Claude Code, Codex, Copilot, Gemini CLI, Kiro CLI, OpenCode, Hermes, DeepSeek Harness, Cline, Roo Code, or any agent that sets `AI_AGENT`) and named in the User-Agent of API requests to Meshy (`meshy.ai`, `meshy.cn`) as `; agent [/]` inside the parentheses; requests anywhere else, sign-in, input URL checks and asset downloads leave it out. Set a name (`grok-bot`, `claude-code/desktop`: lowercase letters, digits, `.`, `-`) to name it yourself, or `none` to leave it out. `meshy doctor` shows what was detected and from which variable | +| `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` | unset — when `HTTPS_PROXY` or `HTTP_PROXY` is set (lowercase spellings too, lowercase first), every request goes through that proxy: API calls, sign-in, downloads, input URL checks and the update check. `HTTPS_PROXY` covers `https:` URLs (through a CONNECT tunnel) and falls back to `HTTP_PROXY`; `http:` URLs go to an `http://` proxy as plain forwarded requests, as with curl (an `https://` proxy tunnels them too). `NO_PROXY` lists hosts that go direct (comma-separated; `*` for all), and this machine (`localhost`, `127.0.0.0/8`, `::1`) always does, so a local API's credential never crosses the proxy. A value that is not a usable `http://` or `https://` proxy URL stops every request with an error naming the variable (never its value), rather than going direct. A request the proxy refuses (a CONNECT not answered 200, a 407), or whose `https://` proxy fails its certificate check, was never sent. Needed inside sandboxes that allow the network only through a proxy, such as Cursor's | | `MESHY_CLI_NO_UPDATE_NOTIFIER` | unset — any non-empty value disables update checks; CI envs (`CI`, `GITHUB_ACTIONS`, `BUILD_NUMBER`, `RUN_ID`) auto-skip | ## Update notifications diff --git a/package.json b/package.json index c434b0f..c097b89 100644 --- a/package.json +++ b/package.json @@ -56,6 +56,7 @@ "dependencies": { "commander": "^15.0.0", "sharp": "^0.35.4", + "undici": "^7.30.2", "zod": "^4.5.2" }, "devDependencies": { diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index db51ce3..d30f88e 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -14,6 +14,9 @@ importers: sharp: specifier: ^0.35.4 version: 0.35.4(@types/node@22.20.4) + undici: + specifier: ^7.30.2 + version: 7.30.2 zod: specifier: ^4.5.2 version: 4.5.2 @@ -522,6 +525,10 @@ packages: undici-types@6.21.0: resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==} + undici@7.30.2: + resolution: {integrity: sha512-mLyPQnHwUxaM/rideoK/+KL8DaAJLRl4aBCfmX444aCSLnIaomqPLtNRe2jdCYcsk5wZzXrDIQC8ZeYNRAYyIA==} + engines: {node: '>=20.18.1'} + zod@4.5.2: resolution: {integrity: sha512-XkYXCol10+ba/6F/cueWV+TezUeOqXW0hdeJt5CdXjTYeAgAQg5N03RQdJ80mhfFE72+pblvYMW4wy2Qp4Qbrg==} @@ -885,4 +892,6 @@ snapshots: undici-types@6.21.0: {} + undici@7.30.2: {} + zod@4.5.2: {} diff --git a/src/client/transport.ts b/src/client/transport.ts index 939cd27..b46be7b 100644 --- a/src/client/transport.ts +++ b/src/client/transport.ts @@ -23,6 +23,7 @@ import { mapHttpError, MeshyApiError } from "./errors.js"; import { logger } from "../internal/logger.js"; import { apiUserAgent } from "../internal/user-agent.js"; +import { proxyFailure } from "../internal/proxy.js"; export type TransportPhase = "validate" | "connect" | "request" | "response" | "body" | "timeout" | "aborted"; @@ -154,6 +155,8 @@ function errnoOf(err: unknown): string | undefined { const CONNECT_ERRNOS = new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "EHOSTUNREACH", "ENETUNREACH", "UND_ERR_CONNECT_TIMEOUT", "ERR_TLS_CERT_ALTNAME_INVALID", "CERT_HAS_EXPIRED", "DEPTH_ZERO_SELF_SIGNED_CERT", "UNABLE_TO_VERIFY_LEAF_SIGNATURE", "SELF_SIGNED_CERT_IN_CHAIN"]); function classifyFetchFailure(err: unknown, phase: TransportPhase): TransportPhase { + // Failed at the proxy, before the target (D-093). + if (proxyFailure(err)) return "connect"; const errno = errnoOf(err); if (errno && CONNECT_ERRNOS.has(errno)) return "connect"; return phase; @@ -223,9 +226,10 @@ export function createTransport(cfg: TransportConfig): Transport { return new TransportError({ message: `request to ${path} timed out after ${timeoutMs}ms`, phase: "timeout", path, cause: err, credentialKind: cfg.credentialKind }); } const errno = errnoOf(err); + const proxy = proxyFailure(err); const msg = err instanceof Error ? err.message : String(err); return new TransportError({ - message: `network error calling ${path}: ${msg}${errno ? ` (${errno})` : ""}`, + message: proxy ? `${proxy} (calling ${path}); nothing was sent` : `network error calling ${path}: ${msg}${errno ? ` (${errno})` : ""}`, phase: classifyFetchFailure(err, phase), path, errno, diff --git a/src/index.ts b/src/index.ts index 9e1dfb7..9d94012 100644 --- a/src/index.ts +++ b/src/index.ts @@ -7,7 +7,8 @@ * - turn SIGINT / SIGTERM / SIGHUP into a cooperative abort (exit 130) instead of a hard kill; * - route every failure — including Commander parse errors — through one * exit that renders the v1 error envelope in the format the command would have used; - * - flush stdout before exiting. + * - flush stdout before exiting; + * - route every request through the proxy HTTPS_PROXY / HTTP_PROXY name. */ import type { Command } from "commander"; @@ -22,8 +23,11 @@ import { stopActiveProgress } from "./internal/progress.js"; import { errorEnvelope } from "./internal/result.js"; import { resolveFormat } from "./internal/runtime.js"; import { refreshCache, shouldRunUpdateCheck } from "./internal/update-notifier.js"; +import { useProxyFromEnv } from "./internal/proxy.js"; async function main(): Promise { + // Before any request, the update check's included (D-093). + await useProxyFromEnv(); const argv = process.argv; if (argv.includes("--no-update-check")) { // Children (none today, but any future spawn) inherit the opt-out. diff --git a/src/internal/device.ts b/src/internal/device.ts index 69be08c..6168203 100644 --- a/src/internal/device.ts +++ b/src/internal/device.ts @@ -10,6 +10,7 @@ import { HintedError } from "./errors.js"; import { USER_AGENT } from "./user-agent.js"; import type { TokenResponse } from "./oauth.js"; +import { fetchErrorMessage, PROXY_HINT, proxyFailure } from "./proxy.js"; // --------------------------------------------------------------------------- // Types @@ -112,9 +113,9 @@ export async function deviceAuthorization( }); } catch (err) { throw new HintedError({ - message: `Network error contacting device authorization endpoint: ${err instanceof Error ? err.message : String(err)}`, + message: `Network error contacting device authorization endpoint: ${fetchErrorMessage(err)}`, code: "oauth_network", - hint: "Run: meshy auth login --with-key msy_...", + hint: proxyFailure(err) ? PROXY_HINT : "Run: meshy auth login --with-key msy_...", }); } @@ -227,9 +228,9 @@ async function deviceTokenOnce( }); } catch (err) { throw new HintedError({ - message: `Network error polling device token: ${err instanceof Error ? err.message : String(err)}`, + message: `Network error polling device token: ${fetchErrorMessage(err)}`, code: "oauth_network", - hint: "Run: meshy auth login", + hint: proxyFailure(err) ? PROXY_HINT : "Run: meshy auth login", }); } diff --git a/src/internal/download.ts b/src/internal/download.ts index a33d41c..f22c15a 100644 --- a/src/internal/download.ts +++ b/src/internal/download.ts @@ -34,6 +34,7 @@ import { isInside, looksLikeFile, realpathLenient, resolveWithinRoot, safeExtens import { USER_AGENT } from "./user-agent.js"; import { enumerateAssets, selectDefaultAssets, type Asset, type DefaultSelection, type SkipReason } from "./artifacts.js"; import { fileDigest, relinkMaterials, type MaterialLinkReport } from "./material-links.js"; +import { fetchErrorMessage } from "./proxy.js"; /** Extensions sharp can transcode between. */ const CONVERTIBLE_IMAGE_EXTS = new Set(["jpg", "jpeg", "png", "webp", "gif", "tiff", "tif", "avif"]); @@ -147,7 +148,7 @@ export async function fetchToTemp(rawUrl: string, target: string, opts: FetchOpt } catch (err) { if (opts.signal?.aborted) throw new CliError({ code: "interrupted", message: `download of ${redact(url)} interrupted` }); if (controller.signal.aborted) throw new CliError({ code: "network", message: `download of ${redact(url)} timed out after ${limits.timeoutMs}ms` }); - throw new CliError({ code: "network", message: `download of ${redact(url)} failed: ${err instanceof Error ? err.message : String(err)}`, cause: err }); + throw new CliError({ code: "network", message: `download of ${redact(url)} failed: ${fetchErrorMessage(err)}`, cause: err }); } if (r.status >= 300 && r.status < 400) { const loc = r.headers.get("location"); diff --git a/src/internal/file-input.ts b/src/internal/file-input.ts index a9f73d0..6709020 100644 --- a/src/internal/file-input.ts +++ b/src/internal/file-input.ts @@ -22,6 +22,7 @@ import type { MediaField, MediaKind } from "../client/resource-registry.js"; import { UsageError } from "./errors.js"; import { logger } from "./logger.js"; import { USER_AGENT } from "./user-agent.js"; +import { fetchErrorMessage } from "./proxy.js"; export const DEFAULT_MEDIA_LIMITS = { /** 50 MiB — an engineering default, not a Meshy product limit. */ @@ -179,7 +180,7 @@ async function preflightUrl(url: string, flagLabel: string, limits: MediaLimits, controller.abort(); } } catch (err) { - const msg = err instanceof Error ? err.message : String(err); + const msg = fetchErrorMessage(err); if (timeout.aborted) throw new UsageError(`${flagLabel}: preflight of ${url} timed out after ${limits.preflightTimeoutMs}ms`); throw new UsageError(`${flagLabel}: cannot reach ${url} (${msg})`); } diff --git a/src/internal/oauth.ts b/src/internal/oauth.ts index 779e54f..b324003 100644 --- a/src/internal/oauth.ts +++ b/src/internal/oauth.ts @@ -22,6 +22,7 @@ import type { CredentialAccount } from "./credentials.js"; import { HintedError } from "./errors.js"; import { USER_AGENT } from "./user-agent.js"; import { renderCallbackPage } from "./oauth-page.js"; +import { fetchErrorMessage, PROXY_HINT, proxyFailure } from "./proxy.js"; // --------------------------------------------------------------------------- // PKCE helpers @@ -350,9 +351,9 @@ async function postToken( }); } catch (err) { throw new HintedError({ - message: `Network error contacting token endpoint: ${err instanceof Error ? err.message : String(err)}`, + message: `Network error contacting token endpoint: ${fetchErrorMessage(err)}`, code: "oauth_network", - hint: "Run: meshy auth login", + hint: proxyFailure(err) ? PROXY_HINT : "Run: meshy auth login", }); } diff --git a/src/internal/proxy-dispatcher.ts b/src/internal/proxy-dispatcher.ts new file mode 100644 index 0000000..311e7a2 --- /dev/null +++ b/src/internal/proxy-dispatcher.ts @@ -0,0 +1,79 @@ +/** + * The undici side of D-093, loaded only when a proxy variable is set (see + * proxy.ts): checking proxy URLs as undici would use them, and the global + * dispatcher that sends this machine direct and everything else through + * EnvHttpProxyAgent. + */ + +import { Agent, Dispatcher, EnvHttpProxyAgent, ProxyAgent, setGlobalDispatcher } from "undici"; + +import { isLoopbackHost, PROXY_INVALID_CODE, type ProxyFromEnv } from "./proxy.js"; + +/** Whether undici accepts value as a proxy URL: http(s), a host, nothing it cannot decode. */ +export function isUsableProxyUrl(value: string): boolean { + try { + const { protocol, hostname } = new URL(value); + if ((protocol !== "http:" && protocol !== "https:") || hostname === "") return false; + void new ProxyAgent({ uri: value }).close(); + return true; + } catch { + return false; + } +} + +/** + * Sends requests for this machine (localhost, 127.0.0.0/8, ::1) direct and + * every other one through the proxy dispatcher. NO_PROXY cannot express a + * range, and appending hosts to it would break NO_PROXY=*. + */ +class LoopbackDirect extends Dispatcher { + constructor( + private readonly proxied: Dispatcher, + private readonly direct: Dispatcher, + ) { + super(); + } + + override dispatch(opts: Dispatcher.DispatchOptions, handler: Dispatcher.DispatchHandler): boolean { + const origin = opts.origin === undefined ? undefined : new URL(String(opts.origin)); + return (origin && isLoopbackHost(origin.hostname) ? this.direct : this.proxied).dispatch(opts, handler); + } + + override close(): Promise; + override close(callback: () => void): void; + override close(callback?: () => void): Promise | void { + const done = Promise.all([this.proxied.close(), this.direct.close()]).then(() => undefined); + if (!callback) return done; + void done.then(callback); + } + + override destroy(): Promise; + override destroy(err: Error | null): Promise; + override destroy(callback: () => void): void; + override destroy(err: Error | null, callback: () => void): void; + override destroy(errOrCallback?: Error | null | (() => void), callback?: () => void): Promise | void { + const err = typeof errOrCallback === "function" ? null : (errOrCallback ?? null); + const cb = typeof errOrCallback === "function" ? errOrCallback : callback; + const done = Promise.all([this.proxied.destroy(err), this.direct.destroy(err)]).then(() => undefined); + if (!cb) return done; + void done.then(cb); + } +} + +function invalidProxyError(variable: string): Error { + const err = new Error(`${variable} is not a valid proxy URL (expected http://host:port or https://host:port); fix or unset it`); + (err as { code?: string }).code = PROXY_INVALID_CODE; + return err; +} + +/** Installs the global dispatcher for a proxy setting, or one whose every connection fails for an unusable one. */ +export function installProxy( + proxy: Exclude, + install: (dispatcher: Dispatcher) => void = setGlobalDispatcher, +): void { + if (proxy.kind === "invalid") { + install(new Agent({ connect: (_opts, callback) => callback(invalidProxyError(proxy.variable), null) })); + return; + } + install(new LoopbackDirect(new EnvHttpProxyAgent({ ...proxy.settings, proxyTunnel: false }), new Agent())); +} diff --git a/src/internal/proxy.ts b/src/internal/proxy.ts new file mode 100644 index 0000000..2561cc4 --- /dev/null +++ b/src/internal/proxy.ts @@ -0,0 +1,144 @@ +/** + * Outbound requests honor the standard proxy variables (D-093). + * + * Node's fetch ignores HTTPS_PROXY / HTTP_PROXY / NO_PROXY unless Node itself + * was started with NODE_USE_ENV_PROXY=1 (22.21+, 24+), so a command run behind + * a proxy (Cursor's sandbox enforces its network allowlist through one, and so + * do many corporate networks) failed at its first request. When one of those + * variables is set, the CLI installs a global dispatcher once, at start, so + * every fetch — API, sign-in, downloads, the update check — goes through the + * proxy, on every Node version the CLI supports. Without the variables + * nothing changes. + * + * - An http: URL goes to an http:// proxy as a plain forwarded request, as + * curl sends it; an https: URL goes through a CONNECT tunnel. undici always + * tunnels through an https:// proxy, http: URLs included. + * - Hosts in NO_PROXY go direct, and this machine always does (localhost, + * 127.0.0.0/8, ::1), as Go's net/http does, so a credential for a local API + * never crosses the proxy in the clear. + * - A proxy value undici cannot use sends nothing at all, rather than going + * direct, and the error names the variable, never its value, which may hold + * a password. + */ + +import { BlockList, isIP } from "node:net"; +import type { Dispatcher } from "undici"; + +export interface ProxySettings { + /** Proxy for https: URLs; "" = use httpProxy. */ + httpsProxy: string; + /** Proxy for http: URLs (and https: ones when httpsProxy is ""); "" = none. */ + httpProxy: string; + /** Hosts that go direct, as NO_PROXY lists them; "" = none. */ + noProxy: string; +} + +export type ProxyFromEnv = + | { kind: "none" } + /** The named variable holds something undici cannot use as a proxy. */ + | { kind: "invalid"; variable: string } + | { kind: "proxy"; settings: ProxySettings }; + +/** The code of the error a request fails with while the proxy setting is unusable. */ +export const PROXY_INVALID_CODE = "MESHY_PROXY_INVALID"; + +/** What to check when a request failed at the proxy. */ +export const PROXY_HINT = "Check HTTPS_PROXY, HTTP_PROXY and NO_PROXY (or unset them)"; + +/** The first variable among names with a non-blank value: lowercase first, as curl and undici read them. */ +function first(env: NodeJS.ProcessEnv, ...names: string[]): { name: string; value: string } | null { + for (const name of names) { + const value = env[name]?.trim(); + if (value) return { name, value }; + } + return null; +} + +/** + * The proxy the environment names. Unset values are "", never undefined: + * undici would otherwise read process.env again. undici, which checks the + * URLs, is loaded only when a proxy variable is set: every command pays for + * it otherwise (~40 ms at start). + */ +export async function proxySettings(env: NodeJS.ProcessEnv = process.env): Promise { + const https = first(env, "https_proxy", "HTTPS_PROXY"); + const http = first(env, "http_proxy", "HTTP_PROXY"); + if (!https && !http) return { kind: "none" }; + const { isUsableProxyUrl } = await import("./proxy-dispatcher.js"); + for (const named of [https, http]) { + if (named && !isUsableProxyUrl(named.value)) return { kind: "invalid", variable: named.name }; + } + return { + kind: "proxy", + settings: { + httpsProxy: https?.value ?? "", + httpProxy: http?.value ?? "", + noProxy: first(env, "no_proxy", "NO_PROXY")?.value ?? "", + }, + }; +} + +// BlockList also matches an IPv4-mapped IPv6 address (::ffff:127.0.0.1) against the IPv4 rule. +const LOOPBACK = new BlockList(); +LOOPBACK.addSubnet("127.0.0.0", 8, "ipv4"); +LOOPBACK.addAddress("::1", "ipv6"); + +/** Whether a URL hostname is this machine: localhost, 127.0.0.0/8, ::1 (bracketed or not). */ +export function isLoopbackHost(hostname: string): boolean { + const host = hostname.replace(/^\[(.*)\]$/, "$1").toLowerCase(); + if (host === "localhost") return true; + const family = isIP(host); + if (family === 4) return LOOPBACK.check(host, "ipv4"); + if (family === 6) return LOOPBACK.check(host, "ipv6"); + return false; +} + +/** + * Routes every fetch through the proxy the environment names. Returns whether + * it installed a dispatcher; a no-op when no proxy variable is set. With an + * unusable value it installs one whose every connection fails, so nothing + * goes direct behind the user's back. Never throws. + */ +export async function useProxyFromEnv( + env: NodeJS.ProcessEnv = process.env, + install?: (dispatcher: Dispatcher) => void, +): Promise { + const proxy = await proxySettings(env); + if (proxy.kind === "none") return false; + const { installProxy } = await import("./proxy-dispatcher.js"); + installProxy(proxy, install); + return true; +} + +/** undici's own errors for a proxy that refused a request (pinned by tests/proxy.test.ts). */ +const PROXY_REFUSALS = [/^Proxy response \(\d{3}\) !== 200 when HTTP Tunneling$/, /^Proxy Authentication Required \(407\)$/]; + +/** + * Why a fetch failed at the proxy, before reaching its target: the proxy + * setting is unusable, the TLS connection to an https:// proxy failed on its + * certificate's name (undici wraps only that one, as UND_ERR_PRX_TLS; other + * certificate and connection errors reach the transport as their own errno), + * or the proxy refused the request (a CONNECT answered other than 200, a + * forwarded request answered 407). Undefined for any other failure. Either + * way the target was never reached. + */ +export function proxyFailure(err: unknown): string | undefined { + // fetch wraps it: "fetch failed" → (a refused tunnel: "Request was cancelled.") → undici's error. + let cause: unknown = err; + for (let depth = 0; depth < 5 && cause instanceof Error; depth += 1, cause = cause.cause) { + const { code } = cause as { code?: unknown }; + if (code === PROXY_INVALID_CODE) return cause.message; + if (code === "UND_ERR_PRX_TLS") { + const reason = cause.cause instanceof Error ? cause.cause.message : cause.message; + return `the TLS connection to the proxy failed: ${reason}`; + } + const { message } = cause; + if (PROXY_REFUSALS.some((re) => re.test(message))) return `the proxy refused the request: ${message}`; + } + return undefined; +} + +/** A fetch failure for a message: the proxy's part when it failed there, else the error's own. */ +export function fetchErrorMessage(err: unknown): string { + return proxyFailure(err) ?? (err instanceof Error ? err.message : String(err)); +} diff --git a/src/root.ts b/src/root.ts index b82e484..7349949 100644 --- a/src/root.ts +++ b/src/root.ts @@ -147,6 +147,7 @@ ENVIRONMENT: MESHY_CLI_NO_UPDATE_NOTIFIER set to disable update checks MESHY_CLI_CLIENT name of the tool running meshy-cli, added to the User-Agent MESHY_CLI_AGENT AI agent named to Meshy in the User-Agent (default: detected); none = off + HTTPS_PROXY, HTTP_PROXY proxy every request goes through (lowercase too); NO_PROXY hosts and this machine go direct Docs: https://docs.meshy.ai/`; diff --git a/tests/proxy.test.ts b/tests/proxy.test.ts new file mode 100644 index 0000000..4e2d937 --- /dev/null +++ b/tests/proxy.test.ts @@ -0,0 +1,290 @@ +/** + * Outbound requests honor the standard proxy variables (D-093): with + * HTTPS_PROXY / HTTP_PROXY set, every request goes through the proxy unless + * NO_PROXY exempts its host or the host is this machine; without them nothing + * changes. Cursor's sandbox enforces its network allowlist through such a + * proxy. + * + * Targets that must go through the proxy use a `.invalid` host: it never + * resolves, so a request that reaches the target at all went through the + * test proxy, which sends every host to the loopback target. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { createServer, request as httpRequest, type Server } from "node:http"; +import { connect, type AddressInfo } from "node:net"; +import { errors, getGlobalDispatcher, setGlobalDispatcher, type Dispatcher } from "undici"; + +import { createTransport, TransportError } from "../src/client/transport.js"; +import { deviceAuthorization } from "../src/internal/device.js"; +import { isLoopbackHost, PROXY_HINT, proxySettings, useProxyFromEnv } from "../src/internal/proxy.js"; +import { jsonReply, runCli, startMockApi } from "./helpers/cli.js"; + +interface TestProxy { + url: string; + /** Plain forwarded requests, then CONNECT tunnels, it carried. */ + forwarded: () => number; + tunnels: () => number; + close: () => Promise; +} + +/** + * A forward proxy on loopback that sends every host to `targetPort` on + * 127.0.0.1. `connect` decides how it answers CONNECT: open the tunnel, or + * refuse with a status. + */ +async function startProxy(targetPort: () => number, opts: { connect?: "open" | number; forward?: "pass" | number } = {}): Promise { + let forwarded = 0; + let tunnels = 0; + const server: Server = createServer((req, res) => { + if (typeof opts.forward === "number") { + res.writeHead(opts.forward, { "Proxy-Authenticate": "Basic" }); + res.end(); + return; + } + forwarded += 1; + const target = new URL(req.url ?? "/"); + const upstream = httpRequest( + { host: "127.0.0.1", port: targetPort(), path: target.pathname + target.search, method: req.method, headers: req.headers }, + (reply) => { + res.writeHead(reply.statusCode ?? 502, reply.headers); + reply.pipe(res); + }, + ); + req.pipe(upstream); + }); + server.on("connect", (_req, socket) => { + if (typeof opts.connect === "number") { + socket.end(`HTTP/1.1 ${opts.connect} Refused\r\nProxy-Authenticate: Basic\r\n\r\n`); + return; + } + tunnels += 1; + const upstream = connect(targetPort(), "127.0.0.1", () => { + socket.write("HTTP/1.1 200 Connection Established\r\n\r\n"); + upstream.pipe(socket); + socket.pipe(upstream); + }); + }); + await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve)); + const { port } = server.address() as AddressInfo; + return { + url: `http://127.0.0.1:${port}`, + forwarded: () => forwarded, + tunnels: () => tunnels, + close: () => new Promise((resolve) => server.close(() => resolve())), + }; +} + +async function startTarget(): Promise<{ port: () => number; hits: () => number; close: () => Promise }> { + let hits = 0; + const server = createServer((_req, res) => { + hits += 1; + res.setHeader("Content-Type", "application/json"); + res.end('{"ok":true}'); + }); + await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve)); + return { + port: () => (server.address() as AddressInfo).port, + hits: () => hits, + close: () => new Promise((resolve) => server.close(() => resolve())), + }; +} + +/** Restores the global dispatcher a test replaced. */ +function keepDispatcher(t: { after: (fn: () => void) => void }): void { + const previous = getGlobalDispatcher(); + t.after(() => setGlobalDispatcher(previous)); +} + +test("no proxy variable: nothing to read, nothing installed", async () => { + assert.deepEqual(await proxySettings({}), { kind: "none" }); + assert.deepEqual(await proxySettings({ HTTPS_PROXY: " ", NO_PROXY: "example.com" }), { kind: "none" }, "blank values and NO_PROXY alone name no proxy"); + const installed: Dispatcher[] = []; + assert.equal(await useProxyFromEnv({ PATH: "/usr/bin" }, (d) => installed.push(d)), false); + assert.equal(installed.length, 0); +}); + +test("proxy settings: both spellings, lowercase first", async () => { + assert.deepEqual(await proxySettings({ HTTPS_PROXY: "http://proxy:3128/" }), { + kind: "proxy", + settings: { httpsProxy: "http://proxy:3128/", httpProxy: "", noProxy: "" }, + }); + assert.deepEqual( + await proxySettings({ + https_proxy: "http://lower:1", + HTTPS_PROXY: "http://upper:1", + http_proxy: "http://lower:2", + HTTP_PROXY: "http://upper:2", + no_proxy: "lower.example", + NO_PROXY: "upper.example", + }), + { kind: "proxy", settings: { httpsProxy: "http://lower:1", httpProxy: "http://lower:2", noProxy: "lower.example" } }, + ); +}); + +test("this machine is localhost, 127.0.0.0/8 and ::1, in any spelling a URL gives", () => { + for (const host of ["localhost", "LOCALHOST", "127.0.0.1", "127.0.0.2", "127.255.255.254", "[::1]", "::1", new URL("http://[::ffff:127.0.0.1]/").hostname]) { + assert.equal(isLoopbackHost(host), true, host); + } + for (const host of ["128.0.0.1", "10.0.0.1", "[::2]", "localhost.example", "example.com", "0.0.0.0"]) { + assert.equal(isLoopbackHost(host), false, host); + } +}); + +test("an invalid proxy URL names the variable, never its value, and no request leaves", async (t) => { + keepDispatcher(t); + const target = await startTarget(); + t.after(target.close); + for (const value of [ + "http://user:s3cret@proxy.example:notaport", + "proxy.example:3128", + "ftp://proxy.example:21", + "http://user:%E0%A4%A@proxy.example:8080", + "http://proxy.example:8080/?x=1", + ]) { + assert.deepEqual(await proxySettings({ HTTPS_PROXY: value }), { kind: "invalid", variable: "HTTPS_PROXY" }, value); + } + assert.deepEqual(await proxySettings({ http_proxy: "::" }), { kind: "invalid", variable: "http_proxy" }); + + assert.equal(await useProxyFromEnv({ HTTP_PROXY: "http://user:s3cret@proxy.example:notaport" }), true); + const transport = createTransport({ baseUrl: `http://api.example.invalid:${target.port()}/openapi/v1`, apiKey: "msy_k", readTimeoutMs: 5000 }); + await assert.rejects(transport.requestJson("POST", "/text-to-3d", { body: {} }), (e: unknown) => { + assert.ok(e instanceof TransportError); + assert.equal(e.neverSent, true, "an unusable proxy setting sends nothing"); + assert.match(e.message, /HTTP_PROXY is not a valid proxy URL/); + assert.doesNotMatch(e.message, /s3cret|user:/); + return true; + }); + assert.equal(target.hits(), 0, "the request did not go direct either"); + + await assert.rejects(deviceAuthorization(`http://api.example.invalid:${target.port()}/openapi/v1`), (e: unknown) => { + const err = e as { message: string; hint?: string }; + assert.match(err.message, /HTTP_PROXY is not a valid proxy URL/, "sign-in names the variable too"); + assert.doesNotMatch(err.message, /s3cret/); + assert.equal(err.hint, PROXY_HINT, "and points at the proxy, not at another way to sign in"); + return true; + }); +}); + +test("an http: request goes through the proxy as a plain forward, an https: one as a tunnel", async (t) => { + keepDispatcher(t); + const target = await startTarget(); + t.after(target.close); + const proxy = await startProxy(target.port, { connect: 403 }); + t.after(proxy.close); + assert.equal(await useProxyFromEnv({ HTTP_PROXY: proxy.url }), true); + + const res = await fetch(`http://api.example.invalid:${target.port()}/x`); + assert.equal(res.status, 200, "a proxy that refuses CONNECT still forwards plain HTTP"); + await res.text(); + assert.equal(proxy.forwarded(), 1); + assert.equal(proxy.tunnels(), 0); +}); + +test("NO_PROXY and this machine's own addresses go direct", async (t) => { + keepDispatcher(t); + const target = await startTarget(); + t.after(target.close); + const proxy = await startProxy(target.port); + t.after(proxy.close); + + assert.equal(await useProxyFromEnv({ HTTP_PROXY: proxy.url }), true); + for (const host of ["127.0.0.1", "localhost"]) { + const res = await fetch(`http://${host}:${target.port()}/x`); + assert.equal(res.status, 200, host); + await res.text(); + } + assert.equal(proxy.forwarded() + proxy.tunnels(), 0, "this machine goes direct"); + + const v6 = createServer((_req, res) => res.end("v6")); + const listening = await new Promise((resolve) => { + v6.once("error", () => resolve(false)); + v6.listen(0, "::1", () => resolve(true)); + }); + if (listening) { + try { + const res = await fetch(`http://[::1]:${(v6.address() as AddressInfo).port}/x`); + assert.equal(await res.text(), "v6"); + assert.equal(proxy.forwarded() + proxy.tunnels(), 0, "[::1] goes direct"); + } finally { + await new Promise((resolve) => v6.close(() => resolve())); + } + } else { + t.diagnostic("no IPv6 loopback here; [::1] not exercised"); + } + + for (const noProxy of ["api.example.invalid", "*"]) { + assert.equal(await useProxyFromEnv({ HTTP_PROXY: proxy.url, NO_PROXY: noProxy }), true); + await assert.rejects(fetch(`http://api.example.invalid:${target.port()}/x`), `NO_PROXY=${noProxy} goes direct, and .invalid does not resolve`); + assert.equal(proxy.forwarded() + proxy.tunnels(), 0, `NO_PROXY=${noProxy}`); + } +}); + +test("a proxy that refuses the request is a request never sent, and says it was the proxy", async (t) => { + keepDispatcher(t); + const target = await startTarget(); + t.after(target.close); + for (const [name, proxyOpts, scheme] of [ + ["CONNECT refused for https", { connect: 407 }, "https"], + ["plain forward refused with 407 for http", { forward: 407 }, "http"], + ] as const) { + const proxy = await startProxy(target.port, proxyOpts); + try { + assert.equal(await useProxyFromEnv({ HTTPS_PROXY: proxy.url, HTTP_PROXY: proxy.url }), true); + const transport = createTransport({ baseUrl: `${scheme}://api.example.invalid:${target.port()}/openapi/v1`, apiKey: "msy_k", readTimeoutMs: 5000 }); + await assert.rejects(transport.requestJson("POST", "/text-to-3d", { body: {} }), (e: unknown) => { + assert.ok(e instanceof TransportError, name); + assert.equal(e.neverSent, true, `${name}: the API was never reached`); + assert.match(e.message, /proxy/i, name); + assert.match(e.message, /407/, name); + return true; + }); + } finally { + await proxy.close(); + } + } + assert.equal(target.hits(), 0); +}); + +test("a failed TLS handshake with an https:// proxy is a request never sent", async () => { + // fetch's error when an https:// proxy's certificate does not match its + // name, as undici 7 builds it (TypeError → SecureProxyConnectionError → the + // TLS error). Reproducing it for real needs a CA the test process trusts. + const tls = Object.assign(new Error("Hostname/IP does not match certificate's altnames: IP: 127.0.0.1 is not in the cert's list: "), { + code: "ERR_TLS_CERT_ALTNAME_INVALID", + }); + const fetchImpl = (async () => { + throw new TypeError("fetch failed", { cause: new errors.SecureProxyConnectionError(tls) }); + }) as unknown as typeof fetch; + const transport = createTransport({ baseUrl: "https://api.meshy.ai/openapi/v1", apiKey: "msy_k", readTimeoutMs: 5000, fetchImpl }); + await assert.rejects(transport.requestJson("POST", "/text-to-3d", { body: {} }), (e: unknown) => { + assert.ok(e instanceof TransportError); + assert.equal(e.neverSent, true, "the target was never reached"); + assert.match(e.message, /TLS connection to the proxy failed: Hostname\/IP does not match/); + return true; + }); +}); + +test("the CLI's API requests go through HTTP_PROXY", async (t) => { + const api = await startMockApi((_req, res) => jsonReply(res, 200, { balance: 7 })); + t.after(() => api.close()); + const port = Number(new URL(api.url).port); + const proxy = await startProxy(() => port); + t.after(proxy.close); + const remote = (extra: Record) => + api.env({ + MESHY_API_KEY: "msy_test", + MESHY_BASE_URL_V1: `http://api.example.invalid:${port}/openapi/v1`, + MESHY_BASE_URL_V2: `http://api.example.invalid:${port}/openapi/v2`, + ...extra, + }); + + const viaProxy = await runCli(["balance"], { env: remote({ HTTP_PROXY: proxy.url }) }); + assert.equal(viaProxy.code, 0, viaProxy.stderr); + assert.equal(proxy.forwarded(), 1, "the API request went through the proxy"); + + const loopback = await runCli(["balance"], { env: api.env({ MESHY_API_KEY: "msy_test", HTTP_PROXY: proxy.url }) }); + assert.equal(loopback.code, 0, loopback.stderr); + assert.equal(proxy.forwarded(), 1, "an API on this machine is reached directly"); +});