lib2fas/

lib2fas.rs

use crate::decrypt::decrypt_services;
use crate::fuzzy::fuzzy_match;
use crate::helpers::{calculate_hash, now};
use crate::json5_support::{json5_from_reader, json5_from_reader_async};
use core::fmt::Formatter;
use core::hash::{Hash, Hasher};
use serde::{Deserialize, Serialize, Serializer};
use std::collections::{BTreeMap, VecDeque};
use std::path::PathBuf;

#[derive(Deserialize, Debug, Clone, PartialEq, PartialOrd, Ord, Eq, Hash, Default)]
pub(crate) struct RawOTPDetails {
    link: Option<String>,
    #[serde(alias = "tokenType")]
    token_type: Option<String>,
    source: Option<String>,
    label: Option<String>,
    account: Option<String>,
    digits: Option<i32>,
    period: Option<i32>,
}

impl RawOTPDetails {
    #[must_use]
    pub fn totp_client(&self) -> Option<totp_rs::TOTP> {
        let link = self.link.as_ref()?;

        // TOTP::from_url checks the secret length for some reason, this version does not:
        totp_rs::TOTP::from_url_unchecked(link).ok()
    }
}

/// Represents details of a one-time password (OTP) entry, including metadata, configuration,
/// and a TOTP client for generating time-based OTPs.
///
/// This struct is used to encapsulate the data and functionality associated with OTPs, including:
/// - TOTP generation at the current time, previous, or future time intervals.
/// - Conversion between string and numeric representations of tokens.
#[derive(Serialize, Debug, Clone, Default)]
pub struct OTPDetails {
    /// The link associated with the OTP, typically containing configuration details in URL format.
    link: Option<String>,
    /// The type of the token (e.g., TOTP, HOTP).
    token_type: Option<String>,
    /// The source or origin of the OTP configuration.
    source: Option<String>,
    /// A human-readable label for the OTP entry.
    label: Option<String>,
    /// The account associated with this OTP.
    account: Option<String>,
    /// The number of digits in the generated OTP (e.g., 6 or 8).
    digits: Option<i32>,
    /// The period (in seconds) for generating time-based OTPs.
    period: Option<i32>,
    /// A TOTP client capable of generating time-based OTPs.
    #[serde(skip_serializing)]
    client: Option<totp_rs::TOTP>,
}

impl PartialEq for OTPDetails {
    fn eq(
        &self,
        other: &Self,
    ) -> bool {
        // this ensures 'client' is omitted from eq check while other fields are checked
        self.fields().eq(&other.fields())
    }
}

// empty impl but required to make Rust understand that eq is possible based on previous partialeq
impl Eq for OTPDetails {}

impl Hash for OTPDetails {
    fn hash<H: Hasher>(
        &self,
        state: &mut H,
    ) {
        self.fields().hash(state);
        // exclude client!
    }
}

impl From<RawOTPDetails> for OTPDetails {
    fn from(val: RawOTPDetails) -> Self {
        let client = val.totp_client();

        Self {
            client,
            link: val.link,
            token_type: val.token_type,
            source: val.source,
            label: val.label,
            account: val.account,
            digits: val.digits,
            period: val.period,
        }
    }
}

impl OTPDetails {
    /// Generates the current time-based OTP as a string, if possible.
    ///
    /// # Returns
    /// - `Some(String)`: The OTP generated at the current time.
    /// - `None`: If the TOTP client or current timestamp is unavailable.
    #[must_use]
    pub fn totp(&self) -> Option<String> {
        self.totp_at(now()?)
    }

    /// Generates the current time-based OTP as a 32-bit unsigned integer, if possible.
    ///
    /// # Returns
    /// - `Some(u32)`: The OTP generated at the current time as a number.
    /// - `None`: If the TOTP client or current timestamp is unavailable.
    #[must_use]
    pub fn totp_u32(&self) -> Option<u32> {
        let token = self.totp()?;

        token.parse().ok()
    }

    /// Generates the next time-based OTP as a string, if possible.
    ///
    /// The next OTP corresponds to the token generated for the next time interval.
    ///
    /// # Returns
    /// - `Some(String)`: The next OTP.
    /// - `None`: If the TOTP client or current timestamp is unavailable.
    #[must_use]
    pub fn totp_next(&self) -> Option<String> {
        let next_t = now()? + 30; // new token every 30s
        self.totp_at(next_t)
    }

    /// Generates the next time-based OTP as a 32-bit unsigned integer, if possible.
    ///
    /// # Returns
    /// - `Some(u32)`: The next OTP as a number.
    /// - `None`: If the TOTP client or current timestamp is unavailable.
    #[must_use]
    pub fn totp_next_u32(&self) -> Option<u32> {
        let token = self.totp_next()?;
        token.parse().ok()
    }

    /// Generates the previous time-based OTP as a string, if possible.
    ///
    /// The previous OTP corresponds to the token generated for the last time interval.
    ///
    /// # Returns
    /// - `Some(String)`: The previous OTP.
    /// - `None`: If the TOTP client or current timestamp is unavailable.
    #[must_use]
    pub fn totp_previous(&self) -> Option<String> {
        let prev_t = now()? - 30; // new token every 30s
        self.totp_at(prev_t)
    }

    /// Generates the previous time-based OTP as a 32-bit unsigned integer, if possible.
    ///
    /// # Returns
    /// - `Some(u32)`: The previous OTP as a number.
    /// - `None`: If the TOTP client or current timestamp is unavailable.
    #[must_use]
    pub fn totp_previous_u32(&self) -> Option<u32> {
        let token = self.totp_previous()?;
        token.parse().ok()
    }

    /// Generates a time-based OTP for a specific timestamp, if possible.
    ///
    /// This method allows generating OTPs for custom timestamps, useful for testing or debugging.
    ///
    /// # Parameters
    /// - `timestamp_sec`: The timestamp (in seconds since the Unix epoch) for which to generate the OTP.
    ///
    /// # Returns
    /// - `Some(String)`: The OTP for the given timestamp.
    /// - `None`: If the TOTP client is unavailable.
    #[must_use]
    pub fn totp_at(
        &self,
        timestamp_sec: u64,
    ) -> Option<String> {
        self.client
            .as_ref()
            .map(|client| client.generate(timestamp_sec))
    }

    /// Generates a time-based OTP for a specific timestamp as a 32-bit unsigned integer, if possible.
    ///
    /// # Parameters
    /// - `timestamp_sec`: The timestamp (in seconds since the Unix epoch) for which to generate the OTP.
    ///
    /// # Returns
    /// - `Some(u32)`: The OTP for the given timestamp as a number.
    /// - `None`: If the TOTP client is unavailable.
    #[must_use]
    pub fn totp_at_u32(
        &self,
        timestamp_sec: u64,
    ) -> Option<u32> {
        let token = self.totp_at(timestamp_sec)?;
        token.parse().ok()
    }

    #[expect(
        clippy::type_complexity,
        reason = "It's a weird type but that's okay for this internal method"
    )]
    const fn fields(
        &self
    ) -> (
        &Option<String>,
        &Option<String>,
        &Option<String>,
        &Option<String>,
        &Option<String>,
        &Option<i32>,
        &Option<i32>,
    ) {
        // internal function to track fields used in hash, eq
        (
            &self.link,
            &self.token_type,
            &self.source,
            &self.label,
            &self.account,
            &self.digits,
            &self.period,
        )
    }
}

/// Represents a unique ordering of services with a positional value.
///
/// Typically used to define display or priority order.
#[derive(
    Serialize, Deserialize, Debug, Copy, Clone, PartialEq, PartialOrd, Ord, Eq, Hash, Default,
)]
pub struct OrderDetails {
    position: u32,
}

/// Details of an icon collection associated with a service, identified by a unique ID.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, PartialOrd, Ord, Eq, Hash, Default)]
pub struct IconCollectionDetails {
    id: String,
}

/// Represents icon details for a service, including the selected icon and its collection.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, PartialOrd, Ord, Eq, Hash, Default)]
pub struct IconDetails {
    selected: String,
    #[serde(alias = "iconCollection")]
    icon_collection: IconCollectionDetails,
}

#[derive(Deserialize, Debug, Clone, PartialEq, PartialOrd, Ord, Eq, Hash, Default)]
pub(crate) struct RawTwoFactorAuthDetails {
    /// `unique_id` = hash of name+secret, calculated after deserializing
    pub name: String,
    secret: String,
    #[serde(alias = "updatedAt")]
    pub updated_at: u32,
    #[serde(alias = "serviceTypeId")]
    pub service_type_id: Option<String>,
    pub otp: Option<RawOTPDetails>,
    pub order: Option<OrderDetails>,
    pub icon: Option<IconDetails>,
    #[serde(alias = "groupId")]
    pub group_id: Option<String>,
}

/// Represents a parsed and structured two-factor authentication (2FA) service.
///
/// This struct encapsulates all details and functionality associated with a single 2FA service, including:
/// - Metadata such as name, updated time, and associated group.
/// - Configuration details for generating OTPs.
/// - Integration with a TOTP client for token generation.
///
/// `TwoFactorAuthDetails` provides methods to generate OTPs and query associated metadata.
///
/// # Example
/// ```rust
/// use lib2fas::load_services;
/// use lib2fas::TwoFactorAuthDetails;
///
/// #[tokio::main]
/// async fn main() {
///     let result = load_services("path/to/services.2fas", Some("passphrase")).await;
///     match result {
///         Ok(storage) => {
///             if let Some(service) = storage.first() {
///                 // service: TwoFactorAuthDetails
///                 println!("Service Name: {}", service.name);
///                 if let Some(otp) = service.totp() {
///                     println!("Current OTP: {}", otp);
///                 } else {
///                     println!("OTP generation not available for this service.");
///                 }
///             } else {
///                 println!("No services found.");
///             }
///         },
///         Err(err) => {
///             eprintln!("Failed to load services: {}", err);
///         },
///     }
/// }
/// ```
#[derive(Serialize, Debug, Clone, PartialEq, Eq, Default, Hash)]
pub struct TwoFactorAuthDetails {
    /// A unique identifier for the 2FA service, derived from its name and secret.
    #[serde(serialize_with = "serialize_to_string")]
    pub unique_id: u64,
    /// The name of the 2FA service.
    pub name: String,
    /// The secret used for generating OTPs.
    secret: String,
    /// The timestamp (in seconds since the Unix epoch) when the service was last updated.
    pub updated_at: u32,
    /// The type of the service, if applicable.
    pub service_type_id: Option<String>,
    /// The OTP details associated with the service, including configuration and TOTP client.
    pub otp: Option<OTPDetails>,
    /// The order details of the service, used for display or prioritization.
    pub order: Option<OrderDetails>,
    /// The icon details of the service, including its collection and selected icon.
    pub icon: Option<IconDetails>,
    /// The ID of the group this service belongs to, if any.
    pub group_id: Option<String>,
}

impl TwoFactorAuthDetails {
    /// Generates the current time-based OTP as a string, if possible.
    ///
    /// # Returns
    /// - `Some(String)`: The OTP generated at the current time.
    /// - `None`: If OTP details or the TOTP client are unavailable.
    #[must_use]
    pub fn totp(&self) -> Option<String> {
        self.otp.as_ref().and_then(OTPDetails::totp)
    }

    /// Generates the current time-based OTP as a 32-bit unsigned integer, if possible.
    ///
    /// # Returns
    /// - `Some(u32)`: The OTP generated at the current time as a number.
    /// - `None`: If OTP details or the TOTP client are unavailable.
    #[must_use]
    pub fn totp_u32(&self) -> Option<u32> {
        self.otp.as_ref().and_then(OTPDetails::totp_u32)
    }

    /// Generates the next time-based OTP as a string, if possible.
    ///
    /// The next OTP corresponds to the token generated for the next time interval.
    ///
    /// # Returns
    /// - `Some(String)`: The next OTP.
    /// - `None`: If OTP details or the TOTP client are unavailable.
    #[cfg(not(tarpaulin))]
    #[must_use]
    pub fn totp_next(&self) -> Option<String> {
        self.otp.as_ref().and_then(OTPDetails::totp_next)
    }

    /// Generates the next time-based OTP as a 32-bit unsigned integer, if possible.
    ///
    /// # Returns
    /// - `Some(u32)`: The next OTP as a number.
    /// - `None`: If OTP details or the TOTP client are unavailable.
    #[must_use]
    pub fn totp_next_u32(&self) -> Option<u32> {
        self.otp.as_ref().and_then(OTPDetails::totp_next_u32)
    }

    /// Generates the previous time-based OTP as a string, if possible.
    ///
    /// The previous OTP corresponds to the token generated for the last time interval.
    ///
    /// # Returns
    /// - `Some(String)`: The previous OTP.
    /// - `None`: If OTP details or the TOTP client are unavailable.
    #[cfg(not(tarpaulin))]
    #[must_use]
    pub fn totp_previous(&self) -> Option<String> {
        self.otp.as_ref().and_then(OTPDetails::totp_previous)
    }

    /// Generates the previous time-based OTP as a 32-bit unsigned integer, if possible.
    ///
    /// # Returns
    /// - `Some(u32)`: The previous OTP as a number.
    /// - `None`: If OTP details or the TOTP client are unavailable.
    #[must_use]
    pub fn totp_previous_u32(&self) -> Option<u32> {
        self.otp.as_ref().and_then(OTPDetails::totp_previous_u32)
    }

    /// Generates a time-based OTP for a specific timestamp, if possible.
    ///
    /// This method allows generating OTPs for custom timestamps, useful for testing or debugging.
    ///
    /// # Parameters
    /// - `time`: The timestamp (in seconds since the Unix epoch) for which to generate the OTP.
    ///
    /// # Returns
    /// - `Some(String)`: The OTP for the given timestamp.
    /// - `None`: If OTP details or the TOTP client are unavailable.
    #[cfg(not(tarpaulin))]
    #[must_use]
    pub fn totp_at(
        &self,
        time: u64,
    ) -> Option<String> {
        self.otp.as_ref().and_then(|client| client.totp_at(time))
    }

    /// Generates a time-based OTP for a specific timestamp as a 32-bit unsigned integer, if possible.
    ///
    /// # Parameters
    /// - `time`: The timestamp (in seconds since the Unix epoch) for which to generate the OTP.
    ///
    /// # Returns
    /// - `Some(u32)`: The OTP for the given timestamp as a number.
    /// - `None`: If OTP details or the TOTP client are unavailable.
    #[must_use]
    pub fn totp_at_u32(
        &self,
        time: u64,
    ) -> Option<u32> {
        self.otp
            .as_ref()
            .and_then(|client| client.totp_at_u32(time))
    }
}

impl From<RawTwoFactorAuthDetails> for TwoFactorAuthDetails {
    fn from(val: RawTwoFactorAuthDetails) -> Self {
        let unique_id = calculate_hash(&format!("{}:{}", val.name, val.secret));
        let otp_with_client = val.otp.map(Into::into);

        Self {
            unique_id,
            name: val.name,
            secret: val.secret,
            updated_at: val.updated_at,
            service_type_id: val.service_type_id,
            otp: otp_with_client,
            order: val.order,
            icon: val.icon,
            group_id: val.group_id,
        }
    }
}

/// Represents a group of services, including metadata and expanded state.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, PartialOrd, Ord, Eq, Hash, Default)]
pub struct Group {
    id: String,
    name: String,

    #[serde(alias = "isExpanded")]
    is_expanded: bool,

    #[serde(alias = "updatedAt")]
    updated_at: u32,
}

#[derive(Deserialize, Debug, Clone, PartialEq, PartialOrd, Ord, Eq, Hash, Default)]
pub(crate) struct RawTwoFactorStorage {
    services: Vec<RawTwoFactorAuthDetails>,

    groups: Option<Vec<Group>>,

    #[serde(alias = "updatedAt")]
    updated_at: Option<u32>,

    #[serde(alias = "schemaVersion")]
    schema_version: Option<u8>, // should warn if not 4

    #[serde(alias = "appVersionCode")]
    app_version_code: Option<i32>,

    #[serde(alias = "appVersionName")]
    app_version_name: Option<String>,

    #[serde(alias = "appOrigin")]
    app_origin: Option<String>,

    #[serde(alias = "servicesEncrypted")]
    services_encrypted: Option<String>,
}

impl RawTwoFactorStorage {
    pub fn is_encrypted(&self) -> bool {
        self.services_encrypted
            .as_ref()
            .is_some_and(|value| !value.is_empty())
    }

    pub fn decrypt(
        &mut self,
        passphrase: &str,
    ) -> anyhow::Result<()> {
        if let Some(data) = &self.services_encrypted {
            let entries = decrypt_services(data, passphrase)?;

            self.services.extend(entries);
            self.services_encrypted = None;
        }

        Ok(())
    }

    fn try_into_final(
        mut self,
        maybe_passphrase: Option<&str>,
    ) -> TwofasResult {
        if self.is_encrypted() {
            if let Some(passphrase) = maybe_passphrase {
                self.decrypt(passphrase)?;
            } else {
                return Err(TwofasError::FileEncrypted);
            }
        }

        Ok(self.into())
    }
}

type ServicesByName = BTreeMap<String, Vec<RawTwoFactorAuthDetails>>;

#[must_use]
fn collect_services_by_name(services: &[RawTwoFactorAuthDetails]) -> ServicesByName {
    let mut services_by_name: ServicesByName = BTreeMap::new();

    for service in services.iter().cloned() {
        services_by_name
            .entry(service.name.clone())
            .or_default()
            .push(service);
    }

    services_by_name
}

type ServicesById = BTreeMap<u64, TwoFactorAuthDetails>;

#[must_use]
fn collect_services_by_id(services: &Vec<RawTwoFactorAuthDetails>) -> ServicesById {
    let mut service_by_id: ServicesById = BTreeMap::new();
    for service_raw in services {
        let service: TwoFactorAuthDetails = service_raw.clone().into();
        service_by_id.entry(service.unique_id).or_insert(service);
    }

    service_by_id
}

impl From<RawTwoFactorStorage> for TwoFactorStorage {
    /// assumes it's already decrypted. Otherwise, use `try_into_final`
    fn from(val: RawTwoFactorStorage) -> Self {
        let by_name = collect_services_by_name(&val.services);
        let by_id = collect_services_by_id(&val.services);
        let count = by_id.len();

        Self {
            services: by_id,
            services_raw: by_name,
            count,

            groups: val.groups,
            updated_at: val.updated_at,

            schema_version: val.schema_version,
            app_version_code: val.app_version_code,
            app_version_name: val.app_version_name,
            app_origin: val.app_origin,
        }
    }
}

// fn btree_keys_only<S: Serializer, K: Serialize, V>(
//     input: &BTreeMap<K, V>,
//     serializer: S,
// ) -> Result<S::Ok, S::Error> {
//     let values: Vec<&K> = input.keys().collect();
//     values.serialize(serializer)
// }

/// Usage: `#[serde(serialize_with = "btree_values_only")]`
fn btree_values_only<S: Serializer, K, V: Serialize>(
    input: &BTreeMap<K, V>,
    serializer: S,
) -> Result<S::Ok, S::Error> {
    let values: Vec<&V> = input.values().collect();
    values.serialize(serializer)
}

/// Usage: `#[serde(serialize_with = "serialize_to_string")]`
fn serialize_to_string<S: Serializer, T: ToString>(
    input: &T,
    serializer: S,
) -> Result<S::Ok, S::Error> {
    let value = input.to_string();
    value.serialize(serializer)
}

/// Represents a storage container for two-factor authentication (2FA) services.
///
/// This struct provides an organized structure for managing 2FA services and associated metadata.
/// It includes methods for querying services by ID or name, iterating over stored services, and
/// serializing or deserializing the data.
///
/// # Example
/// ```rust
/// use lib2fas::{load_services};
/// use lib2fas::TwoFactorStorage;
///
/// #[tokio::main]
/// async fn main() {
///     let result = load_services("path/to/services.2fas", Some("passphrase")).await;
///     match result {
///         Ok(storage) => {
///             // storage: TwoFactorStorage
///             println!("Loaded {} services", storage.len());
///
///             if let Some(service) = storage.first() {
///                 println!("First service: {}", service.name);
///             }
///
///             let services_named = storage.by_name("example");
///             println!("Found {} services with the name 'example'", services_named.len());
///         },
///         Err(err) => {
///             eprintln!("Failed to load services: {}", err);
///         },
///     }
/// }
/// ```
#[derive(Serialize, Debug, Clone, PartialEq, Eq, Hash, Default)]
pub struct TwoFactorStorage {
    /// A map of services indexed by their unique ID.
    #[serde(serialize_with = "btree_values_only")]
    services: BTreeMap<u64, TwoFactorAuthDetails>,
    /// A map of raw services indexed by their name.
    #[serde(skip_serializing)]
    services_raw: BTreeMap<String, Vec<RawTwoFactorAuthDetails>>,
    /// An optional list of groups associated with the services.
    groups: Option<Vec<Group>>,
    /// The timestamp (in seconds since the Unix epoch) when the storage was last updated.
    updated_at: Option<u32>,
    /// The schema version of the stored data.
    schema_version: Option<u8>,
    /// The version code of the application that created the storage.
    app_version_code: Option<i32>,
    /// The version name of the application that created the storage.
    app_version_name: Option<String>,
    /// The origin or source of the application that created the storage.
    app_origin: Option<String>,
    /// The number of services stored.
    count: usize,
}

impl TwoFactorStorage {
    /// Checks whether the storage is empty.
    ///
    /// # Returns
    /// - `true` if there are no services stored.
    /// - `false` otherwise.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.services.is_empty()
    }

    /// Retrieves the first service in the storage.
    ///
    /// # Returns
    /// - `Some(&TwoFactorAuthDetails)` if at least one service exists.
    /// - `None` if the storage is empty.
    #[must_use]
    pub fn first(&self) -> Option<&TwoFactorAuthDetails> {
        Some(self.services.first_key_value()?.1)
    }

    /// Retrieves a service by its unique ID.
    ///
    /// # Parameters
    /// - `id`: The unique ID of the service to retrieve.
    ///
    /// # Returns
    /// - `Some(&TwoFactorAuthDetails)` if the service exists.
    /// - `None` if no service is found with the given ID.
    #[must_use]
    pub fn by_id(
        &self,
        id: u64,
    ) -> Option<&TwoFactorAuthDetails> {
        self.services.get(&id)
    }

    /// Retrieves all services with the specified name.
    ///
    /// # Parameters
    /// - `name`: The name of the services to retrieve.
    ///
    /// # Returns
    /// - A vector of `TwoFactorAuthDetails` matching the given name.
    #[must_use]
    pub fn by_name(
        &self,
        name: &str,
    ) -> Vec<TwoFactorAuthDetails> {
        static DEFAULT_VEC: Vec<RawTwoFactorAuthDetails> = vec![];
        self.services_raw
            .get(name)
            .unwrap_or(&DEFAULT_VEC)
            .iter()
            .map(|it| it.clone().into())
            .collect()
    }

    fn get(
        &self,
        key: &str,
    ) -> Option<&Vec<RawTwoFactorAuthDetails>> {
        // old, use by_id or by_name instead
        self.services_raw.get(key)
    }

    /// Retrieves the first service with the specified name.
    ///
    /// # Parameters
    /// - `name`: The name of the service to retrieve.
    ///
    /// # Returns
    /// - `Some(TwoFactorAuthDetails)` if a service with the given name exists.
    /// - `None` if no service is found with the given name.
    #[must_use]
    pub fn first_by_name(
        &self,
        name: &str,
    ) -> Option<TwoFactorAuthDetails> {
        self.by_name(name).first().cloned()
    }

    /// Searches for services matching the specified query string.
    ///
    /// This method performs a fuzzy match on the service names.
    ///
    /// # Parameters
    /// - `query`: The query string to search for.
    ///
    /// # Returns
    /// - A new `TwoFactorStorage` containing only the matching services.
    #[must_use]
    pub fn find(
        &self,
        query: &str,
    ) -> Self {
        let services_by_name: BTreeMap<String, Vec<RawTwoFactorAuthDetails>>;
        let services_by_id: BTreeMap<u64, TwoFactorAuthDetails>;

        let mut count: usize = 0;

        if let Some(vec) = self.get(query) {
            services_by_name = BTreeMap::from([(query.to_owned(), vec.to_owned())]);
            services_by_id = collect_services_by_id(vec);

            count = vec.len();
        } else {
            // todo: if no services was found in key, look in values? (e.g. description/notes etc)
            let matching_services: Vec<_> = self
                .services_raw
                .clone()
                .into_iter()
                .filter_map(|(key, values)| {
                    fuzzy_match(query, key).then(|| {
                        count += values.len();
                        values
                    })
                })
                .flatten()
                .collect();
            services_by_name = collect_services_by_name(&matching_services);
            services_by_id = collect_services_by_id(&matching_services);
        }

        Self {
            services: services_by_id,
            services_raw: services_by_name,
            count,

            ..self.clone()
        }
    }

    /// Retrieves the first service matching the specified query string.
    ///
    /// This method performs a fuzzy match on the service names.
    ///
    /// # Parameters
    /// - `query`: The query string to search for.
    ///
    /// # Returns
    /// - `Some(TwoFactorAuthDetails)` if a matching service is found.
    /// - `None` if no service matches the query.
    #[must_use]
    pub fn find_first(
        &self,
        name: &str,
    ) -> Option<TwoFactorAuthDetails> {
        self.find(name).first().cloned()
    }

    /// Returns the total number of services stored.
    ///
    /// # Returns
    /// - The number of services in the storage.
    #[must_use]
    pub const fn len(&self) -> usize {
        self.count
    }

    /// Returns an iterator over the stored services.
    ///
    /// # Returns
    /// - An iterator yielding references to `TwoFactorAuthDetails`.
    #[must_use]
    pub fn iter(&self) -> TwoFactorIterator<&TwoFactorAuthDetails> {
        let values: VecDeque<_> = self.services.values().collect();
        TwoFactorIterator { values }
    }

    /// Deserializes a `TwoFactorStorage` instance from a JSON string.
    ///
    /// # Parameters
    /// - `json`: The JSON string containing the serialized storage data.
    ///
    /// # Returns
    /// - `Some(Self)` if deserialization is successful.
    /// - `TwofasError` if the deserialization fails.
    pub fn try_from_json(json: &str) -> TwofasResult {
        let raw: RawTwoFactorStorage = json5::from_str(json)?;
        raw.try_into_final(None)
    }

    /// Deserializes a `TwoFactorStorage` instance from a JSON string.
    ///
    /// # Parameters
    /// - `json`: The JSON string containing the serialized storage data.
    ///
    /// # Returns
    /// - `Some(Self)` if deserialization is successful.
    /// - `None` if the deserialization fails.
    #[must_use]
    pub fn from_json(json: &str) -> Option<Self> {
        let result: RawTwoFactorStorage = json5::from_str(json).ok()?;
        result.try_into_final(None).ok()
    }

    /// Serializes the storage to a JSON string.
    ///
    /// # Returns
    /// - `Some(String)` containing the serialized JSON representation.
    /// - `None` if serialization fails.
    #[must_use]
    pub fn to_json(&self) -> Option<String> {
        json5::to_string(self).ok()
    }
}

/// Iterator for two-factor authentication services.
///
/// This struct provides an iterator for traversing the services stored in a `TwoFactorStorage` instance.
///
/// # Example
/// ```rust
/// use lib2fas::{load_services, TwoFactorStorage};
///
/// #[tokio::main]
/// async fn main() {
///     let result = load_services("path/to/services.2fas", Some("passphrase")).await;
///     if let Ok(storage) = result {
///         for service in storage.iter() {
///             println!("Service Name: {}", service.name);
///         }
///     }
/// }
/// ```
pub struct TwoFactorIterator<T> {
    values: VecDeque<T>,
}

impl<T> Iterator for TwoFactorIterator<T> {
    type Item = T;

    fn next(&mut self) -> Option<Self::Item> {
        self.values.pop_front()
    }
}

impl IntoIterator for TwoFactorStorage {
    type Item = TwoFactorAuthDetails;
    type IntoIter = TwoFactorIterator<Self::Item>;

    fn into_iter(self) -> Self::IntoIter {
        let values: VecDeque<_> = self.services.into_values().collect();
        Self::IntoIter { values }
    }
}

impl<'tfs> IntoIterator for &'tfs TwoFactorStorage {
    type Item = &'tfs TwoFactorAuthDetails;
    type IntoIter = TwoFactorIterator<&'tfs TwoFactorAuthDetails>;
    fn into_iter(self) -> Self::IntoIter {
        self.iter()
    }
}

/// Errors that can occur while using the `lib2fas` library.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, PartialOrd, Ord, Eq, Hash)]
#[non_exhaustive]
pub enum TwofasError {
    /// Indicates that the file is encrypted but no passphrase was provided.
    FileEncrypted,
    /// Represents other errors with a description of the problem.
    Other(String),
}

#[expect(
    clippy::min_ident_chars,
    reason = "compatibility with `std::fmt::Display.fmt`"
)]
impl core::fmt::Display for TwofasError {
    fn fmt(
        &self,
        f: &mut Formatter<'_>,
    ) -> core::fmt::Result {
        match self {
            Self::FileEncrypted => {
                write!(f, "File is encrypted but no passphrase was provided!")
            },
            Self::Other(err) => {
                write!(f, "{err}")
            },
        }
    }
}

impl From<anyhow::Error> for TwofasError {
    fn from(value: anyhow::Error) -> Self {
        Self::Other(value.to_string())
    }
}

impl From<std::io::Error> for TwofasError {
    fn from(value: std::io::Error) -> Self {
        Self::Other(format!("file read error: {value}"))
    }
}

impl From<json5::Error> for TwofasError {
    fn from(value: json5::Error) -> Self {
        Self::Other(format!("json decode error: {value}"))
    }
}

type TwofasResult = Result<TwoFactorStorage, TwofasError>;

/// Loads and parses two-factor authentication services from a given 2fas file.
///
/// # Overview
/// `load_services` serves as the main entry point for the `lib2fas` library. It reads a file containing
/// two-factor authentication service details (potentially encrypted), parses its content, and
/// returns a structured representation of the services.
///
/// If the file is encrypted, a passphrase must be provided to decrypt and load the data.
///
/// # Parameters
/// - `filename`: The path to the 2fas file containing the two-factor authentication services.
///   This can be any type that implements `Into<PathBuf>`.
/// - `passphrase`: An optional passphrase used to decrypt the file if it's encrypted. If the file
///   is encrypted and no passphrase is provided, an error will be returned.
///
/// # Returns
/// - `Ok(TwoFactorStorage)`: A structured representation of the two-factor services, including
///   service details, groups, metadata, and additional attributes.
/// - `Err(TwofasError)`: An error indicating the reason for failure, such as file I/O issues,
///   parsing errors, or missing decryption passphrase for encrypted files.
///
/// # Errors
/// - Returns `TwofasError::FileEncrypted` if the file is encrypted but no passphrase is provided.
/// - Returns `TwofasError::Other` for other issues, such as file read errors or invalid content.
///
/// # Example
/// ```rust
/// async fn example() {
///     use lib2fas::load_services;
///
///     let result = load_services("path/to/services.2fas", Some("passphrase")).await;
///     match result {
///         Ok(storage) => {
///             println!("Loaded {} services", storage.len());
///         },
///         Err(err) => {
///             eprintln!("Failed to load services: {}", err);
///         },
///     }
/// }
/// ```
///
/// # See Also
/// The [`TwoFactorStorage`](struct.TwoFactorStorage.html) struct contains methods for interacting
/// with the loaded two-factor authentication services, such as querying by name or ID, and
/// iterating over the stored services.
///
/// # Note
/// This function is asynchronous and should be awaited to complete its execution.
/// You can use `load_services_blocking` if you can't use async.
pub async fn load_services<P: Into<PathBuf>>(
    filename: P,
    passphrase: Option<&str>,
) -> TwofasResult {
    use tokio::fs::File;
    use tokio::io::BufReader;

    let file = File::open(filename.into())
        .await
        .map_err(TwofasError::from)?;

    let reader = BufReader::new(file);

    let result: RawTwoFactorStorage = json5_from_reader_async(reader).await?;

    result.try_into_final(passphrase)
}

/// Blocking variant of `load_services`.
pub fn load_services_blocking<P: Into<PathBuf>>(
    filename: P,
    passphrase: Option<&str>,
) -> TwofasResult {
    use std::fs::File;
    use std::io::BufReader;

    let file = File::open(filename.into()).map_err(TwofasError::from)?;
    let reader = BufReader::new(file);

    let result: RawTwoFactorStorage = json5_from_reader(reader)?;

    result.try_into_final(passphrase)
}