Appearance
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(记录passnodPID 与协议版本)。 - 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 在接受每个连接后立即执行平台级进程身份校验,拒绝跨用户或未授权进程:
- 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)。
- Release(Developer ID 签名构建):要求有效签名、非 ad-hoc 且满足 Apple 签名需求
- Windows(
WindowsPeerVerifier,peer_windows.rs):daemon 用GetNamedPipeClientProcessId取 PID;打开进程后比对进程令牌的用户 SID 与自己相同(不同即拒绝),用QueryFullProcessImageNameW取路径,用WinVerifyTrust(不联网查吊销)查 Authenticode。PID 可伪造、文件签名不证明进程未被注入,所以这一层只是补充,主要靠管道 DACL 和每条命令自己的权限检查。Windows 代码签名证书到位前(plan 需要人做的第 6 项)策略是DevSameUid(同用户放行并告警),之后在这里钉死签名者。 - 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:
method | params | Ok.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? } | unit | Touch 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 / deny | approvals (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_changed | source: string | 通过 IPC 增删改导入条目,或检测到磁盘外部变更时 |
vault_locked | reason: LockReason | 手动锁定(manual)、空闲超时(idle_timeout)、最大会话时长(max_session_duration)、系统睡眠(system_sleep)、锁屏(screen_locked)、进程退出(shutdown) |
vault_unlocked | method: UnlockMethod | 任意客户端通过 password 或 biometrics 解锁成功时 |
approval_requested / approval_resolved | approval / id | agent 授权请求出现 / 被处理(主题 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(浏览器扩展原生宿主)接入建议
passno-nmhost启动时连接$PASSNO_HOME/run/passnod.sock(可调用passno_ipc::connect_or_spawn_daemon)。- 为避免污染原生消息的
stdout,passno-nmhost不得在标准输出打印任何日志。 - 可同时维持一条请求连接与一条
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 秒,不能被操作续期,锁屏/睡眠/重启清除。