Enhance macOS build scripts with keychain management and error handling

This commit introduces functions to ensure the System keychains are included in the user keychain search list, addressing common codesigning errors related to keychain trust chains. Additionally, it adds preflight checks for codesigning and installer identities, improving error reporting and guidance for developers. The README_MAS.md is updated to include troubleshooting steps for keychain-related issues, enhancing the overall usability of the macOS build process.

build_tools/macos/README_MAS.md

@@ -80,6 +80,24 @@ If there’s no private key under the certificate, it will not be usable for sig
 
 ## Step 4 — Verify identities from the CLI
 
+### Common failure: errSecInternalComponent / chain-to-root warnings
+
+If you see errors like:
+
+- `Warning: unable to build chain to self-signed root for signer "Apple Distribution: ..."`
+- `errSecInternalComponent`
+
+This is almost always a **keychain search list / trust chain** issue.
+
+Fix (safe, common): ensure the System keychains are included in the user search list:
+
+```bash
+security list-keychains -d user
+security list-keychains -d user -s   "$HOME/Library/Keychains/login.keychain-db"   "/Library/Keychains/System.keychain"   "/System/Library/Keychains/SystemRootCertificates.keychain"
+```
+
+Then re-run the build/sign script.
+
 ```bash
 security find-identity -p codesigning -v
 security find-identity -p basic -v

build_tools/macos/build_mas_pkg.sh

@@ -146,6 +146,42 @@ fi
 echo "==> [$(ts)] Embedding provisioning profile"
 cp -f "$provisionprofile" "${app_path}/Contents/embedded.provisionprofile"
 
+ensure_keychain_search_list
+preflight_identity "codesign" "-p codesigning" "$codesign_identity"
+preflight_identity "installer" "-p basic" "$installer_identity"
+
+ensure_keychain_search_list() {
+  # codesign builds the cert chain using the user keychain search list.
+  # If the list is missing the System keychain, you can get:
+  #   "unable to build chain to self-signed root" + errSecInternalComponent
+  local login_kc="$HOME/Library/Keychains/login.keychain-db"
+  local system_kc="/Library/Keychains/System.keychain"
+  local roots_kc="/System/Library/Keychains/SystemRootCertificates.keychain"
+
+  local current
+  current="$(security list-keychains -d user 2>/dev/null | tr -d '"' | tr -d '	' || true)"
+
+  if echo "$current" | grep -Fq "$system_kc"; then
+    return 0
+  fi
+
+  echo "==> [$(ts)] Note: adding System keychains to the user keychain search list (fixes common codesign chain errors)"
+  echo "    (This changes the user keychain search list; run 'security list-keychains -d user' to view.)"
+  security list-keychains -d user -s "$login_kc" "$system_kc" "$roots_kc" >/dev/null 2>&1 || true
+}
+
+preflight_identity() {
+  local what="$1"
+  local predicate="$2"
+  local identity="$3"
+
+  if ! security find-identity "$predicate" -v 2>/dev/null | grep -Fq "$identity"; then
+    echo "Error: ${what} identity not found/usable in Keychain: $identity" >&2
+    echo "Run: ./build_tools/macos/check_signing_identities.sh" >&2
+    exit 2
+  fi
+}
+
 echo "==> [$(ts)] Codesigning app (Mac App Store)"
 codesign_args=( --force --timestamp --options runtime --sign "$codesign_identity" --entitlements "$entitlements" )