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

351 lines
38 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# xop · AI Agent 操作速查(上下文压缩后自动加载)
> 本文件是 **xop 给 AI agent 的"可执行附录"**:Claude Code / WorkBuddy / 其他 agent harness 在每次会话开头、以及**上下文压缩(compact)后**都会自动重新加载它。
> 项目根:`/Users/xs/Documents/x/xop`
> 完整交接文档在 [`HANDOFF.md`](./HANDOFF.md);架构/威胁模型/对比在 [`docs/`](./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. 编译 + 测试
```bash
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 用法速记
```bash
# ── 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`](./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。
10. **Linux 交互 = 直接输 xop passphrase(`pam.rs` 已删除)** — 旧实现 `pkexec -- true` 弹的是 polkit **系统密码框**,违反"任何时候不要让用户输入系统密码"红线(2026-10-02)。Linux 没有可移植的纯指纹 CLI 闸门,身份无法被生物特征证明 → `decide` 返回 `RequirePassphrase`(keyring 也不参与);headless 自动化仍走 keyring 静默。真 Touch ID 闸门仅 macOS 有。
11. **atomic vault write 用 tmp + rename** — `~/.x/xop/key.db.tmp.<pid>` 写完 fsync 后 rename 到 `key.db`,断电不留下半截文件。
12. **argon2id 参数:m=64 MiB, t=3, p=4** — 慢 ≈250ms / attempt,现代 CPU 上比 bcrypt/scrypt 都强。**别调低**。
13. **`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` 必须空。
14. **TTY-aware passphrase prompt 怎么选** — `is_terminal(stdin)` 决定走 `/dev/tty` 还是 stdin fallback。如果用 `/dev/tty` 检测(`/dev/tty` 文件存在性)会误判(SSH 下文件存在但不可用)。**用 `std::io::IsTerminal`**(POSIX `isatty(fd)`)才是真信号。
15. **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 一次**。
16. **`SecretRef::argv_placeholder` 标志位** — 区分 envp 注入(`--secret KEY=NAME`)和 argv 占位符(`%XOP_KEY%`),但走同一个 vault 解析。`build_envp_delta` 跳过 placeholder,`scrub_argv` 处理 placeholder。`ResolvedValue` 镜像这个标志位。
17. **绝不在后台自动化里对真实钥匙串做写/删** — v0.2.1 曾实现 macOS Keychain 存 passphrase,`security(1)` 在 agent 会话里会弹出**系统授权对话框**("xop wants to delete/modify keys"),用户看到就是安全事故,方案整体否决删除。免密改走 0600 文件 keyring:无 GUI、无弹窗、可 `xop key --remove` 秒吊销。
18. **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)`)测。
20. **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` 匹配字面星号。
21. **`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`。
22. **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`(明文进上下文)。
23. **数据目录搬家 `~/.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。
24. **vault 明文里加 `__meta__` 子表不破坏旧格式** — toml 0.8 序列化时**普通值先于表输出**,所以 `KEY = "value"` + `[__meta__]` 不会触发 ValueAfterTable。`encode_plaintext` 在 meta 为空时**完全省略 `__meta__` 表**,让没描述的 vault 保持旧的扁平布局,老版本 xop 二进制照样能读。
25. **glob 匹配器自研而不是引 globset** — 需求只有 `*` 和 `?`;引依赖会带来正则语义(`[]`/`{}`)与 xop「零外部依赖」的定位冲突。`src/glob.rs` 经典双指针 + 回溯 star 记录,11 条单测覆盖 exact/前缀/后缀/中缀/多星/问号/空串/大小写/并集。注意 `*` 不匹配字面 `_`:`matches("*_user","user")` = false。
26. **元数据操作要免闸门,值操作不能免** — 2026-10-22 用户反馈:"`xop list` 应该是免密免 touch 的吧,不然 AI 做会中断"。闸门的意义是"释放真值前要有人在场",而 `list`/`desc` 只给 key 名和描述,**永不吐 value**,所以跳过闸门不泄漏任何 secret。实现上别图省事把 `Vault::open` 的闸门参数去掉——那会让 `get`/`run` 也免掉;正确做法是**新增一条 `open_metadata` 路径**,并用 `auth::needs_gate(Intent)` 把策略写成可测的纯函数
27. **pty 回归测试用 `script -q /dev/null`** — macOS 的 `script` 能给子进程起真 pty(`test -t 0` 为真),正好复现"终端里跑 `xop list`"的场景。关键是要**带超时**:闸门一旦回来,子进程会卡在 Touch ID 弹窗上,测试会挂死而不是失败。用 `std::sync::mpsc::recv_timeout` + 后台线程收 `wait_with_output` 兜住
28. **描述文字不要求引号,但兼容引号** — 用户明确说「打引号很难输入」(中文输入法/键盘布局)。所以 `xop desc` 的文字参数用 `Vec<String>` + `trailing_var_arg`,多个词 join 成一句;用户真打进 vault 的一层引号在 `join_description` 里剥掉。注意剥引号时的切片安全:只认 ASCII 单字节引号,切点必然是 char 边界
29. **"搜索要打引号"的根因是 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`](./HANDOFF.md) |
| 整体设计 + 命令 + 架构 + 不变量 | [`docs/design.md`](./docs/design.md) |
| 12 个威胁 + v0.2 缓解状态 | [`docs/threat-model.md`](./docs/threat-model.md) |
| vs secret-agent / op run / Vault Agent / Deno | [`docs/comparison.md`](./docs/comparison.md) |
| 模块依赖图 + 数据流 + trait 表面 | [`docs/architecture.md`](./docs/architecture.md) |
| 参考实现 | `refs/secret-agent/` |
| 实战示例 | `examples/{init,list,get,ssh,mysql,dry-run}.sh` |
| 集成测试 | `tests/integration.rs` |
---
## 9. License
MIT.