Skip to main content

qualia_core_db/net/qdnf/contracts/compile/
mod.rs

1//! Compiled contract admission. Unknown required semantics cannot become Allow.
2
3pub mod verify;
4
5use crate::net::qdnf::authority::PolicyOutcome;
6use crate::net::qdnf::errors::QdnfError;
7use crate::net::qdnf::types::StrongDigest;
8
9pub use verify::verify_exact_bytes;
10
11/// Pinned contract view. Vocabulary membership is stored as digests filled by
12/// the verifier from a known-vocab table, not as a caller boolean.
13#[repr(C)]
14#[derive(Clone, Copy, Debug, PartialEq, Eq)]
15pub struct ContractBundle {
16    pub exact_bytes_digest: StrongDigest,
17    pub context_digest: StrongDigest,
18    pub ontology_digest: StrongDigest,
19    pub shape_digest: StrongDigest,
20    pub rules_digest: StrongDigest,
21    /// Vocabulary the artifact requires. Zero means unknown required semantics.
22    pub required_vocab_digest: StrongDigest,
23    /// Local known-vocabulary table digest bound by the verifier.
24    pub known_vocab_digest: StrongDigest,
25}
26
27impl ContractBundle {
28    #[inline]
29    /// `ContractBundle::exact_bytes_unsigned`.
30    pub const fn exact_bytes_unsigned(&self) -> bool {
31        self.exact_bytes_digest.is_zero()
32    }
33
34    /// Bind the local known-vocabulary table. Callers of [`compile_decision`]
35    /// must not invent a matching pair to mean “signed”.
36    #[inline]
37    pub fn bind_known_vocabulary(&mut self, known_vocab_digest: StrongDigest) {
38        self.known_vocab_digest = known_vocab_digest;
39    }
40
41    #[inline]
42    /// `ContractBundle::required_vocabulary_known`.
43    pub fn required_vocabulary_known(&self) -> bool {
44        !self.required_vocab_digest.is_zero()
45            && !self.known_vocab_digest.is_zero()
46            && self.required_vocab_digest == self.known_vocab_digest
47    }
48}
49
50/// Admit a compiled view only when exact original bytes hash to the bundle
51/// digest, expected shape/rules/context/ontology/vocabulary match, and the
52/// required vocabulary is present in the verifier's known table.
53///
54/// There is no `signed` / `supported` boolean. Empty bytes are malformed.
55/// Vocabulary mismatch is [`PolicyOutcome::Incomplete`] (no `Unsupported`
56/// variant exists on [`PolicyOutcome`]); it is never [`PolicyOutcome::Allow`].
57pub fn compile_decision(
58    bundle: &ContractBundle,
59    expected: &ContractBundle,
60    original_bytes: &[u8],
61) -> Result<PolicyOutcome, QdnfError> {
62    verify_exact_bytes(bundle.exact_bytes_digest, original_bytes)?;
63    if bundle.exact_bytes_unsigned() {
64        return Err(QdnfError::Malformed);
65    }
66    if bundle.exact_bytes_digest != expected.exact_bytes_digest
67        || bundle.context_digest != expected.context_digest
68        || bundle.ontology_digest != expected.ontology_digest
69        || bundle.shape_digest != expected.shape_digest
70        || bundle.rules_digest != expected.rules_digest
71        || bundle.required_vocab_digest != expected.required_vocab_digest
72    {
73        return Err(QdnfError::Conflict);
74    }
75    if bundle.required_vocab_digest.is_zero() || bundle.known_vocab_digest.is_zero() {
76        return Ok(PolicyOutcome::Incomplete);
77    }
78    if bundle.required_vocab_digest != bundle.known_vocab_digest {
79        // Unknown or unsupported required vocabulary. PolicyOutcome has no
80        // Unsupported variant; Incomplete must never become Allow.
81        return Ok(PolicyOutcome::Incomplete);
82    }
83    Ok(PolicyOutcome::Allow)
84}
85
86#[cfg(test)]
87mod tests {
88    use super::*;
89    use crate::crypto::network::digest::sha384;
90
91    const BYTES: &[u8] = b"qdnf-contract-v1-artifact";
92
93    fn vocab() -> StrongDigest {
94        StrongDigest([0x11; 48])
95    }
96
97    fn other_vocab() -> StrongDigest {
98        StrongDigest([0x22; 48])
99    }
100
101    fn pinned_bundle(bytes: &[u8]) -> ContractBundle {
102        let digest = sha384(bytes);
103        ContractBundle {
104            exact_bytes_digest: digest,
105            context_digest: StrongDigest([0xA1; 48]),
106            ontology_digest: StrongDigest([0xA2; 48]),
107            shape_digest: StrongDigest([0xA3; 48]),
108            rules_digest: StrongDigest([0xA4; 48]),
109            required_vocab_digest: vocab(),
110            known_vocab_digest: vocab(),
111        }
112    }
113
114    #[test]
115    fn real_bytes_allow() {
116        let bundle = pinned_bundle(BYTES);
117        assert_eq!(
118            compile_decision(&bundle, &bundle, BYTES).unwrap(),
119            PolicyOutcome::Allow
120        );
121    }
122
123    #[test]
124    fn attacker_matching_digest_without_bytes_is_malformed() {
125        let bundle = pinned_bundle(BYTES);
126        assert_eq!(
127            compile_decision(&bundle, &bundle, b""),
128            Err(QdnfError::Malformed)
129        );
130    }
131
132    #[test]
133    fn tampered_bytes_are_conflict() {
134        let bundle = pinned_bundle(BYTES);
135        assert_eq!(
136            compile_decision(&bundle, &bundle, b"tampered-not-original"),
137            Err(QdnfError::Conflict)
138        );
139    }
140
141    #[test]
142    fn forged_digest_with_other_bytes_is_conflict() {
143        let mut bundle = pinned_bundle(BYTES);
144        bundle.exact_bytes_digest = sha384(b"different-preimage");
145        let mut expected = bundle;
146        expected.exact_bytes_digest = bundle.exact_bytes_digest;
147        assert_eq!(
148            compile_decision(&bundle, &expected, BYTES),
149            Err(QdnfError::Conflict)
150        );
151    }
152
153    #[test]
154    fn zero_exact_bytes_are_malformed() {
155        let mut bundle = pinned_bundle(BYTES);
156        bundle.exact_bytes_digest = StrongDigest::ZERO;
157        assert_eq!(
158            compile_decision(&bundle, &bundle, BYTES),
159            Err(QdnfError::Malformed)
160        );
161    }
162
163    #[test]
164    fn unknown_required_vocab_is_incomplete_not_allow() {
165        let mut bundle = pinned_bundle(BYTES);
166        bundle.required_vocab_digest = other_vocab();
167        bundle.bind_known_vocabulary(vocab());
168        let expected = bundle;
169        let outcome = compile_decision(&bundle, &expected, BYTES).unwrap();
170        assert_eq!(outcome, PolicyOutcome::Incomplete);
171        assert_ne!(outcome, PolicyOutcome::Allow);
172    }
173
174    #[test]
175    fn zero_required_vocab_is_incomplete_not_allow() {
176        let mut bundle = pinned_bundle(BYTES);
177        bundle.required_vocab_digest = StrongDigest::ZERO;
178        let expected = bundle;
179        assert_eq!(
180            compile_decision(&bundle, &expected, BYTES).unwrap(),
181            PolicyOutcome::Incomplete
182        );
183    }
184
185    #[test]
186    fn shape_digest_mismatch_is_conflict() {
187        let bundle = pinned_bundle(BYTES);
188        let mut expected = bundle;
189        expected.shape_digest = StrongDigest([9u8; 48]);
190        assert_eq!(
191            compile_decision(&bundle, &expected, BYTES),
192            Err(QdnfError::Conflict)
193        );
194    }
195
196    #[test]
197    fn rules_digest_mismatch_is_conflict() {
198        let bundle = pinned_bundle(BYTES);
199        let mut expected = bundle;
200        expected.rules_digest = StrongDigest([9u8; 48]);
201        assert_eq!(
202            compile_decision(&bundle, &expected, BYTES),
203            Err(QdnfError::Conflict)
204        );
205    }
206
207    #[test]
208    fn context_digest_mismatch_is_conflict() {
209        let bundle = pinned_bundle(BYTES);
210        let mut expected = bundle;
211        expected.context_digest = StrongDigest([9u8; 48]);
212        assert_eq!(
213            compile_decision(&bundle, &expected, BYTES),
214            Err(QdnfError::Conflict)
215        );
216    }
217
218    #[test]
219    fn ontology_digest_mismatch_is_conflict() {
220        let bundle = pinned_bundle(BYTES);
221        let mut expected = bundle;
222        expected.ontology_digest = StrongDigest([9u8; 48]);
223        assert_eq!(
224            compile_decision(&bundle, &expected, BYTES),
225            Err(QdnfError::Conflict)
226        );
227    }
228
229    #[test]
230    fn required_vocab_pin_mismatch_is_conflict() {
231        let bundle = pinned_bundle(BYTES);
232        let mut expected = bundle;
233        expected.required_vocab_digest = other_vocab();
234        assert_eq!(
235            compile_decision(&bundle, &expected, BYTES),
236            Err(QdnfError::Conflict)
237        );
238    }
239}