agent-manifest 0.1.0__tar.gz

agent_manifest-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: agent-manifest
+Version: 0.1.0
+Summary: Agent Manifest SDK — cryptographically anchor all 10 artifacts defining an AI agent at deployment
+Project-URL: Homepage, https://github.com/agentrust-io/agent-manifest
+Project-URL: Repository, https://github.com/agentrust-io/agent-manifest
+Project-URL: Documentation, https://github.com/agentrust-io/agent-manifest/tree/main/spec
+Project-URL: Bug Tracker, https://github.com/agentrust-io/agent-manifest/issues
+Project-URL: Changelog, https://github.com/agentrust-io/agent-manifest/releases
+Author-email: Imran Siddique <maintainers@agentrust.io>
+License: Apache-2.0
+Keywords: agent-manifest,ai-agents,attestation,confidential-computing,governance,hardware-attestation,mcp,pydantic,tee,trust
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cryptography<50,>=42
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: all
+Requires-Dist: click>=8.1; extra == 'all'
+Requires-Dist: fastapi>=0.111; extra == 'all'
+Requires-Dist: httpx>=0.27; extra == 'all'
+Requires-Dist: pyoqs>=0.10; extra == 'all'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'all'
+Provides-Extra: cli
+Requires-Dist: click>=8.1; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: bandit[toml]>=1.7; extra == 'dev'
+Requires-Dist: click>=8.1; extra == 'dev'
+Requires-Dist: fastapi>=0.111; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: jcs>=0.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'dev'
+Provides-Extra: pq
+Requires-Dist: pyoqs>=0.10; extra == 'pq'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.111; extra == 'server'
+Requires-Dist: httpx>=0.27; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'server'
+Description-Content-Type: text/markdown
+
+# agent-manifest
+
+**Cryptographically anchor all 10 artifacts defining an AI agent at deployment.**
+
+The Agent Manifest SDK implements the Agent Manifest Specification v0.1  -  a hardware-attestable document that binds every artifact defining an agent's behavior (system prompt, policy bundle, tool schemas, model identity, RAG corpus, memory state, audit chain, delegation chain, supply chain, and human approvals) into a single tamper-evident identity primitive.
+
+```
+pip install agent-manifest
+```
+
+## Why
+
+A signed JWT proves who called an API. An Agent Manifest proves who the agent **was**, what it was **allowed to do**, how it was **built**, what it **decided**, who **approved** it, and whether any of that changed between approval and execution.
+
+```python
+from agent_manifest import (
+    Manifest, ArtifactBindings,
+    SystemPromptBinding, PolicyBundleBinding, ModelIdentityBinding,
+    CryptoProfile, DeploymentType, EnforcementMode, PolicyLanguage,
+    generate_ed25519, Ed25519Signer,
+)
+from agent_manifest._types import HashValue, ManifestId
+from datetime import datetime, timedelta, timezone
+
+now = datetime.now(timezone.utc)
+
+manifest = Manifest(
+    manifest_id=ManifestId("018f4a3b-2c1d-7e5f-a8b9-0d1e2f3a4b5c"),
+    agent_id="spiffe://trust.example/agent/kyc/prod",
+    issued_at=now,
+    expires_at=now + timedelta(days=90),
+    issuer="spiffe://trust.example/signing-authority",
+    crypto_profile=CryptoProfile.standard,
+    artifacts=ArtifactBindings(
+        system_prompt=SystemPromptBinding(
+            hash=HashValue("sha256:" + "a" * 64),
+            bound_at=now,
+        ),
+        policy_bundle=PolicyBundleBinding(
+            hash=HashValue("sha256:" + "b" * 64),
+            policy_language=PolicyLanguage.cedar,
+            version="1.0.0",
+            enforcement_mode=EnforcementMode.enforce,
+            bound_at=now,
+        ),
+        model_identity=ModelIdentityBinding(
+            provider="anthropic",
+            model_id="claude-sonnet-4-6",
+            version="20251001",
+            deployment_type=DeploymentType.api,
+            bound_at=now,
+        ),
+    ),
+)
+
+keypair = generate_ed25519()
+signer = Ed25519Signer(keypair)
+sig_block = signer.sign(manifest.model_dump(mode="json", by_alias=True))
+print(sig_block["algorithm"])   # Ed25519
+print(sig_block["key_id"])      # sha256:<hex>
+```
+
+## The 10 Attested Artifacts
+
+| # | Artifact | What it proves |
+|---|----------|---------------|
+| 1 | System Prompt | The exact prompt that defines the agent's persona and safety constraints |
+| 2 | Policy Bundle | The Cedar/Rego/YAML governance rules that were in force |
+| 3 | Tool Manifest | Every tool schema and description the agent was authorized to call |
+| 4 | Model Identity | Which model and version ran (binary hash for local, version for API) |
+| 5 | RAG Corpus | The knowledge base the agent was grounded on (Merkle root) |
+| 6 | Memory Baseline | Approved agent memory state with TTL-based re-approval |
+| 7 | Decision Trace | Hardware-signed audit chain root for all agent decisions |
+| 8 | A2A Delegation | Signed delegation chain from human principal to current agent |
+| 9 | Supply Chain | Container digest, SLSA provenance, SBOM, MCP server supply chain |
+| 10 | HITL Approvals | Hardware-signed human oversight records (EU AI Act Art. 14) |
+
+## Hardware Attestation
+
+```python
+from agent_manifest._auto_provider import select_provider
+
+# auto-selects: SEV-SNP → TDX → TPM → software  (OPAQUE is explicit opt-in via OPAQUE_ATTESTATION_URL)
+provider = select_provider(level=1)   # Level 1+ requires hardware
+provider.extend_manifest_hash(manifest_dict)
+report = provider.get_attestation_report()
+# report.platform: "amd-sev-snp" | "intel-tdx" | "tpm" | "opaque" | "software"
+```
+
+| Provider | Hardware | Level | Install |
+|----------|----------|-------|---------|
+| `TPMProvider` | TPM 2.0 / AWS Nitro | 1 | `apt install tpm2-tools` |
+| `SEVSNPProvider` | AMD SEV-SNP | 2 | Needs `/dev/sev-guest` |
+| `TDXProvider` | Intel TDX | 2 | Needs `/dev/tdx-guest` |
+| `OPAQUEProvider` | Opaque Runtime | 3 | Set `OPAQUE_ATTESTATION_URL` |
+
+## Verification
+
+```python
+from agent_manifest._verify import verify_manifest, VerificationContext, RevocationStore
+
+result = verify_manifest(
+    manifest_dict,
+    VerificationContext(
+        system_prompt_hash="sha256:...",
+        policy_bundle_hash="sha256:...",
+        enforce_hitl=True,
+    ),
+    RevocationStore(),
+)
+print(result.result)   # VALID | MISMATCH | EXPIRED | REVOKED | ...
+```
+
+## CLI
+
+```bash
+pip install "agent-manifest[cli]"
+
+manifest keygen -d ./keys/
+manifest create config.json -o draft.json
+manifest sign draft.json --key keys/private.hex -o signed.json
+manifest attest signed.json --provider auto --level 1 -o attested.json
+manifest verify attested.json
+manifest revoke <manifest-id> --reason "key compromise" --revoked-by security@example.com
+```
+
+## Cryptography
+
+- **Standard profile**: Ed25519 (RFC 8032), SHA-256, RFC 8785 canonical JSON
+- **Post-quantum profile**: ML-DSA-65 (NIST FIPS 204), SHAKE-256  -  `pip install "agent-manifest[pq]"`
+- **Hybrid**: Both signatures required, identical pre-image
+- **Transparency**: Rekor/Sigstore integration for non-repudiation
+
+## Specification
+
+The full Agent Manifest Specification v0.1 is at [`spec/agent-manifest-spec-v0.1.md`](https://github.com/agentrust-io/agent-manifest/blob/main/spec/agent-manifest-spec-v0.1.md).
+
+Being submitted to the [Agentic AI Foundation (AAIF)](https://agenticai.foundation) under the Linux Foundation alongside AGT.
+
+## License
+
+Apache 2.0

agent_manifest-0.1.0/README.md

@@ -0,0 +1,142 @@
+# agent-manifest
+
+**Cryptographically anchor all 10 artifacts defining an AI agent at deployment.**
+
+The Agent Manifest SDK implements the Agent Manifest Specification v0.1  -  a hardware-attestable document that binds every artifact defining an agent's behavior (system prompt, policy bundle, tool schemas, model identity, RAG corpus, memory state, audit chain, delegation chain, supply chain, and human approvals) into a single tamper-evident identity primitive.
+
+```
+pip install agent-manifest
+```
+
+## Why
+
+A signed JWT proves who called an API. An Agent Manifest proves who the agent **was**, what it was **allowed to do**, how it was **built**, what it **decided**, who **approved** it, and whether any of that changed between approval and execution.
+
+```python
+from agent_manifest import (
+    Manifest, ArtifactBindings,
+    SystemPromptBinding, PolicyBundleBinding, ModelIdentityBinding,
+    CryptoProfile, DeploymentType, EnforcementMode, PolicyLanguage,
+    generate_ed25519, Ed25519Signer,
+)
+from agent_manifest._types import HashValue, ManifestId
+from datetime import datetime, timedelta, timezone
+
+now = datetime.now(timezone.utc)
+
+manifest = Manifest(
+    manifest_id=ManifestId("018f4a3b-2c1d-7e5f-a8b9-0d1e2f3a4b5c"),
+    agent_id="spiffe://trust.example/agent/kyc/prod",
+    issued_at=now,
+    expires_at=now + timedelta(days=90),
+    issuer="spiffe://trust.example/signing-authority",
+    crypto_profile=CryptoProfile.standard,
+    artifacts=ArtifactBindings(
+        system_prompt=SystemPromptBinding(
+            hash=HashValue("sha256:" + "a" * 64),
+            bound_at=now,
+        ),
+        policy_bundle=PolicyBundleBinding(
+            hash=HashValue("sha256:" + "b" * 64),
+            policy_language=PolicyLanguage.cedar,
+            version="1.0.0",
+            enforcement_mode=EnforcementMode.enforce,
+            bound_at=now,
+        ),
+        model_identity=ModelIdentityBinding(
+            provider="anthropic",
+            model_id="claude-sonnet-4-6",
+            version="20251001",
+            deployment_type=DeploymentType.api,
+            bound_at=now,
+        ),
+    ),
+)
+
+keypair = generate_ed25519()
+signer = Ed25519Signer(keypair)
+sig_block = signer.sign(manifest.model_dump(mode="json", by_alias=True))
+print(sig_block["algorithm"])   # Ed25519
+print(sig_block["key_id"])      # sha256:<hex>
+```
+
+## The 10 Attested Artifacts
+
+| # | Artifact | What it proves |
+|---|----------|---------------|
+| 1 | System Prompt | The exact prompt that defines the agent's persona and safety constraints |
+| 2 | Policy Bundle | The Cedar/Rego/YAML governance rules that were in force |
+| 3 | Tool Manifest | Every tool schema and description the agent was authorized to call |
+| 4 | Model Identity | Which model and version ran (binary hash for local, version for API) |
+| 5 | RAG Corpus | The knowledge base the agent was grounded on (Merkle root) |
+| 6 | Memory Baseline | Approved agent memory state with TTL-based re-approval |
+| 7 | Decision Trace | Hardware-signed audit chain root for all agent decisions |
+| 8 | A2A Delegation | Signed delegation chain from human principal to current agent |
+| 9 | Supply Chain | Container digest, SLSA provenance, SBOM, MCP server supply chain |
+| 10 | HITL Approvals | Hardware-signed human oversight records (EU AI Act Art. 14) |
+
+## Hardware Attestation
+
+```python
+from agent_manifest._auto_provider import select_provider
+
+# auto-selects: SEV-SNP → TDX → TPM → software  (OPAQUE is explicit opt-in via OPAQUE_ATTESTATION_URL)
+provider = select_provider(level=1)   # Level 1+ requires hardware
+provider.extend_manifest_hash(manifest_dict)
+report = provider.get_attestation_report()
+# report.platform: "amd-sev-snp" | "intel-tdx" | "tpm" | "opaque" | "software"
+```
+
+| Provider | Hardware | Level | Install |
+|----------|----------|-------|---------|
+| `TPMProvider` | TPM 2.0 / AWS Nitro | 1 | `apt install tpm2-tools` |
+| `SEVSNPProvider` | AMD SEV-SNP | 2 | Needs `/dev/sev-guest` |
+| `TDXProvider` | Intel TDX | 2 | Needs `/dev/tdx-guest` |
+| `OPAQUEProvider` | Opaque Runtime | 3 | Set `OPAQUE_ATTESTATION_URL` |
+
+## Verification
+
+```python
+from agent_manifest._verify import verify_manifest, VerificationContext, RevocationStore
+
+result = verify_manifest(
+    manifest_dict,
+    VerificationContext(
+        system_prompt_hash="sha256:...",
+        policy_bundle_hash="sha256:...",
+        enforce_hitl=True,
+    ),
+    RevocationStore(),
+)
+print(result.result)   # VALID | MISMATCH | EXPIRED | REVOKED | ...
+```
+
+## CLI
+
+```bash
+pip install "agent-manifest[cli]"
+
+manifest keygen -d ./keys/
+manifest create config.json -o draft.json
+manifest sign draft.json --key keys/private.hex -o signed.json
+manifest attest signed.json --provider auto --level 1 -o attested.json
+manifest verify attested.json
+manifest revoke <manifest-id> --reason "key compromise" --revoked-by security@example.com
+```
+
+## Cryptography
+
+- **Standard profile**: Ed25519 (RFC 8032), SHA-256, RFC 8785 canonical JSON
+- **Post-quantum profile**: ML-DSA-65 (NIST FIPS 204), SHAKE-256  -  `pip install "agent-manifest[pq]"`
+- **Hybrid**: Both signatures required, identical pre-image
+- **Transparency**: Rekor/Sigstore integration for non-repudiation
+
+## Specification
+
+The full Agent Manifest Specification v0.1 is at [`spec/agent-manifest-spec-v0.1.md`](https://github.com/agentrust-io/agent-manifest/blob/main/spec/agent-manifest-spec-v0.1.md).
+
+Being submitted to the [Agentic AI Foundation (AAIF)](https://agenticai.foundation) under the Linux Foundation alongside AGT.
+
+## License
+
+Apache 2.0

agent_manifest-0.1.0/pyproject.toml

@@ -0,0 +1,89 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-manifest"
+version = "0.1.0"
+description = "Agent Manifest SDK — cryptographically anchor all 10 artifacts defining an AI agent at deployment"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "Apache-2.0"}
+authors = [{name = "Imran Siddique", email = "maintainers@agentrust.io"}]
+keywords = [
+  "ai-agents", "attestation", "governance", "tee", "confidential-computing",
+  "mcp", "agent-manifest", "trust", "hardware-attestation", "pydantic",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security :: Cryptography",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: System :: Monitoring",
+  "Typing :: Typed",
+]
+dependencies = [
+  "pydantic>=2.7,<3",
+  "cryptography>=42,<50",
+]
+
+[project.optional-dependencies]
+pq      = ["pyoqs>=0.10"]
+server  = ["fastapi>=0.111", "uvicorn[standard]>=0.29", "httpx>=0.27"]
+cli     = ["click>=8.1"]
+all     = ["pyoqs>=0.10", "fastapi>=0.111", "uvicorn[standard]>=0.29", "httpx>=0.27", "click>=8.1"]
+dev     = ["pytest>=8", "pytest-asyncio>=0.23", "pytest-cov>=5", "httpx>=0.27",
+           "jcs>=0.2", "fastapi>=0.111", "uvicorn[standard]>=0.29",
+           "click>=8.1", "mypy>=1.10", "bandit[toml]>=1.7", "pip-audit>=2.7"]
+
+[project.scripts]
+manifest = "agent_manifest.cli:main"
+
+[project.urls]
+Homepage      = "https://github.com/agentrust-io/agent-manifest"
+Repository    = "https://github.com/agentrust-io/agent-manifest"
+Documentation = "https://github.com/agentrust-io/agent-manifest/tree/main/spec"
+"Bug Tracker" = "https://github.com/agentrust-io/agent-manifest/issues"
+Changelog     = "https://github.com/agentrust-io/agent-manifest/releases"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_manifest"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.hatch.version]
+path = "src/agent_manifest/__init__.py"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "agent_manifest._hw_providers"
+warn_unused_ignores = false
+
+[tool.coverage.run]
+source = ["src/agent_manifest"]
+omit = ["src/agent_manifest/cli.py"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+
+[tool.bandit]
+exclude_dirs = ["tests"]
+# B101: assert statements (test helpers); B404/B603/B607: TPM attestation
+# providers require subprocess — inputs are validated before the call and
+# never include user-controlled data, so these are false positives.
+skips = ["B101", "B404", "B603", "B607"]

agent_manifest-0.1.0/src/agent_manifest/__init__.py

@@ -0,0 +1,47 @@
+"""Agent Manifest SDK - public API."""
+from .models import (
+    Manifest, ArtifactBindings,
+    SystemPromptBinding, PolicyBundleBinding, ToolManifestBinding,
+    ModelIdentityBinding, RagCorpusBinding, MemoryBaselineBinding,
+    DecisionTraceBinding, SupplyChainBinding,
+    DelegationHop, HitlRecord, HitlApproval, ManifestSignature,
+    ToolEntry, ScopeGrant, ApprovedScope, PoisoningScan, SlsaProvenance,
+    Sbom, McpServer,
+    EscalationPolicy, HitlRuntime,
+    TransparencyLogEntry, InclusionProof,
+    LogRetention, DataScope, OperationalLifecycle,
+    PolicyLanguage, EnforcementMode, DeploymentType, MemoryType, DriftPolicy,
+    RugPullPolicy, TraceType, SbomFormat, SlsaLevel, PoisoningResult,
+    ApprovalMethod, ApproverIdentityType, PrincipalType, DataClassification,
+    CryptoProfile, SignatureAlgorithm, KeyType, RiskTier,
+    ModelAttestationType, OverrideMechanism, TimeoutAction,
+)
+from ._types import HashValue, ManifestId
+from ._canonicalize import canonicalize, canonical_hash
+from ._signing import (
+    SIGNED_FIELDS,
+    signing_pre_image,
+    generate_ed25519, Ed25519KeyPair, Ed25519Signer, Ed25519Verifier,
+)
+
+__all__ = [
+    "Manifest", "ArtifactBindings",
+    "SystemPromptBinding", "PolicyBundleBinding", "ToolManifestBinding",
+    "ModelIdentityBinding", "RagCorpusBinding", "MemoryBaselineBinding",
+    "DecisionTraceBinding", "SupplyChainBinding",
+    "DelegationHop", "HitlRecord", "HitlApproval", "ManifestSignature",
+    "ToolEntry", "ScopeGrant", "ApprovedScope", "PoisoningScan", "SlsaProvenance",
+    "Sbom", "McpServer",
+    "EscalationPolicy", "HitlRuntime",
+    "TransparencyLogEntry", "InclusionProof",
+    "LogRetention", "DataScope", "OperationalLifecycle",
+    "PolicyLanguage", "EnforcementMode", "DeploymentType", "MemoryType", "DriftPolicy",
+    "RugPullPolicy", "TraceType", "SbomFormat", "SlsaLevel", "PoisoningResult",
+    "ApprovalMethod", "ApproverIdentityType", "PrincipalType", "DataClassification",
+    "CryptoProfile", "SignatureAlgorithm", "KeyType", "RiskTier",
+    "ModelAttestationType", "OverrideMechanism", "TimeoutAction",
+    "HashValue", "ManifestId",
+    "canonicalize", "canonical_hash",
+    "SIGNED_FIELDS", "signing_pre_image",
+    "generate_ed25519", "Ed25519KeyPair", "Ed25519Signer", "Ed25519Verifier",
+]

agent_manifest-0.1.0/src/agent_manifest/_auto_provider.py

@@ -0,0 +1,85 @@
+"""provider='auto' attestation backend selection.
+
+Auto-selection order (first locally-verifiable silicon wins):
+  1. SEVSNPProvider  — if /dev/sev-guest exists
+  2. TDXProvider     — if /dev/tdx-guest exists
+  3. TPMProvider     — if tpm2_extend is in PATH
+  4. SoftwareProvider — fallback, Level 0 only (no hardware attestation)
+
+OPAQUEProvider is explicit opt-in: selected only when OPAQUE_ATTESTATION_URL
+is set. It is never auto-detected.
+
+The SoftwareProvider is never selected automatically for Level 1+ contexts.
+Callers that require Level 1+ MUST explicitly check provider.level >= 1.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+from typing import Any, cast
+
+from ._providers import AttestationProvider, AttestationReport, AttestationUnavailableError, TPMProvider
+
+
+class SoftwareProvider(AttestationProvider):
+    """Level 0 software-only fallback — no hardware attestation.
+
+    Produces a manifest hash using pure software SHA-256. Suitable for
+    development and staging. MUST NOT be used for Level 1+ conformance.
+    """
+
+    LEVEL = 0
+
+    def extend_manifest_hash(self, manifest_json: dict[str, Any]) -> None:
+        # No hardware to extend into — record the hash for report generation
+        self._manifest_hash = self.manifest_hash_value(manifest_json)
+
+    def get_attestation_report(self) -> AttestationReport:
+        if not hasattr(self, "_manifest_hash"):
+            raise AttestationUnavailableError(
+                "Call extend_manifest_hash() before get_attestation_report()."
+            )
+        return AttestationReport(platform="software", manifest_hash=self._manifest_hash)
+
+    def verify_manifest_in_report(self, report: AttestationReport, manifest_json: dict[str, Any]) -> bool:
+        return bool(report.manifest_hash == self.manifest_hash_value(manifest_json))
+
+
+def select_provider(level: int = 0) -> AttestationProvider:
+    """Return the best available attestation provider for *level*.
+
+    Args:
+        level: Minimum conformance level required (0-3).
+
+    Raises:
+        AttestationUnavailableError: If *level* > 0 and no hardware provider
+            is available.
+    """
+    # OPAQUE managed runtime — explicit opt-in only, not auto-detected
+    if os.environ.get("OPAQUE_ATTESTATION_URL"):
+        from ._hw_providers import OPAQUEProvider
+        return cast(AttestationProvider, OPAQUEProvider())
+
+    # AMD SEV-SNP
+    if os.path.exists("/dev/sev-guest"):
+        from ._hw_providers import SEVSNPProvider
+        return cast(AttestationProvider, SEVSNPProvider())
+
+    # Intel TDX
+    if os.path.exists("/dev/tdx-guest"):
+        from ._hw_providers import TDXProvider
+        return cast(AttestationProvider, TDXProvider())
+
+    # Generic TPM / AWS Nitro
+    if shutil.which("tpm2_extend"):
+        return TPMProvider()
+
+    # Software fallback
+    if level >= 1:
+        raise AttestationUnavailableError(
+            "No hardware attestation provider available. "
+            "Level 1+ conformance requires TPM 2.0, AMD SEV-SNP, or Intel TDX. "
+            "To use the OPAQUE managed runtime, set OPAQUE_ATTESTATION_URL. "
+            "For development use, set level=0 explicitly."
+        )
+    return SoftwareProvider()