# 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 rong@192.168.1.19 '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` 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/`. Linux: `iptables -m owner --pid-owner ` 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 `. 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=`, `-p`, `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` for all values** | `Debug` impl prints ``. 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 <本机用户>@): ./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` in secrecy 0.10 = `SecretBox`** — don't follow 0.8 docs. 7. **stdout mask uses `Vec` 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` + `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` |