bc_envelope/base/

error.rs

use thiserror::Error;

/// Error types returned when operating on Gordian Envelopes.
///
/// These errors capture various conditions that can occur when working with envelopes,
/// including structure validation, operation constraints, and extension-specific errors.
///
/// The errors are organized by category, reflecting the base envelope specification
/// and various extensions defined in the Gordian Envelope Internet Draft and Blockchain
/// Commons Research (BCR) documents.
#[derive(Debug, Error)]
pub enum Error {
    //
    // Base Specification
    //

    /// Returned when attempting to compress or encrypt an envelope that has already been elided.
    ///
    /// This error occurs because an elided envelope only contains a digest reference and no longer
    /// has a subject that can be compressed or encrypted.
    #[error("envelope was elided, so it cannot be compressed or encrypted")]
    AlreadyElided,

    /// Returned when attempting to retrieve an assertion by predicate, but multiple matching
    /// assertions exist.
    ///
    /// For queries that expect a single result (like `object_for_predicate`), having multiple
    /// matching assertions is ambiguous and requires more specific targeting.
    #[error("more than one assertion matches the predicate")]
    AmbiguousPredicate,

    /// Returned when a digest validation fails.
    ///
    /// This can occur when unwrapping an envelope, verifying signatures, or other operations
    /// that rely on the integrity of envelope digests.
    #[error("digest did not match")]
    InvalidDigest,

    /// Returned when an envelope's format is invalid.
    ///
    /// This typically occurs during parsing or decoding of an envelope from CBOR.
    #[error("invalid format")]
    InvalidFormat,

    /// Returned when a digest is expected but not found.
    ///
    /// This can occur when working with envelope structures that require digest information,
    /// such as when working with elided envelopes.
    #[error("a digest was expected but not found")]
    MissingDigest,

    /// Returned when attempting to retrieve an assertion by predicate, but no matching
    /// assertion exists.
    ///
    /// This error occurs with functions like `object_for_predicate` when the specified
    /// predicate doesn't match any assertion in the envelope.
    #[error("no assertion matches the predicate")]
    NonexistentPredicate,

    /// Returned when attempting to unwrap an envelope that wasn't wrapped.
    ///
    /// This error occurs when calling `Envelope::unwrap_envelope` on an envelope
    /// that doesn't have the wrapped format.
    #[error("cannot unwrap an envelope that was not wrapped")]
    NotWrapped,

    /// Returned when expecting an envelope's subject to be a leaf, but it isn't.
    ///
    /// This error occurs when calling methods that require access to a leaf value
    /// but the envelope's subject is an assertion, node, or elided.
    #[error("the envelope's subject is not a leaf")]
    NotLeaf,

    /// Returned when expecting an envelope's subject to be an assertion, but it isn't.
    ///
    /// This error occurs when calling methods that require an assertion structure
    /// but the envelope's subject has a different format.
    #[error("the envelope's subject is not an assertion")]
    NotAssertion,

    /// Returned
    #[error("assertion must be a map with exactly one element")]
    InvalidAssertion,

    //
    // Attachments Extension
    //

    /// Returned when an attachment's format is invalid.
    ///
    /// This error occurs when an envelope contains an attachment with an invalid structure
    /// according to the Envelope Attachment specification (BCR-2023-006).
    #[cfg(feature = "attachment")]
    #[error("invalid attachment")]
    InvalidAttachment,

    /// Returned when an attachment is requested but does not exist.
    ///
    /// This error occurs when attempting to retrieve an attachment by ID that
    /// doesn't exist in the envelope.
    #[cfg(feature = "attachment")]
    #[error("nonexistent attachment")]
    NonexistentAttachment,

    /// Returned when multiple attachments match a single query.
    ///
    /// This error occurs when multiple attachments have the same ID, making
    /// it ambiguous which attachment should be returned.
    #[cfg(feature = "attachment")]
    #[error("abiguous attachment")]
    AmbiguousAttachment,

    //
    // Compression Extension
    //

    /// Returned when attempting to compress an envelope that is already compressed.
    ///
    /// This error occurs when calling compression functions on an envelope that
    /// already has compressed content, as defined in BCR-2023-005.
    #[cfg(feature = "compress")]
    #[error("envelope was already compressed")]
    AlreadyCompressed,

    /// Returned when attempting to uncompress an envelope that is not compressed.
    ///
    /// This error occurs when calling uncompression functions on an envelope that
    /// doesn't contain compressed content.
    #[cfg(feature = "compress")]
    #[error("cannot uncompress an envelope that was not compressed")]
    NotCompressed,

    //
    // Symmetric Encryption Extension
    //

    /// Returned when attempting to encrypt an envelope that is already encrypted or compressed.
    ///
    /// This error occurs to prevent multiple layers of encryption or encryption of
    /// compressed data, which could reduce security, as defined in BCR-2023-004.
    #[cfg(feature = "encrypt")]
    #[error("envelope was already encrypted or compressed, so it cannot be encrypted")]
    AlreadyEncrypted,

    /// Returned when attempting to decrypt an envelope that is not encrypted.
    ///
    /// This error occurs when calling decryption functions on an envelope that
    /// doesn't contain encrypted content.
    #[cfg(feature = "encrypt")]
    #[error("cannot decrypt an envelope that was not encrypted")]
    NotEncrypted,

    //
    // Known Values Extension
    //

    /// Returned when expecting an envelope's subject to be a known value, but it isn't.
    ///
    /// This error occurs when calling methods that require a known value (as defined in
    /// BCR-2023-003) but the envelope's subject is a different type.
    #[cfg(feature = "known_value")]
    #[error("the envelope's subject is not a known value")]
    NotKnownValue,

    //
    // Public Key Encryption Extension
    //

    /// Returned when attempting to decrypt an envelope with a recipient that doesn't match.
    ///
    /// This error occurs when trying to use a private key to decrypt an envelope that
    /// wasn't encrypted for the corresponding public key.
    #[cfg(feature = "recipient")]
    #[error("unknown recipient")]
    UnknownRecipient,

    //
    // Encrypted Key Extension
    //

    /// Returned when attempting to decrypt an envelope with a secret that
    /// doesn't match.
    ///
    /// This error occurs when trying to use a secret that does not correspond
    /// to the expected recipient, preventing successful decryption.
    #[cfg(feature = "secret")]
    #[error("secret not found")]
    UnknownSecret,

    //
    // Public Key Signing Extension
    //

    /// Returned when a signature verification fails.
    ///
    /// This error occurs when a signature does not validate against its purported
    /// public key.
    #[cfg(feature = "signature")]
    #[error("could not verify a signature")]
    UnverifiedSignature,

    /// Returned when the outer signature object type is not `Signature`.
    #[cfg(feature = "signature")]
    #[error("unexpected outer signature object type")]
    InvalidOuterSignatureType,

    /// Returned when the inner signature object type is not `Signature`.
    #[cfg(feature = "signature")]
    #[error("unexpected inner signature object type")]
    InvalidInnerSignatureType,

    /// Returned when the inner signature is not made with the same key as the outer signature.
    #[cfg(feature = "signature")]
    #[error("inner signature not made with same key as outer signature")]
    UnverifiedInnerSignature,

    /// Returned when the signature object is not a `Signature`.
    #[cfg(feature = "signature")]
    #[error("unexpected signature object type")]
    InvalidSignatureType,

    //
    // SSKR Extension
    //

    /// Returned when SSKR shares are invalid or insufficient for reconstruction.
    ///
    /// This error occurs when attempting to join SSKR shares that are malformed,
    /// from different splits, or insufficient to meet the recovery threshold.
    #[cfg(feature = "sskr")]
    #[error("invalid SSKR shares")]
    InvalidShares,

    //
    // Types Extension
    //

    /// Returned when an envelope contains an invalid type.
    ///
    /// This error occurs when an envelope's type information doesn't match
    /// the expected format or value.
    #[cfg(feature = "types")]
    #[error("invalid type")]
    InvalidType,

    /// Returned when an envelope contains ambiguous type information.
    ///
    /// This error occurs when multiple type assertions exist that conflict
    /// with each other or create ambiguity about the envelope's type.
    #[cfg(feature = "types")]
    #[error("ambiguous type")]
    AmbiguousType,

    //
    // Expressions Extension
    //

    /// Returned when a response envelope has an unexpected ID.
    ///
    /// This error occurs when processing a response envelope and the ID doesn't
    /// match the expected request ID, as defined in BCR-2023-012.
    #[cfg(feature = "expression")]
    #[error("unexpected response ID")]
    UnexpectedResponseID,

    /// Returned when a response envelope is invalid.
    #[cfg(feature = "expression")]
    #[error("invalid response")]
    InvalidResponse,

    /// dcbor error
    #[error("dcbor error: {0}")]
    DCBOR(#[from] dcbor::Error),
}

pub type Result<T> = std::result::Result<T, Error>;