@myelinbridge/cli 0.12.2 → 0.13.0

package/README.md

@@ -71,6 +71,11 @@ npx @myelinbridge/cli push  ./run_042 --dataset onco1-wes --submit
   too (S3 multipart). Uploads go direct to storage over short-lived presigned
   URLs — no credential is stored on your machine, and revoking the API key cuts
   off signing immediately.
+- **A corporate proxy is not our problem to ignore (0.13.0).** `HTTPS_PROXY`,
+  `HTTP_PROXY` and `NO_PROXY` are honoured on every call — the API and the part
+  uploads alike. Before this the CLI dialled straight out and a pipeline host
+  whose only egress is a proxy could not deliver at all. The hosts and ports to
+  allow are written down under **For your IT department** below.
 - **Transient failures retry themselves.** Since 0.8.0 a rate limit (`429`)
   waits out `Retry-After` and retries on every command, and a part upload that
   hits a storage hiccup (5xx, an edge timeout, an expired URL) re-signs, backs
@@ -193,6 +198,99 @@ version.
 | `MYELIN_API_KEY` | Required. Created by your bridge owner in **Bridge → API**. |
 | `MYELIN_API_URL` | Optional. Defaults to `https://myelinbridge.com/api/v1`. |
 | `MYELIN_API_HEADER` | Optional. Extra headers sent with every API call, one `Name: value` per line — for a Myelin deployment fronted by something that authenticates before Myelin does (a corporate gateway, an SSO-protected preview). It can never override `Authorization`. |
+| `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | Optional, honoured since **0.13.0** — see below. Lowercase spellings read too. |
+
+## For your IT department
+
+Everything below is derived from what the code actually connects to. If you need
+to hand one page to a network team, hand them this one.
+
+### What the CLI needs to reach
+
+Outbound **TCP 443 only**, to two hosts:
+
+| Host | Why |
+|---|---|
+| `myelinbridge.com` | the API — auth, the quality contract, preflight, part signing, submit, status |
+| `cdjlhyyrbogzkoaujzmj.storage.supabase.co` | the bytes — uploads go **straight to storage** over short-lived presigned URLs, never through the API host |
+
+The second one surprises people, and it is the single commonest way a delivery
+half-works: `myelin ping` and `myelin check` succeed, `myelin push` stalls on
+part 1. Since 0.13.0 that failure names the host it could not reach, so the
+allowlist gap is legible from the error.
+
+If your client runs Myelin at their own address, `MYELIN_API_URL` names the
+first host and the second is that deployment's storage host. You never have to
+guess it — every Myelin deployment publishes the authoritative list in its own
+`content-security-policy` header:
+
+```bash
+curl -sI https://myelinbridge.com | tr ';' '\n' | grep connect-src
+#   connect-src 'self' https://<ref>.supabase.co wss://<ref>.supabase.co https://<ref>.storage.supabase.co
+```
+
+A wildcard rule works if your proxy prefers one: `*.supabase.co`.
+
+### What a person using the web portal needs
+
+Someone reviewing a delivery in a browser needs the two hosts above **plus** the
+Supabase API host, because sign-in and the session live there:
+
+| Host | Port | Why |
+|---|---|---|
+| `myelinbridge.com` | 443 | the application itself |
+| `cdjlhyyrbogzkoaujzmj.supabase.co` | 443 | sign-in and session |
+| `cdjlhyyrbogzkoaujzmj.storage.supabase.co` | 443 | browser uploads, the same presigned PUTs the CLI makes |
+
+Plain HTTPS is enough. The policy also permits `wss:` to the Supabase host, but
+the portal opens no WebSocket today — if your proxy distinguishes the two, you
+do not need to allow WebSocket upgrades for the portal to work.
+
+Nothing else is contacted: scripts and fonts are served by the application
+itself and no analytics or tracker host is involved. That is not a promise in a
+README — it is the `content-security-policy` header above, which the browser
+enforces on every response.
+
+### What you do *not* need to open
+
+- **No inbound anything.** Nothing connects to your network. The one exception
+  is opt-in and yours to choose: if you register a webhook endpoint, Myelin
+  makes an outbound HTTPS call to an address you publish.
+- **No access to the destination bucket.** The client's cloud bucket is written
+  by Myelin, server-side, after review. A partner never touches it and never
+  needs a credential for it.
+- **No FTP, SSH, rsync or fixed source IPs.** One protocol, one port.
+
+### Behind a proxy
+
+Set the standard variables — the CLI honours them on every call, the API and
+the part uploads alike:
+
+```bash
+export HTTPS_PROXY=http://proxy.corp.example:8080
+export NO_PROXY=.corp.example,10.0.0.0/8
+myelin ping        # prints "via proxy http://proxy.corp.example:8080" when one is in use
+```
+
+- `HTTPS_PROXY` for https targets, `HTTP_PROXY` for http, `NO_PROXY` to exclude.
+  Lowercase spellings (`https_proxy`, …) are read too — both are in the wild.
+- Credentials go in the URL: `http://user:pass@proxy:8080` (Basic). They are
+  never printed, logged, or echoed in an error.
+- `NO_PROXY` accepts a host, a suffix (`.corp.example`, `*.corp.example`),
+  `host:port`, an IPv4 CIDR (`10.0.0.0/8`), or `*` for everything.
+- **HTTP CONNECT proxies only.** A `socks5://` value is refused with a message
+  rather than silently bypassed — a CLI that quietly dials direct while you
+  believe it is proxied is worse than one that stops.
+- A typo in a proxy variable fails immediately, before any command runs.
+- **TLS terminates at Myelin, not at your proxy.** Through a CONNECT tunnel the
+  proxy sees the hostname and nothing else. If your proxy performs TLS
+  interception, point Node at its CA:
+  `export NODE_EXTRA_CA_CERTS=/etc/ssl/corp-root.pem`.
+
+Before 0.13.0 the CLI ignored all three variables — Node's `fetch` does — so on
+a host whose only egress is a proxy every command failed with `fetch failed`.
+If you are running an older version behind a proxy, upgrade rather than work
+around it.
 
 ## Webhooks instead of polling
 

package/bin/myelin.js

@@ -40,10 +40,27 @@
 // for), even though `check` correctly warned about it via preflight. The API
 // now includes required-but-empty fields in `metadata` too
 // (`required: true`, `value: null`), and `contract` renders them.
+//
+// 0.13.0 — the CLI reaches the network the way a corporate pipeline host
+// actually reaches it. HTTPS_PROXY / HTTP_PROXY / NO_PROXY (either case) are
+// honoured on every call, API and part upload alike; before this, Node's
+// global fetch ignored all three and a partner whose only egress is a proxy
+// could not deliver at all — the failure read as Myelin being down. The
+// transport is now ours (node:http/node:https, still zero dependencies), so
+// there is one path whether or not a proxy is in the picture. Two smaller
+// consequences: a part upload that cannot reach storage now names the host it
+// could not reach (never the presigned URL — its query string is the
+// credential), and `ping` prints the proxy it used. The hosts and ports a
+// partner's firewall must allow are written down for the first time, in the
+// README's "For your IT department" section.
 
 import { readdirSync, statSync, createReadStream, readFileSync } from 'node:fs'
 import { resolve, join, relative, sep, basename } from 'node:path'
 import { createHash } from 'node:crypto'
+import http from 'node:http'
+import https from 'node:https'
+import tls from 'node:tls'
+import zlib from 'node:zlib'
 import process from 'node:process'
 
 const API_URL = (process.env.MYELIN_API_URL ?? 'https://myelinbridge.com/api/v1').replace(/\/$/, '')
@@ -154,13 +171,404 @@ function opt(name) {
   return i >= 0 && args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : null
 }
 
+// ── Egress: the corporate network this CLI actually runs on ────────────────
+//
+// A CRO's pipeline host usually has no route to the internet of its own. Its
+// only way out is an HTTP CONNECT proxy named by HTTPS_PROXY / HTTP_PROXY,
+// with NO_PROXY listing what must stay inside. Node's global `fetch` ignores
+// all three — Node 22+ honours them only if NODE_USE_ENV_PROXY=1 was set
+// before the process started, Node 20 not at all — so until 0.13.0 every
+// command dialled straight out and died with `fetch failed`. A partner whose
+// only egress is a proxy could not deliver a single byte, and it read as
+// Myelin being down rather than as a variable nobody had honoured.
+//
+// So the CLI speaks the proxy protocol itself, over node:http / node:https,
+// and adds no dependency to do it: this is a binary a customer's IT
+// department installs, and an empty `dependencies` is worth more than the
+// ~200 lines below. It is also the only fix that reaches every Node in
+// `engines` — the undici workaround needs a NODE_OPTIONS preload and a
+// package we would have to ship.
+//
+// One transport for every call, proxied or not. Keeping `fetch` for the
+// direct case would have left the proxy path running only at customer sites,
+// which is the definition of a path that rots.
+//
+// ⚠ Every request carries an explicit agent, always. Node ≥24.5 can install a
+// proxy-aware global agent of its own; if it ever did so under us, a request
+// we had already tunnelled would be tunnelled twice. Our own agent means one
+// behaviour on every Node we support.
+
+const UA = `myelin-cli/${VERSION} (node ${process.versions.node})`
+
+// Lowercase first — curl's precedence, and the spelling most pipelines set.
+// Both are read because both are in the wild: on Windows they are the same
+// variable, on Linux they are not, and which spelling we happened to prefer
+// must never become the partner's problem.
+const envPair = (...names) => {
+  for (const name of names) {
+    const value = process.env[name]
+    if (typeof value === 'string' && value.trim()) return { name, value: value.trim() }
+  }
+  return null
+}
+const httpsProxyEnv = () => envPair('https_proxy', 'HTTPS_PROXY')
+const httpProxyEnv = () => envPair('http_proxy', 'HTTP_PROXY')
+const noProxyEnv = () => envPair('no_proxy', 'NO_PROXY')
+const anyProxyEnv = () => Boolean(httpsProxyEnv() || httpProxyEnv())
+
+const ipv4ToInt = (ip) => {
+  const parts = ip.split('.')
+  if (parts.length !== 4) return null
+  let n = 0
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part)) return null
+    const v = Number(part)
+    if (v > 255) return null
+    n = n * 256 + v
+  }
+  return n >>> 0
+}
+
+const cidrContains = (host, entry) => {
+  const [network, bitsRaw] = entry.split('/')
+  const bits = Number(bitsRaw)
+  const a = ipv4ToInt(host)
+  const b = ipv4ToInt(network)
+  if (a === null || b === null || !Number.isInteger(bits) || bits < 0 || bits > 32) return false
+  if (bits === 0) return true
+  const mask = (0xffffffff << (32 - bits)) >>> 0
+  return ((a & mask) >>> 0) === ((b & mask) >>> 0)
+}
+
+// NO_PROXY entries are hostnames, suffixes (`.corp.example`, `*.corp.example`),
+// `host:port`, an IPv4 CIDR, or `*` for everything. The CIDR form is here
+// because a corporate NO_PROXY nearly always carries one (10.0.0.0/8), and
+// tunnelling an internal host fails exactly as hard as not tunnelling an
+// external one.
+function noProxyMatches(hostname, port) {
+  const raw = noProxyEnv()?.value
+  if (!raw) return false
+  const host = hostname.toLowerCase().replace(/^\[/, '').replace(/\]$/, '')
+  for (const token of raw.split(/[,\s]+/)) {
+    if (!token) continue
+    if (token === '*') return true
+    let entry = token.toLowerCase()
+    // `host:port` — but never split a bare IPv6 literal on its own colons.
+    const withPort = /^(.+):(\d+)$/.exec(entry)
+    if (withPort && !withPort[1].includes(':')) {
+      if (withPort[2] !== String(port)) continue
+      entry = withPort[1]
+    }
+    if (entry.includes('/')) {
+      if (cidrContains(host, entry)) return true
+      continue
+    }
+    entry = entry.replace(/^\*?\./, '')
+    if (!entry) continue
+    if (host === entry || host.endsWith(`.${entry}`)) return true
+  }
+  return false
+}
+
+// A proxy variable we cannot parse is refused out loud. Ignoring it would put
+// us back exactly where this release started: a CLI dialling direct while the
+// partner believes their proxy is carrying the traffic.
+//
+// It throws rather than die()s. die() prints, and this runs inside the request
+// path AND inside egressHint() — so a bad variable printed its message three
+// times before the error it caused. One config problem, one line: the throw is
+// rendered once by whoever was making the call, and checked up front by
+// assertProxyEnvUsable() before any command runs.
+const proxyCache = new Map()
+function parseProxy(varName, raw) {
+  const cacheKey = `${varName} ${raw}`
+  if (proxyCache.has(cacheKey)) return proxyCache.get(cacheKey)
+  // `proxy.corp:8080`, with no scheme at all, is common enough to accept.
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `http://${raw}`
+  let u = null
+  try { u = new URL(withScheme) } catch { u = null }
+  if (!u || !u.hostname) {
+    throw new Error(`${varName} is not a usable proxy URL ("${raw}") — expected http://host:port`)
+  }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    throw new Error(
+      `${varName} names a ${u.protocol.replace(':', '')} proxy ("${raw}"), which this CLI cannot use. ` +
+        `Myelin speaks to an HTTP CONNECT proxy (http://host:port). Ask your network team for one, or for the ` +
+        `allowlist in the CLI README's "For your IT department" section.`,
+    )
+  }
+  const port = Number(u.port || (u.protocol === 'https:' ? 443 : 80))
+  const proxy = {
+    protocol: u.protocol,
+    hostname: u.hostname,
+    port,
+    // Credentials go on the wire and nowhere else: `display` is the only form
+    // a message, a log line or an error is allowed to carry.
+    auth: u.username
+      ? Buffer.from(`${decodeURIComponent(u.username)}:${decodeURIComponent(u.password)}`).toString('base64')
+      : null,
+    display: `${u.protocol}//${u.hostname}:${port}`,
+  }
+  proxyCache.set(cacheKey, proxy)
+  return proxy
+}
+
+function proxyForUrl(url) {
+  const port = Number(url.port || (url.protocol === 'https:' ? 443 : 80))
+  if (noProxyMatches(url.hostname, port)) return null
+  const pair = url.protocol === 'https:' ? httpsProxyEnv() : httpProxyEnv()
+  return pair ? parseProxy(pair.name, pair.value) : null
+}
+
+// Checked before the first request rather than at the moment one fails: a typo
+// in HTTPS_PROXY deserves one clear line at the top, not a connection error
+// wearing a configuration error's clothes.
+function assertProxyEnvUsable() {
+  for (const pair of [httpsProxyEnv(), httpProxyEnv()]) {
+    if (!pair) continue
+    try { parseProxy(pair.name, pair.value) } catch (err) { die(err.message) }
+  }
+}
+
+const hostOf = (rawUrl) => {
+  try { return new URL(rawUrl).host } catch { return 'the storage host' }
+}
+
+// Which egress a failed call took, in one clause appended to the error. The
+// old message ("fetch failed") sent a proxied partner to us; naming the proxy
+// sends them to their network team, which is where the answer lives.
+function egressHint(rawUrl, message = '') {
+  let url = null
+  try { url = new URL(rawUrl) } catch { return '' }
+  let proxy = null
+  try { proxy = proxyForUrl(url) } catch { return '' }
+  if (proxy) return message.includes(proxy.display) ? '' : ` — via proxy ${proxy.display}`
+  const port = Number(url.port || (url.protocol === 'https:' ? 443 : 80))
+  if (anyProxyEnv() && noProxyMatches(url.hostname, port)) {
+    return ` — connected directly: NO_PROXY excludes ${url.hostname}`
+  }
+  return ''
+}
+
+const directAgents = {
+  'http:': new http.Agent({ keepAlive: true }),
+  'https:': new https.Agent({ keepAlive: true }),
+}
+
+// CONNECT is where a misconfigured proxy hangs for ever — a blackholed SYN, or
+// a proxy that accepts the socket and then says nothing. Every other wait in
+// this file deliberately inherits fetch's "no timeout" (a 10 000-file
+// preflight legitimately takes minutes); a tunnel that has not opened in 30 s
+// is not opening.
+const TUNNEL_TIMEOUT_MS = 30_000
+
+function openTunnel(proxy, host, port) {
+  return new Promise((resolveSocket, reject) => {
+    const transport = proxy.protocol === 'https:' ? https : http
+    const req = transport.request({
+      host: proxy.hostname,
+      port: proxy.port,
+      method: 'CONNECT',
+      path: `${host}:${port}`,
+      agent: false,
+      headers: {
+        Host: `${host}:${port}`,
+        'User-Agent': UA,
+        ...(proxy.auth ? { 'Proxy-Authorization': `Basic ${proxy.auth}` } : {}),
+      },
+      ...(proxy.protocol === 'https:' ? { servername: proxy.hostname } : {}),
+    })
+    let settled = false
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      req.destroy()
+      reject(new Error(`proxy ${proxy.display} did not open a tunnel to ${host}:${port} within ${TUNNEL_TIMEOUT_MS / 1000}s`))
+    }, TUNNEL_TIMEOUT_MS)
+    timer.unref?.()
+    const settle = (fn) => (...a) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      fn(...a)
+    }
+    req.once('connect', settle((res, socket) => {
+      if (res.statusCode === 200) { resolveSocket(socket); return }
+      socket.destroy()
+      reject(new Error(
+        res.statusCode === 407
+          ? `proxy ${proxy.display} requires authentication (407) — put the credentials in the proxy URL (http://user:pass@host:port)`
+          : `proxy ${proxy.display} refused a tunnel to ${host}:${port} (HTTP ${res.statusCode})`,
+      ))
+    }))
+    // A proxy that answers CONNECT with an ordinary response — a captive
+    // portal, or an explicit proxy expecting absolute-form requests — is not
+    // going to tunnel anything. Say so rather than wait for the timeout.
+    req.once('response', settle((res) => {
+      res.resume()
+      reject(new Error(`proxy ${proxy.display} answered CONNECT with HTTP ${res.statusCode} instead of opening a tunnel to ${host}:${port}`))
+    }))
+    req.once('error', settle((err) => reject(new Error(`proxy ${proxy.display}: ${err.message}`))))
+    req.end()
+  })
+}
+
+// One tunnelling agent per proxy. keepAlive is OFF on this path on purpose: a
+// pooled socket here is a CONNECT tunnel the proxy may have torn down while it
+// sat idle, and the next part upload would then fail on a socket that still
+// looked healthy. One handshake per request, against a 64 MB part, is noise.
+class TunnelAgent extends https.Agent {
+  constructor(proxy) {
+    super({ keepAlive: false })
+    this.proxy = proxy
+  }
+  createConnection(options, cb) {
+    openTunnel(this.proxy, options.host, options.port).then(
+      (socket) => cb(null, tls.connect({ socket, servername: options.servername || options.host })),
+      (err) => cb(err),
+    )
+  }
+}
+const tunnelAgents = new Map()
+const tunnelAgentFor = (proxy) => {
+  const key = `${proxy.display} ${proxy.auth ?? ''}`
+  let agent = tunnelAgents.get(key)
+  if (!agent) {
+    agent = new TunnelAgent(proxy)
+    tunnelAgents.set(key, agent)
+  }
+  return agent
+}
+
+// Bodies: a string, a Buffer, or a FormData (the sandbox upload). Multipart is
+// not hand-rolled — `Response` is a global, so letting the platform encode the
+// FormData costs no dependency and cannot disagree with what a server expects.
+async function encodeBody(body) {
+  if (body == null) return { bytes: null, contentType: null }
+  if (typeof body === 'string') return { bytes: Buffer.from(body, 'utf8'), contentType: null }
+  if (Buffer.isBuffer(body)) return { bytes: body, contentType: null }
+  if (ArrayBuffer.isView(body)) return { bytes: Buffer.from(body.buffer, body.byteOffset, body.byteLength), contentType: null }
+  const encoded = new Response(body)
+  return { bytes: Buffer.from(await encoded.arrayBuffer()), contentType: encoded.headers.get('content-type') }
+}
+
+function decodeBody(raw, encoding) {
+  const enc = String(encoding ?? '').trim().toLowerCase()
+  try {
+    if (enc === 'gzip' || enc === 'x-gzip') return zlib.gunzipSync(raw).toString('utf8')
+    if (enc === 'br') return zlib.brotliDecompressSync(raw).toString('utf8')
+    if (enc === 'deflate') {
+      try { return zlib.inflateSync(raw).toString('utf8') } catch { return zlib.inflateRawSync(raw).toString('utf8') }
+    }
+  } catch {
+    // A body we cannot inflate is still worth showing raw — half an error
+    // message beats none.
+  }
+  return raw.toString('utf8')
+}
+
+// The whole HTTP surface of this CLI, in one function. It returns the small
+// slice of the fetch Response shape the rest of the file uses — `status`,
+// `headers.get()`, `json()`, `text()` — so the call sites read as they did.
+async function httpRequest(rawUrl, { method = 'GET', headers = {}, body } = {}, redirectsLeft = 5) {
+  const url = new URL(rawUrl)
+  const proxy = proxyForUrl(url)
+  const { bytes, contentType } = await encodeBody(body)
+
+  const sent = {}
+  for (const [k, v] of Object.entries(headers)) if (v != null) sent[k.toLowerCase()] = String(v)
+  sent['user-agent'] ??= UA
+  sent['accept-encoding'] ??= 'gzip, deflate, br'
+  if (bytes) {
+    // ⚠ Always a Content-Length, never chunked: S3 rejects a chunked PUT, and
+    // a presigned part upload is the one request here that must never be
+    // refused for a transport reason.
+    sent['content-length'] = String(bytes.length)
+    if (contentType && !sent['content-type']) sent['content-type'] = contentType
+  }
+
+  // https through a proxy is a CONNECT tunnel; plain http through a proxy is
+  // an absolute-form request line addressed to the proxy itself.
+  const tunnelled = Boolean(proxy) && url.protocol === 'https:'
+  const forwarded = Boolean(proxy) && url.protocol === 'http:'
+  if (forwarded) {
+    sent.host = url.host
+    if (proxy.auth) sent['proxy-authorization'] = `Basic ${proxy.auth}`
+  }
+  const transport = (forwarded ? proxy.protocol : url.protocol) === 'https:' ? https : http
+  const options = forwarded
+    ? { host: proxy.hostname, port: proxy.port, method, path: url.href, headers: sent, agent: directAgents[proxy.protocol] }
+    : {
+        host: url.hostname,
+        port: Number(url.port || (url.protocol === 'https:' ? 443 : 80)),
+        method,
+        path: `${url.pathname}${url.search}`,
+        headers: sent,
+        agent: tunnelled ? tunnelAgentFor(proxy) : directAgents[url.protocol],
+      }
+
+  return new Promise((settle, reject) => {
+    const req = transport.request(options, (res) => {
+      // 407 is a proxy's status, never an origin server's. On the forwarded
+      // path it arrives as an ordinary response, so without this the CLI
+      // reported it as though Myelin had answered — "[error] HTTP 407" and a
+      // partner reading it as our problem. The tunnel path already says this
+      // properly; both now do.
+      if (forwarded && res.statusCode === 407) {
+        res.resume()
+        reject(new Error(`proxy ${proxy.display} requires authentication (407) — put the credentials in the proxy URL (http://user:pass@host:port)`))
+        return
+      }
+      const location = res.headers.location
+      if (location && [301, 302, 303, 307, 308].includes(res.statusCode) && redirectsLeft > 0) {
+        res.resume()
+        let next = null
+        try { next = new URL(location, url) } catch { next = null }
+        if (next) {
+          const toGet = res.statusCode === 303 || ([301, 302].includes(res.statusCode) && method !== 'GET' && method !== 'HEAD')
+          const forward = {}
+          for (const [k, v] of Object.entries(headers)) {
+            // The rule fetch follows, and the one that matters here: a bearer
+            // token does not cross an origin. A front door that bounces us to
+            // an identity provider must never be handed the API key.
+            if (next.origin !== url.origin && k.toLowerCase() === 'authorization') continue
+            forward[k] = v
+          }
+          settle(httpRequest(next.href, { method: toGet ? 'GET' : method, headers: forward, body: toGet ? undefined : body }, redirectsLeft - 1))
+          return
+        }
+      }
+      const chunks = []
+      res.on('data', (c) => chunks.push(c))
+      res.on('error', reject)
+      res.on('end', () => {
+        const text = decodeBody(Buffer.concat(chunks), res.headers['content-encoding'])
+        settle({
+          status: res.statusCode,
+          headers: {
+            get: (name) => {
+              const v = res.headers[String(name).toLowerCase()]
+              return v == null ? null : Array.isArray(v) ? v.join(', ') : v
+            },
+          },
+          text: async () => text,
+          json: async () => JSON.parse(text),
+        })
+      })
+    })
+    req.once('error', reject)
+    if (bytes) req.end(bytes)
+    else req.end()
+  })
+}
+
 // 429s are handled HERE so every command inherits the platform's documented
 // contract (honour Retry-After): bounded — 4 waits, then the error surfaces
 // like any other. The wait is capped at 60 s so a pathological header cannot
 // stall a pipeline for an hour.
 async function api(method, path, body, raw) {
   for (let attempt = 1; ; attempt++) {
-    const res = await fetch(API_URL + path, {
+    const res = await httpRequest(API_URL + path, {
       method,
       headers: {
         ...EXTRA_HEADERS,
@@ -168,7 +576,7 @@ async function api(method, path, body, raw) {
         ...(body && !raw ? { 'Content-Type': 'application/json' } : {}),
       },
       body: raw ? body : body ? JSON.stringify(body) : undefined,
-    }).catch((err) => die(`Cannot reach ${API_URL}: ${err.message}`))
+    }).catch((err) => die(`Cannot reach ${API_URL}: ${err.message}${egressHint(API_URL, err.message)}`))
     let json = null
     try { json = await res.json() } catch { /* non-JSON body */ }
     const requestId = res.headers.get('myelin-request-id') ?? json?.request_id ?? null
@@ -452,10 +860,19 @@ async function uploadFileParts(absPath, size, fileId, partSize, adoptLandedGeome
           if (url === undefined) url = await resign(partNo, bytes)
           if (url === null) break // part landed server-side — resign() recorded its etag
           const startedAt = Date.now()
-          put = await fetch(url, { method: 'PUT', body: bytes }).catch(() => null)
+          let netErr = null
+          put = await httpRequest(url, { method: 'PUT', body: bytes }).catch((err) => { netErr = err; return null })
           if (put && put.status === 200) break
           const status = put ? put.status : 0
-          const reason = put ? `HTTP ${put.status}` : 'network error'
+          // ⚠ Never print `url` itself — a presigned URL carries its
+          // authorization in the query string. The HOST is the part a partner
+          // needs: a firewall or proxy that allows the API host and not the
+          // storage host is the commonest way a delivery dies, and the old
+          // bare "network error" sent them to look at Myelin instead of at
+          // their own egress.
+          const reason = put
+            ? `HTTP ${put.status}`
+            : `network error reaching ${hostOf(url)}${netErr ? ` (${netErr.message})` : ''}${egressHint(url, netErr?.message ?? '')}`
           if (isTimeoutClassFailure(status, Date.now() - startedAt)) {
             const strikes = (timeoutStrikes.get(partNo) ?? 0) + 1
             timeoutStrikes.set(partNo, strikes)
@@ -496,6 +913,11 @@ async function cmdPing() {
   const j = expectOk(await api('GET', '/ping'), 'ping')
   emit(j)
   out(`✓ key "${j.key.name}" (${j.key.prefix}…) · bridge ${j.bridge.name} · ${j.projects.length} project(s)`)
+  // The first question an IT department asks once a proxy is in play: is the
+  // CLI actually going through it? Printed only when one applies, so the
+  // ordinary output is unchanged.
+  const via = proxyForUrl(new URL(API_URL))
+  if (via) out(`  via proxy ${via.display}`)
 }
 
 async function cmdProjects() {
@@ -1041,6 +1463,8 @@ Setup:
   export MYELIN_API_URL=…                 (optional; default https://myelinbridge.com/api/v1)
   export MYELIN_API_HEADER="Name: value"  (optional; extra headers, one per line —
                                            for a gateway that authenticates ahead of Myelin)
+  export HTTPS_PROXY=http://proxy:8080    (optional; HTTP_PROXY / NO_PROXY honoured too,
+                                           either case — see README "For your IT department")
 
 Commands:
   ping                                    verify the key; show bridge + projects
@@ -1165,6 +1589,7 @@ const commands = {
 }
 try {
   if (!KEY) die('Set MYELIN_API_KEY (create a key in Bridge → API).')
+  assertProxyEnvUsable()
   const fn = commands[command]
   if (!fn) die(`Unknown command "${command}" — run: myelin help`)
   await fn()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myelinbridge/cli",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "Myelin Partner Ingestion CLI — push R&D data deliveries from a pipeline: preflight against the client's quality rules, resumable upload, submit, track review outcomes.",
   "type": "module",
   "bin": {