Files
xop/docs/architecture.md
T
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

249 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# xop · Architecture
## Module dependency graph
```
main.rs
│
▼
lib.rs (run orchestrator)
│
┌────────────┬────────┼────────┬─────────────┬───────────────┐
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
args.rs secret.rs audit.rs policy.rs guard.rs injector.rs
(clap) (refs) (JSONL) (DSL types) (runtime) (env/askpass/fd)
│
│
┌────────────┼─────────────┐
│ │ │
▼ ▼ ▼
auth/ vault/ commands/
│ │ │
├─ mod.rs ├─ mod.rs ├─ mod.rs
│ (Gate/ ├─ keyring.rs├─ init.rs
│ decide) └─ format.rs ├─ set.rs
└─ touchid.rs ├─ list.rs
├─ get.rs
├─ rm.rs
├─ reset.rs
└─ key.rs
```
`backend/` was removed in v0.2 — the local vault replaces all four external backends.
## Data flow: a typical invocation
```
$ xop --secret DB_PASS=db_pass \
--allow-net=db.local:5432 \
--deny-net=* \
-- mysql -h db.local -u app -e 'SELECT 1'
1. CLI parse (args.rs)
Args {
subcmd: None,
secrets: [("DB_PASS", "db_pass")],
allow_net: ["db.local:5432"],
deny_net: ["*"],
on_leak: Mask,
dry_run: false,
exec_command: ["mysql", "-h", "db.local", "-u", "app", "-e", "SELECT 1"],
}
2. Ref resolution (secret.rs)
Ref { key: "db_pass", name: "db_pass" } // bare key, no scheme
3. Policy build (policy.rs)
Policy {
net: NetPolicy { allow: ["db.local:5432"], deny: ["*"] },
read: ReadPolicy { deny: ["/proc/self/environ", "~/.ssh/id_*", ...] },
leak: Mask,
}
4. Vault resolve (vault::resolve_all)
→ auth::authenticate() → Gate // headless(non-TTY)→AllowKeyring; SSH pty→RequirePassphrase (never remote biometric);
// local TTY: LAContext fingerprint — pass→AllowKeyring, cancel→exit 77, no-biometrics→RequirePassphrase
→ Gate::AllowKeyring ∧ keyring::load() // ~/.x/xop/keyring (0600) hit → key, no typing
→ Gate::RequirePassphrase ∨ no keyring // rpassword::prompt_password() → derive_key = argon2id(passphrase, salt)
→ AES-GCM decrypt → entries["db_pass"] = "hunter2"
→ ResolvedValue { key: "DB_PASS", name: "db_pass", backend: "vault", value: Secret("hunter2") }
5. Injector (injector.rs)
Strategy: Envp (mysql reads MYSQL_PWD natively)
envp_delta: [("DB_PASS", "hunter2"), ("HISTFILE", "/dev/null"), ...]
argv_scrubbed: ["mysql", "-h", "db.local", "-u", "app", "-e", "SELECT 1"]
6. Audit pre-event (audit.rs)
{"ts":"...","event":"spawn","refs":["db_pass"],"policy_hash":"sha256:abc...",
"child_argv":["mysql","-h","db.local","-u","app","-e","SELECT 1"]}
7. Network policy application (guard/network.rs)
macOS: pf rule → block all outbound from PID <x> except to db.local:5432
Linux: iptables -m owner --pid-owner <x> rule
(STUB in v0.2 — runtime TBD)
8. File policy application (guard/file.rs)
sandbox-exec profile → deny file-read* /proc/*/environ, ~/.ssh/id_*
(STUB in v0.2)
9. Spawn (tokio::process::Command)
cmd.pre_exec(|| { setrlimit(RLIMIT_CORE, 0, 0); Ok(()) }) // no core dumps
cmd.spawn() with:
- env_clear() + envs(parent_env) + envs(envp_delta)
- stdout: piped to xop's stdout filter
- stderr: piped to xop's stdout filter
- stdin: inherited from parent
- kill_on_drop(true)
10. Stdout filter (guard/stdout.rs)
Read chunk from child's stdout pipe.
For each chunk, check against secret value patterns.
If match: replace with [REDACTED:DB_PASS] (Mask) or SIGKILL (Kill).
Write to inherited stdout.
11. Audit post-event
{"ts":"...","event":"exit","child_pid":12345,"exit_code":0,"duration_ms":42}
12. waitpid() → exit code 0 propagated to xop's caller
```
## Subcommand flow (zdata vault operations)
```
$ xop set DB_PASS (value piped via stdin)
1. args.rs → Subcmd::Set { key: "DB_PASS", force: false }
2. commands::set::run("DB_PASS", false)
a. auth::authenticate("set DB_PASS in vault") → Gate
headless (no TTY) → AllowKeyring (automation path; no osascript call)
SSH_TTY/SSH_CONNECTION set → RequirePassphrase (never prompt biometrics remotely)
local TTY + macOS → LAContext.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics)
pass → AllowKeyring · cancel → exit 77 abort · no biometrics → RequirePassphrase
local TTY + Linux → RequirePassphrase (system password prompt forbidden)
b. Gate::RequirePassphrase → rpassword::prompt_password("Vault passphrase: ") (keyring ignored)
Gate::AllowKeyring + keyring present → silent; no keyring → prompt
c. vault::Vault::open(path)
key = keyring::load() ∨ argon2id(passphrase, salt)
plaintext = AES-GCM-decrypt(ciphertext, nonce, key)
entries = toml::from_str(plaintext) → HashMap<String, String>
d. read stdin to EOF → get new value (up to 256 chars)
e. if !force && entries.contains_key("DB_PASS"): error KeyAlreadyExists
f. entries.insert("DB_PASS", value)
g. vault.save()
serialize entries to TOML
re-randomize nonce
encrypt with derived key
atomic write: tmp + rename
h. audit::vault_set("DB_PASS")
i. zeroize passphrase buffer (Drop guard)
Other subcommands follow the same shape:
list: open + enumerate + audit (no stdout for values)
get: open + lookup + print + audit (value to stdout, single line)
rm: open + delete + save + audit (TTY confirm unless --force)
```
## Audit log format (JSONL, one event per line)
```jsonl
{"ts":"2026-10-01T12:34:56.123Z","event":"spawn","refs":["db_pass"],"backends":["vault"],"policy_hash":"sha256:9f2a...","child_argv":["mysql","-h","db.local","-u","app","-e","SELECT 1"],"net_allow":["db.local:5432"],"net_deny":["*"],"leak_action":"mask"}
{"ts":"2026-10-01T12:34:56.165Z","event":"stdout_mask","child_pid":12345,"ref":"db_pass","action":"masked","bytes_replaced":11}
{"ts":"2026-10-01T12:34:56.198Z","event":"exit","child_pid":12345,"exit_code":0,"duration_ms":75}
```
Vault subcommand events:
```jsonl
{"ts":"...","event":"vault_init","path":"/home/x/.x/xop/key.db"}
{"ts":"...","event":"vault_unlock","auth":"touchid","success":true}
{"ts":"...","event":"vault_set","name":"DB_PASS"}
{"ts":"...","event":"vault_get","name":"DB_PASS","ok":true}
{"ts":"...","event":"vault_rm","name":"DB_PASS"}
```
**Invariant (I2):** no `value`, `plaintext`, `ciphertext`, or `passphrase` field exists in any event. `secrecy::Secret` never crosses this boundary — only refs, names, and metadata.
## Trait surfaces
```rust
// src/auth/mod.rs
#[async_trait]
pub trait Auth: Send + Sync {
async fn authenticate(&self, reason: &str) -> Result<()>;
}
// src/vault/mod.rs
pub struct Vault { path, salt, nonce, key, entries }
impl Vault {
pub async fn open(path: &Path) -> Result<Self>;
// open order is FIXED: auth::authenticate() FIRST, then keyring::load()
// (~/.x/xop/keyring, 0600 — NOT macOS Keychain) — falls back to typed
// passphrase + argon2id only when the keyring is absent/XOP_NO_KEYRING=1.
pub async fn create(path: &Path, passphrase: &str) -> Result<Self>;
// create writes the vault AND saves the derived key to the keyring.
pub fn key_bytes(&self) -> &[u8; 32]; // for `xop key --save`
pub fn get(&self, key: &str) -> Option<&str>;
pub fn set(&mut self, key: &str, value: &str);
pub fn rm(&mut self, key: &str) -> bool;
pub fn list(&self) -> impl Iterator<Item = (&str, &str)>; // (key, created_at)
pub async fn save(&self) -> Result<()>;
}
// src/guard/mod.rs
#[async_trait]
pub trait Guard: Send + Sync {
fn name(&self) -> &'static str;
async fn setup(&self, policy: &Policy) -> Result<()>;
async fn teardown(&self) -> Result<()>;
}
```
## Lifecycle of a Secret\<T\>
```
vault::get(key) ──► Option<&str> (borrowed, never exposed to LLM)
│
▼
injector::build_envp_delta ──► Vec<(String, Secret<String>)>
│ │
▼ ▼
SecretBox::expose_secret() ◄──┘ tokio::Command envs iter
│ │
▼ ▼
String child copy at execve String dropped after spawn
│
▼
guard::stdout::filter ──► regex match against child
stdout bytes; never
logs value
│
▼
audit::log_event ──► writes ref/name only;
type system forbids
value field
```
The `secrecy::SecretBox` type provides:
- `Debug` impl that prints `<secret>` (so accidental `println!("{:?}", s)` is safe).
- `ExposeSecret` trait — explicit `.expose_secret()` required to read.
- `Drop` impl that zeroizes inner `T` (when `T: Zeroize`).
## Vault file format (binary)
```
Offset Size Field
------ ---- ----------------------------------------------------------
0 4 magic = b"XOP\x01"
4 4 version = 1 (u32 LE)
8 16 salt = argon2id salt (random per vault)
24 12 nonce = AES-GCM nonce (random per save)
36 N ciphertext = AES-256-GCM(key, nonce, plaintext) output
36+N 16 tag = AES-GCM auth tag (appended by aes-gcm crate)
HEADER_LEN = 4 + 4 + 16 + 12 = 36
Plaintext = UTF-8 TOML: `entries = { key_name = "value", ... }`
```
Write path: encrypt → write to `key.db.tmp.<pid>` → fsync → rename to `key.db`.
Read path: open → read header → read ciphertext → decrypt → parse TOML.