影响: 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]>
34 KiB
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. |
| — | 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
-
bash expands
$VAR—xop ssh user:$SSH_PASSWORD@hostgets expanded by bash before xop sees it. Always use--secret KEY=NAMEflag. -
rpassword::prompt_passwordrequires a real TTY — can't be called from CI or piped stdin. Currentrpassword_promptis TTY-aware: stdin is TTY →/dev/tty(hidden), stdin is NOT TTY → stdin fallback (no env-var backdoor). Integration tests runcargo test --features test-bypassto enable theXOP_VAULT_PASSWORDenv bypass. -
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 无缓存,每次真弹指纹。 -
Linux 交互 = 直接输 xop passphrase(
pam.rs已删) — 旧实现pkexec -- true弹的是 polkit 系统登录密码框,违反"任何时候不要让用户输入系统密码"红线。Linux 没有可移植的"纯指纹"CLI 闸门(pam_fprint 罕见且发行版绑定),身份无法被生物特征证明 →decide(tty=true, ssh=false, bio=None)=RequirePassphrase,keyring 也不参与(否则等于零验证)。headless 自动化仍走 keyring 静默。 -
pre_execforRLIMIT_CORE=0—tokio::process::Commanddoesn't exposesetrlimit. Must usecmd.pre_exec(|| setrlimit(...))closure (runs after fork, before execve). Pattern insrc/lib.rs::spawn_child. -
Secret<String>in secrecy 0.10 =SecretBox<String>— don't follow 0.8 docs. -
stdout mask uses
Vec<u8>notString— child stdout may be UTF-8 invalid (binary data); bytes avoidfrom_utf8panic. -
audit log flush before child exits —
AuditLog::write_eventcalls.flush(). If child crashes mid-exec, audit isn't lost. -
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。 -
Argon2 parameters —
m=64 MiB, t=3, p=4is standard. Don't tune down (defeats offline brute force). Eachxopinvocation pays ~250ms per unlock. -
Vault file is per-user —
~/.x/xop/key.dbresolves via$HOME. CI tests must setHOMEto a temp dir before running, which is why--test-threads=1matters. -
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必须空。 -
TTY-aware passphrase prompt —
is_terminal(stdin)决定走/dev/tty还是 stdin fallback。如果用/dev/tty文件存在性检测会误判(SSH 下文件存在但不可用)。用std::io::IsTerminal(POSIXisatty(fd))才是真信号。 -
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 一次。 -
SecretRef::argv_placeholder区分两种注入 —--secret KEY=NAME(envp) vs%XOP_KEY%(argv)。两者走同一个 vault resolve,但build_envp_delta跳过 placeholder,scrub_argv处理 placeholder。ResolvedValue镜像标志位。 -
绝不调 macOS Keychain /
security(1)— 实测:agent 后台会话里security add/find/delete-generic-password会弹系统授权对话框("xop wants to modify/delete keys"),用户体验等同攻击,整个 keychain 方案 2026-10-02 被否决删除。免密解锁 =~/.x/xop/keyring0600 文件(存 argon2 派生密钥 hex,非 passphrase 本身;mode 不合规直接拒用)。OS 预闸门顺序写死在 keyring 读取之前,且闸门结论决定 keyring 资格——本地指纹通过或 headless 才免输;SSH/无指纹交互必须输口令,keyring 根本不读。 -
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。) -
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_CLIENTenv(sshd 注入,本地 Terminal.app 没有)。语义:SSH 交互会话 →Gate::RequirePassphrase(输 xop 管理员密码,keyring 不参与——没有指纹现证就没有任何身份验证垫底);ssh host cmd无 pty 的自动化 → 仍 headless → keyring 静默(xop run无人值守不受影响)。判断顺序!tty → ssh → bio,headless 检查必须在 ssh 之前。 -
数据目录搬家是「复制不移动」 —
~/.xop/→~/.x/xop/(v0.5)。用户真实 vault 有 18+ key,迁移只复制 key.db / keyring / audit.jsonl,旧目录原样留着当备份;新目录已有 vault 时迁移自动跳过。migrate_legacy_from(new_home, old_home)路径显式化,单测不碰全局$HOME(坑 18 同款纪律)。 -
vault 明文加
__meta__子表不破坏旧格式 — toml 0.8 序列化时普通值先于表输出(已用临时测试验证),所以KEY = "value"+[__meta__]不会触发 ValueAfterTable。encode_plaintext在 meta 为空时完全省略__meta__表,没描述的 vault 保持旧扁平布局,老版本 xop 二进制照样能读。 -
glob 匹配器自研不引 globset — 需求只有
*/?;引依赖会带进正则语义([]/{})并破坏 xop「零外部依赖」的定位。src/glob.rs双指针 + star 回溯,11 条单测。matches("*_user", "user")= false——*不能凭空造出字面_。 -
元数据免闸门 ≠ 值免闸门 — 2026-10-22 用户反馈「
xop list应该是免密免 touch 的吧,不然 AI 做会中断」。闸门的作用是"释放真值前确认有人在场",list/desc只给 key 名和描述、永不吐 value,所以跳过闸门不泄漏任何 secret。别把Vault::open的闸门拆掉(那会让get/run也免掉)——正确做法是新增open_metadata路径 +auth::needs_gate(Intent)纯函数把策略钉死。 -
pty 回归测试用
script -q /dev/null,且必须带超时 — macOS 的script给子进程起真 pty(test -t 0为真),正好复现"终端里跑 xop"的场景。闸门若回来,子进程会卡在 Touch ID 弹窗 → 测试挂死而不是失败。用std::sync::mpsc::recv_timeout+ 后台线程收wait_with_output兜住。 -
描述文字不要求引号 — 用户明确说「打引号很难输入」。
xop desc文字参数是Vec<String>+trailing_var_arg,多词 join;用户真打进 vault 的一层引号在join_description里剥掉(只认 ASCII 单字节引号,切点必是 char 边界)。 -
搜索要打引号的锅在 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:
- Implement
NetworkGuard::setupfor macOS (pfctl+ anchor) and Linux (iptables+ owner match). - Test: launch
xop --allow-net=db.local:5432 --deny-net=* -- curl -s db.local:5432and verify it succeeds;xop ... -- curl -s evil.comshould fail. - Implement
FileGuard::setupfor macOS (sandbox-exec) and Linux (landlock). - Askpass strategy for SSH: write askpass script, set
SSH_ASKPASS_REQUIRE=force+DISPLAY=:0,srm -mon 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.runAgentLoopMCP tool. - Add a new MCP tool
xstudio.secrets.execthat callsxop::run(args)internally. - Or expose xop as a CLI that xstudio's agent runtime shells out to.
- The
library modeitem in P2 is exactly for this —pub use xop::execfor 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 |