Verification¶

Verification is the step where a relying party (the service deciding whether to trust an agent) checks a manifest: is the signature from an issuer it trusts, has the manifest expired or been revoked, and do the recorded artifacts match what it observes. This page documents the function that runs those checks and the optional web endpoint that exposes them.

The core verification engine and FastAPI router. See Tutorial: Server-side verification for usage examples.

Public API¶

For gateway and runtime-session binding, call the package-root export rather than the private _verify module:

from agent_manifest import RevocationStore, VerificationContext, verify_manifest

verify_manifest() is the supported high-level entry point. VerificationContext.trusted_keys maps an issuer key_id (the SHA-256 hex of the public key bytes) to its base64url-encoded Ed25519 public key, the form returned by Ed25519KeyPair.public_b64url(). A consumer that holds raw public key bytes must base64url-encode them before populating trusted_keys. VerificationContext.trusted_key_issuers maps the same key_id to the issuer URIs that key may sign for (spec section 5.3.3). It is required for VALID: without it the result is UNVERIFIABLE, and a key not authorized for the manifest's issuer is MISMATCH. agent_manifest.signing_pre_image() is the v0.1 signature pre-image: signers and verifiers share it for the exact RFC 8785 canonical byte sequence, including the hitl_record.approvals normalization, so a relying party never reconstructs the pre-image itself. It does not apply to v0.2 manifests. A v0.2 manifest has no field allowlist and no approvals normalization at the payload level; a verifier checks the COSE Sig_structure over the payload bytes exactly as received (agent_manifest.verify_cose_manifest(), built on agent_manifest.cose_payload() for the producer side), with hitl_record.approvals carried in the unprotected header rather than normalized out of the signed payload.

Core function¶

verify_manifest(manifest: Union[dict[str, Any], bytes], context: VerificationContext, revocation_store: 'RevocationStore', *, _envelope: Optional[CoseVerification] = None) -> VerificationResult

Context¶

Results¶

EvidencePack is an optional reference (trace id, signer, hash, and URI) to an externally retained evidence pack that a verifier can record alongside a result.

TRACE envelopes and evidence packs¶

EvidencePack above is only a reference to a pack. To appraise the pack itself, and the per-tool-call TRACE envelopes inside it, use:

from agent_manifest import verify_evidence_pack, verify_trace_envelope

A TRACE envelope (spec §6.3.2) is signed by a TEE-sealed key over the RFC 8785 canonical form of every field except signature. The envelope carries no algorithm or key id of its own, so the caller supplies both; trusted_keys uses the same key_id → base64url public key mapping as VerificationContext. An evidence pack (spec §5.2.1) instead carries a detached pack_signature object in the form of §3.6, so hybrid signatures work there but not on envelopes.

Read admissible, not just status. A TRACE reporting manifest_verification_result: MISMATCH or EXPIRED can have a perfectly valid signature (the runtime honestly recorded a bad state), but spec §6.3.2 says it "MUST NOT be accepted as evidence of a valid tool call for regulatory reporting purposes". verify_trace_envelope() returns status=VERIFIED with admissible=False in that case.

Passing manifest= additionally enforces the §6.3.2 hash-conflict rule (SCHEMA F-21): if the envelope's policy_hash differs from the manifest's artifacts.policy_bundle.hash, the envelope must declare MISMATCH. One that claims VALID over a conflicting hash is a spec violation and fails.

Verification is fail-closed: a missing key, an unknown algorithm, or a build without the [pq] extra yields UNVERIFIABLE, never VERIFIED.

verify_evidence_pack() also appraises the section 5.2 verification_result inside the pack. The pack signature proves who assembled the pack, not what the result says, so the pack is VERIFIED only when that result is VALID and its manifest_id names the pack's manifest. Its verification_signature is a bare string signed by the attestation service over verification_result_pre_image(); pass result_key_id (and result_algorithm for ML-DSA-65) to check it. Without result_key_id it is not checked, verification_result_signature_verified stays False, and the result carries a verification_result_signature_not_appraised warning. signature_verified refers to the outer pack_signature only.

verify_trace_envelope(envelope: dict[str, Any], *, trusted_keys: Optional[dict[str, str]] = None, key_id: Optional[str] = None, algorithm: str = 'Ed25519', manifest: Optional[dict[str, Any]] = None) -> TraceVerificationResult

verify_evidence_pack(pack: dict[str, Any], *, trusted_keys: Optional[dict[str, str]] = None, expected_pack_hash: Optional[str] = None, trace_key_id: Optional[str] = None, trace_algorithm: str = 'Ed25519', verify_envelopes: bool = True, result_key_id: Optional[str] = None, result_algorithm: str = 'Ed25519') -> EvidencePackVerificationResult

compute_pack_hash() returns the spec §5.2.1 pack_hash: the SHA-256 of the pack's canonical bytes excluding pack_signature. trace_signing_pre_image() and evidence_pack_pre_image() are the shared pre-image functions; producers and verifiers MUST both use them so the byte sequences match.

compute_pack_hash(pack: dict[str, Any]) -> str

trace_signing_pre_image(envelope: dict[str, Any]) -> bytes

evidence_pack_pre_image(pack: dict[str, Any]) -> bytes

verification_result_pre_image(verification_result: dict[str, Any]) -> bytes

Revocation¶

RevocationStore is the revocation lookup a verifier consults during verify_manifest(); the default is in-memory, and production deployments back it with a persistent store. RevocationRecord is a single revocation entry: which manifest was revoked, when, why, and by whom.

FastAPI router¶

create_router(manifest_store: dict[str, dict[str, Any]], revocation_store: RevocationStore, cose_context: Optional[VerificationContext] = None) -> Any