@wlfi-agent/cli 1.4.13 → 1.4.15

package/Cargo.toml

@@ -0,0 +1,50 @@
+[workspace]
+members = [
+    "crates/vault-domain",
+    "crates/vault-policy",
+    "crates/vault-signer",
+    "crates/vault-daemon",
+    "crates/vault-transport-unix",
+    "crates/vault-sdk-agent",
+    "crates/vault-cli-admin",
+    "crates/vault-cli-agent",
+    "crates/vault-cli-daemon",
+    "crates/vault-transport-xpc",
+]
+resolver = "2"
+
+[workspace.package]
+edition = "2021"
+license = "MIT"
+version = "0.1.0"
+authors = ["WLFI Agent SDK Team"]
+
+[workspace.dependencies]
+alloy-primitives = "0.8"
+alloy-sol-types = "0.8"
+anyhow = "1"
+argon2 = "0.5"
+async-trait = "0.1"
+block = "0.1"
+chacha20poly1305 = "0.10"
+clap = { version = "4.5", features = ["derive", "env"] }
+core-foundation = "0.10"
+crossterm = "0.28"
+hex = "0.4"
+k256 = { version = "0.13", features = ["ecdsa"] }
+libc = "0.2"
+rand = "0.9"
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
+ratatui = "0.29"
+rpassword = "7"
+security-framework = { version = "3.7", features = ["OSX_10_15"] }
+security-framework-sys = "2.17"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+sha2 = "0.10"
+thiserror = "2"
+time = { version = "0.3", features = ["macros", "serde", "formatting", "parsing"] }
+tokio = { version = "1", features = ["macros", "rt-multi-thread", "sync", "net", "io-util", "time", "signal"] }
+uuid = { version = "1", features = ["serde", "v4"] }
+zeroize = "1"
+x25519-dalek = { version = "2", features = ["static_secrets"] }

package/README.md

@@ -1,17 +1,437 @@
-# @wlfi-agent/cli
+# WLFI Agent SDK
 
-Command-line package for WLFI Agent Wallet workflows.
+WLFI Agent SDK is a root-managed local signing daemon with policy enforcement, a single `wlfi-agent` CLI, and an optional relay + web approval flow.
+
+The main user path is:
+
+1. run `wlfi-agent admin setup`
+2. let it install the daemon and set up a wallet
+3. use `wlfi-agent transfer`, `wlfi-agent transfer-native`, `wlfi-agent approve`, or `wlfi-agent broadcast`
+4. optionally connect a relay for browser-based manual approvals
+
+User-facing examples below avoid shell env vars on purpose. Prefer prompts, config files, `wlfi-agent admin tui`, and explicit command flags.
+
+## Command model
+
+- `wlfi-agent admin setup`
+  - first-run setup
+  - stores the vault password in macOS System Keychain
+  - installs the root LaunchDaemon
+  - creates a vault key + agent key
+  - prints the Ethereum address
+- `wlfi-agent admin tui`
+  - token-first policy editor for per-token defaults, destination overrides, and manual approvals
+- `wlfi-agent admin reset`
+  - removes the managed daemon state and local wallet credentials
+  - use it only when you are intentionally discarding the current wallet
+- `wlfi-agent admin uninstall`
+  - fully removes the managed daemon, root-owned state, local config, local binaries, and logs
+  - use it when you want WLFI removed from the machine instead of preparing for another setup
+- `wlfi-agent admin ...`
+  - direct policy and relay configuration commands
+- `wlfi-agent transfer`, `wlfi-agent transfer-native`, `wlfi-agent approve`, `wlfi-agent broadcast`
+  - submits signing requests through the daemon
+  - uses the configured agent key id plus the macOS Keychain token by default
+- `wlfi-agent status`
+  - inspects local wallet security posture, daemon/socket trust, state-file trust, bootstrap artifacts, and agent token storage
+  - use `--strict` when you want CI or automation to fail on warnings
+- `wlfi-agent repair`
+  - non-privileged local cleanup for plaintext bootstrap artifacts and legacy `agentAuthToken` config storage
+  - uses `--overwrite-keychain` only when you have confirmed the plaintext config token is the credential you intend to keep
+- `wlfi-agent daemon`
+  - not a user entrypoint; daemon lifecycle is managed by `wlfi-agent admin setup`
 
 ## Install
 
+### Install from npm
+
 ```bash
 npm i -g @wlfi-agent/cli
 ```
 
-## Configuration
+### Work from this repo
+
+```bash
+pnpm install
+npm run build
+npm run install:rust-binaries
+```
+
+If you update Rust daemon code, rerun `npm run install:rust-binaries` so the root-managed daemon uses the new installed binaries under `~/.wlfi_agent/bin`.
+
+## Easiest wallet setup
+
+Run this once:
+
+```bash
+wlfi-agent admin setup
+```
+
+Preview the exact sanitized setup plan first:
+
+```bash
+wlfi-agent admin setup --plan
+```
+
+The preview is read-only. It does not prompt for the vault password, does not touch sudo, and does not mutate wallet or policy state. It prints the planned Rust command, trust preflight results, overwrite risk, and the password transport mode that would be used for the real setup.
+
+You will be prompted for the vault password. The command:
+
+- installs or refreshes the root daemon
+- waits for the daemon to come up
+- configures the requested spending policies
+- imports the agent token into macOS Keychain
+- prints the wallet address
+
+By default, setup keeps the freshly issued agent auth token in macOS Keychain and redacts it from CLI output. Only use `--print-agent-auth-token` when you intentionally need to export that secret.
+
+Example with explicit chain config:
+
+```bash
+wlfi-agent admin setup \
+  --network 11155111 \
+  --chain-name sepolia \
+  --rpc-url https://rpc.sepolia.example \
+  --allow-native-eth \
+  --per-tx-max-wei 1000000000000000000 \
+  --daily-max-wei 5000000000000000000 \
+  --weekly-max-wei 20000000000000000000
+```
+
+Typical output ends with:
+
+```text
+setup complete
+address: 0x...
+vault key id: ...
+agent key id: ...
+daemon socket: /Library/WLFI/run/daemon.sock
+state file: /var/db/wlfi-agent/daemon-state.enc
+```
+
+## Policy definition
+
+There are three practical policy layers:
+
+1. default limits for every destination
+2. stricter per-destination overrides
+3. manual-approval overlays for transactions that should pause for operator review
+
+### Token-first policy setup: `wlfi-agent admin tui`
+
+Use the TUI when you want the easiest way to define:
+
+- a saved token inventory as the primary view
+- per-token per-tx / daily / weekly limits in token decimals
+- per-token gas / fee / calldata caps
+- token-specific destination overrides
+- token-specific manual approval overlays
+- token mappings across multiple saved networks
+
+Run:
+
+```bash
+wlfi-agent admin tui
+```
+
+Like `admin setup`, the TUI stores the new agent auth token in macOS Keychain by default and does not print it unless you pass `--print-agent-auth-token`.
+
+The TUI starts on the token list, lets you add new tokens or networks, fetches token name/symbol/decimals from the selected network RPC, and bootstraps every saved token across its selected networks.
+
+Important rule: destination overrides can only tighten the matching token policy; they cannot relax it.
+
+### Direct setup flags
+
+If you prefer direct flags over the TUI, `wlfi-agent admin setup` already passes through the common policy and wallet-setup options shown above.
+
+Useful direct flags include:
+
+- `--per-tx-max-wei`
+- `--daily-max-wei`
+- `--weekly-max-wei`
+- `--max-gas-per-chain-wei`
+- `--daily-max-tx-count`
+- `--per-tx-max-fee-per-gas-wei`
+- `--per-tx-max-priority-fee-per-gas-wei`
+- `--per-tx-max-calldata-bytes`
+- `--network`
+- `--token`
+- `--allow-native-eth`
+- `--recipient`
+
+### Manual approval policies
+
+Manual approval is an overlay policy: matching requests are held until an operator approves or rejects them.
+
+Create one with direct flags:
+
+```bash
+wlfi-agent admin add-manual-approval-policy \
+  --network 11155111 \
+  --recipient 0x1111111111111111111111111111111111111111 \
+  --allow-native-eth \
+  --min-amount-wei 1000000000000000 \
+  --max-amount-wei 2000000000000000
+```
+
+ERC-20 example:
+
+```bash
+wlfi-agent admin add-manual-approval-policy \
+  --network 11155111 \
+  --recipient 0x2222222222222222222222222222222222222222 \
+  --token 0x3333333333333333333333333333333333333333 \
+  --min-amount-wei 1000000 \
+  --max-amount-wei 5000000
+```
+
+The policy matches all transactions of the requested type that fall inside the destination / token / amount range.
+
+### Inspect and resolve manual approvals locally
+
+```bash
+wlfi-agent admin list-manual-approval-requests
+```
+
+Approve locally:
+
+```bash
+wlfi-agent admin approve-manual-approval-request \
+  --approval-request-id <REQUEST_ID>
+```
+
+Reject locally:
+
+```bash
+wlfi-agent admin reject-manual-approval-request \
+  --approval-request-id <REQUEST_ID>
+```
+
+## Agent requests
+
+Top-level signing commands always go through the daemon.
+
+After `wlfi-agent admin setup`, the normal path is to rely on the configured agent key id plus the token already stored in macOS Keychain. You only need `--agent-key-id` or `--agent-auth-token-stdin` when overriding that default.
+
+Native transfer:
+
+```bash
+wlfi-agent transfer-native \
+  --network 11155111 \
+  --to 0x1111111111111111111111111111111111111111 \
+  --amount-wei 1500000000000000
+```
+
+ERC-20 transfer:
+
+```bash
+wlfi-agent transfer \
+  --network 11155111 \
+  --token 0x3333333333333333333333333333333333333333 \
+  --to 0x2222222222222222222222222222222222222222 \
+  --amount-wei 1000000
+```
+
+Approve allowance:
+
+```bash
+wlfi-agent approve \
+  --network 11155111 \
+  --token 0x3333333333333333333333333333333333333333 \
+  --spender 0x4444444444444444444444444444444444444444 \
+  --amount-wei 1000000
+```
+
+Raw policy-checked transaction request:
+
+```bash
+wlfi-agent broadcast \
+  --network 11155111 \
+  --to 0x1111111111111111111111111111111111111111 \
+  --gas-limit 21000 \
+  --max-fee-per-gas-wei 2000000000 \
+  --value-wei 1500000000000000
+```
+
+If a request hits a manual-approval policy, the CLI prints:
 
-Backend URL is read from `WLFI_AGENT_BACKEND_URL` and defaults to `http://localhost:3000`.
+- approval request id
+- frontend approval URL, if relay is configured
+- relay URL
+- fallback local admin CLI command
 
-## Documentation
+## Local health checks and cleanup
 
-For full usage and API details, see `docs/agent-wallet.md` in this repository.
+Inspect the current machine state:
+
+```bash
+wlfi-agent status
+```
+
+Strict mode is useful in automation:
+
+```bash
+wlfi-agent status --strict
+```
+
+Repair local non-root issues such as lingering plaintext bootstrap files or legacy `agentAuthToken` config storage:
+
+```bash
+wlfi-agent repair
+```
+
+If you intentionally want to keep bootstrap artifacts but redact them in place instead of deleting them:
+
+```bash
+wlfi-agent repair --redact-bootstrap
+```
+
+## Relay setup
+
+Relay is optional. Use it when you want browser-based manual approval.
+
+### Local development setup
+
+1. Copy the relay config file:
+
+```bash
+cp apps/relay/.env.example apps/relay/.env
+```
+
+2. Edit `apps/relay/.env` and set the real values you want to use.
+
+3. Create `apps/web/.env.local`:
+
+```bash
+cat > apps/web/.env.local <<'EOF_WEB'
+NEXT_PUBLIC_WLFI_RELAY_BASE_URL=http://localhost:8787
+NEXT_PUBLIC_WLFI_SITE_NAME=WLFI Approval Console
+EOF_WEB
+```
+
+4. Start Valkey:
+
+```bash
+docker compose -f zarf/docker/valkey/compose.yml up -d
+```
+
+5. Start the relay:
+
+```bash
+pnpm --filter @wlfi-agent/relay dev
+```
+
+6. Start the web UI:
+
+```bash
+pnpm --filter @wlfi-agent/web exec next dev --hostname 127.0.0.1 --port 3000
+```
+
+7. Point the daemon at the relay and web UI:
+
+```bash
+wlfi-agent admin set-relay-config \
+  --relay-url http://localhost:8787 \
+  --frontend-url http://127.0.0.1:3000
+```
+
+The relay does not require daemon auth for daemon registration, polling, or feedback. Only
+admin relay APIs require `RELAY_ADMIN_TOKEN`.
+
+8. Confirm the daemon-side relay config:
+
+```bash
+wlfi-agent admin get-relay-config
+```
+
+### Production relay deploy
+
+The relay app includes Serverless configs under `zarf/serverless/relay/`.
+
+```bash
+pnpm --filter @wlfi-agent/relay deploy:development
+pnpm --filter @wlfi-agent/relay deploy:production
+```
+
+For local dev, prefer the checked-in `apps/relay/.env` file. For deployed environments, use your normal secret manager or platform config.
+
+## Relay approval flow
+
+When relay is configured and a request requires manual approval:
+
+1. the agent CLI prints a frontend approval URL
+2. the operator opens that URL in the browser
+3. the frontend encrypts the vault password + decision to the daemon’s advertised X25519 public key
+4. the relay queues the encrypted update
+5. the daemon polls, decrypts, applies the decision, and reports status back
+6. the original request can be retried and signed
+
+If the frontend link is unavailable, operators can always fall back to the local admin CLI approval command printed by the agent CLI.
+
+## Operational notes
+
+- The daemon state file lives at `/var/db/wlfi-agent/daemon-state.enc` and is intended to be root-only.
+- The managed socket lives at `/Library/WLFI/run/daemon.sock`.
+- If `setup` says the daemon password does not unlock the stored state, use the original vault password or reset the managed state before setting up a fresh wallet.
+- Forgotten vault password recovery is destructive: run `wlfi-agent admin reset`, then `wlfi-agent admin setup` to create a new wallet.
+- After changing daemon-side Rust code, run `npm run install:rust-binaries` and restart the managed daemon through `wlfi-agent admin setup`.
+
+## Reset a forgotten password
+
+If you forgot the vault password, there is no recovery path for the existing encrypted daemon state. Use reset only when you intentionally want to discard the old wallet and create a new one.
+
+```bash
+wlfi-agent admin reset
+```
+
+For automation or CI-style local flows:
+
+```bash
+wlfi-agent admin reset --yes
+```
+
+By default, reset keeps non-secret config like chain settings, but removes the managed daemon state, the daemon password stored in System Keychain, the local agent token, and lingering bootstrap artifacts.
+
+If you want a totally clean local slate too:
+
+```bash
+wlfi-agent admin reset --yes --delete-config
+```
+
+After reset, run `wlfi-agent admin setup` to create a new wallet.
+
+## Fully uninstall WLFI Agent
+
+Use uninstall when you want a full local cleanup instead of preparing for another setup. It removes:
+
+- the managed LaunchDaemon
+- `/Library/WLFI`
+- `/var/db/wlfi-agent`
+- `/var/log/wlfi-agent`
+- `~/.wlfi_agent`
+- the daemon password in System Keychain
+- the local agent auth token in Keychain
+
+```bash
+wlfi-agent admin uninstall
+```
+
+For automation or CI-style local flows:
+
+```bash
+wlfi-agent admin uninstall --yes
+```
+
+## Useful commands
+
+```bash
+wlfi-agent admin setup
+wlfi-agent admin tui
+wlfi-agent admin uninstall
+wlfi-agent admin get-relay-config
+wlfi-agent admin list-manual-approval-requests
+wlfi-agent wallet status
+npm run install:rust-binaries
+pnpm build
+pnpm typecheck
+```

package/crates/vault-cli-admin/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "wlfi-agent-admin"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+
+[dependencies]
+anyhow.workspace = true
+clap.workspace = true
+crossterm.workspace = true
+hex.workspace = true
+libc.workspace = true
+ratatui.workspace = true
+reqwest.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+rpassword.workspace = true
+time.workspace = true
+tokio.workspace = true
+uuid.workspace = true
+zeroize.workspace = true
+vault-daemon = { path = "../vault-daemon" }
+vault-domain = { path = "../vault-domain" }
+vault-signer = { path = "../vault-signer" }
+vault-transport-unix = { path = "../vault-transport-unix" }