appcore-dnt 1.0.3-rc

Authenticated encrypted binary container contracts for AppCore Runtime.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

// =============================================================================
//        #######
//     ###       ###     F: error.rs
//    ##   ## ##   ##    P: AppCore-Runtime
//         ## ##
//                       C: 2026/08/02 00:04:12 by dnettoRaw
//    ##   ## ##   ##    U: 2026/08/02 10:29:16 by dnettoRaw
//      ###########      S: 1.0.1-rc.8
// =============================================================================

//! DNT error contracts.

/// DNT-local result type.
pub type DntResult<T> = Result<T, DntError>;

/// Controlled DNT failures.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum DntError {
    /// The bytes do not contain a structurally valid DNT envelope.
    #[error("invalid DNT container")]
    InvalidFormat,
    /// The envelope version is newer or otherwise unsupported.
    #[error("unsupported DNT envelope version")]
    UnsupportedVersion,
    /// The configured maximum payload size would be exceeded.
    #[error("DNT payload exceeds configured limit")]
    PayloadTooLarge,
    /// The envelope contains an impossible or unsupported flag combination.
    #[error("DNT flags are invalid")]
    InvalidFlags,
    /// The envelope is not bound to the expected context.
    #[error("DNT context mismatch")]
    ContextMismatch,
    /// The key provider could not return usable material.
    #[error("DNT key is unavailable")]
    KeyUnavailable,
    /// AEAD authentication failed.
    #[error("DNT authentication failed")]
    AuthenticationFailed,
    /// The codec identifier is unknown or incompatible.
    #[error("DNT codec is unavailable")]
    CodecUnavailable,
    /// Encoding or decoding failed without exposing payload material.
    #[error("DNT codec failed")]
    CodecFailed,
    /// Filesystem persistence failed.
    #[error("DNT I/O failed")]
    Io,
}

/// Controlled key-provider failures.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum DntKeyError {
    /// The requested key identity is unknown.
    #[error("DNT key was not found")]
    NotFound,
    /// The key provider is intentionally unavailable.
    #[error("DNT key provider is unavailable")]
    Unavailable,
    /// The resolved key material is malformed.
    #[error("DNT key material is invalid")]
    InvalidKey,
    /// The key is not valid for the supplied context.
    #[error("DNT key is not valid for the requested context")]
    Forbidden,
}

/// Controlled codec failures.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum CodecError {
    /// The codec cannot encode the supplied bytes.
    #[error("DNT codec encode failed")]
    EncodeFailed,
    /// The codec cannot decode the supplied bytes.
    #[error("DNT codec decode failed")]
    DecodeFailed,
    /// The payload violates a codec-specific bound.
    #[error("DNT codec payload is too large")]
    PayloadTooLarge,
}

impl From<DntKeyError> for DntError {
    fn from(value: DntKeyError) -> Self {
        match value {
            DntKeyError::NotFound | DntKeyError::Unavailable => Self::KeyUnavailable,
            DntKeyError::InvalidKey => Self::KeyUnavailable,
            DntKeyError::Forbidden => Self::ContextMismatch,
        }
    }
}

impl From<CodecError> for DntError {
    fn from(_: CodecError) -> Self {
        Self::CodecFailed
    }
}