Docs: optional TOA verify for runtime health / promote

README.md

@@ -97,6 +97,7 @@ Deploy, run, and manage MCP servers locally or in a Kubernetes cluster with secu
 - Proxy remote MCP servers securely for unified management
 - Kubernetes Operator for fleet and resource management
 - Leverage OpenTelemetry and Prometheus for monitoring and audit logging
+- Optional offline [TOA](https://github.com/Carmel-Labs-Inc/toa) verify before promote ([docs](docs/toa-optional-runtime-gate.md))
 
 ### 💻 Interfaces
 

docs/README.md

@@ -38,6 +38,7 @@ For information on the ToolHive Operator, see the
 - **[Runtime Implementation Guide](runtime-implementation-guide.md)** - Guide for implementing new container runtime support
 - **[Runtime Version Customization](runtime-version-customization.md)** - Customizing base images and packages for protocol-scheme builds
 - **[Remote MCP Authentication](remote-mcp-authentication.md)** - How ToolHive authenticates to remote MCP servers
+- **[Optional TOA runtime gate](toa-optional-runtime-gate.md)** - Offline delivery-evidence verify before promote / runtime enable
 - **[Server API Documentation](server/README.md)** - How the OpenAPI docs for the `thv serve` REST API are generated and served
 
 ### Operator Documentation

docs/registry/heuristics.md

@@ -17,6 +17,9 @@ This document defines the criteria for including MCP (Model Context Protocol) se
 - Pinned dependencies and GitHub Actions
 - Published Software Bill of Materials (SBOMs)
 
+### Optional delivery evidence (not a registry inclusion requirement)
+- Offline [Tool Outcome Attestation](https://github.com/Carmel-Labs-Inc/toa) (`toa/0.1`) verify before promote / runtime enable. Separate from Sigstore provenance. See [Optional TOA runtime gate](../toa-optional-runtime-gate.md).
+
 ### Continuous Integration
 - Automated dependency updates (Dependabot, Renovate, etc.)
 - Automated security scanning

docs/toa-optional-runtime-gate.md

@@ -0,0 +1,41 @@
+# Optional TOA verify for runtime health / promote
+
+ToolHive runs MCP servers in isolated containers, applies identity and access
+policy, and verifies software provenance (Sigstore / attestations) for registry
+entries. That answers secure run and supply-chain trust. It does not prove that
+a tool recently delivered a real result under an outside probe.
+
+[TOA](https://github.com/Carmel-Labs-Inc/toa) (`toa/0.1`) is an Apache-2.0 signed
+JSON evidence format for MCP tool delivery (reach, invoke, functional, shape,
+and related layers). It is not a wire protocol. It is not meant to run on every
+live `tools/call`.
+
+## Suggested fit
+
+Optional, off by default. Before promoting a workload to a production group, or
+as a CI check after `thv` run / health, require a recent attestation and verify
+it offline with a pinned emitter public key.
+
+- Any party can emit if they sign the schema.
+- AgentStatus is one optional emitter.
+- No AgentStatus account is required to verify.
+
+```yaml
+      # After your ToolHive deploy / health checks.
+      - name: Verify tool delivery attestation
+        if: hashFiles('toa.json') != ''
+        run: |
+          pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@99e2690fec24a5290d9542e58383a8bf753e8b74#subdirectory=python"
+          toa-verify toa.json --require-emitter agentstatus --require-layer functional=pass --max-age 7d
+```
+
+Copy-paste workflow: [`examples/toa-after-runtime.yml`](../examples/toa-after-runtime.yml).
+
+## Out of scope
+
+- Replacing Sigstore provenance, Cedar authz, or the runtime hot path
+- Signing every production `tools/call`
+- Changing ToolHive runtime code
+
+Related: [Registry inclusion heuristics](registry/heuristics.md) (supply-chain)
+vs TOA (delivery evidence).

examples/toa-after-runtime.yml

@@ -0,0 +1,23 @@
+# Example only. Copy into your org workflow as needed.
+name: ToolHive runtime and optional TOA
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - "examples/**"
+      - "toa.json"
+
+jobs:
+  toa:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Your thv run / health / operator checks go here.
+
+      - name: Verify tool delivery attestation
+        if: hashFiles('toa.json') != ''
+        run: |
+          pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@99e2690fec24a5290d9542e58383a8bf753e8b74#subdirectory=python"
+          toa-verify toa.json --require-emitter agentstatus --require-layer functional=pass --max-age 7d