fusion/docs/CODE_SIGNING.md

Code Signing Setup Guide

This document explains how to configure code signing for kb release binaries so they don't trigger OS security warnings on macOS (Gatekeeper) or Windows (SmartScreen).

Overview

The release workflow automatically signs binaries when the appropriate secrets are configured:

• macOS: Codesign with hardened runtime + Apple notarization
• Windows: Authenticode signing with timestamp
• Linux: No signing (no standard code signing requirement for Linux CLI tools)

Signing is optional — if secrets are not configured, the build succeeds and signing steps are skipped.

Required GitHub Secrets

macOS Signing

Secret	Description
APPLE_CERTIFICATE_BASE64	Base64-encoded .p12 Developer ID Application certificate
APPLE_CERTIFICATE_PASSWORD	Password used when exporting the .p12 certificate
APPLE_IDENTITY	Signing identity string (e.g., Developer ID Application: Your Name (TEAMID))
APPLE_ID	Apple ID email address used for notarization
APPLE_TEAM_ID	Apple Developer Team ID (10-character alphanumeric)
APPLE_APP_PASSWORD	App-specific password for notarization

Windows Signing

Secret	Description
WINDOWS_CERTIFICATE_BASE64	Base64-encoded .pfx Authenticode code signing certificate
WINDOWS_CERTIFICATE_PASSWORD	Password for the .pfx certificate

macOS Setup Instructions

1. Obtain a Developer ID Application Certificate

1. Enroll in the Apple Developer Program
2. In Xcode or the Apple Developer portal, create a Developer ID Application certificate
3. Export the certificate from Keychain Access as a .p12 file with a password

2. Encode the Certificate as Base64

base64 -i certificate.p12 | pbcopy

Paste the result as the APPLE_CERTIFICATE_BASE64 secret.

3. Find Your Team ID

Your Team ID is visible at developer.apple.com/account under Membership Details. It's a 10-character alphanumeric string (e.g., ABC1234DEF).

4. Create an App-Specific Password

1. Go to appleid.apple.com
2. Sign in and navigate to Sign-In and Security → App-Specific Passwords
3. Generate a new password and label it (e.g., "kb notarization")
4. Use this as the APPLE_APP_PASSWORD secret

5. Determine Your Signing Identity

The signing identity looks like:

Developer ID Application: Your Name (TEAMID)

You can find it by running:

security find-identity -v -p codesigning

Windows Setup Instructions

1. Obtain an Authenticode Code Signing Certificate

Purchase a code signing certificate from a trusted Certificate Authority:

• DigiCert
• Sectigo (Comodo)
• GlobalSign
• SSL.com

2. Export as .pfx

Export the certificate with its private key as a .pfx (PKCS#12) file. Set a strong password.

3. Encode the Certificate as Base64

[Convert]::ToBase64String([IO.File]::ReadAllBytes("certificate.pfx")) | Set-Clipboard

Or on Linux/macOS:

base64 -i certificate.pfx

Paste the result as the WINDOWS_CERTIFICATE_BASE64 secret.

How Signing Works in the Release Flow

1. A tag push (v*) triggers the release workflow
2. Each platform job builds the standalone binary
3. macOS jobs: scripts/sign-macos.sh runs codesign + notarization
4. Windows jobs: scripts/sign-windows.ps1 runs Authenticode signing
5. Checksums are generated after signing (so they match the signed binaries)
6. Signed binaries and checksums are uploaded to the GitHub Release

The test-release workflow (workflow_dispatch) includes the same signing steps but guards them with secret-availability checks — signing is skipped if secrets are not configured.

Troubleshooting

macOS: "The signature of the binary is invalid"

• Ensure the certificate is a Developer ID Application certificate (not Developer ID Installer or Mac App Distribution)
• Check that the certificate hasn't expired
• Verify the base64 encoding is correct: echo "$APPLE_CERTIFICATE_BASE64" | base64 --decode | file -

macOS: Notarization fails with "Invalid credentials"

• Verify APPLE_ID is your Apple ID email
• Verify APPLE_APP_PASSWORD is an app-specific password (not your Apple ID password)
• Verify APPLE_TEAM_ID matches the team that issued the certificate

macOS: Notarization fails with "The software is not signed"

• Ensure the --options runtime flag is used during codesign (hardened runtime is required for notarization)
• The sign-macos.sh script handles this automatically

Windows: "signtool not found"

• signtool.exe is included in the Windows SDK, which is pre-installed on GitHub Actions Windows runners
• For local testing, install the Windows SDK or Visual Studio Build Tools

Windows: "The specified PFX password is not correct"

• Double-check the WINDOWS_CERTIFICATE_PASSWORD secret matches the password used when exporting the .pfx

Signing step skipped

• In the test-release workflow, signing is intentionally skipped when secrets are not configured
• Verify the secrets are set at the repository level in Settings → Secrets and variables → Actions