Appearance
本地守护进程(passnod)与系统解锁(passno-unlock)
本文记录 v0.2 阶段 2 的守护进程架构、内存加固、自动锁定策略、系统解锁器、打包与自启机制,以及需要由本人在电脑前完成的人机验证项。
详细 IPC 线协议与 Peer 验证见 IPC 协议说明,密钥分层见 设计文档 第 4 节。
1. 组件分工与 crate 边界
passno-ipc:Unix domain socket 传输($PASSNO_HOME/run/passnod.sock,运行目录0700,socket0600)、4 字节大端长度前缀 JSON 帧、PeerVerifier(macOSLOCAL_PEERTOKEN+SecCodeCopyGuestWithAttributes+ Team IDQKPMA8N9LJ校验;LinuxSO_PEERCRED)、IpcPassnoClient(实现PassnoService)与自动拉起(connect_or_spawn_daemon)。passno-unlock:Unlockertrait 与两种实现:PasswordUnlocker、BiometricUnlocker。SecretKeyStoremacOS 钥匙串实现(MacKeychainSecretKeyStore,使用kSecAttrSynchronizable = true写入 iCloud 钥匙串)与FallbackSecretKeyStore(钥匙串不可用、被锁定或自定义测试PASSNO_HOME时自动回退到$PASSNO_HOME/secret.keyFileSecretKeyStore)。BiometricProvidertrait 与MacBiometricProvider(objc2-local-authenticationLAContext+DeviceOwnerAuthenticationWithBiometricsOrCompanion)。- 强制主密码校验状态保存在
$PASSNO_HOME/local/unlock_policy.json:通过可注入的Clock与BootIdProvider(macOS 读取kern.bootsessionuuid)执行重启后必须输主密码、超过 14 天必须输主密码、指纹集变化(evaluatedPolicyDomainState哈希对比)、新设备/缺少本地包裹密钥、或保险库安全头摘要变更检测。
passno-daemon(二进制passnod):- 仅在
passnod进程内持有已解锁的Vault与 AUK(LockedKeyBuffer尝试region::lock/mlock,Drop时zeroize;进程启动即执行RLIMIT_CORE = 0,macOS 调用PT_DENY_ATTACH,Linux 调用PR_SET_DUMPABLE = 0)。 - 所有 GUI(Tauri)和 CLI(
pn)并发请求通过单一Mutex<DaemonCore>串行化并持久化到操作日志,写操作成功后通过广播通道向subscribe客户端推送vault_changed、vault_unlocked、vault_locked事件。 AutoLockController与SystemEventMonitor(macOS 监听CFNotificationCenterGetDistributedCenter的com.apple.screenIsLocked/com.apple.screensaver.didstart与 IOKitIORegisterForSystemPower的kIOMessageSystemWillSleep)在空闲超时(默认 900 秒)、最大会话时长(默认 28800 秒 / 8 小时)、息屏锁屏或睡眠时立刻锁定并清零内存密钥。
- 仅在
2. 客户端接入(pn CLI 与 Tauri 桌面端)
- CLI(
pn):- 默认通过
IpcPassnoClient::with_auto_spawn连接或按需拉起$PASSNO_HOME/run/passnod.sock。解锁一次后,同一个终端会话内后续pn list/add/edit/show/rm/totp无需重复输入主密码;别的会话要自己授权(见下文“命令行的主人授权按终端会话”)。 - 提供
--no-daemon全局参数绕过passnod,以单命令本地进程模式运行(测试及应急维护使用)。未传--no-daemon且无法找到或连接passnod时返回固定退出码7(DaemonUnavailable)。 - 新增
pn lock与pn unlock --biometrics;pn doctor会检查守护进程连通性、PID、Peer 验证模式、锁定状态与生物识别注册状态。
- 默认通过
- 桌面端(
apps/desktop/src-tauri):AppState::open_default()使用IpcPassnoClient::with_auto_spawn;spawn_vault_watcher订阅守护进程推送事件,并将vault_changed/vault_unlocked/vault_locked桥接为前端vault-changed(锁定同时附带vault-locked)。- 应用启动(仅 macOS
.appbundle 内,非测试模式且未设置PASSNO_SKIP_LOGIN_ITEM=1)通过SMAppService::Agent注册Contents/Library/LaunchAgents/com.virtever.passno.daemon.plist开机自启,ad-hoc 本地包未获授权时自动回退到写入~/Library/LaunchAgents/com.virtever.passno.daemon.plist。
- 打包(
scripts/build-mac.sh):- 构建 release 版
pn与passnod一并作为 sidecar 打包进Contents/MacOS/pn与Contents/MacOS/passnod,并嵌入Contents/Library/LaunchAgents/com.virtever.passno.daemon.plist。 - 支持环境变量
PASSNO_SIGN_IDENTITY(默认-本地 ad-hoc 签名;提供正式证书时加--options runtime --timestamp),内层二进制签名后再做--deep验签。
- 构建 release 版
3. Contract changes
本阶段保持已有 API 与前端协议向后兼容,新增或扩展的契约如下(供后续模块与 data / ui 集成参考):
passno-vault新增导出方法(仅增不改):Vault::init_returning_auk、Vault::open_returning_auk、Vault::open_with_auk、Vault::header(&self) -> &VaultHeader。原有Vault::init与Vault::open签名与语义不变。
passno-service新增导出方法(仅增不改):LocalPassnoService::with_secret_key_store、LocalPassnoService::secret_key_store、LocalPassnoService::set_unlocked_vault、LocalPassnoService::is_unlocked、LocalPassnoService::loaded_vault_id。PassnoServicetrait 19 个方法签名完全不变。
- Tauri 桌面端(
apps/desktop/src-tauri):- 已有 25 条命令的名称、入参、返回值 DTO 字段与错误码完全保留未动。
- 新增可选命令(5 条):
daemon_status、unlock_with_biometrics(reason?)、enroll_biometrics、disable_biometrics、set_auto_lock_settings(settings)。 - 新增推送事件:守护进程锁定时在发送
vault-locked(载荷LockReason:manual/idle_timeout/max_session_duration/system_sleep/screen_locked/shutdown)的同时继续发射vault-changed,确保未更新前端代码即可触发状态刷新。
pnCLI:- 新增全局参数
--no-daemon、子命令pn lock、pn unlock --biometrics,以及退出码7(DaemonUnavailable/PeerDenied)。已有 CLI tests(v0.1 独立本地模式验证)在测试辅助函数里显式传入--no-daemon,并新增守护进程不可达退出码7与pn <-> passnod全流程集成测试。
- 新增全局参数
4. 开源实现参考与取舍
开发本阶段前检索并对比了与设计文档同源的开源项目架构:
rbw(MIT):参考其 CLI 短连接 -> 长驻 agent socket 守护进程自动拉起与空闲超时锁定架构;不同之处在于passnod采用 4 字节长度前缀 JSON 帧并强制校验客户端进程签名身份,而不是仅依赖 UID。Secretive(MIT)与 AppleLocalAuthentication文档:参考 macOS 钥匙串 +LAContext+biometryCurrentSet策略;由于本地开发/CI 没有 Apple Developer Provisioning Profile,Data Protection 钥匙串访问控制(.biometryCurrentSet)会在 ad-hoc 构建上返回errSecMissingEntitlement,因此实现为"优先 Data Protection Keychain +.biometryCurrentSet,无 entitlement 时回退本机登录钥匙串 + 显式LAContext::evaluatePolicy与evaluatedPolicyDomainState校验",签名后可无痛切换。kbs2/tsm:参考核心转储禁用(RLIMIT_CORE = 0)与mlock+zeroize内存清零实践,并在RLIMIT_MEMLOCK受限的容器/CI 环境降级为不阻断启动但保留zeroize。
5. 需要用户本人
以下真实系统硬件/权限项无法在无头远程终端或无证书 CI 环境中自动完成验证,需本人在 Mac 电脑前操作:
- Touch ID / Apple Watch 实机生物识别验证:
- 在已安装且包含有效签名的 macOS 会话中运行桌面端或
pn unlock一次,调用enroll_biometrics,验证系统 Touch ID / Apple Watch 弹窗与指纹变更后强制要求输入主密码的行为。
- 在已安装且包含有效签名的 macOS 会话中运行桌面端或
- macOS 钥匙串(iCloud 钥匙串)与登录项弹窗:
- 首次启用 Keychain 存储 Secret Key 或首次注册
SMAppService登录项时,确认系统弹出的钥匙串"允许 / 始终允许"以及"系统设置 -> 通用 -> 登录项"中passno后台权限开关。
- 首次启用 Keychain 存储 Secret Key 或首次注册
- macOS 系统睡眠与锁屏真机联调:
- 解锁保险库后执行系统"锁定屏幕"或合盖休眠,唤醒后检查
pn status --json确认已自动锁定并清空内存 AUK。
- 解锁保险库后执行系统"锁定屏幕"或合盖休眠,唤醒后检查
- 正式 Apple Developer ID(
QKPMA8N9LJ)打包签名与公证验收:- 在配置好签发证书的机器上执行
PASSNO_SIGN_IDENTITY="Developer ID Application: ... (QKPMA8N9LJ)" ./scripts/build-mac.sh,验收codesign --verify --deep --strict、正式 Peer 团队签名校验策略(RequireTeamSignature)以及 Data Protection Keychain 的.biometryCurrentSet硬件绑定。
- 在配置好签发证书的机器上执行
命令行的主人授权按终端会话(2026-11-16)
问题(已修): 以前保险库一解锁,同一用户的任何进程都能经 pn 以主人身份操作:列出全部条目、读验证码、用 script 伪造终端后 pn show --reveal 看明文、修改条目、创建服务令牌。AI agent 有 shell 就能绕开 agent 的权限和审批。是在调研 1Password CLI 时发现的,用真实程序复现过。
现在:
- passnod 把除桌面 App(
passno、passno-desktop)和passno-nmhost(只在验过签名的 Chrome 下运行)以外的调用方都当成命令行。命令行发来的主人请求(cli_session::requires_owner_session:条目、明文、TOTP、附件、历史、回收站、导入、共享、agent 管理、生物识别设置等)必须持有调用方所在终端会话的授权。状态、锁定、生成密码、密文同步、agent 代理请求(自带 agent 凭据或服务令牌)不需要。 - 会话 = Unix 会话号(
getsid)加会话首进程的启动时间,会话号被复用也继承不到旧授权(cli_session.rs,macOS 用proc_pidinfo,Linux 读/proc;其他平台退化为只授权单个进程)。终端标签页、tmux 窗格、SSH 登录各是一个会话;实测 Claude Code 的工具 shell 是独立会话、没有终端。 - 获得授权:在该会话里
init/unlock/unlock --biometrics/ 从同步位置恢复(都要主密码或本人生物识别);或已解锁时发AuthorizeCliSession:带主密码(--password-stdin),或在 Mac 上弹 Touch ID / Apple Watch / 登录密码(提示里写出调用链,如“pn ← zsh ← claude”);在终端里失败了再让人输主密码。2026-11-16 起没有终端的会话也会弹(用户要求:在 Claude Code 里! pn unlock、或 agent 的 shell 用到主人命令时,不该让人再切去自己的终端):pn的主人命令(list、add等)发现会话没授权就自动请求确认,你按指纹即只授权那一个会话。为防后台程序反复弹窗:同一时间只弹一个;你取消后,同一会话 60 秒内再请求直接拒绝(CliSessions::begin_prompt/prompt_done)。取消或拒绝仍返回CliSessionRequired(退出码 3),脚本和 agent 只需处理这一种情况。 - 授权 10 分钟不用或满 12 小时失效,锁定时全部作废。错误码
CliSessionRequired,pn退出码 3。 pn whoami显示这个终端会话有没有授权(发不带密码、不弹窗的AuthorizeCliSession,有授权时会刷新空闲计时)。- agent 的
pn run/pn http/pn mcp/pn ssh-agent带PASSNO_AGENT_KEY或PASSNO_SERVICE_TOKEN时,前端不做主人会话检查,直接把凭据交给 passnod 验证(2026-11-16 修:之前前端先做主人检查,agent 在自己的 shell 里会被拒)。 - 回归测试:
crates/passno-daemon/tests/cli_session_tests.rs(用setsid模拟 agent 的独立会话)。调试版可设PASSNO_TEST_USER_VERIFIER=deny|allow让自动化测试不弹 Touch ID;正式版没有这个开关。会启动 passnod 的测试都必须设它(tools/ci/check-test-verifier.sh检查,2026-11-16:改了这条规则后,旧测试在用户屏幕上弹出了真的 Touch ID)。 - 活动记录(2026-11-16):终端会话获得主人授权时,passnod 记一条
cli_session_authorized(方式:在这个终端解锁 / 主密码 / Touch ID 等本人确认,以及调用链)。解锁方式、锁定原因、iPhone 配对、审批决定等其他记录点见docs/dev/activity.md。