Files
xop/docs/architecture.md
T
2026-10-02 18:25:29 +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() // ~/.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/.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()
// (~/.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.