fix(webui): verify mac-arm64 bundled uv via codesign, not a SHA256 pin

The BUNDLED_UV_SHA256["mac-arm64"] pin captured a post-codesign digest,
but electron-builder ad-hoc-signs the bundled uv on every CI build (no
Developer ID cert configured), and ad-hoc codesign output depends on the
codesign/Xcode toolchain baked into the GitHub-hosted macos-latest runner
image. That image floats between macos-15-arm64 and macos-26-arm64,
producing two different digests for byte-identical source — confirmed
across dmg-structural-smoke runs on PRs #1861, #1886, and #1926. A fixed
pin is therefore not deterministic on macOS: it fails roughly half of CI
runs, and a shipped DMG whose signing output mismatches the baked-in pin
would hard-fail ensureUv() on a user's first launch.

Replace the fixed digest with `codesign --verify --strict` in both
ensureUv() (runtime) and the dmg-structural-smoke helper (CI), matching
the check to what's actually deterministic: the signature's structural
validity, not its exact bytes. Ad-hoc signatures pass this check;
tampered or corrupted binaries still fail it, preserving the fail-loud
guarantee. linux-x64/win-x64 keep their existing SHA256 pins, which are
genuinely deterministic there (no post-build re-signing).

Author: Tomasz Iniewicz

.github/workflows/build-installers.yml

@@ -299,9 +299,14 @@ jobs:
           cp "${tmpdir}/uv-aarch64-apple-darwin/uv" "${DEST_DIR}/uv"
           chmod 0755 "${DEST_DIR}/uv"
           "${DEST_DIR}/uv" --version
-          # Echo the extracted-binary SHA (pre-codesign). To bump the
-          # runtime's POST-codesign digest (BUNDLED_UV_SHA256[mac-arm64]),
-          # run CI and copy the value from the dmg-structural-smoke output.
+          # Echo the extracted-binary SHA (pre-codesign) for build logs only —
+          # there is no runtime pin to update for mac-arm64. Unlike
+          # linux-x64/win-x64, mac-arm64's BUNDLED_UV_SHA256 entry was removed:
+          # electron-builder re-signs this binary during packaging (ad-hoc
+          # identity=- on every CI build today), and ad-hoc codesign output is
+          # not deterministic across GitHub-hosted macos-latest runner image
+          # rollovers. ensureUv() and dmg-structural-smoke both verify this
+          # binary via `codesign --verify --strict` instead of a fixed digest.
           shasum -a 256 "${DEST_DIR}/uv"
 
       - name: Build frontend (Vite)
@@ -762,8 +767,12 @@ jobs:
   # Mirrors appimage-structural-smoke for the macOS DMG. Catches the
   # failure mode that bit v0.17.5: a darwin-arm64 install that hard-fails
   # in ensure-uv on first launch because the bundled uv either was never
-  # shipped or has the wrong SHA256 against BUNDLED_UV_SHA256[mac-arm64]
-  # in backend-installer.cjs.
+  # shipped or fails `codesign --verify --strict` in backend-installer.cjs.
+  # (Prior to the mac-arm64 pin removal, this compared against a fixed
+  # BUNDLED_UV_SHA256[mac-arm64] digest — retired because ad-hoc codesign
+  # output is not deterministic across GitHub-hosted macos-latest runner
+  # image rollovers; see the BUNDLED_UV_SHA256 comment in
+  # backend-installer.cjs.)
   #
   # MUST be present in build-complete `needs:` below — without that
   # wiring, a failing DMG smoke does not block release-readiness.
@@ -793,7 +802,7 @@ jobs:
           echo "Found DMG: ${DMG}"
           echo "dmg=${DMG}" >> "$GITHUB_OUTPUT"
 
-      - name: Structural smoke (uv binary, mode, sha256, --version)
+      - name: Structural smoke (uv binary, mode, codesign, --version)
         env:
           GAIA_DMG: ${{ steps.locate.outputs.dmg }}
         run: node --test tests/electron/dmg-smoke.test.mjs

src/gaia/apps/webui/services/backend-installer.cjs

@@ -77,35 +77,40 @@ 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",
   // The Windows extracted uv.exe SHA is populated by CI during the
   // 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");
@@ -924,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
@@ -945,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.
  *
- * Writes to `uv.tmp-<pid>-<rand>` with mode 0o700, verifies hash,
- * `chmod +x`, then `fs.rename()` (atomic on same filesystem).
+ * 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, `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.
@@ -989,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(
@@ -1012,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 {
@@ -1057,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).
@@ -1071,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) {
@@ -1097,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();

tests/electron/_helpers/installer-smoke.mjs

@@ -7,7 +7,10 @@
 //   1. The in-resources path layout for the bundled `uv` binary
 //      (mirrors electron-builder.yml `extraResources.to: vendor/uv`).
 //   2. Parsing BUNDLED_UV_SHA256 out of backend-installer.cjs.
-//   3. The full existence + executable-bit + SHA256 check.
+//   3. The full existence + executable-bit + verification check — SHA256
+//      pin on linux-x64/win-x64, `codesign --verify --strict` on mac-arm64
+//      (see the BUNDLED_UV_SHA256 comment in backend-installer.cjs for why
+//      mac-arm64 cannot use a fixed digest pin).
 //
 // Consumed by tests/electron/appimage-smoke.test.mjs and
 // tests/electron/dmg-smoke.test.mjs. A future NSIS smoke test should
@@ -18,6 +21,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
 
 // Mirrors electron-builder.yml `extraResources.to: vendor/uv` — the single
 // source of truth for the in-resources layout. If electron-builder.yml
@@ -69,12 +73,16 @@ export function parseBundledUvSha(installerCjsPath, platformKey) {
 }
 
 /**
- * Existence + executable-bit (POSIX only) + SHA256-vs-pin check.
+ * Existence + executable-bit (POSIX only) + verification check.
  *
- * Catches the failure mode that bit issue #849 and motivated #941:
- * a packaged binary whose SHA does not match the pin in
- * BUNDLED_UV_SHA256, which `ensureUv()` would reject at runtime with
- * a hard SHA256 mismatch error on the user's first launch.
+ * mac-arm64 verifies via `codesign --verify --strict` — matching
+ * ensureUv()'s runtime check (see the BUNDLED_UV_SHA256 comment in
+ * backend-installer.cjs: ad-hoc codesign output is not deterministic
+ * across CI runner images, so mac-arm64 has no fixed digest to pin
+ * against). Other platforms compare SHA256 against the pin in
+ * BUNDLED_UV_SHA256, catching the failure mode that bit issue #849 and
+ * motivated #941: a packaged binary whose SHA does not match the pin,
+ * which `ensureUv()` would reject at runtime on the user's first launch.
  *
  * @param {string} uvPath              absolute path to packaged `uv` binary
  * @param {string} platformKey         e.g. "mac-arm64"
@@ -91,6 +99,21 @@ export function assertUvBinary(uvPath, platformKey, installerCjsPath) {
       `uv binary should be executable; mode=${(st.mode & 0o777).toString(8)}`,
     );
   }
+
+  if (platformKey === "mac-arm64") {
+    const result = spawnSync("codesign", ["--verify", "--strict", uvPath], {
+      encoding: "utf8",
+    });
+    const output = `${result.stdout || ""}${result.stderr || ""}`.trim();
+    assert.equal(
+      result.status,
+      0,
+      `bundled mac-arm64 uv failed \`codesign --verify --strict\`; ` +
+        `ensureUv() will reject this at runtime. Output: ${output || "(none)"}`,
+    );
+    return;
+  }
+
   const expected = parseBundledUvSha(installerCjsPath, platformKey);
   const actual = crypto
     .createHash("sha256")