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]>
This commit is contained in:
xop-botandClaude Code committed 2026-10-22 17:03:12 +08:00
1 parent f7cff869b7
commit 7660b92d70
38 files changed
+2114 -299

No files matched your search

+3 -3
View File
@@ -64,7 +64,7 @@ $ xop --secret DB_PASS=db_pass \
4. Vault resolve (vault::resolve_all)
→ auth::authenticate() → Gate // headless(non-TTY)→AllowKeyring; SSH pty→RequirePassphrase (never remote biometric);
// local TTY: LAContext fingerprint — pass→AllowKeyring, cancel→exit 77, no-biometrics→RequirePassphrase
→ Gate::AllowKeyring ∧ keyring::load() // ~/.xop/keyring (0600) hit → key, no typing
→ Gate::AllowKeyring ∧ keyring::load() // ~/.x/xop/keyring (0600) hit → key, no typing
→ Gate::RequirePassphrase ∨ no keyring // rpassword::prompt_password() → derive_key = argon2id(passphrase, salt)
→ AES-GCM decrypt → entries["db_pass"] = "hunter2"
→ ResolvedValue { key: "DB_PASS", name: "db_pass", backend: "vault", value: Secret("hunter2") }
@@ -155,7 +155,7 @@ Other subcommands follow the same shape:
Vault subcommand events:
```jsonl
{"ts":"...","event":"vault_init","path":"/home/x/.xop/key.db"}
{"ts":"...","event":"vault_init","path":"/home/x/.x/xop/key.db"}
{"ts":"...","event":"vault_unlock","auth":"touchid","success":true}
{"ts":"...","event":"vault_set","name":"DB_PASS"}
{"ts":"...","event":"vault_get","name":"DB_PASS","ok":true}
@@ -178,7 +178,7 @@ pub struct Vault { path, salt, nonce, key, entries }
impl Vault {
pub async fn open(path: &Path) -> Result<Self>;
// open order is FIXED: auth::authenticate() FIRST, then keyring::load()
// (~/.xop/keyring, 0600 — NOT macOS Keychain) — falls back to typed
// (~/.x/xop/keyring, 0600 — NOT macOS Keychain) — falls back to typed
// passphrase + argon2id only when the keyring is absent/XOP_NO_KEYRING=1.
pub async fn create(path: &Path, passphrase: &str) -> Result<Self>;
// create writes the vault AND saves the derived key to the keyring.
+1 -1
View File
@@ -15,7 +15,7 @@ Detailed positioning against the 5 most relevant alternatives as of 2026-10-01.
## Where xop wins
1. **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 (`~/.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 stolen `key.db` still needs the keyring file or the passphrase. (Explicitly NOT macOS Keychain — rejected 2026-10-02: `security(1)` popped system dialogs mid-automation.)
1. **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 stolen `key.db` still needs the keyring file or the passphrase. (Explicitly NOT macOS Keychain — rejected 2026-10-02: `security(1)` popped system dialogs mid-automation.)
2. **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.
+15 -13
View File
@@ -1,6 +1,6 @@
# xop · Design Document
> Status: v0.2.1 implemented (2026-10-02). Self-contained encrypted vault, no external backend dependencies. Unlock: OS auth gate first, then file keyring (`~/.xop/keyring`, 0600) or typed passphrase — **deliberately NOT the macOS Keychain** (rejected 2026-10-02: system dialogs during automation).
> Status: v0.2.1 implemented (2026-10-02). Self-contained encrypted vault, no external backend dependencies. Unlock: OS auth gate first, then file keyring (`~/.x/xop/keyring`, 0600) or typed passphrase — **deliberately NOT the macOS Keychain** (rejected 2026-10-02: system dialogs during automation).
## 1. Problem statement
@@ -22,7 +22,7 @@ The result is a worst-of-both-worlds: secrets leak into places they shouldn't, A
| P2 | **One-shot memory lifetime** | Real values live in the parent process only between `Vault::get()` and `execve()`. After `execve` returns, parent memory is zeroized (rpassword + zeroize crate). |
| P3 | **Defense in depth at every layer** | Independent guards: argv parse → OS auth (Touch ID gate) → keyring-or-passphrase unlock → envp inject → stdout mask (`12****【xop禁止将密钥泄漏】`) → network policy. Each fails closed independently. |
| P4 | **Deno-style permission DSL** | `--allow-net=`, `--deny-net=`, `--allow-read=`, `--deny-read=` — same model proven in production by Deno runtime. |
| P5 | **Self-contained vault, no external CLIs** | xop owns its own encrypted vault at `~/.xop/key.db` (AES-256-GCM, argon2id KDF). No `op`/`vault`/`security` subprocesses to verify, no per-resolve spawn overhead, no metadata leaked to `ps`. |
| P5 | **Self-contained vault, no external CLIs** | xop owns its own encrypted vault at `~/.x/xop/key.db` (AES-256-GCM, argon2id KDF). No `op`/`vault`/`security` subprocesses to verify, no per-resolve spawn overhead, no metadata leaked to `ps`. |
| P6 | **Refuse to do the wrong thing** | Any command that *itself* would print the secret (e.g. `echo $DB_PASS`, `env | grep PASS`, `set -x`) is detected at parse-time or runtime and either masked or refused. |
| P7 | **Boring infrastructure, hot path** | `xop` itself is <5MB static binary, no daemon, no server. Single `fork+execve` per command, returns child's exit code. |
@@ -31,14 +31,16 @@ The result is a worst-of-both-worlds: secrets leak into places they shouldn't, A
```
xop # banner + 5 examples (no panic, no error)
xop -h | --help | help # full help w/ subcommands + exec examples
xop init # first-run: prompt passphrase × 2, create ~/.xop/key.db
xop init # first-run: prompt passphrase × 2, create ~/.x/xop/key.db
xop set KEY # Touch ID → read stdin → encrypt → write
xop list # Touch ID → enumerate keys (name + created_at, no values)
xop list [TERM...] # NO Touch ID → enumerate keys (name + description, no values);
# a plain TERM is a quote-free substring search
xop desc KEY [TEXT...] # NO Touch ID → attach/clear a key's description (no quotes needed)
xop get KEY [-v|--value] # Touch ID → print value MASKED by default (first 2 chars +
# ****【xop禁止将密钥泄漏】); -v prints plaintext for HUMAN
# inspection only (agents must use `xop run` injection)
xop rm KEY # Touch ID → delete key (--force to skip confirm)
xop key [--save|--remove] # manage ~/.xop/keyring auto-unlock key (0600 file, NOT Keychain)
xop key [--save|--remove] # manage ~/.x/xop/keyring auto-unlock key (0600 file, NOT Keychain)
xop [flags] -- CMD [args] # exec mode (inject into child process)
```
@@ -54,7 +56,7 @@ Exec-mode flags (existing, mostly kept):
--on-leak=mask|kill|refuse # stdout action on secret pattern
--mask-pattern=REGEX # extra regex to mask in child stdout/stderr
--dry-run # print effective policy; never exec
--audit=PATH # default: ~/.xop/audit.jsonl
--audit=PATH # default: ~/.x/xop/audit.jsonl
--no-color # suppress color in output
```
@@ -98,7 +100,7 @@ Exit codes:
│ ▼ │
│ vault::resolve_all(refs) ─► auth → keyring ∨ passphrase → decrypt │
│ │ (single local vault, no subprocess) │
│ │ key: ~/.xop/keyring (0600) or argon2id(passphrase, salt) │
│ │ key: ~/.x/xop/keyring (0600) or argon2id(passphrase, salt) │
│ │ cipher: AES-256-GCM(key, nonce, plaintext) │
│ ▼ │
│ injector::plan + build_envp_delta (src/injector.rs) │
@@ -116,7 +118,7 @@ Exit codes:
│ ▼ │
│ waitpid() ─► exit code propagated │
│ │
│ Throughout: audit::AuditLog appends ref-only events to ~/.xop/audit.jsonl
│ Throughout: audit::AuditLog appends ref-only events to ~/.x/xop/audit.jsonl
└──────────────────────────────────────────────────────────────────────────┘
```
@@ -129,7 +131,7 @@ Exit codes:
xop --secret DB_PASS=db_pass --allow-net=db.local:5432 --deny-net=* -- mysql ...
# Both halves of KEY=NAME refer to vault keys (no scheme prefix in v0.2).
# KEY = env var name to inject; NAME = key in ~/.xop/key.db.
# KEY = env var name to inject; NAME = key in ~/.x/xop/key.db.
# They are usually the same string, but can differ when mapping multiple env names.
```
@@ -147,7 +149,7 @@ SSH_KEY="ssh_key"
Lines starting with `#` are comments; empty lines ignored.
## 6. Vault file format (`~/.xop/key.db`)
## 6. Vault file format (`~/.x/xop/key.db`)
Binary, fixed-position header for cheap parsing:
@@ -177,7 +179,7 @@ Each `set` / `rm` rewrites the entire file (re-randomizes nonce). Vault size ≈
│ prompt passphrase × 2 (confirm) │
│ generate salt + nonce + empty entries │
│ write vault atomically (tmp + rename) │
│ write keyring atomically (~/.xop/keyring, 0600, hex key) │
│ write keyring atomically (~/.x/xop/keyring, 0600, hex key) │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ set / list / get / rm / run (exec mode) │
@@ -201,7 +203,7 @@ Each `set` / `rm` rewrites the entire file (re-randomizes nonce). Vault size ≈
│ path that makes `xop run` unattended │
│ │
│ 2. Unlock key source: │
│ keyring::load() → Some(key) (file ~/.xop/keyring, 0600) │
│ keyring::load() → Some(key) (file ~/.x/xop/keyring, 0600) │
│ · mode&0o077 != 0 or non-hex → REFUSED (error) │
│ · XOP_NO_KEYRING=1 → skip file, go to prompt │
│ → silent; `xop run` works unattended (issue #3) │
@@ -252,7 +254,7 @@ Each `set` / `rm` rewrites the entire file (re-randomizes nonce). Vault size ≈
| 1Password `op run` | No integration in v0.2. If you already have 1Password set up and want zero infra, use `op run` — but it doesn't have network/file policy enforcement or Touch ID gate. |
| HashiCorp Vault Agent | Sidecar model; xop is fork-style. No integration. |
| Deno permission | Conceptual debt only — Deno governs its own runtime; xop governs foreign Unix processes via OS primitives. |
| macOS Keychain | **Rejected 2026-10-02** (implemented once, then removed — `security(1)` popped system authorization dialogs mid-automation; user veto). xop stores nothing in Keychain and never calls `security(1)`. Unlock-key storage = plain file `~/.xop/keyring` (0600). |
| macOS Keychain | **Rejected 2026-10-02** (implemented once, then removed — `security(1)` popped system authorization dialogs mid-automation; user veto). xop stores nothing in Keychain and never calls `security(1)`. Unlock-key storage = plain file `~/.x/xop/keyring` (0600). |
## 11. Implementation phases
+11 -9
View File
@@ -6,7 +6,7 @@
## T1 — LLM Provider Sees the Secret
**Attack:** agent calls `cat ~/.xop/key.db` or `echo $DB_PASS` to "verify" a value, plaintext flows into LLM provider's request body, gets logged server-side, possibly used for training.
**Attack:** agent calls `cat ~/.x/xop/key.db` or `echo $DB_PASS` to "verify" a value, plaintext flows into LLM provider's request body, gets logged server-side, possibly used for training.
**Mitigation:**
- Refs only (bare key names like `db_pass`) cross the LLM API trust boundary.
@@ -88,13 +88,13 @@
## T9 — Audit Log Itself Leaks
**Attack:** audit log JSONL file at `~/.xop/audit.jsonl` accumulates. If filesystem is later exfiltrated, secrets leak.
**Attack:** audit log JSONL file at `~/.x/xop/audit.jsonl` accumulates. If filesystem is later exfiltrated, secrets leak.
**Mitigation:** `src/audit.rs` writes ONLY refs and metadata, never values. Type system enforces this: `AuditEvent` has fields `ref: String`, `backend: String`, `child_pid: u32`, `policy_hash: String` — no `value: String` field exists. Invariant test (`audit::tests::no_value_field_in_any_event`) scans for `"value":`, `"plaintext":`, `"ciphertext":`, `"passphrase":` substrings in every test event.
## T10 — Vault File Stolen Off Disk
**Attack:** attacker gets filesystem read access (laptop theft, backup exfil, malicious process). They grab `~/.xop/key.db`.
**Attack:** attacker gets filesystem read access (laptop theft, backup exfil, malicious process). They grab `~/.x/xop/key.db`.
**Mitigation:**
- Vault is encrypted at rest: AES-256-GCM with 256-bit key derived via `argon2id(passphrase, salt)`.
@@ -103,7 +103,7 @@
- Per-save nonce is 12 bytes random — AES-GCM guarantees ciphertext indistinguishability across writes of the same plaintext.
- Auth tag (GMAC) detects tampering.
**Residual risk (v0.2.1):** if the attacker can also read `~/.xop/keyring` (same-UID process, or a backup that grabs the whole `~/.xop` dir), the passphrase factor is gone — the hex key decrypts the vault directly. Protections: keyring mode 0600 + dir 0700, `load()` REFUSES any group/other-readable file, `xop key --remove` revokes instantly, `XOP_NO_KEYRING=1` forces typing. Same-UID malware can equally type-jack a live terminal, so this does not widen the classic threat surface — but it IS the accepted tradeoff that makes `xop run` unattended-able. Threat T13 below covers it. Also: weak passphrase — future v0.3 may add zxcvbn-style strength meter during `init`.
**Residual risk (v0.2.1):** if the attacker can also read `~/.x/xop/keyring` (same-UID process, or a backup that grabs the whole `~/.x/xop` dir), the passphrase factor is gone — the hex key decrypts the vault directly. Protections: keyring mode 0600 + dir 0700, `load()` REFUSES any group/other-readable file, `xop key --remove` revokes instantly, `XOP_NO_KEYRING=1` forces typing. Same-UID malware can equally type-jack a live terminal, so this does not widen the classic threat surface — but it IS the accepted tradeoff that makes `xop run` unattended-able. Threat T13 below covers it. Also: weak passphrase — future v0.3 may add zxcvbn-style strength meter during `init`.
## T11 — Attacker Bypasses OS Auth (Touch ID)
@@ -113,6 +113,8 @@
**Residual risk:** if the attacker also has the passphrase or the keyring (see T13), they're in. Out of scope.
**Exception (v0.5.1, user request 2026-10-22 — "AI 做会中断"):** the gate does NOT run for **metadata-only** operations — `xop list` and `xop desc`. They read and write only key *names* and *descriptions*; a secret *value* is never produced by them, so there is nothing for the gate to protect. `Vault::open_metadata` unlocks via the keyring (0600, same-UID) with no biometric and no passphrase; without a keyring it still falls back to typing the xop passphrase. The policy is pinned by `auth::needs_gate(Intent)`: `Metadata → no gate`, `Value → gate`. **Every operation that touches a value (`get` / `set` / `rm` / `run`) keeps the full gate.** Accepted residual risk: someone at an unlocked console can read your key *names* and descriptions without a biometric prompt — names are metadata, not credentials, and the same person can already read them in any headless automation context. This does not widen T13 (keyring theft): reading the keyring still yields every value.
## T12 — Race Condition: Ref Resolved After Spawn
**Attack:** xop resolves ref, then spawns child. Between resolution and execve, a debugger attaches to xop, reads its memory.
@@ -121,18 +123,18 @@
## T13 — Keyring File Stolen (v0.2.1)
**Attack:** malware running as the same UID (or a stolen/loose backup of `~/.xop`) reads `~/.xop/keyring` — the hex argon2-derived key — and decrypts `~/.xop/key.db` without ever knowing the passphrase.
**Attack:** malware running as the same UID (or a stolen/loose backup of `~/.x/xop`) reads `~/.x/xop/keyring` — the hex argon2-derived key — and decrypts `~/.x/xop/key.db` without ever knowing the passphrase.
**Mitigation:**
- This is an **explicitly accepted tradeoff** (user decision 2026-10-02): the alternative — macOS Keychain storage — popped system authorization dialogs during automation and was rejected outright.
- File mode 0600, dir `~/.xop` 0700, atomic write via tmp+rename.
- File mode 0600, dir `~/.x/xop` 0700, atomic write via tmp+rename.
- `keyring::load_at` **refuses** any file whose mode has group/other bits set (error, not silent use) and any non-64-hex content.
- Instant revocation: `xop key --remove` (or `xop reset --yes`, which cascades).
- Per-invocation opt-out: `XOP_NO_KEYRING=1` forces passphrase typing.
- Same-UID is the boundary: a same-UID process can also read the live terminal / keylog the typed passphrase, so the keyring does not meaningfully widen the local-threat surface — it moves one factor from "memory" to "disk".
- Not a remote risk: nothing exfiltrates `~/.xop` by design; backups of the dir should be treated as secret material (or exclude `keyring`).
- Not a remote risk: nothing exfiltrates `~/.x/xop` by design; backups of the dir should be treated as secret material (or exclude `keyring`).
**Residual risk:** backups / dotfile-sync tools (Dropbox, iCloud `~` sync) copying `~/.xop/keyring` off-machine. Mitigation: sync tools honouring dir perms are outside xop's control — document "back up key.db only, never keyring", or keep the dir out of sync paths.
**Residual risk:** backups / dotfile-sync tools (Dropbox, iCloud `~` sync) copying `~/.x/xop/keyring` off-machine. Mitigation: sync tools honouring dir perms are outside xop's control — document "back up key.db only, never keyring", or keep the dir out of sync paths.
## Summary table
@@ -148,6 +150,6 @@
| T8 | core dump | ✅ RLIMIT_CORE=0 in child |
| T9 | audit log leaks | ✅ type system + scan test |
| T10 | vault file stolen | ✅ AES-256-GCM + argon2id |
| T11 | Touch ID bypass | ✅ keyring only after proven identity (biometric pass or headless); SSH/no-biometric → passphrase typed; cancel = exit 77 |
| T11 | Touch ID bypass | ✅ keyring only after proven identity (biometric pass or headless); SSH/no-biometric → passphrase typed; cancel = exit 77. **v0.5.1 exception:** metadata-only ops (`list`/`desc`) skip the gate — they never release a value |
| T12 | debug attach | out of scope |
| T13 | keyring file stolen | ✅ accepted tradeoff — 0600 enforced, revoke via `xop key --remove` |