Add CI and macOS signing workflow

emeisazam · emeisazam · commit a0d67db44047 · 2026-06-29T10:58:43.000-05:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Python, Web, and macOS checks
+    runs-on: macos-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install Python dependencies
+        run: uv sync --extra dev
+
+      - name: Run Python tests
+        run: |
+          uv run python -m unittest discover -s tests
+          uv run pytest -q
+
+      - name: Compile Python modules
+        run: uv run python -m compileall -q aear harness bench_adapter scripts tests
+
+      - name: Check dashboard JavaScript
+        run: node --check aear/static/app.js
+
+      - name: Build macOS shell
+        working-directory: apps/macos
+        run: |
+          swift build
+          swift build -Xswiftc -strict-concurrency=complete
+
+      - name: Package unsigned app
+        run: apps/macos/script/package_unsigned.sh
+
+      - name: Release smoke
+        run: scripts/release_smoke_with_stub.sh
diff --git a/README.md b/README.md
@@ -299,6 +299,8 @@ into memory.
 
 See `docs/native-macos-shell.md` for the SwiftPM package layout, run script,
 menu bar behavior, optional hotkey format, and current native-shell limits.
+See `docs/macos-signing-notarization.md` for Developer ID signing,
+notarization, and release packaging.
 
 ## Architecture Notes
 
diff --git a/apps/macos/script/notarize.sh b/apps/macos/script/notarize.sh
@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+APP_NAME="hmm"
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DIST_DIR="$ROOT_DIR/dist"
+PACKAGE_DIR="$DIST_DIR/package"
+APP_BUNDLE="$PACKAGE_DIR/$APP_NAME.app"
+SIGNED_ARCHIVE="$DIST_DIR/$APP_NAME-macos-signed.zip"
+NOTARIZED_ARCHIVE="$DIST_DIR/$APP_NAME-macos-notarized.zip"
+NOTARY_PROFILE="${NOTARY_PROFILE:-hmm-notary}"
+NOTARY_TIMEOUT="${NOTARY_TIMEOUT:-30m}"
+
+if [[ ! -f "$SIGNED_ARCHIVE" ]]; then
+  "$ROOT_DIR/script/package_signed.sh" >/dev/null
+fi
+
+if [[ ! -d "$APP_BUNDLE" ]]; then
+  echo "app bundle not found: $APP_BUNDLE" >&2
+  exit 1
+fi
+
+codesign --verify --strict --verbose=4 "$APP_BUNDLE"
+
+auth_args=()
+if [[ -n "${NOTARY_KEY:-}" && -n "${NOTARY_KEY_ID:-}" ]]; then
+  auth_args+=(--key "$NOTARY_KEY" --key-id "$NOTARY_KEY_ID")
+  if [[ -n "${NOTARY_ISSUER:-}" ]]; then
+    auth_args+=(--issuer "$NOTARY_ISSUER")
+  fi
+else
+  auth_args+=(--keychain-profile "$NOTARY_PROFILE")
+fi
+
+xcrun notarytool submit "$SIGNED_ARCHIVE" "${auth_args[@]}" --wait --timeout "$NOTARY_TIMEOUT"
+xcrun stapler staple "$APP_BUNDLE"
+xcrun stapler validate "$APP_BUNDLE"
+spctl -a -vv -t execute "$APP_BUNDLE"
+
+rm -f "$NOTARIZED_ARCHIVE"
+(
+  cd "$PACKAGE_DIR"
+  ditto -c -k --keepParent "$APP_NAME.app" "$NOTARIZED_ARCHIVE"
+)
+
+echo "$NOTARIZED_ARCHIVE"
diff --git a/apps/macos/script/package_signed.sh b/apps/macos/script/package_signed.sh
@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+APP_NAME="hmm"
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DIST_DIR="$ROOT_DIR/dist"
+PACKAGE_DIR="$DIST_DIR/package"
+APP_BUNDLE="$PACKAGE_DIR/$APP_NAME.app"
+SIGNED_ARCHIVE="$DIST_DIR/$APP_NAME-macos-signed.zip"
+
+find_default_identity() {
+  security find-identity -p codesigning -v \
+    | sed -n 's/.*"\(Developer ID Application: .*\)"/\1/p' \
+    | head -n 1
+}
+
+SIGNING_IDENTITY="${SIGNING_IDENTITY:-$(find_default_identity)}"
+if [[ -z "$SIGNING_IDENTITY" ]]; then
+  cat >&2 <<'EOF'
+No Developer ID Application signing identity was found.
+
+Install a Developer ID Application certificate in your login keychain, or set:
+  SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)"
+EOF
+  exit 1
+fi
+
+"$ROOT_DIR/script/package_unsigned.sh" >/dev/null
+
+if [[ ! -d "$APP_BUNDLE" ]]; then
+  echo "app bundle not found: $APP_BUNDLE" >&2
+  exit 1
+fi
+
+sign_args=(--force --timestamp --options runtime --sign "$SIGNING_IDENTITY")
+if [[ -n "${HMM_MACOS_ENTITLEMENTS:-}" ]]; then
+  sign_args+=(--entitlements "$HMM_MACOS_ENTITLEMENTS")
+fi
+
+codesign "${sign_args[@]}" "$APP_BUNDLE"
+codesign --verify --strict --verbose=4 "$APP_BUNDLE"
+
+rm -f "$SIGNED_ARCHIVE"
+(
+  cd "$PACKAGE_DIR"
+  ditto -c -k --keepParent "$APP_NAME.app" "$SIGNED_ARCHIVE"
+)
+
+echo "$SIGNED_ARCHIVE"
diff --git a/docs/macos-signing-notarization.md b/docs/macos-signing-notarization.md
@@ -0,0 +1,157 @@
+# macOS Signing and Notarization
+
+This repo can build a local unsigned app without Apple credentials. Public
+distribution outside the Mac App Store needs a Developer ID Application
+certificate, hardened runtime signing, notarization, and ticket stapling.
+
+## Current Local State
+
+The inspected local artifact is:
+
+```text
+apps/macos/dist/hmm.app
+```
+
+Current signing state on this machine:
+
+- `codesign -dvvv --entitlements :- apps/macos/dist/hmm.app` reports an ad hoc
+  signature.
+- `security find-identity -p codesigning -v` reports `0 valid identities found`.
+- `spctl -a -vv apps/macos/dist/hmm.app` fails before notarization because the
+  artifact is not Developer ID signed.
+
+This is expected for the unsigned development archive.
+
+## What You Need From Apple
+
+1. Join the Apple Developer Program if the account is not already enrolled.
+2. Use the Account Holder role to create a Developer ID Application
+   certificate. Apple also offers Developer ID Installer certificates, but this
+   repo ships a zipped `.app`, so the Application certificate is the required
+   first credential.
+3. Install the downloaded `.cer` in Keychain Access. It must appear under
+   `My Certificates` with its private key.
+4. Create notarization credentials:
+   - Recommended local path: store credentials in Keychain with `notarytool`.
+   - CI path: use an App Store Connect API key file (`.p8`), key id, and issuer
+     id as CI secrets. Individual API keys omit issuer id.
+
+## Store Notary Credentials Locally
+
+Use a Keychain profile named `hmm-notary`:
+
+```bash
+xcrun notarytool store-credentials hmm-notary \
+  --apple-id "you@example.com" \
+  --team-id "TEAMID"
+```
+
+`notarytool` will prompt for an app-specific password if you do not pass
+`--password`.
+
+For API-key based authentication:
+
+```bash
+xcrun notarytool store-credentials hmm-notary \
+  --key /secure/path/AuthKey_KEYID.p8 \
+  --key-id KEYID \
+  --issuer ISSUER-UUID
+```
+
+For Individual API Keys, omit `--issuer`.
+
+## Build a Signed Archive
+
+After installing the Developer ID Application certificate:
+
+```bash
+apps/macos/script/package_signed.sh
+```
+
+The script auto-detects the first `Developer ID Application:` identity. To pin a
+specific identity:
+
+```bash
+SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)" \
+  apps/macos/script/package_signed.sh
+```
+
+Output:
+
+```text
+apps/macos/dist/hmm-macos-signed.zip
+```
+
+The script signs with:
+
+- `--options runtime`
+- `--timestamp`
+- Developer ID Application identity
+
+No App Sandbox entitlement is applied. This app launches a local daemon and uses
+ScreenCaptureKit/system audio APIs; sandboxing should be reviewed as a separate
+product decision, not added casually for Developer ID distribution.
+
+## Notarize and Staple
+
+With a stored Keychain profile:
+
+```bash
+apps/macos/script/notarize.sh
+```
+
+With direct API key environment variables:
+
+```bash
+NOTARY_KEY=/secure/path/AuthKey_KEYID.p8 \
+NOTARY_KEY_ID=KEYID \
+NOTARY_ISSUER=ISSUER-UUID \
+  apps/macos/script/notarize.sh
+```
+
+For Individual API Keys, leave `NOTARY_ISSUER` unset.
+
+Output:
+
+```text
+apps/macos/dist/hmm-macos-notarized.zip
+```
+
+The script submits the signed zip with `xcrun notarytool submit --wait`, staples
+the ticket to `hmm.app`, validates the staple, runs Gatekeeper assessment with
+`spctl`, and creates a final zip from the stapled app.
+
+## Validation Commands
+
+```bash
+security find-identity -p codesigning -v
+codesign -dvvv --entitlements :- apps/macos/dist/package/hmm.app
+codesign --verify --strict --verbose=4 apps/macos/dist/package/hmm.app
+xcrun stapler validate apps/macos/dist/package/hmm.app
+spctl -a -vv -t execute apps/macos/dist/package/hmm.app
+```
+
+## CI Notes
+
+CI should not store a Developer ID private key unless release automation is
+explicitly required. The current CI workflow builds and packages unsigned
+artifacts only. To add signed CI releases later, store these as repository or
+environment secrets:
+
+- `MACOS_CERTIFICATE_P12_BASE64`
+- `MACOS_CERTIFICATE_PASSWORD`
+- `APPLE_NOTARY_KEY_P8_BASE64`
+- `APPLE_NOTARY_KEY_ID`
+- `APPLE_NOTARY_ISSUER_ID` for Team API Keys
+
+Create a temporary keychain inside the release job, import the certificate,
+run `apps/macos/script/package_signed.sh`, then run
+`apps/macos/script/notarize.sh`.
+
+## References
+
+- Apple Developer Program: https://developer.apple.com/programs/
+- Developer ID certificates: https://developer.apple.com/help/account/certificates/create-developer-id-certificates/
+- Create a private key: https://developer.apple.com/help/account/keys/create-a-private-key
+- Notarizing macOS software: https://developer.apple.com/documentation/security/notarizing-macos-software-before-distribution
+- Customizing notarization workflow: https://developer.apple.com/documentation/security/customizing-the-notarization-workflow
diff --git a/docs/release-readiness.md b/docs/release-readiness.md
@@ -6,12 +6,6 @@ unsigned local archive. It does not claim the app is signed or notarized.
 
 ## Local Release Check
 
-Start the stub daemon in one terminal:
-
-```bash
-uv run hmm --profile stub --host 127.0.0.1 --port 8765
-```
-
 Run the full local release check from the repository root:
 
 ```bash
@@ -25,11 +19,13 @@ This runs:
 - Dashboard JavaScript syntax check when `node` is available.
 - Native macOS build-and-launch verification.
 - Release-mode unsigned app packaging.
-- `scripts/release_smoke.py` against the running daemon and local app archive.
+- `scripts/release_smoke_with_stub.sh`, which starts a stub daemon, waits for
+  `/health`, runs `scripts/release_smoke.py`, and shuts the daemon down.
 
 For a read-only smoke check after packaging:
 
 ```bash
+uv run hmm --profile stub --host 127.0.0.1 --port 8765
 scripts/release_smoke.py --server http://127.0.0.1:8765
 ```
 
@@ -70,12 +66,13 @@ regression testing, but it is not a signed public distribution artifact.
 
 For signed distribution, the next packaging work must add:
 
-- A Developer ID Application signing identity.
-- Hardened runtime settings.
-- Entitlement review for ScreenCaptureKit, automation, and launch-at-login use.
-- Signing of the app bundle and any nested helper code.
-- Notarization with `notarytool`.
-- Stapling and Gatekeeper verification with `spctl`.
+- A Developer ID Application signing identity installed in Keychain.
+- Notary credentials stored through `notarytool` or passed as API-key
+  environment variables.
+- `apps/macos/script/package_signed.sh`.
+- `apps/macos/script/notarize.sh`.
+
+See `docs/macos-signing-notarization.md` for the exact setup and commands.
 
 ## Rename And Migration Notes
 
diff --git a/scripts/release_smoke_with_stub.sh b/scripts/release_smoke_with_stub.sh
@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+HOST="${HMM_HOST:-127.0.0.1}"
+PORT="${HMM_PORT:-8765}"
+SERVER="http://$HOST:$PORT"
+LOG_FILE="${HMM_SMOKE_LOG:-/tmp/hmm-release-smoke.log}"
+export UV_CACHE_DIR="${UV_CACHE_DIR:-.uv-cache}"
+
+cleanup() {
+  if [[ -n "${SERVER_PID:-}" ]] && ps -p "$SERVER_PID" >/dev/null 2>&1; then
+    kill "$SERVER_PID" >/dev/null 2>&1 || true
+    wait "$SERVER_PID" >/dev/null 2>&1 || true
+  fi
+}
+trap cleanup EXIT
+
+uv run hmm --profile stub --host "$HOST" --port "$PORT" >"$LOG_FILE" 2>&1 &
+SERVER_PID="$!"
+
+uv run python - "$SERVER/health" <<'PY'
+from __future__ import annotations
+
+import sys
+import time
+from urllib.error import URLError
+from urllib.request import urlopen
+
+url = sys.argv[1]
+deadline = time.monotonic() + 20
+while time.monotonic() < deadline:
+    try:
+        with urlopen(url, timeout=1) as response:
+            if response.status == 200:
+                raise SystemExit(0)
+    except URLError:
+        time.sleep(0.25)
+raise SystemExit(f"daemon did not become healthy: {url}")
+PY
+
+scripts/release_smoke.py --server "$SERVER"
diff --git a/scripts/run_local_checks.sh b/scripts/run_local_checks.sh
