Skip to main content

libkeri/keri/core/routing/
revery.rs

1use super::router::Router;
2use crate::cesr::dater::Dater;
3use crate::cesr::indexing::siger::Siger;
4use crate::cesr::prefixer::Prefixer;
5use crate::cesr::saider::Saider;
6use crate::cesr::seqner::Seqner;
7use crate::cesr::verfer::Verfer;
8use crate::cesr::Matter;
9use crate::keri::core::eventing;
10use crate::keri::core::serdering::{Rawifiable, Serder, SerderKERI};
11use crate::keri::db::basing::Baser;
12use crate::keri::db::dbing::keys::{dg_key, sn_key};
13use crate::keri::KERIError;
14use std::collections::VecDeque;
15use crate::keri::core::eventing::kevery::Locals;
16use std::sync::Arc;
17use std::time::{Duration, SystemTime, UNIX_EPOCH};
18use tracing::{debug, info, trace, warn};
19
20pub const TIMEOUT_RPE: u64 = 3600;
21
22/// Reply message event processor
23pub struct Revery {
24    /// Timeout for reply message escrows (in seconds)
25
26    /// Database instance
27    pub db: Arc<Baser>,
28
29    /// Router for dispatching reply messages
30    pub rtr: Router,
31
32    /// Cues for processing
33    pub cues: VecDeque<ReplyMessageCue>,
34
35    /// Promiscuous mode flag
36    pub lax: bool,
37
38    /// Local vs nonlocal restrictions
39    pub local: bool,
40}
41
42/// Cue for reply message processing
43#[derive(Debug, Clone)]
44pub struct ReplyMessageCue {
45    pub kind: String,
46    pub data: std::collections::HashMap<String, serde_json::Value>,
47}
48
49impl Revery {
50    /// Initialize new Revery instance
51    pub fn new(
52        db: Arc<Baser>,
53        rtr: Option<Router>,
54        cues: Option<VecDeque<ReplyMessageCue>>,
55        lax: Option<bool>,
56        local: Option<bool>,
57    ) -> Self {
58        Self {
59            db,
60            rtr: rtr.unwrap_or_else(|| Router::new(None)),
61            cues: cues.unwrap_or_else(VecDeque::new),
62            lax: lax.unwrap_or(true),
63            local: local.unwrap_or(false),
64        }
65    }
66
67    /// Process one reply message with attached signatures
68    ///
69    /// Process logic is route dependent and dispatched by route.
70    ///
71    /// # Parameters
72    /// * `serder` - Instance of reply message
73    /// * `cigars` - Non-transferable signature instances
74    /// * `tsgs` - Transferable signature groups
75    ///
76    /// BADA (Best Available Data Acceptance) model for each reply message.
77    /// Latest-Seen-Signed Pairwise comparison of new update reply compared to
78    /// old already accepted reply from same source for same route (same data).
79    pub fn process_reply(
80        &self,
81        serder: SerderKERI,
82        cigars: Option<Vec<Siger>>,
83        tsgs: Option<Vec<(Prefixer, Seqner, Saider, Vec<Siger>)>>,
84    ) -> Result<(), KERIError> {
85        let ked = serder.ked();
86
87        // Verify SAID of reply
88        let saider = Saider::from_qb64(
89            ked.get("d")
90                .and_then(|v| v.as_str())
91                .ok_or_else(|| KERIError::ValueError("Missing 'd' field in reply".to_string()))?,
92        )?;
93
94        // Use the correct verify method signature
95        if !saider.verify(&ked, true, false, None, "d", None) {
96            return Err(KERIError::ValidationError(format!(
97                "Invalid said = {} for reply msg",
98                saider.qb64()
99            )));
100        }
101
102        // Dispatch to appropriate route handler
103        self.rtr
104            .dispatch(&serder, &saider, cigars.as_deref(), tsgs.as_deref())?;
105
106        Ok(())
107    }
108
109    /// Apply Best Available Data Acceptance policy to reply and signatures
110    ///
111    /// # Returns
112    /// * `true` if successfully accepted, `false` otherwise
113    ///
114    /// # Parameters
115    /// * `serder` - Instance of reply msg (SAD)
116    /// * `saider` - Instance from said in serder (SAD)
117    /// * `osaider` - Instance of saider for previous reply if any
118    /// * `route` - Reply route
119    /// * `aid` - Identifier prefix qb64 of authorizing attributable ID
120    /// * `cigars` - Non-transferable signature instances
121    /// * `tsgs` - Transferable signature groups
122    #[allow(clippy::too_many_arguments)]
123    pub fn accept_reply(
124        &mut self,
125        locals: &Locals,
126        serder: &SerderKERI,
127        saider: &Saider,
128        route: &str,
129        aid: &str,
130        osaider: Option<&Saider>,
131        cigars: Option<&[Siger]>,
132        tsgs: Option<&[(Prefixer, Seqner, Saider, Vec<Siger>)]>, // Third element is Saider
133    ) -> Result<bool, KERIError> {
134        let mut accepted = false;
135        let cigars = cigars.unwrap_or(&[]);
136        let tsgs = tsgs.unwrap_or(&[]);
137
138        // Get date-time for BADA comparison
139        let dater = Dater::from_dts(
140            serder
141                .ked()
142                .get("dt")
143                .and_then(|v| v.as_str())
144                .ok_or_else(|| KERIError::ValueError("Missing 'dt' field in reply".to_string()))?,
145        )?;
146
147        let odater = if let Some(osaider) = osaider {
148            self.db.sdts.get(&[&osaider.qb64()])?
149        } else {
150            None
151        };
152
153        // Process non-transferable signatures (cigars)
154        for cigar in cigars {
155            let verfer = match cigar.verfer() {
156                Some(v) => v,
157                None => {
158                    info!(
159                        "Revery: skipped cigar with no verfer on reply said = {}",
160                        serder.said().unwrap_or_default()
161                    );
162                    continue;
163                }
164            };
165
166            if verfer.is_transferable() {
167                info!(
168                    "Revery: skipped invalid transferable verfer on reply said = {}",
169                    serder.said().unwrap_or_default()
170                );
171                continue;
172            }
173
174            if !self.lax && locals.prefixes.contains(&verfer.qb64()) {
175                if !self.local {
176                    info!(
177                "Revery: skipped own attachment for AID {} on non-local reply at route = {}",
178                aid,
179                serder.ked().get("r").and_then(|v| v.as_str()).unwrap_or("unknown")
180            );
181                    debug!("Reply Body=\n{}\n", serder.pretty(None));
182                    continue;
183                }
184            }
185
186            if aid != verfer.qb64() {
187                info!(
188                    "Revery: skipped cigar not from aid={} on reply at route {}",
189                    aid,
190                    serder
191                        .ked()
192                        .get("r")
193                        .and_then(|v| v.as_str())
194                        .unwrap_or("unknown")
195                );
196                debug!("Reply Body=\n{}\n", serder.pretty(None));
197                continue;
198            }
199
200            // Check if this is later than previous version
201            if let Some(ref odater) = odater {
202                if dater.dt()? <= odater.dt()? {
203                    trace!(
204                        "Revery: skipped stale update from {} of reply at route = {}",
205                        aid,
206                        serder
207                            .ked()
208                            .get("r")
209                            .and_then(|v| v.as_str())
210                            .unwrap_or("unknown")
211                    );
212                    trace!("Reply Body=\n{}\n", serder.pretty(None));
213                    continue;
214                }
215            }
216
217            // Verify signature
218            if !verfer.verify(&cigar.raw(), &serder.raw())? {
219                info!(
220                    "Revery: skipped non-verifying cigar from {} on reply at route = {}",
221                    verfer.qb64(),
222                    serder
223                        .ked()
224                        .get("r")
225                        .and_then(|v| v.as_str())
226                        .unwrap_or("unknown")
227                );
228                debug!("Reply Body=\n{}\n", serder.pretty(None));
229                continue;
230            }
231
232            // All constraints satisfied, update the reply
233            self.update_reply(serder, saider, &dater, Some(cigar), None, None, None, None)?;
234            if let Some(osaider) = osaider {
235                self.remove_reply(osaider)?;
236            }
237            accepted = true;
238            break; // First valid cigar is sufficient
239        }
240
241        // Process transferable signatures (tsgs)
242        for (prefixer, seqner, ssaider, sigers) in tsgs {
243            if !self.lax && locals.prefixes.contains(&prefixer.qb64()) {
244                if !self.local {
245                    debug!(
246                        "Revery: skipped own attachment on nonlocal reply said={}",
247                        serder.said().unwrap_or_default()
248                    );
249                    debug!("event=\n{}\n", serder.pretty(None));
250                    continue;
251                }
252            }
253
254            let spre = &prefixer.qb64();
255            if aid != spre {
256                info!(
257                    "Revery: skipped signature not from aid={} on reply said={}",
258                    aid,
259                    serder.said().unwrap_or_default()
260                );
261                debug!("event=\n{}\n", serder.pretty(None));
262                continue;
263            }
264
265            // Check if this is later than previous version for transferable signatures
266            if let Some(osaider) = osaider {
267                let otsgs = self.db.fetch_tsgs(osaider.clone(), None)?;
268                if !otsgs.is_empty() {
269                    let (_, osqr, _, _) = &otsgs[0];
270
271                    if seqner.sn() < osqr.sn() {
272                        info!(
273                            "Revery: skipped stale key state sig from {} sn={}<{} on reply said={}",
274                            aid,
275                            seqner.sn(),
276                            osqr.sn(),
277                            serder.said().unwrap_or_default()
278                        );
279                        debug!("event=\n{}\n", serder.pretty(None));
280                        continue;
281                    }
282
283                    if seqner.sn() == osqr.sn() {
284                        if let Some(ref odater) = odater {
285                            if dater.dt()? <= odater.dt()? {
286                                info!(
287                                    "Revery: skipped stale key state sig datetime from {} on reply said={}",
288                                    aid, serder.said().unwrap_or_default()
289                                );
290                                debug!("event=\n{}\n", serder.pretty(None));
291                                continue;
292                            }
293                        }
294                    }
295                }
296            }
297
298            // Retrieve last event at sequence number for signer
299            let sdig = self
300                .db
301                .kels
302                .get_last::<_, Vec<u8>>(&[&sn_key(spre, seqner.sn())])?;
303
304            let sdig = match sdig {
305                Some(dig_bytes) => String::from_utf8(dig_bytes)
306                    .map_err(|_| KERIError::ValueError("Invalid UTF-8 in digest".to_string()))?,
307                None => {
308                    // Escrow if signer's establishment event not yet available
309                    info!(
310                        "Revery: escrowing without key state for signer on reply said={}",
311                        serder.said().unwrap_or_default()
312                    );
313                    self.escrow_reply(
314                        serder, saider, &dater, route, prefixer, seqner, ssaider, sigers,
315                    )?;
316
317                    // Add cue to request key state
318                    self.cues.push_back(ReplyMessageCue {
319                        kind: "query".to_string(),
320                        data: {
321                            let mut data = std::collections::HashMap::new();
322                            data.insert("pre".to_string(), serde_json::Value::String(spre.clone()));
323                            data
324                        },
325                    });
326                    continue;
327                }
328            };
329
330            // Retrieve the establishment event itself
331            let sraw = self
332                .db
333                .evts
334                .get::<_, Vec<u8>>(&[&dg_key(spre, &sdig)])?
335                .ok_or_else(|| {
336                    KERIError::ValueError(format!("Event not found for dig={}", sdig))
337                })?;
338
339            let sserder = SerderKERI::from_raw(&sraw, None)?;
340
341            if sserder.said().unwrap_or_default() != ssaider.qb64() {
342                return Err(KERIError::ValidationError(format!(
343                    "Bad trans indexed sig group at sn = {} for reply",
344                    seqner.sn()
345                )));
346            }
347
348            // Verify signatures
349            let sverfers = sserder.verfers().ok_or_else(|| {
350                KERIError::ValidationError(format!(
351                    "Invalid reply from signer={}, no keys at signer's est. event sn={}",
352                    spre,
353                    seqner.sn()
354                ))
355            })?;
356
357            // Fetch any escrowed signatures and combine with current ones
358            let mut all_sigers = sigers.clone();
359            let quad_keys = (
360                saider.qb64(),
361                prefixer.qb64(),
362                format!("{:032x}", seqner.sn()),
363                ssaider.qb64(),
364            );
365
366            let esigers_result =
367                self.db
368                    .ssgs
369                    .get(&[&quad_keys.0, &quad_keys.1, &quad_keys.2, &quad_keys.3])?;
370
371            if !esigers_result.is_empty() {
372                for matter_vec in esigers_result {
373                    for matter in matter_vec {
374                        if let Some(siger) = matter.as_any().downcast_ref::<Siger>() {
375                            all_sigers.push(siger.clone());
376                        }
377                    }
378                }
379            }
380
381            // Validate signatures against thresholds
382            let tholder = sserder.tholder().ok_or_else(|| {
383                KERIError::ValidationError(format!(
384                    "No tholder available for establishment event at sn={}",
385                    seqner.sn()
386                ))
387            })?;
388
389            let (valid_sigers, valid) =
390                eventing::validate_sigs(serder, all_sigers, &sverfers, &tholder)?;
391
392            if valid {
393                // All constraints satisfied, update the reply
394                self.update_reply(
395                    serder,
396                    saider,
397                    &dater,
398                    None,
399                    Some(prefixer),
400                    Some(seqner),
401                    Some(ssaider),
402                    Some(&valid_sigers),
403                )?;
404
405                if let Some(osaider) = osaider {
406                    self.remove_reply(osaider)?;
407                }
408
409                // Remove stale signatures
410                let tsgs_to_trim = self.db.fetch_tsgs(saider.clone(), Some(&seqner.snh()))?;
411                for (prr, snr, dgr, _) in tsgs_to_trim {
412                    if snr.sn() < seqner.sn()
413                        || (snr.sn() == seqner.sn() && dgr.qb64() != ssaider.qb64())
414                    {
415                        let trim_keys = (
416                            prr.qb64(),
417                            format!("{:032x}", snr.sn()),
418                            dgr.qb64(),
419                            String::new(),
420                        );
421                        self.db.ssgs.trim(
422                            &[&trim_keys.0, &trim_keys.1, &trim_keys.2, &trim_keys.3],
423                            true,
424                        )?;
425                    }
426                }
427
428                accepted = true;
429            } else {
430                // Not meeting threshold, escrow
431                self.escrow_reply(
432                    serder, saider, &dater, route, prefixer, seqner, ssaider, sigers,
433                )?;
434            }
435        }
436
437        Ok(accepted)
438    }
439
440    /// Update Reply SAD in database
441    #[allow(clippy::too_many_arguments)]
442    pub fn update_reply(
443        &self,
444        serder: &SerderKERI,
445        saider: &Saider,
446        dater: &Dater,
447        cigar: Option<&Siger>,
448        prefixer: Option<&Prefixer>,
449        seqner: Option<&Seqner>,
450        diger: Option<&Saider>, // This is actually a Saider in the Python code
451        sigers: Option<&[Siger]>,
452    ) -> Result<(), KERIError> {
453        let keys = [saider.qb64()];
454
455        // Store datetime, reply, and signatures
456        self.db.sdts.put(&keys, dater)?;
457        self.db.rpys.put(&keys, serder)?;
458
459        if let Some(cigar) = cigar {
460            if let Some(verfer) = cigar.verfer() {
461                self.db.scgs.put(&keys, &[&verfer, cigar])?;
462            }
463        }
464
465        if let Some(sigers) = sigers {
466            if let (Some(prefixer), Some(seqner), Some(diger)) = (prefixer, seqner, diger) {
467                let quad_keys = (
468                    saider.qb64(),
469                    prefixer.qb64(),
470                    format!("{:032x}", seqner.sn()),
471                    diger.qb64(), // diger is actually a Saider
472                );
473                let sigers_as_matter: Vec<&dyn Matter> =
474                    sigers.iter().map(|s| s as &dyn Matter).collect();
475                self.db.ssgs.put(
476                    &[&quad_keys.0, &quad_keys.1, &quad_keys.2, &quad_keys.3],
477                    &sigers_as_matter,
478                )?;
479            }
480        }
481
482        Ok(())
483    }
484
485    /// Remove Reply SAD artifacts given by saider
486    pub fn remove_reply(&self, saider: &Saider) -> Result<(), KERIError> {
487        let keys = [saider.qb64()];
488
489        // Remove all related data
490        let saider_b64 = saider.qb64();
491        self.db.ssgs.trim(&[saider_b64.as_ref(), ""], true)?; // Remove whole branch
492        self.db.scgs.rem(&keys, None)?;
493        self.db.rpys.rem(&keys)?;
494        self.db.sdts.rem(&keys)?;
495
496        Ok(())
497    }
498
499    /// Escrow reply by route
500    #[allow(clippy::too_many_arguments)]
501    pub fn escrow_reply(
502        &self,
503        serder: &SerderKERI,
504        saider: &Saider,
505        dater: &Dater,
506        route: &str,
507        prefixer: &Prefixer,
508        seqner: &Seqner,
509        ssaider: &Saider,
510        sigers: &[Siger],
511    ) -> Result<(), KERIError> {
512        if sigers.is_empty() {
513            return Ok(()); // Nothing to escrow
514        }
515
516        let keys = [saider.qb64()];
517
518        // Store escrow data
519        self.db.sdts.put(&keys, dater)?;
520        self.db.rpys.put(&keys, serder)?;
521
522        let quad_keys = (
523            saider.qb64(),
524            prefixer.qb64(),
525            format!("{:032x}", seqner.sn()),
526            ssaider.qb64(),
527        );
528        let sigers_as_matter: Vec<&dyn Matter> = sigers.iter().map(|s| s as &dyn Matter).collect();
529        self.db.ssgs.put(
530            &[&quad_keys.0, &quad_keys.1, &quad_keys.2, &quad_keys.3],
531            &sigers_as_matter,
532        )?;
533
534        // Add to reply escrow
535        self.db.rpes.put(&[route], &[saider])?;
536
537        Ok(())
538    }
539
540    /// Process escrows for reply messages
541    ///
542    /// Escrows are keyed by reply route and val is reply said
543    pub fn process_escrow_reply(&mut self) -> Result<(), KERIError> {
544        let mut items_to_process = Vec::new();
545
546        // Collect items to process to avoid borrowing issues
547        let iter_results = self.db.rpes.get_item_iter(&[""], true)?;
548        for (keys, saider) in iter_results {
549            if let Some(route) = keys.get(0) {
550                items_to_process.push((route.clone(), saider.clone()));
551            }
552        }
553
554        for (route, saider) in items_to_process {
555            // Convert Vec<u8> to String
556            let route_str = match String::from_utf8(route) {
557                Ok(s) => s,
558                Err(e) => {
559                    warn!("Invalid UTF-8 in route: {}", e);
560                    continue;
561                }
562            };
563
564            match self.process_single_escrow(&route_str, &saider) {
565                Ok(success) => {
566                    if success {
567                        // Remove from escrow on success
568                        self.db.rpes.rem(&[&route_str.as_bytes()], None)?;
569                        info!("Revery unescrow succeeded for reply said={}", saider.qb64());
570                    }
571                }
572                Err(e) => {
573                    // Remove failed escrow
574                    self.db.rpes.rem(&[&route_str.as_bytes()], None)?;
575                    self.remove_reply(&saider)?;
576                    debug!("Revery unescrowed due to error: {}", e);
577                }
578            }
579        }
580
581        Ok(())
582    }
583
584    /// Process a single escrowed reply
585    fn process_single_escrow(&self, route: &str, saider: &Saider) -> Result<bool, KERIError> {
586        // Convert Diger-based tsgs to Saider-based tsgs for compatibility
587        let tsgs_raw = self.db.fetch_tsgs(saider.clone(), None)?;
588
589        let tsgs: Vec<(Prefixer, Seqner, Saider, Vec<Siger>)> = tsgs_raw
590            .into_iter()
591            .map(|(prefixer, seqner, diger, sigers)| {
592                // Convert Diger to Saider - they should have the same qb64 representation
593                let saider = Saider::from_qb64(&diger.qb64()).unwrap_or_else(|_| {
594                    // This should not fail since Diger and Saider use same encoding
595                    panic!("Failed to convert Diger to Saider: {}", diger.qb64())
596                });
597                (prefixer, seqner, saider, sigers)
598            })
599            .collect();
600
601        let keys = [saider.qb64()];
602
603        let dater = self
604            .db
605            .sdts
606            .get::<_>(&keys)?
607            .ok_or_else(|| KERIError::ValueError("Missing escrow datetime".to_string()))?;
608
609        let serder = self
610            .db
611            .rpys
612            .get::<_>(&keys)?
613            .ok_or_else(|| KERIError::ValueError("Missing escrow serder".to_string()))?;
614
615        // Check if we have the required artifacts
616        if tsgs.is_empty() {
617            return Err(KERIError::ValueError(format!(
618                "Missing escrow artifacts at said={} for route={}",
619                saider.qb64(),
620                route
621            )));
622        }
623
624        // Check for stale escrow
625        let now = SystemTime::now()
626            .duration_since(UNIX_EPOCH)
627            .map_err(|e| KERIError::ValueError(format!("System time error: {}", e)))?;
628
629        let escrow_datetime = dater
630            .dt()
631            .map_err(|e| KERIError::ValueError(format!("Invalid datetime format: {:?}", e)))?;
632
633        let escrow_age =
634            now.saturating_sub(Duration::from_secs(escrow_datetime.timestamp() as u64));
635
636        if escrow_age > Duration::from_secs(TIMEOUT_RPE) {
637            info!(
638                "Revery unescrow error: Stale reply escrow at route = {}",
639                route
640            );
641            return Err(KERIError::ValidationError(format!(
642                "Stale reply escrow at route = {}",
643                route
644            )));
645        }
646
647        // Try to process the escrowed reply
648        self.process_reply(serder, None, Some(tsgs))?;
649
650        Ok(true)
651    }
652}
653
654#[cfg(test)]
655mod tests {
656    use super::*;
657    use crate::keri::db::dbing::LMDBer;
658
659    #[test]
660    fn test_revery_new() -> Result<(), KERIError> {
661        let lmdber = LMDBer::builder()
662            .temp(true)
663            .name("test_revery")
664            .build()
665            .map_err(|e| KERIError::DatabaseError(format!("{}", e)))?;
666
667        let db =
668            Baser::new(Arc::new(lmdber)).map_err(|e| KERIError::DatabaseError(format!("{}", e)))?;
669
670        let revery = Revery::new(Arc::new(db), None, None, Some(true), Some(false));
671
672        assert!(revery.lax);
673        assert!(!revery.local);
674        assert_eq!(revery.cues.len(), 0);
675
676        Ok(())
677    }
678}