Files
xop-botandClaude Code 7660b92d70 v0.5: 描述元数据 + list 免引号搜索 + 元数据操作免闸门
影响: key 多了人/AI 可读的用途说明(存加密 vault 内,不落明文文件);
`xop list` 的搜索不用再打引号; `xop list` / `xop desc` 只碰元数据、
永不吐 value,因此不再弹指纹、不再问口令 —— agent 跑 xop 不会被打断。
118 unit + 40 integration 全绿。

改动:
- 新增 `xop desc KEY [TEXT...]`: 描述存 vault 的 `__meta__` TOML 子表;
  文字用空格 join(不用引号), 真打进 vault 的一层引号会被剥掉;
  不写文字 = 清除描述(不用敲空引号 "")
- `xop list [TERM...]`: 搜索默认改成大小写不敏感的子串匹配, 命中 key 名
  或描述, 不用引号、不用通配符; 含 `*` `?` `[` 的词仍切 glob 语义
  (老写法 `xop list 'git_*'` 行为不变); 多词取并集
- 新增 `Vault::open_metadata` / `open_metadata_at`: 只开元数据路径,
  0600 keyring 静默解锁, 无 keyring 才回落手输 passphrase;
  `get`/`set`/`rm`/`run` 仍走 `Vault::open` 全套闸门
- 新增 `auth::Intent` + `auth::needs_gate(intent)`: 把"哪些操作要闸门"
  写成纯函数; `Vault::open` 与 `open_metadata` 共享 `decrypt_with` 核心
- 新增 `src/glob.rs`: 轻量匹配器, `*` 任意长 / `?` 单字符, 零新依赖;
  搜索用的 `has_meta` / `matches_ignore_case` / `contains_ignore_case` /
  `contains_glob_ignore_case`
- 新增 `src/datadir.rs`: 数据目录 `~/.xop/` → `~/.x/xop/`, 迁移是
  **复制不移动**(旧目录留作备份), 新 vault 已存在则跳过
- `keyring::load_at` / `save_at` 改 pub(路径显式化, 单测不碰全局 HOME)
- `audit.rs` 新增 `vault_desc(name)`: 只记 key 名, 描述文字不入日志(I2)
- 集成测试新增 pty 回归 `list_under_a_tty_never_prompts_for_biometrics`:
  `script -q /dev/null` 起真 pty + 30s 超时, 闸门若回来则失败而非挂死
- 版本 0.4.0 → 0.5.2; AGENTS.md / HANDOFF.md / docs/* 同步;
  examples 里 v0.5 搬家前的 `~/.xop/` 残留路径一并修正

设计: "搜索要打引号"的根因是 shell 通配符(`*` 在 zsh 下没匹配文件直接
`no matches found`), 不是 xop —— 所以正解不是"少打引号", 而是让日常
搜索根本不需要通配符: 默认子串匹配, `*`/`?`/`[` 只在用户显式写了时才
切回 glob。免闸门只给元数据操作: 闸门的意义是"释放真值前确认有人在场",
而 list/desc 永不吐 value; 值路径(get/set/rm/run)一行没动。

Co-Authored-By: Claude Code <[email protected]>
2026-10-22 17:03:12 +08:00

38 KiB
Raw Permalink Blame History

xop · AI Agent 操作速查(上下文压缩后自动加载)

本文件是 xop 给 AI agent 的"可执行附录":Claude Code / WorkBuddy / 其他 agent harness 在每次会话开头、以及上下文压缩(compact)后都会自动重新加载它。 项目根:/Users/xs/Documents/x/xop 完整交接文档在 HANDOFF.md;架构/威胁模型/对比在 docs/。


0. 一句话定位

xop = 自带加密 vault + OS-auth gate 的 secret 注入器。xop init | set | list | get | rm 管理本地 vault(~/.x/xop/key.db,AES-256-GCM + argon2id,LAContext 真指纹预闸门,取消即拒绝,绝不弹系统密码框);xop [flags] -- CMD 把 vault 里的真值注入到子进程的 envp/Askpass/fd,同时强制 Deno 风格的 network/file policy,并在 stdout 里 mask 任何泄漏。无外部后端依赖——不调 op / vault / security CLI。

改 Rust 源码 → 必须 cargo check + cargo test --lib + cargo test --test integration 通过 → 再交付。编译错或测试红禁止 commit。

解锁模型(v0.2.1,2026-10-02 两次实测修正):vault 密钥永远 = argon2(passphrase)。每次操作先过 OS 身份闸门,闸门结论决定 keyring 能不能静默解锁:① 本地真 TTY → 弹 LAContext 真指纹验证(只认手指、绝无密码输入框;取消 = 拒绝操作 exit 77,不静默放行)→ 通过后才允许 keyring 免输;② SSH 会话(stdin 是 pty 但检测到 SSH_TTY/SSH_CONNECTION/SSH_CLIENT env)→ 绝不弹指纹(弹窗会飞到本机物理屏幕上,远程用户根本看不到/等不到),也不走 keyring——没有指纹现证,必须输入 xop passphrase(管理员密码);③ 本地设备无可用指纹(未录入、锁定、无密码、无 GUI、osascript 坏)→ 同样强制输入 xop passphrase;④ Linux 交互会话 → 无指纹闸门可用(pkexec 系统口令框按"永不输系统密码"红线删除)→ xop passphrase;⑤ headless 非 TTY 自动化(agent/pipe/CI/ssh host cmd 无 pty)→ 跳过闸门,keyring 静默解锁(xop run 无人值守的依据)。解锁密钥来源:文件 keyring ~/.x/xop/keyring(0600,存 hex 派生密钥,xop init 自动写入 / xop key --save 补写;xop key --remove 吊销)或终端手输(闸门要求输 passphrase / 无 keyring / XOP_NO_KEYRING=1 时)。明确设计决定(2026-10-02):绝不使用 macOS Keychain——keychain 方案在后台自动化时会弹系统授权对话框(曾被用户否决),xop 任何代码路径都不调 security(1)。keyring 权限位不合规(group/other 可读)直接拒用报错。release 二进制永不读 XOP_VAULT_PASSWORD env。子进程 stdout/stderr 中的任何 vault 值会被自动 mask 成 12****【xop禁止将密钥泄漏】(前 2 真实字符 + 星号 + 警告),--on-leak=kill|refuse 时直接 SIGKILL 子进程。


1. 编译 + 测试

cd /Users/xs/Documents/x/xop

# 快速检查(增量编译,最常用)
cargo check --all-targets

# 跑单元测试(68 个:args(含 get -v 解析)/ secret / policy / audit / vault / keyring / auth(touchid classify + decide 决策表)/ stdout-guard / error / injector / askpass)
cargo test --lib

# 跑集成测试(24 个:help / dry-run / bad-ref / secrets-file / mask 端到端 / keyring 免密解锁 / SSH-headless / get 默认 mask / get -v 明文 / 6 askpass)
# 集成测试需要 auth bypass + 已知 passphrase。`XOP_VAULT_PASSWORD` 仅在
# `--features test-bypass` 构建中才被读取;release binary 永远不读这个 env
# ——passphrase 必须用户亲输。所以集成测试必须显式启用 feature。
XOP_AUTH_BYPASS=1 XOP_VAULT_PASSWORD=testpass \
  cargo test --features test-bypass --test integration -- --test-threads=1

# 完整构建 + smoke(默认 release build 不带 test-bypass feature)
cargo build --release
./target/release/xop            # banner
./target/release/xop help       # 完整帮助
./target/release/xop --dry-run --secret FOO=foo --allow-net=db.local:5432 --deny-net=* -- echo hi
./target/release/xop run --secret SSHPASS=ssh_pass -- sshpass -e ssh user@host

# 跑全部测试(不要漏 env vars)
cargo test --lib && \
  XOP_AUTH_BYPASS=1 XOP_VAULT_PASSWORD=testpass \
    cargo test --features test-bypass --test integration -- --test-threads=1

注意:

  • 修改 Cargo.toml 加依赖后必须 cargo check 让 Cargo.lock 重新生成
  • --test-threads=1 在集成测试里必须带,因为某些测试改 HOME / env 状态
  • 集成测试用 --features test-bypass 构建;release 永远不带这个 feature(防止 XOP_VAULT_PASSWORD 变成绕过 vault 加密的后门)
  • 编译警告允许带 #[allow(...)],但新代码不写 unwrap() 除非能证明 panic-safe

2. CLI 用法速记

# ── Vault 管理 ──────────────────────────────────────────────────────
# 一次性初始化(init 本身不要求 Touch ID — 此时还没有可保护的东西)
xop init
#   init 问 passphrase ×2,然后自动写 ~/.x/xop/keyring(0600 文件 keyring,
#   存 argon2 派生密钥的 hex;不是 macOS Keychain):
#   本地真 TTY:弹指纹 → 通过 → 静默读 keyring,零 passphrase
#   SSH 交互 / 无可用指纹 / Linux 交互:必须手输 xop passphrase(keyring 不参与)
#   headless 自动化(agent/pipe/无 pty):跳过闸门 + keyring 静默
#   管理:xop key(状态)/ xop key --save(补写,老 vault 用它启用免密)
#         xop key --remove(吊销,回到手输)
#   revoke:`xop reset --yes` 会级联删 keyring 文件

# 存 / 列 / 取 / 删 secret(keyring 已存则免 passphrase)
xop set DB_PASS                       # TTY 上值输入带部分 mask(前 2 位明文 + *)
echo "hunter2" | xop set DB_PASS      # 非 TTY(pipe/agent)从 stdin 读值
xop list                              # 列 key 名 + 描述(不显示 value)——免密免 Touch ID
xop list git_local                    # 搜索:**不用引号、不用通配符**(子串匹配 key 名 + 描述,大小写不敏感)
xop list 'git_local*'                 # 带 * ? [ 的词自动切 glob 语义(老写法仍可用)
xop list --names-only                 # 只列名字,不显示描述
xop desc DB_PASS 生产库密码            # 给 key 写描述(存进加密 vault)——免密免 Touch ID
xop desc DB_PASS                      # 不带文字 = 清除描述(不用敲空引号)
xop get DB_PASS                       # 默认脱敏输出 `su****【xop禁止将密钥泄漏】`(前 2 位)——要过闸门
xop get DB_PASS -v                    # 明文——人眼核对专用;AI agent 禁止 -v(明文会进模型上下文),用 xop run --secret 注入
xop rm DB_PASS                        # 删除单个
xop reset --yes                       # 删整个 vault + audit + keyring(应急)

# ── Exec-mode:envp 注入(传统)──────────────────────────────────────
xop --secret DB_PASS=db_pass \
    --allow-net=mysql.local:5432 --deny-net='*' \
    -- mysql -h mysql.local -u app mydb

# ── `xop run`:envp 注入 + argv 占位符(推荐用于 SSH)────────────────
# envp 注入:vault 值 → 子进程环境变量(sshpass -e 读 $SSHPASS)
xop run --secret SSHPASS=s11_pass \
    --allow-net=192.168.1.19:22 --deny-net='*' \
    -- sshpass -e ssh [email protected] 'ls /Users'

# argv 占位符:vault 值直接替换 argv 里的 %XOP_KEY% 字符串
# ⚠️ 替换后的字符串会出现在 /bin/ps 里 —— 密码用 --secret,命令行参数用 %XOP_KEY%
xop run -- ssh user@host 'echo connect with %XOP_DB_PASS%'

# SSH_ASKPASS 注入(v0.4,推荐用于直连 ssh)—— 密码既不进 argv 也不进 env:
# mkdtemp 0700 临时目录里写 0600 data + 0700 getpass.sh,子进程通过
# SSH_ASKPASS=<script> + SSH_ASKPASS_REQUIRE=force 调用,srm -m 自动清理
xop run --askpass=ssh_pass -- ssh user@host

# 批量注入(commit-safe 的 .env.xop 文件,每行 KEY=NAME)
xop --secrets-file .env.xop -- ./deploy.sh

# Dry-run:只看 policy,不真执行(AI 自检的 killer feature)
xop --dry-run --secret FOO=foo --allow-net=db:5432 --deny-net=* -- deploy.sh

注意:

  • KEY=NAME 必须在 -- 之前;-- 后是子命令 + 它的 args
  • bash 会展开 $VAR,所以 secret 引用不要直接写在命令行里——用 --secret flag 或 %XOP_KEY% 占位符
  • v0.2 删了 --backend 和所有 scheme 前缀(op://、vault://)——只有 bare key
  • --dry-run 在 resolve 之前短路,不开 vault、不过 OS 闸门——纯本地打印有效 policy(集成测试 dry_run_prints_effective_policy 无 bypass env 也过)
  • Passphrase 提示策略:stdin 是真 TTY → 走 /dev/tty(隐藏输入),stdin 不是 TTY(agent / pipe / expect)→ fallback 到 stdin。Release binary 永远不读 XOP_VAULT_PASSWORD env——passphrase 必须用户亲输(或走 keyring 免输)
  • xop list / xop desc 免密免 Touch ID(v0.5.1,用户要求"AI 做会中断"):这两个只读/写元数据(key 名 + 描述),永远不吐 value,所以跳过 OS 身份闸门,走 Vault::open_metadata(keyring 静默解锁;没 keyring 才回落到手输 passphrase)。get / set / rm / run 仍然全套过闸门——auth::needs_gate(Intent::Value) == true
  • xop desc 的文字不用打引号:xop desc KEY 生产库 密码 会被 join 成「生产库 密码」;xop desc KEY(不带文字)= 清除描述

3. 模块地图

想了解 看哪里
CLI 所有 flag + 解析 + Subcommand enum src/args.rs
ref 长啥样 + 怎么解析(bare KEY=NAME + argv_placeholder 标志) src/secret.rs
错误类型 + 退出码(BSD sysexits) src/error.rs
权限策略(allow/deny 默认值) src/policy.rs::DEFAULT_DENY_READ + Policy::from_args
本地 vault:文件格式 + 加密 src/vault/mod.rs + src/vault/format.rs
文件 keyring:~/.x/xop/keyring 0600 免密解锁(非 Keychain) src/vault/keyring.rs(路径显式的 *_at 核心 + env 门控 wrapper)
OS auth gate:macOS 真指纹(LAContext via JXA)+ Gate 决策(headless/SSH/无指纹/取消) src/auth/mod.rs(Gate/Bio/decide/ssh_session/Intent/needs_gate)+ touchid.rs(Outcome/classify)
免密元数据读(v0.5.1):跳过闸门的 vault 打开路径 src/vault/mod.rs::open_metadata / open_metadata_at(keyring 静默,无 keyring 才问 passphrase)
子命令(init / set / list / get / rm / reset / key / desc / run) src/commands/{init,set,list,get,rm,reset,key,desc}.rs + src/lib.rs::run_join_and_exec
glob 匹配器(v0.5):* 任意长、? 单字符,大小写敏感,无依赖;v0.5.2 加 has_meta / matches_ignore_case / contains_ignore_case / contains_glob_ignore_case(搜索用) src/glob.rs(matches / matches_any / has_meta / contains_*)
数据目录(v0.5):~/.x/xop/ 路径解析 + 旧 ~/.xop/ 一次性迁移(复制不移动) src/datadir.rs(home / legacy_home / migrate_legacy)
描述元数据(v0.5):vault 内 __meta__ 子表存 desc src/vault/mod.rs(Meta / decode_plaintext / encode_plaintext / set_description / list_with_desc)
%XOP_KEY% argv 占位符 + 单 vault open 协调 src/lib.rs::expand_xop_placeholders + src/injector.rs::scrub_argv
SSH_ASKPASS 注入(v0.4):mkdtemp + 0600 data + 0700 脚本,Drop 自动 srm -m src/askpass.rs
怎么注入到子进程 src/injector.rs::plan + build_envp_delta(按 argv_placeholder 过滤;askpass 由 run_exec 单独 setup)
子进程 stdout 怎么过滤 src/guard/stdout.rs::pipe_filter_loop
网络/文件策略怎么落 src/guard/{network,file}.rs(STUB,P1)
审计日志格式 + 不变量 src/audit.rs(test no_value_field_in_any_event 扫 4 个关键字)
编排 exec-mode pipeline src/lib.rs::run_exec(9 阶段)
TTY-aware passphrase prompt(/dev/tty vs stdin fallback) src/vault/mod.rs::rpassword_prompt
Test-only XOP_VAULT_PASSWORD 旁路(gated by Cargo feature) src/vault/mod.rs 的 #[cfg(feature = "test-bypass")] 块 + Cargo.toml::[features]
spawn 真实现(pre_exec + setrlimit) src/lib.rs::spawn_child

4. 关键不变量(违反任一 = 安全漏洞)

# 不变量 谁保证 验证方式
I1 LLM API / IPC / shell history 永远不出现 secret value --secret KEY=NAME flag 设计 + vault 用 SecretBox<String> 包装值 code review:grep expose_secret 限定在 injector / guard 内
I2 审计日志没有 value/plaintext/ciphertext/passphrase 字段 audit::AuditLog 只接收 serde_json::Value,不接收 ResolvedValue cargo test audit::tests::no_value_field_in_any_event
I3 SecretBox::Debug 打印 <secret> secrecy crate 保证 cargo test secret::tests
I4 真值只在 fork 前短暂活在 parent 内存 injector::build_envp_delta 拷贝值进 envp 后立刻 drop parent 端 手动 review spawn_child
I5 --allow-net/--deny-net 默认 deny-by-default Policy::from_args 不接受空 allow 等于全 deny cargo test policy::tests
I6 子进程退出时 temp 文件清掉 askpass::AskpassHandle::Drop 跑 srm -m,fallback rm -rf;XOP_ASKPASS_DATA 路径不暴露在 argv cargo test askpass::tests::drop_runs_teardown + integration run_askpass_cleans_temp_dir_on_exit
I7 vault 文件只有 passphrase 能解密(v0.2 新增) AES-256-GCM + argon2id KDF;OS auth 只是 pre-gate cargo test vault::format::tests
I8 keyring 静默解锁只在身份已被证明时允许(本地指纹通过 / headless 自动化);SSH 与无指纹交互场景必须输 xop passphrase,keyring 不参与;且 xop 从不触碰 macOS Keychain(v0.2.1 两次修订)。例外(v0.5.1,用户要求):纯元数据操作(list/desc,永不吐 value)走 open_metadata,跳过闸门直接用 keyring Vault::open:auth::authenticate() → Gate;AllowKeyring 才 keyring::load(),RequirePassphrase 直接 prompt(SSH env / 无生物特征 / osascript 坏 / Linux 交互);XOP_NO_KEYRING=1 强制手输;keyring mode 非 0600 报错拒用;代码库无 security(1) 调用。元数据例外:auth::needs_gate(Intent::Metadata) == false,Vault::open_metadata 只在 keyring 命中时静默 cargo test auth::tests::decide_*(5 条决策表)+ cargo test auth::tests::metadata_operations_skip_the_gate_values_do_not + cargo test vault::tests::open_metadata_uses_the_keyring_without_prompting + code review vault/mod.rs::open
I11 子进程 stdout/stderr 里的 vault 值必被 mask(v0.2.1 新增) pipe_filter_loop 行缓冲 + StdoutGuard::filter;--on-leak=kill/refuse 时 SIGKILL cargo test guard::stdout::tests + integration run_masks_*
I9 release binary 不读 XOP_VAULT_PASSWORD env(v0.2 新增) 旁路仅在 #[cfg(feature = "test-bypass")] 编译时存在;release 用 cargo build --release(不带 feature) strings target/release/xop | grep XOP_VAULT_PASSWORD 应无匹配
I10 vault 每次 exec 只开一次(v0.2 新增) --secret 和 %XOP_KEY% 占位符共享同一个 resolve_all 调用 code review:run_join_and_exec + run_exec

5. 当前状态(2026-10-22,v0.5)

✅ 已完成(v0.2 pivot 完成):

  • 删除 src/backend/{op,vault,kc,env}.rs + mod.rs(4 个外部后端)
  • 新增 src/vault/:AES-256-GCM + argon2id,atomic write,单元测试覆盖 round-trip / wrong key / 不同 passphrase
  • 新增 src/auth/:macOS Touch ID(osascript)+ Linux PAM(pkexec)subprocess 方式;TTY 检测 + 1FA fallback
  • 新增 src/commands/:init/set/list/get/rm/reset 6 个子命令
  • 新增 xop run 子命令:--secret KEY=NAME(envp 注入) + %XOP_KEY%(argv 占位符),通过 SecretRef::argv_placeholder 区分
  • 新增 xop reset --yes 子命令:清空 vault + audit
  • subcommand enum:init / set / list / get / rm / reset / run / help
  • Args 重构:subcmd: Option<Subcmd> + flat exec 字段 + Args::as_exec() + ExecArgs.argv_placeholders
  • run_join_and_exec:单次 vault 开锁统一解析 --secret 和 %XOP_KEY%;scrub_argv 替换 argv、build_envp_delta 仅生成 envp
  • spawn_child 真实现:tokio::process::Command + pre_exec 闭包设 RLIMIT_CORE=0
  • pipe_filter_loop 真实现:stdout/stderr 双 pipe reader,过滤后写回 inherited
  • build_envp_delta 真实现:从 ResolvedValue[] 生成 Vec<(String, String)>,按 argv_placeholder 过滤
  • TTY-aware rpassword_prompt:stdin 是 TTY → /dev/tty;stdin 不是 TTY → fallback stdin(agent / pipe / expect 友好)
  • Cargo feature test-bypass:仅在 cargo test --features test-bypass 时启用 XOP_VAULT_PASSWORD 旁路;release 永不包含
  • 39 unit test + 11 integration test 全绿
  • Makefile:build / install(/usr/local/bin/xop)/ uninstall / test / smoke / clippy / clean
  • 4 篇 docs 全部更新到 v0.2(design / architecture / threat-model / comparison)
  • 端到端 SSH 实测:xop run --secret SSHPASS=s11_pass -- sshpass -e ssh [email protected] ls /Users 跑通

✅ v0.2.1(2026-10-02,用户实测 4 问题修复):

  • xop set 值输入不再明文回显:TTY 走 rpassword password_feedback_partial_mask('*', 2)(前 2 位明文 + 其余 *)
  • 免密解锁改用文件 keyring:src/vault/keyring.rs(~/.x/xop/keyring,0600 hex 密钥,xop init 自动写);OS 预闸门照旧先跑,之后 set/list/get/rm/run 免 passphrase → AI agent 可无人值守跑 xop run。曾实现过 macOS Keychain 方案,因自动化时弹系统授权对话框被用户否决并整体删除——xop 不调 security(1)
  • OS 闸门改为真指纹:src/auth/touchid.rs 用 osascript -l JavaScript 调 LAContext.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics)(biometrics-only,弹窗里没有密码框可点)。旧的 do shell script "…" with administrator privileges 实为系统登录密码框,且取消后被当"不可用"静默降级继续执行(实测 xop set 取消指纹仍存了 secret)——现取消/拒绝一律 AuthCancelled exit 77;无指纹设备/会话 → xop passphrase;Linux pkexec 系统口令框删除(gate 变为 no-op)
  • 新增 xop key [--save|--remove] 子命令:查看/补写/吊销 keyring(用户既有 vault 跑一次 xop key --save 即启用免密)
  • xop get 默认脱敏:输出 su****【xop禁止将密钥泄漏】(前 2 位,同 I11 mask 格式),明文只在显式 -v/--value 时打印且 stderr 带警示。动因:agent 会话里 xop get 的 stdout 直接进模型上下文/日志/shell history——I1 在"读取"路径上原本不设防。-v 是人眼专用逃生门,agent 用密钥必须走 xop run --secret 注入
  • SSH 实测二次修正:闸门返回 Gate(auth::decide 纯函数决策表)——SSH 交互会话绝不弹指纹(SSH_TTY/SSH_CONNECTION/SSH_CLIENT 检测;LAContext 弹窗只会出现在本机控制台),且无指纹现证(SSH/无生物特征/Linux 交互/osascript 坏)时 keyring 不参与解锁,强制输入 xop passphrase;只有「本地指纹通过」或「headless 非 TTY 自动化」允许 keyring 静默。Vault::open 按 Gate 分支。Linux 不再有 pam.rs
  • stdout leak guard 修复真 bug:pipe_filter_loop 的 guard_for_reader 原来是直通 stub(这就是用户看到 xop run echo %XOP_s19_pass% 打印明文 123456 的原因);现在按行 buffer(跨 chunk 的密钥不漏检)+ mask 格式 12****【xop禁止将密钥泄漏】 + kill/refuse 时 SIGKILL 子进程 + audit leak_event
  • xop reset --yes 级联删 keyring 文件
  • 64 unit + 17 integration 全绿(端到端 mask ×2、keyring 免密解锁 ×1——env_remove 掉口令通道验证 run 仍成功、touchid LAError 分类 ×8、auth 决策表 decide ×5、SSH+headless 仍走 keyring ×1、get 默认 mask ×2);release 构建 I9 strings 校验通过

✅ v0.3 (2026-10-07,argv 占位符语法改名):

  • argv 占位符语法从 xop://KEY 改为 %XOP_KEY%——更直观、grep 友好(grep '%XOP_' 一抓一个准)、无 shell 展开冲突
  • 旧 xop://KEY 在 expand_xop_placeholders 前置 reject,清晰报错 xop://KEY 占位符在 v0.3 移除;请改用 %XOP_KEY%,不留静默坑
  • regex 由 xop://([A-Za-z_][A-Za-z0-9_]*) 改为 %XOP_([A-Za-z_][A-Za-z0-9_]*)%(前缀需大写 XOP_,后缀 %)
  • 64 unit + 17 integration 全绿;run_masks_argv_placeholder_value 用 %XOP_PH% 重写

✅ v0.4 (2026-10-07,SSH_ASKPASS 注入):

  • 新增 xop --askpass=NAME / xop run --askpass=NAME:解决「直连 ssh user@host 时密码无处放」的根问题——%XOP_PASS% 替换后会出现在 ps,SSHPASS env 只能给 sshpass -e 用,ssh 本身不读 env
  • 实现:mkdtemp(0700) 建 /tmp/xop-askpass-XXXXXX/,写 0600 data + 0700 getpass.sh(cat "$XOP_ASKPASS_DATA"),子进程设 SSH_ASKPASS=<script> + SSH_ASKPASS_REQUIRE=force + DISPLAY=:0 + XOP_ASKPASS_DATA=<data>,值永不进 argv/env
  • AskpassHandle::Drop 跑 srm -m(无 srm 时 fallback rm -rf)——临时文件被回收(包括子进程崩溃、scope exit)
  • SecretRef::askpass() 构造器 + askpass: bool 标志(沿用 v0.3 argv_placeholder 模式);run_exec 把 askpass refs 从 envp_resolved 切出来单独 setup,stdout guard 仍能 mask 全值兜底
  • 移除 injector::plan() 的 SSH_* 自动检测:askpass 现在显式 opt-in,跟 v0.3「少魔法」一致——--askpass=ssh_pass -- ssh user@host 显式给,--secret SSHPASS=ssh_pass -- sshpass -e ssh user@host 显式走 sshpass
  • 用法:xop run --askpass=ssh_pass -- ssh user@host(不在 argv、不在 env、不在 stdout)
  • v0.4 单 secret 限制:多 secret askpass(e.g. ssh passphrase + sudo)P2;SIGKILL 残留靠 /tmp launchd 清理
  • 68 unit(+4 askpass 单测)+ 6 askpass 集成测试(env 设置 / 脚本输出 / 临时目录清理 / 不进 env / 缺 key / 与 env 注入并行)
  • 端到端实测通过 (2026-10-07,192.168.1.19):xop run --askpass=s19_pass -- ssh '%XOP_s19_user%@host' 真 SSH 登录跑通;Drop 跑完 /tmp/xop-askpass-* 零残留;stdout guard 把 %XOP_s19_user% 替换的真用户名也 mask 掉

✅ v0.5 (2026-10-22,list glob 过滤 + 描述元数据 + 数据目录搬家):

  • 影响:xop list 从「一屏裸 key 名」变成「带描述、可过滤」;key 多了人/AI 可读的用途说明(存在加密 vault 内,不落明文文件)
  • xop list [GLOB...]:可给多个 pattern 取并集,* 任意长、? 单字符、大小写敏感;内置轻量匹配器 src/glob.rs,零新依赖;--names-only 只列名字
  • xop desc KEY "文本":唯一形态(无 list-all / show-one / --clear 子形态),空串 "" = 清除描述;描述存进 vault 的 __meta__ 子表(TOML)——引号与清除方式在 v0.5.1 改过,见下
  • vault 明文格式:无描述时保持旧的扁平布局(KEY = "value"),老版本 xop 二进制仍能读;有描述时追加 [__meta__] 子表
  • 数据目录搬家:~/.xop/ → ~/.x/xop/(key.db / keyring / audit.jsonl 全搬)。迁移是复制不是移动——旧目录留作备份,新 vault 已存在时迁移自动跳过
  • 96 unit + 32 integration 全绿;cargo fmt --all + clippy 无新增告警

✅ v0.5.1 (2026-10-22,两处用户反馈修正):

  • 影响 1 · 描述不用打引号:xop desc KEY "文本" → xop desc KEY [TEXT...],多个词用空格 join(xop desc KEY 生产库 密码)。带引号也兼容(shell 通常会吃掉;真打进 vault 的会被剥一层)。不写文字 = 清除描述——不用再敲空引号 ""
  • 影响 2 · xop list / xop desc 免密免 Touch ID(用户:"AI 做会中断"):这两个只碰元数据(key 名 + 描述),永不吐 value,所以跳过 OS 身份闸门(Vault::open_metadata,keyring 静默解锁;无 keyring 才回落手输 passphrase)。get/set/rm/run 仍全套过闸门(auth::needs_gate(Intent::Value))
  • 新增 auth::Intent + auth::needs_gate(intent) 把"哪些操作要闸门"写成可测的纯函数;Vault::open 与 open_metadata 共享 decrypt_with 核心
  • 集成测试新增 pty 回归测试 list_under_a_tty_never_prompts_for_biometrics:用 script -q /dev/null 起真 pty(pty 里 is_terminal() 为真),带 30s 超时——闸门若回来就会卡在 Touch ID 弹窗上,测试即挂
  • 107 unit + 36 integration 全绿

✅ v0.5.2 (2026-10-22,xop list 搜索也不用打引号):

  • 影响:xop list 的搜索词默认是纯子串匹配——xop list git_local 直接命中 key 名或描述里含 "git_local" 的行,不用引号、不用 *。老写法 xop list 'git_*' 仍然可用
  • 为什么:* 是 shell 元字符——zsh 里 xop list git_local* 没匹配文件会直接报 no matches found,所以"带通配符的搜索"天生要引号。解法不是"少打引号",而是让日常搜索根本不需要通配符
  • 匹配规则:搜索词不含 * ? [ → 大小写不敏感的子串匹配,命中 key 名或描述;含元字符 → 该词切 glob 语义(整名匹配 key,或在描述里"某处出现"),老语义不变
  • 多个搜索词取并集(xop list git s19);--names-only 不变
  • src/glob.rs 加 4 个 helper:has_meta / matches_ignore_case / contains_ignore_case / contains_glob_ignore_case(底层 matches 仍大小写敏感、纯 glob 引擎)
  • 118 unit + 40 integration 全绿

⚠️ P1 / 未来工作:

  • spawn_child 真实现 ✅ v0.2
  • pipe_filter_loop 真实现 ✅ v0.2
  • build_envp_delta 真实现 ✅ v0.2
  • xop://KEY argv 占位符 (v0.2 引入,v0.3 改名 %XOP_KEY%) ✅
  • Askpass 注入策略(SSH_ASKPASS + DISPLAY=:0 + SSH_ASKPASS_REQUIRE=force) ✅ v0.4
  • xop list glob 过滤 + xop desc 描述元数据 ✅ v0.5
  • 多 secret askpass(v0.4 单 secret;P2)
  • NetworkGuard 的 pf/iptables 真接入(当前是 stub,新 vault flow OK)
  • FileGuard 的 sandbox-exec/landlock 真接入(当前是 stub)
  • argv scrubber(检测 --password=value 等显式模式)

完整 TODO 列表见 HANDOFF.md。


6. 常见踩坑(来自实测 + 设计权衡)

  1. bash 会展开 $VAR — xop ssh user:$SSH_PASSWORD@host 在 bash 里 $SSH_PASSWORD 先被 bash 展开成真值,xop 看到的是真值。永远用 --secret KEY=NAME flag。

  2. secrecy::SecretBox 的 expose_secret() — 必须 use secrecy::ExposeSecret; 才能调。如果 import 漏了,编译错 E0599。./src/{secret,guard/stdout,vault/mod.rs}.rs 都已加。

  3. async fn in trait 必须 #[async_trait] — Auth::authenticate 和 Guard::setup/teardown 都是 async。trait 必须 derive async_trait::async_trait,且 Cargo.toml 依赖 async-trait = "0.1"。

  4. tokio::process::Command 不支持 setrlimit — 想在子进程设 RLIMIT_CORE=0 必须用 pre_exec 闭包(runs after fork, before exec)。当前 lib.rs::spawn_child 已实现,参考 nix::sys::resource::setrlimit。

  5. Secret<String> 在 secrecy 0.10 改名成 SecretBox<String> — 别按 0.8 文档写代码。

  6. stdout mask 用 Vec<u8> 不是 String — 子进程的 stdout 可能是 UTF-8 invalid(binary data);用 bytes 避免 from_utf8 panic。

  7. audit log 写之前调 .flush() — 否则 child crash 时 audit 丢失。AuditLog::write_event 已 flush。

  8. macOS 指纹 = osascript -l JavaScript 调 LAContext,不是 admin 弹窗 — do shell script … with administrator privileges 是系统登录密码框(红线禁止),且 osascript 会命中 admin 授权缓存导致"看起来免密"其实是缓存放行。正确姿势:JXA ctx.evaluatePolicyLocalizedReasonReply(1, reason, fn)(policy 1 = biometrics-only,无密码选项)+ 主线程 NSRunLoop.runUntilDate 自旋等 block 回调。实测 JXA 能把私有队列的 block 回调 marshal 回 JS 线程(NSOperationQueue 探针 107ms 通过);LAContext 无缓存,每次调用都真弹指纹。取消分类:-128/-5/-12 → 拒绝操作;-7/-8/-10/-11/-1008/-1/-6 → 无指纹降级 passphrase。

  9. Linux 交互 = 直接输 xop passphrase(pam.rs 已删除) — 旧实现 pkexec -- true 弹的是 polkit 系统密码框,违反"任何时候不要让用户输入系统密码"红线(2026-10-02)。Linux 没有可移植的纯指纹 CLI 闸门,身份无法被生物特征证明 → decide 返回 RequirePassphrase(keyring 也不参与);headless 自动化仍走 keyring 静默。真 Touch ID 闸门仅 macOS 有。

  10. atomic vault write 用 tmp + rename — ~/.x/xop/key.db.tmp.<pid> 写完 fsync 后 rename 到 key.db,断电不留下半截文件。

  11. argon2id 参数:m=64 MiB, t=3, p=4 — 慢 ≈250ms / attempt,现代 CPU 上比 bcrypt/scrypt 都强。别调低。

  12. XOP_VAULT_PASSWORD 是 release 后门,必须 gated — v0.2 早期把它当 CI/agent 旁路直接读 env,等于"任何有 env 的进程都能解密 vault"。当前用 #[cfg(feature = "test-bypass")] 包住;release 永远不编译这段。校验手段:strings target/release/xop | grep XOP_VAULT_PASSWORD 必须空。

  13. TTY-aware passphrase prompt 怎么选 — is_terminal(stdin) 决定走 /dev/tty 还是 stdin fallback。如果用 /dev/tty 检测(/dev/tty 文件存在性)会误判(SSH 下文件存在但不可用)。用 std::io::IsTerminal(POSIX isatty(fd))才是真信号。

  14. vault 不要开两次 — 早期 xop run 内部先 expand_xop_placeholders 开一次 vault,再 run_exec 开一次,导致用户输两次 passphrase。修复:让 expand_xop_placeholders 只收集名字(不开 vault),把 placeholder 加进 SecretRef::argv_placeholder=true 的列表,让 run_exec::collect_refs 一次性带去 resolve_all。原则:vault 整个进程最多 open 一次。

  15. SecretRef::argv_placeholder 标志位 — 区分 envp 注入(--secret KEY=NAME)和 argv 占位符(%XOP_KEY%),但走同一个 vault 解析。build_envp_delta 跳过 placeholder,scrub_argv 处理 placeholder。ResolvedValue 镜像这个标志位。

  16. 绝不在后台自动化里对真实钥匙串做写/删 — v0.2.1 曾实现 macOS Keychain 存 passphrase,security(1) 在 agent 会话里会弹出系统授权对话框("xop wants to delete/modify keys"),用户看到就是安全事故,方案整体否决删除。免密改走 0600 文件 keyring:无 GUI、无弹窗、可 xop key --remove 秒吊销。

  17. keyring 静默解锁必须"身份有来源" — Vault::open 先 auth::authenticate() → Gate:AllowKeyring(本地指纹刚通过 / headless 非 TTY 自动化)才读 keyring;RequirePassphrase(SSH 交互会话、无可用生物特征、osascript 坏、Linux 交互)直接强制手输 xop passphrase,keyring 根本不参与——否则"免密"就没有任何身份验证垫底。旧两版 bug:keychain 方案"命中即连闸门都不问";指纹闸门版把 SSH/无指纹也当"降级继续"仍走 keyring。另外:lib 单元测试禁止改全局 env(HOME/XOP_NO_KEYRING/SSH_*)——并行跑会互相污染(实测 4 个 keyring 测试因 set_var("HOME") 竞态随机红),文件逻辑/决策逻辑要抽成参数显式的纯函数(auth::decide(tty, ssh, bio)、keyring::*_at(&Path))测。

  18. SSH 会话里 isatty(0) 是 true,但绝不能弹指纹 — SSH 的 stdin 是 sshd 分配的 pty,TTY 检测≠本地控制台。LAContext 的 Touch ID 窗口只会出现在本机物理控制台,远程用户既看不到也点不了,表现为"卡住/错弹"。正确做法:检测 SSH_TTY/SSH_CONNECTION/SSH_CLIENT env(sshd 注入、本地 Terminal 不会有)→ 直接 Gate::RequirePassphrase(用户输管理员密码,keyring 免谈);ssh host cmd 无 pty 的自动化场景走 headless keyring 静默。顺序必须 !tty → AllowKeyring 先判,tty+ssh 才 RequirePassphrase。

  19. stdout mask 必须按行 buffer — 子进程输出的一个 4096 字节 chunk 可能把密钥劈成两半;pump() 只在遇到 \n 时才 filter+flush 完整行,残行留在 carry buffer,EOF 再补一次。直接 filter 每个 chunk 会漏检跨 chunk 密钥。expect/Tcl 断言 mask 时注意 glob 的 * 匹配任何字符——要用 regexp {to\*+} $log 匹配字面星号。

  20. xop get 默认输出的 su****【xop禁止将密钥泄漏】 不是 bug,是闸门 — agent 会话里工具 stdout 直通模型上下文;get 若回显明文,注入链路(run 子进程 mask)做得再好也白搭——密钥从"读取"这条路就出去了。看到 mask 说明值存在且对路,继续用 xop run 注入即可;严禁给 agent 路径加 -v(-v 是给人眼核对的逃生门,stderr 会打警示)。测试:integration get_masks_value_by_default / get_dash_v_prints_plaintext。

  21. vault key 名 ≠ 字面值 — s19_user/s19_pass 是 vault 里的 key 名字(xop list 列的那些),不是 SSH 用户名/密码的真值。SSH 命令里用户名走 %XOP_s19_user% argv 占位符,密码走 --askpass=s19_pass。若把字面 s19_user 当 SSH 用户名传过去,server 自然不认识 → "Permission denied"。调试时若拿不准 key 下存的是什么,用 %XOP_key% 占位符+stdout guard 拿 mask 前缀(不暴露值)反推;严禁 xop get -v key(明文进上下文)。

  22. 数据目录搬家 ~/.xop/ → ~/.x/xop/ 是「复制不移动」 — 用户的真实 vault 有 18+ key,迁移只做复制(key.db / keyring / audit.jsonl),旧目录原样留作备份;新目录已有 vault 时迁移自动跳过。src/datadir.rs::migrate_legacy_from(new, old) 路径参数显式化,单测不碰全局 HOME(AGENTS.md 坑 18 同款纪律)。新目录 0700、复制出的文件 0600。

  23. vault 明文里加 __meta__ 子表不破坏旧格式 — toml 0.8 序列化时普通值先于表输出,所以 KEY = "value" + [__meta__] 不会触发 ValueAfterTable。encode_plaintext 在 meta 为空时完全省略 __meta__ 表,让没描述的 vault 保持旧的扁平布局,老版本 xop 二进制照样能读。

  24. glob 匹配器自研而不是引 globset — 需求只有 * 和 ?;引依赖会带来正则语义([]/{})与 xop「零外部依赖」的定位冲突。src/glob.rs 经典双指针 + 回溯 star 记录,11 条单测覆盖 exact/前缀/后缀/中缀/多星/问号/空串/大小写/并集。注意 * 不匹配字面 _:matches("*_user","user") = false。

  25. 元数据操作要免闸门,值操作不能免 — 2026-10-22 用户反馈:"xop list 应该是免密免 touch 的吧,不然 AI 做会中断"。闸门的意义是"释放真值前要有人在场",而 list/desc 只给 key 名和描述,永不吐 value,所以跳过闸门不泄漏任何 secret。实现上别图省事把 Vault::open 的闸门参数去掉——那会让 get/run 也免掉;正确做法是新增一条 open_metadata 路径,并用 auth::needs_gate(Intent) 把策略写成可测的纯函数

  26. pty 回归测试用 script -q /dev/null — macOS 的 script 能给子进程起真 pty(test -t 0 为真),正好复现"终端里跑 xop list"的场景。关键是要带超时:闸门一旦回来,子进程会卡在 Touch ID 弹窗上,测试会挂死而不是失败。用 std::sync::mpsc::recv_timeout + 后台线程收 wait_with_output 兜住

  27. 描述文字不要求引号,但兼容引号 — 用户明确说「打引号很难输入」(中文输入法/键盘布局)。所以 xop desc 的文字参数用 Vec<String> + trailing_var_arg,多个词 join 成一句;用户真打进 vault 的一层引号在 join_description 里剥掉。注意剥引号时的切片安全:只认 ASCII 单字节引号,切点必然是 char 边界

  28. "搜索要打引号"的根因是 shell,不是 xop — xop list 'git_local*' 必须加引号,因为 * 是 shell 通配符:zsh 下 xop list git_local* 没匹配文件直接报 no matches found,bash 下则被展开成一堆文件名。引号是躲 shell 的,不是躲 xop 的。所以正解不是"想办法少打引号",而是让日常搜索根本不需要通配符——v0.5.2 把默认搜索改成纯子串匹配(xop list git_local),*/?/[ 只在用户显式写了时才切回 glob 语义。想给 shell 递一个"不展开"的参数只能靠引号或反斜杠,xop 这边无能为力


7. 与 xstudio 的衔接(未来)

xop 是独立项目,但定位上是 xstudio xstudio.ai.runAgentLoop 的"secret 安全层"。集成路径:

  • 短期:xstudio plugin 通过 Process.run("/usr/local/bin/xop --secret ... -- <cmd>") 调用 xop
  • 中期:xop 暴露 pub use xop::run library mode,xstudio 直接 link
  • 不集成:xop 永远不需要知道 xstudio 存在(独立开源)

参考 xstudio 项目里的 xstudio-control skill(同义物)。


8. 文档索引

想看 路径
一句话定位 + CLI 速查 本文件(AGENTS.md)
完整交接 / 实施路线图 HANDOFF.md
整体设计 + 命令 + 架构 + 不变量 docs/design.md
12 个威胁 + v0.2 缓解状态 docs/threat-model.md
vs secret-agent / op run / Vault Agent / Deno docs/comparison.md
模块依赖图 + 数据流 + trait 表面 docs/architecture.md
参考实现 refs/secret-agent/
实战示例 examples/{init,list,get,ssh,mysql,dry-run}.sh
集成测试 tests/integration.rs

9. License

MIT.