feat: Expose ClientTrustConfig as a public class

Signed-off-by: SequeI <[email protected]>

Author: SequeI

CHANGELOG.md

@@ -65,6 +65,9 @@ All versions prior to 0.9.0 are untracked.
   * SigningConfig now has methods that return actual clients (like `RekorClient`) instead of
     just URLs. The returned clients are also filtered according to SigningConfig contents.
     [#1407](https://github.com/sigstore/sigstore-python/pull/1407)
+  * The ClientTrustConfig class has been moved from the private _internal package to a new public
+    module (sigstore.trust). This change formally adds the class to the project's public API,
+    making it available for use in other projects.
 * `--trust-config` now requires a file with SigningConfig v0.2, and is able to fully
   configure the used Sigstore instance [#1358]/(https://github.com/sigstore/sigstore-python/pull/1358)
 * By default (when `--trust-config` is not used) the whole trust configuration now

docs/api/trust.md

@@ -0,0 +1 @@
+:::sigstore.trust

sigstore/_cli.py

@@ -40,7 +40,6 @@
 from sigstore._internal.fulcio.client import ExpiredCertificate
 from sigstore._internal.rekor import _hashedrekord_from_parts
 from sigstore._internal.rekor.client import RekorClient
-from sigstore._internal.trust import ClientTrustConfig
 from sigstore._utils import sha256_digest
 from sigstore.dsse import StatementBuilder, Subject
 from sigstore.dsse._predicate import (
@@ -58,6 +57,7 @@
     detect_credential,
 )
 from sigstore.sign import Signer, SigningContext
+from sigstore.trust import ClientTrustConfig
 from sigstore.verify import (
     Verifier,
     policy,

sigstore/_internal/trust.py

@@ -43,9 +43,6 @@
 from sigstore_protobuf_specs.dev.sigstore.trustroot.v1 import (
     CertificateAuthority as _CertificateAuthority,
 )
-from sigstore_protobuf_specs.dev.sigstore.trustroot.v1 import (
-    ClientTrustConfig as _ClientTrustConfig,
-)
 from sigstore_protobuf_specs.dev.sigstore.trustroot.v1 import (
     Service,
     ServiceConfiguration,
@@ -64,15 +61,13 @@
 from sigstore._internal.rekor.client import RekorClient
 from sigstore._internal.rekor.client_v2 import RekorV2Client
 from sigstore._internal.timestamp import TimestampAuthorityClient
-from sigstore._internal.tuf import DEFAULT_TUF_URL, STAGING_TUF_URL, TrustUpdater
 from sigstore._utils import (
     KeyID,
     PublicKey,
     key_id,
     load_der_public_key,
-    read_embedded,
 )
-from sigstore.errors import Error, MetadataError, TUFError, VerificationError
+from sigstore.errors import Error, MetadataError, VerificationError
 
 # Versions supported by this client
 REKOR_VERSIONS = [1, 2]
@@ -562,123 +557,3 @@ def get_timestamp_authorities(self) -> list[CertificateAuthority]:
             for cert_chain in self._inner.timestamp_authorities
         ]
         return certificate_authorities
-
-
-class ClientTrustConfig:
-    """
-    Represents a Sigstore client's trust configuration, including a root of trust.
-    """
-
-    class ClientTrustConfigType(str, Enum):
-        """
-        Known Sigstore client trust config media types.
-        """
-
-        CONFIG_0_1 = "application/vnd.dev.sigstore.clienttrustconfig.v0.1+json"
-
-        def __str__(self) -> str:
-            """Returns the variant's string value."""
-            return self.value
-
-    @classmethod
-    def from_json(cls, raw: str) -> ClientTrustConfig:
-        """
-        Deserialize the given client trust config.
-        """
-        inner = _ClientTrustConfig().from_json(raw)
-        return cls(inner)
-
-    @classmethod
-    def production(
-        cls,
-        offline: bool = False,
-    ) -> ClientTrustConfig:
-        """Create new trust config from Sigstore production TUF repository.
-
-        If `offline`, will use data in local TUF cache. Otherwise will
-        update the data from remote TUF repository.
-        """
-        return cls.from_tuf(DEFAULT_TUF_URL, offline)
-
-    @classmethod
-    def staging(
-        cls,
-        offline: bool = False,
-    ) -> ClientTrustConfig:
-        """Create new trust config from Sigstore staging TUF repository.
-
-        If `offline`, will use data in local TUF cache. Otherwise will
-        update the data from remote TUF repository.
-        """
-        return cls.from_tuf(STAGING_TUF_URL, offline)
-
-    @classmethod
-    def from_tuf(
-        cls,
-        url: str,
-        offline: bool = False,
-    ) -> ClientTrustConfig:
-        """Create a new trust config from a TUF repository.
-
-        If `offline`, will use data in local TUF cache. Otherwise will
-        update the trust config from remote TUF repository.
-        """
-        updater = TrustUpdater(url, offline)
-
-        tr_path = updater.get_trusted_root_path()
-        inner_tr = _TrustedRoot().from_json(Path(tr_path).read_bytes())
-
-        try:
-            sc_path = updater.get_signing_config_path()
-            inner_sc = _SigningConfig().from_json(Path(sc_path).read_bytes())
-        except TUFError as e:
-            # TUF repo may not have signing config yet: hard code values for prod:
-            # https://github.com/sigstore/sigstore-python/issues/1388
-            if url == DEFAULT_TUF_URL:
-                embedded = read_embedded("signing_config.v0.2.json", url)
-                inner_sc = _SigningConfig().from_json(embedded)
-            else:
-                raise e
-
-        return cls(
-            _ClientTrustConfig(
-                ClientTrustConfig.ClientTrustConfigType.CONFIG_0_1,
-                inner_tr,
-                inner_sc,
-            )
-        )
-
-    def __init__(self, inner: _ClientTrustConfig) -> None:
-        """
-        @api private
-        """
-        self._inner = inner
-        self._verify()
-
-    def _verify(self) -> None:
-        """
-        Performs various feats of heroism to ensure that the client trust config
-        is well-formed.
-        """
-
-        # The client trust config must have a recognized media type.
-        try:
-            ClientTrustConfig.ClientTrustConfigType(self._inner.media_type)
-        except ValueError:
-            raise Error(
-                f"unsupported client trust config format: {self._inner.media_type}"
-            )
-
-    @property
-    def trusted_root(self) -> TrustedRoot:
-        """
-        Return the interior root of trust, as a `TrustedRoot`.
-        """
-        return TrustedRoot(self._inner.trusted_root)
-
-    @property
-    def signing_config(self) -> SigningConfig:
-        """
-        Return the interior root of trust, as a `SigningConfig`.
-        """
-        return SigningConfig(self._inner.signing_config)

sigstore/sign.py

@@ -61,10 +61,11 @@
 from sigstore._internal.rekor import EntryRequestBody, RekorLogSubmitter
 from sigstore._internal.sct import verify_sct
 from sigstore._internal.timestamp import TimestampAuthorityClient, TimestampError
-from sigstore._internal.trust import ClientTrustConfig, KeyringPurpose, TrustedRoot
+from sigstore._internal.trust import KeyringPurpose, TrustedRoot
 from sigstore._utils import sha256_digest
 from sigstore.models import Bundle
 from sigstore.oidc import ExpiredIdentity, IdentityToken
+from sigstore.trust import ClientTrustConfig
 
 _logger = logging.getLogger(__name__)
 

sigstore/trust.py

@@ -0,0 +1,162 @@
+# Copyright 2023 The Sigstore Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Client trust configuration for sigstore-python.
+"""
+
+from __future__ import annotations
+
+import logging
+from enum import Enum
+from pathlib import Path
+
+from sigstore_protobuf_specs.dev.sigstore.trustroot.v1 import (
+    ClientTrustConfig as _ClientTrustConfig,
+)
+from sigstore_protobuf_specs.dev.sigstore.trustroot.v1 import (
+    SigningConfig as _SigningConfig,
+)
+from sigstore_protobuf_specs.dev.sigstore.trustroot.v1 import (
+    TrustedRoot as _TrustedRoot,
+)
+
+from sigstore._internal.trust import SigningConfig, TrustedRoot
+from sigstore._internal.tuf import DEFAULT_TUF_URL, STAGING_TUF_URL, TrustUpdater
+from sigstore._utils import (
+    read_embedded,
+)
+from sigstore.errors import Error, TUFError
+
+_logger = logging.getLogger(__name__)
+
+
+class ClientTrustConfig:
+    """
+    Represents a Sigstore client's trust configuration, including a root of trust.
+    """
+
+    class ClientTrustConfigType(str, Enum):
+        """
+        Known Sigstore client trust config media types.
+        """
+
+        CONFIG_0_1 = "application/vnd.dev.sigstore.clienttrustconfig.v0.1+json"
+
+        def __str__(self) -> str:
+            """Returns the variant's string value."""
+            return self.value
+
+    @classmethod
+    def from_json(cls, raw: str) -> ClientTrustConfig:
+        """
+        Deserialize the given client trust config.
+        """
+        inner = _ClientTrustConfig().from_json(raw)
+        return cls(inner)
+
+    @classmethod
+    def production(
+        cls,
+        offline: bool = False,
+    ) -> ClientTrustConfig:
+        """Create new trust config from Sigstore production TUF repository.
+
+        If `offline`, will use data in local TUF cache. Otherwise will
+        update the data from remote TUF repository.
+        """
+        return cls.from_tuf(DEFAULT_TUF_URL, offline)
+
+    @classmethod
+    def staging(
+        cls,
+        offline: bool = False,
+    ) -> ClientTrustConfig:
+        """Create new trust config from Sigstore staging TUF repository.
+
+        If `offline`, will use data in local TUF cache. Otherwise will
+        update the data from remote TUF repository.
+        """
+        return cls.from_tuf(STAGING_TUF_URL, offline)
+
+    @classmethod
+    def from_tuf(
+        cls,
+        url: str,
+        offline: bool = False,
+    ) -> ClientTrustConfig:
+        """Create a new trust config from a TUF repository.
+
+        If `offline`, will use data in local TUF cache. Otherwise will
+        update the trust config from remote TUF repository.
+        """
+        updater = TrustUpdater(url, offline)
+
+        tr_path = updater.get_trusted_root_path()
+        inner_tr = _TrustedRoot().from_json(Path(tr_path).read_bytes())
+
+        try:
+            sc_path = updater.get_signing_config_path()
+            inner_sc = _SigningConfig().from_json(Path(sc_path).read_bytes())
+        except TUFError as e:
+            # TUF repo may not have signing config yet: hard code values for prod:
+            # https://github.com/sigstore/sigstore-python/issues/1388
+            if url == DEFAULT_TUF_URL:
+                embedded = read_embedded("signing_config.v0.2.json", url)
+                inner_sc = _SigningConfig().from_json(embedded)
+            else:
+                raise e
+
+        return cls(
+            _ClientTrustConfig(
+                ClientTrustConfig.ClientTrustConfigType.CONFIG_0_1,
+                inner_tr,
+                inner_sc,
+            )
+        )
+
+    def __init__(self, inner: _ClientTrustConfig) -> None:
+        """
+        @api private
+        """
+        self._inner = inner
+        self._verify()
+
+    def _verify(self) -> None:
+        """
+        Performs various feats of heroism to ensure that the client trust config
+        is well-formed.
+        """
+
+        # The client trust config must have a recognized media type.
+        try:
+            ClientTrustConfig.ClientTrustConfigType(self._inner.media_type)
+        except ValueError:
+            raise Error(
+                f"unsupported client trust config format: {self._inner.media_type}"
+            )
+
+    @property
+    def trusted_root(self) -> TrustedRoot:
+        """
+        Return the interior root of trust, as a `TrustedRoot`.
+        """
+        return TrustedRoot(self._inner.trusted_root)
+
+    @property
+    def signing_config(self) -> SigningConfig:
+        """
+        Return the interior root of trust, as a `SigningConfig`.
+        """
+        return SigningConfig(self._inner.signing_config)

sigstore/verify/verifier.py

@@ -49,11 +49,12 @@
     verify_sct,
 )
 from sigstore._internal.timestamp import TimestampSource, TimestampVerificationResult
-from sigstore._internal.trust import ClientTrustConfig, KeyringPurpose, TrustedRoot
+from sigstore._internal.trust import KeyringPurpose, TrustedRoot
 from sigstore._utils import base64_encode_pem_cert, sha256_digest
 from sigstore.errors import VerificationError
 from sigstore.hashes import Hashed
 from sigstore.models import Bundle
+from sigstore.trust import ClientTrustConfig
 from sigstore.verify.policy import VerificationPolicy
 
 _logger = logging.getLogger(__name__)

test/unit/conftest.py

@@ -38,11 +38,11 @@
 from sigstore._internal import tuf
 from sigstore._internal.rekor import _hashedrekord_from_parts
 from sigstore._internal.rekor.client import RekorClient
-from sigstore._internal.trust import ClientTrustConfig
 from sigstore._utils import sha256_digest
 from sigstore.models import Bundle
 from sigstore.oidc import IdentityToken
 from sigstore.sign import SigningContext
+from sigstore.trust import ClientTrustConfig
 from sigstore.verify.verifier import Verifier
 
 _TUF_ASSETS = (Path(__file__).parent.parent / "assets" / "staging-tuf").resolve()

test/unit/internal/test_trust.py

@@ -32,14 +32,14 @@
 from sigstore._internal.timestamp import TimestampAuthorityClient
 from sigstore._internal.trust import (
     CertificateAuthority,
-    ClientTrustConfig,
     KeyringPurpose,
     SigningConfig,
     TrustedRoot,
     _is_timerange_valid,
 )
 from sigstore._utils import load_pem_public_key
 from sigstore.errors import Error
+from sigstore.trust import ClientTrustConfig
 
 # Test data for TestSigningcconfig
 _service_v1_op1 = Service("url1", major_api_version=1, operator="op1")