Skip to content

手机批准电脑临时解锁 ​

日期:2026-11-16(新加坡时间)。本工作线仅使用合成数据、临时 PASSNO_HOME 和模拟授权;不访问真实保险库、真实钥匙串或签名私钥。

协议与取舍 ​

passno-approve 独立管理配对、挑战、传输。Mac 保存身份私钥和已核验的手机公钥,不保存手机解锁 AUK。配对码是 256 位随机的一次性载荷(120 秒),包含 Mac 公钥、名称和保险库;手机输入载荷并核对 Mac 指纹,Mac 再核对手机指纹,之后才把 AUK 用 HPKE 加密给手机。配对码不通过 Bonjour 发布。手机的长期能力由原生安全存储保护,不能通过 CLI/MCP 取出。

每次请求生成随机挑战和新的 X25519 临时密钥。Mac 签名绑定双方身份、保险库、用途、请求时间、120 秒批准窗口和绝对 30 分钟会话期限。手机核验后逐次通过授权器获得 AUK,使用临时公钥 HPKE 包裹并签名完整响应。daemon 仅接受当前挑战一次;替换请求、锁定、睡眠、锁屏、退出销毁挑战和临时私钥。使用行为不能延长手机批准期限。

网络为最多 32 KiB 的长度前缀 JSON;连接/读写均有限时,配对与后续消息都加密,已配对请求还必须验签。Bonjour 只发现端点,不能决定信任。手机不在 Mac 所在的网络时,同样的消息经 iCloud 中转(见本文最后“不在同一网络”一节),中转只运密文,验证全在 Mac 上。

研究来源与许可 ​

  • rust-hpke(MIT / Apache-2.0):阅读 single-shot/context API,依赖其 RFC 9180 实现,未自写 HPKE。
  • mdns-sd(MIT / Apache-2.0):参考 service registration / browse 生命周期;发现与身份验证分离。
  • curve25519-dalek(BSD-3-Clause):沿用已有 passno-crypto 的 Ed25519 / X25519 封装,不复制密码管理器代码。

Contract changes ​

  • passno-crypto::hpke:新增 RFC 9180 X25519/HKDF-SHA256/ChaCha20Poly1305 envelope;原 vault 的 epoch 包裹格式不变。原因:已有 epoch wrapper 是 ECIES 组合而非 RFC 9180,不能将其冒称 HPKE。
  • 新增 passno-approve,所有密码学只经 passno-crypto 调用。

需要用户本人 ​

  • 真实 Secure Enclave / Face ID 与钥匙串权限、跨设备局域网权限、主观界面验收。
  • CloudKit 容器、订阅和推送权限已配好(2026-11-16);真机上的推送和 iCloud 中转要本人验收。

daemon / IPC / 界面 ​

  • 桌面设置 → 安全 → iPhone 和 Apple Watch:点“配对 iPhone”显示二维码(daemon 用 qrcode 生成 SVG,内容是一次性配对载荷加这台 Mac 的局域网地址),iPhone 扫码(VisionKit)或粘贴(Mac 上“复制配对内容”经通用剪贴板),双向核对指纹,Mac 端每 2 秒自动刷新出 iPhone 指纹,确认后 iPhone 自动收下能力。2026-11-16 起配对不再关掉 Mac 的 Touch ID:配对主要用来在 iPhone / Apple Watch 上批准 agent 请求,丢掉 Touch ID 不划算。原来的严格模式改成配对后可选的开关“只能用 iPhone 解锁这台 Mac”(phone_approve 命令 unlock_only_on / unlock_only_off,标记文件 local/phone-approve/<vault 哈希>.unlock-only):打开时删除本机生物识别包裹能力、禁止注册和使用 Touch ID,锁屏和睡眠必定锁定;关闭后可在“安全”里重新开 Touch ID。主密码 + Secret Key 恢复不变。
  • 桌面锁定页已配对时出现「请 iPhone 批准解锁」,等待 120 秒并轮询状态,可取消。手机批准时事件推送刷新已有前端。
  • IPC 新增 phone_approve { command, fingerprint? },命令:status/pair/confirm/request/cancel/revoke。只允许已通过 PeerVerifier 的桌面可执行文件 passno / passno-desktop;CLI/MCP/agent 无此接口。响应只包含配对载荷、公钥指纹、端点和状态,不含 AUK。错误使用 PolicyDenied;传输断开不自动重放。
  • UnlockMethod 新增 phone;30 分钟同时使用绝对墙钟和单调时钟,修改 AutoLockSettings 不能移除期限;锁屏与休眠不受普通自动锁定开关影响。启动默认锁定,不恢复请求/临时私钥。
  • 监听(crates/passno-daemon/src/phone_listen.rs,2026-11-16 修:以前默认只开 loopback,配对信息里写的也是 127.0.0.1,真 iPhone 根本连不上):正式版监听所有网卡,端口第一次随机、之后固定(local/phone-approve/port),给手机的地址是 Mac 的局域网 IPv4(UDP 路由探测,不发包),Bonjour 用固定名字 passno-<主机名> 发布 _passno-unlock._tcp。调试版和测试只开 loopback,避免弹 macOS 防火墙提示;PASSNO_APPROVE_LISTEN=host:port 仍可覆盖。没配对过的设备发来的消息照样验签失败被拒绝。iPhone 连不上保存的地址时自动用 Bonjour 重新找 Mac 并记住能用的地址(withMac),找到的地址照样要过 Mac 公钥验证。
  • UniFFI PhoneApprovalClient 是本人原生 UI 专用:pair、receive_capability、restore、fetch_request、approve_request、deny_request。capsule 只能直接交给原生安全存储,不能接到 agent 接口。Swift PhoneCapabilityStoring 可注入;真机 SE P-256 ECIES + biometryCurrentSet 包裹 capsule,模拟器 Keychain + 明确标示的模拟 Face ID 按钮,不调用 LAContext。批准前再次加载能力并核对屏上请求未被替换。
  • 当前原生安全存储保留一组 Mac 配对(重新配对覆盖);手机查看请求也会读取受保护能力,真机可能需额外一次 Face ID。CloudKit 不会被启动。

构建与模拟验收 ​

sh
cargo test -p passno-approve
cargo test -p passno-daemon --test daemon_tests phone_approval_daemon_lifetime_and_recovery
# 唯一一次性合成库,路径必须尚不存在
PASSNO_HOME=/tmp/passno-phoneapprove-demo cargo run -p passno-daemon --example phone_approve_sim
# 上述终端接受 pair / confirm / request / status / lock / sleep / screen / quit
scripts/build-xcframework.sh --debug
cd apps/ios && xcodegen generate
xcodebuild -project Passno.xcodeproj -scheme PhoneApproveDemo -destination 'platform=iOS Simulator,name=iPhone 17 Pro' -derivedDataPath ../../target/phoneapprove-ios.noindex CODE_SIGN_IDENTITY=- CODE_SIGNING_REQUIRED=NO build

按 ios-testing skill 逐步使用 phone:安装 PhoneApproveDemo.app(bundle ID com.virtever.passno.phoneapprove),用 launch args --phone-approve-fixture /tmp/passno-phoneapprove-demo/offer.json 打开;点指纹一致配对;Mac harness 输入 confirm(模拟本人核对);手机点保存能力;harness 输入 request;手机查看请求、批准;harness status 应为 locked=false method=Some(Phone),screen 后应锁定。

演示 App 不创建 PassnoSession、不触碰原 App 的保险库和钥匙串命名空间。真实跨设备网络权限与最终 Face ID 验收留给用户;全部开发测试只在模拟器运行。

Contract changes(补充) ​

  • passno-ipc / Tauri 新增 phone_approve 与 UnlockMethod::Phone;不新增 pn 命令。
  • docs/dev/api.md 与 docs/dev/ipc.md 记录新增接口。
  • 未改 docs/plan.md(协调者所有);需要本人事项集中列在本文,供协调者合并。

手机入口位于设置和锁定页。Bonjour「查找局域网中的 Mac」只提供候选 IPv4 地址,随后仍须人工双向核对指纹;开发验收直接使用 loopback fixture,不请求真实局域网权限。生产 Bonjour 权限提示仅由用户显式点击发现时触发。

CloudKit 设计:私有数据库每个配对使用独立 record zone,记录只携带现有 Wire 密文、随机消息 ID、目标公钥指纹和短 TTL;订阅通知仅作为唤醒提示,不携带秘密。收到通知后拉取密文仍执行同一验签、challenge 单次消费和绝对到期检查;重复/乱序记录不能续期。CloudKit 服务端删除记录不是授权撤销依据,本地配对撤销后立即拒绝所有旧签名。APNs/后台唤醒不保证及时,离线/过期一律保持锁定。

已新增防回归检查 apps/ios/tests/check_phone_approve.py(模拟器不执行 LAContext、不落地明文文件、fixture 只在 Debug+Simulator 且限定临时路径,演示 App 不创建真实 Session);协议测试覆盖重启丢失请求、异常时间值与不匹配 Mac。

配对撤销删除 Mac 的信任记录并拒绝旧手机的网络消息;它不轮换 AUK、不替代整个账户的设备丢失吊销流程。手机已保存的旧能力在手机端仍可能存在,但 daemon 不再信任其批准。重新配对需要主密码会话。

验收记录(2026-11-16,新加坡时间) ​

  • cargo fmt --all -- --check、cargo clippy --workspace --all-targets -- -D warnings、cargo test --workspace 已通过。新增手机协议 / daemon / IPC 回归单独再跑;覆盖错误签名、错误 Mac/库、密文篡改、过期、重放、重启丢弃请求、传输限长、非桌面拒绝、连接丢失不重试,以及截止时清除临时私钥。
  • daemon 集成使用真实临时保险库、Unix IPC 和 loopback TCP,假时钟 / 假系统事件 / 假生物识别;关闭所有普通自动锁定设置后仍在第 1800 秒锁定,持续访问不续期,模拟 sleep/screen lock 仍锁定,主密码可恢复。
  • 桌面 npm run lint、npm test(25 项)、npm run build 已通过。首次并行编译时已有 30ms 搜索性能测试超时,空闲后按原阈值重跑通过,没有修改测试阈值。
  • iOS Debug 模拟器构建、未签名 generic iOS 真机目标编译均通过;check_security.py、check_localization.py、check_phone_approve.py 通过。未安装到真机、未调用真实 SE / LAContext / 签名私钥。
  • phone session passno-phoneapprove,iPhone 17 Pro 模拟器,独立 bundle com.virtever.passno.phoneapprove:输入一次性载荷 → 核对两端指纹(Mac 端由 harness 模拟)→ Keychain 保存能力 → Mac 请求时仍 locked=true → 手机「批准 · 模拟 Face ID」→ daemon locked=false method=Some(Phone) → 模拟锁屏后 locked=true method=None。再次发请求并点拒绝,daemon 仍锁定;关闭 harness 后刷新显示不可用,无假成功。
  • 截图:批准成功、拒绝。只包含合成测试库标识。phone 已 close,harness 已 quit。
  • 开发中发现演示 target 缺少 UILaunchScreen 导致黑边兼容窗口和坐标错位,已修复并加静态回归。另一次设备 slice 比模拟器少一个 UniFFI 方法,已重建两端;build-xcframework.sh 现在在打包前运行 check-ffi-symbols.py,本次 88 个导出符号一致。使用 nm --no-llvm-bc,避免 Xcode nm 读取新版 Rust 标准库 bitcode 时的版本不兼容。

尚未实测的边界 ​

  • 已实测 loopback 加密 TCP 与模拟器逐次批准;真实两台设备之间的 Bonjour multicast、局域网权限、后台唤醒和真实 Face ID / Secure Enclave 仍需本人验收。未触发这些权限提示。
  • iCloud 中转 2026-11-16 已做,见最后一节。
  • 当前只有一组手机/Mac 配对能力;跨设备权限、长期后台请求通知与多 Mac 配对管理不在这个切片的验收范围。

agent 请求审批(2026-11-16) ​

同一个配对通道也用来批准 agent 的密钥请求,详见 docs/dev/agent.md 的“在 passno App 里批准 agent 请求”一节。协议增量:Command::PollAgents、Command::AgentDecision { id, choice, at }、Reply::AgentRequests(SignedAgentRequests);Mac 签名请求列表,手机验签后才显示;决定靠配对通道的手机签名、30 秒时间窗和“只能决定一次”防重放。iOS:「批准 Mac」页新增「Agent 请求」一节,每次查看和决定都先 Face ID。

模拟器验收(2026-11-16,新加坡时间) ​

phone_approve_sim 新增 agent 命令,发起一个合成的 agent 请求(claude 要用「Synthetic API」做 GET api.example.test/v1/me)。在 sim:iPhone 17 Pro 上用 phone 逐步操作:配对 → Mac 端 confirm → 保存解锁能力 → agent → 「查看 agent 请求」显示 agent、条目、具体操作、用途 →「仅这一次」后 Mac 端收到 Approved { approved_ttl_ms: 60000 };再发一次请求点「拒绝」,Mac 端收到 Denied。截图:批准后。

验收中发现:两端界面都在自己解析操作的 JSON,而实际格式和假设不同({"kind":"http",…}),界面显示了原始 JSON。已改为后台进程直接发可读文字(ActionBinding::describe),客户端只翻译 ssh-sign、reveal-once 两个标记,并加了测试防止界面再去解析 JSON。

敏感条目(2026-11-16,模拟器实测): harness 输入 agent-sensitive,iPhone「查看 agent 请求」显示“敏感条目:每次使用都要你确认”,只有「仅这一次」和「拒绝」;点「仅这一次」后 Mac 端收到 Approved { approved_ttl_ms: 60000 }(一次性授权)。 2026-11-17 起,条目设了免确认次数(大于 1 次)时,签名请求里多一个 confirm_limit { window_ms, max_uses },批准按钮写明“批准(5 分钟内或 3 次内不再问)”,Mac 按这个窗口发授权,仍要 Face ID,快捷批准仍不能批。截图:敏感条目。

通知和 Apple Watch 上的批准(2026-11-16) ​

  • 为什么要第二把密钥: 主配对密钥锁在 Secure Enclave 里,每次使用都要 Face ID。手表上点按钮时 iPhone 在口袋里,没法刷 Face ID,所以配对时另外生成一把“快捷批准”密钥。
    • 由主密钥签名的 Command::RegisterQuickKey 登记到 Mac,Mac 存在 <vault哈希>.quick.json,解除配对时一起删除。
    • iPhone 把它存进钥匙串,访问级别为 AfterFirstUnlockThisDeviceOnly,这样锁屏时手表上的按钮也能用。
    • 快捷密钥的打包里没有解锁 Mac 用的 auk(FFI 的 QuickCapsule 和 restore_quick)。
  • Mac 端的限制(Mac::read_wire_signed 返回签名人,daemon 按签名人放行):快捷密钥只能 PollAgents,以及对不需要本人确认的请求发 AgentDecision。敏感条目、取出明文、解锁 Mac(Poll / Approve)一律拒绝,仍然只能用 iPhone 的 Face ID 或 Mac 的 Touch ID。
  • 通知:
    • 类别 AGENT_REQUEST 带“仅这一次”和“拒绝”两个按钮,iOS 会自动转到配对的 Apple Watch;
    • 类别 AGENT_REQUEST_OWNER 不带按钮,只能点开 App 处理;
    • userInfo / 推送载荷里放 request_id;
    • 按钮由 AgentNotificationResponder 处理(PassnoKit,发送决定的那一步可以注入,XCTest 3 项)。
  • 推送: 以后 CloudKit 推送用同样的载荷(aps.category 加 request_id)。在你开通 iCloud 容器之前,iPhone 不在前台时还收不到 agent 请求的通知。
  • 模拟器实测:
    • 配对后,系统弹出通知授权;
    • harness 输入 agent,打印出请求 id;
    • 用 xcrun simctl push 推送;在 SpringBoard 上长按横幅,出现“仅这一次 / 拒绝”;点“仅这一次”后 Mac 收到 Approved { approved_ttl_ms: 60000 },App 全程在后台。
    • 敏感请求即使收到被篡改成带按钮的推送,点“仅这一次”也会被 Mac 拒绝,请求继续等待本人确认。
    • 截图:通知按钮。
  • 测试: approval_tests.rs 的 quick_key_decides_ordinary_requests_only(普通请求能批、敏感请求被拒、快捷密钥不能参与解锁)。
  • 手表专用 App: 不需要。系统转发的通知按钮就够用;独立的 watchOS App 可以放到以后。

锁屏时在 iPhone 上批准 agent(2026-11-16) ​

用户要求:电脑锁屏后,agent 的请求能在手机上批准一段时间。

  • 流程: 保险库锁着,agent 的调用又不在已有长授权(24 小时 / 7 天 / 总是允许)范围内时,broker 返回“已锁定”。passnod 若配了 iPhone,就生成一个解锁请求,purpose 里装 AgentUnlockPurpose(JSON,kind: "agent":agent 名、用到的 pn:// 引用和动作、用途、可选时长、默认项;由 Mac 签名,只有元数据),最多等 90 秒(approve_on_phone_while_locked,crates/passno-daemon/src/server.rs)。
  • iPhone: “查看请求”一次 Face ID 拿到所有待处理请求;锁屏期间的 agent 请求显示成卡片(agent、引用和动作、用途、时长按钮),批准时发 Command::ApproveAgent { approval, choice }:approval 和手机解锁 Mac 用的完全一样(HPKE 把解锁材料加密给这次请求的一次性公钥,手机主密钥签名),只多一个时长。快捷批准键(通知 / 手表)不能发这个命令。
  • Mac: 收到后核对解锁材料确实能打开这个保险库,然后只为这次调用打开一份(Vault::open_with_auk → VaultAccess::Owner),用手机选的时长签发授权;锁着时批准的授权一律能在锁着时使用(条目副本只在内存里),所以选“24 小时 / 总是允许”后后续调用不再打扰手机。Mac 自己的会话始终保持锁定,桌面界面也不会解锁。
  • 规则: 锁着时“直到电脑锁定”没有意义,不提供;你的默认项不适用时预选“仅这一次”,绝不预选比你设置更宽的权限。对这类请求发普通的“解锁 Mac”批准会被拒绝;手机点拒绝,agent 立即收到拒绝;90 秒没人处理,agent 收到“待批准”。
  • 测试: crates/passno-daemon/tests/locked_phone_approval_tests.rs(真实配对和 TCP:手机看到 agent、引用、命令和用途;普通解锁批准被拒;批准 24 小时后 agent 成功、Mac 仍锁、第二次不再询问;拒绝立即返回)。模拟器上 phone_approve_sim 的 agent-locked 命令走同一流程,已实测:手机批准后 Locked agent call: ok、locked=true。
  • 推送(2026-11-16): 没有 passno 服务器。Mac App 在需要人决定时(锁屏时的 agent 请求,或解锁时的审批请求),往你自己 iCloud 的 CloudKit 私有数据库写一条空的 PassnoWake 记录(apps/desktop/src-tauri/src/phone_push.rs,15 秒内只发一次;写新的一条时删掉上一条,iCloud 里最多留一条);iPhone 配对后建立 CloudKit 订阅(PassnoKit/PhoneWake.swift),记录一出现系统就弹“有 agent 在等你批准”。记录里没有 agent、条目、命令或任何秘密;点开通知打开“查看请求”并自动拉取(一次 Face ID),详情仍经签名加密的手机通道从 Mac 取。只有签了 iCloud 权限、登录 iCloud 的 App 才会调 CloudKit(没有权限时调用会让 App 崩溃,所以先检查容器),开发版跳过。App ID 已开推送能力,iPhone 权限文件加了 aps-environment,Mac 的 Developer ID 描述文件已重新生成。
  • 菜单栏常驻: 关掉 Mac 窗口 passno 留在菜单栏(审批、浏览器扩展、推送照常工作),菜单有“打开 passno / 立即锁定 / 撤销所有 agent 授权 / 退出 passno”,点 Dock 图标重新打开窗口(apps/desktop/src-tauri/src/tray.rs)。
  • 测试: 节流单元测试;iOS 单元测试“点通知 → 打开请求列表”,“按钮只做决定、不打开列表”;模拟器上 simctl push 送出的通知显示正确(中文标题和正文);模拟器里合成的点击打不开通知,所以演示 App 有调试版启动参数 --simulate-wake-tap 代替系统投递点击,实测打开后自动拉到了锁屏时的 agent 请求。
  • 还差: 真机推送和 iCloud 中转要在真机上验收(模拟器没有登录 iCloud);发布前要在 CloudKit Console 把 PassnoWake、PassnoRelayCommand、PassnoRelayReply 三种记录类型部署到生产环境。

不在同一网络:经 iCloud 中转(2026-11-16) ​

推送能唤醒不在家的 iPhone,但以前批准本身只能走局域网。现在手机找不到 Mac 时,同一条消息经你自己的 iCloud 私有数据库转交,仍然没有 passno 服务器。

  • 运的是什么: 和局域网完全一样的帧。手机发的是用 HPKE 加密给 Mac、再用手机密钥签名的 Wire;Mac 回的是加密给手机的回复。iCloud(以及能看到这个数据库的任何人)只看到密文,改动或重放的帧在 Mac 上验签、查新鲜度时被拒,和局域网上被人截获的情况相同。不加新的密码学,不改保险库格式。
  • 两条记录: 手机把消息写进固定名字的 relay-cmd 记录(类型 PassnoRelayCommand,字段 id、frame,覆盖写);Mac 回复写进 relay-reply-<id>(类型 PassnoRelayReply,字段 frame),手机读到后删掉。名字固定,所以不用查询、不用索引。一次只有一条消息在路上(手机端加锁),每条消息有自己的 UUID,晚到的回复不会被认错。
  • Mac 什么时候看: Mac App 发出唤醒推送的同时(有 agent 请求或解锁请求在等人),开始每 2 秒看一次 relay-cmd,持续 3 分钟;平时不碰 iCloud。同一条消息只处理一次,存进 iCloud 超过 60 秒的不处理。拿到的帧经 IPC PhoneRelay 交给 passnod(只有桌面 App 能发),passnod 用处理局域网消息的同一个函数(phone_wire)处理。代码:crates/passno-approve/src/transport.rs(RelayMailbox、Relay、relay_frame),apps/desktop/src-tauri/src/phone_relay.rs(RelayInbox trait、CloudKit 实现、RelayPump)。
  • 手机什么时候用: 顺序是保存的局域网地址 → Bonjour 重新找 → iCloud。iCloud 刚用成功的 1 分钟内先走 iCloud,省掉连局域网的等待。通知上的“仅这一次 / 拒绝”按钮也是先局域网、不行再 iCloud。中转在 Rust 里是一种地址(phone_relay_endpoint(),值为 icloud-relay),iOS 在启动时用 set_phone_relay 装上 CloudKit 实现(PassnoKit/CloudKitPhoneRelay.swift,存取记录在 RelayRecordStore 协议后面,测试用假实现)。一次中转最多等 15 秒。
  • 测试: passno-approve 的协议测试(中转帧和局域网一样被验、密文里看不到命令)、passnod 的锁屏批准测试 away_from_home_the_iphone_approves_through_the_relay(经 PhoneRelay 批准、Mac 保持锁定、途中被改的帧没有回复)、FFI 测试(icloud-relay 地址经装好的中转到达 Mac,没装时直接报错)、Mac 端 phone_relay 单元测试(每条只处理一次、过期和被拒的不回复、后台轮询)、iOS CloudKitPhoneRelayTests 和通知按钮回退测试。真实 iCloud 来回要真机验收。

活动记录(2026-11-16) ​

iPhone 的每个决定都进 Mac 的活动记录(approval_decided),写明方式:主密钥(面容 ID)是 iphone,通知或 Apple Watch 的快捷批准是 iphone_quick,Mac 锁定时在 iPhone 上批的是 iphone_while_mac_locked(90 秒没人回答记一条 grant_pending)。配对、解除配对、注册快捷批准密钥、“只能用 iPhone 解锁”开关、经 iPhone 批准解锁 Mac 也都记录。见 docs/dev/activity.md。

文档对应提交 56d1c45 · 由仓库 docs/ 自动生成