Skip to content

本地守护进程(passnod)与系统解锁(passno-unlock) ​

本文记录 v0.2 阶段 2 的守护进程架构、内存加固、自动锁定策略、系统解锁器、打包与自启机制,以及需要由本人在电脑前完成的人机验证项。

详细 IPC 线协议与 Peer 验证见 IPC 协议说明,密钥分层见 设计文档 第 4 节。


1. 组件分工与 crate 边界 ​

  • passno-ipc:Unix domain socket 传输($PASSNO_HOME/run/passnod.sock,运行目录 0700,socket 0600)、4 字节大端长度前缀 JSON 帧、PeerVerifier(macOS LOCAL_PEERTOKEN + SecCodeCopyGuestWithAttributes + Team ID QKPMA8N9LJ 校验;Linux SO_PEERCRED)、IpcPassnoClient(实现 PassnoService)与自动拉起(connect_or_spawn_daemon)。
  • passno-unlock:
    • Unlocker trait 与两种实现:PasswordUnlocker、BiometricUnlocker。
    • SecretKeyStore macOS 钥匙串实现(MacKeychainSecretKeyStore,使用 kSecAttrSynchronizable = true 写入 iCloud 钥匙串)与 FallbackSecretKeyStore(钥匙串不可用、被锁定或自定义测试 PASSNO_HOME 时自动回退到 $PASSNO_HOME/secret.key FileSecretKeyStore)。
    • BiometricProvider trait 与 MacBiometricProvider(objc2-local-authentication LAContext + 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 与 IOKit IORegisterForSystemPower 的 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 .app bundle 内,非测试模式且未设置 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 验签。

3. Contract changes ​

本阶段保持已有 API 与前端协议向后兼容,新增或扩展的契约如下(供后续模块与 data / ui 集成参考):

  1. passno-vault 新增导出方法(仅增不改):
    • Vault::init_returning_auk、Vault::open_returning_auk、Vault::open_with_auk、Vault::header(&self) -> &VaultHeader。原有 Vault::init 与 Vault::open 签名与语义不变。
  2. passno-service 新增导出方法(仅增不改):
    • LocalPassnoService::with_secret_key_store、LocalPassnoService::secret_key_store、LocalPassnoService::set_unlocked_vault、LocalPassnoService::is_unlocked、LocalPassnoService::loaded_vault_id。PassnoService trait 19 个方法签名完全不变。
  3. 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,确保未更新前端代码即可触发状态刷新。
  4. pn CLI:
    • 新增全局参数 --no-daemon、子命令 pn lock、pn unlock --biometrics,以及退出码 7(DaemonUnavailable / PeerDenied)。已有 CLI tests(v0.1 独立本地模式验证)在测试辅助函数里显式传入 --no-daemon,并新增守护进程不可达退出码 7 与 pn <-> passnod 全流程集成测试。

4. 开源实现参考与取舍 ​

开发本阶段前检索并对比了与设计文档同源的开源项目架构:

  1. rbw(MIT):参考其 CLI 短连接 -> 长驻 agent socket 守护进程自动拉起与空闲超时锁定架构;不同之处在于 passnod 采用 4 字节长度前缀 JSON 帧并强制校验客户端进程签名身份,而不是仅依赖 UID。
  2. Secretive(MIT)与 Apple LocalAuthentication 文档:参考 macOS 钥匙串 + LAContext + biometryCurrentSet 策略;由于本地开发/CI 没有 Apple Developer Provisioning Profile,Data Protection 钥匙串访问控制(.biometryCurrentSet)会在 ad-hoc 构建上返回 errSecMissingEntitlement,因此实现为"优先 Data Protection Keychain + .biometryCurrentSet,无 entitlement 时回退本机登录钥匙串 + 显式 LAContext::evaluatePolicy 与 evaluatedPolicyDomainState 校验",签名后可无痛切换。
  3. kbs2 / tsm:参考核心转储禁用(RLIMIT_CORE = 0)与 mlock + zeroize 内存清零实践,并在 RLIMIT_MEMLOCK 受限的容器/CI 环境降级为不阻断启动但保留 zeroize。

5. 需要用户本人 ​

以下真实系统硬件/权限项无法在无头远程终端或无证书 CI 环境中自动完成验证,需本人在 Mac 电脑前操作:

  1. Touch ID / Apple Watch 实机生物识别验证:
    • 在已安装且包含有效签名的 macOS 会话中运行桌面端或 pn unlock 一次,调用 enroll_biometrics,验证系统 Touch ID / Apple Watch 弹窗与指纹变更后强制要求输入主密码的行为。
  2. macOS 钥匙串(iCloud 钥匙串)与登录项弹窗:
    • 首次启用 Keychain 存储 Secret Key 或首次注册 SMAppService 登录项时,确认系统弹出的钥匙串"允许 / 始终允许"以及"系统设置 -> 通用 -> 登录项"中 passno 后台权限开关。
  3. macOS 系统睡眠与锁屏真机联调:
    • 解锁保险库后执行系统"锁定屏幕"或合盖休眠,唤醒后检查 pn status --json 确认已自动锁定并清空内存 AUK。
  4. 正式 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。

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