c802108a02
- Rename npm packages from @kb/* to @hai/* and update all workspace references - Rename CLI binary from kb to hai and config directory from .kb to .hai - Update dashboard UI branding, titles, and references from kb to hai - Update all test files, CI workflows, and documentation to reflect new naming - Run comprehensive grep verification to ensure no stale kb references remain
144 lines
5.2 KiB
Markdown
144 lines
5.2 KiB
Markdown
# 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](https://developer.apple.com/programs/)
|
|
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
|
|
|
|
```bash
|
|
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](https://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](https://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:
|
|
```bash
|
|
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
|
|
|
|
```powershell
|
|
[Convert]::ToBase64String([IO.File]::ReadAllBytes("certificate.pfx")) | Set-Clipboard
|
|
```
|
|
|
|
Or on Linux/macOS:
|
|
```bash
|
|
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**
|