tawasuyu/brahman

1//! Identidad multi-key del nodo: separación entre **identity** (master,
2//! persistente forever) y **session** (keypair libp2p efímera, rotable).
3//!
4//! ## Problema que resuelve
5//!
6//! Hasta Fase 3, el `peer_id` libp2p era la única identidad. Rotar la
7//! keypair (por compromiso, por higiene, por cambio de hardware)
8//! cambiaba el peer_id, lo que invalidaba todas las allowlists
9//! remotas y desconectaba al nodo de la malla. Imposible rotar sin
10//! coordinar.
11//!
12//! ## Modelo
13//!
14//! Cada nodo tiene **dos** keypairs Ed25519:
15//!
16//! - **Identity** (master): persistente para siempre. Identifica al
17//!   nodo como entidad lógica. Su `peer_id` es lo que va en
18//!   allowlists/denylists remotas.
19//! - **Session** (operacional): la que libp2p usa para Noise. Puede
20//!   rotarse libremente sin coordinar — el nodo emite un
21//!   [`SessionCert`] firmado con la identity que prueba "esta session
22//!   key pertenece a mí".
23//!
24//! ## Wire
25//!
26//! El cert viaja en `Hello.identity_cert: Option<SessionCert>`. El
27//! server valida:
28//! 1. La session key del cert == public key de `Hello.signature` ==
29//!    deriva al peer_id autenticado por Noise (consistencia interna).
30//! 2. La firma del cert verifica con la master pubkey declarada.
31//! 3. El cert no está expirado.
32//! 4. La política (allowlist/denylist) se evalúa contra
33//!    `master.to_peer_id()`, NO contra el session peer_id.
34//!
35//! Sin cert, el server cae al modelo de Fase 3: policy contra session
36//! peer_id (compat). Esto permite migración gradual.
37
38use std::sync::Arc;
39use std::time::{Duration, SystemTime, UNIX_EPOCH};
40
41use brahman_net::{Keypair, PeerId, PublicKey};
42use serde::{Deserialize, Serialize};
43
44/// TTL recomendado para un session cert: 24 horas. Suficiente para
45/// que un nodo "viva" un día sin re-emitir; corto enough para que
46/// un cert robado no sirva por mucho. Operadores con políticas
47/// estrictas pueden bajarlo; con uptime largo, subirlo.
48pub const DEFAULT_SESSION_TTL: Duration = Duration::from_secs(24 * 60 * 60);
49
50/// Identidad lógica del nodo. Wraps la master keypair y emite certs
51/// de session firmados.
52///
53/// **Critical**: la master keypair NUNCA debe filtrarse a la red.
54/// Sólo se usa para firmar certs locales y para derivar
55/// `master_peer_id`. Ni siquiera el swarm libp2p la ve — ese usa la
56/// session keypair.
57#[derive(Clone)]
58pub struct Identity {
59    master: Arc<Keypair>,
60}
61
62impl Identity {
63    /// Construye una Identity a partir de una keypair existente.
64    /// Típicamente cargada desde disco vía `keypair_store::load_or_generate`.
65    pub fn from_keypair(master: Keypair) -> Self {
66        Self {
67            master: Arc::new(master),
68        }
69    }
70
71    /// Variante para callers que ya tienen la keypair en `Arc`.
72    pub fn from_arc(master: Arc<Keypair>) -> Self {
73        Self { master }
74    }
75
76    /// PeerId derivado de la master pubkey. Ésta es la identidad
77    /// "lógica" estable del nodo — lo que va en allowlists/denylists.
78    pub fn master_peer_id(&self) -> PeerId {
79        self.master.public().to_peer_id()
80    }
81
82    /// Emite un [`SessionCert`] firmado: certifica que la session
83    /// keypair `session` pertenece a esta identity hasta `now + ttl`.
84    pub fn issue_session_cert(
85        &self,
86        session: &Keypair,
87        ttl: Duration,
88    ) -> Result<SessionCert, CertError> {
89        let now_ms = now_unix_ms();
90        let expires_at_ms = now_ms.saturating_add(ttl.as_millis() as u64);
91        let session_pubkey = session.public().encode_protobuf();
92        let master_pubkey = self.master.public().encode_protobuf();
93        let payload = sign_payload(&session_pubkey, expires_at_ms);
94        let signature = self
95            .master
96            .sign(&payload)
97            .map_err(|e| CertError::Sign(e.to_string()))?;
98        Ok(SessionCert {
99            version: SESSION_CERT_VERSION,
100            session_pubkey,
101            master_pubkey,
102            expires_at_ms,
103            signature,
104        })
105    }
106}
107
108impl std::fmt::Debug for Identity {
109    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
110        f.debug_struct("Identity")
111            .field("master_peer_id", &self.master_peer_id())
112            .finish()
113    }
114}
115
116/// Versión del esquema del cert. Bump al cambiar `sign_payload` o
117/// el shape de `SessionCert`.
118pub const SESSION_CERT_VERSION: u8 = 1;
119
120/// Certificado firmado por la identity que vincula una session key
121/// libp2p a la identidad master del nodo, con expiración.
122///
123/// **Wire**: viaja en `Hello.identity_cert`. Las pubkeys van en
124/// formato canónico libp2p (`encode_protobuf`) — mismo encoding que
125/// `HelloSignature.public_key`.
126#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
127pub struct SessionCert {
128    /// Versión del esquema (ver `SESSION_CERT_VERSION`).
129    pub version: u8,
130    /// Public key de la session libp2p (la que firma el Hello), en
131    /// formato libp2p protobuf.
132    pub session_pubkey: Vec<u8>,
133    /// Public key de la master identity, en formato libp2p protobuf.
134    /// El verificador deriva el `master_peer_id` desde acá.
135    pub master_pubkey: Vec<u8>,
136    /// Expiración en milisegundos desde UNIX_EPOCH. Tras esto, el
137    /// cert no es válido y el nodo debe re-emitirse uno nuevo
138    /// (rotando o re-firmando la misma session).
139    pub expires_at_ms: u64,
140    /// Firma Ed25519 del master sobre `sign_payload(session_pubkey, expires_at_ms)`.
141    pub signature: Vec<u8>,
142}
143
144#[derive(Debug, thiserror::Error)]
145pub enum CertError {
146    #[error("versión de cert desconocida: {0} (esperaba {SESSION_CERT_VERSION})")]
147    UnknownVersion(u8),
148    #[error("decode master_pubkey: {0}")]
149    DecodeMaster(String),
150    #[error("decode session_pubkey: {0}")]
151    DecodeSession(String),
152    #[error("firma del cert inválida")]
153    InvalidSignature,
154    #[error("cert expirado: expires_at_ms={expires}, now_ms={now}")]
155    Expired { expires: u64, now: u64 },
156    #[error("session_pubkey del cert no coincide con la del Hello.signature")]
157    SessionMismatch,
158    #[error("error al firmar: {0}")]
159    Sign(String),
160}
161
162impl SessionCert {
163    /// Verifica el cert: versión, firma criptográfica, no expiración.
164    /// Devuelve el `(master_peer_id, session_peer_id)` derivados.
165    ///
166    /// El caller debe además chequear que `session_peer_id` coincide
167    /// con el peer_id autenticado por Noise (lo verifica
168    /// [`verify_against_session`]).
169    pub fn verify(&self) -> Result<(PeerId, PeerId), CertError> {
170        if self.version != SESSION_CERT_VERSION {
171            return Err(CertError::UnknownVersion(self.version));
172        }
173        let master_pk = PublicKey::try_decode_protobuf(&self.master_pubkey)
174            .map_err(|e| CertError::DecodeMaster(e.to_string()))?;
175        let session_pk = PublicKey::try_decode_protobuf(&self.session_pubkey)
176            .map_err(|e| CertError::DecodeSession(e.to_string()))?;
177        let payload = sign_payload(&self.session_pubkey, self.expires_at_ms);
178        if !master_pk.verify(&payload, &self.signature) {
179            return Err(CertError::InvalidSignature);
180        }
181        let now = now_unix_ms();
182        if now >= self.expires_at_ms {
183            return Err(CertError::Expired {
184                expires: self.expires_at_ms,
185                now,
186            });
187        }
188        Ok((master_pk.to_peer_id(), session_pk.to_peer_id()))
189    }
190
191    /// Verifica el cert Y exige que su `session_pubkey` matchee a
192    /// `expected_session_pubkey` (la que firmó el Hello). Esto
193    /// previene que un atacante reutilice un cert válido con una
194    /// session key distinta.
195    ///
196    /// Devuelve el `master_peer_id` derivado, que es el que el server
197    /// debe usar para evaluar la política de admisión.
198    pub fn verify_against_session(
199        &self,
200        expected_session_pubkey: &[u8],
201    ) -> Result<PeerId, CertError> {
202        if self.session_pubkey.as_slice() != expected_session_pubkey {
203            return Err(CertError::SessionMismatch);
204        }
205        let (master_peer, _session_peer) = self.verify()?;
206        Ok(master_peer)
207    }
208}
209
210/// Concat canónico de los campos firmados. Cualquier cambio aquí
211/// rompe compatibilidad — bump `SESSION_CERT_VERSION`.
212fn sign_payload(session_pubkey: &[u8], expires_at_ms: u64) -> Vec<u8> {
213    let mut buf = Vec::with_capacity(1 + 4 + session_pubkey.len() + 8);
214    buf.push(SESSION_CERT_VERSION);
215    buf.extend_from_slice(b"sess");
216    buf.extend_from_slice(&(session_pubkey.len() as u32).to_le_bytes());
217    buf.extend_from_slice(session_pubkey);
218    buf.extend_from_slice(&expires_at_ms.to_le_bytes());
219    buf
220}
221
222fn now_unix_ms() -> u64 {
223    SystemTime::now()
224        .duration_since(UNIX_EPOCH)
225        .map(|d| d.as_millis() as u64)
226        .unwrap_or(0)
227}
228
229#[cfg(test)]
230mod tests {
231    use super::*;
232
233    #[test]
234    fn issue_and_verify_cert() {
235        let master = Keypair::generate_ed25519();
236        let session = Keypair::generate_ed25519();
237        let id = Identity::from_keypair(master);
238        let cert = id
239            .issue_session_cert(&session, DEFAULT_SESSION_TTL)
240            .unwrap();
241        let (master_peer, session_peer) = cert.verify().unwrap();
242        assert_eq!(master_peer, id.master_peer_id());
243        assert_eq!(session_peer, session.public().to_peer_id());
244    }
245
246    #[test]
247    fn verify_against_session_admits_matching() {
248        let master = Keypair::generate_ed25519();
249        let session = Keypair::generate_ed25519();
250        let id = Identity::from_keypair(master);
251        let cert = id
252            .issue_session_cert(&session, DEFAULT_SESSION_TTL)
253            .unwrap();
254        let session_pk = session.public().encode_protobuf();
255        let master_peer = cert.verify_against_session(&session_pk).unwrap();
256        assert_eq!(master_peer, id.master_peer_id());
257    }
258
259    #[test]
260    fn verify_against_session_rejects_mismatch() {
261        let master = Keypair::generate_ed25519();
262        let session_a = Keypair::generate_ed25519();
263        let session_b = Keypair::generate_ed25519();
264        let id = Identity::from_keypair(master);
265        let cert = id
266            .issue_session_cert(&session_a, DEFAULT_SESSION_TTL)
267            .unwrap();
268        let other_pk = session_b.public().encode_protobuf();
269        let err = cert.verify_against_session(&other_pk).unwrap_err();
270        assert!(matches!(err, CertError::SessionMismatch), "got {err:?}");
271    }
272
273    #[test]
274    fn cert_with_zero_ttl_is_expired() {
275        let master = Keypair::generate_ed25519();
276        let session = Keypair::generate_ed25519();
277        let id = Identity::from_keypair(master);
278        let cert = id
279            .issue_session_cert(&session, Duration::from_secs(0))
280            .unwrap();
281        // Pequeña espera para asegurar que now_ms > expires_at_ms.
282        std::thread::sleep(Duration::from_millis(5));
283        let err = cert.verify().unwrap_err();
284        assert!(matches!(err, CertError::Expired { .. }), "got {err:?}");
285    }
286
287    #[test]
288    fn tampered_signature_rejected() {
289        let master = Keypair::generate_ed25519();
290        let session = Keypair::generate_ed25519();
291        let id = Identity::from_keypair(master);
292        let mut cert = id
293            .issue_session_cert(&session, DEFAULT_SESSION_TTL)
294            .unwrap();
295        if let Some(b) = cert.signature.last_mut() {
296            *b ^= 0x01;
297        }
298        let err = cert.verify().unwrap_err();
299        assert!(matches!(err, CertError::InvalidSignature), "got {err:?}");
300    }
301
302    #[test]
303    fn tampered_expires_at_rejected() {
304        // Si alguien extiende el expires_at sin re-firmar, la firma
305        // no cuadra → InvalidSignature.
306        let master = Keypair::generate_ed25519();
307        let session = Keypair::generate_ed25519();
308        let id = Identity::from_keypair(master);
309        let mut cert = id
310            .issue_session_cert(&session, DEFAULT_SESSION_TTL)
311            .unwrap();
312        cert.expires_at_ms = cert.expires_at_ms.saturating_add(1_000_000);
313        let err = cert.verify().unwrap_err();
314        assert!(matches!(err, CertError::InvalidSignature), "got {err:?}");
315    }
316
317    #[test]
318    fn unknown_version_rejected() {
319        let master = Keypair::generate_ed25519();
320        let session = Keypair::generate_ed25519();
321        let id = Identity::from_keypair(master);
322        let mut cert = id
323            .issue_session_cert(&session, DEFAULT_SESSION_TTL)
324            .unwrap();
325        cert.version = 99;
326        let err = cert.verify().unwrap_err();
327        assert!(matches!(err, CertError::UnknownVersion(99)), "got {err:?}");
328    }
329
330    #[test]
331    fn rotated_session_with_same_master_yields_same_master_peer_id() {
332        // La propiedad fundamental: rotar la session key NO cambia el
333        // master_peer_id derivado del cert.
334        let master = Keypair::generate_ed25519();
335        let id = Identity::from_keypair(master);
336        let original_master_peer = id.master_peer_id();
337
338        let session1 = Keypair::generate_ed25519();
339        let cert1 = id
340            .issue_session_cert(&session1, DEFAULT_SESSION_TTL)
341            .unwrap();
342        let (master_from_cert1, _) = cert1.verify().unwrap();
343
344        // Rotar: nueva session keypair, mismo master.
345        let session2 = Keypair::generate_ed25519();
346        let cert2 = id
347            .issue_session_cert(&session2, DEFAULT_SESSION_TTL)
348            .unwrap();
349        let (master_from_cert2, _) = cert2.verify().unwrap();
350
351        assert_eq!(master_from_cert1, original_master_peer);
352        assert_eq!(master_from_cert2, original_master_peer);
353        assert_eq!(
354            master_from_cert1, master_from_cert2,
355            "rotar session NO debe cambiar el master_peer_id"
356        );
357    }
358}