API: make _StatementBuilder public (#1077)

Author: woodruffw

CHANGELOG.md

@@ -8,6 +8,14 @@ All versions prior to 0.9.0 are untracked.
 
 ## [Unreleased]
 
+### Added
+
+* API: `dsse.StatementBuilder` has been added. It can be used to construct an
+  in-toto `Statement` for subsequent enveloping and signing.
+  This API is public but is **not considered stable until the next major
+  release.**
+  ([#1077](https://github.com/sigstore/sigstore-python/pull/1077))
+
 ### Changed
 
 * API: `verify_dsse` now rejects bundles with DSSE envelopes that have more than

sigstore/dsse.py

@@ -89,19 +89,23 @@ class Statement:
     See: <https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md>
     """
 
-    def __init__(self, contents: bytes) -> None:
+    def __init__(self, contents: bytes | _Statement) -> None:
         """
         Construct a new Statement.
 
         This takes an opaque `bytes` containing the statement; use
         `StatementBuilder` to manually construct an in-toto statement
         from constituent pieces.
         """
-        self._contents = contents
-        try:
-            self._inner = _Statement.model_validate_json(contents)
-        except ValidationError:
-            raise Error("malformed in-toto statement")
+        if isinstance(contents, bytes):
+            self._contents = contents
+            try:
+                self._inner = _Statement.model_validate_json(contents)
+            except ValidationError:
+                raise Error("malformed in-toto statement")
+        else:
+            self._contents = contents.model_dump_json(by_alias=True).encode()
+            self._inner = contents
 
     def _matches_digest(self, digest: Hashed) -> bool:
         """
@@ -130,7 +134,7 @@ def _pae(self) -> bytes:
         return _pae(Envelope._TYPE, self._contents)
 
 
-class _StatementBuilder:
+class StatementBuilder:
     """
     A builder-style API for constructing in-toto Statements.
     """
@@ -142,27 +146,27 @@ def __init__(
         predicate: Optional[Dict[str, Any]] = None,
     ):
         """
-        Create a new `_StatementBuilder`.
+        Create a new `StatementBuilder`.
         """
         self._subjects = subjects or []
         self._predicate_type = predicate_type
         self._predicate = predicate
 
-    def subjects(self, subjects: list[_Subject]) -> _StatementBuilder:
+    def subjects(self, subjects: list[_Subject]) -> StatementBuilder:
         """
         Configure the subjects for this builder.
         """
         self._subjects = subjects
         return self
 
-    def predicate_type(self, predicate_type: str) -> _StatementBuilder:
+    def predicate_type(self, predicate_type: str) -> StatementBuilder:
         """
         Configure the predicate type for this builder.
         """
         self._predicate_type = predicate_type
         return self
 
-    def predicate(self, predicate: dict[str, Any]) -> _StatementBuilder:
+    def predicate(self, predicate: dict[str, Any]) -> StatementBuilder:
         """
         Configure the predicate for this builder.
         """
@@ -183,7 +187,7 @@ def build(self) -> Statement:
         except ValidationError as e:
             raise Error(f"invalid statement: {e}")
 
-        return Statement(stmt.model_dump_json(by_alias=True).encode())
+        return Statement(stmt)
 
 
 class Envelope:

test/unit/test_sign.py

@@ -20,7 +20,7 @@
 from sigstore_protobuf_specs.dev.sigstore.common.v1 import HashAlgorithm
 
 import sigstore.oidc
-from sigstore.dsse import _StatementBuilder, _Subject
+from sigstore.dsse import StatementBuilder, _Subject
 from sigstore.errors import VerificationError
 from sigstore.hashes import Hashed
 from sigstore.sign import SigningContext
@@ -152,7 +152,7 @@ def test_sign_dsse(staging):
 
     ctx = sign_ctx()
     stmt = (
-        _StatementBuilder()
+        StatementBuilder()
         .subjects(
             [_Subject(name="null", digest={"sha256": hashlib.sha256(b"").hexdigest()})]
         )

test/unit/verify/test_verifier.py

@@ -18,7 +18,7 @@
 import pretend
 import pytest
 
-from sigstore.dsse import _StatementBuilder, _Subject
+from sigstore.dsse import StatementBuilder, _Subject
 from sigstore.errors import VerificationError
 from sigstore.models import Bundle
 from sigstore.verify import policy
@@ -159,7 +159,7 @@ def test_verifier_dsse_roundtrip(staging):
 
     ctx = signer_cls()
     stmt = (
-        _StatementBuilder()
+        StatementBuilder()
         .subjects(
             [_Subject(name="null", digest={"sha256": hashlib.sha256(b"").hexdigest()})]
         )