dsse: make constituent types public (#1078)

CHANGELOG.md

@@ -16,6 +16,13 @@ All versions prior to 0.9.0 are untracked.
   release.**
   ([#1077](https://github.com/sigstore/sigstore-python/pull/1077))
 
+* API: `dsse.Digest`, `dsse.DigestSet`, and `dsse.Subject` have been added.
+  These types can be used with the `StatementBuilder` API as part of in-toto
+  `Statement` construction.
+  These API are public but are **not considered stable until the next major
+  release.**
+  ([#1078](https://github.com/sigstore/sigstore-python/pull/1078))
+
 ### Changed
 
 * API: `verify_dsse` now rejects bundles with DSSE envelopes that have more than

sigstore/dsse.py

@@ -34,7 +34,7 @@
 
 _logger = logging.getLogger(__name__)
 
-_Digest = Union[
+Digest = Union[
     Literal["sha256"],
     Literal["sha384"],
     Literal["sha512"],
@@ -50,19 +50,19 @@
 See: <https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md>
 """
 
-_DigestSet = RootModel[Dict[_Digest, str]]
+DigestSet = RootModel[Dict[Digest, str]]
 """
 An internal validation model for in-toto subject digest sets.
 """
 
 
-class _Subject(BaseModel):
+class Subject(BaseModel):
     """
     A single in-toto statement subject.
     """
 
     name: Optional[StrictStr]
-    digest: _DigestSet = Field(...)
+    digest: DigestSet = Field(...)
 
 
 class _Statement(BaseModel):
@@ -73,7 +73,7 @@ class _Statement(BaseModel):
     model_config = ConfigDict(populate_by_name=True)
 
     type_: Literal["https://in-toto.io/Statement/v1"] = Field(..., alias="_type")
-    subjects: List[_Subject] = Field(..., min_length=1, alias="subject")
+    subjects: List[Subject] = Field(..., min_length=1, alias="subject")
     predicate_type: StrictStr = Field(..., alias="predicateType")
     predicate: Optional[Dict[str, Any]] = Field(None, alias="predicate")
 
@@ -141,7 +141,7 @@ class StatementBuilder:
 
     def __init__(
         self,
-        subjects: Optional[List[_Subject]] = None,
+        subjects: Optional[List[Subject]] = None,
         predicate_type: Optional[str] = None,
         predicate: Optional[Dict[str, Any]] = None,
     ):
@@ -152,7 +152,7 @@ def __init__(
         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.
         """

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
@@ -154,7 +154,7 @@ def test_sign_dsse(staging):
     stmt = (
         StatementBuilder()
         .subjects(
-            [_Subject(name="null", digest={"sha256": hashlib.sha256(b"").hexdigest()})]
+            [Subject(name="null", digest={"sha256": hashlib.sha256(b"").hexdigest()})]
         )
         .predicate_type("https://cosign.sigstore.dev/attestation/v1")
         .predicate(

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
@@ -161,7 +161,7 @@ def test_verifier_dsse_roundtrip(staging):
     stmt = (
         StatementBuilder()
         .subjects(
-            [_Subject(name="null", digest={"sha256": hashlib.sha256(b"").hexdigest()})]
+            [Subject(name="null", digest={"sha256": hashlib.sha256(b"").hexdigest()})]
         )
         .predicate_type("https://cosign.sigstore.dev/attestation/v1")
         .predicate(