# 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**:

```bash
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:

```bash
./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:

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

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

```bash
./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:

```bash
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:

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

---

## 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).
- In App Store Connect, wait for processing, select the build, then **Submit for Review**.