hiss 0.4.0

//! macOS Secure Enclave P-256 private key implementation.
//!
//! Delegates key generation, ECDSA signing, and ECDH to Apple's
//! Security framework. Private keys live in the Secure Enclave (or
//! in a software-backed `SecKey` for ephemeral use) and never leave
//! hardware. ECDH uses `kSecKeyAlgorithmECDHKeyExchangeStandard`
//! which returns the raw x-coordinate — Noise-spec compliant.
//!
//! Three key generation modes are available:
//!
//! * [`P256r1PrivateKey::generate_ephemeral`] — software-backed
//!   `SecKey`, not persisted in the Keychain. Suitable for Noise
//!   handshake ephemeral keys.
//!
//! * [`P256r1PrivateKey::generate_secure_enclave_ephemeral`] —
//!   hardware-backed, no per-use biometric prompt, not persisted.
//!
//! * [`P256r1PrivateKey::generate_secure_enclave`] — hardware-backed and
//!   persisted, so the key outlives the process and is recovered later
//!   with [`P256r1PrivateKey::load_from_keychain`]. This is the mode a
//!   long-term Noise static key uses, and the one with setup
//!   requirements — see below.
//!
//! # What a persistent enclave key requires
//!
//! [`generate_secure_enclave`](P256r1PrivateKey::generate_secure_enclave)
//! and [`load_from_keychain`](P256r1PrivateKey::load_from_keychain) only
//! succeed inside an application that has been set up for them. Nothing
//! in this crate can arrange that for you; get it wrong and the calls
//! fail at run time.
//!
//! * **The key is generated into the Data Protection Keychain.**
//!   Apple's technote TN3137 requires it: a key held in the Secure
//!   Enclave must use that keychain, and a `SecItem` call targets the
//!   older file-based keychain unless `kSecUseDataProtectionKeychain`
//!   or `kSecAttrSynchronizable` is set. The generate path sets it; the
//!   load path does not — it pins `kSecAttrTokenIDSecureEnclave`, so a
//!   software key can never be substituted for the hardware one, but it
//!   sets no data-protection selector, leaving the query targeting the
//!   file-based keychain. No test covers the persistent path — it needs
//!   the entitlement below and real hardware — so its behaviour on
//!   device is unverified.
//! * **On macOS, reaching that keychain needs an entitlement.** The
//!   binary must carry a team-prefixed `keychain-access-groups`
//!   entitlement, authorised by a provisioning profile embedded in the
//!   application — the host application's build script places the
//!   profile alongside the binary and signs with it. An unsigned
//!   `cargo run` does not have this. On iOS the same entitlement comes
//!   from ordinary app signing.
//! * **The device must have been unlocked at least once since boot.**
//!   Keys are created `AccessibleAfterFirstUnlockThisDeviceOnly`, so
//!   they are unavailable before first unlock, never leave the device,
//!   and are not in any backup or iCloud Keychain copy. A lost device
//!   is a lost key; plan re-enrolment, not recovery.

use crate::curve::SharedSecret;
use crate::curve::ed25519::{
    Ed25519, Ed25519PublicKey, Ed25519Signature, SoftwareEd25519PrivateKey,
};
use crate::curve::p256::{Error, P256, P256Signature, P256r1PublicKey};
use crate::noise::seal::{SEALED_SIZE, open_32, seal_32};
use crate::provider::{
    CryptoKeyProvider, CryptoKeyProviderAsync, DhProvider, DhProviderAsync, SigningProvider,
    SigningProviderAsync,
};
use core_foundation::{base::TCFType as _, data::CFData, dictionary::CFDictionary};
use security_framework::{
    access_control::{ProtectionMode, SecAccessControl},
    item::Location,
    key::{Algorithm, GenerateKeyOptions, KeyType, SecKey, Token},
    passwords::{
        PasswordOptions, delete_generic_password_options, generic_password,
        set_generic_password_options,
    },
    passwords_options::AccessControlOptions,
};

/// Keychain label for ephemeral P-256 keys.
///
/// Ephemeral keys are never persisted or looked up by label, so this is
/// a fixed, namespace-independent descriptor.
const EPHEMERAL_LABEL: &str = "hiss.ephemeral.p256";

/// Keychain account for the sealed Ed25519 seed item. A neutral
/// descriptor — the per-caller namespace lives in the service name.
const ED25519_SEED_ACCOUNT: &str = "device-identity";

/// Handle to a P-256 private key managed by Apple's Security framework.
///
/// The handle wraps a `SecKey`; the private scalar itself is never held
/// in process memory. For Secure-Enclave-backed keys the scalar is
/// non-extractable and every operation ([`dh`](Self::dh),
/// [`sign`](Self::sign)) runs inside the enclave; for the software-backed
/// ephemeral variant ([`generate_ephemeral`](Self::generate_ephemeral))
/// the scalar lives in a software `SecKey` and never crosses the FFI
/// boundary either. `deletable` records whether the key was persisted to
/// the Keychain and so is removable by [`delete`](Self::delete);
/// non-persisted (ephemeral) keys are not.
//
// `Clone` here is a CoreFoundation retain of the `SecKey` handle — no
// secret material is copied (the key stays in the keychain / Secure
// Enclave). The trait deliberately does not mandate `Clone`; this type
// offers it because a retain is cheap and callers hold handles, not keys.
#[derive(Clone)]
pub struct P256r1PrivateKey {
    key: SecKey,
    deletable: bool,
}

impl P256r1PublicKey {
    fn as_sec_key(&self, attributes: &CFDictionary) -> Result<SecKey, Error> {
        let key_data = CFData::from_buffer(self.to_bytes());
        // SAFETY: `key_data` and `attributes` are live `CFData`/`CFDictionary`
        // values owned by this scope, so the `CFTypeRef`s passed by
        // `as_concrete_TypeRef` stay valid for the whole call. `error` is a
        // null-initialised out-param whose address is a valid `*mut CFErrorRef`.
        // `SecKeyCreateWithData` follows Core Foundation's Create rule: the
        // returned `SecKeyRef` is owned by us (not borrowed/Get), so it is taken
        // with `wrap_under_create_rule` whose `Drop` releases it exactly once. On
        // a null return the written-back `CFError` is likewise Create-owned and
        // wrapped under the create rule, balancing its retain count.
        unsafe {
            let mut error = std::ptr::null_mut();

            let sec_key = security_framework_sys::key::SecKeyCreateWithData(
                key_data.as_concrete_TypeRef(),
                attributes.as_concrete_TypeRef(),
                &mut error,
            );

            if sec_key.is_null() {
                let cf_error = core_foundation::error::CFError::wrap_under_create_rule(error);
                Err(Error::Platform(format!("{cf_error:?}")))
            } else {
                Ok(SecKey::wrap_under_create_rule(sec_key))
            }
        }
    }
}

impl P256r1PrivateKey {
    fn new(key: SecKey, deletable: bool) -> Self {
        Self { key, deletable }
    }

    /// Generate a software-backed ephemeral P-256 key.
    ///
    /// The key is created with `Token::Software` and is never persisted
    /// to the Keychain — it lives only for the lifetime of this handle and
    /// is dropped with it. There is no Secure Enclave involvement and no
    /// authentication prompt. Suitable for Noise handshake ephemeral keys,
    /// which are used once and discarded; for a hardware-backed key see
    /// [`generate_secure_enclave_ephemeral`](Self::generate_secure_enclave_ephemeral).
    pub fn generate_ephemeral() -> Result<Self, Error> {
        let mut attributes = GenerateKeyOptions::default();
        attributes
            .set_key_type(KeyType::ec())
            .set_size_in_bits(256)
            .set_token(Token::Software)
            .set_label(EPHEMERAL_LABEL);

        let key = SecKey::new(&attributes)
            .map_err(|e| Error::Platform(format!("failed to generate SecKey: {e:?}")))?;
        Ok(Self::new(key, false))
    }

    /// Generate an ephemeral Secure Enclave key.
    ///
    /// No per-use biometric prompt — same access control as persistent keys.
    pub fn generate_secure_enclave_ephemeral() -> Result<Self, Error> {
        let mut attributes = GenerateKeyOptions::default();
        attributes
            .set_key_type(KeyType::ec())
            .set_size_in_bits(256)
            .set_token(Token::SecureEnclave)
            .set_label(EPHEMERAL_LABEL)
            .set_access_control(
                SecAccessControl::create_with_protection(
                    Some(ProtectionMode::AccessibleAfterFirstUnlockThisDeviceOnly),
                    AccessControlOptions::PRIVATE_KEY_USAGE.bits(),
                )
                .map_err(|e| Error::Platform(format!("access control: {e}")))?,
            );

        let key = SecKey::new(&attributes)
            .map_err(|e| Error::Platform(format!("failed to generate SecKey: {e:?}")))?;
        Ok(Self::new(key, false))
    }

    /// Generate a persistent Secure Enclave key stored in the Keychain.
    ///
    /// Access control: `PRIVATE_KEY_USAGE` only — no per-use biometric
    /// prompt. The app-level lock screen provides the authentication gate.
    /// `AccessibleAfterFirstUnlockThisDeviceOnly` ensures the key is
    /// available once the device has been unlocked after boot.
    ///
    /// The key goes into the Data Protection Keychain, which the host
    /// application must be entitled to reach — see "What a persistent
    /// enclave key requires" in the [module documentation](self).
    pub fn generate_secure_enclave(label: &str) -> Result<Self, Error> {
        let mut attributes = GenerateKeyOptions::default();
        attributes
            .set_key_type(KeyType::ec())
            .set_size_in_bits(256)
            .set_label(label)
            .set_token(Token::SecureEnclave)
            // Phase 18.1 (`2026/05/12`): the data-protection Keychain
            // selector is RESTORED (D-20-restored) per Apple TN3137
            // ("Keys stored in the Secure Enclave _must_ use this
            // keychain"). Authorisation for the team-prefixed
            // `keychain-access-groups` entitlement is provided by the
            // embedded macOS Development provisioning profile bundled
            // alongside the binary by the host application's build
            // script (D-27.c). The prior 2026/05/08 drop-the-selector
            // experiment and the 2026/05/10 file-based-seed direction
            // both failed empirically (see VERIFICATION.md F-2, F-4, F-5,
            // F-5.A); CONTEXT.md Amendment 2026/05/12 restores the
            // canonical D-04 path.
            .set_location(Location::DataProtectionKeychain)
            .set_access_control(
                SecAccessControl::create_with_protection(
                    Some(ProtectionMode::AccessibleAfterFirstUnlockThisDeviceOnly),
                    AccessControlOptions::PRIVATE_KEY_USAGE.bits(),
                )
                .map_err(|e| Error::Platform(format!("access control: {e}")))?,
            );

        let key = SecKey::new(&attributes)
            .map_err(|e| Error::Platform(format!("failed to generate SecKey: {e:?}")))?;
        Ok(Self::new(key, true))
    }

    /// Load a previously persisted Secure Enclave key from the Keychain.
    ///
    /// Queries the Keychain for a key matching `label` (stored under
    /// `kSecAttrLabel` by
    /// [`generate_secure_enclave`](Self::generate_secure_enclave)). Returns `None`
    /// if no key is found.
    ///
    /// The query pins `kSecAttrTokenIDSecureEnclave`, so a software key
    /// can never be returned in place of the hardware one. Unlike
    /// [`generate_secure_enclave`](Self::generate_secure_enclave) it
    /// sets no `kSecUseDataProtectionKeychain` selector, and by Apple's
    /// TN3137 a `SecItem` call without one targets the file-based
    /// keychain rather than the Data Protection Keychain the key was
    /// written to. No test covers this path — it needs real hardware
    /// plus the entitlement described under "What a persistent enclave
    /// key requires" in the [module documentation](self) — so its
    /// behaviour on device is unverified.
    pub fn load_from_keychain(label: &str) -> Result<Option<Self>, Error> {
        use core_foundation::base::TCFType as _;
        use core_foundation::boolean::CFBoolean;
        use core_foundation::string::CFString;
        use security_framework_sys::item::{
            kSecAttrKeyClass, kSecAttrKeyClassPrivate, kSecAttrKeyType,
            kSecAttrKeyTypeECSECPrimeRandom, kSecAttrLabel, kSecAttrTokenID,
            kSecAttrTokenIDSecureEnclave, kSecClass, kSecClassKey, kSecReturnRef,
        };
        use security_framework_sys::keychain_item::SecItemCopyMatching;

        let label = CFString::new(label);

        // SAFETY: every key/value in `query` is wrapped under the Get rule from
        // a static `kSec*` constant (or an owned `CFString`/`CFBoolean`), so the
        // dictionary holds only valid, live `CFType`s for the duration of the
        // call. `result` is a null-initialised `CFTypeRef` out-param whose
        // address is a valid `*mut CFTypeRef`. `SecItemCopyMatching` reads
        // `query` and, only on `errSecSuccess`, writes back a Create-rule-owned
        // object (we requested `kSecReturnRef`); that object is taken exactly
        // once with `wrap_under_create_rule`, so its `Drop` releases it. The
        // not-found and error status paths return before touching `result`,
        // which is left null.
        unsafe {
            let query = CFDictionary::from_CFType_pairs(&[
                (
                    CFString::wrap_under_get_rule(kSecClass),
                    CFString::wrap_under_get_rule(kSecClassKey).as_CFType(),
                ),
                (
                    CFString::wrap_under_get_rule(kSecAttrKeyType),
                    CFString::wrap_under_get_rule(kSecAttrKeyTypeECSECPrimeRandom).as_CFType(),
                ),
                (
                    CFString::wrap_under_get_rule(kSecAttrKeyClass),
                    CFString::wrap_under_get_rule(kSecAttrKeyClassPrivate).as_CFType(),
                ),
                (
                    CFString::wrap_under_get_rule(kSecAttrLabel),
                    label.as_CFType(),
                ),
                (
                    CFString::wrap_under_get_rule(kSecAttrTokenID),
                    CFString::wrap_under_get_rule(kSecAttrTokenIDSecureEnclave).as_CFType(),
                ),
                (
                    CFString::wrap_under_get_rule(kSecReturnRef),
                    CFBoolean::true_value().as_CFType(),
                ),
            ]);

            let mut result: core_foundation::base::CFTypeRef = std::ptr::null();
            let status = SecItemCopyMatching(query.as_concrete_TypeRef(), &mut result);

            if status == security_framework_sys::base::errSecItemNotFound {
                return Ok(None);
            }
            if status != security_framework_sys::base::errSecSuccess {
                return Err(Error::Platform(format!(
                    "Keychain query failed with status {status}"
                )));
            }

            let key = SecKey::wrap_under_create_rule(result as *mut _);
            Ok(Some(Self::new(key, true)))
        }
    }

    /// Derive the P-256 public key for this private key.
    ///
    /// Reads the public key from the `SecKey` and returns its uncompressed
    /// external representation. This is a local accessor — the public
    /// point is always available to the framework, so it incurs no Secure
    /// Enclave round-trip and no authentication prompt.
    pub fn public(&self) -> Result<P256r1PublicKey, Error> {
        let data = self
            .key
            .public_key()
            .ok_or_else(|| Error::Platform("failed to extract public key".into()))?;
        let data = data.external_representation().ok_or_else(|| {
            Error::Platform("failed to extract public key external representation".into())
        })?;
        P256r1PublicKey::from_bytes(data.bytes())
    }

    /// Perform ECDH against `public_key`, returning the raw shared secret.
    ///
    /// Uses `kSecKeyAlgorithmECDHKeyExchangeStandard`, whose output is the
    /// 32-byte x-coordinate of the shared point with no KDF applied — the
    /// representation Noise requires. For a Secure-Enclave-backed key the
    /// scalar multiplication is carried out in-enclave and the private
    /// scalar never leaves hardware; only the resulting secret is returned.
    /// The peer's public bytes are rebuilt into a `SecKey` using this key's
    /// own public-key attributes as the template (both are P-256 public
    /// keys). Fails if the key does not advertise support for the exchange
    /// algorithm or if the agreed secret is not exactly 32 bytes.
    pub fn dh(&self, public_key: &P256r1PublicKey) -> Result<SharedSecret<32>, Error> {
        let algorithm = Algorithm::ECDHKeyExchangeStandard;

        // SAFETY: `self.key` is a live `SecKey`, so its `as_concrete_TypeRef`
        // yields a valid `SecKeyRef` for the call. The operation type and
        // algorithm are valid static CF constants from `security_framework_sys`.
        // `SecKeyIsAlgorithmSupported` only inspects the key and returns a
        // `Boolean` — it transfers no ownership and returns no Get/Create
        // object, so there is nothing to retain or release.
        let supported = unsafe {
            security_framework_sys::key::SecKeyIsAlgorithmSupported(
                self.key.as_concrete_TypeRef(),
                security_framework_sys::key::kSecKeyOperationTypeKeyExchange,
                security_framework_sys::key::kSecKeyAlgorithmECDHKeyExchangeStandard,
            )
        };
        if supported != 1 {
            return Err(Error::Platform(
                "secret key does not support key exchange".into(),
            ));
        }

        // Build a SecKey from the peer's public bytes, using this key's
        // own public-key attributes as the template (both are P-256
        // public keys, so the EC type/size/class match).
        let self_public = self
            .key
            .public_key()
            .ok_or_else(|| Error::Platform("failed to derive public key for DH".into()))?;
        let public_key: SecKey = public_key.as_sec_key(&self_public.attributes())?;

        let shared_secret = self
            .key
            .key_exchange(algorithm, &public_key, 32, None)
            .map_err(|e| Error::Platform(format!("key exchange failed: {e:?}")))?;

        let bytes: [u8; 32] = shared_secret
            .try_into()
            .map_err(|_| Error::Platform("shared secret is not 32 bytes".into()))?;
        Ok(SharedSecret::new(bytes))
    }

    /// Sign `message` with ECDSA over P-256, SHA-256 digesting the message.
    ///
    /// Uses `kSecKeyAlgorithmECDSASignatureMessageX962SHA256`: the
    /// framework hashes `message` and produces an ASN.1/X9.62 DER
    /// signature, which is decoded into the fixed-width
    /// [`P256Signature`]. For a
    /// Secure-Enclave-backed key the signing scalar multiplication runs
    /// in-enclave and the private scalar never leaves hardware.
    ///
    /// **Unlike the software path, this is not RFC 6979 and not low-S.**
    /// The framework derives its own per-signature nonce, so signing the
    /// same message twice with the same key yields different signatures,
    /// and the `s` it returns is decoded as-is rather than normalized to
    /// the low half of the order. Both are properties of the platform
    /// implementation, which `hiss` does not control. Verifiers that
    /// require low-S — or that assume signature equality implies message
    /// equality — must account for it.
    pub fn sign(&self, message: &[u8]) -> Result<P256Signature, Error> {
        let signature = self
            .key
            .create_signature(Algorithm::ECDSASignatureMessageX962SHA256, message)
            .map_err(|e| Error::Platform(format!("signing failed: {e}")))?;
        P256Signature::try_from_asn1(&signature).map_err(|e| {
            Error::Platform(format!(
                "failed to decode ASN.1 signature {}: {e}",
                hex::encode(&signature)
            ))
        })
    }

    /// Delete the key from the Keychain.
    ///
    /// Only deletes keys that were persisted (created via
    /// [`generate_secure_enclave`](Self::generate_secure_enclave)).
    /// Ephemeral keys are silently ignored.
    pub fn delete(self) -> Result<(), Error> {
        if self.deletable {
            self.key
                .delete()
                .map_err(|e| Error::Platform(format!("failed to delete key: {e}")))
        } else {
            Ok(())
        }
    }
}

// ── AppleSecureEnclave ───────────────────────────────────────────────

/// Apple Secure Enclave provider — P-256 in the enclave, software Ed25519
/// with a sealed seed.
///
/// P-256 static keys are generated in the Secure Enclave and persisted to
/// the data-protection Keychain under the label `{namespace}.p256`;
/// ephemeral keys use a software-backed `SecKey` (no persistence). Ed25519
/// is software-signed — the enclave has no Ed25519 support — and its
/// 32-byte seed is sealed to this device's SE P-256 public key (a
/// 129-byte Noise-N envelope; the internal `noise::seal` helper) and stored in
/// the same data-protection Keychain under the service
/// `{namespace}.ed25519` ([`store_seed`](Self::store_seed) /
/// [`load_seed`](Self::load_seed)). Both platforms (macOS and iOS) use
/// the Keychain — there is no on-disk seed file.
///
/// `namespace` is a required, caller-supplied reverse-DNS base (no
/// default): it names the persisted slots so independent identities on a
/// device never collide.
///
/// # Example
///
/// Swapping the provider is the whole change *in your code* — every
/// handshake call below is identical to the software backend's. The
/// enclave setup is not free, though: see "What a persistent enclave key
/// requires" in the [module documentation](self). The suite must name
/// [`P256`]: the Secure Enclave implements that curve and no other.
///
/// ```no_run
/// use hiss::noise::{Blake2b, ChaChaPoly, P256};
/// use hiss::provider::{AppleSecureEnclave, ProviderExt};
///
/// hiss::noise! {
///     pub XX<P256, ChaChaPoly, Blake2b> {
///         -> e
///         <- e, ee, s, es
///         -> s, se
///     }
/// }
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
///
/// // Generated inside the enclave, persisted to the Keychain, never extractable.
/// let mut keys = AppleSecureEnclave::new("uk.co.example.app");
/// let static_key = keys.generate::<P256>()?;
///
/// // From here nothing is Apple-specific.
/// let (msg1, hs) = XX::initiator(keys, &[]).write_message_1()?;
/// # let _ = (msg1, hs, static_key);
/// # Ok(())
/// # }
/// ```
///
/// This is a `no_run` doctest: it is compiled on every Apple build, but
/// executing it needs real Secure Enclave hardware and a provisioned
/// entitlement, neither of which a CI runner has.
///
/// # The async surface blocks
///
/// This type implements [`DhProviderAsync`] and friends, but every call
/// underneath is a synchronous, blocking Security-framework C function
/// with no async variant — and an enclave operation can stall for a
/// meaningful time, including any keychain or biometric wait. **Those
/// futures therefore do the work on whatever thread polls them and
/// resolve on the first poll; they never suspend.**
///
/// `hiss` deliberately pulls in no async runtime to disguise that. If you
/// are on an executor that must not block, wrap these calls in whatever
/// your runtime provides — `spawn_blocking`, `block_in_place`, a
/// dedicated thread. That is a decision for the application that owns the
/// executor, not for this crate.
#[derive(Clone)]
pub struct AppleSecureEnclave {
    namespace: String,
}

/// Errors from the [`AppleSecureEnclave`] Ed25519 seed lifecycle
/// ([`store_seed`](AppleSecureEnclave::store_seed) /
/// [`load_seed`](AppleSecureEnclave::load_seed)).
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum SeedError {
    /// The Secure Enclave P-256 identity key (the seal recipient) is
    /// absent. Establish it first via
    /// [`generate_static_key`](CryptoKeyProvider::generate_static_key).
    #[error(
        "Secure Enclave P-256 identity key {label:?} not found (establish it before sealing the Ed25519 seed)"
    )]
    IdentityKeyMissing {
        /// Keychain label of the absent SE P-256 identity key.
        label: String,
    },

    /// A Secure Enclave P-256 key operation failed.
    #[error(transparent)]
    P256(#[from] Error),

    /// Sealing or opening the seed via the Noise-N envelope failed.
    ///
    /// The internal `SealError` is rendered to a message at this
    /// boundary because the seal primitive is crate-private.
    #[error("Noise-N seed envelope operation failed: {0}")]
    Seal(String),

    /// A Keychain item operation (store / query / delete) failed.
    #[error("Ed25519 seed Keychain operation failed: {0}")]
    Keychain(String),

    /// The stored seed envelope was not the expected sealed length.
    #[error(
        "stored Ed25519 seed envelope has wrong length: expected {expected} bytes, got {got}",
        expected = SEALED_SIZE
    )]
    WrongSize {
        /// Actual length of the stored envelope, in bytes (the expected
        /// length is the internal `SEALED_SIZE`).
        got: usize,
    },
}

/// Build the data-protection-Keychain generic-password query for the
/// sealed Ed25519 seed under `service`.
fn seed_password_options(service: &str) -> Result<PasswordOptions, SeedError> {
    let mut options = PasswordOptions::new_generic_password(service, ED25519_SEED_ACCOUNT);
    let access_control = SecAccessControl::create_with_protection(
        Some(ProtectionMode::AccessibleAfterFirstUnlockThisDeviceOnly),
        0,
    )
    .map_err(|e| SeedError::Keychain(format!("failed to build seed access control: {e}")))?;
    options.set_access_control(access_control);
    options.set_access_synchronized(Some(false));
    options.use_protected_keychain();
    Ok(options)
}

impl AppleSecureEnclave {
    /// Construct a provider for the given keychain `namespace` (a
    /// reverse-DNS base such as `"uk.co.example.app"`). The namespace
    /// names every persisted slot: the SE key (`{namespace}.p256`) and
    /// the sealed Ed25519 seed (`{namespace}.ed25519`).
    pub fn new(namespace: impl Into<String>) -> Self {
        Self {
            namespace: namespace.into(),
        }
    }

    /// Keychain label of the persisted SE P-256 identity key.
    fn p256_label(&self) -> String {
        format!("{}.p256", self.namespace)
    }

    /// Keychain generic-password service of the sealed Ed25519 seed.
    fn ed25519_service(&self) -> String {
        format!("{}.ed25519", self.namespace)
    }

    /// Load the persisted SE P-256 identity key, if one exists.
    pub fn load_identity(&self) -> Result<Option<P256r1PrivateKey>, Error> {
        P256r1PrivateKey::load_from_keychain(&self.p256_label())
    }

    /// Delete the persisted SE P-256 identity key (idempotent — `Ok` if
    /// none is present).
    pub fn delete_identity(&self) -> Result<(), Error> {
        match self.load_identity()? {
            Some(key) => key.delete(),
            None => Ok(()),
        }
    }

    /// Seal the 32-byte Ed25519 `seed` to this device's SE P-256 public
    /// key and store the resulting 129-byte envelope in the
    /// data-protection Keychain under `{namespace}.ed25519`.
    ///
    /// Requires the SE P-256 identity key (the seal recipient) to already
    /// exist — establish it via
    /// [`generate_static_key`](CryptoKeyProvider::generate_static_key).
    pub async fn store_seed(&self, seed: &[u8; 32]) -> Result<(), SeedError> {
        // Look up the SE identity key and extract its public key — the
        // seal recipient. Only the public key is needed past here, so the
        // private `SecKey` handle is dropped immediately.
        let label = self.p256_label();
        let se_public = match P256r1PrivateKey::load_from_keychain(&label)? {
            Some(se_private) => se_private.public()?,
            None => return Err(SeedError::IdentityKeyMissing { label }),
        };

        // Seal the seed to the SE public key.
        let sealed = seal_32(self.clone(), &se_public, seed)
            .await
            .map_err(|e| SeedError::Seal(e.to_string()))?;

        // Overwrite any prior item, then store the sealed envelope.
        let service = self.ed25519_service();
        let _ = delete_generic_password_options(seed_password_options(&service)?);
        set_generic_password_options(&sealed, seed_password_options(&service)?)
            .map_err(|e| SeedError::Keychain(format!("failed to store sealed Ed25519 seed: {e}")))
    }

    /// Load and unseal the Ed25519 seed, or `None` if none is stored.
    pub async fn load_seed(&self) -> Result<Option<[u8; 32]>, SeedError> {
        // Keychain query for the sealed envelope.
        let service = self.ed25519_service();
        let sealed_bytes = match generic_password(seed_password_options(&service)?) {
            Ok(bytes) => Some(bytes),
            Err(e) if e.code() == security_framework_sys::base::errSecItemNotFound => None,
            Err(e) => {
                return Err(SeedError::Keychain(format!(
                    "failed to query sealed Ed25519 seed: {e}"
                )));
            }
        };
        let Some(sealed_bytes) = sealed_bytes else {
            return Ok(None);
        };
        if sealed_bytes.len() != SEALED_SIZE {
            return Err(SeedError::WrongSize {
                got: sealed_bytes.len(),
            });
        }
        let mut sealed = [0u8; SEALED_SIZE];
        sealed.copy_from_slice(&sealed_bytes);

        // SE-key lookup; the returned handle then moves into `open_32`.
        let label = self.p256_label();
        let se_private = match P256r1PrivateKey::load_from_keychain(&label)? {
            Some(key) => key,
            None => return Err(SeedError::IdentityKeyMissing { label }),
        };

        let opened = open_32(self.clone(), se_private, &sealed)
            .await
            .map_err(|e| SeedError::Seal(e.to_string()))?;
        Ok(Some(opened))
    }

    /// Delete the stored sealed Ed25519 seed (idempotent). Synchronous —
    /// removing the Keychain item needs no enclave round-trip.
    pub fn delete_seed(&self) -> Result<(), SeedError> {
        let service = self.ed25519_service();
        match delete_generic_password_options(seed_password_options(&service)?) {
            Ok(()) => Ok(()),
            Err(e) if e.code() == security_framework_sys::base::errSecItemNotFound => Ok(()),
            Err(e) => Err(SeedError::Keychain(format!(
                "failed to delete sealed Ed25519 seed: {e}"
            ))),
        }
    }
}

// ── A note on the async surface ───────────────────────────────────────
//
// Apple's `SecKey*` and Keychain calls are synchronous, blocking C
// functions with no async variant, and a Secure Enclave operation can
// stall for a meaningful time (including any keychain or biometric wait).
// The `*Async` impls below therefore do the same work as their
// synchronous counterparts and resolve on the first poll — they do not
// suspend, and they do not move the work to another thread.
//
// This crate pulls in **no async runtime** to pretend otherwise. An
// earlier version wrapped every call in `tokio::task::spawn_blocking`,
// which made `tokio` a hard dependency of every macOS/iOS consumer in
// order to add a thread hop this crate cannot know is wanted. A caller
// running on an executor that must not block should wrap these calls in
// whatever their runtime offers (`spawn_blocking`, `block_in_place`, a
// dedicated thread) — that is a decision belonging to the application
// that owns the executor, not to a library.
//
// The `*Async` traits themselves remain the right shape for a backend
// that genuinely suspends — a remote KMS, WebCrypto — where the future
// really does await I/O.

// Apple's Security-framework operations are synchronous, blocking C
// calls — so the *synchronous* surface is simply those inherent ops, run
// directly on the calling thread, exactly as Apple's libraries expose
// them. The async impls further down call the very same operations; see
// the note above them.
impl CryptoKeyProvider<P256> for AppleSecureEnclave {
    type Error = Error;
    type PrivateKey = P256r1PrivateKey;

    fn public_key(&self, key: &Self::PrivateKey) -> Result<P256r1PublicKey, Self::Error> {
        // Cheap, local SecKey accessor — no Secure Enclave round-trip and
        // no prompt — so it stays inline (the trait declares it sync).
        key.public()
    }

    fn generate_static_key(&mut self) -> Result<Self::PrivateKey, Self::Error> {
        P256r1PrivateKey::generate_secure_enclave(&self.p256_label())
    }

    fn generate_ephemeral_key(&mut self) -> Result<Self::PrivateKey, Self::Error> {
        P256r1PrivateKey::generate_ephemeral()
    }
}

impl CryptoKeyProviderAsync<P256> for AppleSecureEnclave {
    async fn generate_static_key_async(&mut self) -> Result<Self::PrivateKey, Self::Error> {
        P256r1PrivateKey::generate_secure_enclave(&self.p256_label())
    }

    async fn generate_ephemeral_key_async(&mut self) -> Result<Self::PrivateKey, Self::Error> {
        P256r1PrivateKey::generate_ephemeral()
    }
}

impl DhProvider<P256> for AppleSecureEnclave {
    fn dh(
        &self,
        key: &Self::PrivateKey,
        peer: &P256r1PublicKey,
    ) -> Result<SharedSecret<32>, Self::Error> {
        key.dh(peer)
    }
}

impl DhProviderAsync<P256> for AppleSecureEnclave {
    async fn dh_async(
        &self,
        key: &Self::PrivateKey,
        peer: &P256r1PublicKey,
    ) -> Result<SharedSecret<32>, Self::Error> {
        key.dh(peer)
    }
}

impl SigningProvider<P256> for AppleSecureEnclave {
    fn sign(&self, key: &Self::PrivateKey, message: &[u8]) -> Result<P256Signature, Self::Error> {
        key.sign(message)
    }
}

impl SigningProviderAsync<P256> for AppleSecureEnclave {
    async fn sign_async(
        &self,
        key: &Self::PrivateKey,
        message: &[u8],
    ) -> Result<P256Signature, Self::Error> {
        key.sign(message)
    }
}

// ── Ed25519 (software — the enclave has no Ed25519 support) ───────────
//
// The Secure Enclave never touches Ed25519: these are software
// (`cryptoxide`) operations. Unlike `EphemeralOnly`, the seed's entropy
// comes from Apple's `SecRandomCopyBytes` (hardware-grade) rather than a
// caller-supplied RNG — so `AppleSecureEnclave` needs no `R` parameter.
// Persistence of the seed at rest is handled separately by the
// sealed-seed lifecycle above (`store_seed` / `load_seed`).

/// Generate a software Ed25519 key seeded from Apple's `SecRandomCopyBytes`.
fn apple_ed25519_generate() -> Result<SoftwareEd25519PrivateKey, crate::curve::ed25519::Error> {
    let mut seed = [0u8; 32];
    // SAFETY: `seed.as_mut_ptr()` is a valid, properly-aligned pointer to the
    // exclusively-borrowed `[u8; 32]` (the `&mut seed` borrow guarantees no
    // aliasing for the call). We pass `seed.len()` (== 32), so exactly that many
    // bytes are written within the array's bounds and no further.
    // `kSecRandomDefault` is the framework's valid default RNG reference. The
    // returned status is checked by the caller below before `seed` is used.
    let status = unsafe {
        security_framework_sys::random::SecRandomCopyBytes(
            security_framework_sys::random::kSecRandomDefault,
            seed.len(),
            seed.as_mut_ptr().cast(),
        )
    };
    if status != 0 {
        return Err(crate::curve::ed25519::Error::Platform(format!(
            "SecRandomCopyBytes failed with status {status}"
        )));
    }
    if seed.iter().all(|&b| b == 0) {
        return Err(crate::curve::ed25519::Error::Platform(
            "SecRandomCopyBytes returned an all-zero seed".into(),
        ));
    }
    Ok(SoftwareEd25519PrivateKey::from_seed(seed))
}

impl CryptoKeyProvider<Ed25519> for AppleSecureEnclave {
    type Error = crate::curve::ed25519::Error;
    type PrivateKey = SoftwareEd25519PrivateKey;

    fn public_key(&self, key: &Self::PrivateKey) -> Result<Ed25519PublicKey, Self::Error> {
        Ok(key.public_key())
    }

    fn generate_static_key(&mut self) -> Result<Self::PrivateKey, Self::Error> {
        apple_ed25519_generate()
    }

    fn generate_ephemeral_key(&mut self) -> Result<Self::PrivateKey, Self::Error> {
        apple_ed25519_generate()
    }
}

impl CryptoKeyProviderAsync<Ed25519> for AppleSecureEnclave {
    async fn generate_static_key_async(&mut self) -> Result<Self::PrivateKey, Self::Error> {
        apple_ed25519_generate()
    }

    async fn generate_ephemeral_key_async(&mut self) -> Result<Self::PrivateKey, Self::Error> {
        apple_ed25519_generate()
    }
}

impl SigningProvider<Ed25519> for AppleSecureEnclave {
    fn sign(
        &self,
        key: &Self::PrivateKey,
        message: &[u8],
    ) -> Result<Ed25519Signature, Self::Error> {
        Ok(key.sign(message))
    }
}

impl SigningProviderAsync<Ed25519> for AppleSecureEnclave {
    async fn sign_async(
        &self,
        key: &Self::PrivateKey,
        message: &[u8],
    ) -> Result<Ed25519Signature, Self::Error> {
        Ok(key.sign(message))
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::curve::p256::P256r1PrivateKey as SoftwareP256r1PrivateKey;
    use crate::provider::ProviderExt;

    #[test]
    fn generate_signature_ephemeral() {
        let sk1 = P256r1PrivateKey::generate_ephemeral().unwrap();
        let pk1 = sk1.public().unwrap();
        const MSG: &[u8] = b"Hello World";
        let signature = sk1.sign(MSG).unwrap();
        assert!(pk1.verify(signature, MSG));

        let sk2 = P256r1PrivateKey::generate_ephemeral().unwrap();
        let pk2 = sk2.public().unwrap();
        assert!(!pk2.verify(signature, MSG));

        sk1.delete().unwrap();
        sk2.delete().unwrap();
    }

    #[test]
    fn generate_dh_ephemerals() {
        let sk1 = P256r1PrivateKey::generate_ephemeral().unwrap();
        let pk1 = sk1.public().unwrap();

        let sk2 = P256r1PrivateKey::generate_ephemeral().unwrap();
        let pk2 = sk2.public().unwrap();

        let ss1 = sk1.dh(&pk2).unwrap();
        let ss2 = sk2.dh(&pk1).unwrap();

        assert_eq!(ss1.as_bytes(), ss2.as_bytes());
    }

    #[test]
    fn macos_x_software() {
        let sk1 = P256r1PrivateKey::generate_ephemeral().unwrap();
        let pk1 = sk1.public().unwrap();

        let sk2 = SoftwareP256r1PrivateKey::generate(rand::rng()).unwrap();
        let pk2 = sk2.public();

        let apple_dh = sk1.dh(&pk2).unwrap();
        let our_dh = sk2.dh(&pk1).unwrap();

        assert_eq!(apple_dh.as_bytes(), our_dh.as_bytes());
    }

    /// Drive the async provider trait methods end-to-end under a real
    /// runtime: generate two ephemeral keys, agree, and confirm the DH
    /// matches both ways. (`tokio` is a dev-dependency for this test only —
    /// the crate itself pulls in no runtime.)
    #[tokio::test]
    async fn crypto_provider_async_dh_roundtrip() {
        let mut provider = AppleSecureEnclave::new("uk.co.example.hiss-test");

        // Fully-qualified P-256: the provider also implements the trait
        // for Ed25519, so the curve can't be inferred from the call alone.
        let a = CryptoKeyProviderAsync::<P256>::generate_ephemeral_key_async(&mut provider)
            .await
            .unwrap();
        let b = CryptoKeyProviderAsync::<P256>::generate_ephemeral_key_async(&mut provider)
            .await
            .unwrap();
        let a_pub = provider.public(&a).unwrap();
        let b_pub = provider.public(&b).unwrap();

        let ab = DhProviderAsync::<P256>::dh_async(&provider, &a, &b_pub)
            .await
            .unwrap();
        let ba = DhProviderAsync::<P256>::dh_async(&provider, &b, &a_pub)
            .await
            .unwrap();
        assert_eq!(ab.as_bytes(), ba.as_bytes());

        // The async signing path round-trips too.
        let sig = SigningProviderAsync::<P256>::sign_async(&provider, &a, b"hello")
            .await
            .unwrap();
        assert!(a_pub.verify(sig, b"hello"));
    }

    #[test]
    #[ignore = "requires Secure Enclave hardware"]
    fn generate_signature_secure_enclave() {
        let sk1 = P256r1PrivateKey::generate_secure_enclave_ephemeral().unwrap();
        let pk1 = sk1.public().unwrap();
        const MSG: &[u8] = b"Hello World";
        let signature = sk1.sign(MSG).unwrap();
        assert!(pk1.verify(signature, MSG));

        let sk2 = P256r1PrivateKey::generate_secure_enclave_ephemeral().unwrap();
        let pk2 = sk2.public().unwrap();
        assert!(!pk2.verify(signature, MSG));

        sk1.delete().unwrap();
        sk2.delete().unwrap();
    }

    /// Establish an SE identity, seal + store the Ed25519 seed to the
    /// Keychain, load it back, and delete — the full keychain-backed
    /// seed lifecycle. Ignored: needs a codesigned binary with the
    /// keychain-access-groups entitlement and Secure Enclave hardware.
    #[tokio::test]
    #[ignore = "requires codesigned test binary + Secure Enclave hardware"]
    async fn ed25519_seed_keychain_round_trip() {
        let mut provider = AppleSecureEnclave::new("uk.co.example.hiss-test");

        // Establish the SE P-256 identity (the seal recipient).
        let _identity = provider.generate::<P256>().unwrap();

        let seed: [u8; 32] = *SoftwareEd25519PrivateKey::generate(rand::rng()).seed();

        assert!(provider.load_seed().await.unwrap().is_none());

        provider.store_seed(&seed).await.unwrap();
        let loaded = provider
            .load_seed()
            .await
            .unwrap()
            .expect("seed present after store");
        assert_eq!(loaded, seed, "loaded seed must byte-equal the stored seed");

        provider.delete_seed().unwrap();
        assert!(provider.load_seed().await.unwrap().is_none());
        // idempotent
        provider.delete_seed().unwrap();

        provider.delete_identity().unwrap();
    }
}