sigstore.errors

  1# Copyright 2023 The Sigstore Authors
  2#
  3# Licensed under the Apache License, Version 2.0 (the "License");
  4# you may not use this file except in compliance with the License.
  5# You may obtain a copy of the License at
  6#
  7#      http://www.apache.org/licenses/LICENSE-2.0
  8#
  9# Unless required by applicable law or agreed to in writing, software
 10# distributed under the License is distributed on an "AS IS" BASIS,
 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 12# See the License for the specific language governing permissions and
 13# limitations under the License.
 14
 15"""
 16Exceptions.
 17"""
 18
 19import sys
 20from logging import Logger
 21from typing import Any, Mapping
 22
 23
 24class Error(Exception):
 25    """Base sigstore exception type. Defines helpers for diagnostics."""
 26
 27    def diagnostics(self) -> str:
 28        """Returns human-friendly error information."""
 29
 30        return str(self)
 31
 32    def log_and_exit(self, logger: Logger, raise_error: bool = False) -> None:
 33        """Prints all relevant error information to stderr and exits."""
 34
 35        remind_verbose = (
 36            "Raising original exception:"
 37            if raise_error
 38            else "For detailed error information, run sigstore with the `--verbose` flag."
 39        )
 40
 41        logger.error(f"{self.diagnostics()}\n{remind_verbose}")
 42
 43        if raise_error:
 44            # don't want "during handling another exception"
 45            self.__suppress_context__ = True
 46            raise self
 47
 48        sys.exit(1)
 49
 50
 51class NetworkError(Error):
 52    """Raised when a connectivity-related issue occurs."""
 53
 54    def diagnostics(self) -> str:
 55        """Returns diagnostics for the error."""
 56
 57        cause_ctx = (
 58            f"""
 59        Additional context:
 60
 61        {self.__cause__}
 62        """
 63            if self.__cause__
 64            else ""
 65        )
 66
 67        return (
 68            """\
 69        A network issue occurred.
 70
 71        Check your internet connection and try again.
 72        """
 73            + cause_ctx
 74        )
 75
 76
 77class TUFError(Error):
 78    """Raised when a TUF error occurs."""
 79
 80    def __init__(self, message: str):
 81        """Constructs a `TUFError`."""
 82        self.message = message
 83
 84    from tuf.api import exceptions
 85
 86    _details: Mapping[Any, str] = {
 87        exceptions.DownloadError: NetworkError().diagnostics()
 88    }
 89
 90    def diagnostics(self) -> str:
 91        """Returns diagnostics specialized to the wrapped TUF error."""
 92        details = TUFError._details.get(
 93            type(self.__context__),
 94            "Please report this issue at <https://github.com/sigstore/sigstore-python/issues/new>.",
 95        )
 96
 97        return f"""\
 98        {self.message}.
 99
100        {details}
101        """
102
103
104class MetadataError(Error):
105    """Raised when TUF metadata does not conform to the expected structure."""
106
107    def diagnostics(self) -> str:
108        """Returns diagnostics for the error."""
109        return f"""{str(self)}."""
110
111
112class RootError(Error):
113    """Raised when TUF cannot establish its root of trust."""
114
115    def diagnostics(self) -> str:
116        """Returns diagnostics for the error."""
117        return """\
118        Unable to establish root of trust.
119
120        This error may occur when the resources embedded in this distribution of sigstore-python are out of date."""
121
122
123class VerificationError(Error):
124    """
125    Raised whenever any phase or subcomponent of Sigstore verification fails.
126    """