影响: 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]>
6.2 KiB
xop vs existing tools
Detailed positioning against the 5 most relevant alternatives as of 2026-10-01.
At a glance
| Tool | Vault? | Injection method | Stdout mask | Network policy | File policy | OS-auth gate |
|---|---|---|---|---|---|---|
| xop (this) | self (AES-256-GCM, argon2id) | envp (+ askpass P1) | ✅ | ✅ (pf/iptables, stubbed P1) | ✅ (sandbox-exec, stubbed P1) | ✅ Touch ID (biometrics-only; SSH/no-biometric → passphrase; Linux: passphrase-only) |
| secret-agent | self (age + sqlite) | envp (template) | ✅ | ❌ | ❌ | ❌ (passphrase only) |
1Password op run |
external (1P only) | envp | ✅ (default) | ❌ | ❌ | ✅ (1P account) |
| HashiCorp Vault Agent | external (Vault) | env file + sidecar | ❌ | ❌ | ❌ | ✅ (Vault token) |
Bitwarden bw |
external (BW) | envp | ❌ (manual) | ❌ | ❌ | ✅ (BW account) |
| Deno permission | n/a | runtime | n/a | ✅ | ✅ | n/a |
Where xop wins
-
OS-level pre-gate before the unlock secret. secret-agent and other self-hosted vaults only require a passphrase. xop gates with a real Touch ID prompt first on the local console (macOS, via
LAContext.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics)— biometrics-only, cancelling refuses the operation). The gate's verdict then decides whether the keyring (~/.x/xop/keyring, 0600 — silent, agent-friendly) may unlock: only a local biometric pass or a headless automation context (agent/pipe) get silent unlock; SSH sessions and machines without usable biometrics must type the xop passphrase — a silent keyring pass there would mean zero identity check. Linux interactive is passphrase-only by design (system-password prompts explicitly forbidden). The gate runs even with a keyring present, so biometric alone never decrypts; a stolenkey.dbstill needs the keyring file or the passphrase. (Explicitly NOT macOS Keychain — rejected 2026-10-02:security(1)popped system dialogs mid-automation.) -
Deno-style policy DSL for arbitrary Unix commands. secret-agent is great at injection but doesn't constrain what the child can do. xop adds
--allow-net=,--deny-read=, etc. — same proven model from Deno runtime. -
Zero external dependencies. xop owns its own encrypted vault. No
op/vault/securityCLI to set up; no OAuth flows; no per-resolve subprocess overhead. Single binary works on a fresh machine. -
LLM-aware guards. Built specifically for the AI-agent use case.
--on-leak=refuseis a parse-time check that catchesecho $SECRETpatterns before spawn — no other tool does this. -
No metadata leakage to
ps. v0.1 spawnedop readper resolve, which leakedop read op://DevOps/mysql/passwordinto process listings. v0.2 does all decryption internally — nothing inpsreveals what vault items exist.
Where existing tools win
- secret-agent has a more mature template engine (
{{NAME}}substitution in arbitrary command strings) and a richer subcommand surface (create/delete/list/exec/inject/get/env/...). xop only has init/set/list/get/rm + one exec verb. If you need template substitution, secret-agent wins. op runis production-grade for the 1Password-only use case. If you're already deep in 1Password, just useop run— it has OAuth refresh, device trust, and a decade of hardening.- Vault Agent has sidecar mode + auto-renewal + Consul Template integration. If you already run Vault Agent in your infrastructure, you don't need xop for the basic case.
- Deno is a runtime — it doesn't run arbitrary bash commands. They solve different problems; we just borrow the policy DSL syntax.
Detailed diff vs secret-agent
| Concern | secret-agent | xop (v0.2) |
|---|---|---|
| Vault storage | age + sqlite, self-managed | AES-256-GCM + argon2id, self-managed |
| Auth model | passphrase via SECRET_AGENT_PASSPHRASE env or prompt |
Touch ID pre-gate (biometrics-only, cancel = refuse) + passphrase prompt |
| Reference syntax | bare-key (e.g. db_pass) |
bare-key (e.g. db_pass) |
| Injection mechanism | env template ({{NAME}} in command string) |
--secret KEY=NAME flag (envp) |
| Stdout sanitization | regex mask by secret name | regex mask by secret name + --on-leak=kill|refuse |
| Network policy | none | --allow-net= / --deny-net= (pf/iptables, stubbed P1) |
| File policy | none | --allow-read= / --deny-read= (sandbox-exec, stubbed P1) |
| Dry-run | secret-agent exec --dry-run |
xop --dry-run (shows parsed cmd + effective policy) |
| Audit | none | JSONL log with policy_hash for replay |
| Sub-command surface | 11 commands (create/delete/list/exec/inject/get/env/...) | 6 (init/set/list/get/rm/help) + one exec verb |
| Per-resolve subprocess | none (in-process) | none (in-process) — both avoid spawning CLI per resolve |
| Two-factor by default | no (passphrase only) | yes (OS auth + passphrase) |
| Library mode | no | planned v0.3 (use xop::exec) |
When NOT to use xop
- ❌ You need 1Password / Vault / Bitwarden integration → use those tools directly.
- ❌ You need a richer template engine (substituting
{{NAME}}inside command strings) → use secret-agent. - ❌ You're running untrusted code (not just untrusted commands) — use gVisor / Firecracker / proper microVM isolation.
When to use xop
- ✅ You're building or operating an AI agent (Claude Code, Cursor, custom) and want defense-in-depth around what credentials it can touch AND what it can do with them.
- ✅ You want a single binary with no external service dependencies (no 1P account, no Vault server).
- ✅ You want an OS-level biometric gate (real Touch ID prompt on macOS — no password dialog anywhere in the flow) before the passphrase — two-factor by default.
- ✅ You want dry-run mode that shows the effective policy before execution (great for agent self-correction).
- ✅ You want audit-grade logs of which refs were used when, without storing values.