Skip to main content

qualia_core_db/crypto/network/
rotation.rs

1//! Paired controller-key rotation and authorized recovery.
2//!
3//! Recovered key possession is not authority to use that material as a network
4//! signing instrument. Authority is a matching `ProviderGrant` generation on
5//! the admitted epoch. Signing with a revoked old epoch returns `Revoked`.
6
7use super::ed25519;
8use super::errors::CryptoError;
9use super::key_provider::ProviderGrant;
10use super::secret_lease::SecretLease;
11use super::types::{KeyEpoch, KeyPurpose, ED25519_SIG_LEN};
12
13/// Overlapping controller epochs. `revoked_old` forbids signatures under `old`.
14#[repr(C)]
15#[derive(Clone, Copy, Debug, PartialEq, Eq)]
16pub struct RotationState {
17    pub old: KeyEpoch,
18    pub new: KeyEpoch,
19    pub revoked_old: bool,
20}
21
22impl RotationState {
23    /// Pair old/new epochs for one controller and purpose. `new.epoch` must advance.
24    pub fn paired(old: KeyEpoch, new: KeyEpoch) -> Result<Self, CryptoError> {
25        if old.controller != new.controller {
26            return Err(CryptoError::Unauthorized);
27        }
28        if old.purpose != new.purpose {
29            return Err(CryptoError::Unauthorized);
30        }
31        if new.epoch <= old.epoch {
32            return Err(CryptoError::StaleGeneration);
33        }
34        Ok(Self {
35            old,
36            new,
37            revoked_old: false,
38        })
39    }
40
41    /// Revokes the previous-generation key material.
42    pub fn revoke_old(&mut self) {
43        self.revoked_old = true;
44    }
45
46    /// Sign under `requested` only when that epoch is admitted and the grant matches.
47    pub fn sign_ed25519(
48        &self,
49        grant: &ProviderGrant,
50        requested: KeyEpoch,
51        seed: &[u8; 32],
52        message: &[u8],
53        context: &[u8],
54        now_unix: u64,
55        controller: u64,
56        authority_generation: u64,
57        sig_out: &mut [u8; ED25519_SIG_LEN],
58    ) -> Result<(), CryptoError> {
59        if requested == self.old && self.revoked_old {
60            return Err(CryptoError::Revoked);
61        }
62        if requested != self.old && requested != self.new {
63            return Err(CryptoError::Unauthorized);
64        }
65        grant.authorize(
66            requested.purpose,
67            controller,
68            now_unix,
69            authority_generation,
70        )?;
71        if grant.epoch != requested {
72            return Err(CryptoError::Unauthorized);
73        }
74        ed25519::sign_with_context(seed, message, context, sig_out)
75    }
76
77    /// Recovery material may confirm a rotation onto `new`; it cannot be the grant.
78    pub fn admit_recovered_rotation(
79        &self,
80        recovered: &RecoveredPossession,
81        grant: &ProviderGrant,
82        now_unix: u64,
83        authority_generation: u64,
84    ) -> Result<(), CryptoError> {
85        recovered.confirms_controller(self.new.controller)?;
86        if grant.epoch != self.new {
87            return Err(CryptoError::Unauthorized);
88        }
89        grant.authorize(
90            self.new.purpose,
91            self.new.controller,
92            now_unix,
93            authority_generation,
94        )
95    }
96}
97
98/// Held recovered secret bytes. Possession does not confer network signing authority.
99pub struct RecoveredPossession {
100    controller: u64,
101    material: SecretLease,
102}
103
104impl RecoveredPossession {
105    /// Rebuilds a recovered possession for `controller` from `secret`.
106    pub fn from_bytes(controller: u64, secret: &[u8]) -> Result<Self, CryptoError> {
107        Ok(Self {
108            controller,
109            material: SecretLease::new(KeyPurpose::ControllerSign, secret)?,
110        })
111    }
112
113    /// `Ok` when `controller` matches; error on mismatch.
114    pub fn confirms_controller(&self, controller: u64) -> Result<(), CryptoError> {
115        let _ = self.material.purpose()?;
116        if self.controller != controller {
117            return Err(CryptoError::Unauthorized);
118        }
119        Ok(())
120    }
121
122    /// Recovered bytes are never a network signing oracle.
123    pub fn sign_ed25519(
124        &self,
125        _message: &[u8],
126        _context: &[u8],
127        _sig_out: &mut [u8; ED25519_SIG_LEN],
128    ) -> Result<(), CryptoError> {
129        let _ = self.material.purpose()?;
130        Err(CryptoError::Unauthorized)
131    }
132
133    /// Zeroizes the recovered secret.
134    pub fn destroy(&mut self) {
135        self.material.destroy();
136    }
137}
138
139impl core::fmt::Debug for RecoveredPossession {
140    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
141        f.debug_struct("RecoveredPossession")
142            .field("controller", &self.controller)
143            .field("material", &self.material)
144            .finish()
145    }
146}
147
148#[cfg(test)]
149mod tests {
150    use super::*;
151    use crate::crypto::network::ed25519::public_from_seed;
152    use crate::crypto::network::ed25519::verify_with_context;
153
154    fn epochs() -> (KeyEpoch, KeyEpoch) {
155        let old = KeyEpoch {
156            purpose: KeyPurpose::ControllerSign,
157            epoch: 1,
158            controller: 9,
159        };
160        let new = KeyEpoch {
161            purpose: KeyPurpose::ControllerSign,
162            epoch: 2,
163            controller: 9,
164        };
165        (old, new)
166    }
167
168    fn grant_for(epoch: KeyEpoch, generation: u64) -> ProviderGrant {
169        ProviderGrant {
170            epoch,
171            cell_epoch: 1,
172            authority_generation: generation,
173            deadline_unix: 100,
174            revoked: false,
175        }
176    }
177
178    #[test]
179    fn paired_epochs_must_share_controller_and_advance() {
180        let (old, mut new) = epochs();
181        new.controller = 8;
182        assert_eq!(
183            RotationState::paired(old, new).unwrap_err(),
184            CryptoError::Unauthorized
185        );
186        let (old, mut new) = epochs();
187        new.epoch = 1;
188        assert_eq!(
189            RotationState::paired(old, new).unwrap_err(),
190            CryptoError::StaleGeneration
191        );
192    }
193
194    #[test]
195    fn revoked_old_epoch_sign_fails_revoked() {
196        let (old, new) = epochs();
197        let mut state = RotationState::paired(old, new).unwrap();
198        state.revoke_old();
199        let grant = grant_for(old, 1);
200        let seed = [3u8; 32];
201        let mut sig = [0u8; ED25519_SIG_LEN];
202        assert_eq!(
203            state.sign_ed25519(&grant, old, &seed, b"m", b"c", 10, 9, 1, &mut sig),
204            Err(CryptoError::Revoked)
205        );
206        assert_eq!(sig, [0u8; ED25519_SIG_LEN]);
207    }
208
209    #[test]
210    fn new_epoch_sign_requires_matching_authority_generation() {
211        let (old, new) = epochs();
212        let state = RotationState::paired(old, new).unwrap();
213        let grant = grant_for(new, 4);
214        let seed = [3u8; 32];
215        let mut sig = [0u8; ED25519_SIG_LEN];
216        assert_eq!(
217            state.sign_ed25519(&grant, new, &seed, b"m", b"c", 10, 9, 3, &mut sig),
218            Err(CryptoError::StaleGeneration)
219        );
220        state
221            .sign_ed25519(&grant, new, &seed, b"m", b"c", 10, 9, 4, &mut sig)
222            .unwrap();
223        let pk = public_from_seed(&seed);
224        verify_with_context(&pk, b"m", b"c", &sig).unwrap();
225    }
226
227    #[test]
228    fn recovered_possession_is_not_signing_authority() {
229        let seed = [3u8; 32];
230        let recovered = RecoveredPossession::from_bytes(9, &seed).unwrap();
231        let mut sig = [0u8; ED25519_SIG_LEN];
232        assert_eq!(
233            recovered.sign_ed25519(b"m", b"c", &mut sig),
234            Err(CryptoError::Unauthorized)
235        );
236        assert_eq!(sig, [0u8; ED25519_SIG_LEN]);
237        let (old, new) = epochs();
238        let state = RotationState::paired(old, new).unwrap();
239        let grant_old = grant_for(old, 1);
240        assert_eq!(
241            state.admit_recovered_rotation(&recovered, &grant_old, 10, 1),
242            Err(CryptoError::Unauthorized)
243        );
244        let grant_new = grant_for(new, 1);
245        state
246            .admit_recovered_rotation(&recovered, &grant_new, 10, 1)
247            .unwrap();
248        assert_eq!(
249            state.admit_recovered_rotation(&recovered, &grant_new, 10, 9),
250            Err(CryptoError::StaleGeneration)
251        );
252    }
253
254    #[test]
255    fn recovered_destroy_rejects_later_confirm() {
256        let mut recovered = RecoveredPossession::from_bytes(9, &[3u8; 32]).unwrap();
257        recovered.destroy();
258        assert_eq!(
259            recovered.confirms_controller(9).unwrap_err(),
260            CryptoError::Revoked
261        );
262        let mut sig = [0u8; ED25519_SIG_LEN];
263        assert_eq!(
264            recovered.sign_ed25519(b"m", b"c", &mut sig),
265            Err(CryptoError::Revoked)
266        );
267    }
268
269    #[test]
270    fn grant_epoch_must_match_requested_slot() {
271        let (old, new) = epochs();
272        let state = RotationState::paired(old, new).unwrap();
273        let grant_new = grant_for(new, 1);
274        let seed = [3u8; 32];
275        let mut sig = [0u8; ED25519_SIG_LEN];
276        assert_eq!(
277            state.sign_ed25519(&grant_new, old, &seed, b"m", b"c", 10, 9, 1, &mut sig),
278            Err(CryptoError::Unauthorized)
279        );
280    }
281
282    #[test]
283    fn debug_redacts_recovered_secret() {
284        let recovered = RecoveredPossession::from_bytes(9, &[3u8; 32]).unwrap();
285        let rendered = format!("{:?}", recovered);
286        assert!(rendered.contains("RecoveredPossession"));
287        assert!(rendered.contains("SecretLease"));
288        assert!(!rendered.contains("bytes"));
289    }
290}