Eve library

Code Signing Guide for Yemaya Desktop

Guide

Revision 1

On this page

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)

  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

  2. Create an App-Specific Password

  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:

"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

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)

    text
    # 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?#