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

//!

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

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

use crate::{

    ArtiPath, BoxedKeystore, Error, KeyCertificateSpecifier, 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,

};

/// 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")]

    #[cfg_attr(docsrs, doc(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.

            // 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.

    /// 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()`.

    /// 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.

    #[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).

    ///

    /// NOTE: Currently, ctor entries cannot be validated using [`describe`](KeyMgr::describe), so they

    /// are considered valid if the manager successfully retrieves the corresponding keys,

    /// but are otherwise not validated by this procedure.

    ///

    /// 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

        // TODO: Implement `describe()` support for CTor keystore entries

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

                // TODO: `Error::Corruption` might not be the best fit for this situation.

    /// 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`] 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 keys and certificates of a specific keystore.

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

    /// Describe the specified key.

    ///

    /// Returns [`KeyPathError::Unrecognized`] 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 key from one of the specified `stores`.

    ///

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

        };

    /// 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_duration_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::{

        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 std::time::{Duration, SystemTime};

    use tor_basic_utils::test_rng::testing_rng;

    use tor_cert::CertifiedKey;

    use tor_cert::Ed25519Cert;

    use tor_error::{ErrorKind, HasKind};

    use tor_key_forge::{

        CertData, EncodableItem, ErasedKey, InvalidCertError, KeyType, KeystoreItem,

    };

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

    use tor_llcrypto::rng::FakeEntropicRng;

    /// 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,

    }

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

    #[derive(Clone, Debug)]

    struct AlwaysValidCert(TestItem);

    /// The corresponding fake public key type.

    #[derive(Clone, Debug)]

    struct TestPublicKey {

        /// The underlying key.

        key: KeystoreItem,

    }

    impl From<TestItem> for TestPublicKey {

        fn from(tk: TestItem) -> TestPublicKey {

            TestPublicKey { key: tk.item }

        }

    }

    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 = TestItem;

        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))

        }

        /// 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))

    }

    macro_rules! impl_keystore {

        ($name:tt, $id:expr $(,$unrec:expr)?) => {

            struct $name {

                inner: RwLock<

                    Vec<StdResult<(ArtiPath, KeystoreItemType, TestItem), UnrecognizedEntryError>>,

                >,

                id: KeystoreId,

            }

            impl Default for $name {

                fn default() -> Self {

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

                    let inner: RwLock<

                        Vec<

                            StdResult<

                                (ArtiPath, KeystoreItemType, TestItem),

                                UnrecognizedEntryError,

                            >,

                        >,

                    > = Default::default();

                    // Populate the Keystore with the specified number

                    // of unrecognized entries.

                    $(

                        for i in 0..$unrec {

                            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, id.clone()).into();

                            let entry = UnrecognizedEntryError::new(

                                entry,

                                Arc::new(ArtiNativeKeystoreError::MalformedPath {

                                    path: invalid_key_path,

                                    err: MalformedPathError::NoExtension,

                                }),

                            );

                            inner.write().unwrap().push(Err(entry));

                        }

                    )?

                    Self {

                        inner,

                        id,

                    }

                }

            }

            #[allow(dead_code)] // this is only dead code for Keystore1

            impl $name {

                fn new_boxed() -> BoxedKeystore {

                    Box::<Self>::default()

                }

            }

            impl crate::Keystore for $name {

                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()

                        .find(|res| match res {

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

                            Err(_) => false,

                        })

                        .is_some())

                }

                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| {

                        match res {

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

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

                                    let mut k = k.clone();

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

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

                                }

                            }

                            Err(_) => {}

                        }

                        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 meta = key.meta.clone();

                    let item_type = item.item_type()?;

                    let key = TestItem { item, meta };

                    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))));

                    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())

                }

            }

        };

    }

    macro_rules! impl_specifier {

        ($name:tt, $id:expr) => {

            struct $name;

            impl KeySpecifier for $name {

                fn arti_path(&self) -> StdResult<ArtiPath, ArtiPathUnavailableError> {

                    Ok(ArtiPath::new($id.into()).map_err(|e| tor_error::internal!("{e}"))?)

                }

                fn ctor_path(&self) -> Option<crate::CTorPath> {

                    None

                }

                fn keypair_specifier(&self) -> Option<Box<dyn KeySpecifier>> {

                    None

                }

            }

        };

    }

    impl_keystore!(Keystore1, "keystore1");

    impl_keystore!(Keystore2, "keystore2");

    impl_keystore!(Keystore3, "keystore3");

    impl_keystore!(KeystoreUnrec1, "keystore_unrec1", 1);

    impl_specifier!(TestKeySpecifier1, "spec1");

    impl_specifier!(TestKeySpecifier2, "spec2");

    impl_specifier!(TestKeySpecifier3, "spec3");

    impl_specifier!(TestKeySpecifier4, "spec4");

    impl_specifier!(TestPublicKeySpecifier1, "pub-spec1");

    /// Create a test `KeystoreEntry`.

    fn entry_descriptor(specifier: impl KeySpecifier, keystore_id: &KeystoreId) -> KeystoreEntry {

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

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

        KeystoreEntry {

            key_path: arti_path.into(),

            key_type: TestItem::item_type(),

            keystore_id,

            raw_id,

        }

    }

    #[test]

    #[allow(clippy::cognitive_complexity)]

    fn insert_and_get() {

        let mut builder = KeyMgrBuilder::default().primary_store(Box::<Keystore1>::default());

        builder

            .secondary_stores()

            .extend([Keystore2::new_boxed(), Keystore3::new_boxed()]);

        let mgr = builder.build().unwrap();

        // Insert a key into Keystore2

        let old_key = mgr

            .insert(

                TestItem::new("coot"),

                &TestKeySpecifier1,

                KeystoreSelector::Id(&KeystoreId::from_str("keystore2").unwrap()),

                true,

            )

            .unwrap();

        assert!(old_key.is_none());

        let key = mgr.get::<TestItem>(&TestKeySpecifier1).unwrap().unwrap();

        assert_eq!(key.meta.item_id(), "coot");

        assert_eq!(

            key.meta.retrieved_from(),

            Some(&KeystoreId::from_str("keystore2").unwrap())

        );

        assert_eq!(key.meta.is_generated(), false);

        // Insert a different key using the _same_ key specifier.

        let old_key = mgr

            .insert(

                TestItem::new("gull"),

                &TestKeySpecifier1,

                KeystoreSelector::Id(&KeystoreId::from_str("keystore2").unwrap()),

                true,

            )

            .unwrap()

            .unwrap();

        assert_eq!(old_key.meta.item_id(), "coot");

        assert_eq!(

            old_key.meta.retrieved_from(),

            Some(&KeystoreId::from_str("keystore2").unwrap())