# VaultMesh MCP + TEM Shield Node Integration

## 1. Overview

The VaultMesh core ledger integrates with an external **OffSec Shield
Node** that runs:

- OffSec agents
- MCP backend (FastAPI)
- TEM Engine (Threat / Experience Memory)

The node is implemented in the separate `offsec-agents/` repository and
deployed to `shield-vm` (or lab nodes). VaultMesh talks to it via HTTP
and ingests receipts.

---

## 2. Node Contract

**Node identity:**

- Node ID: `shield-vm` (example)
- Role: `shield` / `offsec-node`

**MCP endpoints (examples):**

- `GET /health`
- `POST /api/command`
  - `{ "cmd": "agents list" }`
  - `{ "cmd": "agent spawn", "args": {...} }`
  - `{ "cmd": "agent mission", "args": {...} }`
  - `{ "cmd": "tem status" }`
- `GET /tem/status`
- `GET /tem/stats`

---

## 3. VaultMesh Client (Thin Shim)

VaultMesh does not embed offsec-agents. It uses a minimal HTTP client:

- Location: `scripts/offsec_node_client.py`
- Responsibilities:
  - Send commands to Shield Node
  - Handle timeouts / errors
  - Normalize responses for `vm_cli.py`

Example call:

```python
from scripts.offsec_node_client import OffsecNodeClient

client = OffsecNodeClient(base_url="http://shield-vm:8081")

agents = await client.command("agents list")
status = await client.command("tem status")
```

---

## 4. CLI Integration

`vm_cli.py` can expose high-level commands that proxy to the Shield Node:

- `vm offsec agents`
  - Calls `agents list`
- `vm offsec mission --agent <id> --target <t>`
  - Calls `agent mission`
- `vm tem status`
  - Calls `tem status`

These commands are optional and only work if the Shield Node is
configured in env:

- `OFFSEC_NODE_URL=http://shield-vm:8081`

If the node is unreachable, the CLI should:

- Fail gracefully
- Print a clear error message
- Not affect core ledger operations

---

## 5. Receipts and Guardian Integration

The Shield Node writes receipts locally (e.g. on shield-vm):

- `/opt/offsec-agents/receipts/offsec.jsonl`
- `/opt/offsec-agents/receipts/tem/tem_events.jsonl`

Integration options:

1. **File sync / pull**
   - A sync job (cron, rsync, MinIO, etc.) copies receipts into the
     VaultMesh node under:
     - `receipts/shield/offsec.jsonl`
     - `receipts/shield/tem_events.jsonl`

2. **API pull**
   - Shield Node exposes `/receipts/export` endpoints
   - VaultMesh pulls and stores under `receipts/shield/`

Guardian then:

- Computes partial roots for Shield receipts:
  - `ROOT.shield.offsec.txt`
  - `ROOT.shield.tem.txt`
- Includes them in the combined anchor:

```python
roots = {
    "mesh": read_root("ROOT.mesh.txt"),
    "treasury": read_root("ROOT.treasury.txt"),
    "offsec": read_root("ROOT.offsec.txt"),
    "shield_tem": read_root("ROOT.shield.tem.txt"),
}
anchor_root = compute_combined_root(roots)
```

---

## 6. Configuration

Example env vars for VaultMesh:

- `OFFSEC_NODE_URL=http://shield-vm:8081`
- `OFFSEC_NODE_ID=shield-vm`
- `OFFSEC_RECEIPTS_PATH=/var/lib/vaultmesh/receipts/shield`

Example env vars for Shield Node:

- `VAULTMESH_ROOT=/opt/vaultmesh`
- `TEM_DB_PATH=/opt/offsec-agents/state/tem.db`
- `TEM_RECEIPTS_PATH=/opt/offsec-agents/receipts/tem`

---

## 7. Failure Modes

If the Shield Node is:

- **Down**: CLI commands fail, core ledger continues; Guardian anchors
  without Shield roots (or marks them missing).
- **Lagging**: Receipts are delayed; anchors include older Shield state.
- **Misconfigured**: CLI reports invalid node URL or protocol errors.

VaultMesh must never block core anchors solely because Shield is
unavailable; Shield is an extension, not the root of truth.

---

## 8. Design Principles

- Keep Shield node separate from VaultMesh core.
- Integrate via:
  - HTTP commands
  - Receipt ingestion
- Treat Shield as:
  - A specialized OffSec/TEM appliance
  - A contributor to the global ProofChain