strawberry/build_tools/macos/README_MAS.md

Mac App Store (MAS) submission guide (manual steps)

This repo supports a Mac App Store build mode (BUILD_FOR_MAC_APP_STORE=ON) and includes scripts to build a signed upload .pkg.

If you’re blocked because security find-identity only shows Developer ID and not Apple Distribution / Installer, follow the steps below.

---

Open Keychain Access (macOS “hidden” Utilities)

Any of these work:

• Spotlight: press ⌘ + Space → type Keychain Access → Enter
• Finder: Applications → Utilities → Keychain Access
• Terminal:

open -a "Keychain Access"

---

The core issue: certificate exists but is not a usable identity

If you see certificates like:

• Apple Distribution: ...
• 3rd Party Mac Developer Installer: ...

but security find-identity does not list them, then the certificate is present but the private key is missing (or not paired / in the wrong keychain).

You can confirm with:

./build_tools/macos/check_signing_identities.sh

---

Step 1 — Create the private keys on this Mac (CSR)

1. Open Keychain Access
2. Menu: Keychain Access → Certificate Assistant → Request a Certificate From a Certificate Authority…
3. Fill:
   • User Email Address: your Apple ID email
   • Common Name: e.g. Dry Ark LLC (any label is fine)
   • CA Email Address: leave blank
   • Select: Saved to disk
4. Save the CSR (.certSigningRequest) somewhere safe

This CSR step is what creates the private key locally in your login keychain.

---

Step 2 — Create + download the certificates (Apple Developer portal)

In Apple Developer → Certificates, Identifiers & Profiles → Certificates → +:

• Create Apple Distribution (use the CSR you just made)
• Create Mac Installer Distribution (or “3rd Party Mac Developer Installer”, wording varies) (use a CSR)

Download the resulting .cer files.

---

Step 3 — Install certificates into your login keychain

Double-click each downloaded .cer to install it.

Then in Keychain Access → login → My Certificates:

• Find Apple Distribution: ... and expand it
  • You must see a private key under it.
• Find ... Installer ... and expand it
  • You must see a private key under it.

If there’s no private key under the certificate, it will not be usable for signing on this Mac.

---

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.

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:

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.

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):

sudo security add-certificates -k /Library/Keychains/System.keychain "/path/to/WWDR.cer"

Verify it’s visible:

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:

security verify-cert -c "Apple Distribution: Dry Ark LLC (7628766FL2)" 2>&1 | head -n 80

security find-identity -p codesigning -v
security find-identity -p basic -v
./build_tools/macos/check_signing_identities.sh

Expected:

• Apple Distribution: ... shows up under codesigning
• ... Installer ... shows up as an installer identity (used to sign upload .pkg)

---

Step 5 — Create + install the provisioning profile (Mac App Store)

In Apple Developer → Profiles → +:

• Platform: macOS
• Type: Mac App Store
• App ID: com.dryark.strawberry (or your own bundle id)
• Select the Apple Distribution certificate
• Generate + Download

Where the .provisionprofile ends up (newer Xcode/macOS)

Recent Xcode versions store “downloaded manual profiles” under:

• ~/Library/Developer/Xcode/UserData/Provisioning Profiles/

Older tooling sometimes used:

• ~/Library/MobileDevice/Provisioning Profiles/

This repo’s MAS build script does not require the profile to be in a specific folder — you can pass the path directly.

To locate and pick the right profile, use:

./build_tools/macos/find_mas_provisioning_profile.sh --bundle-id com.dryark.strawberry

(Optional) Copy to the legacy folder

If some other tools expect the legacy folder, you can copy it there:

mkdir -p "$HOME/Library/MobileDevice/Provisioning Profiles"
cp -f "/path/to/profile.provisionprofile" "$HOME/Library/MobileDevice/Provisioning Profiles/"

---

Step 6 — Build the signed upload package (.pkg)

This repo provides:

• build_tools/macos/build_mas_pkg.sh (build → deploy → embed profile → sign → productbuild)

Example:

./build_tools/macos/build_mas_pkg.sh --run --release --clean \
  --codesign-identity "Apple Distribution: Dry Ark LLC (7628766FL2)" \
  --installer-identity "3rd Party Mac Developer Installer: Dry Ark LLC (7628766FL2)" \
  --provisionprofile "$HOME/Library/MobileDevice/Provisioning Profiles/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.provisionprofile"

Outputs:

• cmake-build-macos-release-mas/strawberry.app
• cmake-build-macos-release-mas/strawberry-mas.pkg

---

Architecture note — arm64 vs universal (arm64+x86_64)

For Mac App Store uploads, your .pkg can contain either:

• arm64-only app (Apple Silicon only), or
• universal app (arm64 + x86_64), or
• x86_64-only app (runs on Apple Silicon under Rosetta 2, but native Intel only otherwise)

Apple does not require universal binaries for review. arm64-only is allowed, but:

• Intel Macs cannot run an arm64-only app.
• If you ship arm64-only, App Store Connect will effectively make the app available only to Apple Silicon Macs (and your listing will reflect that).

Recommendation

• If you want the broadest compatibility, aim for a universal build.
• If you’re okay supporting only Apple Silicon Macs, arm64-only is the simplest path.

Can I upload two different .pkgs (one arm64, one x86_64)?

Not in the way you want.

• In App Store Connect you can upload multiple builds over time, but for any given version/submission you ultimately pick one build to submit.
• Apple will not “merge” two separate uploads (arm64-only + x86_64-only) into one app for customers.

If you want both Apple Silicon and Intel supported natively, you need to produce a single universal app bundle and package that into one .pkg.

If you don’t want to deal with universal yet, your practical choices are:

• arm64-only: Apple Silicon only.
• x86_64-only: runs on Intel natively, and on Apple Silicon under Rosetta 2 (slower, but widely compatible).

Practical reality for this repo

This project depends on large native dependency stacks (Qt, GStreamer, plugins). If you build those via Homebrew, you typically end up with single-architecture libraries (arm64 under /opt/homebrew, x86_64 under /usr/local).

A true universal app requires all bundled native code (your executable and all .dylib/plugins/frameworks you ship) to be universal as well.

If you decide you want universal:

• You’ll need a universal build of Qt and GStreamer (and all bundled plugins), or
• Build arm64 and x86_64 bundles separately and combine matching binaries where possible (advanced; easy to break signing / plugin loading).

---

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:

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.:

security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k 'p@ssw0rd!$' "$HOME/Library/Keychains/login.keychain-db"

Then rerun:

./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

7.1 Install Apple “Transporter” (the upload tool)

Apple requires Mac App Store submissions to be uploaded using Transporter (a macOS app published by Apple).

Where to get it:

• Install Transporter from the Mac App Store (search for “Transporter”).
  • App Store listing name is typically “Transporter” by Apple.

7.2 Upload the .pkg with Transporter

1. Open Transporter
2. Sign in with the Apple ID that has access to App Store Connect
3. Click Add App (or +) and choose your signed upload package:
   • cmake-build-macos-release-mas/strawberry-mas.pkg (or your custom --pkg-out path)
4. Click Deliver
5. Wait for upload + server-side validation to complete

Notes:

• Uploading can take a while depending on your connection.
• If Transporter reports an error, the message usually includes the exact App Store Connect requirement you violated (bundle id mismatch, missing entitlements, invalid signature, etc.).

7.3 Submit the build in App Store Connect

1. Open App Store Connect in your browser and go to My Apps
2. Select your app, then go to the macOS App platform section
3. Find your uploaded build under TestFlight or Prepare for Submission (Apple’s UI wording changes over time)
4. Wait for Apple to finish “Processing” the build
5. Select the build for your version, complete required metadata, then click Submit for Review

(Optional) CLI upload (advanced): iTMSTransporter

If you prefer uploading from the command line, Apple’s underlying uploader is iTMSTransporter. On most systems it’s available via Xcode command line tools as:

xcrun iTMSTransporter -help

CLI upload requires additional credentials (App Store Connect API key or Apple ID auth) and is easier to get wrong than the Transporter GUI. For most folks, Transporter.app is the recommended path.

---

Creating a universal Mac App Store upload using two Macs (arm64 + x86_64)

If you have both an Apple Silicon Mac and an Intel Mac, the most reliable way to ship a universal app for this repo is:

1. Build + deploy the unsigned MAS app bundle on each machine (arm64 and x86_64).
2. Copy both .app bundles to the machine that has your signing keys.
3. Merge them with lipo and then sign + package once, producing a single universal .pkg.

Step A — Build + deploy (arm64 machine)

On your Apple Silicon Mac:

./build_tools/macos/build_app.sh --release --clean --mas --deploy --build-dir ./cmake-build-macos-release-mas-arm64

This produces (unsigned):

• cmake-build-macos-release-mas-arm64/strawberry.app

Step B — Build + deploy (x86_64 machine)

On your Intel Mac:

./build_tools/macos/build_app.sh --release --clean --mas --deploy --build-dir ./cmake-build-macos-release-mas-x86_64

This produces (unsigned):

• cmake-build-macos-release-mas-x86_64/strawberry.app

Step C — Copy both app bundles to one “packaging” machine

Pick the Mac that has your Apple Distribution and Installer identities (private keys) installed. Copy both .app bundles onto that Mac, for example:

• /path/to/inputs/strawberry-arm64.app
• /path/to/inputs/strawberry-x86_64.app

Tip: rsync works well for app bundles:

rsync -a "/path/to/arm64/strawberry.app" "/path/to/inputs/strawberry-arm64.app"
rsync -a "/path/to/x86_64/strawberry.app" "/path/to/inputs/strawberry-x86_64.app"

Step D — Merge + sign + build the universal .pkg

On the packaging machine:

./build_tools/macos/build_mas_universal_pkg.sh --run \
  --arm-app "/path/to/inputs/strawberry-arm64.app" \
  --x86-app "/path/to/inputs/strawberry-x86_64.app" \
  --codesign-identity "Apple Distribution: Your Name (TEAMID)" \
  --installer-identity "3rd Party Mac Developer Installer: Your Name (TEAMID)" \
  --provisionprofile "/path/to/profile.provisionprofile"

Outputs:

• cmake-build-macos-release-mas-universal/strawberry.app (universal)
• cmake-build-macos-release-mas-universal/strawberry-mas-universal.pkg

Important constraints (don’t skip)

• The two input apps must be built from the same commit with the same enabled features so the app bundle layouts match.
• Do not sign the per-arch apps first; lipo invalidates signatures. Sign only after merging.