feat: Attestation.statement

Signed-off-by: William Woodruff <william@trailofbits.com>

Author: woodruffw

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `Attestation.statement` has been added as a convenience API for accessing
+  the attestation's enveloped statement as a dictionary
+
 ## [0.0.15]
 
 This is a corrective release for [0.0.14].

src/pypi_attestations/_impl.py

@@ -6,6 +6,7 @@
 from __future__ import annotations
 
 import base64
+import json
 from enum import Enum
 from typing import TYPE_CHECKING, Annotated, Any, Literal, NewType, Optional, Union, get_args
 
@@ -148,6 +149,15 @@ class Attestation(BaseModel):
     The enveloped attestation statement and signature.
     """
 
+    @property
+    def statement(self) -> dict[str, Any]:
+        """Return the statement within this attestation's envelope.
+
+        The value returned here is a dictionary, in the shape of an
+        in-toto statement.
+        """
+        return json.loads(self.envelope.statement)
+
     @classmethod
     def sign(cls, signer: Signer, dist: Distribution) -> Attestation:
         """Create an envelope, with signature, from the given Python distribution.

test/test_impl.py

@@ -168,8 +168,13 @@ def test_verify(self) -> None:
         attestation = impl.Attestation.model_validate_json(dist_attestation_path.read_text())
         predicate_type, predicate = attestation.verify(pol, dist, staging=True)
 
-        assert predicate_type == "https://docs.pypi.org/attestations/publish/v1"
-        assert predicate is None
+        assert attestation.statement["_type"] == "https://in-toto.io/Statement/v1"
+        assert (
+            predicate_type
+            == attestation.statement["predicateType"]
+            == "https://docs.pypi.org/attestations/publish/v1"
+        )
+        assert predicate is None and attestation.statement["predicate"] is None
 
         # convert the attestation to a bundle and verify it that way too
         bundle = attestation.to_bundle()