Appearance
macOS 发布工程
更新:2026-11-16(UTC+8)。本分支负责发布工具,不升级产品版本、不推送、不合并、不部署。工作区目前仍为 0.1.0;协调者合并功能分支、完成验收后再升版。本轮保留 agy 的实现并修正无人值守签名、通用架构清单、发布顺序和许可证缺失检查。
需要用户本人
| 事项 | 当前状态 / 下一步 |
|---|---|
| Developer ID 私钥授权 | 未尝试正式 codesign。本机可能弹出“允许”,用户不在场时不得探测或重试。本人先准备能无交互签名的钥匙串/私钥 ACL,再由发布负责人设置 PASSNO_SIGNING_READY=1。仅解锁钥匙串并不保证不会弹窗 |
| App 与 DMG 的公证 / staple / Gatekeeper | 本轮只做 ad-hoc dry-run,正式公证未执行。凭据缺失、拒绝或需要账户处理时停止此步,保留日志,不自动循环 |
| Keychain 访问组与 iCloud 容器 | 2026-11-16 已完成:App ID com.virtever.passno(iOS + macOS 通用)开了 iCloud(容器 iCloud.com.virtever.passno)、App Groups(group.com.virtever.passno)、自动填充;Developer ID 描述文件“passno Mac Developer ID”已生成并放在 ~/.passno-release/passno.provisionprofile。它包含钥匙串访问组和 iCloud 容器(icloud-container-environment = Production),说明 Developer ID 分发的 Mac 版也能用 iCloud 文档容器。签名时用 passno-app-keychain.entitlements.plist;脚本先核对描述文件确实授予这些权限,缺了就报错,避免签出打不开的 App。描述文件到期或改了 App ID 能力后要重新生成(App Store Connect API:POST /v1/profiles,类型 MAC_APP_DIRECT) |
| passnod 的钥匙串权限 | 2026-11-17 已完成:App ID com.virtever.passno.daemon(Mac)和 Developer ID 描述文件“passno daemon Developer ID”(~/.passno-release/passnod.provisionprofile,到 2027-02-01,授予 keychain-access-groups = QKPMA8N9LJ.*),都是用 App Store Connect API 生成的。到期后用同样方法重新生成(POST /v1/profiles,类型 MAC_APP_DIRECT,证书是 Developer ID Application) |
| 第三方安全审计和升级体验验收 | 需本人/协调者确定审计方,在干净机器验证首次安装、升级授权、Touch ID 与回滚。短 fuzz 和 Apple 公证都不代替审计 |
| 发布密钥备份 | agy 已创建 ~/.passno-release/updater.key(0600);本轮复用并通过签名验证公钥配对。本人应离线备份;丢失后旧客户端不能验证新 key 的更新 |
以上按工作线约定记录在本页,docs/plan.md 留给协调者更新。
构建与 dry-run
前提:macOS、Xcode Command Line Tools、Rust stable、Node 22+、Python 3.11+、cargo-about,桌面 npm 依赖已安装。本机优先 Apple Silicon,通用包另需 rustup target add x86_64-apple-darwin。
bash
(cd apps/desktop && npm ci)
python3 scripts/release/gen-licenses.py
scripts/release/bump-version.sh --check
PASSNO_HOME="$(mktemp -d /tmp/passno-release.XXXXXX)" \
scripts/release/mac-release.sh --arch aarch64 --dry-run
scripts/release/publish-update.sh --dir target/release-artifacts.noindex/0.1.0 --dry-run--dry-run 仍进行真实编译、ad-hoc 签名、归档和 hdiutil DMG 打包,绝不碰 Developer ID 或提交公证,也不发布。stdin 关闭并设置 CI;更新签名密码显式为空或从环境/受保护文件读取,不询问密码。缺更新 key 时 dry-run 可生成标为 DRY_RUN_UNSIGNED 的清单;正式发布不允许。输出有 DRY_RUN 标记,发布器即使带 --publish 也拒绝。
产物默认在 target/release-artifacts.noindex/<版本>/:DMG、.app.tar.gz、.sig、SHA256SUMS.txt、latest.json。.app 只在打包期间存在;正常结束后删除,避免 Spotlight 出现第二个 App。失败后可能在 .noindex 留待诊断,不要把它当正式安装包。自定义 --out-dir 请使用绝对路径且位于 .noindex 目录内。
scripts/build-mac.sh 保留 v0.1 默认安装行为和单 bundle 保证。工作线测试只用 --no-install,产物放 target/bundle.noindex/;本轮不触碰 /Applications/passno.app、用户 CLI 软链和真实保险库。两个入口都自动发现当前 Cargo workspace 的 pn / passnod / passno-nmhost,存在才编译打包;通用包用 lipo 合并 sidecar。本分支目前只有 pn,其余在合并后重新验收。
正式签名和公证
用户先确认私钥无交互可用后,负责人运行(不能把此环境变量当成自动检测结果):
bash
PASSNO_SIGNING_READY=1 scripts/release/mac-release.sh --arch universal流程:先构建 ad-hoc App,再由内到外签所有 Contents/MacOS helper 和 App,启用 Hardened Runtime 与 secure timestamp;App ZIP 经 notarytool submit --wait 后 staple;随后生成已 staple App 的更新归档;hdiutil create 生成 DMG,签名、公证、staple,最后对 App/DMG 跑 spctl -a -vv 和 stapler validate。不调用会启动 Finder/osascript 的 Tauri DMG bundler。失败立即退出,无重试授权。
签名身份为 Developer ID Application: Feng Chen (QKPMA8N9LJ)。ASC 从 ~/.appstoreconnect/glass.env 的 GLASS_ASC_KEY_ID / GLASS_ASC_ISSUER 和对应的 private_keys/AuthKey_<id>.p8 读取;不会输出内容。PASSNO_ASC_ENV 可覆盖路径。
entitlements 在 scripts/release/entitlements/:App 允许 WebKit JIT 和网络;pn、passno-nmhost 仅网络;都没有 get-task-allow 或 disable-library-validation。存在 ~/.passno-release/passno.provisionprofile(或 --provision-profile)时才给 App 加 QKPMA8N9LJ.com.virtever.passno 访问组。
passnod 是辅助 App(2026-11-17): Secret Key、Touch ID 包裹密钥、iCloud 钥匙串里的恢复包都由 passnod 存取,它们都在数据保护钥匙串里,要 keychain-access-groups 这类受限权限;受限权限必须有描述文件,而只有包(bundle)才能嵌入描述文件(苹果文档《Signing a daemon with a restricted entitlement》)。所以发布脚本把 Tauri 放在 Contents/MacOS/passnod 的程序移进 Contents/Library/Helpers/passnod.app(App ID com.virtever.passno.daemon,嵌入 passnod.provisionprofile,用 passnod.entitlements.plist 签名,访问组和 App 相同),原位置留一个指向它的符号链接,自动拉起、登录项、pn 都照旧从 Contents/MacOS/passnod 找。经符号链接启动时系统同样认辅助 App 的描述文件(2026-11-17 用探针实测:不带权限写数据保护钥匙串返回 -34018,装进辅助 App 后直接启动和经链接启动都成功)。签完后脚本检查 passnod.app 确实带访问组,没有就中止发布。
此前 passnod 是不带权限的普通程序,发布版里:开 iCloud 备份报“本地文件读写失败”(恢复包写不进 iCloud 钥匙串);Secret Key 只存进本机钥匙串,iPhone 拿不到;Touch ID 包裹密钥退回到不受生物识别保护的旧式钥匙串项。都没有任何提示。还没覆盖的: pn 的同步命令和本地模式也会直接读写钥匙串,pn 仍是普通程序,这些路径在发布版里只能用本机钥匙串(后续:改走 passnod,或也做成辅助 App)。
CI 只在托管 macOS runner 上运行。正式模式需要 APPLE_CERTIFICATE(p12 base64)、APPLE_CERTIFICATE_PASSWORD、ASC_KEY_ID、ASC_ISSUER_ID、ASC_KEY_P8、TAURI_SIGNING_PRIVATE_KEY,以及可选 provisioning profile / updater password secrets。工作流创建临时钥匙串、授权 codesign、结束时删除;tag 必须与 workspace 版本一致。只创建 draft GitHub Release,不部署 Cloudflare。
版本、更新和托管
Cargo.toml [workspace.package].version是唯一权威。bump-version.sh 0.2.0同步 workspace crate(含旧字面量)、Tauri、桌面 package/lock、已存在的 extension manifest/package/lock,并生成 Conventional Commits 更新日志。Chrome 用纯数字版号,预发布名放version_name。支持--check、--print、--no-changelog。脚本需要 Python 3.11+;首次无 tag 时会收集全部历史,正式发布前编辑确认更新日志范围。- 插件注册限于启动位置的几行;依赖为桌面 target 专用。公钥写在 Tauri 配置,不新增 agent 明文接口、不新增前端 updater capability。设置页“检查/安装更新”由 UI 集成,插件本身不会自动联网或安装。
- 与 Developer ID 独立的 minisign key 在仓库外。初始化新机器用
scripts/release/init-updater-key.sh(拒绝覆盖现有 key);首次设置应写入新公钥并安全备份,不能随意重新生成,否则旧版失去升级能力。 - 更新签名用
--app-version,客户端requireSignedVersion=true,发布前用 Tauri 同款minisign-verify库验签。JSON 清单本身不是单独签名;被签的是归档及可信版本注释。通用包同时声明darwin-aarch64和darwin-x86_64,不用客户端不会请求的darwin-universal。 publish-update.sh默认仅校验;明确--publish才上传。拒绝 dry-run、校验和不符、错版本、未知平台、异常 URL 和签名不符;只上传白名单文件,所有归档完成后才更新latest.json,然后 HTTPS 读回核对。
使用 R2 避免 Worker 静态资源单文件大小限制,也避免文档站重新部署覆盖历史更新。部署模板为 scripts/release/wrangler.jsonc / updates-worker.mjs,仅路由 passno.virtever.com/updates/*,其他 URL 仍由原文档站处理。尚未创建 bucket、路由或部署,由协调者在发布时执行:
bash
# All Cloudflare writes wait for coordinator approval; these are instructions only.
cd site
./node_modules/.bin/wrangler r2 bucket create passno-updates
./node_modules/.bin/wrangler deploy --config ../scripts/release/wrangler.jsonc
cd ..
scripts/release/publish-update.sh --dir target/release-artifacts.noindex/0.2.0 --publish使用拥有 R2 写权限的 CLOUDFLARE_API_TOKEN,不能误用仅 DNS token。运行发布器前必须配置好 HTTPS 路由,不会自动触发登录。首次发布及保留旧更新包的端到端验收由协调者执行。
安全、许可证与测试
security.yml 执行 cargo-deny、cargo audit、桌面/已存在扩展的 production npm audit、版本和许可证一致性、发布脚本回归测试。fuzz.yml 夜间分别 fuzz 1pux、CSV、保险库/同步文件和 IPC 模型,使用 ASan、资源上限与合成 seeds;变异语料放被忽略的 fuzz/corpus/,不把成千上万个临时变异文件提交为 seed。
IPC 和手机通道(2026-11-16 更新): ipc_framing 改为调用真实的 passno_ipc::read_frame(daemon 读的 IpcRequest、客户端读的 IpcServerMessage),解出来的消息再编码一次核对;新增 phone_wire,测 Mac 从局域网读到的未认证数据(帧、Wire 解码、Mac::join / Mac::read_wire)。本机各跑 60 秒无崩溃:ipc_framing 223,461 次,phone_wire 1,968,881 次。详见威胁模型和审计清单。
Rust 许可证用 cargo-about,npm 用随仓库发布的 lockfile/license checker:production 许可只允许明确白名单,缺正文直接失败,包含 MIT / Apache 双许可证各自正文及字体许可。react-remove-scroll-bar@2.3.8 npm 包缺正文,上游 master 8ca9ba5ea52de03308fe8ced94f7b159a44d28ff 的 LICENSE 补存于 scripts/release/licenses/(其 npm gitHead 已不可访问);升级版本需重新核对。EFF 和 Apple PMR 的署名来自仓库原 NOTICE/LICENSE,生成 THIRD_PARTY_LICENSES.md 和 App resource JSON。JSON 的 cargo/npm/data 条目通过 text_hashes 关联正文,设置 → 关于 → 开源许可读取这份 JSON(Tauri 命令 third_party_licenses / license_text,先列组件,点开才取正文);licenses.rs 的测试核对每个组件都有正文、EFF 署名在列。
崩溃报告(2026-11-16)
商用标准要求"默认关闭、用户同意才上传、不含任何保险库内容"。passno 没有服务器,所以做法是:只在本机写报告,从不自动上传,由用户自己复制后发出去。
- crate
passno-diag:install(app, version)装 panic hook,先存报告再交给原来的 hook,存失败不影响原来的行为。CrashReportStore是接口,DirReportStore是按文件夹的实现(每份一个 JSON,权限 0600,只留最新 20 份),测试时换成临时文件夹。 - 接入:
passno(桌面 App)、passnod、pn、passno-nmhost启动时都调用install。iOS 不接:崩溃由 Apple 的"与 App 开发者共享"(用户在系统设置里同意)送达。 - 报告里有什么: App 名、版本、系统、CPU、时间、出错的源码位置、调用栈里的函数名。panic 消息只在它是字面量(
panic!("...")不带参数)时保留;带格式的消息(包括所有unwrap/expect在错误上的消息)可能带运行时数据,一律丢掉。家目录换成~。 - 放在哪: macOS
~/Library/Logs/passno/crashes/,其他系统在本地数据目录下;PASSNO_CRASH_DIR可以改(测试用)。 - 怎么看: 设置 → 关于 → 崩溃报告(每条可复制,可全部删除;没有报告时只一行说明),或
pn crashes ls|show|clear(见 CLI 参考)。 - 不覆盖: 原生崩溃(段错误等)由系统的崩溃报告处理;前端 JS 错误不记录。
- 参考: human-panic(MIT / Apache-2.0):本机写报告、让用户自己决定发不发;Sentry 的
before_send:发出前先脱敏。我们比两者更严:只保留编译期固定的文字,不用依赖。 - 测试:
crates/passno-diag/tests/reports.rs(带运行时机密的expect不进报告、调用栈只留帧行、0600、裁剪)、桌面crash_reports.rs单元测试、src/test/crash-reports.test.tsx(加载前不渲染、空状态、复制、全部删除);2026-11-16 用 IPC 测试桥加合成报告在真实界面看过。
参考实现
2026-11-16 查阅以下许可兼容的上游文档/源码组织,没有从 GPL/AGPL 应用复制代码:
- Tauri updater 文档与 tauri-action(MIT / Apache-2.0):平台映射、归档签名和 CI 分发步骤;另外核查本机 2.14.1 updater 源码的可信版本注释验证。
- cargo-about(MIT / Apache-2.0):许可证正文汇总结构。
- cargo-fuzz(MIT / Apache-2.0):真实 parser harness、ASan、corpus 与 crash artifact 分离。
Contract changes
没有修改服务 API、CLI 或保险库格式。新增发布合同为:workspace 版本权威、资源 JSON schema v1、HTTPS 更新路径、签名绑定版本、R2 Worker 路由。Cargo.toml/lock 的 zip 9.6 及 importer 文件名 Result 适配继承 agy 的安全依赖更新;请 data/import 协调者合并时保留。Tauri Cargo 仅增加 updater 依赖并继承版本,lib.rs 仅接入插件;撤回 agy 扩大的前端 capability。新增安全文档目录的侧栏登记属于本站文档集成。
macOS 自带 Bash 3.2 在 set -u 下展开空数组会报错。本轮 dry-run 捕获此问题,已改为有默认参数的签名数组和兼容的可选参数展开;发布器 dry-run 回归测试固定该场景,正式 App 主程序名从 Info.plist 读取。
验证记录
2026-11-16,本机 macOS 26.6.2 / arm64:
| 检查 | 结果 |
|---|---|
cargo fmt --all、cargo clippy --workspace --all-targets -- -D warnings、cargo test --workspace | 通过,69 项测试 / 28 组结果(含空 doc-test 组) |
桌面 npm run lint、npm test、npm run build | 通过,13 项前端测试 |
cargo audit、cargo deny check、npm audit --omit=dev | 退出 0;Rust 两项非阻断上游警告见威胁模型,npm 0 漏洞 |
四个 cargo +nightly fuzz run,每个约 16 秒 | 无 crash:1pux 32,535 次、CSV 27,721 次、sync 文件 130,031 次、IPC 模型 1,877,686 次;不代表正式 IPC 或同步传输覆盖 |
| Python 发布工具测试 / Node Worker 测试 | 14 项 / 3 项通过;含签名验证、改包后重算 SHA-256 仍拒绝、dry-run 禁发、系统 Bash 可选参数、版本/扩展 lock 一致性 |
ShellCheck、Actionlint、许可证 --check、版本 --check | 通过 |
mac-release.sh --arch aarch64 --dry-run | 完整构建、ad-hoc 签名、更新签名、hdiutil DMG、清单与校验和生成通过 |
更新发布 --dry-run / 实物复核 | 公钥验签通过,篡改拒绝;DMG hdiutil verify 通过,只读挂载后 App 严格验签、arm64 pn --help、许可证资源逐字节核对通过;挂载已卸载 |
scripts/build-mac.sh --no-install | 通过;只在 target/bundle.noindex/ 留产物,未改安装目录和 CLI 软链 |
文档站 npm run build / Worker wrangler deploy --dry-run | 通过,未部署 |
本地日志在 target/release-checks/(忽略,不提交),试制产物在 target/release-artifacts.noindex/0.1.0/,带 DRY_RUN,不可公开发布。正式签名/公证、Intel/universal 实机、Linux/Windows、更新界面端到端、扩展依赖审计(本分支尚无 extension package-lock)和 GitHub 托管 CI 运行尚未验证。
CI 只在发布时运行(2026-11-16)
GitHub Actions 额度用到 90%,用户要求改为发布时才触发:Rust、安全扫描、桌面前端、文档同步、文档站部署这些 workflow 只在推 v* 标签(或手动 Run workflow)时运行;模糊测试只能手动触发;发布流程仍由 v* 标签触发。平时:
- 推送前本机跑
scripts/check-all.sh(含 Linux 交叉 clippy、前端、插件、文档同步、文档站构建、依赖审计)。 - 文档站用
scripts/deploy-docs.sh在本机部署。