signer: update sigstore docs + minor refactor

As per Jussi's CR:
- Add comments to explain env vars
- Add comments to mark API as unstable
- Refactor raise-except-raise pattern

Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>

Author: lukpueh

securesystemslib/signer/_sigstore_signer.py

@@ -58,7 +58,10 @@
 
 
 class SigstoreKey(Key):
-    """Sigstore verifier."""
+    """Sigstore verifier.
+
+    NOTE: unstable API - routines and metadata formats may change!
+    """
 
     @classmethod
     def from_dict(cls, keyid: str, key_dict: Dict[str, Any]) -> "SigstoreKey":
@@ -84,6 +87,7 @@ def to_dict(self) -> Dict:
 
     def verify_signature(self, signature: Signature, data: bytes) -> None:
         # pylint: disable=import-outside-toplevel,import-error
+        result = None
         try:
             from sigstore.verify import VerificationMaterials, Verifier
             from sigstore.verify.policy import Identity
@@ -98,25 +102,29 @@ def verify_signature(self, signature: Signature, data: bytes) -> None:
                 input_=io.BytesIO(data), bundle=bundle, offline=True
             )
             result = verifier.verify(materials, identity)
-            if not result:
-                logger.info(
-                    "Key %s failed to verify sig: %s", self.keyid, result.reason
-                )
-                raise UnverifiedSignatureError(
-                    f"Failed to verify signature by {self.keyid}"
-                )
-        except UnverifiedSignatureError:
-            raise
 
         except Exception as e:
             logger.info("Key %s failed to verify sig: %s", self.keyid, str(e))
             raise VerificationError(
                 f"Unknown failure to verify signature by {self.keyid}"
             ) from e
 
+        if not result:
+            logger.info(
+                "Key %s failed to verify sig: %s",
+                self.keyid,
+                getattr(result, "reason", ""),
+            )
+            raise UnverifiedSignatureError(
+                f"Failed to verify signature by {self.keyid}"
+            )
+
 
 class SigstoreSigner(Signer):
-    """Sigstore signer."""
+    """Sigstore signer.
+
+    NOTE: unstable API - routines and metadata formats may change!
+    """
 
     def __init__(self, token: str, public_key: Key):
         # TODO: Vet public key

tox.ini

@@ -50,6 +50,7 @@ deps =
     -r{toxinidir}/requirements-pinned.txt
     -r{toxinidir}/requirements-sigstore.txt
 passenv =
+    # These are required to detect ambient credentials on GitHub
     GITHUB_ACTIONS
     ACTIONS_ID_TOKEN_REQUEST_TOKEN
     ACTIONS_ID_TOKEN_REQUEST_URL