Skip to main content

libkeri/keri/app/keeping/
keeper.rs

1use crate::cesr::prefixer::Prefixer;
2use crate::cesr::signing::Cipher;
3use crate::keri::app::keeping::creators::Algos;
4use crate::keri::core::filing::{BaseFiler, Filer, FilerDefaults};
5use crate::keri::db::dbing::LMDBer;
6use crate::keri::db::errors::DBError;
7use crate::keri::db::koming::{Komer, SerialKind};
8use crate::keri::db::subing::cesr::CesrSuber;
9use crate::keri::db::subing::signer::CryptSignerSuber;
10use crate::keri::db::subing::Suber;
11use serde::{Deserialize, Serialize};
12use std::iter::IntoIterator;
13use std::path::PathBuf;
14use std::sync::Arc;
15
16/// Public key list with indexes and datetime created
17#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
18pub struct PubLot {
19    /// List of fully qualified Base64 public keys
20    #[serde(default)]
21    pub pubs: Vec<String>,
22
23    /// Rotation index of set of public keys at establishment event
24    /// Index of key set at inception event is 0
25    #[serde(default)]
26    pub ridx: usize,
27
28    /// Key index of starting key in key set in sequence wrt to all public keys
29    /// Example if each set has 3 keys then ridx 2 has kidx of 2*3 = 6
30    #[serde(default)]
31    pub kidx: usize,
32
33    /// Datetime in ISO8601 format of when key set was first created
34    #[serde(default)]
35    pub dt: String,
36}
37
38impl Default for PubLot {
39    fn default() -> Self {
40        Self {
41            pubs: Vec::new(),
42            ridx: 0,
43            kidx: 0,
44            dt: String::new(),
45        }
46    }
47}
48
49impl IntoIterator for PubLot {
50    type Item = (String, serde_json::Value);
51    type IntoIter = std::vec::IntoIter<Self::Item>;
52
53    fn into_iter(self) -> Self::IntoIter {
54        let mut result = Vec::new();
55
56        // Convert the struct to key-value pairs similar to Python's asdict
57        result.push((
58            "pubs".to_string(),
59            serde_json::to_value(&self.pubs).unwrap(),
60        ));
61        result.push((
62            "ridx".to_string(),
63            serde_json::to_value(&self.ridx).unwrap(),
64        ));
65        result.push((
66            "kidx".to_string(),
67            serde_json::to_value(&self.kidx).unwrap(),
68        ));
69        result.push(("dt".to_string(), serde_json::to_value(&self.dt).unwrap()));
70
71        result.into_iter()
72    }
73}
74
75/// Prefix's public key situation (sets of public keys)
76#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
77pub struct PreSit {
78    /// Previous public key lot
79    #[serde(default)]
80    pub old: Option<PubLot>,
81
82    /// Newly current public key lot
83    #[serde(default)]
84    pub new: PubLot,
85
86    /// Next public key lot
87    #[serde(default)]
88    pub nxt: PubLot,
89}
90
91impl Default for PreSit {
92    fn default() -> Self {
93        Self {
94            old: Some(PubLot::default()),
95            new: PubLot::default(),
96            nxt: PubLot::default(),
97        }
98    }
99}
100
101impl IntoIterator for PreSit {
102    type Item = (String, serde_json::Value);
103    type IntoIter = std::vec::IntoIter<Self::Item>;
104
105    fn into_iter(self) -> Self::IntoIter {
106        let mut result = Vec::new();
107
108        // Convert the struct to key-value pairs similar to Python's asdict
109        result.push(("old".to_string(), serde_json::to_value(&self.old).unwrap()));
110        result.push(("new".to_string(), serde_json::to_value(&self.new).unwrap()));
111        result.push(("nxt".to_string(), serde_json::to_value(&self.nxt).unwrap()));
112
113        result.into_iter()
114    }
115}
116
117/// Prefix's parameters for creating new key pairs
118#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
119pub struct PrePrm {
120    /// Prefix index for this keypair sequence
121    #[serde(default)]
122    pub pidx: usize,
123
124    /// Algorithm used to create new key pairs (default is salty)
125    #[serde(default = "default_algo")]
126    pub algo: String,
127
128    /// Salt used for salty algorithm
129    #[serde(default)]
130    pub salt: String,
131
132    /// Default unique path stem for salty algorithm
133    #[serde(default)]
134    pub stem: String,
135
136    /// Security tier for stretch index salty algorithm
137    #[serde(default)]
138    pub tier: String,
139}
140
141fn default_algo() -> String {
142    Algos::Salty.to_string()
143}
144
145impl Default for PrePrm {
146    fn default() -> Self {
147        Self {
148            pidx: 0,
149            algo: Algos::Salty.to_string(),
150            salt: String::new(),
151            stem: String::new(),
152            tier: String::new(),
153        }
154    }
155}
156
157impl IntoIterator for PrePrm {
158    type Item = (String, serde_json::Value);
159    type IntoIter = std::vec::IntoIter<Self::Item>;
160
161    fn into_iter(self) -> Self::IntoIter {
162        let mut result = Vec::new();
163
164        // Convert the struct to key-value pairs similar to Python's asdict
165        result.push((
166            "pidx".to_string(),
167            serde_json::to_value(&self.pidx).unwrap(),
168        ));
169        result.push((
170            "algo".to_string(),
171            serde_json::to_value(&self.algo).unwrap(),
172        ));
173        result.push((
174            "salt".to_string(),
175            serde_json::to_value(&self.salt).unwrap(),
176        ));
177        result.push((
178            "stem".to_string(),
179            serde_json::to_value(&self.stem).unwrap(),
180        ));
181        result.push((
182            "tier".to_string(),
183            serde_json::to_value(&self.tier).unwrap(),
184        ));
185
186        result.into_iter()
187    }
188}
189
190/// Prefix's public key set (list) at rotation index ridx
191#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
192pub struct PubSet {
193    /// List of fully qualified Base64 public keys
194    #[serde(default)]
195    pub pubs: Vec<String>,
196}
197
198impl Default for PubSet {
199    fn default() -> Self {
200        Self { pubs: Vec::new() }
201    }
202}
203
204impl IntoIterator for PubSet {
205    type Item = (String, serde_json::Value);
206    type IntoIter = std::vec::IntoIter<Self::Item>;
207
208    fn into_iter(self) -> Self::IntoIter {
209        let mut result = Vec::new();
210
211        // Convert the struct to key-value pairs similar to Python's asdict
212        result.push((
213            "pubs".to_string(),
214            serde_json::to_value(&self.pubs).unwrap(),
215        ));
216
217        result.into_iter()
218    }
219}
220
221/// Keeper struct for key pair storage (KS)
222/// Sets up named sub databases for key pair storage.
223/// Methods provide key pair creation, storage, and data signing.
224pub struct Keeper {
225    /// Base database
226    lmdber: Arc<LMDBer>, // The base LMDB database
227
228    /// Global parameters for all prefixes
229    /// Key is parameter label, Value is parameter
230    pub gbls: Suber,
231
232    /// Private keys database
233    /// Key is public key (fully qualified qb64)
234    /// Value is private key (fully qualified qb64)
235    pub pris: CryptSignerSuber,
236
237    /// Encrypted private keys database
238    /// Key is identifier prefix (fully qualified qb64)
239    /// Value is encrypted private key
240    pub prxs: CesrSuber<Cipher>,
241
242    /// Next key digests database
243    /// Key is identifier prefix (fully qualified qb64)
244    /// Value is next key commitment (digest)
245    pub nxts: CesrSuber<Cipher>,
246
247    /// Prefixes database
248    /// Key is first public key in key sequence for a prefix (fully qualified qb64)
249    /// Value is prefix or first public key (temporary) (fully qualified qb64)
250    pub pres: CesrSuber<Prefixer>,
251
252    /// Prefix parameters database
253    /// Key is identifier prefix (fully qualified qb64)
254    /// Value is serialized parameter dict of public key parameters
255    pub prms: Komer<PrePrm>,
256
257    /// Prefix situation database
258    /// Key is identifier prefix (fully qualified qb64)
259    /// Value is serialized parameter dict of public key situation
260    pub sits: Komer<PreSit>,
261
262    /// Public keys database
263    /// Key is prefix.ridx (rotation index as 32 char hex string)
264    /// Value is serialized list of fully qualified public keys
265    pub pubs: Komer<PubSet>,
266}
267
268impl Filer for Keeper {
269    fn defaults() -> FilerDefaults {
270        BaseFiler::defaults()
271    }
272
273    #[cfg(target_os = "windows")]
274    const TAIL_DIR_PATH: &'static str = "keri\\ks";
275    #[cfg(not(target_os = "windows"))]
276    const TAIL_DIR_PATH: &'static str = "keri/ks";
277
278    #[cfg(target_os = "windows")]
279    const ALT_TAIL_DIR_PATH: &'static str = ".keri\\ks";
280    #[cfg(not(target_os = "windows"))]
281    const ALT_TAIL_DIR_PATH: &'static str = ".keri/ks";
282
283    const TEMP_PREFIX: &'static str = "keri_ks_";
284}
285
286impl Keeper {
287    /// Maximum number of named databases
288    pub const MAX_NAMED_DBS: u32 = 10;
289
290    /// Create a new Keeper instance
291    pub fn new(lmdber: Arc<LMDBer>) -> Result<Self, DBError> {
292        // Create the keeper instance
293        let keeper = Keeper {
294            lmdber: lmdber.clone(),
295            // These will be initialized in the reopen method
296            gbls: Suber::new(lmdber.clone(), "gbls.", None, false)
297                .map_err(|e| DBError::DatabaseError(format!("SuberError: {}", e)))?,
298            pris: CryptSignerSuber::new(lmdber.clone(), "pris.", None, false)
299                .map_err(|e| DBError::DatabaseError(format!("SuberError: {}", e)))?,
300            prxs: CesrSuber::new(lmdber.clone(), "prxs.", None, false)
301                .map_err(|e| DBError::DatabaseError(format!("SuberError: {}", e)))?,
302            nxts: CesrSuber::new(lmdber.clone(), "nxts.", None, false)
303                .map_err(|e| DBError::DatabaseError(format!("SuberError: {}", e)))?,
304            pres: CesrSuber::new(lmdber.clone(), "pres.", None, false)
305                .map_err(|e| DBError::DatabaseError(format!("SuberError: {}", e)))?,
306            prms: Komer::new(lmdber.clone(), "prms.", SerialKind::Json)
307                .map_err(|e| DBError::DatabaseError(format!("SuberError: {}", e)))?,
308            sits: Komer::new(lmdber.clone(), "sits.", SerialKind::Json)
309                .map_err(|e| DBError::DatabaseError(format!("SuberError: {}", e)))?,
310            pubs: Komer::new(lmdber.clone(), "pubs.", SerialKind::Json)
311                .map_err(|e| DBError::DatabaseError(format!("SuberError: {}", e)))?,
312        };
313
314        Ok(keeper)
315    }
316
317    /// Check if database is opened
318    pub fn opened(&self) -> bool {
319        self.lmdber.opened()
320    }
321
322    /// Get name of database
323    pub fn name(&self) -> String {
324        self.lmdber.name()
325    }
326
327    /// Get database path
328    pub fn path(&self) -> Option<PathBuf> {
329        self.lmdber.path()
330    }
331
332    /// Close the database
333    /// Check if database is temporary
334    pub fn temp(&self) -> bool {
335        self.lmdber.temp()
336    }
337
338    /// Create a key to access the pubs database with prefix and rotation index
339    pub fn ri_key(pre: &str, ri: u64) -> String {
340        format!("{}.{:032x}", pre, ri)
341    }
342}
343
344/// Trait for key pair storage and cryptographic key management
345pub trait KeeperTrait: Send + Sync {
346    /// Check if database is opened
347    fn opened(&self) -> bool;
348
349    /// Get name of database
350    fn name(&self) -> String;
351
352    /// Get database path
353    fn path(&self) -> Option<PathBuf>;
354
355    /// Check if database is temporary
356    fn temp(&self) -> bool;
357
358    /// Create a key to access the pubs database with prefix and rotation index
359    fn ri_key(&self, pre: &str, ri: u64) -> String;
360}
361
362impl KeeperTrait for Keeper {
363    fn opened(&self) -> bool {
364        self.lmdber.opened()
365    }
366
367    fn name(&self) -> String {
368        self.lmdber.name()
369    }
370
371    fn path(&self) -> Option<PathBuf> {
372        self.lmdber.path()
373    }
374
375    fn temp(&self) -> bool {
376        self.lmdber.temp()
377    }
378
379    fn ri_key(&self, pre: &str, ri: u64) -> String {
380        Self::ri_key(pre, ri) // Calling the static method
381    }
382}
383
384#[cfg(test)]
385mod tests {
386    use super::*;
387    use crate::cesr::Parsable;
388    use crate::Matter;
389
390    #[test]
391    fn test_keeper_basics() -> Result<(), DBError> {
392        // Create a temporary Keeper instance
393        let lmdber = Arc::new(LMDBer::builder().name("test_keeper").temp(true).build()?);
394
395        // Create "seen." database
396        assert_eq!(lmdber.name(), "test_keeper");
397        assert!(lmdber.opened());
398        let keeper = Keeper::new(lmdber.clone())?;
399        assert!(keeper.opened());
400
401        // Check it was created properly
402        assert_eq!(keeper.name(), "test_keeper");
403        assert!(keeper.opened());
404        assert!(keeper.temp());
405
406        // Check path exists
407        let path = keeper.path().unwrap();
408        assert!(path.exists());
409
410        // Test dropping the keeper (should clean up if temp=true)
411        drop(keeper);
412        drop(lmdber);
413
414        //TODO: Fix lmdber clean up dir on temp=true
415        // assert!(!path.exists());
416
417        Ok(())
418    }
419
420    #[test]
421    fn test_keeper_subdb() -> Result<(), DBError> {
422        // Create a temporary Keeper instance
423        let lmdber = Arc::new(
424            LMDBer::builder()
425                .name("test_keeper_subdb")
426                .temp(true)
427                .build()?,
428        );
429
430        // Create "seen." database
431        assert_eq!(lmdber.name(), "test_keeper_subdb");
432        assert!(lmdber.opened());
433        let keeper = Keeper::new(lmdber.clone())?;
434
435        // Test the gbls database
436        let key = "aeid";
437        let val = "BDzwEHHzq7K0gzQPYGGwTmuupUhPx5_yZ-Wk1x4ejhcc";
438
439        keeper
440            .gbls
441            .put(&[key], &val.as_bytes())
442            .map_err(|e| DBError::DatabaseError(format!("SuberError: {}", e)))?;
443
444        let result: Option<Vec<u8>> = keeper
445            .gbls
446            .get(&[key])
447            .map_err(|e| DBError::DatabaseError(format!("SuberError: {}", e)))?;
448        assert!(result.is_some());
449
450        let val_bytes = result.unwrap();
451        let val_str = String::from_utf8(val_bytes).unwrap();
452        assert_eq!(val_str, val);
453
454        // Test the pres database
455        let pub_key = b"BDzwEHHzq7K0gzQPYGGwTmuupUhPx5_yZ-Wk1x4ejhcc";
456        let pre = Prefixer::from_qb64b(&mut pub_key.to_vec(), None).expect("Invalid prefix");
457
458        keeper
459            .pres
460            .put(&[pub_key], &pre)
461            .expect("Failed to put prefix");
462
463        let result = keeper.pres.get(&[pub_key]).expect("Failed to get prefix");
464        assert!(result.is_some());
465
466        let retrieved_pre = result.unwrap();
467        assert_eq!(retrieved_pre.qb64(), pre.qb64());
468
469        // Test the prms Komer database (would require complete PrePrm implementation)
470        // For brevity, we'll just check it exists
471        let prms = PrePrm::default();
472        let key = "prms.00000000000000000000000000000000";
473        let result = keeper.prms.put(&[key], &prms).expect("Failed to put prms");
474        assert!(result);
475
476        let result = keeper.prms.get(&[key]).expect("Failed to get prms");
477        assert!(result.is_some());
478        assert_eq!(result.unwrap().pidx, 0);
479
480        assert!(
481            keeper
482                .prms
483                .cnt_all()
484                .expect("there to be some values in the database")
485                > 0
486        );
487
488        Ok(())
489    }
490
491    #[test]
492    fn test_keeper_ri_key() {
493        let pre = "EBfxc1UdwEMYy_g8Ldekf-aQEzBSkb3A5-vASBrV0qs4";
494        let ri = 0;
495        assert_eq!(
496            Keeper::ri_key(pre, ri),
497            "EBfxc1UdwEMYy_g8Ldekf-aQEzBSkb3A5-vASBrV0qs4.00000000000000000000000000000000"
498        );
499
500        let ri = 1;
501        assert_eq!(
502            Keeper::ri_key(pre, ri),
503            "EBfxc1UdwEMYy_g8Ldekf-aQEzBSkb3A5-vASBrV0qs4.00000000000000000000000000000001"
504        );
505    }
506}