Skip to main content

qualia_peer/
negotiate.rs

1//! E20.3 capability/version negotiation, anti-rollback, signed update bytes.
2//!
3//! A boolean `signed=true` is not an API and is not accepted as proof.
4
5use qualia_core_db::crypto::network::digest::sha384;
6use qualia_core_db::crypto::network::transcript::Transcript;
7use qualia_core_db::net::qdnf::errors::QdnfError;
8use qualia_core_db::net::qdnf::types::{Generation, StrongDigest};
9
10/// Pinned capability identity: SHA-384 transcript digest plus generation.
11#[derive(Clone, Copy, Debug, PartialEq, Eq)]
12pub struct CapabilityVersion {
13    pub digest: StrongDigest,
14    pub generation: Generation,
15}
16
17/// Pin a capability to a version digest. Empty id or generation 0 is rejected.
18pub fn pin_capability_version(
19    capability: &[u8],
20    generation: Generation,
21) -> Result<CapabilityVersion, QdnfError> {
22    if capability.is_empty() {
23        return Err(QdnfError::Malformed);
24    }
25    if generation == Generation::ZERO {
26        return Err(QdnfError::Unauthorized);
27    }
28    let mut t = Transcript::new();
29    t.append(b"qdnf-cap-version", capability)?;
30    t.append(b"generation", &generation.0.to_be_bytes())?;
31    Ok(CapabilityVersion {
32        digest: t.digest(),
33        generation,
34    })
35}
36
37/// Anti-rollback: an offered generation older than `min` is StaleGeneration.
38pub fn admit_capability_generation(offered: Generation, min: Generation) -> Result<(), QdnfError> {
39    if min == Generation::ZERO || offered == Generation::ZERO {
40        return Err(QdnfError::Unauthorized);
41    }
42    if offered.0 < min.0 {
43        return Err(QdnfError::StaleGeneration);
44    }
45    Ok(())
46}
47
48/// Admit a peer only when generation is current and the pinned digest matches.
49pub fn negotiate_capability(
50    local: CapabilityVersion,
51    peer_generation: Generation,
52    peer_digest: StrongDigest,
53) -> Result<StrongDigest, QdnfError> {
54    if local.digest.is_zero() || peer_digest.is_zero() {
55        return Err(QdnfError::Malformed);
56    }
57    admit_capability_generation(peer_generation, local.generation)?;
58    if peer_digest != local.digest {
59        return Err(QdnfError::Conflict);
60    }
61    Ok(local.digest)
62}
63
64/// Signed update metadata: exact SHA-384 of the bytes. No `signed` flag.
65pub fn verify_update_bytes(expected: StrongDigest, bytes: &[u8]) -> Result<(), QdnfError> {
66    if bytes.is_empty() || expected.is_zero() {
67        return Err(QdnfError::Malformed);
68    }
69    let got = sha384(bytes);
70    if got != expected {
71        return Err(QdnfError::Conflict);
72    }
73    Ok(())
74}
75
76#[cfg(test)]
77mod tests {
78    use super::*;
79
80    #[test]
81    fn pin_is_digest_of_capability_and_generation() {
82        let a = pin_capability_version(b"qpr-v1", Generation(3)).unwrap();
83        let b = pin_capability_version(b"qpr-v1", Generation(3)).unwrap();
84        let other_id = pin_capability_version(b"qpr-v2", Generation(3)).unwrap();
85        let other_gen = pin_capability_version(b"qpr-v1", Generation(4)).unwrap();
86        assert_eq!(a.digest, b.digest);
87        assert_ne!(a.digest, StrongDigest::ZERO);
88        assert_ne!(a.digest, other_id.digest);
89        assert_ne!(a.digest, other_gen.digest);
90        assert_eq!(
91            pin_capability_version(b"", Generation(1)),
92            Err(QdnfError::Malformed)
93        );
94        assert_eq!(
95            pin_capability_version(b"qpr-v1", Generation::ZERO),
96            Err(QdnfError::Unauthorized)
97        );
98    }
99
100    #[test]
101    fn older_generation_is_stale_not_admitted() {
102        let min = Generation(5);
103        assert_eq!(
104            admit_capability_generation(Generation(4), min),
105            Err(QdnfError::StaleGeneration)
106        );
107        assert!(admit_capability_generation(Generation(5), min).is_ok());
108        assert!(admit_capability_generation(Generation(6), min).is_ok());
109        assert_eq!(
110            admit_capability_generation(Generation::ZERO, min),
111            Err(QdnfError::Unauthorized)
112        );
113    }
114
115    #[test]
116    fn negotiate_requires_matching_digest_and_current_generation() {
117        let local = pin_capability_version(b"qpr-v1", Generation(2)).unwrap();
118        assert_eq!(
119            negotiate_capability(local, Generation(1), local.digest),
120            Err(QdnfError::StaleGeneration)
121        );
122        let other = pin_capability_version(b"qpr-v2", Generation(2)).unwrap();
123        assert_eq!(
124            negotiate_capability(local, Generation(2), other.digest),
125            Err(QdnfError::Conflict)
126        );
127        assert_eq!(
128            negotiate_capability(local, Generation(2), local.digest).unwrap(),
129            local.digest
130        );
131    }
132
133    #[test]
134    fn update_metadata_requires_exact_bytes_hash() {
135        let bytes = b"qdnf-update-artifact-v1";
136        let digest = sha384(bytes);
137        assert!(verify_update_bytes(digest, bytes).is_ok());
138        assert_eq!(
139            verify_update_bytes(digest, b"tampered-artifact"),
140            Err(QdnfError::Conflict)
141        );
142        assert_eq!(verify_update_bytes(digest, b""), Err(QdnfError::Malformed));
143        assert_eq!(
144            verify_update_bytes(StrongDigest::ZERO, bytes),
145            Err(QdnfError::Malformed)
146        );
147        let matching_wrong = sha384(b"other-bytes");
148        assert_eq!(
149            verify_update_bytes(matching_wrong, bytes),
150            Err(QdnfError::Conflict)
151        );
152    }
153}