# TruthGate for Agents

TruthGate is a fail-closed preflight, approval, evidence, and verification
runtime for Hermes, OpenClaw, n8n agents, and custom LLM systems.

It does not promise zero hallucinations. It prevents unsupported output from
being treated as verified completion.

## v0.2 security model

- Server-owned policy cannot be weakened by request payloads.
- API routes require a bearer key.
- High-risk approvals are HMAC-signed, task-bound, expiring, and single-use.
- External tool traces can require HMAC signatures.
- Evidence IDs, citations, trust, claim coverage, tool success, output text,
  and artifact hashes receive deterministic checks.
- Evidence is scanned for common prompt-injection patterns before generation.
- A genuinely different verifier model is required by default.
- Audit events avoid raw prompts, tokens, and secrets.
- Verified memory is deduplicated and retains task provenance.
- Provider requests use bounded retries and sanitized errors.

## Install

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
truthgate-api
```

Open `http://127.0.0.1:8787/docs`. All `/v1/*` routes require:

```text
Authorization: Bearer <TRUTHGATE_API_KEY>
```

Production startup rejects the included development secrets.

## Hermes MCP integration

TruthGate exposes three narrow MCP tools:

- `truthgate_preflight`
- `truthgate_verify`
- `truthgate_authorize`

Use `integrations/hermes/config.example.yaml` to configure the stdio server in
`~/.hermes/config.yaml`, then run `/reload-mcp` in Hermes. Copy the companion
`integrations/hermes/SKILL.md` into your Hermes skills directory if you want
Hermes to follow the gate workflow consistently.

## Human approval

Preflight returns `task_id` and `task_digest`. A human can issue a short-lived
approval:

```bash
truthgate approve \
  --task-id TASK_ID \
  --task-digest TASK_DIGEST \
  --risk-level high
```

The token does not authorize a different task contract and cannot be consumed
twice.

## Deterministic rules

Requests can attach server-validated rules:

- `evidence_exists`
- `tool_succeeded`
- `output_contains`
- `artifact_sha256`

Model verification is never enough by itself. A final result is `verified` only
when the independent verifier and all deterministic gates pass.

## API

- `GET /health`
- `POST /v1/preflight`
- `POST /v1/verify`
- `POST /v1/run`
- `POST /v1/authorize`
- `GET /v1/memory`
- `GET /v1/audit/{task_id}`

## Hard limitation

MCP cannot intercept every Hermes built-in tool result. Signed traces require a
trusted host wrapper or a native Hermes tool-result hook. Without that hook,
TruthGate should verify knowledge work and explicit evidence, but must not claim
cryptographic proof of every action Hermes performs.