# Agent Trust Manifest

> **⚠️ Early-stage / alpha software.** Agent Trust is under active development. The manifest returns advisory receipts — the application owns enforcement. Not yet published on PyPI; install from GitHub source. See [Current Limitations](#current-limitations).

## What is this?

Agent Trust is a **local advisory receipt library** for AI-agent prompts, actions, scopes, and external tool descriptors. It generates a **projection of live enforcement configuration** — returning deterministic allow/review/quarantine decisions for each checked item.

The manifest is **generated from live enforcement configuration** and carries a **self-hash (`sha256`)** over the canonical JSON. Third parties can regenerate the manifest from the same source and compare.

**What Agent Trust does:**
- Generates a manifest from live enforcement objects (tool allowlists, boundary catalogs, protected paths)
- Returns advisory receipts: allow / review / quarantine per checked item
- Provides a self-hash (`sha256`) and a drift test for third-party regeneration

**What Agent Trust does NOT do:**
- Does not intercept LLM calls or execute tools
- Does not create a sandbox or runtime enforcement layer
- Does not replace application-level enforcement — the application owns enforcement

This architecture follows Pawel Twardziak's advice (LangChain Forum, July 2026): "The manifest should be generated from the enforced config — a projection of runtime-enforced boundaries, not a promise the agent makes."

## Where to find the manifest

The live manifest is available at:

- **API endpoint:** `GET /api/agent-trust/manifest` (on the running Ouroboros server)
- **Static copy:** `docs/agent-trust/manifest.json` (in this repository), with `manifest.json.sig` and `signing_key.pub` next to it
- **Landing page:** `docs/agent-trust/index.html` — interactive viewer that fetches and displays the manifest

## How to verify the manifest

### Option 0: Signature (authenticity)

`manifest.json.sig` is an OpenSSH Ed25519 signature over the exact bytes of `manifest.json`, produced by the **root-owned promote service** after every healthy deploy. The agent runs unprivileged and can neither read nor replace the key, so a valid signature means the file came out of Rain's deploy pipeline — not out of the agent's own hands.

```bash
B=https://rain-ouroboros.github.io/rain-site/agent-trust
curl -sSO $B/manifest.json -O $B/manifest.json.sig -O $B/signing_key.pub -O $B/verify_manifest.py
python3 verify_manifest.py          # VERIFIED / REJECTED (wraps `ssh-keygen -Y verify`)
```

Key fingerprint to pin: `SHA256:8zhBfyAfhCXlkxITYlA3cJ/oYF734JIJ5EA7qgr8dls`. The publisher refuses to ship a `.sig` that does not verify against the manifest next to it (`signature_mismatch` in the publish log).

### Option 1: Drift test (canonical)

```bash
python3 -m pytest tests/test_agent_trust_manifest_drift.py -q
```

This test regenerates the manifest from the live generator and asserts that
the committed `docs/agent-trust/manifest.json` matches (modulo volatile
fields such as timestamps and git commit).

### Option 2: Manual regeneration

```bash
python3 -m ouroboros.agent_trust_manifest > /tmp/manifest.json
diff <(python3 -m ouroboros.agent_trust_manifest) docs/agent-trust/manifest.json
```

The manifest is a projection of live enforcement configuration; any drift
means the committed snapshot is stale and must be regenerated.

### Option 3: Landing page

Open `docs/agent-trust/index.html` in a browser. The page:
- Fetches `manifest.json`
- Displays the manifest with syntax highlighting
- Lists checked tools, hard gates, and boundary catalog

## Manifest structure

```json
{
  "contract_version": "agent-trust-manifest-v1",
  "generated_at": "ISO8601",
  "generator": "ouroboros.agent_trust_manifest.build_runtime_manifest",
  "git": {"commit": "...", "version": "..."},
  "effective_enforcement_mode": "enforce",
  "enforcement_mode_source": "env:OUROBOROS_AGENT_TRUST_ENFORCE",
  "safety_prompt_sha256": "...",
  "safety_py_sha256": "...",
  "hard_gate_ids": [...],
  "hard_gate_count": 0,
  "hard_gates_enforced": true,
  "tools": {...},
  "boundaries": {...},
  "boundary_count": 0,
  "os_enforced": [...],
  "tool_result_scanning": false,
  "tool_result_scanning_note": "...",
  "sha256": "..."
}
```

The manifest is a **projection of live enforcement configuration** (CHECKED_TOOLS,
_BOUNDARIES, effective env mode, OS state) — it is regenerated by
`ouroboros.agent_trust_manifest.build_manifest_json()` and committed as a
build-time snapshot. A drift test (`tests/test_agent_trust_manifest_drift.py`)
fails when the committed `manifest.json` diverges from the generator output.

## Key architectural decisions

1. **Generated from enforced config, not self-description.** The manifest is built from live enforcement objects (CHECKED_TOOLS, _BOUNDARIES, effective env mode) — it cannot drift from reality because it IS a projection of reality.

2. **Signed by the deploy pipeline, not by the agent.** The Ed25519 key is root-only on the deploy host; the promote service signs the manifest only after the release passed the test gate and came up healthy. **Self-hash for third-party regeneration.** The manifest carries a `sha256` self-hash over the canonical (sorted-key) JSON, so any third party can regenerate the manifest from the same source and detect drift deterministically.

3. **Advisory receipts, application-owned enforcement.** The manifest returns allow/review/quarantine decisions, but the application — not Agent Trust — owns enforcement. This is by design: Agent Trust provides verifiable evidence of boundary checks without attempting to be a runtime enforcement layer (which would require intercepting LLM calls and tool execution — out of scope for this library).

## Current Limitations

- **Advisory only.** Agent Trust returns receipts (allow/review/quarantine) — it does not enforce them. The application owns enforcement.
- **Alpha/early-stage.** The API and manifest format may change. Not yet production-hardened.
- **Not on PyPI.** Install from GitHub source: `pip install "agent-trust @ git+https://github.com/Rain-ouroboros/agent-trust.git"`
- **No LLM interception.** Agent Trust does not intercept LLM calls or execute tools — it operates on the configuration layer.
- **No sandbox.** Agent Trust is not a sandbox or container runtime.

## For third-party verification

If you are building agent-to-agent trust and want to verify an Ouroboros agent's manifest:

1. Fetch the published snapshot, `manifest.json.sig` and `signing_key.pub`; verify the signature (Option 0). Pin the key fingerprint.
2. Regenerate it from live enforcement configuration and compare (the `sha256` self-hash and the drift test make this deterministic)
3. Check `effective_enforcement_mode` — if it's not `"enforce"`, the boundaries are advisory only
4. Review `boundaries`, `tools`, `os_enforced`, and `hard_gate_ids` to understand what is actually blocked

## Related

- **BIBLE.md** — Rain's Constitution (Principle 0: Agency, Principle 2: Self-Creation)
- **agent_trust_boundaries.py** — boundary catalog and enforcement logic
- **agent_trust_manifest.py** — manifest generation from live enforcement config
- **tools/verify_agent_trust_manifest.py** — verification tool