""" Unified error types for ChaosCrypt. Every failure raised by this library is a subclass of :class:`ChaosCryptError`, and every instance renders as:: ChaosCrypt_ERR__ The machine-readable ``code`` attribute (``E001`` … ``E016``) is stable and is safe to branch on; the human-readable portion is documentation only and may be reworded between minor releases. Catching :class:`ChaosCryptError` is sufficient to handle every error the library can raise. """ from __future__ import annotations __all__ = [ "ChaosCryptError", "ChaosCrypt_ERR_KeyFileNotFound_E001", "ChaosCrypt_ERR_KeyFileCorrupted_E002", "ChaosCrypt_ERR_KeyPasswordIncorrect_E003", "ChaosCrypt_ERR_KeyNotLoaded_E004", "ChaosCrypt_ERR_KeyFileExists_E005", "ChaosCrypt_ERR_EmptyPassword_E006", "ChaosCrypt_ERR_PasswordMismatch_E007", "ChaosCrypt_ERR_EmptyPlaintext_E008", "ChaosCrypt_ERR_EmptyCiphertext_E009", "ChaosCrypt_ERR_MalformedCiphertext_E010", "ChaosCrypt_ERR_DecryptionFailed_E011", "ChaosCrypt_ERR_EncodingFailed_E012", "ChaosCrypt_ERR_InvalidArgument_E013", "ChaosCrypt_ERR_FileReadFailed_E014", "ChaosCrypt_ERR_FileWriteFailed_E015", "ChaosCrypt_ERR_UnsupportedKeyVersion_E016", "ChaosCrypt_ERR_MissingMagicHeader_E017", "ChaosCrypt_ERR_MalformedHeader_E018", ] class ChaosCryptError(Exception): """Base class for every error raised by ChaosCrypt. Attributes: detail: Human-readable description of what went wrong. code: Stable machine-readable code, e.g. ``"E003"``. message: The fully rendered ``ChaosCrypt_ERR__`` string. """ #: Default machine-readable code; overridden by subclasses. CODE = "E000" #: Default human-readable detail; overridden by subclasses. DETAIL = "UnknownError" def __init__(self, detail: str | None = None, code: str | None = None): self.detail = detail if detail is not None else self.DETAIL self.code = code if code is not None else self.CODE self.message = f"ChaosCrypt_ERR_{self.detail}_{self.code}" super().__init__(self.message) def __str__(self) -> str: # pragma: no cover - trivial return self.message def __repr__(self) -> str: # pragma: no cover - trivial return f"{type(self).__name__}({self.message!r})" def _define(name: str, detail: str, code: str, doc: str) -> type: """Create a named ``ChaosCryptError`` subclass.""" return type( name, (ChaosCryptError,), {"DETAIL": detail, "CODE": code, "__doc__": doc}, ) # --------------------------------------------------------------------------- # Named error types # --------------------------------------------------------------------------- ChaosCrypt_ERR_KeyFileNotFound_E001 = _define( "ChaosCrypt_ERR_KeyFileNotFound_E001", "KeyFileNotFound", "E001", "The requested key file does not exist.", ) ChaosCrypt_ERR_KeyFileCorrupted_E002 = _define( "ChaosCrypt_ERR_KeyFileCorrupted_E002", "KeyFileCorrupted", "E002", "The key file could not be parsed (truncated, altered, or not a " "ChaosCrypt key file).", ) ChaosCrypt_ERR_KeyPasswordIncorrect_E003 = _define( "ChaosCrypt_ERR_KeyPasswordIncorrect_E003", "KeyPasswordIncorrect", "E003", "The supplied key file password does not unlock this key file.", ) ChaosCrypt_ERR_KeyNotLoaded_E004 = _define( "ChaosCrypt_ERR_KeyNotLoaded_E004", "KeyNotLoaded", "E004", "An operation requiring key material was attempted before any key " "was loaded.", ) ChaosCrypt_ERR_KeyFileExists_E005 = _define( "ChaosCrypt_ERR_KeyFileExists_E005", "KeyFileExists", "E005", "The target key file already exists and overwriting was not permitted.", ) ChaosCrypt_ERR_EmptyPassword_E006 = _define( "ChaosCrypt_ERR_EmptyPassword_E006", "EmptyPassword", "E006", "A password was required but none was supplied.", ) ChaosCrypt_ERR_PasswordMismatch_E007 = _define( "ChaosCrypt_ERR_PasswordMismatch_E007", "PasswordMismatch", "E007", "The two password entries did not match.", ) ChaosCrypt_ERR_EmptyPlaintext_E008 = _define( "ChaosCrypt_ERR_EmptyPlaintext_E008", "EmptyPlaintext", "E008", "The plaintext to encrypt was empty.", ) ChaosCrypt_ERR_EmptyCiphertext_E009 = _define( "ChaosCrypt_ERR_EmptyCiphertext_E009", "EmptyCiphertext", "E009", "The ciphertext to decrypt was empty.", ) ChaosCrypt_ERR_MalformedCiphertext_E010 = _define( "ChaosCrypt_ERR_MalformedCiphertext_E010", "MalformedCiphertext", "E010", "The ciphertext is not valid hexadecimal or has an odd length.", ) ChaosCrypt_ERR_DecryptionFailed_E011 = _define( "ChaosCrypt_ERR_DecryptionFailed_E011", "DecryptionFailed", "E011", "Decryption did not produce valid data: the password is wrong, the key " "file does not match, or the ciphertext was altered.", ) ChaosCrypt_ERR_EncodingFailed_E012 = _define( "ChaosCrypt_ERR_EncodingFailed_E012", "EncodingFailed", "E012", "A Base64 or UTF-8 encode/decode step failed.", ) ChaosCrypt_ERR_InvalidArgument_E013 = _define( "ChaosCrypt_ERR_InvalidArgument_E013", "InvalidArgument", "E013", "An argument had an invalid type or value.", ) ChaosCrypt_ERR_FileReadFailed_E014 = _define( "ChaosCrypt_ERR_FileReadFailed_E014", "FileReadFailed", "E014", "Reading a file failed with an I/O error.", ) ChaosCrypt_ERR_FileWriteFailed_E015 = _define( "ChaosCrypt_ERR_FileWriteFailed_E015", "FileWriteFailed", "E015", "Writing a file failed with an I/O error.", ) ChaosCrypt_ERR_UnsupportedKeyVersion_E016 = _define( "ChaosCrypt_ERR_UnsupportedKeyVersion_E016", "UnsupportedKeyVersion", "E016", "The key file declares a format version this build cannot read.", ) ChaosCrypt_ERR_MissingMagicHeader_E017 = _define( "ChaosCrypt_ERR_MissingMagicHeader_E017", "MissingMagicHeader", "E017", "The input does not begin with the ChaosCrypt magic header. Every key file " "and ciphertext produced by this system carries a self-describing header; " "input without one is rejected outright.", ) ChaosCrypt_ERR_MalformedHeader_E018 = _define( "ChaosCrypt_ERR_MalformedHeader_E018", "MalformedHeader", "E018", "The ChaosCrypt header is present but could not be parsed: a marker is " "missing, the JSON is invalid, or a required field is absent.", )