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

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

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

---

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