Sign Project - Native Desktop

The sign command allows you to digitally sign your built Native Desktop applications for Windows and macOS. Code signing is essential for ensuring user trust, preventing security warnings, and meeting platform distribution requirements.

Prerequisites

Before signing your application, ensure:

Your application has been built using native-desktop build
You have valid code signing certificates for your target platform
You have the necessary credentials and identities configured

Code signing requires platform-specific certificates and credentials. Unsigned applications may trigger security warnings or be blocked by operating systems.

Basic Usage

To sign an application, run:

native-desktop sign [app-path]

If you don’t specify an app path, the CLI will attempt to detect the application automatically from the bin/ directory.

# Auto-detect application
native-desktop sign

# Specify application path
native-desktop sign bin/my-app.dmg

Command Options

`[app-path]` (Optional)

Path to the application to sign.

Type: String (positional argument)
Required: No (auto-detected if not provided)
Example: bin/MyApp.dmg, bin/MyApp.exe

native-desktop sign bin/MyApp.dmg

`--platform`

Target platform for signing.

Type: String
Choices: windows, mac
Required: No (auto-detected from app path)

native-desktop sign --platform mac

`--verbose`

Enable verbose logging for detailed signing information.

Type: Boolean
Default: false

native-desktop sign --verbose

macOS Signing

Signing macOS applications requires an Apple Developer certificate and optionally Apple ID credentials for notarization.

Required Credentials

Developer ID Application Certificate: For signing the application
Apple ID (optional): For notarization
Team ID (optional): For notarization

macOS Options

`--identity`

Certificate identity name or hash for signing.

native-desktop sign bin/MyApp.dmg --platform mac --identity "Developer ID Application: Your Name (TEAM123)"

Type: String
Required: Yes (for macOS)
Format: Certificate name or SHA-1 hash

To find your certificate identity, use: security find-identity -v -p codesigning

`--apple-id`

Apple ID email address for notarization.

native-desktop sign bin/MyApp.dmg \
  --platform mac \
  --identity "Developer ID Application" \
  --apple-id "developer@example.com"

Type: String
Required: No (required for notarization)

`--apple-id-password`

Apple ID app-specific password for notarization.

native-desktop sign bin/MyApp.dmg \
  --platform mac \
  --identity "Developer ID Application" \
  --apple-id "developer@example.com" \
  --apple-id-password "xxxx-xxxx-xxxx-xxxx"

Type: String
Required: No (required for notarization)

Generate an app-specific password at appleid.apple.com. Never use your main Apple ID password.

`--team-id`

Apple Team ID for notarization.

native-desktop sign bin/MyApp.dmg \
  --platform mac \
  --identity "Developer ID Application" \
  --apple-id "developer@example.com" \
  --apple-id-password "xxxx-xxxx-xxxx-xxxx" \
  --team-id "TEAM123456"

Type: String
Required: No (required for notarization)

macOS Examples

Basic Signing (No Notarization)

native-desktop sign bin/MyApp.dmg \
  --platform mac \
  --identity "Developer ID Application: Company Name (TEAMID)"

Signing with Notarization

native-desktop sign bin/MyApp.dmg \
  --platform mac \
  --identity "Developer ID Application: Company Name (TEAMID)" \
  --apple-id "developer@example.com" \
  --apple-id-password "xxxx-xxxx-xxxx-xxxx" \
  --team-id "TEAMID"

Using Certificate Hash

# Find certificate hash
security find-identity -v -p codesigning

# Sign using hash
native-desktop sign bin/MyApp.dmg \
  --platform mac \
  --identity "ABC123DEF456..."

macOS Notarization

Notarization is an additional security step required for distribution outside the Mac App Store. It involves:

Signing: Application is signed with Developer ID
Upload: Binary is uploaded to Apple for scanning
Verification: Apple verifies the application
Stapling: Notarization ticket is attached to the application

Notarization is required for macOS 10.15+ applications distributed outside the Mac App Store.

Windows Signing

Signing Windows applications requires a code signing certificate in .pfx or .p12 format.

Required Credentials

Code Signing Certificate: .pfx or .p12 file
Certificate Password: Password for the certificate file

Windows Options

`--cert-file`

Path to the certificate file (.pfx or .p12).

native-desktop sign bin/MyApp.exe \
  --platform windows \
  --cert-file "path/to/certificate.pfx" \
  --cert-password "your-password"

Type: String
Required: Yes (one of cert-file or certificate-sha1)

`--cert-password`

Password for the certificate file.

native-desktop sign bin/MyApp.exe \
  --platform windows \
  --cert-file "certificate.pfx" \
  --cert-password "SecurePassword123"

Type: String
Required: Yes (when using cert-file)

Never commit certificate passwords to version control. Use environment variables or secure secret management.

`--cert-subject-name`

Certificate subject name (alternative to cert-file).

native-desktop sign bin/MyApp.exe \
  --platform windows \
  --cert-subject-name "Company Name Inc."

Type: String
Required: No

`--certificate-sha1`

Certificate SHA1 hash (alternative to cert-file).

native-desktop sign bin/MyApp.exe \
  --platform windows \
  --certificate-sha1 "ABC123DEF456..."

Type: String
Required: No

Windows Examples

Signing with Certificate File

native-desktop sign bin/MyApp.exe \
  --platform windows \
  --cert-file "certificate.pfx" \
  --cert-password "MyPassword123"

Signing with Certificate Store

native-desktop sign bin/MyApp.exe \
  --platform windows \
  --cert-subject-name "Company Name Inc."

Signing with SHA1 Hash

native-desktop sign bin/MyApp.exe \
  --platform windows \
  --certificate-sha1 "1234567890ABCDEF1234567890ABCDEF12345678"

Signing MSI Installer

native-desktop sign bin/MyApp.msi \
  --platform windows \
  --cert-file "certificate.pfx" \
  --cert-password "MyPassword123" \
  --verbose

Automatic Signing During Build

You can automatically sign your application during the build process using the --sign flag:

# macOS
native-desktop build --target dmg --sign

# Windows
native-desktop build --target exe --sign

When using --sign with the build command, signing credentials must be configured in your native-desktop.config.json5 file.

Configuration File Signing

You can configure signing credentials in your native-desktop.config.json5 file:

{
  "signing": {
    "mac": {
      "identity": "Developer ID Application: Company (TEAMID)",
      "appleId": "developer@example.com",
      "appleIdPassword": "xxxx-xxxx-xxxx-xxxx",
      "teamId": "TEAMID"
    },
    "windows": {
      "certFile": "path/to/certificate.pfx",
      "certPassword": "${WINDOWS_CERT_PASSWORD}"
    }
  }
}

Use environment variables for sensitive credentials like passwords.

Verification

After signing, verify your application:

macOS Verification

# Verify signature
codesign --verify --verbose bin/MyApp.app

# Check notarization
spctl --assess --verbose bin/MyApp.app

# Display signature information
codesign -dv bin/MyApp.app

Windows Verification

# Using signtool (Windows SDK)
signtool verify /pa bin/MyApp.exe

# Display signature information
signtool verify /v bin/MyApp.exe

Common Issues

macOS: Certificate Not Found

Error: Certificate identity not foundSolution: Ensure your Developer ID certificate is installed in Keychain.

# List available certificates
security find-identity -v -p codesigning

# Import certificate if needed
security import certificate.p12 -k ~/Library/Keychains/login.keychain

macOS: Notarization Failed

Error: Notarization failedSolution: Check that all credentials are correct and the app-specific password is valid.

Verify Apple ID credentials
Ensure app-specific password is generated
Check Team ID matches your developer account
Review verbose logs with --verbose

Windows: Certificate Password Invalid

Error: Invalid certificate passwordSolution: Verify the certificate password is correct.

# Test certificate
certutil -dump certificate.pfx

Windows: Certificate File Not Found

Error: Certificate file not foundSolution: Provide the correct path to the certificate file.

# Use absolute path
native-desktop sign bin/MyApp.exe \
  --cert-file "/absolute/path/to/certificate.pfx" \
  --cert-password "password"

Application Path Not Found

Error: Application path not foundSolution: Ensure the application has been built and the path is correct.

# Build first
native-desktop build --target dmg

# Then sign
native-desktop sign bin/MyApp.dmg

Security Best Practices

Secure Credentials

Never commit certificates or passwords to version control. Use environment variables or secret management tools.

App-Specific Passwords

Use Apple app-specific passwords instead of your main Apple ID password for notarization.

Certificate Protection

Store certificate files securely and restrict access to authorized personnel only.

Regular Renewal

Monitor certificate expiration dates and renew before expiry to avoid distribution issues.

Platform Requirements

macOS

macOS 10.13+: Required for code signing
Xcode Command Line Tools: Install with xcode-select --install
Apple Developer Account: Required for Developer ID certificates
Internet Connection: Required for notarization

Windows

Windows 7+: Supported for code signing
signtool: Included in Windows SDK
Code Signing Certificate: From trusted Certificate Authority

CI/CD Integration

GitHub Actions Example

name: Build and Sign

on: [push]

jobs:
  build-mac:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install certificates
        env:
          CERTIFICATE_BASE64: ${{ secrets.MACOS_CERTIFICATE }}
        run: |
          echo $CERTIFICATE_BASE64 | base64 --decode > certificate.p12
          security import certificate.p12 -k ~/Library/Keychains/login.keychain
      
      - name: Build and Sign
        env:
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
          TEAM_ID: ${{ secrets.TEAM_ID }}
        run: |
          native-desktop build --target dmg
          native-desktop sign bin/MyApp.dmg \
            --platform mac \
            --identity "Developer ID Application" \
            --apple-id "$APPLE_ID" \
            --apple-id-password "$APPLE_PASSWORD" \
            --team-id "$TEAM_ID"

Quick Start

Getting started

Tips and Tricks

User Guide

​Prerequisites

​Basic Usage

​Command Options

​[app-path] (Optional)

​--platform

​--verbose

​macOS Signing

​Required Credentials

​macOS Options

​--identity

​--apple-id

​--apple-id-password

​--team-id

​macOS Examples

​Basic Signing (No Notarization)

​Signing with Notarization

​Using Certificate Hash

​macOS Notarization

​Windows Signing

​Required Credentials

​Windows Options

​--cert-file

​--cert-password

​--cert-subject-name

​--certificate-sha1

​Windows Examples

​Signing with Certificate File

​Signing with Certificate Store

​Signing with SHA1 Hash

​Signing MSI Installer

​Automatic Signing During Build

​Configuration File Signing

​Verification

​macOS Verification

​Windows Verification

​Common Issues

​Security Best Practices

Secure Credentials

App-Specific Passwords

Certificate Protection

Regular Renewal

​Platform Requirements

​macOS

​Windows

​CI/CD Integration

​GitHub Actions Example

Prerequisites

Basic Usage

Command Options

`[app-path]` (Optional)

`--platform`

`--verbose`

macOS Signing

Required Credentials

macOS Options

`--identity`

`--apple-id`

`--apple-id-password`

`--team-id`

macOS Examples

Basic Signing (No Notarization)

Signing with Notarization

Using Certificate Hash

macOS Notarization

Windows Signing

Required Credentials

Windows Options

`--cert-file`

`--cert-password`

`--cert-subject-name`

`--certificate-sha1`

Windows Examples

Signing with Certificate File

Signing with Certificate Store

Signing with SHA1 Hash

Signing MSI Installer

Automatic Signing During Build

Configuration File Signing

Verification

macOS Verification

Windows Verification

Common Issues

Security Best Practices

Platform Requirements

macOS

Windows

CI/CD Integration

GitHub Actions Example