vaibot-guard

# VAIBot Guard (OpenClaw Skill)

This skill provides a **local policy decision service** plus a `vaibot-guard` CLI that enforces **pre-execution checks** and writes a **tamper-evident audit log**.

## Deployment modes

- **Local workstation mode (recommended default):** run `vaibot-guard` as a **systemd user service** (`systemctl --user`), optionally coupled to `openclaw-gateway.service` so it starts whenever OpenClaw starts (typically at login).
- **VPS / production mode:** run `vaibot-guard` as a **systemd system service** (`sudo systemctl`) under a dedicated user, with stricter sandboxing and boot-time startup.

See: `references/ops-runbook.md`.

Note: some registries/packagers may strip `*.service` files. This skill’s `install-local` command generates the **user** unit file at install time, so the Clawhub-installed package does not need to include `systemd/*/*.service`.

## Quick Start (local workstation)

### 0) One-time install + configure (recommended)

Fast path (recommended): one-command local install.

This will:
- install a **systemd user service** (`~/.config/systemd/user/vaibot-guard.service`)
- create `~/.config/vaibot-guard/vaibot-guard.env` (mode `0600`) if missing
- **auto-generate `VAIBOT_GUARD_TOKEN`** if it isn’t already set

```bash
node scripts/vaibot-guard.mjs install-local
```

Or run the interactive configurator only (writes/updates `~/.config/vaibot-guard/vaibot-guard.env` with `chmod 600`):

```bash
node scripts/vaibot-guard.mjs configure
```

### 1) Start + smoke test

#### Foreground (quick dev check)

From this skill directory:

```bash
# 1) Start the guard service (foreground)
# Reads VAIBOT_GUARD_TOKEN (and other settings) from:
#   - env vars, or
#   - ~/.config/vaibot-guard/vaibot-guard.env
node scripts/vaibot-guard-service.mjs
```

In another terminal:

```bash
# 2) Precheck + exec (example)
node scripts/vaibot-guard.mjs precheck --intent '{"tool":"system.run","action":"exec","command":"/bin/echo","cwd":".","args":["hello"],"expect...

# VAIBot-Guard

Local policy guard + tamper-evident audit log for OpenClaw/VAIBot operations.

At a high level:
- You run a **local Guard service** (`vaibot-guard-service`) on `127.0.0.1`.
- OpenClaw (via a bridge plugin) or a CLI wrapper asks Guard **“is this tool call allowed?”**
- Guard returns `allow | deny | approve` and writes an append-only **audit trail** under `.vaibot-guard/`.

## What this repo/package contains

- `scripts/vaibot-guard-service.mjs` — HTTP service (policy decisions + audit + checkpoints)
- `scripts/vaibot-guard.mjs` — CLI to install/configure/run precheck/exec/finalize/flush/proof
- `references/` — policy + receipt/checkpoint schema docs
- `systemd/` — example unit/env files (note: some registries strip `.service` files)

## HTTP API (current)

Health:
- `GET /health`

Exec decisions (shell commands):
- `POST /v1/decide/exec`
- `POST /v1/finalize`

Generic tool decisions (used by the OpenClaw bridge plugin):
- `POST /v1/decide/tool`
- `POST /v1/finalize/tool`

Ops / audit:
- `POST /v1/flush` — attempt to flush/anchor checkpoints
- `POST /api/proof` — inclusion proofs for checkpointed leaves

> Auth: if `VAIBOT_GUARD_TOKEN` is set, protected endpoints require `Authorization: Bearer <token>`.

## Quick start (local workstation)

### 1) Install local service + config (recommended)

From this directory:

```bash
node scripts/vaibot-guard.mjs install-local
```

This will:
- create/update `~/.config/vaibot-guard/vaibot-guard.env` (chmod 600)
- generate a `VAIBOT_GUARD_TOKEN` if missing
- generate a **systemd user** unit (so it can run continuously)

Start it:

```bash
systemctl --user daemon-reload
systemctl --user enable --now vaibot-guard
systemctl --user status vaibot-guard --no-pager
```

### 2) Dev-mode foreground run (fast check)

```bash
node scripts/vaibot-guard-service.mjs
```

Then in another terminal:

```bash
curl -s http://127.0.0.1:39111/health | jq
```

## Wiring into OpenClaw

VAIBot-Guard can be used two ways:

1) **Skill/CLI wr...