Skip to content

passnod IPC 协议规范(v1) ​

对应实现:crates/passno-ipc · 最后更新:2026-11-16(UTC+8)

本文档定义后台进程 passnod 与本地客户端(pn CLI、桌面端 passno-desktop、浏览器原生宿主 passno-nmhost)之间的本地进程间通信(IPC)协议。


1. 传输与路径 ​

  • 传输层:Unix Domain Socket(AF_UNIX、SOCK_STREAM)。
  • 运行目录:$PASSNO_HOME/run/(Unix 权限 0700)。
  • Socket 路径:$PASSNO_HOME/run/passnod.sock(Unix 权限 0600)。
  • PID 文件:$PASSNO_HOME/run/passnod.pid(记录 passnod PID 与协议版本)。
  • Windows(2026-11-16,feat/windows 第 ① 步):命名管道 \\.\pipe\passno-<SHA-256(小写 home) 前 16 位十六进制>。daemon 用 passno_ipc::transport::server::create 建每个实例:DACL 为 D:P(A;;GA;;;<当前用户 SID>)(只有本人能打开)、第一个实例带 FILE_FLAG_FIRST_PIPE_INSTANCE(名字被占就启动失败,防抢注)、PIPE_REJECT_REMOTE_CLIENTS。客户端以 SECURITY_SQOS_PRESENT | SECURITY_IDENTIFICATION 打开,冒充的服务端只能识别、不能模拟客户端。同步客户端在内部用单线程 tokio 运行时实现读写超时,语义和 Unix 的 set_read_timeout 一致。
  • 代码结构:passno_ipc::transport::{endpoint, ClientStream} 是客户端唯一入口;daemon 的 listener.rs(LocalListener、verify_peer)屏蔽平台差异,server.rs 不再出现 Unix 类型。

2. 帧格式(Framing) ​

所有请求、响应与推送事件均采用长度前缀 JSON 帧:

text
+-------------------------------+----------------------------------------+
|  length: 4 bytes (u32 BE)     |  payload: UTF-8 JSON (length bytes)    |
+-------------------------------+----------------------------------------+
  • 长度字段为 4 字节大端无符号整数(big-endian u32)。
  • length == 0 视为非法帧。
  • 最大帧长度 MAX_FRAME_BYTES = 16 MiB(16 * 1024 * 1024 字节),超过立即拒绝。

3. 对端身份校验(PeerVerifier) ​

passnod 在接受每个连接后立即执行平台级进程身份校验,拒绝跨用户或未授权进程:

  1. macOS(MacPeerVerifier):
    • getpeereid(fd) 验证对端 uid == geteuid()。
    • getsockopt(fd, SOL_LOCAL, LOCAL_PEERTOKEN) 获取内核签发的 audit_token_t。
    • SecCodeCopyGuestWithAttributes(kSecGuestAttributeAudit) 获取 SecCodeRef,并检查 SecCodeCheckValidity 与 SecCodeCopySigningInformation。
    • 校验策略(可注入 PeerPolicy):
      • Release(Developer ID 签名构建):要求有效签名、非 ad-hoc 且满足 Apple 签名需求 anchor apple generic and certificate leaf[subject.OU] = "QKPMA8N9LJ"(RequireTeamSignature)。
      • Release(本地 ad-hoc 打包构建):要求有效签名,且满足 QKPMA8N9LJ 或位于同一 .app/Contents/MacOS 目录 / 匹配 cdhash(RequireBundledSignature)。
      • Dev(debug_assertions 或测试):允许同 UID 未签名进程,但会打印醒目的安全警告日志(DevSameUid)。
  2. Windows(WindowsPeerVerifier,peer_windows.rs):daemon 用 GetNamedPipeClientProcessId 取 PID;打开进程后比对进程令牌的用户 SID 与自己相同(不同即拒绝),用 QueryFullProcessImageNameW 取路径,用 WinVerifyTrust(不联网查吊销)查 Authenticode。PID 可伪造、文件签名不证明进程未被注入,所以这一层只是补充,主要靠管道 DACL 和每条命令自己的权限检查。Windows 代码签名证书到位前(plan 需要人做的第 6 项)策略是 DevSameUid(同用户放行并告警),之后在这里钉死签名者。
  3. Linux(LinuxPeerVerifier):
    • getsockopt(fd, SOL_SOCKET, SO_PEERCRED) 验证对端 uid == geteuid()。

4. 消息信封 ​

4.1 客户端请求(IpcRequest) ​

json
{
  "protocol_version": 1,
  "id": 1,
  "request": {
    "method": "status"
  }
}
  • protocol_version:固定 1。若版本不匹配,服务端返回 UnsupportedProtocolVersion。
  • id:单连接内由客户端递增的请求关联编号(u64)。
  • request:内部使用 {"method": "<snake_case>", "params": {...}} 标签格式(无参方法省略 params)。

4.2 服务端消息(IpcServerMessage) ​

服务端在普通连接上返回 kind: "response",在订阅流连接上先返回 Subscribed 响应,随后异步推送 kind: "event":

成功响应:

json
{
  "kind": "response",
  "protocol_version": 1,
  "id": 1,
  "result": {
    "Ok": {
      "type": "status",
      "data": {
        "initialized": true,
        "locked": false,
        "vault_path": "/Users/alice/Library/Application Support/passno/vault",
        "item_count": 42
      }
    }
  }
}

错误响应:

json
{
  "kind": "response",
  "protocol_version": 1,
  "id": 2,
  "result": {
    "Err": {
      "code": "Locked",
      "message": "vault is locked",
      "reason": "idle timeout reached",
      "next": "run `pn unlock` or unlock with Touch ID in passno.app"
    }
  }
}

推送事件:

json
{
  "kind": "event",
  "event": "vault_changed",
  "source": "cli"
}

5. 全量方法列表 ​

所有与 docs/dev/api.md 对应的业务方法与 PassnoService DTO 完全一致;以下列出全部 request.method 与 Ok.type:

methodparamsOk.type & data说明
ping无pong { daemon_version, pid, peer_verification_mode }探活与对端校验模式查询
daemon_status无daemon_status { pid, daemon_version, protocol_version, vault, peer_verification_mode, unlock_method, unlocked_at, last_activity_at, last_password_unlock_at, biometrics_supported, biometrics_enrolled, master_password_required_reason, auto_lock }扩展守护进程与策略状态
status无status (Status)保险库初始化与锁定状态
init{ master_password }init (InitResult)初始化新保险库并保持解锁
unlock{ master_password, secret_key? }unit主密码解锁(会刷新 14 天与重启基线)
unlock_with_biometrics{ reason? }unitTouch ID / Apple Watch 解锁(受 design.md §4 规则约束)
enroll_biometrics无unit为当前已解锁会话生成本地生物识别包裹密钥
disable_biometrics无unit删除本地生物识别包裹材料
change_master_password{ current_password?, new_password }account { biometrics, phone_needs_repair, other_devices }修改主密码(2026-11-16)。需已解锁、主人会话;省略 current_password 时由 passnod 弹 Touch ID,只限 App。见 修改主密码
move_vault_aside{ confirmed: true }account { moved_to, old_vault_id, deleted: false }忘记主密码时重新开始(2026-11-16)。锁着也能用;只限 App 或有终端的命令行,并需本人确认;不删除任何文件
set_auto_lock_settings{ settings: AutoLockSettings }unit更新空闲超时、最大会话时长、睡眠/锁屏自动锁定设置
lock无unit立即清零内存密钥并锁定,广播 vault_locked
list_items{ filter: ItemFilter }items (Vec<ItemSummary>)列出或搜索条目摘要(不含隐藏字段明文)
get_item{ id }item (Item)获取条目详情(隐藏字段 value 为 null;每个字段带 empty,值为空时为 true,隐藏字段也带,空值不算泄露)
reveal_field{ item_id, field_id }revealed { value }取出单字段明文(仅本人交互界面/终端或经未来审批使用)
create_item{ draft: ItemDraft }created { id }新建条目并广播 vault_changed
update_item{ id, draft: ItemDraft }unit更新条目并广播 vault_changed
delete_item{ id }unit软删除至回收站并广播 vault_changed
restore_item{ id }unit从回收站恢复并广播 vault_changed
set_item_archived{ id, archived }unit设置归档标记并广播 vault_changed
set_item_favorite{ id, favorite }unit设置收藏标记并广播 vault_changed
generate{ options: GeneratorOptions }generated (Generated)生成密码/口令短语/PIN(无需解锁)
totp{ item_id }totp (TotpCode)计算当前 TOTP 验证码
import_preview{ path, format }import_preview (ImportPreview)只读预览导入文件
import_commit{ path, format, policy }import_report (ImportReport)执行幂等导入并广播 vault_changed
list_attachments{ item_id }attachments (Vec<AttachmentInfo>)列出条目附件的元数据
add_attachment{ item_id, path }attachment (AttachmentInfo)把本机文件加密存入保险库并广播 vault_changed。path 必须是绝对路径:守护进程的工作目录和调用方不同,pn 发送前会先转成绝对路径
export_attachment{ item_id, attachment_id, dest_path }unit解密附件写到 dest_path(绝对路径)
delete_attachment{ item_id, attachment_id }unit删除附件并广播 vault_changed
list_password_history{ item_id }password_history (Vec<PasswordHistoryMeta>)密码历史元数据(序号和时间,不含明文)
reveal_password_history{ item_id, index }revealed { value }取出某条历史密码明文(规则同 reveal_field)
list_trashed_items{ filter: ItemFilter }items (Vec<ItemSummary>)列出回收站条目
purge_item{ id }unit永久删除并广播 vault_changed
empty_trash无purged { count }清空回收站并广播 vault_changed
approvals{ action: "list" }、{ action: "decide", id, choice }、{ action: "overview" }、{ action: "revoke_grant", id }、{ action: "revoke_all_grants" }、{ action: "revoke_agent", agent },choice 为 once / this_run / one_hour / denyapprovals (ApprovalView[])、unit 或 agent_overview(JSON 元数据)agent 授权请求的人工审批;只接受桌面 App 对端。ApprovalView.needs_owner_check 为真(Reveal)时,批准前 daemon 先弹 Touch ID / 登录密码,在 core 锁外进行;未确认返回 BiometricsCancelled,请求继续等待。客户端对 approvals 的读超时为 90 秒。事件主题 approvals:approval_requested { approval }、approval_resolved { id }
stats无stats (Stats)汇总安全统计
security_audit无security_audit (SecurityAudit)弱密码、复用密码组与缺少 2FA 审计
reload_if_changed无reloaded { changed }检查磁盘是否有外部写入并重载
open_item{ id }unit扩展的“在 passno 中打开”。只接受 passno-nmhost 对端;id 只能是字母数字和 -_:,最长 200;记下请求 30 秒并推送 open_item_requested(不带 id)
take_open_item—open_item(string | null)App 领取最近 30 秒内的打开请求,只领一次;只接受桌面 App 对端
subscribe{ topics?: SubscriptionTopic[] }subscribed(后转为事件流)订阅事件;topics 为空表示订阅全部事件

Agent broker 方法(v1 增量) ​

method参数响应说明
agent{ method, params, agent, credential?, service_token?, cwd }agent,内部为 MCP Result<CallToolResult, ErrorData>method 仅支持八个 MCP 工具及 ssh-identities、ssh-sign、reveal;复用身份校验、授权、审计与打码,不提供原始 vault 读取接口
agent_admin{ method, params }agent,管理结果 JSON已解锁 owner 操作:vault-create、token-create、token-revoke、subvault-add、item-policy;首次服务令牌只按既有管理契约输出一次

两种请求复用连接的 PeerVerifier,Debug 输出统一隐藏参数及响应。agent 中的错误附带稳定 code 和 exit_code,前端保留 2/3/4/5/6/7/8 的语义。客户端不把审批模式传入协议;模拟策略来自 daemon 启动环境。服务令牌不依赖 owner 解锁,但每次调用检查到期、撤销和纪元。SSH 仅传入公钥与待签名数据,私钥留在 daemon。

长操作在核心锁外执行,以便锁屏/休眠和其他连接继续工作。agent IPC 读取超时为 330 秒,覆盖现有子进程 300 秒上限;普通 RPC 保持 30 秒。broker 操作在 I/O 错误后不自动重发,防止已执行但响应丢失时重复运行命令、签发或撤销令牌。自动启动 daemon 时删除继承环境中的主密码、agent 凭据、服务令牌和本地代理凭据。

6. 订阅事件(IpcEvent) ​

event字段触发时机
vault_changedsource: string通过 IPC 增删改导入条目,或检测到磁盘外部变更时
vault_lockedreason: LockReason手动锁定(manual)、空闲超时(idle_timeout)、最大会话时长(max_session_duration)、系统睡眠(system_sleep)、锁屏(screen_locked)、进程退出(shutdown)
vault_unlockedmethod: UnlockMethod任意客户端通过 password 或 biometrics 解锁成功时
approval_requested / approval_resolvedapproval / idagent 授权请求出现 / 被处理(主题 approvals)
open_item_requested—扩展请求打开条目(主题 open_item);App 收到后用 take_open_item 取 id,窗口提到前面

7. 错误码对照 ​

除 docs/dev/api.md 中的 ServiceError 错误码(NotInitialized、AlreadyInitialized、Locked、WrongPassword、SecretKeyMissing、WeakPassword、NotFound、Invalid、NoTotp、ParseError、Io、Internal)外,IPC 与解锁层新增以下错误码:

code含义建议处理
MasterPasswordRequired满足 design.md §4 强制主密码规则(重启后首次、超 14 天、指纹变更、安全设置变更)引导用户输入主密码调用 unlock
BiometricsUnavailable本机不支持或未录入生物识别包裹回退主密码解锁,解锁后可重新 enroll_biometrics
BiometricsCancelled用户取消了 Touch ID / Apple Watch 弹窗允许重试或改用主密码
PasswordChanged主密码已在本机或另一台设备上修改,给出的是旧代的主密码或旧 AUK(2026-11-16)提示用新主密码解锁;生物识别包裹已自动删除,解锁后会重新包裹
PeerDenied对端进程未通过 PeerVerifier 校验检查应用与 CLI 签名是否一致(pn doctor)
UnsupportedProtocolVersion客户端与 passnod 协议版本不兼容重启 passnod 或重新安装同一版本的应用包

8. passno-nmhost(浏览器扩展原生宿主)接入建议 ​

  1. passno-nmhost 启动时连接 $PASSNO_HOME/run/passnod.sock(可调用 passno_ipc::connect_or_spawn_daemon)。
  2. 为避免污染原生消息的 stdout,passno-nmhost 不得在标准输出打印任何日志。
  3. 可同时维持一条请求连接与一条 subscribe 连接,用于在锁屏/自动锁定时立即清空扩展侧状态。

integrate1 验收补充(2026-11-16) ​

  • 调试版 passnod --vault-dir <临时目录> --simulate-biometrics 可用于无人值守的端到端验收。 强制临时目录;模拟 biometric provider / 系统事件,Secret Key 写到临时文件存储。 release 构建不包含这个参数,不能用于真实保险库。
  • Totp 不再更新空闲活动时间:桌面会每秒刷新显示,若当成活动会阻止自动锁定。 实际填充读取密码、编辑等其他操作仍按原有策略更新活动。
  • Native Messaging 订阅断开时推送 locked,并等待 daemon 恢复重新订阅;不通过事件线程解锁。

integrate1:浏览器原子请求 ​

v1 新增可选请求 browser_fill { id, url }、update_login_credentials { id, url, username, password }, 分别返回 browser_fill 和 login_updated { changed }。沿用现有 peer 验证,不新增 agent 入口。 旧 daemon 未识别时拒绝,宿主不退回非原子的读取 / 全条目覆盖。 宿主还单独验证其浏览器父进程,避免可信宿主被 shell 用公开的扩展 origin 冒充调用。

integrate2 与 agent 合并(2026-11-16,新加坡时间) ​

  • 同时保留 RequestBody::Sync、Agent、AgentAdmin 与 ResponseBody::Sync、Agent; 请求与响应的 Debug 均不输出同步凭据、恢复材料或 broker 内容。
  • Agent 只在短暂取得服务引用后释放 core 锁,随后进入 spawn_blocking,创建独立 Tokio runtime 执行 broker。子进程或 HTTP 等待期间,其他连接仍可请求同步和锁库。
  • 普通请求(含 Sync 与 AgentAdmin)在 blocking worker 内持 core 锁串行处理; 同步调度器仍处理启动、解锁、写入防抖、定期检查与唤醒,避免 blocking 传输嵌套 runtime。
  • IpcClient::call 统一设置响应等待时间:agent 为 330 秒、sync 为 120 秒、其他为 30 秒。 复用连接时按本次请求重设,防止其中一条路径覆盖另一条的等待时间。
  • IpcPassnoClient::call_raw 不重放 Agent、AgentAdmin 或 Sync;sync_command 同样 不自动重试。I/O 或帧错误后丢弃失效连接,只供下一次显式请求重连;丢失响应不能证明写入未发生。
  • 回归覆盖两条同步调用入口的丢失响应,以及真实 broker 子进程运行期间的同步与锁库。

手机批准扩展 ​

RequestBody::PhoneApprove { command, fingerprint? } → ResponseBody::PhoneApprove(JSON);命令为 status/pair/confirm/request/cancel/revoke。pair/confirm/revoke 必须有主密码解锁会话,所有命令仅对通过 peer 验证的桌面可执行文件开放。不得自动重试写请求。状态只含配对、指纹、端点与截止时间;AUK 通过独立加密 TCP 协议直接进入 daemon,不经过 IPC。详情见 手机批准。

新增 unlock_method: "phone";手机会话默认绝对 1800 秒,不能被操作续期,锁屏/睡眠/重启清除。

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