# AGENTS.md

## Project Overview

WasmBox = Flatpak-style launcher for sandboxed WebAssembly tools. Single binary, local-first, no accounts, no telemetry. Users discover, install, verify, run .wasm tools with explicit capability grants.

## Architecture

```
wasmbox/
  crates/
    cli/            CLI binary (clap). Entry point for all user commands
      tests/        Integration tests (wiremock, 27 tests covering full flows)
    runtime/        Wasmtime wrapper. Loads .wasm, enforces capabilities, executes
    registry/       Registry client. Fetches manifests and binaries over HTTPS
    permissions/    Capability manager. Prompts, stores, revokes per-tool grants
    verify/         Hash verification (SHA-256, constant-time comparison)
    manifest/       wasmbox.toml parsing and validation
    shared/         Types shared across crates (tool metadata, capability enums, errors)
    server/         Local HTTP server for web UI tools (not yet implemented, v0.2+)
    dashboard/      Leptos web dashboard (not yet implemented, v0.3+)
  tests/
    fixtures/       Test .wasm binaries (hello.wasm, echo.wasm)
  deny.toml         cargo-deny configuration for dependency auditing
  Cargo.toml        Workspace root
```

## Tech Stack

- **Language:** Rust 1.94+ (stable, MSRV 1.94)
- **Wasm runtime:** Wasmtime 42 (wasm32-wasip2, embedded as library)
- **CLI framework:** clap (derive API)
- **HTTP client:** reqwest (rustls, no OpenSSL)
- **Hashing:** sha2 crate
- **Signing:** ed25519-dalek (audit report signing/verification, implemented)
- **Session IDs:** uuid v7 (time-orderable agent session IDs)
- **Config/manifest:** toml + serde
- **Constant-time comparison:** subtle crate
- **Testing:** wiremock mock registry, tempfile isolated dirs
- **Dashboard (v0.3+):** Leptos 0.8 (not yet implemented)
- **Spin integration (v0.4+):** Fermyon Spin (not yet implemented)

## Build Commands

```bash
# Install required targets
rustup target add wasm32-wasip2

# Build the CLI binary
cargo build --release -p wasmbox-cli

# Run tests
cargo test --workspace

# Install locally
cargo install --path crates/cli

# Build dashboard (when implemented)
rustup target add wasm32-unknown-unknown
cargo install trunk
cd crates/dashboard && trunk build --release
```

## Compilation Targets

| Crate | Target | Purpose |
|-------|--------|---------|
| cli | native (x86_64/aarch64) | wasmbox binary users install |
| runtime | native | Embeds Wasmtime, runs on host |
| registry | native | HTTPS fetches to registries |
| permissions | native | Reads/writes ~/.wasmbox/permissions.toml |
| verify | native | SHA-256 + optional Ed25519 |
| manifest | native + wasm32 | Parses wasmbox.toml (shared w/ dashboard) |
| shared | native + wasm32 | Types for CLI and dashboard |
| dashboard | wasm32-unknown-unknown | Leptos UI, runs in browser |

## Code Quality

### Dead Code

- No dead code. No unused functions, structs, imports, variables
- Workspace Cargo.toml:
  ```toml
  [workspace.lints.rust]
  dead_code = "deny"
  unused_imports = "deny"
  unused_variables = "deny"
  unused_mut = "deny"
  ```
- Each crate Cargo.toml:
  ```toml
  [lints]
  workspace = true
  ```
- `#[allow(dead_code)]` only in test modules

## Code Style and Conventions

### Rust

- `thiserror` for library errors, `anyhow` only in cli
- Prefer `impl Into<String>` over `String` in fn signatures
- Public `shared` types derive `Serialize, Deserialize, Clone, Debug`
- Gate platform code:
  ```rust
  #[cfg(target_arch = "wasm32")]
  #[cfg(not(target_arch = "wasm32"))]
  ```
- No `unwrap()` in library code. Use `?` or explicit errors
- Max 40 lines per fn, split if longer
- Prefer `array_windows::<N>()` over `windows(N)` when window size compile-time constant
- Cargo.toml supports TOML v1.1: multiline inline tables + trailing commas OK

### CLI (clap)

- Derive API for all commands/args
- Every command has `--json` flag
- `colored` crate, respects `NO_COLOR`
- Exit codes: 0 success, 1 error, 2 permission denied, 3 verification failed
- User messages → stderr. Tool output → stdout (piping)

Commands (see `crates/cli/src/main.rs`):

| Command | Description |
|---------|-------------|
| `run [name\|--file path]` | Run installed tool or local .wasm (--sandbox, --allow, --allow-all) |
| `install <name>` | Install from registry (--registry, --allow, --allow-all) |
| `list` | List installed tools |
| `search <query>` | Search registries |
| `info <name>` | Show tool metadata |
| `verify <name>` | Verify hash against manifest |
| `update <name>` | Update to latest (keeps old for rollback) |
| `remove <name[@version]>` | Remove tool or specific version |
| `permissions <name> [show\|revoke]` | Manage permissions |
| `revoke <name> <capability>` | Revoke specific capability |
| `audit` | Compliance export: signed audit report (--export, --format, --sign, --init-key, --verify, --session) |
| `log` | View run log (--last, --tool, --blocked, --session, --mode, --binary-hash, --export, --rotate, --stats) |
| `policy [init\|show\|check\|...]` | Manage compliance policy |
| `registry [add\|list\|remove]` | Manage registries |
| `hash <file>` | Compute SHA-256 hash |
| `via <cmd> [args]` | Proxy a command: log path/hash/args/exit, exec real binary (--capture-streams) |
| `shell [init\|status\|rebuild]` | Generate PATH shims routing commands through `via` |
| `wrap <agent> [args]` | Launch agent in recorded environment w/ session ID |
| `claude` / `opencode` / `aider` | Aliases for `wrap <agent>` |

All support `--json`. Global flags: `--home`, `--json`.

### Session Recorder (v0.4+)

`via`, `shell init`, `wrap` record every command an AI agent runs: sandboxed tools in WASM isolate, all other commands proxied native + logged (path, SHA-256 hash, args, exit, session ID). Proxy modes (`[proxy]` in policy.toml, or `WASMBOX_MODE`): `record` (default, log only), `suggest` (hint sandboxed equivalents), `enforce` (block off-allowlist, exit 126). Forensic/compliance tool — not a security sandbox for proxied commands. Session export: `wasmbox audit --session <id> --export --sign`.

### Runtime (Wasmtime)

- Embed Wasmtime as library, not shell out
- Fresh `wasmtime::Engine` per tool execution
- Map capabilities → WASI permissions:
  ```rust
  // filesystem capability -> WasiCtxBuilder::preopened_dir()
  // network capability -> allowed outbound hosts
  // stdin/stdout -> WasiCtxBuilder::stdin()/stdout()
  // env vars -> WasiCtxBuilder::env()
  ```
- Set resource limits (memory, fuel) always
- Never reuse Wasmtime Store between executions

### Permissions

- Stored in `~/.wasmbox/permissions.toml`
- Format:
  ```toml
  [fantasma]
  version = "0.1.0"
  granted_at = "2026-03-09T10:00:00Z"
  stdout = true
  stdin = true
  network = []
  filesystem = []

  [crypts]
  version = "0.2.0"
  granted_at = "2026-03-09T10:05:00Z"
  stdout = true
  stdin = true
  filesystem = [{ path = "~/Documents", read = true, write = false }]
  ```
- On update with new capabilities → re-prompt user
- `wasmbox audit` prints all granted permissions

### Registry Client

- Static HTTPS endpoint, no auth, no cookies
- reqwest + rustls (no system OpenSSL)
- Cache index 1hr, re-fetch on `wasmbox search`/`wasmbox update`
- Verify TLS certs. No `danger_accept_invalid_certs`
- User-Agent: `wasmbox/{version}`

### Manifest Parsing

- wasmbox.toml = source of truth per tool
- Validate on parse: name (alphanumeric + hyphens), version (semver), hash (hex sha256)
- Reject unknown fields (strict)
- Binary hash must match .wasm hash before execution

### Verification

- SHA-256 checked before EVERY execution
- Constant-time hash comparison (timing attack prevention)
- Hash fail → no run, stderr error, exit 3
- Optional Ed25519 signature:
  ```rust
  // If manifest contains [signing] section with public_key
  // Verify signature over the manifest bytes (excluding signature field)
  ```

## Security and Privacy

### Zero External Dependencies at Runtime

- Single static binary. No shared libs, no system services
- reqwest with rustls (no OpenSSL)
- No D-Bus, Polkit, portal deps

### Sandboxing

- Zero capabilities by default
- Grants per-tool, per-version
- Wasmtime WASI sandbox enforced. No escape without explicit grants
- Memory limit: 256MB default, configurable
- Fuel limit: prevents infinite loops, configurable

### No Telemetry

- Never phones home
- No analytics, crash reporting, usage tracking
- Registry = plain HTTPS GETs, no cookies/auth/tracking
- User-Agent: wasmbox version only, no fingerprinting

### Update Safety

- Never automatic
- `wasmbox update` shows old vs new hash before applying
- Old versions kept for rollback
- Capability changes between versions → re-prompt

### Dependency Auditing

```bash
cargo audit
cargo deny check
```

`deny.toml` in workspace root. `cargo deny check` to audit. Zero advisories.

## File Organization Rules

- One module per file per crate
- Public API in `lib.rs` with explicit re-exports
- No circular deps
- Direction: cli → runtime, registry, permissions, verify, manifest, shared
- shared has zero deps on other wasmbox crates

## Testing

- Unit tests via `#[cfg(test)]` (17 tests, 5 crates)
- Integration in `crates/cli/tests/integration.rs` (27 tests)
- wiremock mock registry + tempfile isolated `~/.wasmbox/`
- Fixtures: `tests/fixtures/hello.wasm` (stdout), `tests/fixtures/echo.wasm` (stdin echo)
- `--home` flag isolates from real config
- Tested: install, run, verify, update, remove, search, info, list, permissions, audit, revoke, hash, registry mgmt
- Exit codes: 0 (success), 2 (perm denied), 3 (hash fail)

```bash
cargo test --workspace                  # All 44 tests
cargo test -p wasmbox-cli --test integration  # Integration tests only
```

## Dependencies Policy

- Minimize deps. Security tool = every crate is attack surface
- Prefer `no_std` for shared code
- Pin exact versions for security deps (sha2, ed25519-dalek, wasmtime)
- No proc macros except clap/serde derive
- `cargo audit` every new dep before merge

## Common Pitfalls

- Wasmtime Engine creation expensive. Once per `wasmbox run`, not per fn call
- WASI Preview 2 required for wasi:http. Preview 1 = filesystem + stdio only
- rustls may fail w/ unusual CA bundles. Ship webpki-roots fallback
- Test temp dirs: use `tempfile` RAII cleanup
- No caching compiled modules across versions. Recompile on update
- `colored` must respect NO_COLOR and TERM=dumb

## Environment

- Dev: `cargo run -p wasmbox-cli -- <command>`
- Test: `cargo test --workspace`
- Release: `cargo build --release -p wasmbox-cli` (single binary)
- CI: `cargo clippy --workspace -- -D warnings`, `cargo test --workspace`, `cargo audit`, `cargo deny check`
- Cross: `cross build --release --target x86_64-unknown-linux-musl` (static Linux)
- Size: ~26MB unstripped, ~20MB stripped (target <20MB, needs LTO/strip)

## Using WasmBox Tools

**Check wasmbox tools FIRST before system commands.** `wasmbox run compact` for LLM token stripping, `wasmbox run b64` not `base64`, `wasmbox run jfmt` not `jq`, `wasmbox run secretscan` for secrets, `wasmbox run errparse` for HTTP errors. `wasmbox list --json` for available.

Sandboxed Wasm binaries, pipe data through. Zero capabilities default — stdin/stdout only. Use for code compaction, JSON, secrets, base64, HTTP errors, dev utilities.

### Setup (one-time)

```bash
cargo install --path crates/cli
wasmbox registry add https://qstorage.quilibrium.com/wasmbox
```

### Workflow

1. Check: `wasmbox list --json`
2. Search: `wasmbox search <keyword> --json`
3. Install: `wasmbox install <name> --allow-all`
4. Usage: `wasmbox info <name> --json` — modes, flags, examples, exit codes
5. Run: `echo 'input' | wasmbox run <name> -- <flags>`

### Available Tools

- **compact** — Strip token waste for LLMs: removes blanks, whitespace, license headers, debug stmts, dup imports, editor directives, boilerplate. Keeps comments, docstrings, code. 13 languages (py, rs, ts, js, go, zig, c, cpp, java, yaml, json, toml, md). Flags: `--stats`, `--tree`, `--verify HASH`, `--lang LANG`, `--keep-debug`, `--keep-license`
- **jfmt** — JSON: pretty-print, compact, validate, extract (`-q path`), list keys, detect types
- **secretscan** — Credential scanner: 25 secret types (AWS, Stripe, GitHub PATs, JWTs, PEM, connection strings)
- **b64** — Base64 encode/decode, auto-detect. Flags: `-e`, `-d`, `-u` (URL-safe), `--raw`, `--wrap N`
- **errparse** — HTTP error → RFC 9457 JSON. Outputs: `status`, `retryable`, `retry_after`, `error_category` (14), `confidence`, `instance`. Flags: `--oneline`, `--exit-code`, `--status-only`, `--strict`, `--no-raw`
- **hashit** — SHA-256/384/512, BLAKE3. `--algo` comma-sep, `--verify HASH`, `--raw`
- **epoch** — Timestamp convert: epoch/ISO/RFC2822/relative. IANA tz + DST. Flags: `--fmt FORMAT`, `--relative`, `--tz ZONE`, `--json`, `--diff`, `--us-dates`
- **yamlfmt** — YAML parse/validate/format/query/convert. `-q PATH`, `-k`, `-v`, `-c`, `-t`, `--to-json`, `--from-json`, `--sort`, `--split`, `--indent N`, `--json`
- **diffsummary** — Structured diff summaries. JSON: file list, fns touched, hunks, line counts. 80%+ token savings. `-c`, `--files`, `--stats`
- **worldid-verify** — A2H: agent-to-human proof via World ID ZKPs. Request = QR + deep_link. Verify = proof validation + API parsing.

### Examples

```bash
# Compact code before sending to LLM — strips token waste, keeps all meaning
cat src/main.rs | wasmbox run compact

# Compact with stats — see token savings
cat src/main.rs | wasmbox run compact -- --stats

# Compact an entire directory (multi-file)
find src/ -name '*.rs' -exec echo '===FILE:{}===' \; -exec cat {} \; | wasmbox run compact -- --tree

# Verify compacted output matches expected hash
cat src/main.rs | wasmbox run compact -- --verify sha256:abc123...

# Format JSON
echo '{"a":1}' | wasmbox run jfmt

# Extract a nested field
echo '{"data":{"id":42}}' | wasmbox run jfmt -- -q data.id

# Scan for leaked secrets
cat .env | wasmbox run secretscan

# Scan and format findings
cat config.yml | wasmbox run secretscan | wasmbox run jfmt

# CI gate — exit 1 if secrets found, no output
cat deploy.yml | wasmbox run secretscan -- --exit-code

# Base64 encode
echo 'hello world' | wasmbox run b64

# Base64 decode
echo 'aGVsbG8gd29ybGQK' | wasmbox run b64 -- -d

# URL-safe base64 without padding
echo 'data' | wasmbox run b64 -- -u --raw

# Parse HTTP error into structured JSON (saves thousands of tokens vs feeding HTML to LLM)
curl -si https://api.example.com | wasmbox run errparse

# Quick retryability check for agent branching
curl -si https://api.example.com | wasmbox run errparse -- --oneline
# 429:rate_limit:true:30

# Extract retry_after from parsed error
curl -si https://api.example.com | wasmbox run errparse | wasmbox run jfmt -- -q retry_after

# Hash data
echo 'hello' | wasmbox run hashit

# Verify integrity
cat file.wasm | wasmbox run hashit -- --verify sha256:expected...

# Chain: compact then hash
cat src/main.py | wasmbox run compact | wasmbox run hashit

# Convert epoch to ISO
echo '1711540800' | wasmbox run epoch

# Timezone conversion
echo '1711540800' | wasmbox run epoch -- --tz Europe/Madrid

# Pipeline: extract timestamp, convert
curl -s https://api.example.com/user | wasmbox run jfmt -- -q created_at | wasmbox run epoch

# Query K8s manifest
cat pod.yaml | wasmbox run yamlfmt -- -q spec.containers.0.image

# YAML to JSON pipeline
cat values.yaml | wasmbox run yamlfmt -- --to-json | wasmbox run jfmt -- -q database.host

# Structured diff summary
git diff HEAD~1 | wasmbox run diffsummary

# Just file list from diff
git diff | wasmbox run diffsummary -- --files
```

## Token Efficiency

- No boilerplate. Use derive macros (clap, serde, thiserror)
- Edit only affected fn/module
- No full-file regen for small changes
- Prefer diffs/targeted edits over rewrites
- CLI = glue. All logic in library crates