feat(packaging): code-sign the Rust binary inside the macOS wheel

An ad-hoc signature carries no signing identity, so the binary's designated
requirement degenerates to its cdhash — which changes on every build. That
requirement is what a Keychain item's ACL records when the user clicks "Always
Allow", so an unsigned wheel re-prompts for the API token on every upgrade.

hatch_build.py signs the fused binary right after lipo, because the wheel is
zipped around it and nothing downstream can. The rcodesign invocation moves out
of macos_sign_file into scripts/build-os-packages/macos-sign-file so the
standalone bundle and the wheel share one set of binary identifiers, and the
`ggshield` in both ends up with the same designated requirement.

tag.yml asks for signing explicitly; a run that cannot read the secrets fails
rather than publishing an unsigned wheel. Without `sign` — PRs, including from
forks, and local builds — the wheel is built unsigned and still works.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: amascia-gg

.github/workflows/tag.yml

@@ -17,6 +17,9 @@ jobs:
   # `push_to_pypi` below can download them.
   build_platform_wheels:
     uses: ./.github/workflows/wheels.yml
+    secrets: inherit
+    with:
+      sign: true
 
   push_to_pypi:
     needs: [build_release_assets, build_platform_wheels]

.github/workflows/wheels.yml

@@ -18,7 +18,17 @@ on:
   # Called by tag.yml, so a release actually publishes these. Same run as
   # `build_wheel_sdist`, which is what lets `push_to_pypi` download both.
   workflow_call:
+    inputs:
+      sign:
+        description: 'Code-sign the macOS binary (needs secrets, so no PR from a fork can)'
+        type: boolean
+        default: false
   workflow_dispatch:
+    inputs:
+      sign:
+        description: 'Code-sign the macOS binary (needs secrets, so no PR from a fork can)'
+        type: boolean
+        default: false
   # Only the packaging inputs: nothing else changes what these wheels contain,
   # and six jobs on every push is a lot of runner time for that.
   pull_request:
@@ -36,6 +46,11 @@ env:
   # standalone bundles; bump both together. Checksums from
   # https://static.rust-lang.org/rustup/archive/$RUSTUP_VERSION/$triple/rustup-init.sha256
   RUSTUP_VERSION: 1.29.0
+  # Same rcodesign as build_release_assets.yml installs for the standalone
+  # bundles; bump both together. The checksum is the aarch64 one -- the macOS
+  # wheel is built on macos-14 and lipo'd, so there is no Intel runner here.
+  RCODESIGN_VERSION: 0.27.0
+  RCODESIGN_SHA256: 163520079cd6ad1427791c792735a6ddfcb8eca0187bbcf0cc0bebfa4a62153d
 
 jobs:
   macos:
@@ -49,6 +64,44 @@ jobs:
       - uses: dtolnay/rust-toolchain@stable
         with:
           targets: aarch64-apple-darwin,x86_64-apple-darwin
+      # Only `sign: true` callers get here, and for them signing is not
+      # best-effort: an unsigned `ggshield` publishes fine and only shows up
+      # months later, as every upgrade re-prompting for Keychain access. Fail
+      # instead of shipping one.
+      - name: Prepare code signing
+        if: inputs.sign
+        env:
+          MACOS_P12_FILE: ${{ secrets.MACOS_P12_FILE }}
+          MACOS_P12_PASSWORD: ${{ secrets.MACOS_P12_PASSWORD }}
+        run: |
+          set -euo pipefail
+          if [ -z "$MACOS_P12_FILE" ] ; then
+            echo "sign: true, but the signing secrets are not readable here" >&2
+            exit 1
+          fi
+
+          # scripts/download needs `sha256sum`, which macOS does not ship.
+          brew install coreutils
+          # Unpacked outside the checkout: `python -m build` runs on it next.
+          scripts/download \
+            "https://github.com/indygreg/apple-platform-rs/releases/download/apple-codesign%2F$RCODESIGN_VERSION/apple-codesign-$RCODESIGN_VERSION-aarch64-apple-darwin.tar.gz" \
+            "$RUNNER_TEMP/rcodesign.tar.gz" \
+            "$RCODESIGN_SHA256"
+          tar -C "$RUNNER_TEMP" --strip-components=1 -xzf "$RUNNER_TEMP/rcodesign.tar.gz"
+          cp "$RUNNER_TEMP/rcodesign" /usr/local/bin
+
+          SECRETS_DIR=$RUNNER_TEMP/secrets
+          mkdir -p "$SECRETS_DIR"
+          # The p12 is base64-encoded because it is binary.
+          echo "$MACOS_P12_FILE" | base64 --decode > "$SECRETS_DIR/cert.p12"
+          echo "$MACOS_P12_PASSWORD" > "$SECRETS_DIR/cert.pwd"
+          cat >> "$GITHUB_ENV" <<EOF
+          MACOS_P12_FILE=$SECRETS_DIR/cert.p12
+          MACOS_P12_PASSWORD_FILE=$SECRETS_DIR/cert.pwd
+          EOF
+
+      # hatch_build.py signs the binary itself, right after lipo: nothing outside
+      # the build can, because the wheel is zipped around it.
       - name: Build wheel
         env:
           GGSHIELD_BUILD_RUST: '1'
@@ -62,6 +115,11 @@ jobs:
           name: wheel-macos-universal2
           path: dist/*.whl
 
+  # Not Authenticode-signed, unlike the .msi and .zip: nothing on Windows binds a
+  # stored credential to a binary's signature the way a macOS Keychain ACL does,
+  # so the only thing signing buys the wheel is SmartScreen reputation on a
+  # binary users reach through pip rather than a download. Separate concern,
+  # separate ticket.
   windows:
     name: wheel windows-amd64
     runs-on: windows-latest

doc/dev/os-packages.md

@@ -70,6 +70,8 @@ Although PyInstaller supports signing, it did not work at the time we tried it,
 
 For Gatekeeper to accept the app, the executable and all the dynamic libraries must be signed, as well as the .pkg archive itself. Signing the executable and the libraries is done by the `sign` step, whereas signing the .pkg archive is done by the `create_archive` step.
 
+The `rcodesign` invocation lives in its own script, `scripts/build-os-packages/macos-sign-file`, because the macOS wheel signs the same `ggshield` from Python (`hatch_build.py`). Both must produce the same designated requirement, or a Keychain grant given to one artifact does not apply to the other.
+
 [rcodesign]: https://gregoryszorc.com/docs/apple-codesign/
 
 ## Windows specific information

hatch_build.py

@@ -107,6 +107,25 @@ def _verify_elf(binary: Path, plat: str) -> None:
                 f"which does not match the {plat} wheel tag"
             )
 
+    def _sign(self, binary: Path) -> None:
+        """Code-sign the fused binary, when the build was given a certificate.
+
+        On the fused file rather than the slices: one signature covers both, and
+        cargo leaves the x86_64 slice unsigned altogether.
+
+        Unsigned -- local builds and PRs from forks, neither of which can read the
+        secrets -- the wheel still installs and runs. What it loses is a stable
+        designated requirement: an ad-hoc signature carries no signing identity,
+        so the requirement degenerates to the binary's cdhash, which changes on
+        every build. That requirement is what a Keychain item's ACL records, so
+        the grant the user gives `ggshield` for the API token stops matching on
+        the next upgrade.
+        """
+        if not os.environ.get("MACOS_P12_FILE"):
+            return
+        script = Path(self.root) / "scripts/build-os-packages/macos-sign-file"
+        subprocess.run([str(script), str(binary)], check=True)
+
     def _build(self, crate: Path, binary: Path) -> None:
         # --locked: build the dependency versions committed in rust/Cargo.lock,
         # not whatever resolves today.
@@ -139,6 +158,7 @@ def _build(self, crate: Path, binary: Path) -> None:
             subprocess.run(
                 ["lipo", "-create", "-output", str(binary), *slices], check=True
             )
+            self._sign(binary)
         else:
             subprocess.run(
                 ["cargo", "build", "--release", "--locked", "--bin", "ggshield"],

scripts/build-os-packages/macos-functions.bash

@@ -1,5 +1,7 @@
 MACOS_P12_FILE=${MACOS_P12_FILE:-}
 MACOS_P12_PASSWORD_FILE=${MACOS_P12_PASSWORD_FILE:-}
+# macos-sign-file is a separate process: without this it sees neither.
+export MACOS_P12_FILE MACOS_P12_PASSWORD_FILE
 
 # Path to a file used by rcodesign for notarizing.
 # Follow the instructions from
@@ -37,40 +39,11 @@ macos_sign() {
     done
 }
 
-# $1 is the file to sign, $2 an optional entitlements plist.
+# $1 is the file to sign, $2 an optional entitlements plist. The invocation lives
+# in macos-sign-file, shared with the macOS wheel build.
 macos_sign_file() {
     check_var MACOS_P12_FILE
-
-    local file entitlements
-    file="$1"
-    entitlements="${2:-}"
-    info "- Signing $file${entitlements:+ (with entitlements)}"
-
-    local args=(
-        --p12-file "$MACOS_P12_FILE"
-        --p12-password-file "$MACOS_P12_PASSWORD_FILE"
-        --code-signature-flags runtime
-        --for-notarization
-    )
-    if [ -n "$entitlements" ] ; then
-        args+=(--entitlements-xml-path "$entitlements")
-    fi
-
-    # Left alone, rcodesign keeps the ad-hoc identifier the linker left in the
-    # Mach-O, which carries a per-build hash: 1.53.0 shipped as
-    # `ggshield-55554944c60d09a76c903cb78828e61396fa0721`. The identifier is part
-    # of the designated requirement, and the designated requirement is what a
-    # Keychain item's ACL records when the user clicks "Always Allow" — so a
-    # per-build identifier means the grant stops matching on the next release and
-    # every upgrade re-prompts for the token. Both launchers read the token, so
-    # both need a stable one; libraries keep their own, they are never the
-    # process asking for the secret.
-    case "$(basename "$file")" in
-        ggshield)    args+=(--binary-identifier com.gitguardian.ggshield) ;;
-        ggshield-py) args+=(--binary-identifier com.gitguardian.ggshield-py) ;;
-    esac
-
-    rcodesign sign "${args[@]}" "$file"
+    "$SCRIPT_DIR/macos-sign-file" "$@"
 }
 
 # Every Mach-O in the bundle, because notarization rejects the .pkg if a single

scripts/build-os-packages/macos-sign-file

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Code-sign one Mach-O with the GitGuardian Developer ID certificate.
+#
+# A script rather than a function in macos-functions.bash because the macOS wheel
+# signs from Python (hatch_build.py) and the standalone bundle from bash: the
+# `ggshield` in both is the same dispatcher reading the same Keychain item, so
+# both must produce the same designated requirement — one invocation, one set of
+# identifiers.
+#
+# $1 is the file to sign, $2 an optional entitlements plist. $MACOS_P12_FILE and
+# $MACOS_P12_PASSWORD_FILE must point to the certificate and to its password.
+set -euo pipefail
+
+file="${1:?usage: $0 FILE [ENTITLEMENTS]}"
+entitlements="${2:-}"
+if [ -z "${MACOS_P12_FILE:-}" ] || [ -z "${MACOS_P12_PASSWORD_FILE:-}" ] ; then
+    echo "$0: MACOS_P12_FILE and MACOS_P12_PASSWORD_FILE must be set" >&2
+    exit 1
+fi
+
+echo "- Signing $file${entitlements:+ (with entitlements)}"
+
+args=(
+    --p12-file "$MACOS_P12_FILE"
+    --p12-password-file "$MACOS_P12_PASSWORD_FILE"
+    --code-signature-flags runtime
+    --for-notarization
+)
+if [ -n "$entitlements" ] ; then
+    args+=(--entitlements-xml-path "$entitlements")
+fi
+
+# Left alone, rcodesign keeps the ad-hoc identifier the linker left in the
+# Mach-O, which carries a per-build hash: 1.53.0 shipped as
+# `ggshield-55554944c60d09a76c903cb78828e61396fa0721`. The identifier is part of
+# the designated requirement, and the designated requirement is what a Keychain
+# item's ACL records when the user clicks "Always Allow" — so a per-build
+# identifier means the grant stops matching on the next release and every upgrade
+# re-prompts for the token. Both launchers read the token, so both need a stable
+# one; libraries keep their own, they are never the process asking for the secret.
+identifier=""
+case "$(basename "$file")" in
+    ggshield)    identifier=com.gitguardian.ggshield ;;
+    ggshield-py) identifier=com.gitguardian.ggshield-py ;;
+esac
+[ -z "$identifier" ] || args+=(--binary-identifier "$identifier")
+
+rcodesign sign "${args[@]}" "$file"
+
+# A wrong identifier signs, notarizes and installs perfectly happily; it only
+# surfaces later as a re-prompt on upgrade. Check the one thing the ACL depends on.
+if [ -n "$identifier" ] ; then
+    # --verbose, or codesign prints only the path. Everything goes to stderr.
+    signed_as=$(codesign --display --verbose "$file" 2>&1 | sed -n 's/^Identifier=//p')
+    if [ "$signed_as" != "$identifier" ] ; then
+        echo "FAIL: $file is signed as '$signed_as', not $identifier" >&2
+        exit 1
+    fi
+fi