Skip to content

feat(desktop): add conditional macOS Developer ID signing and notarization - #9226

Open
loopx-agent wants to merge 1 commit into
mainfrom
codex/macos-developer-id-notarize-20261122
Open

loopx-agent wants to merge 1 commit into
mainfrom
codex/macos-developer-id-notarize-20261122

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

Summary

Enable conditional macOS Developer ID signing and Apple notarization across both .github/workflows/desktop-release-artifacts.yml and .github/workflows/desktop-updater.yml, while preserving ad-hoc integrity builds when Apple signing secrets are absent and failing closed on partial secret configurations.

Changes

  • Shared macOS signing/notarization/verification helper (scripts/desktop_macos_signing.py):
    • Inspects the 5 core Apple secrets (APPLE_CERTIFICATE, APPLE_CERTIFICATE_PASSWORD, APPLE_ID, APPLE_PASSWORD, APPLE_TEAM_ID) plus optional KEYCHAIN_PASSWORD and APPLE_SIGNING_IDENTITY.
    • All 5 core secrets set (signing_mode=developer_id): omits "signingIdentity":"-" so Tauri v2 signs LoopX.app with Developer ID Application + Hardened Runtime and notarizes/staples LoopX.app before packaging LoopX.app.zip and updater .app.tar.gz; generates an ephemeral masked random KEYCHAIN_PASSWORD if unset; unsets empty APPLE_SIGNING_IDENTITY placeholders so Tauri auto-detects the certificate identity; notarizes and staples .dmg via xcrun notarytool submit --wait and xcrun stapler staple; verifies codesign --verify --deep --strict --verbose=2, ^Authority=Developer ID Application:, spctl --assess, xcrun stapler validate, hdiutil verify, and updater .app.tar.gz ticket/signature members (Contents/CodeResources and Contents/_CodeSignature/CodeResources).
    • All 5 core secrets unset (signing_mode=adhoc): strips Apple signing env vars, retains "signingIdentity":"-", and verifies ^Signature=adhoc$ + codesign --verify --deep --strict (+ hdiutil verify for .dmg).
    • Partially configured (1–4 of 5 core secrets): fails fast (exit 1 with ::error title=Incomplete Apple signing configuration:: naming present/missing keys without secret values).
  • Workflows (.github/workflows/desktop-release-artifacts.yml, .github/workflows/desktop-updater.yml):
    • Wired Resolve macOS signing mode, Build ..., Notarize macOS disk image (desktop-release-artifacts.yml developer_id only), and Verify macOS ... in both non-PR macOS workflows.
    • Kept pull_request preview builds strictly --no-sign with zero Apple secrets.
  • Documentation (apps/desktop/loopx-control-plane/README.md):
    • Documented conditional Developer ID + Apple Notarization for releases and updater bundles, confirmed updater compatibility across ad-hoc -> Developer ID transitions, and added macOS Sequoia 15+ first-launch instructions for ad-hoc builds (System Settings → Privacy & Security → Open Anyway or xattr -dr com.apple.quarantine /Applications/LoopX.app, avoiding Gatekeeper's default Move to Trash).
  • Tests & Smokes (examples/desktop-release-workflow-smoke.py, tests/desktop/test_desktop_signing_workflow.py, tests/desktop/test_update_feed.py):
    • Updated workflow smoke and updater tests and added unit + CLI + workflow-structure tests covering developer_id, adhoc, partial-secret fail-fast, ephemeral KEYCHAIN_PASSWORD fallback, empty APPLE_SIGNING_IDENTITY cleanup, and PR unsigned isolation.

src-tauri Updater Compatibility Verified

Inspected apps/desktop/loopx-control-plane/src-tauri/tauri.conf.json, src/update_backup.rs, src/macos_update.rs, src/maintenance.rs, src/prepared_update.rs, and tests/signed_bundle.rs:

  • In-app update archives are verified with Tauri's embedded minisign public key (minisign-verify / tauri-plugin-updater), independent of Apple Developer ID signing.
  • Extracted candidates and rollback backups are validated via signature_verifies / installed_bundle_verifies (codesign --verify --deep --strict) and swapped atomically via replace_bundle (renameat_with(..., RenameFlags::EXCHANGE) / ditto), with no ad-hoc-only restriction, supporting seamless transitions from ad-hoc builds to Developer ID + notarized releases.

Local Verification

  • uv run --extra test python examples/desktop-release-workflow-smoke.py — passed (desktop-release-preflight-smoke: 9 semantic cases passed, desktop-release-workflow-smoke: ok)
  • uv run --extra test python -m unittest discover -s tests/desktop -p 'test_*.py' — passed (Ran 40 tests ... OK)
  • python3 -m unittest discover -s tests/desktop -p 'test_*.py' — passed (Ran 40 tests ... OK)
  • uv run --extra test pytest -q --basetemp /private/tmp/sub1-macos-bt tests/desktop/ — passed (40 passed, 45 subtests passed)
  • uv run --extra test python examples/release-artifacts-smoke.py & examples/desktop-icon-alpha-smoke.py — passed
  • uv run --extra test python -m ruff check tests loopx/canary loopx/control_plane loopx/domain_packs loopx/presentation scripts/desktop_macos_signing.py examples/desktop-release-workflow-smoke.py — passed
  • uv run --extra test python -m mypy & strict mypy on changed Python scripts/tests — passed
  • uv run --extra test python scripts/check_rfc_bilingual.py --base origin/main --head HEAD — passed
  • loopx check --scan-path ... (7 changed files) — errors=0, warnings=0 (public boundary scan clean)
  • Goal-bound change-quality CQR (personal-loopx-maintenance): cqr_2eb936097810c57d73ac (status=valid, decision=pass, scope_fingerprint=2eb936097810c57d73ac98de67424f6512ae89f4c756ea69732d0ff09c286d3b)
  • loopx canary premerge --from-git-diff --git-diff-base origin/main --goal-id personal-loopx-maintenance — gate.status=passed, merge_gate_passed=true, selected_check_count=19, failure_count=0, manual_hold_count=0

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · Gemini · Google · self_reported

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

动机 / Motivation

受影响方为桌面端 macOS 发布维护者,以及直接下载安装包或通过内置更新器接收热更新的 macOS 终端用户。改动前即使仓库已经具备 Apple 签名与公证凭据,发布和更新工作流仍固定写入临时自签身份而跳过公证,导致用户首次打开应用被系统拦截;改动后只要 5 项核心 Apple 密钥全部就绪,构建阶段就会自动使用 Developer ID 证书与硬化运行时签名并完成应用和磁盘镜像的公证与离线装订校验,而在全部 5 项密钥缺失时保持原有的临时完整性签名回退行为。具体而言,在基线 06fd6feeab 的 .github/workflows/desktop-release-artifacts.yml 与 .github/workflows/desktop-updater.yml 中,所有非 PR macOS 构建都硬编码了 signingIdentity="-" 的 ad-hoc 签名且完全没有 Apple 公证(notarization),导致 macOS Sequoia 15+ 首次打开会弹出默认指向 Move to Trash 的 Gatekeeper 警告。可观测改进为:PR 预览构建严格保留无签名模式且完全不接触 Apple 密钥;非 PR 构建在 5 项核心密钥全缺失时保留临时自签及基础完整性校验,在 5 项全齐时自动签发并装订公证票据且通过严格系统评估门禁,而在仅配置 1 至 4 项时以非零状态立即阻断并仅输出缺失变量名。本 PR 边界明确不包含在仓库中预设真实证书或凭据、不改动桌面端 Rust 更新器或 Windows 安装包签名逻辑,也不改变任何 PR 预览构建的未签名隔离策略。

改动思路 / Approach

工作流层由 github.event_name != 'pull_request' && runner.os == 'macOS' 严格隔离 PR 预览构建,策略与执行层则收口到纯标准库共享工具 scripts/desktop_macos_signing.py。将状态判定、环境清洗、DMG 公证与验签不变量收拢进单一纯标准库辅助脚本,两份工作流仅负责触发条件控制与环境变量传递,职责清晰且无冗余持久化状态。在具体执行链上,resolve_apple_signing 从 5 个核心环境变量(APPLE_CERTIFICATE、APPLE_CERTIFICATE_PASSWORD、APPLE_ID、APPLE_PASSWORD、APPLE_TEAM_ID)推导出瞬态输出 signing-mode(developer_id 或 adhoc),cmd_build 用 --expected-mode 复核后再构造 Tauri --config JSON 与清洗后的子进程环境,随后串联 notarize-dmg(仅 developer_id 下在 release workflow 执行)和 verify 门禁。

独立检索基线与当前 head 的 scripts/desktop_*.py 与两份 desktop workflow 可知:desktop_release_artifacts.py 负责 DESKTOP-SHA256SUMS 清单,desktop_update_feed.py 负责 minisign 与 desktop-updater.json feed,desktop_runtime_bundle.py 负责内嵌 Python 运行时归档,三者均与平台代码签名正交,因此统一收口到 scripts/desktop_macos_signing.py 并复用是合理的边界分离。当前 PR 交付完整的条件签名、公证、验签、文档与本地契约测试切片,真实证书密钥的配置与首次托管公证验证留在 PR 之外。

构建场景 核心 Apple secrets 实际动作与产物门禁
pull_request 预览 禁止访问任何 secrets.* 仅运行 npm run build -- --bundles ... --no-sign,跳过公证与签名校验
非 PR(全缺失 / 全空白) 0 / 5 signing_mode=adhoc:剥离全 7 个 Apple 变量,注入 signingIdentity:"-",校验 Signature=adhoc 与 hdiutil verify
非 PR(全齐) 5 / 5 signing_mode=developer_id:生成 masked KEYCHAIN_PASSWORD,清除空 APPLE_SIGNING_IDENTITY,Tauri 签名并公证装订 .app,工作流另对 .dmg 执行 notarytool --wait + stapler staple,全量校验 codesign、Authority=Developer ID Application:、spctl、stapler validate、hdiutil 与 updater .app.tar.gz 内 Contents/CodeResources
非 PR(半配置) 1–4 / 5 立即抛出 AppleSigningConfigError 以退出码 1 阻断,仅列缺失/在场键名且零密钥值泄露

具体改动 / Changes

本次共变更 7 个文件(+1364 / -47 行):生产代码包括 scripts/desktop_macos_signing.py(+484)、.github/workflows/desktop-release-artifacts.yml(+46/-7)与 .github/workflows/desktop-updater.yml(+39/-1);文档为 apps/desktop/loopx-control-plane/README.md(+51/-11);测试与 smoke 为 tests/desktop/test_desktop_signing_workflow.py(+572)、examples/desktop-release-workflow-smoke.py(+169/-26)与 tests/desktop/test_update_feed.py(+3/-2)。关于需求规格对照:基线仓库的 docs/product/release-readiness.md 与 docs/architecture/rfcs/desktop-execution-frontends-v0.md 仅记录此前 macOS 为 ad-hoc 未公证状态,并不存在针对本次条件签名助手机制的独立成文规格文档,因此以两份既有 workflow 契约与 Tauri v2 实际打包机制作为对照基线。

核对上游 Tauri v2(tauri-cli 与 tauri-bundler)源码可以确认两点关键工程细节:第一,tauri-cli 会通过 env::var_os("APPLE_SIGNING_IDENTITY") 读取环境变量,GitHub Actions 对未设置的 optional secret 传入空字符串会触发签名身份匹配问题;第二,tauri-bundler 会在构建 .app 后为其签名、公证、装订(写入 Contents/CodeResources)并先打包出 updater .app.tar.gz,随后对 .dmg 仅做 codesign 签名而不提交 .dmg 公证(且 tauri-macos-sign::staple_app 未显式检查 stapler 退出码)。这正好解释了为何必须由 prepare_build_env 剔除空 APPLE_SIGNING_IDENTITY,并由 notarize-dmg 与 verify 补全 .dmg 公证装订及 .app/.dmg/.app.tar.gz 装订校验。

关键代码讲解

  • resolve_apple_signing(scripts/desktop_macos_signing.py:74):扫描 CORE_APPLE_SECRETS 的非空白存在性,仅当全为空时返回 adhoc、全齐时返回 developer_id;若 KEYCHAIN_PASSWORD 未设或空白则通过 secrets.token_urlsafe(32) 生成临时密码,若 APPLE_SIGNING_IDENTITY 为空则设为 None。任何 1–4 项半配置立即抛出 AppleSigningConfigError,保证异常中仅包含环境变量名。
  • tauri_build_config(scripts/desktop_macos_signing.py:118):基于 SEMVER_RE 校验版本号并拼装传给 tauri build --config 的 JSON。仅在 adhoc 模式下写入 bundle.macOS.signingIdentity="-",在 developer_id 模式下主动省略该键以启用 Tauri 原生证书签名与 Hardened Runtime(Tauri v2 MacConfig.hardened_runtime 默认 true)。
  • prepare_build_env(scripts/desktop_macos_signing.py:144):在 adhoc 模式下剥离全部 7 项 ALL_APPLE_VARS 防止环境变量残留;在 developer_id 模式下注入解析得到的 KEYCHAIN_PASSWORD(并在 cmd_build 中对自动生成的密码输出 ::add-mask::),同时移除空 APPLE_SIGNING_IDENTITY 以免干扰证书自动发现。
  • notarize_dmg_commands(scripts/desktop_macos_signing.py:168):生成 xcrun notarytool submit ... --wait 与 xcrun stapler staple 命令序列,配合 _redact_argv 将报错命令中的 --password 参数脱敏为 ***,供 cmd_notarize_dmg 顺序执行。
  • verification_commands 与 verify_updater_tar_gz(scripts/desktop_macos_signing.py:253):按签名模式构造分层命令门禁——developer_id 校验 .app 与 .dmg 的 codesign、^Authority=Developer ID Application:、spctl --assess、xcrun stapler validate、hdiutil verify,以及 updater .app.tar.gz 及其 .sig 配对和 LoopX.app/Contents/CodeResources / _CodeSignature/CodeResources 存在性;adhoc 仅校验 ^Signature=adhoc$、codesign --verify --deep --strict 与 hdiutil verify。

对主干的风险 / Risks

本次无阻塞性缺陷。通过独立构建负例并对照基线验证:30 种 1–4 核心密钥半配置组合全部以退出码 1 拒绝且不打印密钥值;--expected-mode 跨步失配会在构建前阻断;notarize-dmg 失败报错已对 --password 掩码;pull_request 路线在基线与 head 均保持 --no-sign 且零 secrets.* 引用;本机 macOS spctl --assess --type open --context context:primary-signature --verbose=4 参数语法也已实测有效。就作用域与语义而言,所有生产入口均直接挂载于两份官方工作流,SigningMode 仅用于本 helper 内部而未改动任何共享控制面词汇表或持久化状态,default_off_isolation 在未配置 secrets 时与基线完全等价,也不涉及新增 Actor 生命周期或权限语义。

剩余非阻塞边界与最弱覆盖点在于:本地评审环境没有真实的 Apple Developer ID 证书与 Notary 账号凭据,因此真实的证书导入、Apple 远程公证扫描及真签产物上的 spctl --assess 仍待仓库 secrets 就绪后的首次托管构建来实测。另外两处非阻塞细节值得后续顺手微调:verify_updater_tar_gz(scripts/desktop_macos_signing.py:263)可用 removeprefix("./") 代替 lstrip("./") 以更精确剥离前缀;tests/desktop/test_update_feed.py:122 中的 macos_step 字符串切片跨越了新增的校验与收集步骤,虽然目前断言仍能命中且 test_desktop_signing_workflow.py 已按步精确解析 YAML,收窄切片终点会让测试意图更清晰。此外 PR 描述正文的 Local Verification 字段附带了一处维护者本地工作上下文标识符,但已确认 7 个仓库变更文件本身完全洁净、无任何私有群聊/成员名或本机路径。

我的整体评价 / Verdict

从长程演化(long_horizon)来看,已核对 src-tauri/src/macos_update.rs 与 update_backup.rs:应用内更新校验仅依赖内嵌 minisign 公钥与 codesign --verify --deep --strict,不存在 ad-hoc 限定限制,能够无缝承接从旧 ad-hoc 版本向 Developer ID 公证版本的原地升级与原子回滚(decision: preserved)。从终端用户体验与运维视角(user_experience)来看,本 PR 打通了正式包签名公证与 Sequoia 15+ ad-hoc 引导文档,已检查全部 7 个改动文件与桌面端 README,本次仅修改工作流配置、签名辅助脚本、测试与说明文档,未改变任何渲染界面或截图展示(visual_review: not_applicable,unverified_scope: none)。

综合可观测语义、代码体积与隔离评估(observable_semantics: intentional_change_validated、code_volume: necessary、change_proportionality: proportionate、default_off_isolation: isolated、authority_semantics: not_applicable、semantic_alignment: not_applicable / local_only),我们在隔离的 exact-head(d92fd4effb8914c6408831c6e3b485b3f23262a0)工作树独立复跑了全部本地检查:desktop 单元测试 40 passed, 45 subtests passed (PASS)、desktop-release-workflow-smoke.py (PASS)、release-artifacts-smoke.py & desktop-icon-alpha-smoke.py (PASS)、ruff check & mypy --strict & 全仓 mypy (PASS)、check_rfc_bilingual.py (PASS)、7 文件 loopx check 公开边界扫描 0 error/0 warning (PASS)、独立负例测试 (PASS),以及在挂载 node_modules 后的 canary premerge 19/19 条校验全通过(PASS,其中因临时隔离工作树不带作者本地收据而提示收据状态,未 consulted 远程 CI);唯一未执行项为依赖真实 Apple 凭据的远程公证与真签 spctl 验证(UNVERIFIED)。综上,同意批准此精确提交。

英文简短结论

English verdict: APPROVE at head d92fd4effb8914c6408831c6e3b485b3f23262a0. No blocking findings; shared scripts/desktop_macos_signing.py cleanly enforces all-or-nothing 5-secret Developer ID signing/notarization, ad-hoc fallback, fail-closed partial config rejection, empty APPLE_SIGNING_IDENTITY cleanup, and strict PR --no-sign isolation across both desktop workflows. Local validation passed (tests/desktop/ 40 tests / 45 subtests PASS, desktop-release-workflow-smoke.py PASS, ruff & mypy PASS, loopx check clean, 30-subset negative counterfactuals PASS, canary premerge 19/19 checks PASS); live Apple Notary/Developer ID cryptographic execution remains UNVERIFIED locally pending repository secrets.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant