Skip to main content

libkeri/keri/app/
habbing.rs

1use crate::cesr::cigar::Cigar;
2use crate::cesr::counting::{ctr_dex_1_0, BaseCounter, Counter};
3use crate::cesr::diger::Diger;
4use crate::cesr::indexing::siger::Siger;
5use crate::cesr::prefixer::Prefixer;
6use crate::cesr::saider::Saider;
7use crate::cesr::seqner::Seqner;
8use crate::cesr::signing::Sigmat;
9use crate::cesr::tholder::{Tholder, TholderSith};
10use crate::cesr::verfer::Verfer;
11use crate::cesr::{mtr_dex, trait_dex, Tiers};
12use crate::cesr::{Matter, Parsable};
13use crate::hio::hicting::Mict;
14use crate::keri::app::configing::Configer;
15use crate::keri::app::keeping::creators::Algos;
16use crate::keri::app::keeping::{Keeper, Manager};
17use crate::keri::core::eventing::incept::InceptionEventBuilder;
18use crate::keri::core::eventing::interact::InteractEventBuilder;
19use crate::keri::core::eventing::kever::Kever;
20use crate::keri::core::eventing::kevery::Kevery;
21use crate::keri::core::eventing::messagize;
22use crate::keri::core::eventing::query::QueryEventBuilder;
23use crate::keri::core::eventing::receipt::ReceiptEventBuilder;
24use crate::keri::core::eventing::reply::ReplyEventBuilder;
25use crate::keri::core::eventing::rotate::RotateEventBuilder;
26use crate::keri::core::eventing::{Seal, SealEvent, SealLast};
27use crate::keri::core::parsing::Parser;
28use crate::keri::core::routing::{Revery, Router};
29use crate::keri::core::serdering::{Rawifiable, SadValue, Sadder, Serder, SerderKERI};
30use crate::keri::db::basing::{Baser, EndpointRecord, HabitatRecord, LocationRecord};
31use crate::keri::db::dbing::keys::{dg_key, sn_key};
32use crate::keri::KERIError;
33use crate::keri::KERIError::{ConfigurationError, MissingEntryError, ValidationError};
34use crate::keri::{Ilks, Roles};
35use indexmap::{IndexMap, IndexSet};
36use serde_json;
37use std::collections::{HashMap, VecDeque};
38use std::ops::{Deref, DerefMut};
39use std::str::FromStr;
40use std::sync::Arc;
41use tracing::{debug, info, warn};
42
43/// A view of one local identifier over components owned by a [`Habery`](crate::keri::app::habery::Habery).
44///
45/// BaseHab borrows the shared Manager, Kevery, Revery and Parser for as long as it
46/// lives, so every Hab sees the same key state and local-prefix set. Get one from
47/// `Habery::hab_by_name` / `hab_by_pre` / `make_hab`; drop it to use the Habery again.
48pub struct BaseHab<'a> {
49    pub db: Arc<Baser>,
50    pub mgr: &'a mut Manager,
51    pub rtr: Option<Arc<Router>>,
52    pub rvy: &'a mut Revery,
53    pub kvy: &'a mut Kevery,
54    pub psr: &'a mut Parser<std::io::Empty>,
55    pub name: String,
56    pub ns: Option<String>,
57    pub pre: Option<String>,
58    pub temp: bool,
59    pub inited: bool,
60    pub delpre: Option<String>,
61}
62
63impl<'a> BaseHab<'a> {
64    pub fn new(
65        db: Arc<Baser>,
66        mgr: &'a mut Manager,
67        rtr: Option<Arc<Router>>,
68        rvy: &'a mut Revery,
69        kvy: &'a mut Kevery,
70        psr: &'a mut Parser<std::io::Empty>,
71        name: String,
72        ns: Option<String>,
73        pre: Option<String>,
74        temp: bool,
75    ) -> Result<Self, KERIError> {
76        let hab = BaseHab {
77            db,
78            mgr,
79            rtr,
80            rvy,
81            kvy,
82            psr,
83            name,
84            ns,
85            pre,
86            temp,
87            inited: false,
88            delpre: None,
89        };
90
91        Ok(hab)
92    }
93
94    /// Parse `msg` and route each message into this Hab's Kevery/Revery as a
95    /// local (protected) source, e.g. to store a receipt this Hab just made.
96    pub fn ingest_local(&mut self, msg: &[u8]) -> Result<(), KERIError> {
97        for m in self.psr.parse_messages(msg)? {
98            crate::keri::app::habery::route_message(self.kvy, self.rvy, m, true)?;
99        }
100        Ok(())
101    }
102
103    /// Create inception event with verifiers, threshold settings, witnesses, etc.
104    pub fn make(
105        &mut self,
106        d_n_d: Option<bool>,
107        code: Option<&str>,
108        data: Option<Vec<SadValue>>,
109        delpre: Option<String>,
110        est_only: Option<bool>,
111        isith: Option<Tholder>,
112        verfers: Vec<Verfer>,
113        nsith: Option<Tholder>,
114        digers: Option<Vec<Diger>>,
115        toad: Option<u32>,
116        wits: Option<Vec<String>>,
117    ) -> Result<SerderKERI, KERIError> {
118        if self.pre.is_some() {
119            return Err(ValidationError("Habitat already incepted".to_string()));
120        }
121
122        let d_n_d = d_n_d.unwrap_or(false);
123        let est_only = est_only.unwrap_or(false);
124        let toad = toad.unwrap_or(0);
125        let wits = wits.unwrap_or_default();
126        let data = data.unwrap_or_default();
127
128        let icount = verfers.len();
129        let ncount = if let Some(ref digers) = digers {
130            digers.len()
131        } else {
132            0
133        };
134
135        // Convert Tholder to TholderSith - if not provided, compute defaults
136        let isith_sith = if let Some(isith) = isith {
137            isith.sith()
138        } else {
139            let threshold = std::cmp::max(1, (icount as f64 / 2.0).ceil() as usize);
140            TholderSith::Integer(threshold)
141        };
142
143        let nsith_sith = if let Some(nsith) = nsith {
144            nsith.sith()
145        } else {
146            let threshold = std::cmp::max(0, (ncount as f64 / 2.0).ceil() as usize);
147            TholderSith::Integer(threshold)
148        };
149
150        // Build configuration array
151        let mut cnfg = Vec::new();
152        if est_only {
153            cnfg.push(trait_dex::EST_ONLY.to_string());
154        }
155        if d_n_d {
156            cnfg.push(trait_dex::DO_NOT_DELEGATE.to_string());
157        }
158
159        // Store delegator prefix if provided
160        self.delpre = delpre.clone();
161
162        // Extract keys from verfers
163        let keys: Vec<String> = verfers.iter().map(|verfer| verfer.qb64()).collect();
164
165        // Extract next key digests from digers if provided
166        let ndigs: Vec<String> = if let Some(digers) = digers {
167            digers.iter().map(|diger| diger.qb64()).collect()
168        } else {
169            Vec::new()
170        };
171
172        // Anchored data goes into `a` as given, as keripy `Hab.make(data=...)`.
173        let sad_data: Vec<SadValue> = data;
174
175        // Create the inception event using the builder
176        let mut builder = InceptionEventBuilder::new(keys)
177            .with_isith(isith_sith)
178            .with_nsith(nsith_sith)
179            .with_ndigs(ndigs)
180            .with_toad(toad as usize)
181            .with_wits(wits)
182            .with_cnfg(cnfg)
183            .with_data(sad_data);
184
185        // Set derivation code if provided
186        if let Some(code) = code {
187            builder = builder.with_code(code.to_string());
188        }
189
190        // Set delegator prefix if this is a delegated inception
191        if let Some(ref delpre) = self.delpre {
192            builder = builder.with_delpre(delpre.clone());
193        }
194
195        // Build the serder
196        let serder = builder.build()?;
197
198        Ok(serder)
199    }
200
201    pub fn save(&mut self, habord: &HabitatRecord) -> Result<(), KERIError> {
202        // Ensure we have a prefix
203        let pre = self.pre.as_ref().ok_or_else(|| {
204            KERIError::ValueError("Cannot save habitat without prefix".to_string())
205        })?;
206
207        // Save the habitat record keyed by prefix
208        self.db
209            .habs
210            .pin(&[pre.as_bytes()], habord)
211            .map_err(|e| KERIError::DatabaseError(format!("Failed to save habitat: {}", e)))?;
212
213        // Handle namespace - empty string if None
214        let ns = self.ns.as_deref().unwrap_or("");
215
216        // Check if name already exists
217        let existing: Option<Vec<u8>> = self
218            .db
219            .names
220            .get(&[ns.as_bytes(), self.name.as_bytes()])
221            .map_err(|e| {
222            KERIError::DatabaseError(format!("Failed to check existing name: {}", e))
223        })?;
224
225        if existing.is_some() {
226            return Err(KERIError::ValueError(
227                "AID already exists with that name".to_string(),
228            ));
229        }
230
231        // Pin the name to prefix mapping
232        self.db
233            .names
234            .pin(
235                &[ns.as_bytes(), self.name.as_bytes()],
236                &pre.as_bytes().to_vec(),
237            )
238            .map_err(|e| KERIError::DatabaseError(format!("Failed to save name mapping: {}", e)))?;
239
240        Ok(())
241    }
242
243    pub fn reconfigure(&self) {
244        // Not yet implemented
245    }
246
247    /// Get own inception event serder
248    pub fn iserder(&self) -> Result<SerderKERI, KERIError> {
249        if let Some(ref pre) = self.pre {
250            // Get digest of inception event (sequence number 0)
251            let sn_key = sn_key(pre, 0);
252
253            let dig = self.db.get_ke_last(&sn_key)?.ok_or_else(|| {
254                ConfigurationError(format!(
255                    "Missing inception event in KEL for Habitat pre={}",
256                    pre
257                ))
258            })?;
259            let dg_key = dg_key(pre, dig.as_bytes());
260
261            let raw = self.db.get_evt(&dg_key)?.ok_or_else(|| {
262                ConfigurationError(format!("Missing inception event for Habitat pre={}", pre))
263            })?;
264            SerderKERI::from_raw(&raw, None).map_err(|e| {
265                ValidationError(format!("Failed to deserialize inception event: {}", e))
266            })
267        } else {
268            Err(ConfigurationError("No prefix set for habitat".to_string()))
269        }
270    }
271
272    /// Get all kevers from the local database
273    pub fn kevers(&self) -> &HashMap<String, Kever> {
274        &self.kvy.kevers
275    }
276
277    /// Check if this habitat is accepted into local KEL
278    pub fn accepted(&self) -> bool {
279        // In Python: return self.pre in self.kevers
280        // This checks if the habitat's prefix exists in the kevers map
281        if let Some(ref pre) = self.pre {
282            self.kvy.kevers.contains_key(pre)
283        } else {
284            false
285        }
286    }
287
288    /// Get the kever (key state) of the local controller
289    pub fn kever(&self) -> Result<&Kever, KERIError> {
290        if let Some(ref pre) = self.pre {
291            self.kvy
292                .kevers
293                .get(pre)
294                .ok_or_else(|| MissingEntryError(format!("No kever for prefix {}", pre)))
295        } else {
296            Err(ConfigurationError("No prefix set for habitat".to_string()))
297        }
298    }
299
300    /// Get local prefixes for database
301    pub fn prefixes(&self) -> IndexSet<String> {
302        // Return prefixes from the database
303        // This represents all locally controlled prefixes
304        self.kvy.locals.prefixes.clone()
305    }
306
307    /// Create inception event (alias for make)
308    pub fn incept(
309        &mut self,
310        transferable: Option<bool>,
311        code: Option<&str>,
312        count: Option<u32>,
313        ncount: Option<u32>,
314        isith: Option<Tholder>,
315        nsith: Option<Tholder>,
316        toad: Option<u32>,
317        wits: Option<Vec<String>>,
318        cnfg: Option<Vec<&str>>,
319        data: Option<Vec<SadValue>>,
320        delpre: Option<String>,
321    ) -> Result<SerderKERI, KERIError> {
322        let transferable = transferable.unwrap_or(true);
323        let count = count.unwrap_or(1);
324        let ncount = ncount.unwrap_or(1);
325
326        // Create verifiers and digesters using the manager
327        let (verfers, digers) = self.mgr.incept(
328            None,                  // icodes
329            Some(count as usize),  // icount
330            None,                  // icode - will use default
331            None,                  // ncodes
332            Some(ncount as usize), // ncount
333            None,                  // ncode - will use default
334            None,                  // dcode - will use default
335            None,                  // algo
336            None,                  // salt
337            None,                  // stem
338            None,                  // tier
339            None,                  // rooted
340            Some(transferable),
341            Some(self.temp),
342        )?;
343
344        // Extract configuration flags from cnfg parameter
345        let mut d_n_d = false;
346        let mut est_only = false;
347        if let Some(cnfg) = cnfg {
348            for config in cnfg {
349                match config {
350                    "EO" => est_only = true, // EST_ONLY trait
351                    "DND" => d_n_d = true,   // DO_NOT_DELEGATE trait
352                    _ => {}                  // Ignore unknown configs
353                }
354            }
355        }
356
357        // Now call make with the proper parameters
358        self.make(
359            Some(d_n_d),    // d_n_d: Option<bool>
360            code,           // code: Option<&str>
361            data,           // data: Option<Vec<SadValue>>
362            delpre,         // delpre: Option<String>
363            Some(est_only), // est_only: Option<bool>
364            isith,          // isith: Option<Tholder>
365            verfers,        // verfers: Vec<Verfer>
366            nsith,          // nsith: Option<Tholder>
367            Some(digers),   // digers: Option<Vec<Diger>>
368            toad,           // toad: Option<u32>
369            wits,           // wits: Option<Vec<String>>
370        )
371    }
372
373    /// Perform rotation operation
374    pub fn rotate(
375        &mut self,
376        verfers: Option<Vec<Verfer>>,
377        digers: Option<Vec<Diger>>,
378        ncount: Option<u32>,
379        isith: Option<Tholder>,
380        nsith: Option<Tholder>,
381        toad: Option<u32>,
382        cuts: Option<Vec<String>>,
383        adds: Option<Vec<String>>,
384        data: Option<Vec<SadValue>>,
385    ) -> Result<Vec<u8>, KERIError> {
386        if self.pre.is_none() {
387            return Err(ValidationError("Habitat not incepted".to_string()));
388        }
389
390        // Get current kever state before rotation - this is the "prior next"
391        let kever = self.kever()?;
392        let pre = self.pre.as_ref().unwrap();
393
394        // Use provided keys or generate new ones
395        let (verfers, digers) = match (verfers, digers) {
396            (Some(v), Some(d)) => (v, d),
397            _ => {
398                let ncount = ncount.unwrap_or(1);
399                self.mgr.rotate(
400                    pre.as_bytes(),
401                    None,                  // ncodes
402                    Some(ncount as usize), // ncount
403                    None,                  // ncode
404                    None,                  // dcode
405                    Some(true),            // transferable
406                    Some(self.temp),       // temp
407                    Some(true),            // erase
408                )?
409            }
410        };
411
412        // Determine signing thresholds following Python logic
413        let isith_sith = if let Some(isith) = isith {
414            isith.sith()
415        } else {
416            // Use prior next threshold as default, or provide fallback if None
417            kever
418                .ntholder
419                .as_ref()
420                .map(|tholder| tholder.sith())
421                .unwrap_or(TholderSith::Integer(1)) // Provide a sensible default
422        };
423
424        let nsith_sith = if let Some(nsith) = nsith {
425            nsith.sith()
426        } else {
427            // Use new current as default (same as isith)
428            isith_sith.clone()
429        };
430
431        // If still no thresholds, compute defaults from key counts
432        let final_isith = if matches!(isith_sith, TholderSith::Integer(0)) {
433            let threshold = std::cmp::max(1, (verfers.len() as f64 / 2.0).ceil() as usize);
434            TholderSith::Integer(threshold)
435        } else {
436            isith_sith
437        };
438
439        let final_nsith = if matches!(nsith_sith, TholderSith::Integer(0)) {
440            let threshold = std::cmp::max(0, (digers.len() as f64 / 2.0).ceil() as usize);
441            TholderSith::Integer(threshold)
442        } else {
443            nsith_sith
444        };
445
446        // Extract keys from verfers
447        let keys: Vec<String> = verfers.iter().map(|verfer| verfer.qb64()).collect();
448
449        // Validate rotation against prior next key digests
450        let mut indices = Vec::new();
451        if let Some(prior_digers) = &kever.ndigers {
452            for (idx, prior_diger) in prior_digers.iter().enumerate() {
453                for verfer in &verfers {
454                    let new_diger = Diger::from_ser(&mut verfer.qb64b(), Some(prior_diger.code()))?;
455                    if new_diger.qb64() == prior_diger.qb64() {
456                        indices.push(idx);
457                        break;
458                    }
459                }
460            }
461        }
462
463        // Validate that new key set can satisfy prior next signing threshold
464        if !kever
465            .ntholder
466            .as_ref()
467            .map_or(false, |tholder| tholder.satisfy(&indices))
468        {
469            return Err(ValidationError(
470                "Invalid rotation: new key set unable to satisfy prior next signing threshold"
471                    .to_string(),
472            ));
473        }
474
475        // Extract next key digests from digers
476        let ndigs: Vec<String> = digers.iter().map(|diger| diger.qb64()).collect();
477
478        // Anchored data goes into `a` as given, as keripy `Hab.rotate(data=...)`.
479        let sad_data: Vec<SadValue> = data.unwrap_or_default();
480
481        let said = kever
482            .serder
483            .as_ref()
484            .ok_or_else(|| ValidationError("Missing serder".to_string()))?
485            .said()
486            .ok_or_else(|| ValidationError("Missing said in serder".to_string()))?
487            .to_string();
488
489        let num = kever
490            .sner
491            .as_ref()
492            .ok_or_else(|| ValidationError("Missing sner".to_string()))?
493            .num();
494
495        // Build rotation event using the builder
496        let mut builder = RotateEventBuilder::new(
497            pre.clone(),
498            keys,
499            said, // previous event digest
500        )
501        .with_sn(num as usize + 1) // next sequence number
502        .with_isith(final_isith)
503        .with_nsith(final_nsith)
504        .with_ndigs(ndigs)
505        .with_wits(kever.wits())
506        .with_data(sad_data);
507
508        // Set witness threshold if provided
509        if let Some(toad) = toad {
510            builder = builder.with_toad(toad as usize);
511        }
512
513        // Set witness cuts and adds if provided
514        if let Some(cuts) = cuts {
515            builder = builder.with_cuts(cuts);
516        }
517
518        if let Some(adds) = adds {
519            builder = builder.with_adds(adds);
520        }
521
522        // Set the appropriate ilk based on whether this is delegated
523        if kever.delpre.is_some() {
524            builder = builder.with_ilk(Ilks::DRT.to_string()); // Delegated rotation
525        } else {
526            builder = builder.with_ilk(Ilks::ROT.to_string()); // Regular rotation
527        }
528
529        // Build the serder
530        let serder = builder.build()?;
531
532        // Sign the rotation event
533        let sigers = self.sign(
534            &serder.raw(),
535            Some(verfers),
536            Some(true), // indexed
537            None,       // indices
538            None,       // ondices
539            None,       // ponly
540        )?;
541
542        // Create message from serder and signatures
543        let msg = messagize(&serder, Some(&sigers), None, None, None, false)
544            .map_err(|e| KERIError::ValidationError(format!("Failed to create message: {}", e)))?;
545
546        // Process the event to update key state
547        match self.kvy.process_event(
548            serder.clone(),
549            sigers,
550            None,
551            None,
552            None,
553            None,
554            None,
555            None,
556            None,
557        ) {
558            Ok(_) => {}
559            Err(KERIError::MissingSignatureError(_)) => {}
560            Err(e) => {
561                return Err(KERIError::ValidationError(format!(
562                    "Improper Habitat rotation for pre={}. Error: {}",
563                    pre, e
564                )));
565            }
566        }
567
568        Ok(msg)
569    }
570
571    /// Create, sign and accept an interaction event (keripy `Hab.interact`).
572    ///
573    /// `data` is the event's anchor list `a`, typically seals such as
574    /// `{"i": pre, "s": sn, "d": said}`; `None` gives an empty list.
575    pub fn interact(&mut self, data: Option<Vec<SadValue>>) -> Result<Vec<u8>, KERIError> {
576        // Get the current kever (key event state)
577        let kever = self.kever()?;
578
579        // Get the prefix - must exist for interaction
580        let pre = self
581            .pre
582            .as_ref()
583            .ok_or_else(|| ConfigurationError("No prefix set for habitat".to_string()))?;
584
585        // Get the current sequence number and increment for next event
586        let current_sn = kever
587            .sner
588            .as_ref()
589            .ok_or_else(|| ValidationError("Missing sequence number in kever".to_string()))?
590            .num();
591        let next_sn = current_sn + 1;
592
593        // Get the digest of the current event (prior event)
594        let prior_dig = kever
595            .serder
596            .as_ref()
597            .ok_or_else(|| ValidationError("Missing serder in kever".to_string()))?
598            .said()
599            .ok_or_else(|| ValidationError("Missing SAID in current event".to_string()))?
600            .to_string();
601
602        // Create interaction event using the builder
603        let mut builder =
604            InteractEventBuilder::new(pre.clone(), prior_dig).with_sn(next_sn as usize);
605
606        // Anchored data goes into `a` as given, as keripy `Hab.interact(data=...)`:
607        // a list of seals, each normally an object such as {"i", "s", "d"}.
608        if let Some(data) = data {
609            builder = builder.with_data_list(data);
610        }
611
612        // Build the serder
613        let serder = builder.build()?;
614
615        // Sign the interaction event
616        let sigers = self.sign(
617            &serder.raw(), // ser: serialized event to sign
618            None,          // verfers: use current verfers from kever
619            Some(true),    // indexed: create indexed signatures
620            None,          // indices: let manager choose indices
621            None,          // ondices: no specific ondices
622            None,          // ponly: not ponly mode
623        )?;
624
625        // Create the complete message with serder and signatures
626        let msg = messagize(&serder, Some(&sigers), None, None, None, false)
627            .map_err(|e| ValidationError(format!("Failed to create message: {}", e)))?;
628
629        // Process the event through kevery to update local state
630        // This validates the event and updates the kever state
631        match self.kvy.process_event(
632            serder, // serder: the interaction event
633            sigers, // sigers: signatures
634            None,   // wigers: no witness signatures
635            None,   // local: not specified
636            None,   // cigars: no non-indexed signatures
637            None,   // tsgs: no trans signatures
638            None,   // tholder: no threshold
639            None,   // toader: no toad threshold
640            None,   // seqner: sequence number will be extracted
641        ) {
642            Ok(_) => {
643                // Event processed successfully
644            }
645            Err(KERIError::MissingSignatureError(_)) => {
646                // Missing signatures are acceptable for some scenarios
647                // Continue processing
648            }
649            Err(e) => {
650                // Any other error indicates improper interaction
651                return Err(ValidationError(format!(
652                    "Improper Habitat interaction for pre={}. Error: {}",
653                    pre, e
654                )));
655            }
656        }
657
658        Ok(msg)
659    }
660
661    /// Sign given serialization using appropriate keys
662    pub fn sign(
663        &self,
664        ser: &[u8],
665        verfers: Option<Vec<Verfer>>,
666        indexed: Option<bool>,
667        indices: Option<Vec<u32>>,
668        ondices: Option<Vec<Option<u32>>>,
669        ponly: Option<bool>,
670    ) -> Result<Vec<Siger>, KERIError> {
671        let indexed = indexed.unwrap_or(true);
672        let _ponly = ponly.unwrap_or(false);
673
674        // If no verfers provided, use the current kever's verfers
675        let verfers_to_use = if verfers.is_some() {
676            verfers
677        } else {
678            if let Ok(kever) = self.kever() {
679                kever.verfers.clone()
680            } else {
681                None
682            }
683        };
684
685        // Delegate to the manager's sign method
686        let signatures = self.mgr.sign(
687            ser,
688            None, // pubs
689            verfers_to_use,
690            Some(indexed),
691            indices,
692            ondices,
693            self.pre.as_ref().map(|p| p.as_bytes()),
694            None, // path
695        )?;
696
697        // Extract Siger instances from Sigmat enum
698        signatures
699            .into_iter()
700            .map(|sig| match sig {
701                Sigmat::Indexed(siger) => Ok(siger),
702                Sigmat::NonIndexed(_) => Err(KERIError::ValidationError(
703                    "Expected Siger but got Cigar - indexed signatures required".to_string(),
704                )),
705            })
706            .collect()
707    }
708
709    pub fn decrypt(&self, ser: &[u8], verfers: Option<Vec<Verfer>>) -> Result<Vec<u8>, KERIError> {
710        // If no verfers provided, use the current kever's verfers
711        let verfers_to_use = if let Some(verfers) = verfers {
712            Some(verfers)
713        } else {
714            // Get verfers from kever - these provide group signing keys when in group mode
715            match self.kever() {
716                Ok(kever) => kever.verfers.clone(),
717                Err(_) => {
718                    return Err(KERIError::ConfigurationError(
719                        "No kever available and no verfers provided for decryption".to_string(),
720                    ));
721                }
722            }
723        };
724
725        // Delegate to the manager's decrypt method
726        // Note: The Python comment mentions this "should not use mgr.decrypt since it assumes qb64"
727        // but says it's "just lucky its not yet a problem". We'll use it as intended for now.
728        self.mgr.decrypt(
729            ser,            // qb64: the ciphertext to decrypt
730            None,           // pubs: not using public key strings
731            verfers_to_use, // verfers: use the verfers we determined above
732        )
733    }
734
735    pub fn query(
736        &self,
737        pre: &str,
738        src: &str,
739        query: Option<IndexMap<String, SadValue>>,
740        route: Option<String>,
741        reply_route: Option<String>,
742        stamp: Option<String>,
743    ) -> Result<Vec<u8>, KERIError> {
744        // Start with provided query parameters or create new map
745        let mut query_params = query.unwrap_or_else(|| IndexMap::new());
746
747        // Set required query parameters
748        query_params.insert("i".to_string(), SadValue::String(pre.to_string()));
749        query_params.insert("src".to_string(), SadValue::String(src.to_string()));
750
751        // Build the query event using QueryEventBuilder
752        let mut builder = QueryEventBuilder::new().with_query(query_params);
753
754        // Set optional parameters if provided
755        if let Some(r) = route {
756            builder = builder.with_route(r);
757        }
758
759        if let Some(rr) = reply_route {
760            builder = builder.with_reply_route(rr);
761        }
762
763        if let Some(ts) = stamp {
764            builder = builder.with_stamp(ts);
765        }
766
767        // Build the serder
768        let serder = builder
769            .build()
770            .map_err(|e| ValidationError(format!("Failed to build query event: {}", e)))?;
771
772        // Endorse the query with SealLast (last=true)
773        self.endorse(&serder, Some(true), None)
774    }
775
776    pub fn endorse(
777        &self,
778        serder: &SerderKERI,
779        last: Option<bool>,
780        pipelined: Option<bool>,
781    ) -> Result<Vec<u8>, KERIError> {
782        let last = last.unwrap_or(false);
783        let pipelined = pipelined.unwrap_or(true);
784
785        // Get the current kever state
786        let kever = self.kever()?;
787
788        // Get the prefixer and check if it exists
789        let prefixer = kever
790            .prefixer
791            .as_ref()
792            .ok_or_else(|| ValidationError("Missing prefixer in kever".to_string()))?;
793
794        // Check if the habitat's identifier is transferable
795        if prefixer.transferable() {
796            // For transferable identifiers, create indexed signatures with seals
797
798            // Create appropriate seal based on 'last' parameter
799            let seal = if last {
800                // Create SealLast with just the identifier
801                Seal::SealLast(SealLast::new(prefixer.qb64()))
802            } else {
803                // Create SealEvent with identifier, sequence number, and digest
804                // Get the last establishment event info
805                let last_est_sn = kever
806                    .sner
807                    .as_ref()
808                    .ok_or_else(|| ValidationError("Missing sequence number in kever".to_string()))?
809                    .num();
810
811                let last_est_dig = kever
812                    .serder
813                    .as_ref()
814                    .ok_or_else(|| ValidationError("Missing serder in kever".to_string()))?
815                    .said()
816                    .ok_or_else(|| ValidationError("Missing SAID in current event".to_string()))?
817                    .to_string();
818
819                Seal::SealEvent(SealEvent::new(
820                    prefixer.qb64(),              // identifier prefix
821                    format!("{:x}", last_est_sn), // sequence number as hex string
822                    last_est_dig,                 // digest of last establishment event
823                ))
824            };
825
826            // Sign the serder with indexed signatures
827            let sigers = self.sign(
828                &serder.raw(), // ser: serialized event to sign
829                None,          // verfers: use current verfers from kever
830                Some(true),    // indexed: create indexed signatures
831                None,          // indices: let manager choose indices
832                None,          // ondices: no specific ondices
833                None,          // ponly: not ponly mode
834            )?;
835
836            // Create the endorsement message with serder, signatures, and seal
837            let msg = messagize(
838                serder,        // serder: the event being endorsed
839                Some(&sigers), // sigers: indexed signatures
840                Some(seal),    // seal: seal indicating endorser's state
841                None,          // cigars: not used for transferable
842                None,          // wigers: no witness signatures
843                pipelined,     // pipelined: message format
844            )
845            .map_err(|e| ValidationError(format!("Failed to create endorsement message: {}", e)))?;
846
847            Ok(msg)
848        } else {
849            // For non-transferable identifiers, create non-indexed signatures (cigars)
850
851            // As keripy: sign with this Hab's current keys.
852            let verfers = self.kever()?.verfers();
853            // Sign the serder with non-indexed signatures
854            let signatures = self.mgr.sign(
855                &serder.raw(),                           // ser: serialized event to sign
856                None,                                    // pubs: not using public key strings
857                verfers,     // verfers: current keys of this Hab
858                Some(false), // indexed: create non-indexed signatures
859                None,        // indices: not applicable for non-indexed
860                None,        // ondices: not applicable for non-indexed
861                self.pre.as_ref().map(|p| p.as_bytes()), // pre: habitat prefix
862                None,        // path: not specified
863            )?;
864
865            // Extract Cigar instances from Sigmat enum
866            let cigars: Result<Vec<Cigar>, KERIError> = signatures.into_iter()
867                .map(|sig| {
868                    match sig {
869                        Sigmat::NonIndexed(cigar) => Ok(cigar),
870                        Sigmat::Indexed(_) => Err(KERIError::ValidationError(
871                            "Expected Cigar but got Siger - non-indexed signatures required for non-transferable".to_string()
872                        ))
873                    }
874                })
875                .collect();
876
877            let cigars = cigars?;
878
879            // Create the endorsement message with serder and cigars (no seal for non-transferable)
880            let msg = messagize(
881                serder,        // serder: the event being endorsed
882                None,          // sigers: not used for non-transferable
883                None,          // seal: not used for non-transferable
884                None,          // wigers: no witness signatures
885                Some(&cigars), // cigars: non-indexed signatures
886                pipelined,     // pipelined: message format
887            )
888            .map_err(|e| ValidationError(format!("Failed to create endorsement message: {}", e)))?;
889
890            Ok(msg)
891        }
892    }
893    /// Envelope `msg` (a KERI message with its attachments) for `recipient`'s
894    /// mailbox at witness `mbx`, as keripy's `Poster.forwardToWitness` does:
895    /// this identifier's KEL when `mbx` is not one of its own witnesses (keripy
896    /// `forwarding.introduce`, which also skips it once `mbx` has receipted
897    /// our inception), then a `/fwd` `exn` with `msg` embedded at `/e/evt`,
898    /// endorsed by this identifier, then `msg`'s attachments as a pathed group.
899    /// POST the result to `mbx`.
900    ///
901    /// The mailbox stores `msg` under `{recipient}/{topic}`; the recipient's
902    /// keripy agent processes mailbox messages as local.
903    pub fn forward(&self, recipient: &str, topic: &str, msg: &[u8], mbx: &str) -> Result<Vec<u8>, KERIError> {
904        let pre = self
905            .pre
906            .clone()
907            .ok_or_else(|| ValidationError("Habitat not incepted".to_string()))?;
908        let mut out = Vec::new();
909        if !self.kever()?.wits().iter().any(|w| w == mbx) {
910            out.extend(self.replay(None, None)?);
911        }
912        let mut modifiers = IndexMap::new();
913        modifiers.insert("pre".to_string(), SadValue::String(recipient.to_string()));
914        modifiers.insert("topic".to_string(), SadValue::String(topic.to_string()));
915        let (fwd, atc) = crate::keri::core::eventing::exchange::exchange(
916            "/fwd",
917            &pre,
918            IndexMap::new(),
919            modifiers,
920            &[("evt", msg)],
921            None,
922            None,
923            None,
924        )?;
925        out.extend(self.endorse(&fwd, Some(false), Some(false))?);
926        out.extend(atc);
927        Ok(out)
928    }
929    /// Create and process a receipt event for the given serder
930    ///
931    /// Creates a KERI receipt event for the provided event serder, signs it
932    /// with the appropriate signature type based on transferability, and
933    /// processes it into the local database.
934    ///
935    /// # Arguments
936    /// * `serder` - The event serder to create a receipt for
937    ///
938    /// # Returns
939    /// * `Result<Vec<u8>, KERIError>` - The complete receipt message bytes
940    ///
941    /// # Errors
942    /// * `KERIError::ValidationError` - If receipt building, signing, or processing fails
943    /// * `KERIError::ConfigurationError` - If habitat not properly initialized
944    /// * `KERIError::MissingEntryError` - If required kever state is missing
945    pub fn receipt(&mut self, serder: &SerderKERI) -> Result<Vec<u8>, KERIError> {
946        // Extract event details from the provided serder
947        let ked = serder.ked();
948
949        // Get the identifier prefix from the event
950        let pre = ked
951            .get("i")
952            .and_then(|v| match v {
953                SadValue::String(s) => Some(s.clone()),
954                _ => None,
955            })
956            .ok_or_else(|| ValidationError("Missing or invalid identifier in event".to_string()))?;
957
958        // Get the sequence number from the event and convert from hex
959        let sn_hex = ked
960            .get("s")
961            .and_then(|v| match v {
962                SadValue::String(s) => Some(s.clone()),
963                _ => None,
964            })
965            .ok_or_else(|| {
966                ValidationError("Missing or invalid sequence number in event".to_string())
967            })?;
968
969        let sn = usize::from_str_radix(&sn_hex, 16)
970            .map_err(|_| ValidationError("Invalid hex sequence number format".to_string()))?;
971
972        // Get the SAID of the event
973        let said = serder
974            .said()
975            .ok_or_else(|| ValidationError("Missing SAID in event serder".to_string()))?
976            .to_string();
977
978        // Create the receipt event using ReceiptEventBuilder
979        let receipt_serder = ReceiptEventBuilder::new(pre, sn, said)
980            .build()
981            .map_err(|e| ValidationError(format!("Failed to build receipt event: {}", e)))?;
982
983        // Get the current kever to determine signature type
984        let kever = self.kever()?;
985
986        // Get the prefixer and check transferability
987        let prefixer = kever
988            .prefixer
989            .as_ref()
990            .ok_or_else(|| ValidationError("Missing prefixer in kever".to_string()))?;
991
992        let msg = if prefixer.transferable() {
993            // For transferable identifiers, create indexed signatures with seal
994
995            // Get the last establishment event info for the seal
996            let last_est_sn = kever
997                .sner
998                .as_ref()
999                .ok_or_else(|| ValidationError("Missing sequence number in kever".to_string()))?
1000                .num();
1001
1002            let last_est_dig = kever
1003                .serder
1004                .as_ref()
1005                .ok_or_else(|| ValidationError("Missing serder in kever".to_string()))?
1006                .said()
1007                .ok_or_else(|| ValidationError("Missing SAID in current event".to_string()))?
1008                .to_string();
1009
1010            // Create SealEvent with the last establishment event details
1011            let seal = Seal::SealEvent(SealEvent::new(
1012                self.pre
1013                    .as_ref()
1014                    .ok_or_else(|| ConfigurationError("No prefix set for habitat".to_string()))?
1015                    .clone(), // identifier prefix of the receiptor
1016                format!("{:x}", last_est_sn), // sequence number as hex string
1017                last_est_dig,                 // digest of last establishment event
1018            ));
1019
1020            // Sign the original serder (not the receipt) with indexed signatures
1021            let sigers = self.sign(
1022                &serder.raw(), // Sign the original event, not the receipt
1023                None,          // verfers: use current verfers from kever
1024                Some(true),    // indexed: create indexed signatures
1025                None,          // indices: let manager choose indices
1026                None,          // ondices: no specific ondices
1027                None,          // ponly: not ponly mode
1028            )?;
1029
1030            // Create the receipt message with receipt serder, signatures, and seal
1031            messagize(
1032                &receipt_serder, // serder: the receipt event
1033                Some(&sigers),   // sigers: indexed signatures
1034                Some(seal),      // seal: seal indicating receiptor's state
1035                None,            // cigars: not used for transferable
1036                None,            // wigers: no witness signatures
1037                false,           // not pipelined, as keripy Hab.receipt: peers strip one counter
1038            )
1039            .map_err(|e| ValidationError(format!("Failed to create receipt message: {}", e)))?
1040        } else {
1041            // For non-transferable identifiers, create non-indexed signatures (cigars)
1042
1043            // As keripy: sign with this Hab's current keys.
1044            let verfers = self.kever()?.verfers();
1045            // Sign the original serder with non-indexed signatures
1046            let signatures = self.mgr.sign(
1047                &serder.raw(),                           // Sign the original event, not the receipt
1048                None,                                    // pubs: not using public key strings
1049                verfers,                                 // verfers: current keys of this Hab
1050                Some(false),                             // indexed: create non-indexed signatures
1051                None,                                    // indices: not applicable for non-indexed
1052                None,                                    // ondices: not applicable for non-indexed
1053                self.pre.as_ref().map(|p| p.as_bytes()), // pre: habitat prefix
1054                None,                                    // path: not specified
1055            )?;
1056
1057            // Extract Cigar instances from Sigmat enum
1058            let cigars: Result<Vec<Cigar>, KERIError> = signatures.into_iter()
1059                .map(|sig| {
1060                    match sig {
1061                        Sigmat::NonIndexed(cigar) => Ok(cigar),
1062                        Sigmat::Indexed(_) => Err(KERIError::ValidationError(
1063                            "Expected Cigar but got Siger - non-indexed signatures required for non-transferable".to_string()
1064                        ))
1065                    }
1066                })
1067                .collect();
1068
1069            let cigars = cigars?;
1070
1071            // Create the receipt message with receipt serder and cigars (no seal for non-transferable)
1072            messagize(
1073                &receipt_serder, // serder: the receipt event
1074                None,            // sigers: not used for non-transferable
1075                None,            // seal: not used for non-transferable
1076                None,            // wigers: no witness signatures
1077                Some(&cigars),   // cigars: non-indexed signatures
1078                false,           // not pipelined, as keripy Hab.receipt: peers strip one counter
1079            )
1080            .map_err(|e| ValidationError(format!("Failed to create receipt message: {}", e)))?
1081        };
1082
1083        // Process the receipt message locally into the database
1084        // Parse and process the receipt into the local database
1085        self.ingest_local(&msg).map_err(|e| {
1086            ValidationError(format!("Failed to process receipt into database: {}", e))
1087        })?;
1088
1089        Ok(msg)
1090    }
1091
1092    pub fn witness(&mut self, serder: &SerderKERI) -> Result<Vec<u8>, KERIError> {
1093        // Check if this habitat's identifier is transferable (witnesses must be non-transferable)
1094        let kever = self.kever()?;
1095        let prefixer = kever
1096            .prefixer
1097            .as_ref()
1098            .ok_or_else(|| ValidationError("Missing prefixer in kever".to_string()))?;
1099
1100        if prefixer.transferable() {
1101            return Err(ValidationError(format!(
1102                "Attempt to create witness receipt with transferable pre={}",
1103                self.pre.as_deref().unwrap_or("unknown")
1104            )));
1105        }
1106
1107        // Extract event details from the provided serder
1108        let ked = serder.ked();
1109
1110        // Get the identifier prefix from the event being witnessed
1111        let event_pre = ked
1112            .get("i")
1113            .and_then(|v| match v {
1114                SadValue::String(s) => Some(s.clone()),
1115                _ => None,
1116            })
1117            .ok_or_else(|| ValidationError("Missing or invalid identifier in event".to_string()))?;
1118
1119        // Check if we have key state for the event's identifier
1120        if !self.kvy.kevers.contains_key(&event_pre) {
1121            return Err(ValidationError(format!(
1122                "Attempt by {} to witness event with missing key state",
1123                self.pre.as_deref().unwrap_or("unknown")
1124            )));
1125        }
1126
1127        // Get the kever for the event being witnessed
1128        let event_kever = self
1129            .kvy
1130            .kevers
1131            .get(&event_pre)
1132            .ok_or_else(|| MissingEntryError(format!("No kever for prefix {}", event_pre)))?;
1133
1134        // Check if this habitat is in the witness list
1135        let witness_pre = self
1136            .pre
1137            .as_ref()
1138            .ok_or_else(|| ConfigurationError("No prefix set for habitat".to_string()))?;
1139
1140        let witness_index = event_kever.wits().iter().position(|wit| wit == witness_pre);
1141
1142        if witness_index.is_none() {
1143            println!(
1144                "Attempt by {} to witness event of {} when not a witness in wits={:?}",
1145                witness_pre,
1146                event_pre,
1147                event_kever.wits()
1148            );
1149        }
1150
1151        let index = witness_index.unwrap_or(0); // Use 0 as fallback if not found
1152
1153        // Get the sequence number from the event and convert from hex
1154        let sn_hex = ked
1155            .get("s")
1156            .and_then(|v| match v {
1157                SadValue::String(s) => Some(s.clone()),
1158                _ => None,
1159            })
1160            .ok_or_else(|| {
1161                ValidationError("Missing or invalid sequence number in event".to_string())
1162            })?;
1163
1164        let sn = usize::from_str_radix(&sn_hex, 16)
1165            .map_err(|_| ValidationError("Invalid hex sequence number format".to_string()))?;
1166
1167        // Get the SAID of the event
1168        let said = serder
1169            .said()
1170            .ok_or_else(|| ValidationError("Missing SAID in event serder".to_string()))?
1171            .to_string();
1172
1173        // Create the receipt event using ReceiptEventBuilder
1174        let receipt_serder = ReceiptEventBuilder::new(event_pre, sn, said)
1175            .build()
1176            .map_err(|e| ValidationError(format!("Failed to build receipt event: {}", e)))?;
1177
1178        // Since witness id is non-transferable, the public key is the same as the prefix
1179        // Create witness signatures using the manager's sign method
1180        let signatures = self.mgr.sign(
1181            &serder.raw(),                   // Sign the original event, not the receipt
1182            Some(vec![witness_pre.clone()]), // pubs: witness prefix as public key
1183            None,                            // verfers: not using verfers for witness
1184            Some(true),                      // indexed: create indexed signatures
1185            Some(vec![index as u32]),        // indices: witness index in the witness list
1186            None,                            // ondices: not applicable
1187            None,                            // pre: not using pre-based signing
1188            None,                            // path: not specified
1189        )?;
1190
1191        // Extract Siger instances from Sigmat enum (witnesses use indexed signatures)
1192        let wigers: Result<Vec<Siger>, KERIError> = signatures
1193            .into_iter()
1194            .map(|sig| match sig {
1195                Sigmat::Indexed(siger) => Ok(siger),
1196                Sigmat::NonIndexed(_) => Err(KERIError::ValidationError(
1197                    "Expected Siger but got Cigar - indexed signatures required for witness"
1198                        .to_string(),
1199                )),
1200            })
1201            .collect();
1202
1203        let wigers = wigers?;
1204
1205        // Create the witness receipt message with receipt serder and witness signatures
1206        let msg = messagize(
1207            &receipt_serder, // serder: the receipt event
1208            None,            // sigers: not used for witness receipts
1209            None,            // seal: not used for witness receipts
1210            Some(&wigers),   // wigers: witness signatures
1211            None,            // cigars: not used for witness receipts
1212            true,            // pipelined: standard message format
1213        )
1214        .map_err(|e| ValidationError(format!("Failed to create witness receipt message: {}", e)))?;
1215
1216        // Process local copy into database
1217        self.ingest_local(&msg)?;
1218
1219        Ok(msg)
1220    }
1221    /// Replay events for the given prefix starting from the specified first seen number.
1222    ///
1223    /// This method creates a complete replay by first including the delegation chain
1224    /// (if the identifier is delegated), then including all events for the prefix
1225    /// starting from the specified first seen ordinal number.
1226    ///
1227    /// # Parameters
1228    /// * `pre` - Optional identifier prefix as string. If None, uses self.pre
1229    /// * `fn_num` - Optional first seen number to start replay from. Default is 0
1230    ///
1231    /// # Returns
1232    /// * `Result<Vec<u8>, KERIError>` - Concatenated messages representing the complete replay
1233    pub fn replay(&self, pre: Option<&str>, fn_num: Option<u64>) -> Result<Vec<u8>, KERIError> {
1234        // Use provided prefix or default to self.pre
1235        let replay_pre = if let Some(p) = pre {
1236            p.to_string()
1237        } else {
1238            self.pre
1239                .as_ref()
1240                .ok_or_else(|| {
1241                    KERIError::ConfigurationError("No prefix set for habitat".to_string())
1242                })?
1243                .clone()
1244        };
1245
1246        let fn_start = fn_num.unwrap_or(0);
1247        let mut msgs = Vec::new();
1248
1249        // Get the kever for the prefix we're replaying
1250        let kever = self.kvy.kevers.get(&replay_pre).ok_or_else(|| {
1251            KERIError::MissingEntryError(format!("No kever for prefix {}", replay_pre))
1252        })?;
1253
1254        // First clone the delegation chain if this is a delegated identifier
1255        let delegation_msgs = self
1256            .db
1257            .clone_delegation(kever, &self.kvy.kevers)
1258            .map_err(|e| KERIError::DatabaseError(format!("Failed to clone delegation: {}", e)))?;
1259
1260        for msg in delegation_msgs {
1261            msgs.extend(msg);
1262        }
1263
1264        // Then clone all events for this prefix starting from fn
1265        let prefix_msgs = self
1266            .db
1267            .clone_pre_iter(&replay_pre, Some(fn_start))
1268            .map_err(|e| {
1269                KERIError::DatabaseError(format!("Failed to clone prefix events: {}", e))
1270            })?;
1271
1272        for msg in prefix_msgs {
1273            msgs.extend(msg);
1274        }
1275
1276        Ok(msgs)
1277    }
1278
1279    /// Replay all events for all identifier prefixes in the database.
1280    ///
1281    /// This method creates a complete replay of all events across all prefixes
1282    /// in first seen order with attachments. Useful for database synchronization
1283    /// and backup scenarios.
1284    ///
1285    /// # Returns
1286    /// * `Result<Vec<u8>, KERIError>` - Concatenated messages representing all events
1287    pub fn replay_all(&self) -> Result<Vec<u8>, KERIError> {
1288        let mut msgs = Vec::new();
1289
1290        // Get all event messages from the database
1291        let all_msgs = self
1292            .db
1293            .clone_all_pre_iter()
1294            .map_err(|e| KERIError::DatabaseError(format!("Failed to clone all events: {}", e)))?;
1295
1296        // Concatenate all messages
1297        for msg in all_msgs {
1298            msgs.extend(msg);
1299        }
1300
1301        Ok(msgs)
1302    }
1303    /// Make other event message for given prefix and sequence number.
1304    ///
1305    /// # Parameters
1306    /// * `pre` - The prefix identifier
1307    /// * `sn` - The sequence number
1308    ///
1309    /// # Returns
1310    /// * `Ok(Some(Vec<u8>))` - The event message bytes if found
1311    /// * `Ok(None)` - If prefix not in kevers
1312    /// * `Err(KERIError)` - If missing event or other error
1313    pub fn make_other_event(
1314        &self,
1315        pre: impl AsRef<[u8]>,
1316        sn: u64,
1317    ) -> Result<Option<Vec<u8>>, KERIError> {
1318        let pre_bytes = pre.as_ref();
1319
1320        // Convert bytes to string for kevers lookup
1321        let pre_str = String::from_utf8_lossy(pre_bytes);
1322
1323        // Check if prefix exists in kevers
1324        if !self.kevers().contains_key(pre_str.as_ref()) {
1325            return Ok(None);
1326        }
1327
1328        let mut msg = Vec::<u8>::new();
1329
1330        // Get the last digest for this prefix and sequence number
1331        let sn_key = sn_key(pre_bytes, sn);
1332        let dig = match self.db.get_ke_last(&sn_key)? {
1333            Some(digest) => digest,
1334            None => {
1335                return Err(KERIError::MissingEntryError(format!(
1336                    "Missing event for pre={} at sn={}",
1337                    pre_str, sn
1338                )));
1339            }
1340        };
1341
1342        // Create digest key and get event
1343        let key = dg_key(pre_bytes, dig.as_bytes());
1344        let evt = match self.db.get_evt(&key)? {
1345            Some(event) => event,
1346            None => {
1347                return Err(KERIError::MissingEntryError(format!(
1348                    "Missing event data for key"
1349                )));
1350            }
1351        };
1352        msg.extend_from_slice(&evt);
1353
1354        // Get signature count and create counter
1355        let sig_count = self.db.cnt_sigs(&key)?;
1356        let base_counter = BaseCounter::from_code_and_count(
1357            Some(ctr_dex_1_0::CONTROLLER_IDX_SIGS),
1358            Some(sig_count as u64),
1359            None,
1360        )
1361        .map_err(|e| KERIError::CounterError(format!("Failed to create counter: {}", e)))?;
1362
1363        // Use as Counter trait and get qb64 bytes
1364        let counter: &dyn Counter = &base_counter;
1365        let counter_bytes = counter.qb64b();
1366        msg.extend_from_slice(&counter_bytes);
1367
1368        // Attach all signatures
1369        for sig_result in self.db.get_sigs_iter(&key)? {
1370            let sig = sig_result?;
1371            msg.extend_from_slice(&sig);
1372        }
1373
1374        Ok(Some(msg))
1375    }
1376    /// Fetch endpoint record for given cid, role, and eid
1377    ///
1378    /// # Parameters
1379    /// * `cid` - Controller identifier (qb64 prefix)
1380    /// * `role` - Role such as watcher, witness
1381    /// * `eid` - Endpoint identifier
1382    ///
1383    /// # Returns
1384    /// * `Ok(Some(EndpointRecord))` - If record found
1385    /// * `Ok(None)` - If no record found
1386    /// * `Err(KERIError)` - On database error
1387    pub fn fetch_end(
1388        &self,
1389        cid: &str,
1390        role: &str,
1391        eid: &str,
1392    ) -> Result<Option<EndpointRecord>, KERIError> {
1393        let keys = [cid.as_bytes(), role.as_bytes(), eid.as_bytes()];
1394        self.db.ends.get(&keys).map_err(|e| {
1395            KERIError::DatabaseError(format!("Failed to fetch endpoint record: {}", e))
1396        })
1397    }
1398
1399    /// Fetch location record for given eid and scheme
1400    ///
1401    /// # Parameters
1402    /// * `eid` - Endpoint identifier
1403    /// * `scheme` - URL protocol scheme (defaults to "http")
1404    ///
1405    /// # Returns
1406    /// * `Ok(Some(LocationRecord))` - If record found
1407    /// * `Ok(None)` - If no record found
1408    /// * `Err(KERIError)` - On database error
1409    pub fn fetch_loc(
1410        &self,
1411        eid: &str,
1412        scheme: Option<&str>,
1413    ) -> Result<Option<LocationRecord>, KERIError> {
1414        let scheme = scheme.unwrap_or("http"); // Default to HTTP scheme
1415        let keys = [eid.as_bytes(), scheme.as_bytes()];
1416        self.db.locs.get(&keys).map_err(|e| {
1417            KERIError::DatabaseError(format!("Failed to fetch location record: {}", e))
1418        })
1419    }
1420
1421    /// Fetch endpoint allowed status for given cid, role, and eid
1422    ///
1423    /// # Parameters
1424    /// * `cid` - Controller identifier (qb64 prefix)
1425    /// * `role` - Role such as watcher, witness
1426    /// * `eid` - Endpoint identifier
1427    ///
1428    /// # Returns
1429    /// * `Ok(Some(bool))` - If record found and allowed status is set
1430    /// * `Ok(None)` - If no record found or allowed status is None
1431    /// * `Err(KERIError)` - On database error
1432    pub fn fetch_end_allowed(
1433        &self,
1434        cid: &str,
1435        role: &str,
1436        eid: &str,
1437    ) -> Result<Option<bool>, KERIError> {
1438        match self.fetch_end(cid, role, eid)? {
1439            Some(end) => Ok(end.allowed),
1440            None => Ok(None),
1441        }
1442    }
1443
1444    /// Fetch endpoint enabled status for given cid, role, and eid
1445    ///
1446    /// # Parameters
1447    /// * `cid` - Controller identifier (qb64 prefix)
1448    /// * `role` - Role such as watcher, witness
1449    /// * `eid` - Endpoint identifier
1450    ///
1451    /// # Returns
1452    /// * `Ok(Some(bool))` - If record found and enabled status is set
1453    /// * `Ok(None)` - If no record found or enabled status is None
1454    /// * `Err(KERIError)` - On database error
1455    pub fn fetch_end_enabled(
1456        &self,
1457        cid: &str,
1458        role: &str,
1459        eid: &str,
1460    ) -> Result<Option<bool>, KERIError> {
1461        match self.fetch_end(cid, role, eid)? {
1462            Some(end) => Ok(end.enabled),
1463            None => Ok(None),
1464        }
1465    }
1466
1467    /// Fetch endpoint authorization status (enabled OR allowed) for given cid, role, and eid
1468    ///
1469    /// # Parameters
1470    /// * `cid` - Controller identifier (qb64 prefix)
1471    /// * `role` - Role such as watcher, witness
1472    /// * `eid` - Endpoint identifier
1473    ///
1474    /// # Returns
1475    /// * `Ok(Some(bool))` - If record found and either enabled or allowed is true
1476    /// * `Ok(None)` - If no record found or both enabled and allowed are None/false
1477    /// * `Err(KERIError)` - On database error
1478    pub fn fetch_end_authzed(
1479        &self,
1480        cid: &str,
1481        role: &str,
1482        eid: &str,
1483    ) -> Result<Option<bool>, KERIError> {
1484        match self.fetch_end(cid, role, eid)? {
1485            Some(end) => {
1486                let authorized = end.enabled.unwrap_or(false) || end.allowed.unwrap_or(false);
1487                if authorized {
1488                    Ok(Some(true))
1489                } else {
1490                    // Return None if both are None or false
1491                    if end.enabled.is_none() && end.allowed.is_none() {
1492                        Ok(None)
1493                    } else {
1494                        Ok(Some(false))
1495                    }
1496                }
1497            }
1498            None => Ok(None),
1499        }
1500    }
1501
1502    /// Fetch URL for given eid and scheme
1503    ///
1504    /// # Parameters
1505    /// * `eid` - Endpoint identifier
1506    /// * `scheme` - URL protocol scheme (defaults to "http")
1507    ///
1508    /// # Returns
1509    /// * `Ok(Some(String))` - If location record found, returns the URL
1510    /// * `Ok(None)` - If no location record found
1511    /// * `Err(KERIError)` - On database error
1512    pub fn fetch_url(&self, eid: &str, scheme: Option<&str>) -> Result<Option<String>, KERIError> {
1513        match self.fetch_loc(eid, scheme)? {
1514            Some(loc) => Ok(Some(loc.url)),
1515            None => Ok(None),
1516        }
1517    }
1518
1519    /// Fetch URLs for given eid and optional scheme filter
1520    /// Returns a Mict containing (scheme, url) pairs for all matching locations
1521    ///
1522    /// # Parameters
1523    /// * `eid` - Endpoint identifier
1524    /// * `scheme` - Optional scheme filter (empty string means all schemes)
1525    ///
1526    /// # Returns
1527    /// * `Ok(Mict<String, String>)` - Mict containing scheme->url mappings
1528    /// * `Err(KERIError)` - On database error
1529    pub fn fetch_urls(
1530        &self,
1531        eid: &str,
1532        scheme: Option<&str>,
1533    ) -> Result<Mict<String, String>, KERIError> {
1534        let scheme_filter = scheme.unwrap_or("");
1535
1536        // Get vector of location records matching the eid and scheme pattern
1537        let items = self
1538            .db
1539            .locs
1540            .get_item_iter(&[eid.as_bytes(), scheme_filter.as_bytes()])
1541            .map_err(|e| {
1542                KERIError::DatabaseError(format!("Failed to get location items: {}", e))
1543            })?;
1544
1545        // Filter and transform the items using into_iter()
1546        let url_pairs: Vec<(String, String)> = items
1547            .into_iter()
1548            .filter_map(|(keys, loc)| {
1549                // Only include locations with non-empty URLs
1550                if !loc.url.is_empty() && keys.len() >= 2 {
1551                    // Extract scheme from keys[1] and pair with URL
1552                    Some((keys[1].clone(), loc.url))
1553                } else {
1554                    None
1555                }
1556            })
1557            .collect();
1558
1559        Ok(Mict::from_iter(url_pairs))
1560    }
1561
1562    /// Fetch role URLs for given cid, role, and optional filters
1563    /// Returns a Mict containing role -> Mict(eid -> urls) mappings
1564    ///
1565    /// # Parameters
1566    /// * `cid` - Controller identifier
1567    /// * `role` - Optional role filter (empty string means all roles)
1568    /// * `scheme` - Optional scheme filter (empty string means all schemes)
1569    /// * `eids` - Optional list of endpoint identifiers to filter by
1570    /// * `enabled` - Whether to include enabled endpoints
1571    /// * `allowed` - Whether to include allowed endpoints
1572    ///
1573    /// # Returns
1574    /// * `Ok(Mict<String, Mict<String, Mict<String, String>>>)` - Nested Mict structure
1575    /// * `Err(KERIError)` - On database error
1576    pub fn fetch_role_urls(
1577        &self,
1578        cid: &str,
1579        role: Option<&str>,
1580        scheme: Option<&str>,
1581        eids: Option<&[String]>,
1582        enabled: bool,
1583        allowed: bool,
1584    ) -> Result<Mict<String, Mict<String, Mict<String, String>>>, KERIError> {
1585        let role_filter = role.unwrap_or("");
1586        let mut rurls = Mict::new();
1587
1588        // Special handling for witness role - get from kever's witness list
1589        if role_filter == Roles::Witness.as_str() || role_filter.is_empty() {
1590            if let Some(kever) = self.kevers().get(cid) {
1591                // Latest key state for cid - iterate through witnesses
1592                for wit in &kever.wits {
1593                    // Convert Vec<String> to a single string (assuming it's a prefix or identifier)
1594                    let eid = wit.join(""); // or wit[0] if you only need the first element
1595
1596                    if eids.is_none() || eids.unwrap().contains(&eid) {
1597                        let surls = self.fetch_urls(&eid, scheme)?;
1598                        if !surls.is_empty() {
1599                            let mut eid_urls = Mict::new();
1600                            eid_urls.add(eid.clone(), surls);
1601                            rurls.add(Roles::Witness.as_str().to_string(), eid_urls);
1602                        }
1603                    }
1604                }
1605            }
1606        }
1607
1608        // Get endpoints from database
1609        let items = self
1610            .db
1611            .ends
1612            .get_item_iter(&[cid.as_bytes(), role_filter.as_bytes()])
1613            .map_err(|e| {
1614                KERIError::DatabaseError(format!("Failed to get endpoint items: {}", e))
1615            })?;
1616
1617        for (keys, end) in items {
1618            // Check authorization (enabled or allowed as requested)
1619            let is_authorized = (enabled && end.enabled.unwrap_or(false))
1620                || (allowed && end.allowed.unwrap_or(false));
1621
1622            if is_authorized && keys.len() >= 3 {
1623                let erole = &keys[1]; // role from database key
1624                let eid = &keys[2]; // eid from database key
1625
1626                // Filter by eids if provided
1627                if eids.is_none() || eids.unwrap().contains(eid) {
1628                    let surls = self.fetch_urls(eid, scheme)?;
1629                    if !surls.is_empty() {
1630                        let mut eid_urls = Mict::new();
1631                        eid_urls.add(eid.clone(), surls);
1632                        rurls.add(erole.clone(), eid_urls);
1633                    }
1634                }
1635            }
1636        }
1637
1638        Ok(rurls)
1639    }
1640
1641    /// Fetch witness URLs for given cid
1642    /// Convenience method that calls fetch_role_urls with witness role
1643    ///
1644    /// # Parameters
1645    /// * `cid` - Controller identifier
1646    /// * `scheme` - Optional scheme filter (empty string means all schemes)
1647    /// * `eids` - Optional list of endpoint identifiers to filter by
1648    /// * `enabled` - Whether to include enabled endpoints
1649    /// * `allowed` - Whether to include allowed endpoints
1650    ///
1651    /// # Returns
1652    /// * `Ok(Mict<String, Mict<String, Mict<String, String>>>)` - Nested Mict structure
1653    /// * `Err(KERIError)` - On database error
1654    pub fn fetch_witness_urls(
1655        &self,
1656        cid: &str,
1657        scheme: Option<&str>,
1658        eids: Option<&[String]>,
1659        enabled: bool,
1660        allowed: bool,
1661    ) -> Result<Mict<String, Mict<String, Mict<String, String>>>, KERIError> {
1662        self.fetch_role_urls(
1663            cid,
1664            Some(Roles::Witness.as_str()),
1665            scheme,
1666            eids,
1667            enabled,
1668            allowed,
1669        )
1670    }
1671
1672    /// Get all endpoints for a given prefix, organized by role and endpoint ID
1673    /// Returns a nested HashMap structure: role -> eid -> scheme -> url
1674    ///
1675    /// # Parameters
1676    /// * `pre` - Prefix (controller identifier)
1677    ///
1678    /// # Returns
1679    /// * `Ok(HashMap<String, HashMap<String, HashMap<String, String>>>)` - Nested structure of endpoints
1680    /// * `Err(KERIError)` - On database error
1681    pub fn ends_for(
1682        &self,
1683        pre: &str,
1684    ) -> Result<HashMap<String, HashMap<String, HashMap<String, String>>>, KERIError> {
1685        let mut ends: HashMap<String, HashMap<String, HashMap<String, String>>> = HashMap::new();
1686
1687        // Get all endpoints from database for the given prefix
1688        let items = self.db.ends.get_item_iter(&[pre.as_bytes()]).map_err(|e| {
1689            KERIError::DatabaseError(format!("Failed to get endpoint items: {}", e))
1690        })?;
1691
1692        for (keys, end) in items {
1693            if keys.len() >= 3 {
1694                let erole = &keys[1]; // role from database key
1695                let eid = &keys[2]; // eid from database key
1696
1697                // Fetch URLs for this endpoint
1698                let urls = self.fetch_urls(eid, None)?;
1699
1700                // Convert URLs to HashMap using firsts() method
1701                let mut locs: HashMap<String, String> = HashMap::new();
1702                for (rscheme, url) in urls.firsts() {
1703                    locs.insert(rscheme, url);
1704                }
1705
1706                // Initialize role entry if it doesn't exist
1707                if !ends.contains_key(erole) {
1708                    ends.insert(erole.clone(), HashMap::new());
1709                }
1710
1711                // Add the location mapping for this endpoint
1712                ends.get_mut(erole).unwrap().insert(eid.clone(), locs);
1713            }
1714        }
1715
1716        // Handle witness endpoints separately from kever
1717        let mut witrolls: HashMap<String, HashMap<String, String>> = HashMap::new();
1718
1719        if let Some(kever) = self.kevers().get(pre) {
1720            let witness_ids = kever.wits();
1721
1722            for eid in witness_ids {
1723                // Fetch URLs for this witness endpoint
1724                let urls = self.fetch_urls(&eid, None)?;
1725
1726                // Convert URLs to HashMap using firsts() method
1727                let mut locs: HashMap<String, String> = HashMap::new();
1728                for (rscheme, url) in urls.firsts() {
1729                    locs.insert(rscheme, url);
1730                }
1731
1732                witrolls.insert(eid, locs);
1733            }
1734        }
1735
1736        // Add witness endpoints if any exist
1737        if !witrolls.is_empty() {
1738            ends.insert(Roles::Witness.as_str().to_string(), witrolls);
1739        }
1740
1741        Ok(ends)
1742    }
1743
1744    /// Create and endorse a reply event
1745    ///
1746    /// # Parameters
1747    /// * `route` - Namespaced path that indicates data flow handler
1748    /// * `data` - Optional attribute section of reply
1749    /// * `stamp` - Optional timestamp (RFC-3339 format)
1750    /// * `version` - Optional version string
1751    /// * `kind` - Optional serialization kind
1752    /// * `last` - Optional flag for seal type (default: false)
1753    /// * `pipelined` - Optional flag for message format (default: true)
1754    ///
1755    /// # Returns
1756    /// * `Ok(Vec<u8>)` - Endorsed reply message
1757    /// * `Err(KERIError)` - On validation or signing error
1758    pub fn reply(
1759        &self,
1760        route: String,
1761        data: Option<IndexMap<String, SadValue>>,
1762        stamp: Option<String>,
1763        version: Option<String>,
1764        kind: Option<String>,
1765        last: Option<bool>,
1766        pipelined: Option<bool>,
1767    ) -> Result<Vec<u8>, KERIError> {
1768        // Build the reply event using ReplyEventBuilder
1769        let mut builder = ReplyEventBuilder::new().with_route(route);
1770
1771        if let Some(data) = data {
1772            builder = builder.with_data(data);
1773        }
1774
1775        if let Some(stamp) = stamp {
1776            builder = builder.with_stamp(stamp);
1777        }
1778
1779        if let Some(version) = version {
1780            builder = builder.with_version(version);
1781        }
1782
1783        if let Some(kind) = kind {
1784            builder = builder.with_kind(kind);
1785        }
1786
1787        // Build the serder
1788        let serder = builder.build()?;
1789
1790        // Endorse the reply event
1791        self.endorse(&serder, last, pipelined)
1792    }
1793
1794    /// Create and endorse an endpoint role management reply event
1795    ///
1796    /// # Parameters
1797    /// * `eid` - Endpoint identifier
1798    /// * `role` - Role to assign (default: Controller)
1799    /// * `allow` - If true, adds the role; if false, removes it (default: true)
1800    /// * `stamp` - Optional timestamp (RFC-3339 format)
1801    ///
1802    /// # Returns
1803    /// * `Ok(Vec<u8>)` - Endorsed endpoint role reply message
1804    /// * `Err(KERIError)` - On validation or signing error
1805    pub fn make_end_role(
1806        &self,
1807        eid: String,
1808        role: Option<Roles>,
1809        allow: Option<bool>,
1810        stamp: Option<String>,
1811    ) -> Result<Vec<u8>, KERIError> {
1812        let role = role.unwrap_or(Roles::Controller);
1813        let allow = allow.unwrap_or(true);
1814
1815        // Get the habitat's prefix
1816        let pre = self
1817            .pre
1818            .as_ref()
1819            .ok_or_else(|| KERIError::ValidationError("Missing habitat prefix".to_string()))?;
1820
1821        // Create data payload
1822        let mut data = IndexMap::new();
1823        data.insert("cid".to_string(), SadValue::String(pre.clone()));
1824        data.insert(
1825            "role".to_string(),
1826            SadValue::String(role.as_str().to_string()),
1827        );
1828        data.insert("eid".to_string(), SadValue::String(eid));
1829
1830        // Determine route based on allow flag
1831        let route = if allow {
1832            "/end/role/add".to_string()
1833        } else {
1834            "/end/role/cut".to_string()
1835        };
1836
1837        // Create and endorse the reply
1838        self.reply(route, Some(data), stamp, None, None, None, None)
1839    }
1840
1841    /// Load and reconstruct an endpoint role message from the database
1842    ///
1843    /// # Parameters
1844    /// * `cid` - Controller identifier
1845    /// * `eid` - Endpoint identifier  
1846    /// * `role` - Role to load (default: Controller)
1847    ///
1848    /// # Returns
1849    /// * `Ok(Vec<u8>)` - Reconstructed message bytes
1850    /// * `Err(KERIError)` - On database error or validation failure
1851    pub fn load_end_role(
1852        &self,
1853        cid: &str,
1854        eid: &str,
1855        role: Option<Roles>,
1856    ) -> Result<Vec<u8>, KERIError> {
1857        let role = role.unwrap_or(Roles::Controller);
1858        let mut msgs = Vec::new();
1859
1860        // Check if endpoint exists and is enabled/allowed
1861        let end = self
1862            .db
1863            .ends
1864            .get(&[cid.as_bytes(), role.as_str().as_bytes(), eid.as_bytes()])
1865            .map_err(|e| KERIError::DatabaseError(format!("Failed to get endpoint: {}", e)))?;
1866
1867        if let Some(end) = end {
1868            // Fix: Handle Option<bool> properly - default to false if None
1869            if end.enabled.unwrap_or(false) || end.allowed.unwrap_or(false) {
1870                // Get the SAID for this endpoint role
1871                let said = self
1872                    .db
1873                    .eans
1874                    .get(&[cid.as_bytes(), role.as_str().as_bytes(), eid.as_bytes()])
1875                    .map_err(|e| KERIError::DatabaseError(format!("Failed to get SAID: {}", e)))?;
1876
1877                if let Some(said) = said {
1878                    // Get the reply serder
1879                    let serder = self.db.rpys.get(&[said.qb64().as_bytes()]).map_err(|e| {
1880                        KERIError::DatabaseError(format!("Failed to get reply: {}", e))
1881                    })?;
1882
1883                    if let Some(serder) = serder {
1884                        // Get cigars (non-transferable signatures)
1885                        let cigars_result =
1886                            self.db.scgs.get(&[said.qb64().as_bytes()]).map_err(|e| {
1887                                KERIError::DatabaseError(format!("Failed to get cigars: {}", e))
1888                            })?;
1889
1890                        // Get transferable signature groups
1891                        let tsgs = self.db.fetch_tsgs(said, None)?;
1892
1893                        // Process cigars
1894                        let cigar = if cigars_result.len() == 1 && cigars_result[0].len() == 2 {
1895                            // Extract verfer and cigar from the pair
1896                            let verfer_matter = &cigars_result[0][0];
1897                            let cigar_matter = &cigars_result[0][1];
1898
1899                            // Fix: Handle Option types from downcast_ref properly
1900                            if let (Some(verfer), Some(cigar)) = (
1901                                verfer_matter.as_any().downcast_ref::<Verfer>(),
1902                                cigar_matter.as_any().downcast_ref::<Cigar>(),
1903                            ) {
1904                                // Create a mutable clone and set the verfer
1905                                let mut cigar_clone = cigar.clone();
1906                                cigar_clone.set_verfer(verfer.clone());
1907                                Some(cigar_clone)
1908                            } else {
1909                                None
1910                            }
1911                        } else {
1912                            None
1913                        };
1914
1915                        // Process transferable signature groups
1916                        let (sigers, seal) = if !tsgs.is_empty() {
1917                            let (prefixer, seqner, diger, sigers) = &tsgs[0];
1918
1919                            let seal = SealEvent::new(prefixer.qb64(), seqner.snh(), diger.qb64());
1920
1921                            (Some(sigers.as_slice()), Some(Seal::SealEvent(seal)))
1922                        } else {
1923                            (None, None)
1924                        };
1925
1926                        // Create the message
1927                        let cigars_slice: Option<&[Cigar]> = if let Some(ref cigar) = cigar {
1928                            // Fix: Provide explicit type annotation for the slice
1929                            Some(std::slice::from_ref(cigar))
1930                        } else {
1931                            None
1932                        };
1933
1934                        let msg = messagize(
1935                            &serder,
1936                            sigers,
1937                            seal,
1938                            None, // wigers
1939                            cigars_slice,
1940                            true, // pipelined
1941                        )
1942                        .map_err(|e| {
1943                            KERIError::ValidationError(format!("Failed to create message: {}", e))
1944                        })?;
1945
1946                        msgs.extend(msg);
1947                    }
1948                }
1949            }
1950        }
1951
1952        Ok(msgs)
1953    }
1954
1955    /// Create and endorse a location scheme reply message
1956    ///
1957    /// # Parameters
1958    /// * `url` - The URL for this location scheme
1959    /// * `eid` - Optional endpoint identifier (defaults to self.pre)
1960    /// * `scheme` - Scheme type (default: "http")
1961    /// * `stamp` - Optional timestamp (RFC-3339 format)
1962    ///
1963    /// # Returns
1964    /// * `Ok(Vec<u8>)` - Endorsed location scheme reply message
1965    /// * `Err(KERIError)` - On validation or signing error
1966    pub fn make_loc_scheme(
1967        &self,
1968        url: String,
1969        eid: Option<String>,
1970        scheme: Option<String>,
1971        stamp: Option<String>,
1972    ) -> Result<Vec<u8>, KERIError> {
1973        let eid = match eid {
1974            Some(eid) => eid,
1975            None => self.pre.clone().ok_or_else(|| {
1976                KERIError::ValueError("No pre available for default eid".to_string())
1977            })?,
1978        };
1979
1980        let scheme = scheme.unwrap_or_else(|| "http".to_string());
1981
1982        // Create the data payload
1983        let mut data = IndexMap::new();
1984        data.insert("eid".to_string(), SadValue::String(eid));
1985        data.insert("scheme".to_string(), SadValue::String(scheme));
1986        data.insert("url".to_string(), SadValue::String(url));
1987
1988        // Create the reply message
1989        self.reply(
1990            "/loc/scheme".to_string(),
1991            Some(data),
1992            stamp,
1993            None, // version
1994            None, // kind
1995            None, // last
1996            None, // pipelined
1997        )
1998    }
1999
2000    /// Create reply messages for all location schemes matching the given eid and scheme
2001    ///
2002    /// # Parameters
2003    /// * `eid` - Endpoint identifier
2004    /// * `scheme` - Optional scheme filter (empty string means all schemes)
2005    ///
2006    /// # Returns
2007    /// * `Ok(Vec<u8>)` - Combined reply messages for all matching location schemes
2008    /// * `Err(KERIError)` - On database error or message creation failure
2009    pub fn reply_loc_scheme(
2010        &self,
2011        eid: String,
2012        scheme: Option<String>,
2013    ) -> Result<Vec<u8>, KERIError> {
2014        let mut msgs = Vec::new();
2015        let scheme_filter = scheme.as_deref().unwrap_or("");
2016
2017        // Fetch URLs for the given eid and scheme
2018        let urls = self.fetch_urls(&eid, Some(scheme_filter))?;
2019
2020        // Iterate over the first occurrence of each scheme-url pair
2021        for (rscheme, url) in urls.firsts() {
2022            let scheme_msg = self.make_loc_scheme(
2023                url.clone(),
2024                Some(eid.clone()),
2025                Some(rscheme.clone()),
2026                None, // stamp
2027            )?;
2028            msgs.extend(scheme_msg);
2029        }
2030
2031        Ok(msgs)
2032    }
2033
2034    /// Load and reconstruct location scheme messages from the database
2035    ///
2036    /// # Parameters
2037    /// * `eid` - Endpoint identifier
2038    /// * `scheme` - Optional scheme filter (None means all schemes)
2039    ///
2040    /// # Returns
2041    /// * `Ok(Vec<u8>)` - Reconstructed message bytes
2042    /// * `Err(KERIError)` - On database error or validation failure
2043    pub fn load_loc_scheme(&self, eid: &str, scheme: Option<&str>) -> Result<Vec<u8>, KERIError> {
2044        let mut msgs = Vec::new();
2045
2046        // Build keys based on whether scheme is provided
2047        let keys: Vec<&[u8]> = if let Some(scheme) = scheme {
2048            vec![eid.as_bytes(), scheme.as_bytes()]
2049        } else {
2050            vec![eid.as_bytes()]
2051        };
2052
2053        // Get items from lans database
2054        let items = self.db.lans.get_item_iter(&keys, false).map_err(|e| {
2055            KERIError::DatabaseError(format!("Failed to get location items: {}", e))
2056        })?;
2057
2058        for (pre_keys, said_bytes) in items {
2059            // Convert said_bytes to Saider
2060            let said = Saider::from_qb64(&String::from_utf8_lossy(&said_bytes))
2061                .map_err(|e| KERIError::ValidationError(format!("Invalid SAID: {}", e)))?;
2062
2063            // Get the reply serder
2064            let serder = self
2065                .db
2066                .rpys
2067                .get(&[said.qb64().as_bytes()])
2068                .map_err(|e| KERIError::DatabaseError(format!("Failed to get reply: {}", e)))?;
2069
2070            if let Some(serder) = serder {
2071                // Get cigars (non-transferable signatures)
2072                let cigars_result = self.db.scgs.get(&[said.qb64().as_bytes()]).map_err(|e| {
2073                    KERIError::DatabaseError(format!("Failed to get cigars: {}", e))
2074                })?;
2075
2076                // Get transferable signature groups
2077                let tsgs = self.db.fetch_tsgs(said, None)?;
2078
2079                // Process cigars
2080                let cigar = if cigars_result.len() == 1 && cigars_result[0].len() == 2 {
2081                    // Extract verfer and cigar from the pair
2082                    let verfer_matter = &cigars_result[0][0];
2083                    let cigar_matter = &cigars_result[0][1];
2084
2085                    // Convert Matter to appropriate types
2086                    if let (Some(verfer), Some(cigar)) = (
2087                        verfer_matter.as_any().downcast_ref::<Verfer>(),
2088                        cigar_matter.as_any().downcast_ref::<Cigar>(),
2089                    ) {
2090                        // Create a mutable clone and set the verfer
2091                        let mut cigar_clone = cigar.clone();
2092                        cigar_clone.set_verfer(verfer.clone());
2093                        Some(cigar_clone)
2094                    } else {
2095                        None
2096                    }
2097                } else {
2098                    None
2099                };
2100
2101                // Process transferable signature groups
2102                let (sigers, seal) = if !tsgs.is_empty() {
2103                    let (prefixer, seqner, diger, sigers) = &tsgs[0];
2104
2105                    let seal = SealEvent::new(prefixer.qb64(), seqner.snh(), diger.qb64());
2106
2107                    (Some(sigers.as_slice()), Some(Seal::SealEvent(seal)))
2108                } else {
2109                    (None, None)
2110                };
2111
2112                // Create the message
2113                let cigars_slice: Option<&[Cigar]> = if let Some(ref cigar) = cigar {
2114                    Some(std::slice::from_ref(cigar))
2115                } else {
2116                    None
2117                };
2118
2119                let msg = messagize(
2120                    &serder,
2121                    sigers,
2122                    seal,
2123                    None, // wigers
2124                    cigars_slice,
2125                    true, // pipelined
2126                )
2127                .map_err(|e| {
2128                    KERIError::ValidationError(format!("Failed to create message: {}", e))
2129                })?;
2130
2131                msgs.extend(msg);
2132            }
2133        }
2134
2135        Ok(msgs)
2136    }
2137
2138    /// Reply with endpoint role information for a given controller identifier
2139    ///
2140    /// # Parameters
2141    /// * `cid` - Controller identifier
2142    /// * `role` - Optional role filter (None means all roles)
2143    /// * `eids` - Optional list of endpoint identifiers to filter by
2144    /// * `scheme` - Scheme filter for location queries (empty string means all schemes)
2145    ///
2146    /// # Returns
2147    /// * `Ok(Vec<u8>)` - Combined reply messages
2148    /// * `Err(KERIError)` - On database error or validation failure
2149    pub fn reply_end_role(
2150        &self,
2151        cid: &str,
2152        role: Option<Roles>,
2153        eids: Option<&[String]>,
2154        scheme: Option<&str>,
2155    ) -> Result<Vec<u8>, KERIError> {
2156        let mut msgs = Vec::new();
2157        let scheme_filter = scheme.unwrap_or("");
2158
2159        // Check if we have a kever for this cid
2160        let kevers = self.kevers();
2161        if !kevers.contains_key(cid) {
2162            return Ok(msgs); // Return empty messages if no kever found
2163        }
2164
2165        // Replay events for this cid
2166        let replay_msgs = self.replay(Some(cid), None)?;
2167        msgs.extend(replay_msgs);
2168
2169        let kever = &kevers[cid];
2170        let kever_wits = kever.wits();
2171
2172        // Check if we are a witness for this cid
2173        let witness = if let Some(self_pre) = &self.pre {
2174            kever_wits.contains(self_pre)
2175        } else {
2176            false
2177        };
2178
2179        // Handle witness role specifically
2180        if let Some(Roles::Witness) = role {
2181            // Process all witnesses for this cid
2182            for eid in &kever_wits {
2183                // Check if we should include this eid
2184                let should_include = if let Some(eids_filter) = eids {
2185                    eids_filter.contains(eid)
2186                } else {
2187                    true
2188                };
2189
2190                if should_include {
2191                    // If this is our own endpoint, reply with location scheme
2192                    if let Some(self_pre) = &self.pre {
2193                        if eid == self_pre {
2194                            let loc_msgs = self.reply_loc_scheme(
2195                                eid.clone(),
2196                                if scheme_filter.is_empty() {
2197                                    None
2198                                } else {
2199                                    Some(scheme_filter.to_string())
2200                                },
2201                            )?;
2202                            msgs.extend(loc_msgs);
2203                        } else {
2204                            // Load location scheme for other witnesses
2205                            let loc_msgs = self.load_loc_scheme(eid, Some(scheme_filter))?;
2206                            msgs.extend(loc_msgs);
2207                        }
2208                    } else {
2209                        // Load location scheme for all witnesses if we don't have a pre
2210                        let loc_msgs = self.load_loc_scheme(eid, Some(scheme_filter))?;
2211                        msgs.extend(loc_msgs);
2212                    }
2213
2214                    // If we are not a witness, send auth records
2215                    if !witness {
2216                        let auth_msgs = self.make_end_role(
2217                            eid.clone(),
2218                            Some(Roles::Witness),
2219                            None, // allow (default: true)
2220                            None, // stamp
2221                        )?;
2222                        msgs.extend(auth_msgs);
2223                    }
2224                }
2225            }
2226        }
2227
2228        // Process all endpoint roles from the database
2229        let items = self.db.ends.get_item_iter(&[cid.as_bytes()]).map_err(|e| {
2230            KERIError::DatabaseError(format!("Failed to get endpoint items: {}", e))
2231        })?;
2232
2233        for (keys, end) in items {
2234            // Keys should be [cid, role, eid] - we need at least role and eid
2235            if keys.len() >= 2 {
2236                let erole_str = &keys[0]; // role is first key after cid
2237                let eid = &keys[1]; // eid is second key after cid
2238
2239                // Parse the role string
2240                let erole = match Roles::from_str(erole_str) {
2241                    Ok(r) => r,
2242                    Err(_) => continue, // Skip invalid roles
2243                };
2244
2245                // Check if this endpoint should be included
2246                let enabled_or_allowed =
2247                    end.enabled.unwrap_or(false) || end.allowed.unwrap_or(false);
2248                let role_matches = role.is_none() || role == Some(erole);
2249                let eid_matches = eids.is_none() || eids.unwrap().contains(eid);
2250
2251                if enabled_or_allowed && role_matches && eid_matches {
2252                    // Load location scheme for this endpoint
2253                    let loc_msgs = self.load_loc_scheme(eid, Some(scheme_filter))?;
2254                    msgs.extend(loc_msgs);
2255
2256                    // Load endpoint role information
2257                    let role_msgs = self.load_end_role(cid, eid, Some(erole))?;
2258                    msgs.extend(role_msgs);
2259                }
2260            }
2261        }
2262
2263        Ok(msgs)
2264    }
2265
2266    /// Reply to OOBI (Out-Of-Band Introduction) request
2267    /// This is a simple wrapper around reply_end_role
2268    ///
2269    /// # Parameters
2270    /// * `aid` - Agent identifier (controller ID)
2271    /// * `role` - Role to reply with
2272    /// * `eids` - Optional list of endpoint identifiers to filter by
2273    ///
2274    /// # Returns
2275    /// * `Ok(Vec<u8>)` - Combined reply messages
2276    /// * `Err(KERIError)` - On database error or validation failure
2277    pub fn reply_to_oobi(
2278        &self,
2279        aid: &str,
2280        role: Roles,
2281        eids: Option<&[String]>,
2282    ) -> Result<Vec<u8>, KERIError> {
2283        self.reply_end_role(aid, Some(role), eids, None)
2284    }
2285
2286    /// Get own event at specified sequence number
2287    ///
2288    /// # Parameters
2289    /// * `sn` - Sequence number of the event to retrieve
2290    /// * `allow_partially_signed` - If true, also check partially signed events database
2291    ///
2292    /// # Returns
2293    /// * `Ok((SerderKERI, Vec<Siger>, Option<T>))` - Event serder, signatures, and optional couple
2294    /// * `Err(KERIError)` - On missing event or database error
2295    pub fn get_own_event<T>(
2296        &self,
2297        sn: u64,
2298        allow_partially_signed: bool,
2299    ) -> Result<(SerderKERI, Vec<Siger>, Option<T>), KERIError>
2300    where
2301        T: TryFrom<Vec<u8>>,
2302        <T as TryFrom<Vec<u8>>>::Error: std::fmt::Debug,
2303    {
2304        // Get our prefix
2305        let pre = self
2306            .pre
2307            .as_ref()
2308            .ok_or_else(|| KERIError::ValidationError("Missing habitat prefix".to_string()))?;
2309
2310        // Create sequence number key
2311        let key = sn_key(pre, sn);
2312
2313        // Try to get digest from key event log
2314        let mut dig = self.db.get_ke_last(key.clone())?;
2315
2316        // If not found and partially signed events are allowed, try PSE database
2317        if dig.is_none() && allow_partially_signed {
2318            let pse_result = self
2319                .db
2320                .pses
2321                .get_last::<_, Vec<u8>>(&[&key])
2322                .map_err(|e| KERIError::DatabaseError(format!("Failed to get PSE: {}", e)))?;
2323
2324            if let Some(bytes) = pse_result {
2325                dig = Some(String::from_utf8(bytes).map_err(|e| {
2326                    KERIError::DeserializationError(format!(
2327                        "Failed to decode PSE digest as UTF-8: {}",
2328                        e
2329                    ))
2330                })?);
2331            }
2332        }
2333
2334        // If still no digest found, return error
2335        let digest = dig.ok_or_else(|| {
2336            KERIError::MissingEntryError(format!("Missing event for pre={} at sn={}", pre, sn))
2337        })?;
2338
2339        // Create digest key
2340        let dig_key = dg_key(pre, digest.as_bytes());
2341
2342        // Get the event message
2343        let msg = self.db.get_evt(dig_key.clone())?.ok_or_else(|| {
2344            KERIError::MissingEntryError(format!("Missing event message for digest key"))
2345        })?;
2346
2347        // Create serder from the raw message
2348        let serder = SerderKERI::from_raw(&msg, None)?;
2349
2350        // Get signatures for this event
2351        let sigs_iter = self
2352            .db
2353            .sigs
2354            .get_iter::<_, Vec<u8>>(&[&dig_key])
2355            .map_err(|e| KERIError::DatabaseError(format!("Failed to get signatures: {}", e)))?;
2356
2357        let mut sigs = Vec::new();
2358        for sig_result in sigs_iter {
2359            let mut sig_bytes = sig_result.map_err(|e| {
2360                KERIError::DatabaseError(format!("Failed to deserialize signature: {}", e))
2361            })?;
2362
2363            let siger = Siger::from_qb64b(&mut sig_bytes, None).map_err(|e| {
2364                KERIError::ValidationError(format!("Failed to create Siger: {}", e))
2365            })?;
2366
2367            sigs.push(siger);
2368        }
2369
2370        // Get the couple (attachment anchor seal)
2371        let couple = self
2372            .db
2373            .aess
2374            .get::<_, T>(&[&dig_key])
2375            .map_err(|e| KERIError::DatabaseError(format!("Failed to get couple: {}", e)))?;
2376
2377        Ok((serder, sigs, couple))
2378    }
2379
2380    /// Create own event message with attachments at specified sequence number
2381    ///
2382    /// # Parameters
2383    /// * `sn` - Sequence number of the event to retrieve
2384    /// * `allow_partially_signed` - If true, also check partially signed events database
2385    ///
2386    /// # Returns
2387    /// * `Ok(Vec<u8>)` - Complete event message with attachments
2388    /// * `Err(KERIError)` - On missing event or database error
2389    pub fn make_own_event(
2390        &self,
2391        sn: u64,
2392        allow_partially_signed: bool,
2393    ) -> Result<Vec<u8>, KERIError> {
2394        let mut msg = Vec::new();
2395
2396        // Get the event, signatures, and couple
2397        let (serder, sigs, couple): (SerderKERI, Vec<Siger>, Option<Vec<u8>>) =
2398            self.get_own_event(sn, allow_partially_signed)?;
2399
2400        // Add the raw event message
2401        msg.extend_from_slice(serder.raw());
2402
2403        // Add controller indexed signatures counter and signatures
2404        let sig_counter = BaseCounter::from_code_and_count(
2405            Some(ctr_dex_1_0::CONTROLLER_IDX_SIGS),
2406            Some(sigs.len() as u64),
2407            None,
2408        )
2409        .map_err(|e| {
2410            KERIError::ValidationError(format!("Failed to create signature counter: {}", e))
2411        })?;
2412
2413        msg.extend(sig_counter.qb64b());
2414
2415        // Add each signature
2416        for sig in &sigs {
2417            msg.extend(sig.qb64b());
2418        }
2419
2420        // Add couple if present
2421        if let Some(couple_data) = couple {
2422            let couple_counter = BaseCounter::from_code_and_count(
2423                Some(ctr_dex_1_0::SEAL_SOURCE_COUPLES),
2424                Some(1),
2425                None,
2426            )
2427            .map_err(|e| {
2428                KERIError::ValidationError(format!("Failed to create couple counter: {}", e))
2429            })?;
2430
2431            msg.extend(couple_counter.qb64b());
2432            msg.extend(couple_data);
2433        }
2434
2435        Ok(msg)
2436    }
2437
2438    /// Messages that give every witness of own event `sn` the receipts of
2439    /// the other witnesses (the second half of keripy `Receiptor.receipt`).
2440    ///
2441    /// For each witness, the message is a `rct` for the event with the other
2442    /// witnesses' signatures stored so far as receipt couples. For an
2443    /// inception, and for a rotation toward a witness it adds, the other
2444    /// witnesses' `/loc/scheme` replies come first so the witnesses learn
2445    /// each other's endpoints. A witness with nothing to receive is skipped.
2446    ///
2447    /// Returns `(witness prefix, CESR stream)` pairs.
2448    pub fn witness_receipt_msgs(&self, sn: u64) -> Result<Vec<(String, Vec<u8>)>, KERIError> {
2449        let (serder, _sigs, _couple): (SerderKERI, Vec<Siger>, Option<Vec<u8>>) =
2450            self.get_own_event(sn, false)?;
2451        let pre = serder.pre().unwrap_or_default();
2452        let said = serder.said().unwrap_or_default().to_string();
2453        let wits = self.kever()?.wits();
2454
2455        // Stored witness signatures, as (witness prefix, couple signature).
2456        let wigs: Vec<Vec<u8>> = self.db.wigs.get(&[pre.as_str(), said.as_str()])?;
2457        let mut couples: Vec<(String, Cigar)> = Vec::new();
2458        for mut wig in wigs {
2459            use crate::cesr::indexing::Indexer;
2460            let wiger = Siger::from_qb64b(&mut wig, None)?;
2461            let Some(wit) = wits.get(wiger.index() as usize) else {
2462                continue;
2463            };
2464            let cigar = crate::keri::core::eventing::kevery::wiger_to_cigar(&wiger, Verfer::from_qb64(wit)?)?;
2465            couples.push((wit.clone(), cigar));
2466        }
2467
2468        let introduce_all = matches!(serder.ilk(), Some(crate::keri::Ilk::Icp) | Some(crate::keri::Ilk::Dip));
2469        let adds = serder.adds().unwrap_or_default();
2470        let rct = ReceiptEventBuilder::new(pre.clone(), sn as usize, said.clone())
2471            .build()
2472            .map_err(|e| ValidationError(format!("Failed to build receipt: {}", e)))?;
2473
2474        let mut out = Vec::new();
2475        for wit in &wits {
2476            let others: Vec<&(String, Cigar)> = couples.iter().filter(|(w, _)| w != wit).collect();
2477            if others.is_empty() {
2478                continue;
2479            }
2480            let mut msg = Vec::new();
2481            if introduce_all || adds.contains(wit) {
2482                for (eid, _) in &others {
2483                    msg.extend(self.load_loc_scheme(eid, None)?);
2484                }
2485            }
2486            let cigars: Vec<Cigar> = others.iter().map(|(_, c)| c.clone()).collect();
2487            msg.extend(
2488                messagize(&rct, None, None, None, Some(&cigars), false)
2489                    .map_err(|e| ValidationError(format!("Failed to messagize receipt: {}", e)))?,
2490            );
2491            out.push((wit.clone(), msg));
2492        }
2493        Ok(out)
2494    }
2495
2496    /// Create own inception event message with attachments
2497    /// This is a convenience method that calls make_own_event with sn=0
2498    ///
2499    /// # Parameters
2500    /// * `allow_partially_signed` - If true, also check partially signed events database
2501    ///
2502    /// # Returns
2503    /// * `Ok(Vec<u8>)` - Complete inception event message with attachments
2504    /// * `Err(KERIError)` - On missing event or database error
2505    pub fn make_own_inception(&self, allow_partially_signed: bool) -> Result<Vec<u8>, KERIError> {
2506        self.make_own_event(0, allow_partially_signed)
2507    }
2508
2509    /// Process all cues and return combined messages
2510    ///
2511    /// # Parameters
2512    /// * `cues` - Deque of cue objects to process
2513    ///
2514    /// # Returns
2515    /// * `Ok(Vec<u8>)` - Combined outgoing messages from all cues
2516    /// * `Err(KERIError)` - On processing error
2517    pub fn process_cues(
2518        &mut self,
2519        cues: &mut VecDeque<IndexMap<String, SadValue>>,
2520    ) -> Result<Vec<u8>, KERIError> {
2521        let mut msgs = Vec::new();
2522
2523        for msg_result in self.process_cues_iter(cues)? {
2524            let msg = msg_result?;
2525            msgs.extend(msg);
2526        }
2527
2528        Ok(msgs)
2529    }
2530
2531    /// Process cues iteratively, yielding messages for each cue
2532    ///
2533    /// # Parameters
2534    /// * `cues` - Deque of cue objects to process
2535    ///
2536    /// # Returns
2537    /// * `Ok(Vec<Result<Vec<u8>, KERIError>>)` - Iterator of message results
2538    /// * `Err(KERIError)` - On processing error
2539    pub fn process_cues_iter(
2540        &mut self,
2541        cues: &mut VecDeque<IndexMap<String, SadValue>>,
2542    ) -> Result<Vec<Result<Vec<u8>, KERIError>>, KERIError> {
2543        let mut results = Vec::new();
2544
2545        while let Some(cue) = cues.pop_front() {
2546            let mut msgs = Vec::new();
2547
2548            // Get the cue kind
2549            let cue_kin = cue.get("kin").and_then(|v| v.as_str()).ok_or_else(|| {
2550                KERIError::ValidationError("Missing or invalid cue kind".to_string())
2551            })?;
2552
2553            match cue_kin {
2554                "receipt" => {
2555                    // Handle receipt cue
2556                    let cued_serder_data = cue.get("serder").ok_or_else(|| {
2557                        KERIError::ValidationError("Missing serder in receipt cue".to_string())
2558                    })?;
2559
2560                    // Convert SadValue to SerderKERI (assuming there's a conversion method)
2561                    let cued_serder = self.sad_value_to_serder(cued_serder_data)?;
2562                    let cued_ked = cued_serder.ked();
2563
2564                    // Get the identifier from the event
2565                    let cued_pre = cued_ked.get("i").and_then(|v| v.as_str()).ok_or_else(|| {
2566                        KERIError::ValidationError("Missing identifier in cued event".to_string())
2567                    })?;
2568
2569                    // Create prefixer to check transferability
2570                    let cued_prefixer = Prefixer::from_qb64(cued_pre).map_err(|e| {
2571                        KERIError::ValidationError(format!("Failed to create prefixer: {}", e))
2572                    })?;
2573
2574                    info!(
2575                        "{} got cue: kin={} {}",
2576                        self.pre.as_deref().unwrap_or("None"),
2577                        cue_kin,
2578                        cued_serder.said().unwrap_or("None")
2579                    );
2580                    debug!("event=\n{}\n", cued_serder.pretty(None));
2581
2582                    // Check if this is an inception event
2583                    if let Some(ilk) = cued_ked.get("t").and_then(|v| v.as_str()) {
2584                        if ilk == "icp" {
2585                            // Create digest key for our own inception
2586                            let pre = self.pre.as_ref().ok_or_else(|| {
2587                                KERIError::ValidationError("Missing habitat prefix".to_string())
2588                            })?;
2589
2590                            let iserder = self.iserder()?;
2591                            let iserder_said = iserder.said().ok_or_else(|| {
2592                                KERIError::ValidationError("Missing inception SAID".to_string())
2593                            })?;
2594
2595                            let dgkey = dg_key(pre, iserder_said);
2596                            let mut found = false;
2597
2598                            if cued_prefixer.transferable() {
2599                                // Check for transferable receipts (VRCs)
2600                                let vrcs_iter =
2601                                    self.db.vrcs.get_iter::<_, Vec<u8>>(&[&dgkey]).map_err(
2602                                        |e| {
2603                                            KERIError::DatabaseError(format!(
2604                                                "Failed to get VRCs: {}",
2605                                                e
2606                                            ))
2607                                        },
2608                                    )?;
2609
2610                                for quadruple_result in vrcs_iter {
2611                                    let quadruple = quadruple_result.map_err(|e| {
2612                                        KERIError::DatabaseError(format!(
2613                                            "Failed to deserialize VRC: {}",
2614                                            e
2615                                        ))
2616                                    })?;
2617
2618                                    if let Ok(quadruple_str) = String::from_utf8(quadruple) {
2619                                        if quadruple_str.starts_with(cued_pre) {
2620                                            found = true;
2621                                            break;
2622                                        }
2623                                    }
2624                                }
2625                            } else {
2626                                // Check for non-transferable receipts (RCTs)
2627                                let rcts_iter =
2628                                    self.db.rcts.get_iter::<_, Vec<u8>>(&[&dgkey]).map_err(
2629                                        |e| {
2630                                            KERIError::DatabaseError(format!(
2631                                                "Failed to get RCTs: {}",
2632                                                e
2633                                            ))
2634                                        },
2635                                    )?;
2636
2637                                for couple_result in rcts_iter {
2638                                    let couple = couple_result.map_err(|e| {
2639                                        KERIError::DatabaseError(format!(
2640                                            "Failed to deserialize RCT: {}",
2641                                            e
2642                                        ))
2643                                    })?;
2644
2645                                    if let Ok(couple_str) = String::from_utf8(couple) {
2646                                        if couple_str.starts_with(cued_pre) {
2647                                            found = true;
2648                                            break;
2649                                        }
2650                                    }
2651                                }
2652                            }
2653
2654                            if !found {
2655                                // No receipt from remote, so send our own inception
2656                                let inception_msg = self.make_own_inception(false)?;
2657                                msgs.extend(inception_msg);
2658                            }
2659                        }
2660                    }
2661
2662                    // Create receipt for the cued event
2663                    let receipt_msg = self.receipt(&cued_serder)?;
2664                    msgs.extend(receipt_msg);
2665
2666                    results.push(Ok(msgs));
2667                }
2668
2669                "replay" => {
2670                    // Handle replay cue
2671                    let replay_msgs = cue.get("msgs").ok_or_else(|| {
2672                        KERIError::ValidationError("Missing msgs in replay cue".to_string())
2673                    })?;
2674
2675                    // Convert SadValue to Vec<u8> (assuming there's a conversion method)
2676                    let msgs = self.sad_value_to_bytes(replay_msgs)?;
2677                    results.push(Ok(msgs));
2678                }
2679
2680                "reply" => {
2681                    // Handle reply cue
2682                    let data = cue
2683                        .get("data")
2684                        .and_then(|v| self.sad_value_to_indexmap(v).ok());
2685
2686                    let route = cue.get("route").and_then(|v| v.as_str()).ok_or_else(|| {
2687                        KERIError::ValidationError("Missing route in reply cue".to_string())
2688                    })?;
2689
2690                    let reply_msg = self.reply(
2691                        route.to_string(),
2692                        data,
2693                        None, // stamp
2694                        None, // version
2695                        None, // kind
2696                        None, // last
2697                        None, // pipelined
2698                    )?;
2699
2700                    results.push(Ok(reply_msg));
2701                }
2702
2703                _ => {
2704                    // Handle unknown cue kinds - for now just log and continue
2705                    warn!("Unhandled cue kind: {}", cue_kin);
2706                    // TODO: Implement handlers for other cue kinds:
2707                    // - "query" for various types of queries
2708                    // - "notice" for new event notifications
2709                    // - "witness" to create witness receipts
2710                    // - "noticeBadCloneFN" for bad clone notifications
2711                    // - "approveDelegation" for delegation approval
2712                    // - "keyStateSaved" for key state persistence
2713                    // - "psUnescrow" for partial signature unescrow
2714                    // - "stream" for streaming operations
2715                    // - "invalid" for invalid events
2716                    // - "remoteMemberedSig" for remote member signatures
2717
2718                    results.push(Ok(Vec::new())); // Return empty message for unhandled cues
2719                }
2720            }
2721        }
2722
2723        Ok(results)
2724    }
2725
2726    /// Returns whether this habitat can act as a witness
2727    ///
2728    /// # Returns
2729    /// * `bool` - Always true for base implementation
2730    pub fn witnesser(&self) -> bool {
2731        true
2732    }
2733
2734    // Helper methods for SadValue conversions
2735
2736    /// Convert SadValue to SerderKERI
2737    fn sad_value_to_serder(&self, sad_value: &SadValue) -> Result<SerderKERI, KERIError> {
2738        match sad_value {
2739            SadValue::Object(map) => SerderKERI::from_sad(&Sadder::from(map.clone())),
2740            _ => Err(KERIError::ValidationError(
2741                "Expected object for serder".to_string(),
2742            )),
2743        }
2744    }
2745
2746    /// Convert SadValue to Vec<u8>
2747    fn sad_value_to_bytes(&self, sad_value: &SadValue) -> Result<Vec<u8>, KERIError> {
2748        match sad_value {
2749            SadValue::String(s) => Ok(s.as_bytes().to_vec()),
2750            SadValue::Array(arr) => {
2751                // Convert array of numbers to bytes
2752                let mut bytes = Vec::new();
2753                for val in arr {
2754                    if let Some(num) = val.as_u64() {
2755                        if num <= 255 {
2756                            bytes.push(num as u8);
2757                        } else {
2758                            return Err(KERIError::ValidationError(
2759                                "Byte value out of range".to_string(),
2760                            ));
2761                        }
2762                    } else {
2763                        return Err(KERIError::ValidationError(
2764                            "Expected numeric values for bytes".to_string(),
2765                        ));
2766                    }
2767                }
2768                Ok(bytes)
2769            }
2770            _ => Err(KERIError::ValidationError(
2771                "Cannot convert SadValue to bytes".to_string(),
2772            )),
2773        }
2774    }
2775
2776    /// Convert SadValue to IndexMap
2777    fn sad_value_to_indexmap(
2778        &self,
2779        sad_value: &SadValue,
2780    ) -> Result<IndexMap<String, SadValue>, KERIError> {
2781        match sad_value {
2782            SadValue::Object(map) => Ok(map.clone()),
2783            _ => Err(KERIError::ValidationError(
2784                "Expected object for IndexMap".to_string(),
2785            )),
2786        }
2787    }
2788}
2789
2790/// Hab class provides a given identifier controller's local resource environment
2791/// i.e. hab or habitat. Includes dependency injection of database, keystore,
2792/// configuration file as well as Kevery and key store Manager.
2793///
2794/// # Attributes (Injected)
2795/// * `ks` - LMDB key store
2796/// * `db` - LMDB data base for KEL etc
2797/// * `cf` - Config file instance  
2798/// * `mgr` - Creates and rotates keys in key store
2799/// * `rtr` - Routes reply 'rpy' messages
2800/// * `rvy` - Factory that processes reply 'rpy' messages
2801/// * `kvy` - Factory for local processing of local event msgs
2802/// * `psr` - Parses local messages for .kvy .rvy
2803///
2804/// # Attributes
2805/// * `name` - Alias of controller
2806/// * `pre` - qb64 prefix of own local controller or None if new
2807/// * `temp` - True means testing: use weak level when salty algo for stretching
2808///   in key creation for incept and rotate of keys for this hab.pre
2809/// * `inited` - True means fully initialized wrt databases. False means not yet fully initialized
2810/// * `delpre` - Delegator prefix if any else None
2811///
2812/// # Properties
2813/// * `kever` - Instance of key state of local controller
2814/// * `kevers` - Of eventing.Kever instances from KELs in local db keyed by qb64 prefix.
2815///   Read through cache of kevers of states for KELs in db.states
2816/// * `iserder` - Own inception event
2817/// * `prefixes` - Local prefixes for .db
2818/// * `accepted` - True means accepted into local KEL. False otherwise
2819
2820pub struct Hab<'a> {
2821    /// Base habitat functionality
2822    pub base: BaseHab<'a>,
2823    /// Configuration file instance
2824    pub cf: Option<Arc<Configer>>,
2825}
2826
2827// Implement Deref to delegate read-only access to BaseHab
2828impl<'a> Deref for Hab<'a> {
2829    type Target = BaseHab<'a>;
2830
2831    fn deref(&self) -> &Self::Target {
2832        &self.base
2833    }
2834}
2835
2836// Implement DerefMut to delegate mutable access to BaseHab
2837impl<'a> DerefMut for Hab<'a> {
2838    fn deref_mut(&mut self) -> &mut Self::Target {
2839        &mut self.base
2840    }
2841}
2842
2843impl<'a> Hab<'a> {
2844    /// Create a new Hab instance
2845    ///
2846    /// # Parameters
2847    /// * `db` - Baser database instance
2848    /// * `mgr` - Manager for key operations
2849    /// * `rtr` - Optional router for reply messages
2850    /// * `rvy` - Revery for processing reply messages
2851    /// * `kvy` - Kevery for processing event messages
2852    /// * `psr` - Handler-less parser used to ingest locally produced messages
2853    /// * `cf` - Optional configuration file
2854    /// * `name` - Alias name for the controller
2855    /// * `ns` - Optional namespace
2856    /// * `pre` - Optional existing prefix
2857    /// * `temp` - Testing mode flag
2858    /// * `delpre` - Optional delegator prefix
2859    ///
2860    /// # Returns
2861    /// * `Result<Self, KERIError>` - New Hab instance or error
2862    pub fn new(
2863        db: Arc<Baser>,
2864        mgr: &'a mut Manager,
2865        rtr: Option<Arc<Router>>,
2866        rvy: &'a mut Revery,
2867        kvy: &'a mut Kevery,
2868        psr: &'a mut Parser<std::io::Empty>,
2869        cf: Option<Arc<Configer>>,
2870        name: String,
2871        ns: Option<String>,
2872        pre: Option<String>,
2873        temp: bool,
2874        delpre: Option<String>,
2875    ) -> Result<Self, KERIError> {
2876        let base = BaseHab::new(db, mgr, rtr, rvy, kvy, psr, name, ns, pre, temp)?;
2877
2878        let mut hab = Hab { base, cf };
2879
2880        // Set delegator prefix if provided
2881        hab.base.delpre = delpre;
2882
2883        Ok(hab)
2884    }
2885
2886    /// Create a new habitat with the given parameters.
2887    /// This method handles both replay (from secrecies) and normal inception flows.
2888    pub fn make(
2889        &mut self,
2890        secrecies: Option<Vec<Vec<String>>>,
2891        iridx: Option<usize>,
2892        code: Option<&str>,
2893        dcode: Option<&str>,
2894        icode: Option<&str>,
2895        transferable: Option<bool>,
2896        isith: Option<Tholder>,
2897        icount: Option<usize>,
2898        nsith: Option<Tholder>,
2899        ncount: Option<usize>,
2900        toad: Option<u32>,
2901        wits: Option<Vec<String>>,
2902        delpre: Option<String>,
2903        est_only: Option<bool>,
2904        d_n_d: Option<bool>,
2905        hidden: Option<bool>,
2906        data: Option<Vec<SadValue>>,
2907        algo: Option<Algos>,
2908        salt: Option<Vec<u8>>,
2909        tier: Option<Tiers>,
2910    ) -> Result<SerderKERI, KERIError> {
2911        // Check if resources are opened
2912        if !(self.mgr.ks.opened() && self.db.opened() && self.cf.as_ref().map_or(true, |cf| cf.opened))
2913        {
2914            return Err(KERIError::ClosedError(
2915                "Attempt to make Hab with unopened resources.".to_string(),
2916            ));
2917        }
2918
2919        let transferable = transferable.unwrap_or(true);
2920        let icount = icount.unwrap_or(1);
2921        let mut ncount = ncount.unwrap_or(icount);
2922        // As keripy: None lets BaseHab::make compute the default from the key
2923        // count; only non-transferable forces "0".
2924        let mut nsith = nsith;
2925        let mut code = code.unwrap_or(mtr_dex::BLAKE3_256);
2926        let hidden = hidden.unwrap_or(false);
2927        let iridx = iridx.unwrap_or(0);
2928
2929        // Handle non-transferable case
2930        if !transferable {
2931            ncount = 0;
2932            nsith = Some(Tholder::new(None, None, Some(TholderSith::HexString("0".to_string())))?);
2933            code = mtr_dex::ED25519N;
2934        }
2935
2936        // Create stem from name and namespace
2937        let stem = if let Some(ref ns) = self.ns {
2938            format!("{}{}", ns, self.name)
2939        } else {
2940            self.name.clone()
2941        };
2942        let temp_clone = self.temp.clone();
2943        let (verfers, digers) = if let Some(secrecies) = secrecies {
2944            // Replay flow
2945            let (ipre, _) = self.mgr.ingest(
2946                secrecies,
2947                Some(iridx),
2948                Some(ncount),
2949                None, // ncode
2950                None, // dcode
2951                algo,
2952                salt,
2953                Some(stem),
2954                tier,
2955                None, // rooted
2956                Some(transferable),
2957                Some(temp_clone),
2958            )?;
2959
2960            self.mgr.replay(
2961                ipre.as_bytes(),
2962                dcode,
2963                Some(false), // advance = false
2964                None,        // erase
2965            )?
2966        } else {
2967            // Normal inception flow
2968
2969            self.mgr.incept(
2970                None, // icodes
2971                Some(icount),
2972                icode,
2973                None, // ncodes
2974                Some(ncount),
2975                None, // ncode
2976                dcode.map(|s| s.to_string()),
2977                algo,
2978                salt,
2979                Some(&stem),
2980                tier,
2981                None, // rooted
2982                Some(transferable),
2983                Some(temp_clone),
2984            )?
2985        };
2986
2987        // Call parent make method (BaseHab::make)
2988        let serder = self.base.make(
2989            d_n_d,
2990            Some(code),
2991            data,
2992            delpre.clone(),
2993            est_only,
2994            isith,
2995            verfers.clone(),
2996            nsith,
2997            Some(digers),
2998            toad,
2999            wits,
3000        )?;
3001
3002        // Set the new prefix from the serder - extract "i" field from ked
3003        let ked = serder.ked();
3004        if let Some(SadValue::String(pre)) = ked.get("i") {
3005            self.pre = Some(pre.clone());
3006        } else {
3007            return Err(KERIError::ValueError(
3008                "Invalid inception event: missing or invalid 'i' field".to_string(),
3009            ));
3010        }
3011
3012        // Move from old prefix to new prefix
3013        if let Some(ref pre) = self.pre.clone() {
3014            let opre = verfers[0].qb64(); // default zeroth original pre from key store
3015            self.mgr.move_prefix(opre.as_bytes(), pre.as_bytes())?; // move to incept event pre
3016
3017            // Create habitat record
3018            let habord = HabitatRecord {
3019                hid: pre.clone(),
3020                name: Some(self.name.clone()),
3021                domain: self.ns.clone(),
3022                ..Default::default()
3023            };
3024
3025            // Must add self.pre to self.prefixes before calling processEvent so that
3026            // Kever.locallyOwned or Kever.locallyDelegated or Kever.locallyWitnessed
3027            // evaluates correctly when processing own inception event.
3028            if !hidden {
3029                self.save(habord)?;
3030                self.kvy.locals.prefixes.insert(pre.clone());
3031            }
3032
3033            // Sign handles group hab with .mhab case
3034            let sigers = self.sign(
3035                serder.raw(),
3036                Some(verfers),
3037                None, // indexed (defaults to true)
3038                None, // indices
3039                None, // ondices
3040                None, // ponly
3041            )?;
3042
3043            // During delegation initialization of a habitat we ignore the MissingDelegationError and
3044            // MissingSignatureError
3045            match self.kvy.process_event(
3046                serder.clone(),
3047                sigers,
3048                None, // wigers
3049                None, // delseqner
3050                None, // delsaider
3051                None, // firner
3052                None, // dater
3053                None, // eager
3054                None, // local (uses kvy.local default)
3055            ) {
3056                Ok(_) => {}
3057                Err(KERIError::MissingSignatureError(_)) => {
3058                    // This is acceptable during delegation initialization - just pass
3059                }
3060                Err(ex) => {
3061                    return Err(KERIError::ConfigurationError(format!(
3062                        "Improper Habitat inception for pre={}: {}",
3063                        pre, ex
3064                    )));
3065                }
3066            }
3067
3068            // Read in self.cf config file and process any oobis or endpoints
3069            self.reconfigure(); // should we do this for new Habs not loaded from db
3070
3071            self.inited = true;
3072            Ok(serder)
3073        } else {
3074            Err(KERIError::ValueError(
3075                "Failed to set prefix after inception".to_string(),
3076            ))
3077        }
3078    }
3079
3080    /// Save habitat record to database and register name
3081    ///
3082    /// # Parameters
3083    /// * `habord` - HabitatRecord to save
3084    ///
3085    /// # Returns
3086    /// * `Result<(), KERIError>` - Ok if successful, error otherwise
3087    ///
3088    /// # Errors
3089    /// * Returns error if AID already exists with the given name
3090    pub fn save(&mut self, habord: HabitatRecord) -> Result<(), KERIError> {
3091        // Get the current prefix - should be set by this point
3092        let pre = self.pre.as_ref().ok_or_else(|| {
3093            KERIError::ValueError("Cannot save habitat: prefix not set".to_string())
3094        })?;
3095
3096        // Save the habitat record keyed by prefix
3097        self.db.habs.pin(&[pre.as_bytes()], &habord).map_err(|e| {
3098            KERIError::DatabaseError(format!("Failed to save habitat record: {}", e))
3099        })?;
3100
3101        // Prepare namespace - empty string if None
3102        let ns = self.ns.as_deref().unwrap_or("");
3103
3104        // Check if name already exists in this namespace
3105        let existing: Option<Vec<u8>> = self
3106            .db
3107            .names
3108            .get(&[ns.as_bytes(), self.name.as_bytes()])
3109            .map_err(|e| {
3110            KERIError::DatabaseError(format!("Failed to check existing name: {}", e))
3111        })?;
3112
3113        let existing_string = existing.map(|bytes| String::from_utf8_lossy(&bytes).to_string());
3114
3115        if existing_string.is_some() {
3116            return Err(KERIError::ValueError(
3117                "AID already exists with that name".to_string(),
3118            ));
3119        }
3120
3121        // Save the name mapping (namespace, name) -> prefix
3122        self.db
3123            .names
3124            .pin(&[ns.as_bytes(), self.name.as_bytes()], &pre.as_bytes())
3125            .map_err(|e| KERIError::DatabaseError(format!("Failed to save name mapping: {}", e)))?;
3126
3127        Ok(())
3128    }
3129    /// Get the algorithm used for this habitat
3130    ///
3131    /// # Returns
3132    /// * `Result<String, KERIError>` - The algorithm name or error
3133    pub fn algo(&self) -> Result<String, KERIError> {
3134        let pre = self
3135            .pre
3136            .as_ref()
3137            .ok_or_else(|| KERIError::ValueError("Cannot get algo: prefix not set".to_string()))?;
3138
3139        let pp = self.mgr.ks.prms.get(&[pre.as_bytes()])?.ok_or_else(|| {
3140            KERIError::ValueError(format!("No parameters found for prefix: {}", pre))
3141        })?;
3142
3143        Ok(pp.algo)
3144    }
3145
3146    /// Perform rotation operation. Register rotation in database.
3147    /// Returns rotation message with attached signatures.
3148    ///
3149    /// # Parameters
3150    /// * `isith` - Current signing threshold
3151    /// * `nsith` - Next signing threshold
3152    /// * `ncount` - Next number of signing keys
3153    /// * `toad` - Witness threshold after cuts and adds
3154    /// * `cuts` - List of witness prefixes to be removed from witness list
3155    /// * `adds` - List of witness prefixes to be added to witness list
3156    /// * `data` - List of committed data such as seals
3157    ///
3158    /// # Returns
3159    /// * `Result<Vec<u8>, KERIError>` - Rotation message with signatures or error
3160    pub fn rotate(
3161        &mut self,
3162        isith: Option<Tholder>,
3163        nsith: Option<Tholder>,
3164        ncount: Option<u32>,
3165        toad: Option<u32>,
3166        cuts: Option<Vec<String>>,
3167        adds: Option<Vec<String>>,
3168        data: Option<Vec<SadValue>>,
3169    ) -> Result<Vec<u8>, KERIError> {
3170        let pre = self
3171            .pre
3172            .clone()
3173            .ok_or_else(|| KERIError::ValueError("Cannot rotate: prefix not set".to_string()))?;
3174
3175        // Set defaults for counts - use len of prior next digers as default
3176        let ncount = ncount.unwrap_or({
3177            let kever = self.kever()?;
3178            match kever.ndigers.as_ref() {
3179                Some(digers) => digers.len() as u32,
3180                None => 0,
3181            }
3182        });
3183
3184        // Try to replay first, fallback to rotate if IndexError
3185        let (verfers, digers) = match self.mgr.replay(
3186            pre.as_bytes(),
3187            None,       // dcode
3188            Some(true), // advance
3189            Some(true), // erase
3190        ) {
3191            Ok((verfers, digers)) => (verfers, digers),
3192            Err(KERIError::IndexError(_)) => {
3193                // Old next is new current - need to rotate
3194                self.mgr.rotate(
3195                    pre.as_bytes(),
3196                    None,                  // ncodes
3197                    Some(ncount as usize), // ncount
3198                    None,                  // ncode - will use default ED25519
3199                    None,                  // dcode - will use default BLAKE3_256
3200                    Some(true),            // transferable
3201                    Some(self.temp),       // temp
3202                    Some(true),            // erase
3203                )?
3204            }
3205            Err(e) => return Err(e),
3206        };
3207
3208        // Pass pre-generated keys to BaseHab::rotate so it doesn't regenerate them
3209        self.base.rotate(
3210            Some(verfers),
3211            Some(digers),
3212            Some(ncount),
3213            isith,
3214            nsith,
3215            toad,
3216            cuts,
3217            adds,
3218            data,
3219        )
3220    }
3221}