Enhance macOS build tools with keychain management and troubleshooting guidance

This commit updates the `README_MAS.md` to include important notes on keychain trust settings and the installation of Apple intermediate certificates, addressing common codesigning issues. Additionally, the `build_mas_pkg.sh` script is enhanced with functions to prepare the login keychain for signing, diagnose chain failures, and provide clear error messages for authorization issues during the build process. These improvements aim to streamline the macOS build experience and assist developers in resolving keychain-related errors effectively.

build_tools/macos/README_MAS.md

@@ -89,6 +89,16 @@ If you see errors like:
 
 This is almost always a **keychain search list / trust chain** issue.
 
+#### Important: do NOT “Always Trust” your Apple Distribution / Installer certs
+
+Setting your leaf signing certificates (e.g. **Apple Distribution** / **3rd Party Mac Developer Installer**) to **Always Trust** can make things worse by overriding the normal trust chain and causing codesign to fail chain building.
+
+If you changed trust settings:
+
+- In **Keychain Access → login → My Certificates**
+  - open the cert → **Trust**
+  - set **“When using this certificate” = “Use System Defaults”**
+
 Fix (safe, common): ensure the System keychains are included in the user search list:
 
 ```bash
@@ -98,6 +108,36 @@ security list-keychains -d user -s   "$HOME/Library/Keychains/login.keychain-db"
 
 Then re-run the build/sign script.
 
+#### Install the correct Apple intermediate certificates (WWDR)
+
+If the System keychains are already in the search list and you still get chain errors, you’re likely missing an Apple intermediate (commonly **WWDR**).
+
+Download the current Apple WWDR intermediate certificate(s) from Apple’s official Certificate Authority page:
+
+- `https://www.apple.com/certificateauthority/`
+
+Then import into the **System** keychain (recommended):
+
+- Keychain Access → **System** keychain → File → **Import Items…** → select the downloaded `.cer`
+
+Or via CLI (requires admin):
+
+```bash
+sudo security add-certificates -k /Library/Keychains/System.keychain "/path/to/WWDR.cer"
+```
+
+Verify it’s visible:
+
+```bash
+security find-certificate -a -c "Apple Worldwide Developer Relations" /Library/Keychains/System.keychain | head -n 10
+```
+
+If needed, you can also verify the chain for your distribution cert:
+
+```bash
+security verify-cert -c "Apple Distribution: Dry Ark LLC (7628766FL2)" 2>&1 | head -n 80
+```
+
 ```bash
 security find-identity -p codesigning -v
 security find-identity -p basic -v
@@ -172,6 +212,52 @@ Outputs:
 
 ---
 
+## Troubleshooting — `productbuild` fails with CSSM `-60008` (authorization)
+
+If you see something like:
+
+- `SignData failed ... CSSM Exception: -60008 Unable to obtain authorization for this operation`
+
+That means the **Installer** certificate is present, but macOS is not allowing `productbuild` to use the **private key** without additional authorization.
+
+### Fix option A (recommended): set key partition list (CLI)
+
+This is the standard “allow Apple tools to sign without GUI prompts” fix:
+
+```bash
+security unlock-keychain "$HOME/Library/Keychains/login.keychain-db"
+security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "<login-keychain-password>" "$HOME/Library/Keychains/login.keychain-db"
+```
+
+Note: if your password contains characters like `!` or `$` and you paste it into a command in `zsh`,
+the shell can modify it (history/variable expansion) and `security ... -k` may claim it’s “incorrect”.
+Use **single quotes** (or the env var path shown below) to avoid this, e.g.:
+
+```bash
+security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k 'p@ssw0rd!$' "$HOME/Library/Keychains/login.keychain-db"
+```
+
+Then rerun:
+
+```bash
+./build_tools/macos/build_mas_pkg.sh --run ...
+```
+
+This repo’s script also supports:
+
+- `--keychain-password <pw>` (or env var `STRAWBERRY_KEYCHAIN_PASSWORD`)
+
+### Fix option B: Keychain Access UI (one-time)
+
+1. Open **Keychain Access**
+2. Select **login** keychain → **My Certificates**
+3. Find your installer cert (e.g. `3rd Party Mac Developer Installer: ...`) and **expand it**
+4. Select the **private key** under it
+5. **Get Info → Access Control**
+   - Add `/usr/bin/productbuild` (and optionally `/usr/bin/pkgbuild`) to the allowed apps
+
+---
+
 ## Step 7 — Upload + submit for review
 
 - Upload the `.pkg` using Apple’s **Transporter** app (App Store Connect).