# Veritas — Integrity & Provenance for Agents

Veritas lets any AI agent prove its outputs have not been tampered with, and
trace where a piece of content came from. Call `/attest` to get a signed,
content-addressed receipt for an output; call `/verify` to check that content
still matches its receipt; call `/chain` and `/lineage` to record and walk
provenance across agents.

No API key or auth is required. Every response is JSON. Signatures are Ed25519
over a canonical (sorted-key) statement, so anyone holding the statement and the
public key can re-verify offline.

**Base URL:** `https://veritas-attest.vercel.app`

## 1. Health — call this first
```
GET https://veritas-attest.vercel.app/health
```
Returns `{"status":"ok","algorithm":"ed25519","public_key":"<hex>","attestations":<n>}`.
If `status` is `ok`, the service is up.

## 2. Attest an output — get a receipt
```
POST https://veritas-attest.vercel.app/attest
content-type: application/json

{ "content": <any JSON value or string>, "kind": "output", "agent": "your-agent-id" }
```
Returns:
```
{ "attestation_id": "sha256:…", "cid": "sha256:…",
  "statement": { "v":"veritas/1", "cid":"sha256:…", "kind":"output", "agent":"your-agent-id", "seq":0, "parents":[], "context":{} },
  "signature": "<hex>", "public_key": "<hex>" }
```
Store the `attestation_id` (or the whole object) next to your output — it is the receipt.

curl:
```
curl -s https://veritas-attest.vercel.app/attest -H 'content-type: application/json' \
  -d '{"content":"The Q3 revenue figure is 4.2M USD.","agent":"analyst-agent"}'
```

## 3. Verify content against a receipt
```
POST https://veritas-attest.vercel.app/verify
content-type: application/json
```
Either supply the stored id plus the content you want to check:
```
{ "attestation_id": "sha256:…", "content": <the content to check> }
```
…or supply a full self-contained bundle (works even if this server never stored it):
```
{ "statement": {…}, "signature": "<hex>", "public_key": "<hex>", "content": <…> }
```
Returns:
```
{ "valid": true, "checks": { "signature_valid": true, "content_matches_cid": true, "known_to_registry": true } }
```
If the content changed by even one byte, `content_matches_cid` and `valid` are `false`.

curl:
```
curl -s https://veritas-attest.vercel.app/verify -H 'content-type: application/json' \
  -d '{"attestation_id":"sha256:…","content":"The Q3 revenue figure is 4.2M USD."}'
```

## 4. Record provenance for derived content
```
POST https://veritas-attest.vercel.app/chain
content-type: application/json

{ "content": <derived output>, "parents": ["sha256:…parent-attestation-id…"], "agent": "editor-agent" }
```
Returns an attestation whose `statement.parents` lists its sources. Unknown parents are rejected with 422.

## 5. Walk the provenance chain
```
GET https://veritas-attest.vercel.app/lineage/{attestation_id}
```
Returns `{ "root": "sha256:…", "nodes": [...], "edges": [{"child":"…","parent":"…"}] }`.

## 6. Fetch an existing receipt
```
GET https://veritas-attest.vercel.app/attest/{attestation_id}
```

## Typical multi-agent flow
1. A producer agent finishes an output → `POST /attest` → keeps `attestation_id` with the output.
2. A consumer agent receives `(output, attestation_id)` → `POST /verify` with the output → trusts it only if `valid` is true.
3. If the consumer transforms it and passes it on → `POST /chain` with `parents=[attestation_id]`.
4. An auditor → `GET /lineage/{id}` to reconstruct the full chain of custody.