Add documentation around HistoryParams insecure options

akd/benches/directory.rs

@@ -79,7 +79,7 @@ fn history_generation<TC: NamedConfiguration>(c: &mut Criterion) {
 
                 // generate for the most recent 10 updates
                 let label = AkdLabel::from("User 1");
-                let params = akd::HistoryParams::MostRecent(5);
+                let params = akd::HistoryParams::MostRecentInsecure(5);
                 runtime
                     .block_on(directory.key_history(&label, params))
                     .unwrap();

akd/src/directory.rs

@@ -461,8 +461,10 @@ where
         // apply filters specified by HistoryParams struct
         user_data = match params {
             HistoryParams::Complete => user_data,
-            HistoryParams::MostRecent(n) => user_data.into_iter().take(n).collect::<Vec<_>>(),
-            HistoryParams::SinceEpoch(epoch) => {
+            HistoryParams::MostRecentInsecure(n) => {
+                user_data.into_iter().take(n).collect::<Vec<_>>()
+            }
+            HistoryParams::SinceEpochInsecure(epoch) => {
                 user_data = user_data
                     .into_iter()
                     .filter(|val| val.epoch >= epoch)
@@ -861,10 +863,12 @@ where
 pub enum HistoryParams {
     /// Returns a complete history for a label
     Complete,
-    /// Returns up to the most recent N updates for a label
-    MostRecent(usize),
-    /// Returns all updates since a specified epoch (inclusive)
-    SinceEpoch(u64),
+    /// Returns up to the most recent N updates for a label. This is not secure, and
+    /// should not be used in a production environment.
+    MostRecentInsecure(usize),
+    /// Returns all updates since a specified epoch (inclusive). This is not secure, and
+    /// should not be used in a production environment.
+    SinceEpochInsecure(u64),
 }
 
 impl Default for HistoryParams {

akd/src/lib.rs

@@ -198,11 +198,14 @@
 //! ```
 //!
 //! ## History Proofs
-//! As mentioned above, the security is defined by consistent views of the value for a key at any epoch.
+//! As mentioned above, security is defined by consistent views of the value for a key at any epoch.
 //! To this end, a server running an AKD needs to provide a way to check the history of a key. Note that in this case,
 //! the server is trusted for validating that a particular client is authorized to run a history check on a particular key.
-//! We can use [`Directory::key_history`] to prove the history of a key's values at a given epoch. The [HistoryParams] field
-//! can be used to limit the history that we issue proofs for, but in this example we default to a complete history.
+//! We can use [`Directory::key_history`] to prove the history of a key's values at a given epoch.
+//!
+//! The [HistoryParams] field can be used to limit the history that we issue proofs for, but in this
+//! example we default to a complete history. For more information on the parameters, see the
+//! [History Parameters](#history-parameters) section.
 //! ```
 //! # use akd::storage::StorageManager;
 //! # use akd::storage::memory::AsyncInMemoryDatabase;
@@ -422,6 +425,19 @@
 //! ```
 //! An application can set their own specific domain label to a custom string achieve domain separation from other applications.
 //!
+//! ## History Parameters
+//!
+//! The [HistoryParams] enum can be used to limit the number of updates for a given entry that the server provides
+//! to the client. The enum has the following options:
+//! - [HistoryParams::Complete]: Includes a complete history of all updates to an entry. This is the default option.
+//! - [HistoryParams::MostRecentInsecure]: Includes (at most) the most recent input number of updates for an entry.
+//! - [HistoryParams::SinceEpochInsecure]: Includes all updates to an entry since a given epoch.
+//!
+//! Note that the "insecure" options are not recommended for use in production, as they do not provide a
+//! complete history of updates, and lack inclusion proofs for earlier entries. These options should only be
+//! used for testing purposes.
+//!
+//!
 //! ## Compilation Features
 //!
 //! This crate supports multiple compilation features:

akd/src/tests.rs

@@ -567,7 +567,10 @@ async fn test_limited_key_history<TC: Configuration>() -> Result<(), AkdError> {
 
     // "hello" was updated in epochs 1,2,3,5. Pull the latest item from the history (i.e. a lookup proof)
     let (history_proof, root_hash) = akd
-        .key_history(&AkdLabel::from("hello"), HistoryParams::MostRecent(1))
+        .key_history(
+            &AkdLabel::from("hello"),
+            HistoryParams::MostRecentInsecure(1),
+        )
         .await?;
     assert_eq!(1, history_proof.update_proofs.len());
     assert_eq!(5, history_proof.update_proofs[0].epoch);
@@ -584,7 +587,10 @@ async fn test_limited_key_history<TC: Configuration>() -> Result<(), AkdError> {
 
     // Take the top 3 results, and check that we're getting the right epoch updates
     let (history_proof, root_hash) = akd
-        .key_history(&AkdLabel::from("hello"), HistoryParams::MostRecent(3))
+        .key_history(
+            &AkdLabel::from("hello"),
+            HistoryParams::MostRecentInsecure(3),
+        )
         .await?;
     assert_eq!(3, history_proof.update_proofs.len());
     assert_eq!(5, history_proof.update_proofs[0].epoch);
@@ -603,7 +609,10 @@ async fn test_limited_key_history<TC: Configuration>() -> Result<(), AkdError> {
 
     // "hello" was updated in epochs 1,2,3,5. Pull the updates since epoch 3 (inclusive)
     let (history_proof, root_hash) = akd
-        .key_history(&AkdLabel::from("hello"), HistoryParams::SinceEpoch(3))
+        .key_history(
+            &AkdLabel::from("hello"),
+            HistoryParams::SinceEpochInsecure(3),
+        )
         .await?;
     assert_eq!(2, history_proof.update_proofs.len());
     assert_eq!(5, history_proof.update_proofs[0].epoch);