Repository navigation
feat(desktop): add conditional macOS Developer ID signing and notarization - #9226
loopx-agent wants to merge 1 commit into
Conversation
…ation Signed-off-by: LoopX Agent <[email protected]>
loopx-agent
left a comment
There was a problem hiding this comment.
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 v2MacConfig.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.
Summary
Enable conditional macOS Developer ID signing and Apple notarization across both
.github/workflows/desktop-release-artifacts.ymland.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
scripts/desktop_macos_signing.py):APPLE_CERTIFICATE,APPLE_CERTIFICATE_PASSWORD,APPLE_ID,APPLE_PASSWORD,APPLE_TEAM_ID) plus optionalKEYCHAIN_PASSWORDandAPPLE_SIGNING_IDENTITY.signing_mode=developer_id): omits"signingIdentity":"-"so Tauri v2 signsLoopX.appwith Developer ID Application + Hardened Runtime and notarizes/staplesLoopX.appbefore packagingLoopX.app.zipand updater.app.tar.gz; generates an ephemeral masked randomKEYCHAIN_PASSWORDif unset; unsets emptyAPPLE_SIGNING_IDENTITYplaceholders so Tauri auto-detects the certificate identity; notarizes and staples.dmgviaxcrun notarytool submit --waitandxcrun stapler staple; verifiescodesign --verify --deep --strict --verbose=2,^Authority=Developer ID Application:,spctl --assess,xcrun stapler validate,hdiutil verify, and updater.app.tar.gzticket/signature members (Contents/CodeResourcesandContents/_CodeSignature/CodeResources).signing_mode=adhoc): strips Apple signing env vars, retains"signingIdentity":"-", and verifies^Signature=adhoc$+codesign --verify --deep --strict(+hdiutil verifyfor.dmg).exit 1with::error title=Incomplete Apple signing configuration::naming present/missing keys without secret values)..github/workflows/desktop-release-artifacts.yml,.github/workflows/desktop-updater.yml):Resolve macOS signing mode,Build ...,Notarize macOS disk image(desktop-release-artifacts.ymldeveloper_idonly), andVerify macOS ...in both non-PR macOS workflows.pull_requestpreview builds strictly--no-signwith zero Apple secrets.apps/desktop/loopx-control-plane/README.md):System Settings → Privacy & Security → Open Anywayorxattr -dr com.apple.quarantine /Applications/LoopX.app, avoiding Gatekeeper's default Move to Trash).examples/desktop-release-workflow-smoke.py,tests/desktop/test_desktop_signing_workflow.py,tests/desktop/test_update_feed.py):developer_id,adhoc, partial-secret fail-fast, ephemeralKEYCHAIN_PASSWORDfallback, emptyAPPLE_SIGNING_IDENTITYcleanup, and PR unsigned isolation.src-tauriUpdater Compatibility VerifiedInspected
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, andtests/signed_bundle.rs:minisign-verify/tauri-plugin-updater), independent of Apple Developer ID signing.signature_verifies/installed_bundle_verifies(codesign --verify --deep --strict) and swapped atomically viareplace_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— passeduv 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— passeduv run --extra test python -m mypy& strictmypyon changed Python scripts/tests — passeduv run --extra test python scripts/check_rfc_bilingual.py --base origin/main --head HEAD— passedloopx check --scan-path ...(7 changed files) —errors=0, warnings=0(public boundary scan clean)change-qualityCQR (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