Merge pull request #4046 from telepresenceio/thallgren/macos-pkg-signing

Add macOS pkg signing and refocus install docs on native installers

Author: thallgren

.github/workflows/release.yaml

@@ -41,10 +41,10 @@ jobs:
         if: runner.os == 'Windows' && matrix.arch == 'amd64'
         shell: pwsh
         run: |
-          dotnet tool install --global wix
-          wix extension add -g WixToolset.BootstrapperApplications.wixext
-          wix extension add -g WixToolset.UI.wixext
-          wix extension add -g WixToolset.Util.wixext
+          dotnet tool install --global wix --version 6.0.2
+          wix extension add -g WixToolset.BootstrapperApplications.wixext/6.0.2
+          wix extension add -g WixToolset.UI.wixext/6.0.2
+          wix extension add -g WixToolset.Util.wixext/6.0.2
       - name: Build WiX Installer
         if: runner.os == 'Windows' && matrix.arch == 'amd64'
         shell: bash
@@ -53,13 +53,6 @@ jobs:
           cd build-aux/wix-installer
           make bundle ARCH=${{ matrix.arch }}
           cp ../../build-output/bin/TelepresenceInstall.exe ../../build-output/release/telepresence-windows-${{ matrix.arch }}-setup.exe
-      - name: Build macOS Installer
-        if: runner.os == 'macOS'
-        shell: bash
-        run: |
-          cd build-aux/pkg-installer
-          VERSION="${TELEPRESENCE_VERSION#v}" ARCH=${{ matrix.arch }} ./build-pkg.sh
-          cp ../../build-output/Telepresence.pkg ../../build-output/release/telepresence-darwin-${{ matrix.arch }}.pkg
       - name: Install nfpm
         if: runner.os == 'Linux'
         shell: bash
@@ -234,6 +227,84 @@ jobs:
           delete-partial-images: true
           delete-orphaned-images: true
 
+  build-macos-pkg:
+    # This job builds signed and notarized macOS .pkg installers.
+    # It uses a protected environment requiring approval from authorized reviewers.
+    # If not approved, the release proceeds without .pkg installers (standalone binaries are still available).
+    environment: macos-signing
+    needs:
+      - publish-release
+    strategy:
+      fail-fast: false
+      matrix:
+        arch:
+          - amd64
+          - arm64
+    runs-on: macos-latest
+    env:
+      GOARCH: ${{ matrix.arch }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: ./.github/actions/install-dependencies
+        name: install dependencies
+      - name: set version
+        shell: bash
+        run: echo "TELEPRESENCE_VERSION=${{ github.ref_name }}" >> $GITHUB_ENV
+      - name: generate binaries
+        run: make release-binary
+      - name: Import Apple certificates
+        env:
+          MACOS_CERTIFICATE_P12: ${{ secrets.MACOS_CERTIFICATE_P12 }}
+          MACOS_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PASSWORD }}
+        run: |
+          # Create a temporary keychain
+          KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db
+          KEYCHAIN_PASSWORD=$(openssl rand -base64 32)
+
+          security create-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
+          security set-keychain-settings -lut 21600 "$KEYCHAIN_PATH"
+          security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
+
+          # Import certificates from base64-encoded P12
+          echo "$MACOS_CERTIFICATE_P12" | base64 --decode > $RUNNER_TEMP/certificate.p12
+          security import $RUNNER_TEMP/certificate.p12 -P "$MACOS_CERTIFICATE_PASSWORD" -A -t cert -f pkcs12 -k "$KEYCHAIN_PATH"
+          rm $RUNNER_TEMP/certificate.p12
+
+          # Add keychain to search list and set as default
+          security list-keychain -d user -s "$KEYCHAIN_PATH" login.keychain
+          security default-keychain -s "$KEYCHAIN_PATH"
+
+          # Allow codesign to access the keychain without prompting
+          security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
+
+          # Store keychain path for cleanup
+          echo "KEYCHAIN_PATH=$KEYCHAIN_PATH" >> $GITHUB_ENV
+
+      - name: Build signed macOS Installer
+        env:
+          MACOS_SIGN_APPLICATION: ${{ secrets.MACOS_SIGN_APPLICATION }}
+          MACOS_SIGN_INSTALLER: ${{ secrets.MACOS_SIGN_INSTALLER }}
+          MACOS_NOTARIZE_APPLE_ID: ${{ secrets.MACOS_NOTARIZE_APPLE_ID }}
+          MACOS_NOTARIZE_TEAM_ID: ${{ secrets.MACOS_NOTARIZE_TEAM_ID }}
+          MACOS_NOTARIZE_PASSWORD: ${{ secrets.MACOS_NOTARIZE_PASSWORD }}
+        run: |
+          cd build-aux/pkg-installer
+          VERSION="${TELEPRESENCE_VERSION#v}" ARCH=${{ matrix.arch }} ./build-pkg.sh
+
+      - name: Cleanup macOS keychain
+        if: always() && env.KEYCHAIN_PATH != ''
+        run: |
+          security delete-keychain "$KEYCHAIN_PATH" || true
+
+      - name: Add signed package to release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          cp build-output/Telepresence.pkg telepresence-darwin-${{ matrix.arch }}.pkg
+          gh release upload ${{ github.ref_name }} telepresence-darwin-${{ matrix.arch }}.pkg --clobber
+
   test-release:
     needs:
       - push-images
@@ -286,5 +357,4 @@ jobs:
           else
               echo "Version does not match!"
               exit 1
-          fi
-
+          fi

CLAUDE.md

@@ -305,3 +305,108 @@ The documentation website at [telepresence.io](https://telepresence.io) is manag
 - `DOCS_VERSION` - Major.minor version to generate or update (e.g., `2.27`)
 
 See the telepresence.io repository for full instructions.
+
+### macOS Installer Signing and Notarization
+
+The macOS `.pkg` installers are signed and notarized to pass Gatekeeper verification. The signing process uses a protected GitHub Environment to secure the signing credentials.
+
+#### Environment Setup
+
+The `build-macos-pkg` job uses the `macos-signing` environment, which must be configured in the repository settings:
+
+1. Go to https://github.com/telepresenceio/telepresence/settings/environments
+2. Create an environment named `macos-signing`
+3. Enable "Required reviewers" and add authorized personnel
+4. Optionally restrict deployment branches to `release/*`
+5. Add the following secrets to the environment (not repository-level):
+
+| Secret Name | Description |
+|-------------|-------------|
+| `MACOS_CERTIFICATE_P12` | Base64-encoded P12 file containing both Application and Developer ID Installer certificates |
+| `MACOS_CERTIFICATE_PASSWORD` | Password for the P12 file |
+| `MACOS_SIGN_APPLICATION` | Developer ID Application certificate name (e.g., `Developer ID Application: Your Name (TEAMID)`) |
+| `MACOS_SIGN_INSTALLER` | Developer ID Installer certificate name (e.g., `Developer ID Installer: Your Name (TEAMID)`) |
+| `MACOS_NOTARIZE_APPLE_ID` | Apple ID email for notarization |
+| `MACOS_NOTARIZE_TEAM_ID` | Apple Developer Team ID |
+| `MACOS_NOTARIZE_PASSWORD` | App-specific password for notarization |
+
+#### Release Workflow
+
+When a release tag is pushed:
+1. All platform binaries (Linux, Windows, macOS) are built immediately
+2. Linux `.deb`/`.rpm` and Windows `.exe` installers are built
+3. The release is published with all binaries and Linux/Windows installers
+4. The `build-macos-pkg` job waits for approval from a required reviewer
+5. Once approved, signed `.pkg` installers are built and added to the release
+
+This design ensures:
+- **Emergency releases can proceed** without the signing approver being available (all binaries and Linux/Windows installers are released)
+- **Signing credentials are protected** by requiring explicit approval before they are exposed
+- **Signed packages are added later** when the approver reviews and approves the job
+
+If the environment is not configured or never approved, the release will contain macOS standalone binaries but not `.pkg` installers.
+
+#### Obtaining the Certificates
+
+You need an [Apple Developer Program](https://developer.apple.com/programs/) membership ($99/year) to obtain signing certificates.
+
+1. **Create certificates in Apple Developer Portal:**
+   - Go to [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/certificates/list)
+   - Click the + button to create a new certificate
+   - Create **Developer ID Application** certificate (for signing binaries)
+   - Create **Developer ID Installer** certificate (for signing .pkg files)
+   - Download both certificates and double-click to install in Keychain Access
+
+2. **Find your Team ID:**
+   - Go to [Membership Details](https://developer.apple.com/account#MembershipDetailsCard)
+   - Copy the Team ID (10-character alphanumeric string)
+   - Set as `MACOS_NOTARIZE_TEAM_ID`
+
+3. **Find the certificate names:**
+   - Open Keychain Access and look under "My Certificates"
+   - The names will be like:
+     - `Developer ID Application: Your Name (TEAMID)` → `MACOS_SIGN_APPLICATION`
+     - `Developer ID Installer: Your Name (TEAMID)` → `MACOS_SIGN_INSTALLER`
+   - You can also list them with: `security find-identity -v -p codesigning`
+
+4. **Export certificates to P12:**
+   ```bash
+   # Export each certificate from Keychain Access:
+   # - Right-click certificate → Export
+   # - Choose .p12 format
+   # - Set a strong password (will be MACOS_CERTIFICATE_PASSWORD)
+
+   # If you have both in separate .p12 files, you can import them together
+   # or export them together from Keychain Access by selecting both
+
+   # Base64-encode for GitHub secrets:
+   base64 -i certificates.p12 | pbcopy
+   # Paste as MACOS_CERTIFICATE_P12
+   ```
+
+5. **Create app-specific password for notarization:**
+   - Go to [appleid.apple.com](https://appleid.apple.com/) → Sign-In and Security → App-Specific Passwords
+   - Generate a new password with a descriptive name (e.g., "GitHub Actions Notarization")
+   - Copy the generated password → `MACOS_NOTARIZE_PASSWORD`
+   - Use your Apple ID email → `MACOS_NOTARIZE_APPLE_ID`
+
+#### Testing Locally
+
+To test signing locally before configuring GitHub secrets:
+
+```bash
+# Set environment variables
+export MACOS_SIGN_APPLICATION="Developer ID Application: Your Name (TEAMID)"
+export MACOS_SIGN_INSTALLER="Developer ID Installer: Your Name (TEAMID)"
+export MACOS_NOTARIZE_APPLE_ID="your@email.com"
+export MACOS_NOTARIZE_TEAM_ID="ABCD123456"
+export MACOS_NOTARIZE_PASSWORD="xxxx-xxxx-xxxx-xxxx"
+
+# Build the signed and notarized package
+cd build-aux/pkg-installer
+VERSION=2.26.0 ./build-pkg.sh
+
+# Verify the signature
+pkgutil --check-signature ../../build-output/Telepresence.pkg
+spctl --assess --type install ../../build-output/Telepresence.pkg
+```

build-aux/pkg-installer/build-pkg.sh

@@ -14,6 +14,58 @@ if [[ "$(uname -s)" != "Darwin" ]]; then
     exit 1
 fi
 
+# === Signing and Notarization Configuration ===
+# These environment variables enable code signing and notarization:
+#   MACOS_SIGN_APPLICATION - Developer ID Application certificate name (for codesign)
+#   MACOS_SIGN_INSTALLER   - Developer ID Installer certificate name (for productsign)
+#   MACOS_NOTARIZE_APPLE_ID - Apple ID for notarization
+#   MACOS_NOTARIZE_TEAM_ID  - Apple Developer Team ID
+#   MACOS_NOTARIZE_PASSWORD - App-specific password for notarization
+#
+# If signing variables are not set, packages will be built unsigned (suitable for local development).
+
+sign_binary() {
+    local binary="$1"
+    if [[ -n "${MACOS_SIGN_APPLICATION}" ]]; then
+        echo "Signing binary: $binary"
+        codesign --force --options runtime --timestamp --sign "${MACOS_SIGN_APPLICATION}" "$binary"
+        codesign --verify --verbose "$binary"
+    fi
+}
+
+sign_package() {
+    local unsigned_pkg="$1"
+    local signed_pkg="$2"
+    if [[ -n "${MACOS_SIGN_INSTALLER}" ]]; then
+        echo "Signing package: $unsigned_pkg -> $signed_pkg"
+        productsign --sign "${MACOS_SIGN_INSTALLER}" "$unsigned_pkg" "$signed_pkg"
+        pkgutil --check-signature "$signed_pkg"
+    else
+        # No signing, just rename
+        mv "$unsigned_pkg" "$signed_pkg"
+    fi
+}
+
+notarize_package() {
+    local pkg="$1"
+    if [[ -n "${MACOS_NOTARIZE_APPLE_ID}" && -n "${MACOS_NOTARIZE_TEAM_ID}" && -n "${MACOS_NOTARIZE_PASSWORD}" ]]; then
+        echo "Submitting package for notarization: $pkg"
+        # Use --timeout to prevent indefinite waiting (15 minutes should be plenty)
+        xcrun notarytool submit "$pkg" \
+            --apple-id "${MACOS_NOTARIZE_APPLE_ID}" \
+            --team-id "${MACOS_NOTARIZE_TEAM_ID}" \
+            --password "${MACOS_NOTARIZE_PASSWORD}" \
+            --wait \
+            --timeout 15m
+
+        echo "Stapling notarization ticket to: $pkg"
+        xcrun stapler staple "$pkg"
+        xcrun stapler validate "$pkg"
+    else
+        echo "Skipping notarization (credentials not provided)"
+    fi
+}
+
 # Allow ARCH override from environment (for CI cross-builds), otherwise detect
 if [[ -n "${ARCH}" ]]; then
     arch="${ARCH}"
@@ -56,6 +108,7 @@ cli_payload="$build_output/cli/Payload"
 mkdir -p "$cli_payload/usr/local/bin"
 cp "$telepresence_binary" "$cli_payload/usr/local/bin/telepresence"
 chmod +x "$cli_payload/usr/local/bin/telepresence"
+sign_binary "$cli_payload/usr/local/bin/telepresence"
 
 cp uninstall "$cli_payload/usr/local/bin/telepresence-uninstall"
 chmod +x "$cli_payload/usr/local/bin/telepresence-uninstall"
@@ -103,6 +156,12 @@ productbuild --distribution "$product/Distribution.xml" \
              --package-path "$product" \
              --resources "$resources" \
              --version "$VERSION" \
-             "$build_output/Telepresence.pkg"
+             "$build_output/Telepresence-unsigned.pkg"
+
+# Sign the package (or rename if no signing certificate)
+sign_package "$build_output/Telepresence-unsigned.pkg" "$build_output/Telepresence.pkg"
+
+# Notarize the signed package (if credentials are provided)
+notarize_package "$build_output/Telepresence.pkg"
 
 rm -rf cli rootd resources product