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

34 KiB
Raw Permalink Blame History

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

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
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 SecretRefs (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

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.

  9. 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。

  10. 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.

  11. 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.

  12. 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 必须空。

  13. TTY-aware passphrase prompt — is_terminal(stdin) 决定走 /dev/tty 还是 stdin fallback。如果用 /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 区分两种注入 — --secret KEY=NAME (envp) vs %XOP_KEY% (argv)。两者走同一个 vault resolve,但 build_envp_delta 跳过 placeholder,scrub_argv 处理 placeholder。ResolvedValue 镜像标志位。

  16. 绝不调 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 根本不读。

  17. 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。)

  18. 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 之前。

  19. 数据目录搬家是「复制不移动」 — ~/.xop/ → ~/.x/xop/(v0.5)。用户真实 vault 有 18+ key,迁移只复制 key.db / keyring / audit.jsonl,旧目录原样留着当备份;新目录已有 vault 时迁移自动跳过。migrate_legacy_from(new_home, old_home) 路径显式化,单测不碰全局 $HOME(坑 18 同款纪律)。

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

  21. glob 匹配器自研不引 globset — 需求只有 * / ?;引依赖会带进正则语义([]/{})并破坏 xop「零外部依赖」的定位。src/glob.rs 双指针 + star 回溯,11 条单测。matches("*_user", "user") = false——* 不能凭空造出字面 _。

  22. 元数据免闸门 ≠ 值免闸门 — 2026-10-22 用户反馈「xop list 应该是免密免 touch 的吧,不然 AI 做会中断」。闸门的作用是"释放真值前确认有人在场",list/desc 只给 key 名和描述、永不吐 value,所以跳过闸门不泄漏任何 secret。别把 Vault::open 的闸门拆掉(那会让 get/run 也免掉)——正确做法是新增 open_metadata 路径 + auth::needs_gate(Intent) 纯函数把策略钉死。

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

  24. 描述文字不要求引号 — 用户明确说「打引号很难输入」。xop desc 文字参数是 Vec<String> + trailing_var_arg,多词 join;用户真打进 vault 的一层引号在 join_description 里剥掉(只认 ASCII 单字节引号,切点必是 char 边界)。

  25. 搜索要打引号的锅在 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).
  4. 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