# Meshy macOS Code Signing and Notarization Guide

## Quick Start

**Before first use:**
```bash
# Store your Apple ID credentials for notarization (one-time setup)
xcrun notarytool store-credentials "meshy-notary" \
  --apple-id "your@email.com" \
  --team-id "LG87HQ83LT" \
  --password "your-app-specific-password"
```

**To build, sign, and notarize both versions:**
```bash
./build-aux/macos/build-and-notarize-all.sh
```

This will create:
- `dist-homebrew/Meshy-YY.MM.DD.dmg` - Homebrew-optimized (~20 MB)
- `dist/Meshy-YY.MM.DD.dmg` - Standalone (~150 MB)

Both fully signed and notarized, ready for distribution!

---

## Available Scripts

### 1. `build-and-notarize-all.sh` (Recommended)
**What it does:** Builds, signs, and notarizes BOTH Homebrew and Standalone versions

**Use when:** You want to release both versions at once (typical release workflow)

**Timeline:**
- Homebrew build: ~2 min
- Homebrew notarization: ~3-5 min
- Standalone build: ~2 min  
- Standalone notarization: ~3-5 min
- **Total: ~10-15 minutes**

**Output:**
```
dist-homebrew/Meshy-26.06.20.dmg    (~20 MB, requires Homebrew GTK4)
dist/Meshy-26.06.20.dmg             (~150 MB, fully self-contained)
```

### 2. `build-and-notarize.sh`
**What it does:** Builds, signs, and notarizes ONLY the standalone version

**Use when:** You only want the self-contained bundle (most users)

**Timeline:** ~5-7 minutes

**Output:**
```
dist/Meshy-26.06.20.dmg             (~150 MB, fully self-contained)
```

### 3. Individual build scripts (without notarization)
**For development/testing only** - not for distribution!

```bash
# Homebrew-optimized (unsigned)
./build-aux/macos/build-homebrew-bundle.sh

# Homebrew-optimized (signed, not notarized)
./build-aux/macos/build-homebrew-bundle.sh \
  --sign "Developer ID Application: Jaroslav Reznik (LG87HQ83LT)"

# Standalone (unsigned)
./build-aux/macos/create-standalone-bundle.sh

# Standalone (signed, not notarized)
./build-aux/macos/create-standalone-bundle.sh \
  --sign "Developer ID Application: Jaroslav Reznik (LG87HQ83LT)"
```

---

## Which Version Should Users Download?

### Homebrew-optimized (~20 MB)
**For:** Developers and power users who already use Homebrew

**Requirements:**
```bash
brew install gtk4 libadwaita python@3.14
```

**Pros:**
- ✅ Small download size
- ✅ Uses system-wide GTK4/libadwaita (stays up-to-date)
- ✅ Less disk space

**Cons:**
- ❌ Requires Homebrew installation
- ❌ Users must install dependencies manually

### Standalone (~150 MB)
**For:** General users, non-technical users

**Requirements:** None - fully self-contained

**Pros:**
- ✅ Zero dependencies
- ✅ Just drag-and-drop to Applications
- ✅ Works immediately after download

**Cons:**
- ❌ Larger download size
- ❌ Uses bundled GTK4/libadwaita (not auto-updated)

**Recommendation:** Provide both! Users can choose based on their needs.

---

## Credentials Setup (One-Time)

### 1. Get App-Specific Password

1. Go to https://appleid.apple.com/account/manage
2. Under "Sign-In and Security" → "App-Specific Passwords"
3. Click **+** to generate new password
4. Label: "Meshy Notarization"
5. **Copy the password** (you can't see it again)

### 2. Store Credentials in Keychain

```bash
xcrun notarytool store-credentials "meshy-notary" \
  --apple-id "your@email.com" \
  --team-id "LG87HQ83LT" \
  --password "xxxx-xxxx-xxxx-xxxx"
```

Replace:
- `your@email.com` - Your Apple Developer account email
- `xxxx-xxxx-xxxx-xxxx` - The app-specific password from step 1

This stores credentials securely in macOS Keychain. You'll never need to type them again!

---

## Troubleshooting

### "0 valid identities found"
**Problem:** Certificate not in login keychain or missing private key

**Solution:**
```bash
# Check if certificate exists
security find-identity -v -p codesigning

# Import intermediate certificate
curl -O https://www.apple.com/certificateauthority/DeveloperIDG2CA.cer
security import DeveloperIDG2CA.cer -k ~/Library/Keychains/login.keychain-db
rm DeveloperIDG2CA.cer
```

### Notarization fails
**Problem:** Invalid credentials or network issue

**Solution:**
```bash
# Get detailed error log (replace with actual submission ID from error)
xcrun notarytool log <submission-id> --keychain-profile "meshy-notary"

# Re-store credentials if invalid
xcrun notarytool store-credentials "meshy-notary" \
  --apple-id "your@email.com" \
  --team-id "LG87HQ83LT" \
  --password "xxxx-xxxx-xxxx-xxxx"
```

### "The staple and validate action failed"
**Problem:** DMG wasn't notarized or notarization failed

**Solution:**
- Check that notarization succeeded before stapling
- Re-run the build script (it handles retries)

### Manual verification commands

```bash
# Verify app signature
codesign --verify --verbose dist/Meshy.app
spctl --assess --verbose dist/Meshy.app

# Verify DMG signature
codesign --verify --verbose dist/Meshy-26.06.20.dmg
spctl --assess --type open --context context:primary-signature --verbose dist/Meshy-26.06.20.dmg

# Verify notarization ticket is stapled
stapler validate dist/Meshy-26.06.20.dmg
```

---

## Release Checklist

- [ ] Set up notarization credentials (one-time): `xcrun notarytool store-credentials`
- [ ] Run `./build-aux/macos/build-and-notarize-all.sh`
- [ ] Wait ~10-15 minutes for both builds to complete
- [ ] Verify both DMGs open without Gatekeeper warnings
- [ ] Upload DMGs to release page
- [ ] Update release notes with system requirements for each version

---

## Your Signing Identity

```
Developer ID Application: Jaroslav Reznik (LG87HQ83LT)
```

This is already configured in all scripts. No manual editing needed!
