@amd-gaia/agent-ui 0.21.1 → 0.22.0

package/services/backend-installer.cjs

@@ -36,6 +36,8 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 const https = require("https");
+const http = require("http");
+const tls = require("tls");
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -75,25 +77,27 @@ const INSTALL_RETRY_BACKOFF_MS = 3000;
 // `curl | sh` path is retained only as an unpackaged-dev fallback so
 // contributors running from source keep working.
 //
-// When bumping uv, update BOTH:
+// When bumping uv, update:
 //   - .github/workflows/build-installers.yml (tarball .tar.gz SHA256 — archive)
-//   - BUNDLED_UV_SHA256 below (extracted ELF binary SHA256)
-// These are two different digests: the workflow verifies the downloaded
-// archive against upstream's published .sha256, then extracts the `uv` binary
-// which is what `ensureUv()` hashes at runtime.
+//   - BUNDLED_UV_SHA256 below (extracted binary SHA256, linux-x64/win-x64 only)
 //
-// Currently pinned: uv v0.5.14 linux-x64, mac-arm64.
-// (win-x64 deferred to a follow-up issue — its SHA must ship together with an
-// NSIS structural-smoke verifier, not on its own; see the #849 lesson.)
-//
-// IMPORTANT: per-platform SHA origin differs:
-//   - linux-x64:  raw extracted-from-tarball digest (no post-build modification).
-//   - mac-arm64:  POST-CODESIGN digest. electron-builder code-signs the bundled
-//                 uv during packaging, so this hash matches what ensureUv() sees
-//                 at runtime, NOT the upstream tarball. Bumping this pin means
-//                 running the CI build, then copying the SHA from the
-//                 dmg-structural-smoke failure message — never from `shasum`
-//                 against the freshly downloaded tarball.
+// IMPORTANT: per-platform verification strategy differs:
+//   - linux-x64 / win-x64: BUNDLED_UV_SHA256 pins the raw extracted-binary
+//     digest (no post-build modification) — deterministic across CI runs.
+//   - mac-arm64: NOT pinned here. electron-builder code-signs the bundled uv
+//     during packaging (ad-hoc `identity=-` when no Developer ID cert is
+//     configured, which is every CI build today), and ad-hoc codesign output
+//     depends on the codesign/Xcode toolchain baked into the GitHub-hosted
+//     `macos-latest` runner image — which floats and is NOT reproducible
+//     across CI runs (observed: macos-15-arm64 vs macos-26-arm64 images
+//     produced two different digests for byte-identical source). A fixed
+//     SHA256 pin is therefore not deterministic on macOS and would fail
+//     ~half of CI runs and brick first-launch on user machines whenever the
+//     runner image rolls. Instead, ensureUv() and the dmg-structural-smoke
+//     test both run `codesign --verify --strict` against the bundled binary
+//     — this validates the on-disk signature is intact/untampered without
+//     depending on the exact signing bytes, and still fails loud on
+//     corruption or an actually-invalid signature.
 const BUNDLED_UV_VERSION = "0.5.14";
 const BUNDLED_UV_SHA256 = {
   "linux-x64": "0e05d828b5708e8a927724124db3746396afddad6273c47283d7c562dc795bd6",
@@ -101,9 +105,12 @@ const BUNDLED_UV_SHA256 = {
   // build step. The placeholder MUST be replaced in CI before packaging
   // so runtime verification remains strict.
   "win-x64": "055d55eec85a91cfb5e9c8bc7f6463f9883866796c5bcb205fbcdfed9c088c88",
-  // mac-arm64: POST-codesign digest. CI should populate this value when
-  // packaging the macOS DMG and running the dmg-structural-smoke job.
-  "mac-arm64": "6099aa8cd701f0c81227ee30c304777ce151e4d47c53a75ce53cd2243448d8c8",
+  // mac-arm64: intentionally absent. See the comment block above — the
+  // post-codesign digest is not deterministic across CI runner images, so
+  // mac-arm64 is verified via codesignVerify() (identity/signature validity)
+  // instead of a fixed SHA256 pin. bundledUvPlatformKey() still returns
+  // "mac-arm64"; callers must not treat a missing entry here as "unpinned
+  // platform" for darwin — see ensureUv()/installBundledUv().
 };
 
 const MANAGED_UV_DIR = path.join(GAIA_HOME, "bin");
@@ -510,6 +517,27 @@ function isTransientNetworkError(output) {
   );
 }
 
+/**
+ * Detect a TLS trust failure in `uv pip install` output. Behind a corporate
+ * MITM proxy, PyPI is presented with a certificate signed by a custom root CA
+ * that uv's bundled webpki roots don't include, so uv reports
+ * "invalid peer certificate: UnknownIssuer" (issue #1693). It surfaces wrapped
+ * in "Failed to fetch" / "error sending request", so isTransientNetworkError
+ * also matches it — the install loop MUST check this first and retry with
+ * --native-tls (the OS trust store, where IT installs the corporate CA) rather
+ * than burning the transient retries on the same bundled roots.
+ */
+function isTlsCertError(output) {
+  if (!output) return false;
+  return (
+    /invalid peer certificate/i.test(output) ||
+    /unknownissuer/i.test(output) ||
+    /certificate verify failed/i.test(output) ||
+    /unable to get local issuer certificate/i.test(output) ||
+    /self[- ]signed certificate/i.test(output)
+  );
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -590,69 +618,234 @@ function checkDiskSpace() {
 }
 
 /**
- * Best-effort network reachability check. Performs a HEAD request to
- * https://astral.sh (where the uv installer lives). Resolves { ok, message? }.
+ * Read the OS trust store. Node 22+ exposes `tls.getCACertificates("system")`;
+ * older Node lacks it, so this returns `[]` there (callers fall back to
+ * NODE_EXTRA_CA_CERTS / the bundled Mozilla set).
+ *
+ * Why this exists: behind a corporate TLS-inspection proxy, the proxy's root
+ * CA is installed in the OS trust store but NOT in Node's bundled Mozilla set,
+ * so every HTTPS handshake fails with UNABLE_TO_GET_ISSUER_CERT_LOCALLY and the
+ * machine looks "offline" when it is online (issue #1572).
+ */
+function _systemCaCertificates() {
+  try {
+    if (typeof tls.getCACertificates === "function") {
+      return tls.getCACertificates("system") || [];
+    }
+  } catch (err) {
+    log(`Could not read system CA store: ${err.message}`);
+  }
+  return [];
+}
+
+/** Read a pinned corporate root CA from NODE_EXTRA_CA_CERTS (any Node version). */
+function _extraCaCertificates() {
+  const file = process.env.NODE_EXTRA_CA_CERTS;
+  if (!file) return [];
+  try {
+    return [fs.readFileSync(file, "utf8")];
+  } catch (err) {
+    log(`Could not read NODE_EXTRA_CA_CERTS (${file}): ${err.message}`);
+    return [];
+  }
+}
+
+/**
+ * Build the CA trust bundle for the network probe. Passing `ca` to
+ * `https.request` REPLACES Node's default trust store, so when we add system /
+ * extra certs we must re-include the bundled Mozilla set. Returns `undefined`
+ * when there is nothing extra to add (probe uses Node's default trust store —
+ * behaviour unchanged).
+ */
+function buildCaBundle() {
+  const extra = [..._systemCaCertificates(), ..._extraCaCertificates()];
+  if (extra.length === 0) return undefined;
+  return [...new Set([...tls.rootCertificates, ...extra])];
+}
+
+/** First non-empty proxy URL from the standard env vars, or null. */
+function proxyForHttps() {
+  return (
+    process.env.HTTPS_PROXY ||
+    process.env.https_proxy ||
+    process.env.HTTP_PROXY ||
+    process.env.http_proxy ||
+    null
+  );
+}
+
+/**
+ * Classify a network error so the caller can tell a trust-store gap (NOT
+ * offline) apart from genuine connectivity loss.
+ *   - "tls"          → certificate/handshake failure (machine is online)
+ *   - "timeout"      → request timed out
+ *   - "connectivity" → DNS/connect failure (likely offline)
+ */
+function classifyNetworkError(err) {
+  const code = (err && err.code) || "";
+  const message = (err && err.message) || "";
+  if (/CERT|SELF_SIGNED|UNABLE_TO_|_SIGNATURE|ALTNAME/.test(code)) {
+    return "tls";
+  }
+  if (code === "ETIMEDOUT" || /timed out/i.test(message)) {
+    return "timeout";
+  }
+  return "connectivity";
+}
+
+/** HEAD-probe `target` (a URL) directly, trusting `ca`. */
+function _probeDirect(target, ca, finish, setSock) {
+  const opts = {
+    host: target.hostname,
+    port: target.port || 443,
+    path: target.pathname || "/",
+    method: "HEAD",
+    servername: target.hostname,
+    headers: { "User-Agent": "gaia-backend-installer/1.0" },
+  };
+  if (ca) opts.ca = ca;
+  try {
+    const req = https.request(opts, (res) => {
+      res.resume();
+      finish({ ok: true, status: res.statusCode });
+    });
+    setSock(req);
+    req.on("error", (err) =>
+      finish({ ok: false, kind: classifyNetworkError(err), message: `${target.href}: ${err.message}` })
+    );
+    req.end();
+  } catch (err) {
+    finish({ ok: false, kind: classifyNetworkError(err), message: `${target.href}: ${err.message}` });
+  }
+}
+
+/** HEAD-probe `target` through an HTTP CONNECT proxy, trusting `ca`. */
+function _probeViaProxy(target, proxy, ca, finish, setSock) {
+  let proxyUrl;
+  try {
+    proxyUrl = new URL(proxy);
+  } catch {
+    finish({ ok: false, kind: "connectivity", message: `${target.href}: invalid proxy URL "${proxy}"` });
+    return;
+  }
+  const headers = {};
+  if (proxyUrl.username) {
+    const cred = `${decodeURIComponent(proxyUrl.username)}:${decodeURIComponent(proxyUrl.password)}`;
+    headers["Proxy-Authorization"] = "Basic " + Buffer.from(cred).toString("base64");
+  }
+  const connectReq = http.request({
+    host: proxyUrl.hostname,
+    port: proxyUrl.port || 80,
+    method: "CONNECT",
+    path: `${target.hostname}:${target.port || 443}`,
+    headers,
+  });
+  setSock(connectReq);
+  connectReq.on("connect", (res, socket) => {
+    if (res.statusCode !== 200) {
+      try { socket.destroy(); } catch { /* ignore */ }
+      finish({ ok: false, kind: "connectivity", message: `${target.href}: proxy CONNECT returned ${res.statusCode}` });
+      return;
+    }
+    setSock(socket);
+    const opts = {
+      host: target.hostname,
+      port: target.port || 443,
+      path: target.pathname || "/",
+      method: "HEAD",
+      socket,
+      agent: false,
+      servername: target.hostname,
+      headers: { "User-Agent": "gaia-backend-installer/1.0" },
+    };
+    if (ca) opts.ca = ca;
+    try {
+      const req = https.request(opts, (r) => {
+        r.resume();
+        finish({ ok: true, status: r.statusCode });
+      });
+      req.on("error", (err) =>
+        finish({ ok: false, kind: classifyNetworkError(err), message: `${target.href}: ${err.message}` })
+      );
+      req.end();
+    } catch (err) {
+      finish({ ok: false, kind: classifyNetworkError(err), message: `${target.href}: ${err.message}` });
+    }
+  });
+  connectReq.on("error", (err) =>
+    finish({ ok: false, kind: classifyNetworkError(err), message: `${target.href}: ${err.message}` })
+  );
+  connectReq.end();
+}
+
+/**
+ * Best-effort reachability probe for a single host. A HEAD that gets any
+ * response (even 3xx/4xx) proves connectivity. Trusts the system / pinned CA
+ * store (issue #1572) and honors HTTPS_PROXY/HTTP_PROXY. Resolves
+ * { ok, status? } or { ok:false, kind, message }.
  */
 function _checkOneHost(url) {
   return new Promise((resolve) => {
     let settled = false;
+    let sock = null;
+    let timer = null;
     const finish = (result) => {
       if (settled) return;
       settled = true;
+      if (timer) clearTimeout(timer);
+      if (sock) {
+        try { sock.destroy(); } catch { /* ignore */ }
+      }
       resolve(result);
     };
-
-    try {
-      const req = https.request(
-        url,
-        {
-          method: "HEAD",
-          timeout: NETWORK_CHECK_TIMEOUT_MS,
-          headers: { "User-Agent": "gaia-backend-installer/1.0" },
-        },
-        (res) => {
-          // Any response (even 3xx/4xx) means we have basic connectivity.
-          res.resume();
-          finish({ ok: true, status: res.statusCode });
-        }
-      );
-      req.on("timeout", () => {
-        req.destroy();
-        finish({
-          ok: false,
-          message: `${url}: timed out after ${NETWORK_CHECK_TIMEOUT_MS / 1000}s`,
-        });
-      });
-      req.on("error", (err) => {
-        finish({
-          ok: false,
-          message: `${url}: ${err.message}`,
-        });
-      });
-      req.end();
-    } catch (err) {
+    const setSock = (s) => {
+      sock = s;
+    };
+    timer = setTimeout(() => {
       finish({
         ok: false,
-        message: `${url}: ${err.message}`,
+        kind: "timeout",
+        message: `${url}: timed out after ${NETWORK_CHECK_TIMEOUT_MS / 1000}s`,
       });
+    }, NETWORK_CHECK_TIMEOUT_MS);
+
+    let target;
+    try {
+      target = new URL(url);
+    } catch (err) {
+      finish({ ok: false, kind: "connectivity", message: `${url}: ${err.message}` });
+      return;
+    }
+    const ca = buildCaBundle();
+    const proxy = proxyForHttps();
+    if (proxy) {
+      _probeViaProxy(target, proxy, ca, finish, setSock);
+    } else {
+      _probeDirect(target, ca, finish, setSock);
     }
   });
 }
 
 /**
- * Probe each host in ``NETWORK_CHECK_HOSTS`` sequentially. Succeed as
- * soon as ANY host responds (even 3xx/4xx counts — it proves
- * connectivity). Only fail if ALL hosts are unreachable.
+ * Probe each host in ``NETWORK_CHECK_HOSTS`` sequentially. Succeed as soon as
+ * ANY host responds (even 3xx/4xx counts — it proves connectivity). On total
+ * failure, report the dominant failure `kind` so the caller can distinguish a
+ * trust-store gap ("tls" — online but Node doesn't trust the proxy CA) from a
+ * genuine outage ("connectivity").
  */
 async function checkNetwork() {
   const errors = [];
+  const kinds = new Set();
   for (const url of NETWORK_CHECK_HOSTS) {
     const result = await _checkOneHost(url);
-    if (result.ok) return result;
+    if (result.ok) return { ok: true, status: result.status };
     errors.push(result.message);
+    kinds.add(result.kind || "connectivity");
   }
+  const allTls = kinds.size > 0 && [...kinds].every((k) => k === "tls");
   return {
     ok: false,
+    kind: allTls ? "tls" : kinds.has("connectivity") ? "connectivity" : [...kinds][0] || "connectivity",
     message: `Network check failed for all hosts: ${errors.join("; ")}`,
   };
 }
@@ -736,6 +929,27 @@ function sha256File(filePath) {
   });
 }
 
+/**
+ * Verify a macOS binary's code signature is structurally intact via
+ * `codesign --verify --strict`. Used in place of a fixed SHA256 pin for
+ * mac-arm64 (see the BUNDLED_UV_SHA256 comment) — ad-hoc-signed binaries
+ * (identity=-, which is every CI build today) pass this check, but a
+ * corrupted, tampered, or actually-unsigned binary fails it. This does NOT
+ * depend on the specific bytes any given codesign/Xcode toolchain produces,
+ * so it is stable across GitHub-hosted runner image rollovers where a fixed
+ * digest pin is not.
+ *
+ * @param {string} binPath
+ * @returns {{ ok: boolean, output: string }}
+ */
+function codesignVerify(binPath) {
+  const result = spawnSync("codesign", ["--verify", "--strict", binPath], {
+    encoding: "utf8",
+  });
+  const output = `${result.stdout || ""}${result.stderr || ""}`.trim();
+  return { ok: result.status === 0, output };
+}
+
 /**
  * Resolve the bundled uv binary path inside the Electron resources dir.
  * Returns null if this isn't an Electron-packaged runtime (no
@@ -757,15 +971,22 @@ function findBundledUvResource() {
 }
 
 /**
- * Atomically install the bundled uv into ~/.gaia/bin/uv after verifying
- * its SHA256 against BUNDLED_UV_SHA256. Returns the installed path.
+ * Atomically install the bundled uv into ~/.gaia/bin/uv after verifying it.
+ * Returns the installed path.
+ *
+ * Verification strategy differs by platform (see the BUNDLED_UV_SHA256
+ * comment): mac-arm64 uses `codesign --verify --strict` (darwin only —
+ * post-codesign SHA256 is not deterministic across CI runner images);
+ * linux-x64 / win-x64 use the SHA256 pin in BUNDLED_UV_SHA256, which IS
+ * deterministic for those platforms (no post-build re-signing).
  *
- * Writes to `uv.tmp-<pid>-<rand>` with mode 0o700, verifies hash,
- * `chmod +x`, then `fs.rename()` (atomic on same filesystem).
+ * Writes to `uv.tmp-<pid>-<rand>` with mode 0o700, verifies, `chmod +x`,
+ * then `fs.rename()` (atomic on same filesystem).
  */
 async function installBundledUv(sourcePath, platformKey) {
+  const isDarwin = platformKey === "mac-arm64";
   const expected = BUNDLED_UV_SHA256[platformKey];
-  if (!expected || expected.startsWith("<")) {
+  if (!isDarwin && (!expected || expected.startsWith("<"))) {
     // Enforce strict verification: builds MUST populate the expected SHA
     // for packaged binaries. Failing fast prevents shipping an unverified
     // uv binary which would be a supply-chain regression.
@@ -801,18 +1022,39 @@ async function installBundledUv(sourcePath, platformKey) {
     rs.pipe(ws);
   });
 
-  let actual;
-  try {
-    actual = await sha256File(tmpPath);
-  } catch (err) {
-    try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
-    throw new InstallError(
-      `Could not hash copied uv binary: ${err.message}`,
-      { stage: STAGES.ENSURE_UV }
-    );
-  }
+  if (isDarwin) {
+    // chmod BEFORE codesign --verify: codesign needs the execute bit to
+    // resolve the binary's designated requirement on some toolchains.
+    try {
+      fs.chmodSync(tmpPath, 0o700);
+    } catch (err) {
+      log(`Warning: chmod on tmp uv failed: ${err.message}`);
+    }
+    const { ok, output } = codesignVerify(tmpPath);
+    if (!ok) {
+      try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+      throw new InstallError(
+        `Bundled uv failed code signature verification (codesign --verify --strict): ${output || "no output"}`,
+        {
+          stage: STAGES.ENSURE_UV,
+          suggestion:
+            "The AppImage/installer may be corrupt. Re-download from https://amd-gaia.ai and try again.",
+        }
+      );
+    }
+    log("Bundled uv passed codesign --verify --strict");
+  } else {
+    let actual;
+    try {
+      actual = await sha256File(tmpPath);
+    } catch (err) {
+      try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+      throw new InstallError(
+        `Could not hash copied uv binary: ${err.message}`,
+        { stage: STAGES.ENSURE_UV }
+      );
+    }
 
-  if (expected) {
     if (actual !== expected) {
       try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
       throw new InstallError(
@@ -824,14 +1066,12 @@ async function installBundledUv(sourcePath, platformKey) {
         }
       );
     }
-  } else {
-    log("No expected SHA registered for bundled uv; installed binary will not be verified locally.");
-  }
 
-  try {
-    if (!IS_WINDOWS) fs.chmodSync(tmpPath, 0o700);
-  } catch (err) {
-    log(`Warning: chmod on tmp uv failed: ${err.message}`);
+    try {
+      if (!IS_WINDOWS) fs.chmodSync(tmpPath, 0o700);
+    } catch (err) {
+      log(`Warning: chmod on tmp uv failed: ${err.message}`);
+    }
   }
 
   try {
@@ -869,9 +1109,11 @@ function addManagedBinToPath() {
 
 /**
  * Ensure `uv` is available. Preference order (per issue #782 / T3):
- *   1. Managed copy at ~/.gaia/bin/uv with matching SHA256 (warm-install fast path).
+ *   1. Managed copy at ~/.gaia/bin/uv already verified (warm-install fast path):
+ *      SHA256 pin on linux-x64/win-x64, `codesign --verify --strict` on mac-arm64.
  *   2. Bundled binary in process.resourcesPath/vendor/uv/<platform>/uv:
- *      copy atomically to ~/.gaia/bin/uv with SHA256 verification.
+ *      copy atomically to ~/.gaia/bin/uv with the same platform-appropriate
+ *      verification.
  *   3. DEV-ONLY fallback (app.isPackaged === false OR no resourcesPath):
  *      the original `curl | sh` from astral.sh. Not a shipped-user path.
  *   4. System `uv` on PATH (last resort — unverified version).
@@ -883,10 +1125,20 @@ async function ensureUv({ onProgress, isPackaged } = {}) {
   report(STAGES.ENSURE_UV, 0, "Checking uv (Python package manager)");
 
   const platformKey = bundledUvPlatformKey();
+  const isDarwin = platformKey === "mac-arm64";
   const expectedSha = platformKey ? BUNDLED_UV_SHA256[platformKey] : null;
 
-  // Fast path: warm install already on disk with correct hash.
-  if (expectedSha && fs.existsSync(MANAGED_UV_BIN)) {
+  // Fast path: warm install already on disk and still passes verification.
+  if (isDarwin && fs.existsSync(MANAGED_UV_BIN)) {
+    const { ok, output } = codesignVerify(MANAGED_UV_BIN);
+    if (ok) {
+      log(`Managed uv at ${MANAGED_UV_BIN} passed codesign --verify --strict — reusing`);
+      addManagedBinToPath();
+      report(STAGES.ENSURE_UV, 100, "uv ready (cached)");
+      return;
+    }
+    log(`Managed uv failed codesign verification (${output || "no output"}) — replacing`);
+  } else if (expectedSha && fs.existsSync(MANAGED_UV_BIN)) {
     try {
       const actual = await sha256File(MANAGED_UV_BIN);
       if (actual === expectedSha) {
@@ -909,22 +1161,36 @@ async function ensureUv({ onProgress, isPackaged } = {}) {
     report(STAGES.ENSURE_UV, 30, "Installing bundled uv");
     log(`Using bundled uv from ${bundled}`);
 
-    // Verify the source resource matches the manifest before copying —
-    // catches AppImage corruption before we touch the user's home.
-    // Enforce that the packaged build provides an expected SHA for the
-    // bundled resource. CI replaces the placeholder with the extracted
-    // binary's SHA during the build; missing/placeholder values are a
-    // build-time error and are rejected at runtime here.
-    const srcHash = await sha256File(bundled);
-    if (srcHash !== expectedSha) {
-      throw new InstallError(
-        `Bundled uv resource SHA256 mismatch (expected ${expectedSha}, got ${srcHash}).`,
-        {
-          stage: STAGES.ENSURE_UV,
-          suggestion:
-            "The installer appears to be corrupt. Re-download GAIA from https://amd-gaia.ai and try again.",
-        }
-      );
+    // Verify the source resource before copying — catches installer
+    // corruption before we touch the user's home. mac-arm64 uses
+    // codesign --verify --strict (see BUNDLED_UV_SHA256 comment for why a
+    // fixed digest isn't viable there); other platforms use the SHA256 pin,
+    // which CI must have populated — a missing/placeholder value is a
+    // build-time error, rejected at runtime here.
+    if (isDarwin) {
+      const { ok, output } = codesignVerify(bundled);
+      if (!ok) {
+        throw new InstallError(
+          `Bundled uv resource failed code signature verification (codesign --verify --strict): ${output || "no output"}`,
+          {
+            stage: STAGES.ENSURE_UV,
+            suggestion:
+              "The installer appears to be corrupt. Re-download GAIA from https://amd-gaia.ai and try again.",
+          }
+        );
+      }
+    } else {
+      const srcHash = await sha256File(bundled);
+      if (srcHash !== expectedSha) {
+        throw new InstallError(
+          `Bundled uv resource SHA256 mismatch (expected ${expectedSha}, got ${srcHash}).`,
+          {
+            stage: STAGES.ENSURE_UV,
+            suggestion:
+              "The installer appears to be corrupt. Re-download GAIA from https://amd-gaia.ai and try again.",
+          }
+        );
+      }
     }
     await installBundledUv(bundled, platformKey);
     addManagedBinToPath();
@@ -1198,10 +1464,38 @@ async function installBackend(opts = {}) {
   // would otherwise fail the whole bootstrap (and block a release). File-lock
   // failures (Windows os-error-32) are NOT retried — they need user action.
   let installResult;
-  for (let attempt = 1; attempt <= INSTALL_MAX_ATTEMPTS; attempt++) {
-    installResult = await runCommand("uv", pipArgs, { stageLabel: "pip" });
+  let useNativeTls = false;
+  let nativeTlsAttempted = false;
+  // The TLS branch flips useNativeTls and `continue`s, consuming an iteration.
+  // If the signature only surfaces on the final attempt, extend the loop once
+  // so the promised --native-tls retry actually runs (issue #1693 review).
+  for (
+    let attempt = 1;
+    attempt <= INSTALL_MAX_ATTEMPTS || (useNativeTls && !nativeTlsAttempted);
+    attempt++
+  ) {
+    const attemptArgs = useNativeTls ? [...pipArgs, "--native-tls"] : pipArgs;
+    if (useNativeTls) nativeTlsAttempted = true;
+    installResult = await runCommand("uv", attemptArgs, { stageLabel: "pip" });
     if (installResult.code === 0) break;
     const attemptOutput = `${installResult.stdout || ""}\n${installResult.stderr || ""}`;
+    // A corporate proxy's custom root CA isn't in uv's bundled webpki roots, so
+    // the fetch fails with UnknownIssuer. This LOOKS transient ("Failed to
+    // fetch") but retrying the bundled roots can't fix it — retry once with
+    // --native-tls so uv trusts the OS certificate store instead (issue #1693).
+    if (!useNativeTls && isTlsCertError(attemptOutput)) {
+      useNativeTls = true;
+      log(
+        "TLS trust failure (corporate proxy CA not in uv's bundled roots) — " +
+          "retrying install with --native-tls to use the OS certificate store"
+      );
+      report(
+        STAGES.INSTALL_PACKAGE,
+        0,
+        "Certificate trust issue — retrying with the system certificate store"
+      );
+      continue;
+    }
     const canRetry =
       attempt < INSTALL_MAX_ATTEMPTS &&
       isTransientNetworkError(attemptOutput) &&
@@ -1225,11 +1519,23 @@ async function installBackend(opts = {}) {
     // main.cjs should have killed it first; if the lock persists, point the
     // user at the live process rather than the generic manual-install hint.
     const output = `${installResult.stdout || ""}\n${installResult.stderr || ""}`;
-    const suggestion = isFileLockedError(output)
-      ? "A running GAIA process is locking the install. Close GAIA completely (including any leftover gaia.exe in Task Manager), then relaunch."
-      : `Try installing manually:\n  uv pip install ${pipPackage} --python ${
-          IS_WINDOWS ? `${GAIA_VENV_DISPLAY}/Scripts/python.exe` : `${GAIA_VENV_DISPLAY}/bin/python`
-        }\nThen restart GAIA. See https://amd-gaia.ai/quickstart#cli-install`;
+    let suggestion;
+    if (isFileLockedError(output)) {
+      suggestion =
+        "A running GAIA process is locking the install. Close GAIA completely (including any leftover gaia.exe in Task Manager), then relaunch.";
+    } else if (isTlsCertError(output)) {
+      suggestion =
+        "PyPI's certificate isn't trusted on this network — usually a corporate proxy presenting its own root CA. " +
+        (nativeTlsAttempted
+          ? "GAIA retried with the OS certificate store and it still failed. "
+          : "") +
+        "Ask IT to install the proxy's root CA in your system's trusted certificate store, then relaunch GAIA. " +
+        "See https://amd-gaia.ai/quickstart#cli-install";
+    } else {
+      suggestion = `Try installing manually:\n  uv pip install ${pipPackage} --python ${
+        IS_WINDOWS ? `${GAIA_VENV_DISPLAY}/Scripts/python.exe` : `${GAIA_VENV_DISPLAY}/bin/python`
+      }\nThen restart GAIA. See https://amd-gaia.ai/quickstart#cli-install`;
+    }
     throw new InstallError(
       `Failed to install ${pipPackage} (pip exit ${installResult.code}).`,
       {
@@ -1426,18 +1732,25 @@ async function ensureBackend(opts = {}) {
       throw err;
     }
 
-    // Network check failure: fatal, surface as InstallError.
+    // Network check is ADVISORY, never fatal. A failed HEAD probe is most often
+    // a corporate TLS-inspection proxy whose root CA isn't in Node's bundled
+    // trust store (#1572) — the machine is online and `uv`/`pip`, which honor
+    // HTTPS_PROXY and the system trust store, install fine. If the host really
+    // is unreachable, the install step below fails loudly with an accurate
+    // uv/pip error, which is more actionable than a generic "offline".
     if (!preChecks.network.ok) {
-      const err = new InstallError(
-        `You appear to be offline. ${preChecks.network.message || "Could not reach any network host."}`,
-        {
-          stage: STAGES.PRE_CHECKS,
-          suggestion:
-            "Connect to the internet and try again. If you are behind a corporate proxy, configure HTTPS_PROXY and re-launch GAIA.",
-        }
-      );
-      setState(STATES.FAILED, { stage: STAGES.PRE_CHECKS, message: err.message });
-      throw err;
+      if (preChecks.network.kind === "tls") {
+        log(
+          `Network pre-check hit a TLS/certificate error (not offline): ${preChecks.network.message}. ` +
+            "Typically a corporate proxy root CA missing from Node's trust store — " +
+            "set NODE_EXTRA_CA_CERTS to it (or relaunch with --use-system-ca) if the install fails. Proceeding."
+        );
+      } else {
+        log(
+          `Network pre-check could not reach any host: ${preChecks.network.message}. ` +
+            "Proceeding anyway; the install step will surface an accurate error if the network is truly unreachable."
+        );
+      }
     }
 
     // Fast-path: already installed at the expected version.
@@ -1521,6 +1834,11 @@ module.exports = {
   checkNetwork,
   isFileLockedError,
   isTransientNetworkError,
+  isTlsCertError,
+  buildCaBundle,
+  proxyForHttps,
+  classifyNetworkError,
+  _checkOneHost,
 
   // State machine
   getState,