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#
-
Apple Developer Account ($99/year)
- Sign up at developer.apple.com
- Enroll in the Apple Developer Program
-
Developer ID Certificate
- Open Xcode > Preferences > Accounts
- Select your team and click "Manage Certificates"
- Create a "Developer ID Application" certificate
Setup Steps#
-
Get Your Team ID
- Visit developer.apple.com/account
- Go to Membership
- Copy your Team ID (e.g.,
ABCD1234EF)
-
Create an App-Specific Password
- Visit 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
-
Set Environment Variables
bashexport APPLE_ID="your@email.com" export APPLE_PASSWORD="xxxx-xxxx-xxxx-xxxx" export APPLE_TEAM_ID="ABCD1234EF" -
Verify Certificate Installation
bashsecurity find-identity -v -p codesigningYou 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 enginecom.apple.security.cs.allow-unsigned-executable-memory- Required for Electroncom.apple.security.cs.disable-library-validation- Required for native modulescom.apple.security.network.client- For API callscom.apple.security.network.server- For dev toolscom.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
- 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#
-
Standard Code Signing Certificate (~$100-300/year)
- Requires building reputation with Microsoft SmartScreen
- Initial downloads may still show warnings
-
EV Code Signing Certificate (~$300-500/year)
- Immediate SmartScreen reputation
- Requires hardware token (SafeNet/USB)
- Recommended for production releases
Recommended Certificate Providers#
Setup Steps#
-
Purchase a Certificate
- Complete the validation process with your CA
- For EV certificates, install the SafeNet client software
-
Export Certificate (Standard Certificates)
text# Export from Windows Certificate Store to .pfx file # Include private key and all certificates in chain -
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:
- SafeNet Authentication Client installed
- Hardware token connected
- 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:
# macOS
APPLE_ID
APPLE_PASSWORD
APPLE_TEAM_ID
# Windows
WINDOWS_CERTIFICATE_FILE # Base64-encoded .pfx
WINDOWS_CERTIFICATE_PASSWORD
# Publishing
GITHUB_TOKEN
Example workflow step:
- 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:
# Build without signing (development only)
npm run build
npm run package # Will skip signing if credentials not set
Security Best Practices#
- Never commit credentials - Use environment variables or CI secrets
- Rotate passwords regularly - Especially App-Specific Passwords
- Protect your certificate - Use strong passwords for .pfx files
- Monitor for misuse - Set up alerts for unexpected signing activity
- 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 |