# Code Signing Guide for Yemaya Desktop

This document explains how to set up code signing for distributing the Yemaya desktop application on macOS and Windows.

## Why Code Signing?

Code signing is essential for:
- **macOS**: Apps without signing show scary "unidentified developer" warnings and cannot be notarized
- **Windows**: Unsigned apps trigger SmartScreen warnings and may be blocked by enterprise policies
- **Auto-updates**: Signed updates are required for secure update verification

## macOS Code Signing & Notarization

### Prerequisites

1. **Apple Developer Account** ($99/year)
   - Sign up at [developer.apple.com](https://developer.apple.com)
   - Enroll in the Apple Developer Program

2. **Developer ID Certificate**
   - Open Xcode > Preferences > Accounts
   - Select your team and click "Manage Certificates"
   - Create a "Developer ID Application" certificate

### Setup Steps

1. **Get Your Team ID**
   - Visit [developer.apple.com/account](https://developer.apple.com/account)
   - Go to Membership
   - Copy your Team ID (e.g., `ABCD1234EF`)

2. **Create an App-Specific Password**
   - Visit [appleid.apple.com/account/manage](https://appleid.apple.com/account/manage)
   - Sign in with your Apple ID
   - Go to Security > App-Specific Passwords
   - Generate a new password and save it securely

3. **Set Environment Variables**
   ```bash
   export APPLE_ID="your@email.com"
   export APPLE_PASSWORD="xxxx-xxxx-xxxx-xxxx"
   export APPLE_TEAM_ID="ABCD1234EF"
   ```

4. **Verify Certificate Installation**
   ```bash
   security find-identity -v -p codesigning
   ```
   You should see your "Developer ID Application" certificate listed.

### Entitlements

The app uses hardened runtime with the following entitlements (defined in `build/entitlements.mac.plist`):

- `com.apple.security.cs.allow-jit` - Required for V8 JavaScript engine
- `com.apple.security.cs.allow-unsigned-executable-memory` - Required for Electron
- `com.apple.security.cs.disable-library-validation` - Required for native modules
- `com.apple.security.network.client` - For API calls
- `com.apple.security.network.server` - For dev tools
- `com.apple.security.files.user-selected.read-write` - For file operations

### Troubleshooting macOS

**"The signature is invalid" error:**
- Ensure your certificate is properly installed in Keychain
- Check that the Team ID matches your certificate

**Notarization fails:**
- Verify your App-Specific Password is correct
- Check Apple's system status: [developer.apple.com/system-status](https://developer.apple.com/system-status)
- Review the notarization log for specific issues

**"App is damaged" after download:**
- Run: `xattr -cr /Applications/Yemaya.app`
- This removes quarantine attributes from malformed zip extraction

---

## Windows Code Signing

### Certificate Types

1. **Standard Code Signing Certificate** (~$100-300/year)
   - Requires building reputation with Microsoft SmartScreen
   - Initial downloads may still show warnings

2. **EV Code Signing Certificate** (~$300-500/year)
   - Immediate SmartScreen reputation
   - Requires hardware token (SafeNet/USB)
   - Recommended for production releases

### Recommended Certificate Providers

- [DigiCert](https://www.digicert.com/code-signing)
- [Sectigo](https://sectigo.com/ssl-certificates-tls/code-signing)
- [GlobalSign](https://www.globalsign.com/en/code-signing-certificate)

### Setup Steps

1. **Purchase a Certificate**
   - Complete the validation process with your CA
   - For EV certificates, install the SafeNet client software

2. **Export Certificate (Standard Certificates)**
   ```
   # Export from Windows Certificate Store to .pfx file
   # Include private key and all certificates in chain
   ```

3. **Set Environment Variables**
   ```bash
   # For .pfx file-based signing
   export WINDOWS_CERTIFICATE_FILE="/path/to/certificate.pfx"
   export WINDOWS_CERTIFICATE_PASSWORD="your-password"

   # For EV certificates with hardware token
   export WINDOWS_SIGN_TOOL_PATH="C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\x64\signtool.exe"
   ```

### EV Certificate Signing

For EV certificates with hardware tokens, the signing process requires:

1. SafeNet Authentication Client installed
2. Hardware token connected
3. Token PIN entry during build (automated in CI is complex)

### Troubleshooting Windows

**SmartScreen warnings persist:**
- Standard certificates need to build reputation
- Encourage users to click "More info" > "Run anyway"
- Consider upgrading to an EV certificate

**signtool.exe not found:**
- Install Windows SDK
- Add to PATH or set WINDOWS_SIGN_TOOL_PATH

**Certificate password incorrect:**
- Ensure no special characters are causing issues
- Try escaping special characters in the password

---

## CI/CD Integration

### GitHub Actions

Add these secrets to your repository:

```yaml
# macOS
APPLE_ID
APPLE_PASSWORD
APPLE_TEAM_ID

# Windows
WINDOWS_CERTIFICATE_FILE  # Base64-encoded .pfx
WINDOWS_CERTIFICATE_PASSWORD

# Publishing
GITHUB_TOKEN
```

Example workflow step:

```yaml
- name: Build and Sign
  env:
    APPLE_ID: ${{ secrets.APPLE_ID }}
    APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
    APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
  run: npm run make
```

### Local Testing (Without Signing)

For local development without signing credentials:

```bash
# Build without signing (development only)
npm run build
npm run package  # Will skip signing if credentials not set
```

---

## Security Best Practices

1. **Never commit credentials** - Use environment variables or CI secrets
2. **Rotate passwords regularly** - Especially App-Specific Passwords
3. **Protect your certificate** - Use strong passwords for .pfx files
4. **Monitor for misuse** - Set up alerts for unexpected signing activity
5. **Use CI/CD** - Avoid signing on developer machines when possible

---

## Quick Reference

| Platform | Certificate Cost | Annual Renewal | Reputation |
|----------|-----------------|----------------|------------|
| macOS    | $99/year        | Required       | Immediate  |
| Windows (Standard) | $100-300/year | Required | Build over time |
| Windows (EV) | $300-500/year | Required | Immediate |

---

## Need Help?

- [Apple Developer Documentation](https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution)
- [Microsoft Code Signing Documentation](https://docs.microsoft.com/en-us/windows/win32/seccrypto/cryptography-tools)
- [Electron Forge Signing Guide](https://www.electronforge.io/guides/code-signing)
