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

11 KiB
Raw Permalink Blame History

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)

{"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:

{"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

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