//! POD types for the system-keyring surface

//! (SUPER_PLAN_2 §4 P4.2 + research/02 §0 "hardware-bound" storage).

//!

//! A biometry-bindable secret key/value store backed by the OS keyring:

//! iOS/macOS Keychain (`SecItem*`, optionally `kSecAttrAccessControl =

//! biometryCurrentSet`), Android `KeyStore` (`setUserAuthenticationRequired`),

//! Linux libsecret, Windows `CredentialLocker`. Defined here in `azul-core`

//! so the request/result types cross the FFI without `azul-layout` being a

//! dependency; the stateful side lives in

//! `azul_layout::managers::keyring::KeyringManager`.

//!

//! Request-driven and channel-delivered, mirroring biometric ([`crate::

//! biometric`]): a `Get` of a biometry-bound item shows the OS prompt and

//! resolves asynchronously, so *every* op resolves through the result

//! channel for a uniform, engine-agnostic surface. One op is in flight at

//! a time (the demo reveals one entry at a time); request↔result

//! correlation by id is a future refinement.

use azul_css::AzString;

/// A keyring operation queued by a callback

/// (`CallbackInfo::keyring_store` / `keyring_get` / `keyring_delete`) and

/// dispatched to the platform backend by the layout pass.

///

/// `secret` is an [`AzString`] — the common case is a password / token;

/// binary blobs are base64-encoded by the caller. `key` is the lookup

/// name, scoped to the app's keyring service.

#[repr(C, u8)]

#[derive(Debug, Clone, PartialEq, Eq)]

pub enum KeyringRequest {

    /// Write `secret` under `key`, overwriting any existing value. When

    /// `require_biometry` is set the item is stored access-controlled so a

    /// later `Get` triggers the OS biometric prompt (Keychain

    /// `biometryCurrentSet` / `KeyStore` `setUserAuthenticationRequired`).

    Store {

        key: AzString,

        secret: AzString,

        require_biometry: bool,

    },

    /// Read the secret stored under `key`. For a biometry-bound item the

    /// OS shows its auth prompt first; the result arrives asynchronously.

    Get { key: AzString },

    /// Remove the item stored under `key` (no-op if absent).

    Delete { key: AzString },

}

#[allow(variant_size_differences)] // repr(C,u8) FFI enum: boxing the large variant would change the C ABI (api.json bindings); size disparity accepted

/// The outcome of a [`KeyringRequest`], delivered to the result channel

/// and read by callbacks via `CallbackInfo::get_keyring_result()`.

#[repr(C, u8)]

#[derive(Debug, Clone, PartialEq, Eq)]

pub enum KeyringResult {

    /// A `Store` succeeded.

    Stored,

    /// A `Get` returned the secret.

    Retrieved(AzString),

    /// A `Delete` succeeded (the key is now absent).

    Deleted,

    /// The requested key was not present in the keyring.

    NotFound,

    /// A biometry-bound read was refused — the user failed or cancelled

    /// the OS auth prompt.

    Denied,

    /// No keyring backend is available on this platform / it isn't

    /// configured (e.g. Linux without a running secret service).

    Unavailable,

    /// A platform error occurred (locked keychain, I/O, unmapped code).

    Error,

}

impl KeyringResult {

    /// The retrieved secret, if this is a successful `Get`.

        }

    /// `true` for the success outcomes (`Stored` / `Retrieved` / `Deleted`).

            Self::Stored | Self::Retrieved(_) | Self::Deleted

        )

}

// FFI Option wrapper for `CallbackInfo::get_keyring_result() ->

// Option<KeyringResult>` — `None` until the first op completes. Not Copy

// (carries an `AzString` in `Retrieved`), so `copy = false` (mirrors

// `OptionNodeType`).

impl_option!(

    KeyringResult,

    OptionKeyringResult,

    copy = false,

    [Debug, Clone, PartialEq, Eq]

);

#[cfg(test)]

mod autotest_generated {

    use super::*;

    use alloc::string::String;

    // Payloads chosen to break naive C-string / byte-length assumptions in the

    // FFI layer: interior NUL, C0/C1 controls, CRLF.

    const NASTY_BYTES: &str = "pw\0with\u{1}nul\u{7f}\r\n\t";

    // Combining marks, RTL overrides, replacement char and the maximum scalar.

    const NASTY_UNICODE: &str = "🔑🗝 ключ 鍵 مفتاح e\u{301}\u{202e}terces\u{202c}\u{fffd}\u{10ffff}";

    /// Every `KeyringResult` variant, in declaration order.

    fn all_variants() -> [KeyringResult; 7] {

        [

            KeyringResult::Stored,

            KeyringResult::Retrieved(AzString::from("s3cr3t")),

            KeyringResult::Deleted,

            KeyringResult::NotFound,

            KeyringResult::Denied,

            KeyringResult::Unavailable,

            KeyringResult::Error,

        ]

    }

    /// The documented contract, restated independently of the impl:

    /// `(is_ok, has_secret)`. The exhaustive match is deliberate — adding a

    /// variant to `KeyringResult` breaks this and forces the truth tables

    /// below to be revisited rather than silently under-testing the new one.

    fn expected(r: &KeyringResult) -> (bool, bool) {

        match r {

            KeyringResult::Stored => (true, false),

            KeyringResult::Retrieved(_) => (true, true),

            KeyringResult::Deleted => (true, false),

            KeyringResult::NotFound => (false, false),

            KeyringResult::Denied => (false, false),

            KeyringResult::Unavailable => (false, false),

            KeyringResult::Error => (false, false),

        }

    }

    // ---- getter: KeyringResult::secret ------------------------------------

    #[test]

    fn secret_returns_the_exact_payload_of_retrieved() {

        let r = KeyringResult::Retrieved(AzString::from("hunter2"));

        assert_eq!(r.secret().expect("Retrieved must yield a secret").as_str(), "hunter2");

    }

    #[test]

    fn secret_is_none_for_every_non_retrieved_variant() {

        for r in &all_variants() {

            let has_secret = expected(r).1;

            assert_eq!(

                r.secret().is_some(),

                has_secret,

                "secret() disagrees with the documented contract for {r:?}"

            );

        }

    }

    #[test]

    fn secret_of_an_empty_payload_is_some_empty_not_none() {

        // An empty secret is a *present* secret. Collapsing it to `None` would

        // make a stored-empty-string indistinguishable from `NotFound`.

        let r = KeyringResult::Retrieved(AzString::from(""));

        assert_eq!(r.secret().expect("empty payload is still a payload").as_str(), "");

        assert!(r.is_ok());

        let d = KeyringResult::Retrieved(AzString::default());

        assert_eq!(d.secret().expect("default payload is still a payload").as_str(), "");

        assert!(d.is_ok());

    }

    #[test]

    fn secret_preserves_interior_nul_and_control_bytes() {

        let r = KeyringResult::Retrieved(AzString::from(NASTY_BYTES));

        let s = r.secret().expect("Retrieved must yield a secret");

        assert_eq!(s.as_str(), NASTY_BYTES);

        // Byte-exact: nothing truncated at the NUL, nothing re-encoded.

        assert_eq!(s.as_str().as_bytes(), NASTY_BYTES.as_bytes());

        assert_eq!(s.as_str().len(), NASTY_BYTES.len());

    }

    #[test]

    fn secret_preserves_multibyte_and_max_scalar_boundaries() {

        let r = KeyringResult::Retrieved(AzString::from(NASTY_UNICODE));

        let s = r.secret().expect("Retrieved must yield a secret");

        // `AzString::as_str` is `from_utf8_unchecked`, so a byte-level mangling

        // here would be UB rather than a clean error — assert byte equality.

        assert_eq!(s.as_str(), NASTY_UNICODE);

        assert_eq!(s.as_str().as_bytes(), NASTY_UNICODE.as_bytes());

        assert_eq!(s.as_str().chars().count(), NASTY_UNICODE.chars().count());

        assert!(s.as_str().ends_with('\u{10ffff}'));

    }

    #[test]

    fn secret_handles_a_megabyte_payload() {

        let big = "k".repeat(1 << 20);

        let r = KeyringResult::Retrieved(AzString::from(big.clone()));

        let s = r.secret().expect("Retrieved must yield a secret");

        assert_eq!(s.as_str().len(), 1 << 20);

        assert_eq!(s.as_str(), big.as_str());

        assert!(r.is_ok());

    }

    #[test]

    fn secret_borrows_the_payload_in_place_and_is_repeatable() {

        let r = KeyringResult::Retrieved(AzString::from("borrow-me"));

        let inner: &AzString = match &r {

            KeyringResult::Retrieved(s) => s,

            other => unreachable!("constructed Retrieved, got {other:?}"),

        };

        let first = r.secret().expect("Retrieved must yield a secret");

        assert!(

            core::ptr::eq(first, inner),

            "secret() must borrow the payload, not hand back a copy"

        );

        // Repeated calls are stable: same AzString, same backing buffer.

        let second = r.secret().expect("secret() must be repeatable");

        assert!(core::ptr::eq(first, second));

        assert_eq!(first.as_str().as_ptr(), second.as_str().as_ptr());

    }

    // ---- predicate: KeyringResult::is_ok ----------------------------------

    #[test]

    fn is_ok_truth_table_is_exhaustive() {

        for r in &all_variants() {

            let want = expected(r).0;

            assert_eq!(r.is_ok(), want, "is_ok() wrong for {r:?}");

        }

        // Spelled out as well, so a mis-edited `expected()` can't hide a bug.

        assert!(KeyringResult::Stored.is_ok());

        assert!(KeyringResult::Retrieved(AzString::from("x")).is_ok());

        assert!(KeyringResult::Deleted.is_ok());

        assert!(!KeyringResult::NotFound.is_ok());

        assert!(!KeyringResult::Denied.is_ok());

        assert!(!KeyringResult::Unavailable.is_ok());

        assert!(!KeyringResult::Error.is_ok());

    }

    #[test]

    fn is_ok_is_independent_of_the_retrieved_payload() {

        let payloads = [

            String::new(),

            String::from(NASTY_BYTES),

            String::from(NASTY_UNICODE),

            "a".repeat(100_000),

        ];

        for p in payloads {

            assert!(

                KeyringResult::Retrieved(AzString::from(p)).is_ok(),

                "Retrieved is a success outcome whatever it carries"

            );

        }

    }

    #[test]

    fn is_ok_and_secret_never_contradict_each_other() {

        for r in &all_variants() {

            // A secret can only come from a success; a failure never carries one.

            if r.secret().is_some() {

                assert!(r.is_ok(), "{r:?} yielded a secret but reports failure");

            }

            if !r.is_ok() {

                assert!(r.secret().is_none(), "failure {r:?} yielded a secret");

            }

        }

    }

    #[test]

    fn accessors_are_pure() {

        for r in &all_variants() {

            let before = r.clone();

            for _ in 0..8 {

                assert_eq!(r.is_ok(), before.is_ok());

                assert_eq!(r.secret().is_some(), before.secret().is_some());

            }

            assert_eq!(*r, before, "accessors must not mutate the receiver");

        }

    }

    // ---- clone/drop: AzString carries an FFI destructor ------------------

    #[test]

    fn dropping_a_clone_leaves_the_original_payload_readable() {

        let payload = "🔐 secret-that-must-survive";

        let original = KeyringResult::Retrieved(AzString::from(payload));

        for _ in 0..1000 {

            let c = original.clone();

            assert_eq!(c.secret().expect("clone keeps the payload").as_str(), payload);

            // A shallow clone would free the original's buffer right here.

            drop(c);

        }

        assert_eq!(

            original.secret().expect("original survives 1000 clone/drop cycles").as_str(),

            payload

        );

        assert!(original.is_ok());

    }

    #[test]

    fn dropping_the_original_leaves_the_clone_payload_readable() {

        let payload = NASTY_UNICODE;

        let original = KeyringResult::Retrieved(AzString::from(payload));

        let clone = original.clone();

        drop(original);

        assert_eq!(clone.secret().expect("clone owns its payload").as_str(), payload);

    }

    #[test]

    fn eq_is_sensitive_to_both_variant_and_payload() {

        assert_eq!(

            KeyringResult::Retrieved(AzString::from("a")),

            KeyringResult::Retrieved(AzString::from("a"))

        );

        assert_ne!(

            KeyringResult::Retrieved(AzString::from("a")),

            KeyringResult::Retrieved(AzString::from("b"))

        );

        // Empty payload must not compare equal to a payload-less success.

        assert_ne!(KeyringResult::Retrieved(AzString::from("")), KeyringResult::Stored);

        assert_ne!(KeyringResult::NotFound, KeyringResult::Denied);

        assert_ne!(KeyringResult::Unavailable, KeyringResult::Error);

        assert_eq!(KeyringResult::Deleted, KeyringResult::Deleted);

    }

    // ---- round-trip: OptionKeyringResult FFI wrapper ----------------------

    #[test]

    fn option_wrapper_round_trips_none_and_every_variant() {

        let none: OptionKeyringResult = Option::<KeyringResult>::None.into();

        assert!(none.is_none());

        assert_eq!(Option::<KeyringResult>::from(none), None);

        assert!(OptionKeyringResult::default().is_none());

        for r in all_variants() {

            let wrapped: OptionKeyringResult = Some(r.clone()).into();

            let back: Option<KeyringResult> = wrapped.into();

            assert_eq!(back, Some(r), "encode/decode through OptionKeyringResult lost data");

        }

    }

    #[test]

    fn option_wrapper_accessors_agree_with_each_other() {

        let payload = "round-trip-me";

        let some = OptionKeyringResult::Some(KeyringResult::Retrieved(AzString::from(payload)));

        assert!(some.is_some());

        assert!(!some.is_none());

        assert_eq!(

            some.as_option().and_then(KeyringResult::secret).map(AzString::as_str),

            Some(payload)

        );

        assert_eq!(some.as_ref(), some.as_option());

        let none = OptionKeyringResult::None;

        assert!(none.is_none());

        assert!(!none.is_some());

        assert!(none.as_option().is_none());

    }

    #[test]

    fn option_wrapper_into_option_clones_and_leaves_the_wrapper_intact() {

        // `into_option(&self)` takes a reference and clones — calling it twice

        // must not double-free or hollow out the wrapper.

        let payload = NASTY_BYTES;

        let wrapped = OptionKeyringResult::Some(KeyringResult::Retrieved(AzString::from(payload)));

        let first = wrapped.into_option().expect("Some stays Some");

        let second = wrapped.into_option().expect("into_option must not consume the wrapper");

        assert_eq!(first, second);

        assert_eq!(first.secret().expect("payload survives").as_str(), payload);

        drop(first);

        assert_eq!(second.secret().expect("payload survives its sibling").as_str(), payload);

        drop(second);

        assert_eq!(

            wrapped.as_option().and_then(KeyringResult::secret).map(AzString::as_str),

            Some(payload),

            "wrapper must still own its payload after both clones died"

        );

    }

    #[test]

    fn option_wrapper_replace_returns_the_previous_value() {

        let mut o = OptionKeyringResult::None;

        assert_eq!(o.replace(KeyringResult::Stored), OptionKeyringResult::None);

        let prev = o.replace(KeyringResult::Retrieved(AzString::from("new")));

        assert_eq!(prev, OptionKeyringResult::Some(KeyringResult::Stored));

        assert_eq!(

            o.as_option().and_then(KeyringResult::secret).map(AzString::as_str),

            Some("new")

        );

    }

    #[test]

    fn option_wrapper_as_mut_can_overwrite_a_retrieved_payload() {

        let mut o = OptionKeyringResult::Some(KeyringResult::Retrieved(AzString::from("old")));

        if let Some(slot) = o.as_mut() {

            *slot = KeyringResult::Deleted; // drops the old AzString in place

        }

        assert_eq!(o.as_option(), Some(&KeyringResult::Deleted));

        assert!(o.as_option().expect("still Some").is_ok());

        assert!(o.as_option().expect("still Some").secret().is_none());

    }

    // ---- KeyringRequest: payload-carrying FFI enum ------------------------

    #[test]

    fn request_equality_is_sensitive_to_key_secret_and_biometry_flag() {

        let store = KeyringRequest::Store {

            key: AzString::from("k"),

            secret: AzString::from("s"),

            require_biometry: false,

        };

        assert_eq!(store, store.clone());

        assert_ne!(

            store,

            KeyringRequest::Store {

                key: AzString::from("k"),

                secret: AzString::from("s"),

                require_biometry: true,

            },

            "require_biometry changes the stored access control — it must not be ignored"

        );

        assert_ne!(

            store,

            KeyringRequest::Store {

                key: AzString::from("k"),

                secret: AzString::from("other"),

                require_biometry: false,

            }

        );

        assert_ne!(

            KeyringRequest::Get { key: AzString::from("k") },

            KeyringRequest::Delete { key: AzString::from("k") },

            "a read and a delete of the same key are different operations"

        );

        assert_ne!(

            KeyringRequest::Get { key: AzString::from("a") },

            KeyringRequest::Get { key: AzString::from("b") }

        );

    }

    #[test]

    fn request_payloads_survive_clone_and_drop() {

        let key = "🔑".repeat(10_000);

        let req = KeyringRequest::Store {

            key: AzString::from(key.clone()),

            secret: AzString::from(NASTY_BYTES),

            require_biometry: true,

        };

        let clone = req.clone();

        drop(req);

        match &clone {

            KeyringRequest::Store { key: k, secret: s, require_biometry } => {

                assert_eq!(k.as_str(), key.as_str());

                assert_eq!(s.as_str(), NASTY_BYTES);

                assert!(*require_biometry);

            }

            other => unreachable!("constructed Store, got {other:?}"),

        }

    }

    #[test]

    fn request_accepts_empty_keys_without_panicking() {

        // An empty key is nonsense to a backend, but the POD type must still

        // construct, compare and drop cleanly rather than blow up in the callback.

        let empty = KeyringRequest::Get { key: AzString::from("") };

        assert_eq!(empty, KeyringRequest::Get { key: AzString::default() });

        assert_ne!(empty, KeyringRequest::Get { key: AzString::from("k") });

    }

}