Files
xop/HANDOFF.md
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

337 lines
34 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 · Session Handoff
> Pick up here in a new session at `/Users/xs/Documents/x/xop`.
> This doc tells you exactly where the project is, what's done, what's not, and what to do next.
---
## TL;DR for the next session
```bash
cd /Users/xs/Documents/x/xop
# 必须先编译
cargo check --all-targets
# 单元测试(68 个,全跑;无 env 前置)
cargo test --lib
# 集成测试(24 个,需要 XOP_AUTH_BYPASS=1 + XOP_VAULT_PASSWORD=testpass)
# 注意:XOP_VAULT_PASSWORD 旁路只在 `--features test-bypass` 构建中有效;
# release binary 永远不读这个 env。cargo test --test integration 不带 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 DB_PASS=db_pass --allow-net=db.local:5432 --deny-net=* -- echo hi
./target/release/xop run --secret SSHPASS=s11_pass --allow-net=192.168.1.19:22 --deny-net='*' -- \
sshpass -e ssh -o StrictHostKeyChecking=accept-new [email protected] 'ls /Users'
# v0.4 直连 ssh(推荐):askpass 让 ssh 走 SSH_ASKPASS,密码既不在 argv 也不在 env
./target/release/xop run --askpass=ssh_pass -- ssh %XOP_user_key%@192.168.1.19
```
**v0.4 status (2026-10-07, end-to-end verified against 192.168.1.19): working CLI + local vault + real Touch ID gate + `xop run` + `%XOP_KEY%` argv placeholders + file-keyring passphrase-free unlock + real stdout/stderr leak masking + `xop key [--save|--remove]` + **`--askpass=NAME` SSH_ASKPASS injection (v0.4: `mkdtemp(0700)` + 0600 data + 0700 helper script `cat "$XOP_ASKPASS_DATA"`, `Drop` auto `srm -m`, single-secret per invocation, `askpass: bool` on SecretRef, SSH_* auto-detect removed to keep strategy explicit).** No external backend dependencies. The single most impactful next step: **NetworkGuard / FileGuard OS-level enforcement (pf/iptables/sandbox-exec/landlock) + multi-secret askpass** (P1 below).
---
## 1. What's done
### v0.2.1 additions (2026-10-02 — user live-test drove 4 fixes)
| Layer | Status | File |
|---|---|---|
| `set` value no longer echoes plaintext (partial mask `ab****`) | ✅ complete | `src/commands/set.rs` (rpassword `password_feedback_partial_mask`) |
| **File keyring unlock** — `~/.x/xop/keyring` 0600 hex key; OS gate runs first and its `Gate` verdict decides eligibility (biometric pass or headless → silent keyring; SSH/no-biometric → typed passphrase, keyring unused); agent-friendly `xop run` with zero passphrase | ✅ complete + unit + integration tested | `src/vault/keyring.rs` + `src/vault/mod.rs::open` |
| `xop key [--save|--remove]` subcommand (status / enable on old vaults / revoke) | ✅ complete | `src/commands/key.rs` |
| **Real stdout leak masking** (old `guard_for_reader` was a passthrough stub — that's why raw `123456` reached the user's terminal). Line-buffered filter, mask `12****【xop禁止将密钥泄漏】`, kill/refuse → SIGKILL, audit leak_event | ✅ complete + 8 unit + 2 e2e tests | `src/guard/stdout.rs` |
| `xop reset --yes` cascades keyring deletion | ✅ complete | `src/commands/reset.rs` |
| **OS gate rewritten to REAL fingerprint**: LAContext `.deviceOwnerAuthenticationWithBiometrics` via JXA (biometrics-only — dialog has no password field). LAError classification: cancel/refuse (-128/-5/-12/unknown) → `AuthCancelled` exit 77 (old code degraded to OK and `xop set` stored the secret after "用户已取消") | ✅ complete + 8 unit tests | `src/auth/touchid.rs` |
| **`auth::Gate` decision table (live-test #2 fix)**: authenticate now returns `AllowKeyring` / `RequirePassphrase`. Headless(non-TTY, incl. `ssh host cmd`) → AllowKeyring; **SSH pty session → never attempts biometrics** (dialog would pop on the local console), requires typed xop passphrase, keyring NOT consulted; local no-biometrics / broken osascript / Linux interactive → same RequirePassphrase. Rationale: silent keyring unlock needs an identity proof behind it. Linux `pam.rs` deleted (pkexec system password was the old bug) | ✅ complete + 5 unit decide tests + 1 integration | `src/auth/mod.rs::decide` + `src/vault/mod.rs::open` |
| **macOS Keychain approach: implemented, then REJECTED & deleted** — `security(1)` popped system authorization dialogs during background automation (2026-10-02 user veto: 不要放在钥匙串). xop must NEVER call `security(1)` against the user's keychain | ❌ removed | (git history only) |
### v0.4 (2026-10-07 — SSH_ASKPASS injection)
| Layer | Status | File |
|---|---|---|
| `--askpass=NAME` flag (Args + Run subcommand) | ✅ complete | `src/args.rs` |
| `SecretRef::askpass()` ctor + `askpass: bool` flag (mirrored on `ResolvedValue`) | ✅ complete | `src/secret.rs` |
| `src/askpass.rs` — `mkdtemp(0700)` + 0600 data + 0700 `getpass.sh` (`cat "$XOP_ASKPASS_DATA"`); `Drop` runs `srm -m` (falls back to `rm -rf`); `env_vars()` emits `SSH_ASKPASS` + `SSH_ASKPASS_REQUIRE=force` + `DISPLAY=:0` + `XOP_ASKPASS_DATA` | ✅ complete + 4 unit tests | `src/askpass.rs` |
| `run_exec` Phase 3.5: split askpass refs out of `envp_resolved`, setup infrastructure BEFORE audit (no orphan spawn_event on setup failure); stdout guard still sees full resolved set so any leaked value is masked | ✅ complete + 6 integration tests | `src/lib.rs::run_exec` |
| Simplify `injector::plan()` — SSH_* auto-detect removed (askpass is now opt-in via `--askpass=NAME`); `InjectStrategy::Askpass`/`Fd` variants removed; tests rewritten to assert envp-default | ✅ complete | `src/injector.rs` |
| `Error::Io(String, String)` variant (exit 73) for askpass setup / chmod / write failures | ✅ complete | `src/error.rs` |
### v0.5 (2026-10-22 — list glob filtering + description metadata + data-dir move)
| Layer | Status | File |
|---|---|---|
| `xop list [GLOB...]` — repeatable patterns, union semantics; `*` = any run, `?` = exactly one char, case-sensitive; no `[]`/`{}`/`**`. `--names-only` prints names only. **v0.5.2 refined this**: the default search became a quote-free substring match (see v0.5.2 below) | ✅ complete + 4 unit + 4 integration | `src/args.rs` + `src/commands/list.rs` |
| Built-in glob matcher — classic two-pointer with star backtracking; **zero new dependencies** (xop's "no external deps" position) | ✅ complete + 11 unit tests | `src/glob.rs` |
| `xop desc KEY "TEXT"` — the ONLY desc form (no list-all / show-one / `--clear`); empty string `""` clears the description; unknown key → `KeyNotFound` (exit 77). **v0.5.1 refined this**: the text became variadic (`KEY [TEXT...]`) and "no text" now clears the description | ✅ complete + 3 integration | `src/commands/desc.rs` |
| Description metadata stored **inside the encrypted vault**: `Meta { desc }` map, serialized as a `__meta__` TOML sub-table. Vaults with no descriptions keep the legacy flat layout (`KEY = "value"`) so older xop binaries can still read them | ✅ complete + 8 unit tests | `src/vault/mod.rs` (`META_TABLE`, `decode_plaintext`, `encode_plaintext`, `set_description`, `list_with_desc`) |
| `audit.rs` gains `vault_desc(name)` — records the key NAME only; the description text is deliberately NOT logged (I2) | ✅ complete | `src/audit.rs` |
| **Data dir move** `~/.xop/` → `~/.x/xop/` (key.db / keyring / audit.jsonl). Migration is **copy, never move** — the legacy dir is left intact as a backup; a pre-existing new vault wins and the migration is skipped. Dir 0700, copied files 0600. Path-parameterized core so unit tests never touch global `$HOME` | ✅ complete + 5 unit + 1 integration | `src/datadir.rs` |
| `xop list` renders the description column (padded to the longest name); prints `(N total)` / `(N of M total)` / `(no keys match)` | ✅ complete | `src/commands/list.rs` |
### v0.5.1 (2026-10-22 — user feedback: no quotes; list must never interrupt an agent)
| Layer | Status | File |
|---|---|---|
| `xop desc KEY [TEXT...]` — the text is a variadic positional (`trailing_var_arg` + `allow_hyphen_values`); the words are joined with single spaces, so **no quote character has to be typed**. One layer of literal surrounding quotes is stripped if the user typed them; **omitting the text clears the description** (no empty `""` needed). Prints `description cleared: KEY (was: …)` so a misfire is visible | ✅ complete + 6 unit + 3 integration | `src/args.rs` + `src/commands/desc.rs::join_description` |
| **Gate-free metadata path** — `Vault::open_metadata` / `open_metadata_at` skip the OS identity gate: the keyring (0600, same-UID) unlocks silently, and only a *missing* keyring falls back to typing the passphrase. `xop list` + `xop desc` use it; **`get` / `set` / `rm` / `run` keep the full gate** | ✅ complete + 2 unit + 1 pty integration | `src/vault/mod.rs` + `src/commands/{list,desc}.rs` |
| `auth::Intent` (`Value` / `Metadata`) + `auth::needs_gate(intent)` — the "which operations need the gate" policy as a pure, testable function | ✅ complete + 1 unit | `src/auth/mod.rs` |
| `Vault::open` and `open_metadata` now share the `decrypt_with` core (no duplicated decrypt/parse code) | ✅ complete | `src/vault/mod.rs` |
| `keyring::load_at` / `keyring::save_at` made public — path-explicit, so the metadata unlock is unit-testable without touching the process-global `$HOME` | ✅ complete | `src/vault/keyring.rs` |
| pty regression test: `list_under_a_tty_never_prompts_for_biometrics` runs the binary under `script -q /dev/null` (a real pty, so `is_terminal()` is true inside xop) with a 30 s timeout — if the gate ever came back, the child would block on the Touch ID dialog and the test would fail instead of hanging | ✅ complete | `tests/integration.rs` |
### v0.5.2 (2026-10-22 — user feedback: the list search must not need quotes either)
| Layer | Status | File |
|---|---|---|
| `xop list [TERM...]` — a plain term is a **case-insensitive substring match** against the key name **or** the description: `xop list git_local` works with **no quotes and no wildcard**. The quoting was never about xop — `*` is a shell metacharacter, so `xop list git_local*` either explodes into filenames (bash) or dies with `no matches found` (zsh) | ✅ complete + 6 unit + 4 integration | `src/commands/list.rs::matches_term` |
| A term that carries `*`, `?` or `[` switches that term to **glob** semantics — whole-name match, or "fits somewhere inside" the description. The old `xop list 'git_*'` form keeps working unchanged | ✅ complete | `src/commands/list.rs` |
| Several terms are unioned (`xop list git s19`); `--names-only` unchanged; the positional arg was renamed `patterns` → `terms` (CLI syntax unchanged) | ✅ complete | `src/args.rs` + `src/lib.rs` |
| `src/glob.rs` gains the search helpers `has_meta`, `matches_ignore_case`, `contains_ignore_case`, `contains_glob_ignore_case`. The low-level `matches` stays a case-sensitive pure glob engine | ✅ complete + 4 unit tests | `src/glob.rs` |
### v0.2 (2026-10-01)
| Layer | Status | File |
|---|---|---|
| Cargo.toml + deps (no backend crates) | ✅ complete | `Cargo.toml` |
| CLI arg surface (clap derive, Subcommand enum) | ✅ complete | `src/args.rs` |
| `SecretRef` parsing (bare `KEY=NAME` + `argv_placeholder` flag) | ✅ complete + unit tested | `src/secret.rs` |
| Typed `XopError` + exit code mapping (BSD sysexits) | ✅ complete | `src/error.rs` |
| `Policy` (NetPolicy / ReadPolicy / LeakAction) | ✅ complete + unit tested | `src/policy.rs` |
| Default deny-read list (pre-seeded) | ✅ complete | `src/policy.rs::DEFAULT_DENY_READ` |
| **Local encrypted vault** (AES-256-GCM, argon2id, atomic write) | ✅ complete + unit tested | `src/vault/{mod,format}.rs` |
| **OS auth gate** (v0.2 shipped osascript-admin + pkexec; **rewritten in v0.2.1** to LAContext biometrics-only via JXA + `Gate` eligibility for keyring; SSH & Linux-interactive & no-biometric → typed passphrase — see table above) | ✅ complete | `src/auth/{mod,touchid}.rs` |
| **6 subcommands** (init/set/list/get/rm/reset) | ✅ complete + integration tested | `src/commands/{init,set,list,get,rm,reset}.rs` |
| **`xop run` subcommand** (envp inject + `%XOP_KEY%` argv substitution; single vault open) | ✅ complete + live SSH-verified | `src/lib.rs::run_join_and_exec` + `src/injector.rs::scrub_argv` |
| **TTY-aware passphrase prompt** (`/dev/tty` for real terminal, stdin fallback for agent/pipe/expect) | ✅ complete | `src/vault/mod.rs::rpassword_prompt` |
| **`test-bypass` Cargo feature** (gates `XOP_VAULT_PASSWORD` env to test builds only) | ✅ complete | `Cargo.toml::[features]` + `src/vault/mod.rs` cfg-gate |
| Audit log (ref-only, JSONL, invariant test scans 4 keywords) | ✅ complete | `src/audit.rs` |
| `secrecy::SecretBox<String>` wrapper for values | ✅ complete | `src/secret.rs::ResolvedValue` |
| StdoutGuard (filter + pipe loop, async tokio) | ✅ complete + unit tested | `src/guard/stdout.rs` |
| NetworkGuard / FileGuard (interface) | ✅ interface complete, OS impl stubbed | `src/guard/{network,file}.rs` |
| Injector plan + `build_envp_delta` (real impl, skips `argv_placeholder` refs) | ✅ complete | `src/injector.rs` |
| Child env hardening (HISTFILE=/dev/null etc.) | ✅ complete | `src/injector.rs::harden_child_envp` |
| **Spawn pipeline** (tokio + pre_exec + RLIMIT_CORE=0) | ✅ complete | `src/lib.rs::spawn_child` |
| Dry-run mode | ✅ complete | `src/lib.rs::run_dry` |
| Design / threat-model / comparison / architecture docs | ✅ complete | `docs/*.md` |
| Examples (init, list, get, ssh, mysql, dry-run) | ✅ complete | `examples/*.sh` |
| Integration tests (assert_cmd) | ✅ 11 tests, all green (with `--features test-bypass`) | `tests/integration.rs` |
| `Makefile` (build / install / uninstall / test / clippy) | ✅ complete | `Makefile` |
| secret-agent cloned as reference | ✅ complete | `refs/secret-agent/` |
## 2. What's NOT done
### 🟡 P1 — Important but not blocking v0.2
| Item | Where | Effort | Notes |
|---|---|---|---|
| **`NetworkGuard` OS impl** (pf / iptables) | `src/guard/network.rs::setup` | 2-3 hours | macOS: `Command::new("pfctl")` + stdin pipe, anchor = `xop/<pid>`. Linux: `iptables -m owner --pid-owner <pid>` in OUTPUT chain. |
| **`FileGuard` OS impl** (sandbox-exec / landlock) | `src/guard/file.rs::setup` | 2-3 hours | macOS: `build_sandbox_profile` exists; need to invoke `sandbox-exec -p <profile>`. Linux: `prctl(PR_SET_NO_NEW_PRIVS)` + landlock ruleset before execve. |
| ~~**`Askpass` injection strategy**~~ | ✅ done v0.4 → `src/askpass.rs` | — | — |
| **Multi-secret askpass** (v0.4 single-secret; one script that dispatches by SSH prompt content) | `src/askpass.rs` | 1-2 hours | Needed for `ssh passphrase + sudo` flows; the dispatcher picks which `XOP_DATA` to cat based on `$1` (ssh passes prompt text as first arg). |
| **`Fd` injection strategy** | `src/injector.rs` | 30 min | Lower priority — for tools that read password from fd 3. |
| **Argv scrubber** | `src/injector.rs::scrub_argv` | 1 hour | Detect `--password=<value>`, `-p<password>`, `PASSWORD=...` patterns in user's argv. |
| **Signal forwarding (SIGINT/SIGTERM)** | `src/lib.rs::spawn_child` | 30 min | `Command::kill_on_drop(true)` already; need separate signal handler task to forward SIGINT/SIGTERM. |
| **Entropy-based stdout detection** | `src/guard/stdout.rs` | 4-6 hours | High-entropy string match (gitleaks-style) for unknown leaks that evade name-based regex. |
### 🟢 P2 — Nice to have
| Item | Where | Notes |
|---|---|---|
| **Library mode** | `src/lib.rs` | `pub use xop::exec` for embedding in xstudio later. |
| **Passphrase strength meter** (zxcvbn) | `src/commands/init.rs` | Warn or refuse weak passphrases during `init`. |
| **Ref-to-hash translation in history** | `src/lib.rs` | So shell history doesn't reveal which vault items are in use. |
| ~~**macOS Keychain as passphrase-source**~~ | — | **REJECTED 2026-10-02** (user veto after live test: `security(1)` popped system authorization dialogs mid-automation). Replaced by file keyring `~/.x/xop/keyring`. Do NOT re-litigate. |
---
## 3. Key design decisions (v0.2 pivot)
| Decision | Why | Source |
|---|---|---|
| **Local vault, no external backends** | Avoid per-resolve subprocess (`op read`, `vault kv get`) which leaks vault metadata into `ps`. Single binary, works on fresh machine. | this doc, `docs/design.md` §2 P5 |
| **OS auth gate (real Touch ID, biometrics-only) + passphrase = 2FA; keyring silent-unlock only where identity is proven** | Biometric alone never decrypts; passphrase alone never reaches the vault. Dialog shows NO password option; cancel = exit 77 refusal; **never** the system login password (user hard rule 2026-10-02). SSH sessions & no-biometric devices must type the xop passphrase — keyring unused there; headless automation may use keyring silently. | `docs/design.md` §7, `docs/threat-model.md` T11, `src/auth/{mod,touchid}.rs` |
| **Whole-file single blob (TOML in AES-GCM)** | Simple. Atomic write. Re-randomized nonce per save. | `docs/architecture.md` |
| **`op://`/`vault://`/`keychain://` schemes removed** | v0.1 leaked which backend was in use (metadata). v0.2 = bare key names only. | `src/secret.rs` |
| **Master key in vault file** (decision 9A) | Simpler than separate keystore. Argon2(passphrase) provides the key; OS auth is just a pre-gate. | `docs/design.md` §7 |
| **Deno-style permission DSL** | `--allow-net=`, `--deny-net=`. Battle-tested in Deno runtime. | `docs/design.md` §3 |
| **Audit log: NO `value`/`plaintext`/`ciphertext`/`passphrase` field** | Type-system + scan test enforce it. Invariant I2. | `src/audit.rs` |
| **`SecretBox<String>` for all values** | `Debug` impl prints `<secret>`. Prevents accidental `println!("{:?}", v)` leaks. | `src/secret.rs` |
| **`pre_exec` for `RLIMIT_CORE=0`** | Only way to set rlimit on a `tokio::process::Command` child (runs after fork, before execve). | `src/lib.rs::spawn_child`, `docs/architecture.md` |
| **`XOP_AUTH_BYPASS=1` for tests only** | Skip OS auth in CI/headless. Passphrase still required (invariant I8). | `src/auth/mod.rs` |
| **Atomic vault writes (`tmp + rename`)** | Survive partial writes / power loss. | `src/vault/format.rs::write` |
| **`XOP_VAULT_PASSWORD` is feature-gated** | Reading this env from a release binary is a backdoor — any process with the env var decrypts the whole vault. Compiled out of release via `#[cfg(feature = "test-bypass")]`. Verified by `strings target/release/xop \| grep XOP_VAULT_PASSWORD` → empty. | `Cargo.toml::[features]` + `src/vault/mod.rs` |
| **`xop run` opens vault exactly once** | `--secret` env-inject refs and `%XOP_KEY%` argv placeholders are both `SecretRef`s (differentiated by `argv_placeholder` flag), collected by `collect_refs` and passed to a single `resolve_all` call. User types passphrase once. | `src/lib.rs::run_join_and_exec` + `src/secret.rs::SecretRef::argv_placeholder` |
| **TTY-aware passphrase prompt** | `is_terminal(stdin)` decides: real terminal → `/dev/tty` (so `xop set` still reads the secret value from stdin); non-TTY (agent/pipe/expect) → stdin fallback. No env-var backdoor needed. | `src/vault/mod.rs::rpassword_prompt` |
---
## 4. How to test
```bash
cd /Users/xs/Documents/x/xop
# 1. Unit tests (fast, run often, no env needed)
cargo test --lib
# Expected: 68 tests pass (args, secret, policy, audit, vault::format, vault::mod, vault::keyring, auth(touchid LAError 分类 ×8 + decide 决策表 ×5), stdout-guard, error, injector, askpass).
# 2. Integration tests (need built binary + bypass env + test-bypass feature)
# XOP_VAULT_PASSWORD 旁路只在 --features test-bypass 构建中有效
XOP_AUTH_BYPASS=1 XOP_VAULT_PASSWORD=testpass \
cargo test --features test-bypass --test integration -- --test-threads=1
# Expected: 24 tests pass (help, banner, dry-run, bad-ref, secrets-file, env, init-vault, get-unknown, list-empty, run_masks_secret_in_child_stdout, run_masks_argv_placeholder_value, run_rejects_v0_xop_key_placeholder, keyring_enables_passphrase_free_unlock, ssh_env_headless_still_unlocks_via_keyring, get_masks_value_by_default, get_dash_v_prints_plaintext, run_askpass_* ×6).
# 3. Combined
cargo test --lib && \
XOP_AUTH_BYPASS=1 XOP_VAULT_PASSWORD=testpass \
cargo test --features test-bypass --test integration -- --test-threads=1
# 4. Live smoke — 必须真人跑,两种终端各测一遍
cargo build --release
# (a) 本机 Terminal.app:
./target/release/xop init # 不弹指纹(bootstrap);passphrase ×2 后自动写 keyring
./target/release/xop set DB_PASS # 弹真指纹 → 通过 → 交互输入 secret value(不再问口令)
./target/release/xop list # 弹指纹 → keyring 静默解锁
# (b) SSH 会话(ssh <本机用户>@<host>):
./target/release/xop list # 绝不弹指纹 → 提示输入 Vault passphrase(管理员密码)→ 成功
./target/release/xop set aa # 同上:先输口令再输入值;点取消口令 = 失败
./target/release/xop --dry-run --secret DB_PASS=db_pass --allow-net=db.local:5432 --deny-net=* -- echo hi
./target/release/xop run --secret SSHPASS=ssh_pass \
--allow-net=192.168.1.0/24 --deny-net='*' -- \
sshpass -e ssh user@host 'ls /Users'
# v0.4:直连 ssh 不依赖 sshpass,密码走 SSH_ASKPASS(既不进 argv 也不进 env)
./target/release/xop run --askpass=ssh_pass -- ssh '%XOP_user_key%@192.168.1.19' 'ls /Users'
# 5. 验证 release binary 没有 XOP_VAULT_PASSWORD 旁路(应空)
strings target/release/xop | grep XOP_VAULT_PASSWORD
```
---
## 5. Common pitfalls for the next session
1. **bash expands `$VAR`** — `xop ssh user:$SSH_PASSWORD@host` gets expanded by bash before xop sees it. **Always use `--secret KEY=NAME` flag**.
2. **`rpassword::prompt_password` requires a real TTY** — can't be called from CI or piped stdin. Current `rpassword_prompt` is TTY-aware: stdin is TTY → `/dev/tty` (hidden), stdin is NOT TTY → stdin fallback (no env-var backdoor). Integration tests run `cargo test --features test-bypass` to enable the `XOP_VAULT_PASSWORD` env bypass.
3. **macOS Touch ID = `osascript -l JavaScript` (JXA) 调 LAContext,不是 admin 弹窗** — 旧写法 `do shell script "..." with administrator privileges` 是**系统登录密码框**(红线禁止),且 osascript 命中 admin 授权缓存造成"看起来免密"的假象。正确姿势:`ctx.evaluatePolicyLocalizedReasonReply(1, reason, fn)`(policy 1 = biometrics-only,弹窗无密码选项)+ 主线程 `NSRunLoop.runUntilDate` 自旋等 block 回调;JXA 会把私有队列的回调 marshal 回 JS 线程(实测 NSOperationQueue 探针 107ms)。LAContext 无缓存,每次真弹指纹。
4. **Linux 交互 = 直接输 xop passphrase(`pam.rs` 已删)** — 旧实现 `pkexec -- true` 弹的是 polkit **系统登录密码框**,违反"任何时候不要让用户输入系统密码"红线。Linux 没有可移植的"纯指纹"CLI 闸门(pam_fprint 罕见且发行版绑定),身份无法被生物特征证明 → `decide(tty=true, ssh=false, bio=None)` = `RequirePassphrase`,keyring 也不参与(否则等于零验证)。headless 自动化仍走 keyring 静默。
5. **`pre_exec` for `RLIMIT_CORE=0`** — `tokio::process::Command` doesn't expose `setrlimit`. Must use `cmd.pre_exec(|| setrlimit(...))` closure (runs after fork, before execve). Pattern in `src/lib.rs::spawn_child`.
6. **`Secret<String>` in secrecy 0.10 = `SecretBox<String>`** — don't follow 0.8 docs.
7. **stdout mask uses `Vec<u8>` not `String`** — child stdout may be UTF-8 invalid (binary data); bytes avoid `from_utf8` panic.
8. **audit log flush before child exits** — `AuditLog::write_event` calls `.flush()`. If child crashes mid-exec, audit isn't lost.
10. **`osascript -l JavaScript` 调用姿势** — 用 `Command::new("/usr/bin/osascript").arg("-l").arg("JavaScript").arg("-e").arg(JXA_SCRIPT).arg(reason)`:reason 走 **argv** 而非字符串拼接,完全没有 shell 引号转义问题。JXA 里 enum 名(`LAPolicyDeviceOwnerAuthenticationWithBiometrics`)不一定桥接成功,**用数字 1** 稳定。详见 `src/auth/touchid.rs::JXA_SCRIPT`。
11. **Argon2 parameters** — `m=64 MiB, t=3, p=4` is standard. Don't tune down (defeats offline brute force). Each `xop` invocation pays ~250ms per unlock.
12. **Vault file is per-user** — `~/.x/xop/key.db` resolves via `$HOME`. CI tests must set `HOME` to a temp dir before running, which is why `--test-threads=1` matters.
13. **`XOP_VAULT_PASSWORD` 是 release 后门,必须 feature-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` 文件存在性检测会误判(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` 区分两种注入** — `--secret KEY=NAME` (envp) vs `%XOP_KEY%` (argv)。两者走同一个 vault resolve,但 `build_envp_delta` 跳过 placeholder,`scrub_argv` 处理 placeholder。`ResolvedValue` 镜像标志位。
17. **绝不调 macOS Keychain / `security(1)`** — 实测:agent 后台会话里 `security add/find/delete-generic-password` 会弹系统授权对话框("xop wants to modify/delete keys"),用户体验等同攻击,整个 keychain 方案 2026-10-02 被否决删除。免密解锁 = `~/.x/xop/keyring` 0600 文件(存 argon2 派生密钥 hex,非 passphrase 本身;mode 不合规直接拒用)。OS 预闸门顺序写死在 keyring 读取之前,且闸门结论决定 keyring 资格——本地指纹通过或 headless 才免输;SSH/无指纹交互必须输口令,keyring 根本不读。
18. **lib 单元测试禁止 set_var 全局 env** — `cargo test --lib` 默认并行;keyring 测试曾用 `set_var("HOME", tmpdir)` + `set_var("XOP_NO_KEYRING")`,4 个测试随机红(别的测试同时读到被改的 HOME)。解法:文件逻辑抽成路径显式的 `save_at/load_at/remove_at(&Path)` 纯函数,wrapper 才解析 `path()`+env 门控;测试只打 tempdir 路径。决策逻辑同理抽成 `auth::decide(tty, ssh, bio)` 纯函数,测 SSH/headless 分支不碰 env。(集成测试单进程串行 + 子进程 env 隔离,set_var HOME 仍安全,保持 `--test-threads=1`。)
19. **SSH 会话 `isatty(0)` 也是 true——TTY ≠ 本地控制台** — sshd 分配的 pty 让 `isatty(0)`/`is_terminal()` 返回 true,旧闸门据此在 SSH 会话里调 LAContext:Touch ID 弹窗只会出现在**本机物理控制台**,远程用户看不到也点不了,等于卡死/错弹(2026-10-02 实测抱怨"ssh 状态也让输入指纹")。检测用 `SSH_TTY/SSH_CONNECTION/SSH_CLIENT` env(sshd 注入,本地 Terminal.app 没有)。语义:SSH 交互会话 → `Gate::RequirePassphrase`(输 xop 管理员密码,keyring 不参与——没有指纹现证就没有任何身份验证垫底);`ssh host cmd` 无 pty 的自动化 → 仍 headless → keyring 静默(`xop run` 无人值守不受影响)。判断顺序 `!tty → ssh → bio`,headless 检查必须在 ssh 之前。
20. **数据目录搬家是「复制不移动」** — `~/.xop/` → `~/.x/xop/`(v0.5)。用户真实 vault 有 18+ key,迁移只复制 key.db / keyring / audit.jsonl,旧目录原样留着当备份;新目录已有 vault 时迁移自动跳过。`migrate_legacy_from(new_home, old_home)` 路径显式化,单测不碰全局 `$HOME`(坑 18 同款纪律)。
21. **vault 明文加 `__meta__` 子表不破坏旧格式** — toml 0.8 序列化时**普通值先于表输出**(已用临时测试验证),所以 `KEY = "value"` + `[__meta__]` 不会触发 ValueAfterTable。`encode_plaintext` 在 meta 为空时**完全省略 `__meta__` 表**,没描述的 vault 保持旧扁平布局,老版本 xop 二进制照样能读。
22. **glob 匹配器自研不引 globset** — 需求只有 `*` / `?`;引依赖会带进正则语义(`[]`/`{}`)并破坏 xop「零外部依赖」的定位。`src/glob.rs` 双指针 + star 回溯,11 条单测。`matches("*_user", "user")` = false——`*` 不能凭空造出字面 `_`。
23. **元数据免闸门 ≠ 值免闸门** — 2026-10-22 用户反馈「`xop list` 应该是免密免 touch 的吧,不然 AI 做会中断」。闸门的作用是"释放真值前确认有人在场",`list`/`desc` 只给 key 名和描述、永不吐 value,所以跳过闸门不泄漏任何 secret。**别把 `Vault::open` 的闸门拆掉**(那会让 `get`/`run` 也免掉)——正确做法是**新增 `open_metadata` 路径** + `auth::needs_gate(Intent)` 纯函数把策略钉死。
24. **pty 回归测试用 `script -q /dev/null`,且必须带超时** — macOS 的 `script` 给子进程起真 pty(`test -t 0` 为真),正好复现"终端里跑 xop"的场景。闸门若回来,子进程会卡在 Touch ID 弹窗 → 测试挂死而不是失败。用 `std::sync::mpsc::recv_timeout` + 后台线程收 `wait_with_output` 兜住。
25. **描述文字不要求引号** — 用户明确说「打引号很难输入」。`xop desc` 文字参数是 `Vec<String>` + `trailing_var_arg`,多词 join;用户真打进 vault 的一层引号在 `join_description` 里剥掉(只认 ASCII 单字节引号,切点必是 char 边界)。
26. **搜索要打引号的锅在 shell,不在 xop** — `xop list 'git_local*'` 必须加引号,因为 `*` 是 shell 通配符:zsh 下 `xop list git_local*` 没匹配文件直接 `no matches found`,bash 下被展开成一堆文件名。**引号是躲 shell 的**。所以 v0.5.2 的正解不是"想办法少打引号",而是**让日常搜索根本不需要通配符**——默认搜索改成纯子串匹配(`xop list git_local`,命中 key 名或描述,大小写不敏感),`*`/`?`/`[` 只在用户显式写了时才切回 glob 语义。想递一个"不被 shell 展开"的参数只能靠引号或反斜杠,xop 这边无能为力。
---
## 6. Where to look first (file map)
| Question | File |
|---|---|
| How is the CLI parsed? | `src/args.rs` |
| What does a ref look like (incl. `argv_placeholder` flag)? | `src/secret.rs` |
| What does the policy look like? | `src/policy.rs` |
| How is the vault encrypted? | `src/vault/mod.rs` + `src/vault/format.rs` |
| How does the fingerprint gate work (LAContext via JXA; `Outcome`/`classify`)? 闸门结论怎么决定 keyring 能否静默(`Gate`/`Bio`/`decide(tty,ssh,bio)` 纯决策表:headless→静默 · SSH/无指纹→强制输 passphrase · 取消→exit 77)? | `src/auth/mod.rs` + `src/auth/touchid.rs` |
| What's in each subcommand (incl. `reset`, `key`, `desc`)? | `src/commands/{init,set,list,get,rm,reset,key,desc}.rs` |
| How does the glob matcher work (`*` / `?`, backtracking)? | `src/glob.rs`(`matches` / `matches_any`) |
| Where do key descriptions live, and how are they encoded? | `src/vault/mod.rs`(`META_TABLE = "__meta__"`、`Meta`、`decode_plaintext` / `encode_plaintext`) |
| Where does the data dir live, and how did `~/.xop/` → `~/.x/xop/` migration work? | `src/datadir.rs`(`home` / `legacy_home` / `migrate_legacy` / `migrate_legacy_from`) |
| Which operations skip the OS identity gate, and why? | `src/auth/mod.rs`(`Intent` / `needs_gate`)+ `src/vault/mod.rs::open_metadata` |
| How does passphrase-free unlock work (file keyring, NOT Keychain)? | `src/vault/keyring.rs` + `src/vault/mod.rs::open`(顺序:OS gate → Gate::AllowKeyring 才读 keyring;RequirePassphrase 直接手输,keyring 不参与) |
| How does `xop run` coordinate env-inject + `%XOP_%` placeholders in one vault open? | `src/lib.rs::run_join_and_exec` + `expand_xop_placeholders` |
| How does argv placeholder substitution work? | `src/injector.rs::scrub_argv` |
| What guards run around the child? | `src/guard/mod.rs` + `src/guard/{stdout,network,file}.rs` |
| Where's the audit invariant enforced? | `src/audit.rs` (test scans 4 keywords) |
| How is the child spawned? | `src/lib.rs::spawn_child` |
| How is stdout filtered? | `src/guard/stdout.rs::pipe_filter_loop` |
| How does passphrase prompt choose `/dev/tty` vs stdin? | `src/vault/mod.rs::rpassword_prompt` |
| Where is `XOP_VAULT_PASSWORD` test bypass gated? | `Cargo.toml::[features]` + `src/vault/mod.rs` `#[cfg(feature = "test-bypass")]` block |
| What's the overall flow? | `docs/architecture.md` |
| What's the threat model? | `docs/threat-model.md` |
| How does this compare to existing tools? | `docs/comparison.md` |
---
## 7. Next-step path (P1 work, 1-2 sessions)
If you have 2-3 hours and want the NetworkGuard wired up:
1. **Implement `NetworkGuard::setup`** for macOS (`pfctl` + anchor) and Linux (`iptables` + owner match).
2. **Test**: launch `xop --allow-net=db.local:5432 --deny-net=* -- curl -s db.local:5432` and verify it succeeds; `xop ... -- curl -s evil.com` should fail.
3. **Implement `FileGuard::setup`** for macOS (`sandbox-exec`) and Linux (`landlock`).
5. **Askpass strategy** for SSH: write askpass script, set `SSH_ASKPASS_REQUIRE=force` + `DISPLAY=:0`, `srm -m` on exit.
That gets v0.2 to a fully-enforced posture (XIP, FS, network all live). Phase 2 adds entropy detection, signal forwarding, library mode.
---
## 8. Future: connecting to xstudio
xop is **standalone**. When (if) xstudio wants xop as its secrets layer:
- xstudio already has a `xstudio.ai.runAgentLoop` MCP tool.
- Add a new MCP tool `xstudio.secrets.exec` that calls `xop::run(args)` internally.
- Or expose xop as a CLI that xstudio's agent runtime shells out to.
- The `library mode` item in P2 is exactly for this — `pub use xop::exec` for embedding.
For now xop doesn't know xstudio exists. Keep it that way until there's a concrete integration ask.
---
## 9. Quick reference
| What | Where |
|---|---|
| Project root | `/Users/xs/Documents/x/xop` |
| Reference impl | `refs/secret-agent/` |
| Design docs | `docs/*.md` |
| CLI entry | `src/main.rs` |
| Orchestrator | `src/lib.rs::run` |
| Vault module | `src/vault/mod.rs` |
| Audit invariant test | `src/audit.rs::tests::no_value_field_in_any_event` |
| Tests require | integration: `--features test-bypass` build + `XOP_AUTH_BYPASS=1 XOP_VAULT_PASSWORD=testpass` |