docs: MkDocs setup for tests.agentrust-io.com

.github/workflows/docs.yml

@@ -0,0 +1,66 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "requirements-docs.txt"
+      - "README.md"
+      - "CHANGELOG.md"
+      - "CONTRIBUTING.md"
+      - "CNAME"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Build and deploy docs
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install docs dependencies
+        run: |
+          pip install -r requirements-docs.txt
+          pip install -e "."
+
+      - name: Configure git for gh-deploy
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Assemble docs build directory
+        run: |
+          BUILD=.docs_build
+          mkdir -p $BUILD
+
+          if [ -d docs ]; then cp -r docs $BUILD/docs; fi
+
+          for fname in README.md CHANGELOG.md CONTRIBUTING.md CNAME; do
+            if [ -f "$fname" ]; then cp "$fname" "$BUILD/$fname"; fi
+          done
+
+          echo "Build dir contains $(find $BUILD -type f | wc -l) files"
+
+      - name: Generate build config
+        run: |
+          sed 's|^docs_dir: \.$|docs_dir: .docs_build|' mkdocs.yml > .mkdocs_build.yml
+
+      - name: Build and deploy to GitHub Pages
+        run: mkdocs gh-deploy --force --clean --config-file .mkdocs_build.yml

CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## v0.2.0 — 2026-06-19
+
+- DID subject support: `subject` now accepts `did:` URIs in addition to `spiffe://`.
+- Embedded signature verification: plain TRACE records signed with `agentrust-trace sign_record()` are now cryptographically verified at all levels.
+- SLSA Level 0: `build_provenance.slsa_level: 0` is now valid for software-only / development records.
+- Software-only platform: `runtime.platform: "software-only"` accepted at Level 0.
+- Private key leak detection: TR-SIG now fails records that embed a private key (`d` member) in `cnf.jwk`.
+
+## v0.1.0 — 2026-05-01
+
+- Initial release with 7 test modules: TR-ENV, TR-SIG, TR-RTE, TR-POL, TR-TXN, TR-ANC, TR-SCA.
+- Conformance levels 0, 1, 2.

CNAME

@@ -0,0 +1 @@
+tests.agentrust-io.com

docs/error-codes.md

@@ -0,0 +1,56 @@
+# Error Codes
+
+All TRACE test failures emit a structured error code of the form `TR-<MODULE>-<NNN>`.
+
+## TR-ENV — Envelope
+
+| Code | Description |
+|------|-------------|
+| TR-ENV-001 | Missing or invalid `eat_profile` URI |
+| TR-ENV-002 | `iat` is missing, not an integer, or out of range |
+| TR-ENV-003 | `subject` does not match SPIFFE URI or DID pattern |
+| TR-ENV-004 | One or more required fields are absent |
+
+## TR-SIG — Signature
+
+| Code | Description |
+|------|-------------|
+| TR-SIG-001 | Signature algorithm is not Ed25519 |
+| TR-SIG-002 | `cnf.jwk` missing or malformed |
+| TR-SIG-003 | Signature verification failed |
+| TR-SIG-004 | Private key material (`d` member) found in `cnf.jwk` |
+
+## TR-RTE — Runtime
+
+| Code | Description |
+|------|-------------|
+| TR-RTE-001 | `runtime.platform` is not a recognised TEE enum value |
+| TR-RTE-002 | `runtime.measurement` is not a valid `sha256:` digest |
+
+## TR-POL — Policy
+
+| Code | Description |
+|------|-------------|
+| TR-POL-001 | `policy.bundle_hash` is not a valid `sha256:` digest |
+| TR-POL-002 | `policy.enforcement_mode` is not `enforce` or `monitor` |
+
+## TR-TXN — Transcript
+
+| Code | Description |
+|------|-------------|
+| TR-TXN-001 | `tool_transcript.hash` is not a valid `sha256:` digest |
+| TR-TXN-002 | `tool_transcript.call_count` is negative or not an integer |
+
+## TR-ANC — Transparency
+
+| Code | Description |
+|------|-------------|
+| TR-ANC-001 | `transparency` field missing or empty |
+| TR-ANC-002 | `transparency` URI does not use `https://` scheme |
+
+## TR-SCA — Provenance
+
+| Code | Description |
+|------|-------------|
+| TR-SCA-001 | `build_provenance.slsa_level` is not 0–4 |
+| TR-SCA-002 | `build_provenance.digest` is not a valid `sha256:` digest |

docs/levels.md

@@ -0,0 +1,17 @@
+# Conformance Levels
+
+TRACE defines three conformance levels. Higher levels require all lower-level modules plus additional ones.
+
+| Level | Required Modules | Use Case |
+|-------|-----------------|----------|
+| **0** | TR-ENV, TR-SIG, TR-POL | Software-only development and staging |
+| **1** | Level 0 + TR-RTE, TR-SCA | Production TEE-attested records |
+| **2** | Level 1 + TR-TXN, TR-ANC | Full records with transparency anchoring |
+
+## Choosing a level
+
+- Use **Level 0** during development. Records can use `runtime.platform: "software-only"` and `build_provenance.slsa_level: 0`.
+- Use **Level 1** for production deployments in a TEE (AMD SEV-SNP, Intel TDX, NVIDIA H100).
+- Use **Level 2** when you need an auditable, tamper-evident log with a SCITT transparency service.
+
+The certification program (launching 2027) will require Level 1 at minimum.

docs/modules.md

@@ -0,0 +1,13 @@
+# Test Modules
+
+The TRACE conformance suite is divided into seven modules. Each module maps to a section of the TRACE specification.
+
+| Module | ID Prefix | Spec Section | What It Tests |
+|--------|-----------|--------------|---------------|
+| [Envelope](modules/tr-env.md) | TR-ENV | §3.2 | EAT envelope structure, `eat_profile` URI, required fields, `iat` validity |
+| [Signature](modules/tr-sig.md) | TR-SIG | §3.2.1 | Algorithm conformance (Ed25519), key binding, private key leak detection |
+| [Runtime](modules/tr-rte.md) | TR-RTE | §3.1 | TEE platform enum, measurement format, RIM URI resolution |
+| [Policy](modules/tr-pol.md) | TR-POL | §3.1 | Policy bundle hash format, enforcement mode values |
+| [Transcript](modules/tr-txn.md) | TR-TXN | §3.1 | Tool-call transcript hash binding |
+| [Transparency](modules/tr-anc.md) | TR-ANC | §3.2 | SCITT receipt URI format, inclusion proof structure |
+| [Provenance](modules/tr-sca.md) | TR-SCA | §3.1 | SLSA provenance level, builder URI, digest format |

docs/modules/tr-anc.md

@@ -0,0 +1,10 @@
+# TR-ANC — Transparency
+
+Tests transparency anchoring via SCITT.
+
+## Required at Level 2+
+
+| Test ID | Description |
+|---------|-------------|
+| TR-ANC-001 | `transparency` is a non-empty URI |
+| TR-ANC-002 | URI scheme is `https://` |

docs/modules/tr-env.md

@@ -0,0 +1,12 @@
+# TR-ENV — Envelope
+
+Tests the top-level EAT envelope structure of a TRACE Trust Record.
+
+## Required at Level 0+
+
+| Test ID | Description | Positive Case | Negative Case |
+|---------|-------------|---------------|---------------|
+| TR-ENV-001 | `eat_profile` present and correct URI | `tag:agentrust.io,2026:trace-v0.1` | missing or wrong |
+| TR-ENV-002 | `iat` is a valid Unix timestamp | integer, reasonable range | string, future date |
+| TR-ENV-003 | `subject` matches SPIFFE URI or DID | `spiffe://trust.example/agent/x` or `did:key:z6Mk...` | bare string |
+| TR-ENV-004 | Required fields present | all of: eat_profile, iat, subject, model, runtime, policy, data_class, build_provenance, appraisal | missing any |

docs/modules/tr-pol.md

@@ -0,0 +1,10 @@
+# TR-POL — Policy
+
+Tests Cedar policy bundle binding.
+
+## Required at Level 0+
+
+| Test ID | Description |
+|---------|-------------|
+| TR-POL-001 | `policy.bundle_hash` is a valid `sha256:` digest |
+| TR-POL-002 | `policy.enforcement_mode` is `enforce` or `monitor` |

docs/modules/tr-rte.md

@@ -0,0 +1,11 @@
+# TR-RTE — Runtime
+
+Tests TEE platform attestation in the `runtime` field.
+
+## Required at Level 1+
+
+| Test ID | Description |
+|---------|-------------|
+| TR-RTE-001 | `runtime.platform` is a known TEE enum value |
+| TR-RTE-002 | `runtime.measurement` is a valid `sha256:` digest |
+| TR-RTE-003 | RIM URI (if present) resolves to a valid reference image |

docs/modules/tr-sca.md

@@ -0,0 +1,10 @@
+# TR-SCA — Provenance
+
+Tests SLSA build provenance.
+
+## Required at Level 1+
+
+| Test ID | Description |
+|---------|-------------|
+| TR-SCA-001 | `build_provenance.slsa_level` is 0–4 |
+| TR-SCA-002 | `build_provenance.digest` is a valid `sha256:` digest |

docs/modules/tr-sig.md

@@ -0,0 +1,12 @@
+# TR-SIG — Signature
+
+Tests Ed25519 signature binding on the TRACE Trust Record.
+
+## Required at Level 0+
+
+| Test ID | Description |
+|---------|-------------|
+| TR-SIG-001 | Signature algorithm is Ed25519 (OKP crv=Ed25519) |
+| TR-SIG-002 | `cnf.jwk` present and carries the public key |
+| TR-SIG-003 | Signature verifies over the canonical record bytes (RFC 8785 JCS) |
+| TR-SIG-004 | `cnf.jwk` does not contain private key material (`d` member absent) |

docs/modules/tr-txn.md

@@ -0,0 +1,10 @@
+# TR-TXN — Transcript
+
+Tests tool-call transcript binding.
+
+## Required at Level 2+
+
+| Test ID | Description |
+|---------|-------------|
+| TR-TXN-001 | `tool_transcript.hash` is a valid `sha256:` digest |
+| TR-TXN-002 | `tool_transcript.call_count` is a non-negative integer |

docs/quickstart.md

@@ -0,0 +1,43 @@
+# Quick Start
+
+## Install
+
+```bash
+pip install agentrust-trace-tests
+```
+
+## Run against a Trust Record
+
+```bash
+trace-tests verify --record path/to/trust-record.json --level 1
+```
+
+Level 0 is software-only (development). Level 1 requires TEE attestation. Level 2 adds transparency anchoring.
+
+## Run all levels
+
+```bash
+trace-tests verify --record trust-record.json --level 0
+trace-tests verify --record trust-record.json --level 1
+trace-tests verify --record trust-record.json --level 2
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | All required tests passed |
+| 1    | One or more tests failed |
+| 2    | Record could not be loaded |
+
+## Output format
+
+Each test emits a structured result:
+
+```
+TR-ENV-001  PASS  EAT envelope: eat_profile present
+TR-SIG-001  PASS  Signature: Ed25519 algorithm confirmed
+TR-RTE-001  FAIL  Runtime: TEE measurement missing (required at level 1)
+```
+
+Error codes follow the form `TR-<MODULE>-<NNN>`.

docs/stylesheets/extra.css

@@ -0,0 +1,9 @@
+/* AgentTrust brand — matches trace-spec palette */
+[data-md-color-scheme="slate"] {
+  --md-primary-fg-color: #0ea5e9;
+  --md-accent-fg-color: #38bdf8;
+}
+[data-md-color-scheme="default"] {
+  --md-primary-fg-color: #0284c7;
+  --md-accent-fg-color: #0ea5e9;
+}