//! Code for managing multiple [`Keystore`](crate::Keystore)s.

//!

//! See the [`KeyMgr`] docs for more details.

use crate::raw::{RawEntryId, RawKeystoreEntry};

use crate::{

    ArtiPath, BoxedKeystore, KeyPath, KeyPathError, KeyPathInfo, KeyPathInfoExtractor,

    KeyPathPattern, KeySpecifier, KeystoreCorruptionError, KeystoreEntryResult, KeystoreId,

    KeystoreSelector, Result,

};

use itertools::Itertools;

use std::iter;

use std::result::Result as StdResult;

use tor_error::{bad_api_usage, internal, into_bad_api_usage};

use tor_key_forge::{

    ItemType, Keygen, KeygenRng, KeystoreItemType, ToEncodableCert, ToEncodableKey,

};

#[cfg(feature = "experimental-api")]

use crate::KeyCertificateSpecifier;

/// A key manager that acts as a frontend to a primary [`Keystore`](crate::Keystore) and

/// any number of secondary [`Keystore`](crate::Keystore)s.

///

/// Note: [`KeyMgr`] is a low-level utility and does not implement caching (the key stores are

/// accessed for every read/write).

///

/// The `KeyMgr` accessors - currently just [`get()`](KeyMgr::get) -

/// search the configured key stores in order: first the primary key store,

/// and then the secondary stores, in order.

///

///

/// ## Concurrent key store access

///

/// The key stores will allow concurrent modification by different processes. In

/// order to implement this safely without locking, the key store operations (get,

/// insert, remove) will need to be atomic.

///

/// **Note**: [`KeyMgr::generate`] and [`KeyMgr::get_or_generate`] should **not** be used

/// concurrently with any other `KeyMgr` operation that mutates the same key

/// (i.e. a key with the same `ArtiPath`), because

/// their outcome depends on whether the selected key store

/// [`contains`][crate::Keystore::contains]

/// the specified key (and thus suffers from a TOCTOU race).

#[derive(derive_builder::Builder)]

#[builder(pattern = "owned", build_fn(private, name = "build_unvalidated"))]

pub struct KeyMgr {

    /// The primary key store.

    primary_store: BoxedKeystore,

    /// The secondary key stores.

    #[builder(default, setter(custom))]

    secondary_stores: Vec<BoxedKeystore>,

    /// The key info extractors.

    ///

    /// These are initialized internally by [`KeyMgrBuilder::build`], using the values collected

    /// using `inventory`.

    #[builder(default, setter(skip))]

    key_info_extractors: Vec<&'static dyn KeyPathInfoExtractor>,

}

/// A keystore entry descriptor.

///

/// This identifies a key entry from a specific keystore.

/// The key entry can be retrieved, using [`KeyMgr::get_entry`],

/// or removed, using [`KeyMgr::remove_entry`].

///

/// Returned from [`KeyMgr::list_matching`].

#[derive(Clone, Debug, PartialEq, amplify::Getters)]

pub struct KeystoreEntry<'a> {

    /// The [`KeyPath`] of the key.

    key_path: KeyPath,

    /// The [`KeystoreItemType`] of the key.

    key_type: KeystoreItemType,

    /// The [`KeystoreId`] of the keystore where the key was found.

    #[getter(as_copy)]

    keystore_id: &'a KeystoreId,

    /// The [`RawEntryId`] of the key, an identifier used in

    /// `arti raw` operations.

    #[getter(skip)]

    raw_id: RawEntryId,

}

impl<'a> KeystoreEntry<'a> {

    /// Create a new `KeystoreEntry`

    /// Return an instance of [`RawKeystoreEntry`]

    #[cfg(feature = "onion-service-cli-extra")]

}

// NOTE: Some methods require a `KeystoreEntryResult<KeystoreEntry>` as an

// argument (e.g.: `KeyMgr::raw_keystore_entry`). For this reason  implementing

// `From<KeystoreEntry<'a>> for KeystoreEntryResult<KeystoreEntry<'a>>` makes

// `KeystoreEntry` more ergonomic.

impl<'a> From<KeystoreEntry<'a>> for KeystoreEntryResult<KeystoreEntry<'a>> {

}

impl KeyMgrBuilder {

    /// Construct a [`KeyMgr`] from this builder.

        use itertools::Itertools as _;

}

// TODO: auto-generate using define_list_builder_accessors/define_list_builder_helper

// when that becomes possible.

//

// See https://gitlab.torproject.org/tpo/core/arti/-/merge_requests/1760#note_2969841

impl KeyMgrBuilder {

    /// Access the being-built list of secondary stores (resolving default)

    ///

    /// If the field has not yet been set or accessed, the default list will be

    /// constructed and a mutable reference to the now-defaulted list of builders

    /// will be returned.

    /// Set the whole list (overriding the default)

    /// Inspect the being-built list (with default unresolved)

    ///

    /// If the list has not yet been set, or accessed, `&None` is returned.

    /// Mutably access the being-built list (with default unresolved)

    ///

    /// If the list has not yet been set, or accessed, `&mut None` is returned.

}

inventory::collect!(&'static dyn crate::KeyPathInfoExtractor);

impl KeyMgr {

    /// Read a key from one of the key stores, and try to deserialize it as `K::Key`.

    ///

    /// The key returned is retrieved from the first key store that contains an entry for the given

    /// specifier.

    ///

    /// Returns `Ok(None)` if none of the key stores have the requested key.

    /// Retrieve the specified keystore entry, and try to deserialize it as `K::Key`.

    ///

    /// The key returned is retrieved from the key store specified in the [`KeystoreEntry`].

    ///

    /// Returns `Ok(None)` if the key store does not contain the requested entry.

    ///

    /// Returns an error if the specified `key_type` does not match `K::Key::item_type()`.

    /// Retrieve the specified keystore certificate entry and the corresponding

    /// subject and signing keys, deserializing the subject key as `K::Key`,

    /// the cert as `C::Cert`, and the signing key as `C::SigningKey`.

    ///

    /// The `S` type parameter is the [`KeyCertificateSpecifier`] of the certificate.

    ///

    /// The key returned is retrieved from the key store specified in the [`KeystoreEntry`].

    ///

    /// Returns `Ok(None)` if the key store does not contain the requested entry.

    ///

    /// Returns an error if the item type of the [`KeystoreEntry`] does not match `C::item_type()`,

    /// or if the certificate is not valid according to [`ToEncodableCert::validate`],

    /// or if the [`ArtiPath`] of the entry cannot be converted to a certificate specifier

    /// of type `S`.

    #[cfg(feature = "experimental-api")]

        )

    /// Read the key identified by `key_spec`.

    ///

    /// The key returned is retrieved from the first key store that contains an entry for the given

    /// specifier.

    ///

    /// If the requested key does not exist in any of the key stores, this generates a new key of

    /// type `K` from the key created using using `K::Key`'s [`Keygen`] implementation, and inserts

    /// it into the specified keystore, returning the newly inserted value.

    ///

    /// This is a convenience wrapper around [`get()`](KeyMgr::get) and

    /// [`generate()`](KeyMgr::generate).

    {

        }

    /// Read a key from one of the key stores specified, and try to deserialize it as `K::Key`.

    ///

    /// Returns `Ok(None)` if none of the key stores have the requested key.

    ///

    /// Returns an error if the specified keystore does not exist.

    // TODO: The function takes `&KeystoreId`, but it would be better to accept a

    // `KeystoreSelector`.

    // This way, the caller can pass `KeystoreSelector::Primary` directly without

    // needing to know the specific `KeystoreId` of the primary keystore.

    #[cfg(feature = "onion-service-cli-extra")]

    /// Validates the integrity of a [`KeystoreEntry`].

    ///

    /// This retrieves the key corresponding to the provided [`KeystoreEntry`],

    /// and checks if its contents are valid (i.e. that the key can be parsed).

    /// The [`KeyPath`] of the entry is further validated using [`describe`](KeyMgr::describe).

    ///

    /// Returns `Ok(())` if the specified keystore entry is valid, and `Err` otherwise.

    ///

    /// NOTE: If the specified entry does not exist, this will only validate its [`KeyPath`].

    #[cfg(feature = "onion-service-cli-extra")]

        // Ignore the parsed key, only checking if it parses correctly

        // Ignore the result, just checking if the path is recognized

    /// Generate a new key of type `K`, and insert it into the key store specified by `selector`.

    ///

    /// If the key already exists in the specified key store, the `overwrite` flag is used to

    /// decide whether to overwrite it with a newly generated key.

    ///

    /// On success, this function returns the newly generated key.

    ///

    /// Returns [`Error::KeyAlreadyExists`](crate::Error::KeyAlreadyExists)

    /// if the key already exists in the specified key store and `overwrite` is `false`.

    ///

    /// **IMPORTANT**: using this function concurrently with any other `KeyMgr` operation that

    /// mutates the key store state is **not** recommended, as it can yield surprising results! The

    /// outcome of [`KeyMgr::generate`] depends on whether the selected key store

    /// [`contains`][crate::Keystore::contains] the specified key, and thus suffers from a TOCTOU race.

    //

    // TODO (#1119): can we make this less racy without a lock? Perhaps we should say we'll always

    // overwrite any existing keys.

    //

    // TODO: consider replacing the overwrite boolean with a GenerateOptions type

    // (sort of like std::fs::OpenOptions)

    {

        } else {

        }

    /// Insert `key` into the [`Keystore`](crate::Keystore) specified by `selector`.

    ///

    /// If the key already exists in the specified key store, the `overwrite` flag is used to

    /// decide whether to overwrite it with the provided key.

    ///

    /// If this key is not already in the keystore, `None` is returned.

    ///

    /// If this key already exists in the keystore, its value is updated

    /// and the old value is returned.

    ///

    /// Returns an error if the selected keystore is not the primary keystore or one of the

    /// configured secondary stores.

        } else {

        }

    /// Remove the key identified by `key_spec` from the [`Keystore`](crate::Keystore)

    /// specified by `selector`.

    ///

    /// Returns an error if the selected keystore is not the primary keystore or one of the

    /// configured secondary stores.

    ///

    /// Returns the value of the removed key,

    /// or `Ok(None)` if the key does not exist in the requested keystore.

    ///

    /// Returns `Err` if an error occurred while trying to remove the key.

    /// Remove the specified keystore entry.

    ///

    /// Like [`KeyMgr::remove`], except this function does not return the value of the removed key.

    ///

    /// A return value of `Ok(None)` indicates the key was not found in the specified key store,

    /// whereas `Ok(Some(())` means the key was successfully removed.

    //

    // TODO: We should be consistent and return the removed key.

    //

    // This probably will involve changing the return type of Keystore::remove

    // to Result<Option<ErasedKey>>.

    /// Remove the specified keystore entry.

    ///

    /// Similar to [`KeyMgr::remove_entry`], except this method accepts both recognized and

    /// unrecognized entries, identified by a raw id (in the form of a `&str`) and a

    /// [`KeystoreId`].

    ///

    /// Returns an error if the entry could not be removed, or if the entry doesn't exist.

    #[cfg(feature = "onion-service-cli-extra")]

    /// Return the keystore entry descriptors of the keys matching the specified [`KeyPathPattern`].

    ///

    /// NOTE: This searches for matching keys in _all_ keystores.

    ///

    /// NOTE: This function only returns the *recognized* entries that match the provided pattern.

    /// The unrecognized entries (i.e. those that do not have a valid [`KeyPath`]) will be filtered out,

    /// even if they match the specified pattern.

    /// List keys and certificates of the specified keystore.

    #[cfg(feature = "onion-service-cli-extra")]

    /// List keys and certificates of all the keystores.

    #[cfg(feature = "onion-service-cli-extra")]

    /// List all the configured keystore.

    #[cfg(feature = "onion-service-cli-extra")]

    /// Describe the specified key.

    ///

    /// Returns `None` if none of the registered

    /// [`KeyPathInfoExtractor`]s is able to parse the specified [`KeyPath`].

    ///

    /// This function uses the [`KeyPathInfoExtractor`]s registered using

    /// [`register_key_info_extractor`](crate::register_key_info_extractor),

    /// or by [`DefaultKeySpecifier`](crate::derive_deftly_template_KeySpecifier).

        }

    /// Attempt to retrieve a key from one of the specified `stores`.

    ///

    /// Returns the `<K as ToEncodableKey>::Key` representation of the key.

    ///

    /// See [`KeyMgr::get`] for more details.

                Ok(None) => {

                    // The key doesn't exist in this store, so we check the next one...

                }

                    // Note: we immediately return if one of the keystores is inaccessible.

                }

            };

            // Found it! Now try to downcast it to the right type (this should _not_ fail)...

        }

    /// Attempt to retrieve a certificate from one of the specified `stores`.

    #[cfg(feature = "experimental-api")]

        else {

        };

        // Get the subject key...

        else {

        };

    /// Attempt to retrieve a key from one of the specified `stores`.

    ///

    /// See [`KeyMgr::get`] for more details.

        else {

            // If the key_spec is the specifier for the public part of a keypair,

            // try getting the pair and extracting the public portion from it.

            };

        };

    /// Read the specified key and certificate from one of the key stores,

    /// deserializing the subject key as `K::Key`, the cert as `C::Cert`,

    /// and the signing key as `C::SigningKey`.

    ///

    /// Returns `Ok(None)` if none of the key stores have the requested key.

    ///

    // Note: the behavior of this function is a bit inconsistent with

    // get_or_generate_key_and_cert: here, if the cert is absent but

    // its subject key is not, we return Ok(None).

    // In get_or_generate_key_and_cert, OTOH< we return an error in that case

    // (because we can't possibly generate the missing subject key

    // without overwriting the cert of the missing key).

    ///

    /// This function validates the certificate using [`ToEncodableCert::validate`],

    /// returning an error if it is invalid or missing.

    #[cfg(feature = "experimental-api")]

    {

        // Get the subject key...

        else {

        };

        else {

        };

        // Finally, get the signing key and validate the cert

    /// Like [`KeyMgr::get_key_and_cert`], except this function also generates the subject key

    /// and its corresponding certificate if they don't already exist.

    ///

    /// If the key certificate is missing, it will be generated

    /// from the subject key and signing key using the provided `make_certificate` callback.

    ///

    /// Generates the missing key and/or certificate as follows:

    ///

    /// ```text

    /// | Subject Key exists | Signing Key exists | Cert exists | Action                                 |

    /// |--------------------|--------------------|-------------|----------------------------------------|

    /// | Y                  | Y                  | Y           | Validate cert, return key and cert     |

    /// |                    |                    |             | if valid, error otherwise              |

    /// |--------------------|--------------------|-------------|----------------------------------------|

    /// | N                  | Y                  | N           | Generate subject key and               |

    /// |                    |                    |             | a new cert signed with signing key     |

    /// |--------------------|--------------------|-------------|----------------------------------------|

    /// | Y                  | Y                  | N           | Generate cert signed with signing key  |

    /// |--------------------|--------------------|-------------|----------------------------------------|

    /// | Y                  | N                  | N           | Error - cannot validate cert           |

    /// |                    |                    |             | if signing key is not available        |

    /// |--------------------|--------------------|-------------|----------------------------------------|

    /// | Y/N                | N                  | N           | Error - cannot generate cert           |

    /// |                    |                    |             | if signing key is not available        |

    /// |--------------------|--------------------|-------------|----------------------------------------|

    /// | N                  | Y/N                | Y           | Error - subject key was removed?       |

    /// |                    |                    |             | (we found the cert,                    |

    /// |                    |                    |             | but the subject key is missing)        |

    /// ```

    ///

    //

    // Note; the table above isn't a markdown table because CommonMark-flavor markdown

    // doesn't support multiline text in tables. Even if we trim down the text,

    // the resulting markdown table would be pretty unreadable in raw form

    // (it would have several excessively long lines, over 120 chars in len).

    #[cfg(feature = "experimental-api")]

    {

            (Some(_), None) => {

            }

        }

            _ => {

                        )

            }

        };

            None => {

            }

        };

    /// Return an iterator over all configured stores.

    /// Return the [`Keystore`](crate::Keystore) matching the specified `selector`.

    ///

    /// Returns an error if the selected keystore is not the primary keystore or one of the

    /// configured secondary stores.

        }

    /// Return the [`Keystore`](crate::Keystore) with the specified `id`.

    ///

    /// Returns an error if the specified ID is not the ID of the primary keystore or

    /// the ID of one of the configured secondary stores.

    /// Get the signing key of the certificate described by `spec`.

    ///

    /// Returns a [`KeystoreCorruptionError::MissingSigningKey`] error

    /// if the signing key doesn't exist in any of the keystores.

    #[cfg(feature = "experimental-api")]

    {

        else {

        };

    /// Insert `cert` into the [`Keystore`](crate::Keystore) specified by `selector`.

    ///

    /// If the key already exists in the specified key store, it will be overwritten.

    ///

    // NOTE: if we ever make this public we should rethink/improve its API.

    // TODO: maybe fold this into insert() somehow?

    {

}

#[cfg(test)]

mod tests {

    // @@ begin test lint list maintained by maint/add_warning @@

    #![allow(clippy::bool_assert_comparison)]

    #![allow(clippy::clone_on_copy)]

    #![allow(clippy::dbg_macro)]

    #![allow(clippy::mixed_attributes_style)]

    #![allow(clippy::print_stderr)]

    #![allow(clippy::print_stdout)]

    #![allow(clippy::single_char_pattern)]

    #![allow(clippy::unwrap_used)]

    #![allow(clippy::unchecked_time_subtraction)]

    #![allow(clippy::useless_vec)]

    #![allow(clippy::needless_pass_by_value)]

    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->

    use super::*;

    use crate::keystore::arti::err::{ArtiNativeKeystoreError, MalformedPathError};

    use crate::raw::{RawEntryId, RawKeystoreEntry};

    use crate::test_utils::{TestDerivedKeySpecifier, TestDerivedKeypairSpecifier};

    use crate::{

        ArtiPath, ArtiPathUnavailableError, Error, KeyPath, KeystoreEntryResult, KeystoreError,

        UnrecognizedEntryError,

    };

    use std::path::PathBuf;

    use std::result::Result as StdResult;

    use std::str::FromStr;

    use std::sync::{Arc, RwLock};

    use tor_basic_utils::test_rng::testing_rng;

    use tor_cert::CertifiedKey;

    use tor_cert::Ed25519Cert;

    use tor_checkable::TimeValidityError;

    use tor_error::{ErrorKind, HasKind};

    use tor_key_forge::{

        CertData, CertType, EncodableItem, EncodedEd25519Cert, ErasedKey, InvalidCertError,

        KeyType, KeystoreItem,

    };

    use tor_llcrypto::pk::ed25519::{self, Ed25519PublicKey as _};

    use tor_llcrypto::rng::FakeEntropicRng;

    use web_time_compat::{Duration, SystemTime, SystemTimeExt};

    #[cfg(feature = "experimental-api")]

    use {

        crate::CertSpecifierPattern,

        crate::test_utils::{TestCertSpecifier, TestCertSpecifierPattern},

    };

    /// Metadata structure for tracking key operations in tests.

    #[derive(Clone, Debug, PartialEq)]

    struct KeyMetadata {

        /// The identifier for the item (e.g., "coot", "moorhen").

        item_id: String,

        /// The keystore from which the item was retrieved.

        ///

        /// Set by `Keystore::get`.

        retrieved_from: Option<KeystoreId>,

        /// Whether the item was generated via `Keygen::generate`.

        is_generated: bool,

    }

    /// Metadata structure for tracking certificate operations in tests.

    #[derive(Clone, Debug, PartialEq)]

    struct CertMetadata {

        /// The identifier for the subject key (e.g., "coot").

        subject_key_id: String,

        /// The identifier for the signing key (e.g., "moorhen").

        signing_key_id: String,

        /// The keystore from which the certificate was retrieved.

        ///

        /// Set by `Keystore::get`.

        retrieved_from: Option<KeystoreId>,

        /// Whether the certificate was freshly generated (i.e. returned from the "or generate"

        /// branch of `get_or_generate()`) or retrieved from a keystore.

        is_generated: bool,

    }

    /// Metadata structure for tracking item operations in tests.

    #[derive(Clone, Debug, PartialEq, derive_more::From)]

    enum ItemMetadata {

        /// Metadata about a key.

        Key(KeyMetadata),

        /// Metadata about a certificate.

        Cert(CertMetadata),

    }

    impl ItemMetadata {

        /// Get the item ID.

        ///

        /// For keys, this returns the key's ID.

        /// For certificates, this returns a formatted string identifying the subject key.

        fn item_id(&self) -> &str {

            match self {

                ItemMetadata::Key(k) => &k.item_id,

                ItemMetadata::Cert(c) => &c.subject_key_id,

            }

        }

        /// Get retrieved_from.

        fn retrieved_from(&self) -> Option<&KeystoreId> {

            match self {

                ItemMetadata::Key(k) => k.retrieved_from.as_ref(),

                ItemMetadata::Cert(c) => c.retrieved_from.as_ref(),

            }

        }

        /// Get is_generated.

        fn is_generated(&self) -> bool {

            match self {

                ItemMetadata::Key(k) => k.is_generated,

                ItemMetadata::Cert(c) => c.is_generated,

            }

        }

        /// Set the retrieved_from field to the specified keystore ID.

        fn set_retrieved_from(&mut self, id: KeystoreId) {

            match self {

                ItemMetadata::Key(meta) => meta.retrieved_from = Some(id),

                ItemMetadata::Cert(meta) => meta.retrieved_from = Some(id),

            }

        }

        /// Returns a reference to key metadata if this is a Key variant.

        fn as_key(&self) -> Option<&KeyMetadata> {

            match self {

                ItemMetadata::Key(meta) => Some(meta),

                _ => None,

            }

        }

        /// Returns a reference to certificate metadata if this is a Cert variant.

        fn as_cert(&self) -> Option<&CertMetadata> {

            match self {

                ItemMetadata::Cert(meta) => Some(meta),

                _ => None,

            }

        }

    }

    /// The type of "key" stored in the test key stores.

    #[derive(Clone, Debug)]

    struct TestItem {

        /// The underlying key.

        item: KeystoreItem,

        /// Metadata about the key.

        meta: ItemMetadata,

    }

    /// The type of certificate stored in the test key stores.

    struct TestCert(TestItem);

    impl ItemType for TestCert {

        fn item_type() -> KeystoreItemType

        where

            Self: Sized,

        {

            CertType::Ed25519TorCert.into()

        }

    }

    /// A "certificate" used for testing purposes.

    #[derive(Clone, Debug)]

    struct AlwaysValidCert(TestItem);

    /// An expired "certificate" used for testing purposes.

    #[derive(Clone, Debug)]

    struct AlwaysExpiredCert(TestItem);

    /// The corresponding fake public key type.

    #[derive(Clone, Debug)]

    struct TestPublicKey {

        /// The underlying key.

        key: KeystoreItem,

        /// Metadata about the key.

        meta: ItemMetadata,

    }

    impl From<TestItem> for TestPublicKey {

        fn from(tk: TestItem) -> TestPublicKey {

            TestPublicKey {

                key: tk.item,

                meta: tk.meta,

            }

        }

    }

    impl TestItem {

        /// Create a new test key with the specified metadata.

        fn new(item_id: &str) -> Self {

            let mut rng = testing_rng();

            TestItem {

                item: ed25519::Keypair::generate(&mut rng)

                    .as_keystore_item()

                    .unwrap(),

                meta: ItemMetadata::Key(KeyMetadata {

                    item_id: item_id.to_string(),

                    retrieved_from: None,

                    is_generated: false,

                }),

            }

        }

    }

    impl Keygen for TestItem {

        fn generate(mut rng: &mut dyn KeygenRng) -> tor_key_forge::Result<Self>

        where

            Self: Sized,

        {

            Ok(TestItem {

                item: ed25519::Keypair::generate(&mut rng).as_keystore_item()?,

                meta: ItemMetadata::Key(KeyMetadata {

                    item_id: "generated_test_key".to_string(),

                    retrieved_from: None,

                    is_generated: true,

                }),

            })

        }

    }

    impl ItemType for TestItem {

        fn item_type() -> KeystoreItemType

        where

            Self: Sized,

        {

            // Dummy value

            KeyType::Ed25519Keypair.into()

        }

    }

    impl EncodableItem for TestItem {

        fn as_keystore_item(&self) -> tor_key_forge::Result<KeystoreItem> {

            Ok(self.item.clone())

        }

    }

    impl ToEncodableKey for TestItem {

        type Key = Self;

        type KeyPair = Self;

        fn to_encodable_key(self) -> Self::Key {

            self

        }

        fn from_encodable_key(key: Self::Key) -> Self {

            key

        }

    }

    impl ItemType for TestPublicKey {

        fn item_type() -> KeystoreItemType

        where

            Self: Sized,

        {

            KeyType::Ed25519PublicKey.into()

        }

    }

    impl EncodableItem for TestPublicKey {

        fn as_keystore_item(&self) -> tor_key_forge::Result<KeystoreItem> {

            Ok(self.key.clone())

        }

    }

    impl ToEncodableKey for TestPublicKey {

        type Key = Self;

        type KeyPair = TestItem;

        fn to_encodable_key(self) -> Self::Key {

            self

        }

        fn from_encodable_key(key: Self::Key) -> Self {

            key

        }

    }

    impl ToEncodableCert<TestItem> for AlwaysValidCert {

        type ParsedCert = TestCert;

        type EncodableCert = TestItem;

        type SigningKey = TestItem;

        fn validate(

            cert: Self::ParsedCert,

            _subject: &TestItem,

            _signed_with: &Self::SigningKey,

        ) -> StdResult<Self, InvalidCertError> {

            // AlwaysValidCert is always valid

            Ok(Self(cert.0))

        }

        /// Convert this cert to a type that implements [`EncodableKey`].

        fn to_encodable_cert(self) -> Self::EncodableCert {

            self.0

        }

    }

    impl ToEncodableCert<TestItem> for AlwaysExpiredCert {

        type ParsedCert = TestCert;

        type EncodableCert = TestItem;

        type SigningKey = TestItem;

        fn validate(

            _cert: Self::ParsedCert,

            _subject: &TestItem,

            _signed_with: &Self::SigningKey,

        ) -> StdResult<Self, InvalidCertError> {

            Err(InvalidCertError::TimeValidity(TimeValidityError::Expired(

                Duration::from_secs(60),

            )))

        }

        /// Convert this cert to a type that implements [`EncodableKey`].

        fn to_encodable_cert(self) -> Self::EncodableCert {

            self.0

        }

    }

    #[derive(thiserror::Error, Debug, Clone, derive_more::Display)]

    enum MockKeystoreError {

        NotFound,

    }

    impl KeystoreError for MockKeystoreError {}

    impl HasKind for MockKeystoreError {

        fn kind(&self) -> ErrorKind {

            // Return a dummy ErrorKind for the purposes of this test

            tor_error::ErrorKind::Other

        }

    }

    fn build_raw_id_path<T: ToString>(key_path: &T, key_type: &KeystoreItemType) -> RawEntryId {

        let mut path = key_path.to_string();

        path.push('.');

        path.push_str(&key_type.arti_extension());

        RawEntryId::Path(PathBuf::from(&path))

    }

    struct Keystore {

        inner: RwLock<Vec<KeystoreEntryResult<(ArtiPath, KeystoreItemType, TestItem)>>>,

        id: KeystoreId,

    }

    impl Keystore {

        fn new(id: &str) -> Self {

            let id = KeystoreId::from_str(id).unwrap();

            Self {

                inner: Default::default(),

                id,

            }

        }

        fn new_boxed(id: &str) -> BoxedKeystore {

            Box::new(Self::new(id))

        }

    }

    impl crate::Keystore for Keystore {

        fn contains(

            &self,

            key_spec: &dyn KeySpecifier,

            item_type: &KeystoreItemType,

        ) -> Result<bool> {

            let wanted_arti_path = key_spec.arti_path().unwrap();

            Ok(self.inner.read().unwrap().iter().any(|res| match res {

                Ok((spec, ty, _)) => spec == &wanted_arti_path && ty == item_type,

                Err(_) => false,

            }))

        }

        fn id(&self) -> &KeystoreId {

            &self.id

        }

        fn get(

            &self,

            key_spec: &dyn KeySpecifier,

            item_type: &KeystoreItemType,

        ) -> Result<Option<ErasedKey>> {

            let key_spec = key_spec.arti_path().unwrap();

            Ok(self.inner.read().unwrap().iter().find_map(|res| {

                if let Ok((arti_path, ty, k)) = res {

                    if arti_path == &key_spec && ty == item_type {

                        let mut k = k.clone();

                        k.meta.set_retrieved_from(self.id().clone());

                        match item_type {

                            KeystoreItemType::Key(_) => {

                                return Some(Box::new(k) as Box<dyn ItemType>);

                            }

                            KeystoreItemType::Cert(_) => {

                                // Hack: the KeyMgr code will want to downcast cert types

                                // to C::ParsedCert, so we need to avoid returning the bare

                                // TestItem here

                                return Some(Box::new(TestCert(k)) as Box<dyn ItemType>);

                            }

                            _ => panic!("unknown item type?!"),

                        }

                    }

                }

                None

            }))

        }

        #[cfg(feature = "onion-service-cli-extra")]

        fn raw_entry_id(&self, raw_id: &str) -> Result<RawEntryId> {

            Ok(RawEntryId::Path(PathBuf::from(raw_id.to_string())))

        }

        fn insert(&self, key: &dyn EncodableItem, key_spec: &dyn KeySpecifier) -> Result<()> {

            let key = key.downcast_ref::<TestItem>().unwrap();

            let item = key.as_keystore_item()?;

            let item_type = item.item_type()?;

            self.inner

                .write()

                .unwrap()

                // TODO: `insert` is used instead of `push`, because some of the

                // tests (mainly `insert_and_get` and `keygen`) fail otherwise.

                // It could be a good idea to use `push` and adapt the tests,

                // in order to reduce cognitive complexity.

                .insert(

                    0,

                    Ok((key_spec.arti_path().unwrap(), item_type, key.clone())),

                );

            Ok(())

        }

        fn remove(

            &self,

            key_spec: &dyn KeySpecifier,

            item_type: &KeystoreItemType,

        ) -> Result<Option<()>> {

            let wanted_arti_path = key_spec.arti_path().unwrap();

            let index = self.inner.read().unwrap().iter().position(|res| {

                if let Ok((arti_path, ty, _)) = res {

                    arti_path == &wanted_arti_path && ty == item_type

                } else {

                    false

                }

            });

            let Some(index) = index else {

                return Ok(None);

            };

            let _ = self.inner.write().unwrap().remove(index);

            Ok(Some(()))

        }

        #[cfg(feature = "onion-service-cli-extra")]

        fn remove_unchecked(&self, entry_id: &RawEntryId) -> Result<()> {

            let index = self.inner.read().unwrap().iter().position(|res| match res {

                Ok((spec, ty, _)) => {

                    let id = build_raw_id_path(spec, ty);

                    entry_id == &id

                }

                Err(e) => e.entry().raw_id() == entry_id,

            });

            let Some(index) = index else {

                return Err(Error::Keystore(Arc::new(MockKeystoreError::NotFound)));

            };

            let _ = self.inner.write().unwrap().remove(index);

            Ok(())

        }

        fn list(&self) -> Result<Vec<KeystoreEntryResult<KeystoreEntry>>> {

            Ok(self

                .inner

                .read()

                .unwrap()

                .iter()

                .map(|res| match res {

                    Ok((arti_path, ty, _)) => {

                        let raw_id = RawEntryId::Path(PathBuf::from(&arti_path.to_string()));

                        Ok(KeystoreEntry::new(

                            KeyPath::Arti(arti_path.clone()),

                            ty.clone(),

                            self.id(),

                            raw_id,

                        ))

                    }

                    Err(e) => Err(e.clone()),

                })

                .collect())

        }

    }

    // Populate `keystore` with the specified number of unrecognized entries.

    fn add_unrecognized_entries(keystore: &mut Keystore, count: usize) {

        for i in 0..count {

            let invalid_key_path = PathBuf::from(&format!("unrecognized_entry{}", i));

            let raw_id = RawEntryId::Path(invalid_key_path.clone());

            let entry = RawKeystoreEntry::new(raw_id, keystore.id.clone()).into();

            let entry = UnrecognizedEntryError::new(

                entry,