umsh_crypto/

lib.rs

#![allow(async_fn_in_trait)]
#![cfg_attr(not(feature = "std"), no_std)]

//! Cryptographic traits and UMSH-specific key/packet operations.
//!
//! This crate separates algorithm providers from protocol logic. The low-level
//! traits such as [`AesProvider`] and [`Sha256Provider`] can be backed either by
//! software implementations or hardware accelerators, while [`CryptoEngine`]
//! implements the UMSH-specific derivation and packet-authentication rules.
//!
//! # Example
//!
//! ```rust
//! use umsh_crypto::software::{SoftwareAes, SoftwareIdentity, SoftwareSha256};
//! use umsh_crypto::{CryptoEngine, NodeIdentity};
//!
//! let alice = SoftwareIdentity::from_secret_bytes(&[0x11; 32]);
//! let bob = SoftwareIdentity::from_secret_bytes(&[0x22; 32]);
//! let shared = alice.shared_secret_with(bob.public_key()).unwrap();
//! let engine = CryptoEngine::new(SoftwareAes, SoftwareSha256);
//! let keys = engine.derive_pairwise_keys(&shared);
//!
//! assert_ne!(keys.k_enc, [0u8; 16]);
//! assert_ne!(keys.k_mic, [0u8; 16]);
//! ```

use core::ops::Range;

use umsh_core::{
    ChannelId, ChannelKey, ChannelTag, PacketHeader, PacketType, PublicKey, SourceAddrRef,
    UnsealedPacket, feed_aad,
};
use zeroize::{Zeroize, ZeroizeOnDrop};

pub mod replay;

/// AES block-cipher instance used by the protocol engine.
pub trait AesCipher {
    /// Encrypt one 16-byte block in place.
    fn encrypt_block(&self, block: &mut [u8; 16]);
    /// Decrypt one 16-byte block in place.
    fn decrypt_block(&self, block: &mut [u8; 16]);
}

/// Factory for keyed AES cipher instances.
pub trait AesProvider {
    /// Concrete cipher type returned by [`new_cipher`](Self::new_cipher).
    type Cipher: AesCipher;

    /// Create a new AES-128 cipher using `key`.
    fn new_cipher(&self, key: &[u8; 16]) -> Self::Cipher;
}

/// SHA-256 and HMAC-SHA-256 provider.
pub trait Sha256Provider {
    /// Hash a list of borrowed byte slices as one concatenated message.
    fn hash(&self, data: &[&[u8]]) -> [u8; 32];
    /// Compute HMAC-SHA-256 over a list of borrowed byte slices.
    fn hmac(&self, key: &[u8], data: &[&[u8]]) -> [u8; 32];
}

/// Raw X25519 shared secret.
#[derive(Clone, Zeroize, ZeroizeOnDrop)]
pub struct SharedSecret(pub [u8; 32]);

/// Node identity capable of signing and key agreement.
pub trait NodeIdentity {
    type Error;

    /// Return the long-term Ed25519 public key for this identity.
    fn public_key(&self) -> &PublicKey;

    /// Return the three-byte node hint derived from [`public_key`](Self::public_key).
    fn hint(&self) -> umsh_core::NodeHint {
        self.public_key().hint()
    }

    /// Sign an arbitrary message.
    async fn sign(&self, message: &[u8]) -> Result<[u8; 64], Self::Error>;
    /// Perform X25519-style key agreement with a peer public key.
    async fn agree(&self, peer: &PublicKey) -> Result<SharedSecret, Self::Error>;
}

/// Protocol-level crypto failures.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum CryptoError {
    InvalidPublicKey,
    InvalidSharedSecret,
    InvalidPacket,
    AuthenticationFailed,
}

/// Maximum channel-name length accepted by
/// [`CryptoEngine::derive_named_channel_key`].
///
/// This is an implementation limit of the no-alloc canonicalization buffer,
/// not a protocol constant; the spec places no length bound on named
/// channels.
pub const MAX_CHANNEL_NAME_LEN: usize = 64;

/// Error returned when a channel name cannot be canonicalized for key
/// derivation (see multicast-channels.md § Named Channels).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ChannelNameError {
    /// The name contains non-ASCII characters. UTF-8 names are deferred by
    /// the spec because Unicode case-folding is non-trivial.
    NotAscii,
    /// The name exceeds [`MAX_CHANNEL_NAME_LEN`].
    TooLong,
}

/// Derived pairwise transport keys.
#[derive(Clone, Zeroize, ZeroizeOnDrop)]
pub struct PairwiseKeys {
    pub k_enc: [u8; 16],
    pub k_mic: [u8; 16],
}

/// Derived multicast or channel transport keys.
#[derive(Clone)]
pub struct DerivedChannelKeys {
    pub k_enc: [u8; 16],
    pub k_mic: [u8; 16],
    pub channel_id: ChannelId,
}

impl Zeroize for DerivedChannelKeys {
    fn zeroize(&mut self) {
        self.k_enc.zeroize();
        self.k_mic.zeroize();
    }
}

impl Drop for DerivedChannelKeys {
    fn drop(&mut self) {
        self.zeroize();
    }
}

/// Incremental AES-CMAC state.
pub struct CmacState<C: AesCipher> {
    cipher: C,
    state: [u8; 16],
    buffer: [u8; 16],
    pos: usize,
    k1: [u8; 16],
    k2: [u8; 16],
}

impl<C: AesCipher> CmacState<C> {
    /// Initialize a new incremental CMAC state.
    pub fn new(cipher: C) -> Self {
        let mut l = [0u8; 16];
        cipher.encrypt_block(&mut l);
        let k1 = dbl(&l);
        let k2 = dbl(&k1);
        Self {
            cipher,
            state: [0u8; 16],
            buffer: [0u8; 16],
            pos: 0,
            k1,
            k2,
        }
    }

    /// Feed additional bytes into the MAC state.
    pub fn update(&mut self, mut data: &[u8]) {
        while !data.is_empty() {
            let space = 16 - self.pos;
            let take = space.min(data.len());
            self.buffer[self.pos..self.pos + take].copy_from_slice(&data[..take]);
            self.pos += take;
            data = &data[take..];
            if self.pos == 16 && !data.is_empty() {
                self.process_buffer();
            }
        }
    }

    /// Finalize and return the full 16-byte CMAC value.
    pub fn finalize(self) -> [u8; 16] {
        let this = self;
        let mut last = [0u8; 16];
        if this.pos == 16 {
            last.copy_from_slice(&this.buffer);
            xor_in_place(&mut last, &this.k1);
        } else {
            last[..this.pos].copy_from_slice(&this.buffer[..this.pos]);
            last[this.pos] = 0x80;
            xor_in_place(&mut last, &this.k2);
        }

        xor_in_place(&mut last, &this.state);
        this.cipher.encrypt_block(&mut last);
        last
    }

    fn process_buffer(&mut self) {
        let mut block = self.buffer;
        xor_in_place(&mut block, &self.state);
        self.cipher.encrypt_block(&mut block);
        self.state = block;
        self.buffer = [0u8; 16];
        self.pos = 0;
    }
}

/// UMSH protocol crypto engine.
pub struct CryptoEngine<A: AesProvider, S: Sha256Provider> {
    aes: A,
    sha: S,
}

impl<A: AesProvider, S: Sha256Provider> CryptoEngine<A, S> {
    /// Create a new engine from algorithm providers.
    pub fn new(aes: A, sha: S) -> Self {
        Self { aes, sha }
    }

    /// Derive stable pairwise encryption and MIC keys from a shared secret.
    pub fn derive_pairwise_keys(&self, shared_secret: &SharedSecret) -> PairwiseKeys {
        let mut okm = [0u8; 32];
        self.hkdf(
            &shared_secret.0,
            b"UMSH-PAIRWISE-SALT",
            b"UMSH-UNICAST-V1",
            &mut okm,
        );
        let mut keys = PairwiseKeys {
            k_enc: [0u8; 16],
            k_mic: [0u8; 16],
        };
        keys.k_enc.copy_from_slice(&okm[..16]);
        keys.k_mic.copy_from_slice(&okm[16..32]);
        okm.zeroize();
        keys
    }

    /// Derive the channel identifier from a raw channel key.
    pub fn derive_channel_id(&self, channel_key: &ChannelKey) -> ChannelId {
        let mut out = [0u8; 2];
        self.hkdf(&channel_key.0, b"UMSH-CHAN-ID", b"", &mut out);
        ChannelId(out)
    }

    /// Derive three bytes for presentation — a deterministic colour a user
    /// interface can give a channel.
    ///
    /// This is the channel-identifier derivation run one byte longer, so the
    /// first two bytes are the channel identifier itself: HKDF-Expand emits a
    /// prefix of the same block either way. Nothing on the wire carries the
    /// third byte, and nothing depends on it.
    pub fn derive_channel_tint(&self, channel_key: &ChannelKey) -> [u8; 3] {
        let mut out = [0u8; 3];
        self.hkdf(&channel_key.0, b"UMSH-CHAN-ID", b"", &mut out);
        out
    }

    /// Derive the channel tag — a local identity wide enough to tell apart two
    /// channels whose keys derive the same channel identifier.
    ///
    /// Same derivation as the channel identifier, run to sixteen bytes, so the
    /// identifier and the presentation tint are prefixes of it.
    pub fn derive_channel_tag(&self, channel_key: &ChannelKey) -> ChannelTag {
        let mut out = [0u8; 16];
        self.hkdf(&channel_key.0, b"UMSH-CHAN-ID", b"", &mut out);
        ChannelTag(out)
    }

    /// Derive multicast transport keys and the channel identifier.
    pub fn derive_channel_keys(&self, channel_key: &ChannelKey) -> DerivedChannelKeys {
        let channel_id = self.derive_channel_id(channel_key);
        let mut info = [0u8; 15];
        info[..13].copy_from_slice(b"UMSH-MCAST-V1");
        info[13..15].copy_from_slice(&channel_id.0);
        let mut okm = [0u8; 32];
        self.hkdf(&channel_key.0, b"UMSH-MCAST-SALT", &info, &mut okm);
        let mut derived = DerivedChannelKeys {
            k_enc: [0u8; 16],
            k_mic: [0u8; 16],
            channel_id,
        };
        derived.k_enc.copy_from_slice(&okm[..16]);
        derived.k_mic.copy_from_slice(&okm[16..32]);
        okm.zeroize();
        derived
    }

    /// Combine pairwise and channel keys for blind-unicast payload protection.
    pub fn derive_blind_keys(
        &self,
        pairwise: &PairwiseKeys,
        channel: &DerivedChannelKeys,
    ) -> PairwiseKeys {
        let mut keys = PairwiseKeys {
            k_enc: [0u8; 16],
            k_mic: [0u8; 16],
        };
        for (dst, (left, right)) in keys
            .k_enc
            .iter_mut()
            .zip(pairwise.k_enc.iter().zip(channel.k_enc.iter()))
        {
            *dst = left ^ right;
        }
        for (dst, (left, right)) in keys
            .k_mic
            .iter_mut()
            .zip(pairwise.k_mic.iter().zip(channel.k_mic.iter()))
        {
            *dst = left ^ right;
        }
        keys
    }

    /// Derive a channel key from a human-readable channel name.
    ///
    /// The name is canonicalized first, per the spec (multicast-channels.md
    /// § Named Channels): it must be ASCII, and ASCII letters are folded to
    /// lowercase before derivation — so `Public`, `public`, and `PUBLIC` all
    /// derive the same key. Non-ASCII names are rejected (UTF-8 case-folding
    /// is deferred by the spec). Names longer than
    /// [`MAX_CHANNEL_NAME_LEN`] are rejected as an implementation limit of
    /// the no-alloc canonicalization buffer.
    pub fn derive_named_channel_key(&self, name: &str) -> Result<ChannelKey, ChannelNameError> {
        let bytes = name.as_bytes();
        if bytes.len() > MAX_CHANNEL_NAME_LEN {
            return Err(ChannelNameError::TooLong);
        }
        if !name.is_ascii() {
            return Err(ChannelNameError::NotAscii);
        }
        let mut canonical = [0u8; MAX_CHANNEL_NAME_LEN];
        for (dst, byte) in canonical.iter_mut().zip(bytes) {
            *dst = byte.to_ascii_lowercase();
        }
        Ok(ChannelKey(
            self.sha
                .hmac(b"UMSH-CHANNEL-V1", &[&canonical[..bytes.len()]]),
        ))
    }

    /// Seal a unicast or multicast packet in place.
    pub fn seal_packet(
        &self,
        packet: &mut UnsealedPacket<'_>,
        keys: &PairwiseKeys,
    ) -> Result<usize, CryptoError> {
        let header = packet.header().map_err(|_| CryptoError::InvalidPacket)?;
        let sec_info = header.sec_info.ok_or(CryptoError::InvalidPacket)?;
        let full_mac = {
            let bytes = packet.as_bytes();
            let mut cmac = self.cmac_state(&keys.k_mic);
            feed_aad(&header, bytes, |chunk| cmac.update(chunk));
            cmac.update(packet.body());
            cmac.finalize()
        };

        let mic_len = sec_info
            .scf
            .mic_size()
            .map_err(|_| CryptoError::InvalidPacket)?
            .byte_len();
        packet.mic_slot()[..mic_len].copy_from_slice(&full_mac[..mic_len]);

        if sec_info.scf.encrypted() {
            let iv = self.build_ctr_iv(
                &full_mac[..mic_len],
                &packet.as_bytes()[packet.sec_info_range()],
            );
            self.aes_ctr(&keys.k_enc, &iv, packet.body_mut());
        }

        Ok(mic_len)
    }

    /// Seal a blind-unicast packet, including its hidden address block.
    pub fn seal_blind_packet(
        &self,
        packet: &mut UnsealedPacket<'_>,
        blind_keys: &PairwiseKeys,
        channel_keys: &DerivedChannelKeys,
    ) -> Result<usize, CryptoError> {
        let header = packet.header().map_err(|_| CryptoError::InvalidPacket)?;
        match header.packet_type() {
            PacketType::BlindUnicast | PacketType::BlindUnicastAckReq => {}
            _ => return Err(CryptoError::InvalidPacket),
        }

        let sec_info = header.sec_info.ok_or(CryptoError::InvalidPacket)?;
        let blind_addr_range = packet
            .blind_addr_range()
            .ok_or(CryptoError::InvalidPacket)?;
        let full_mac = {
            let bytes = packet.as_bytes();
            let mut cmac = self.cmac_state(&blind_keys.k_mic);
            feed_aad(&header, bytes, |chunk| cmac.update(chunk));
            cmac.update(packet.body());
            cmac.finalize()
        };

        let mic_len = sec_info
            .scf
            .mic_size()
            .map_err(|_| CryptoError::InvalidPacket)?
            .byte_len();
        let iv = self.build_ctr_iv(
            &full_mac[..mic_len],
            &packet.as_bytes()[packet.sec_info_range()],
        );
        packet.mic_slot()[..mic_len].copy_from_slice(&full_mac[..mic_len]);
        if sec_info.scf.encrypted() {
            self.aes_ctr(&blind_keys.k_enc, &iv, packet.body_mut());
            self.aes_ctr(
                &channel_keys.k_enc,
                &iv,
                &mut packet.as_bytes_mut()[blind_addr_range],
            );
        }
        Ok(mic_len)
    }

    /// Verify and, if needed, decrypt a received secure packet in place.
    pub fn open_packet(
        &self,
        buf: &mut [u8],
        header: &PacketHeader,
        keys: &PairwiseKeys,
    ) -> Result<Range<usize>, CryptoError> {
        let sec_info = header.sec_info.ok_or(CryptoError::InvalidPacket)?;
        let mut mic = [0u8; 16];
        let mic_len = header.mic_range.end - header.mic_range.start;
        mic[..mic_len].copy_from_slice(&buf[header.mic_range.clone()]);
        if sec_info.scf.encrypted() {
            let iv = self.build_ctr_iv(&mic[..mic_len], &buf[sec_info_bytes_range(header)?]);
            self.aes_ctr(&keys.k_enc, &iv, &mut buf[header.body_range.clone()]);
        }

        let full_mac = {
            let mut cmac = self.cmac_state(&keys.k_mic);
            feed_aad(header, buf, |chunk| cmac.update(chunk));
            cmac.update(&buf[header.body_range.clone()]);
            cmac.finalize()
        };
        if !constant_time_eq(&mic[..mic_len], &full_mac[..mic_len]) {
            return Err(CryptoError::AuthenticationFailed);
        }

        let body_range = match (header.packet_type(), header.source) {
            (PacketType::Multicast, SourceAddrRef::Encrypted { len, .. }) => {
                (header.body_range.start + len)..header.body_range.end
            }
            _ => header.body_range.clone(),
        };
        Ok(body_range)
    }

    /// Decrypt the blinded destination/source address block of a blind unicast.
    pub fn decrypt_blind_addr(
        &self,
        buf: &mut [u8],
        header: &PacketHeader,
        channel_keys: &DerivedChannelKeys,
    ) -> Result<(umsh_core::NodeHint, SourceAddrRef), CryptoError> {
        match header.source {
            SourceAddrRef::Encrypted { offset, len } => {
                let addr_start = offset.checked_sub(3).ok_or(CryptoError::InvalidPacket)?;
                let addr_end = addr_start + 3 + len;
                let iv = self.build_ctr_iv(
                    &buf[header.mic_range.clone()],
                    &buf[sec_info_bytes_range(header)?],
                );
                self.aes_ctr(&channel_keys.k_enc, &iv, &mut buf[addr_start..addr_end]);
                let dst = umsh_core::NodeHint([
                    buf[addr_start],
                    buf[addr_start + 1],
                    buf[addr_start + 2],
                ]);
                let source = if len == 3 {
                    SourceAddrRef::Hint(umsh_core::NodeHint([
                        buf[addr_start + 3],
                        buf[addr_start + 4],
                        buf[addr_start + 5],
                    ]))
                } else if len == 32 {
                    SourceAddrRef::FullKeyAt {
                        offset: addr_start + 3,
                    }
                } else {
                    return Err(CryptoError::InvalidPacket);
                };
                Ok((dst, source))
            }
            SourceAddrRef::Hint(hint) => {
                let dst = header.dst.ok_or(CryptoError::InvalidPacket)?;
                Ok((dst, SourceAddrRef::Hint(hint)))
            }
            SourceAddrRef::FullKeyAt { offset } => {
                let dst = header.dst.ok_or(CryptoError::InvalidPacket)?;
                let _ = buf
                    .get(offset..offset + 32)
                    .ok_or(CryptoError::InvalidPacket)?;
                Ok((dst, SourceAddrRef::FullKeyAt { offset }))
            }
            SourceAddrRef::None => Err(CryptoError::InvalidPacket),
        }
    }

    /// Compute the 8-byte MAC ack trailer (`ack_mic || ack_tag`) from a full
    /// CMAC and `k_enc`.
    ///
    /// The trailer splits into two 4-byte halves:
    ///
    /// - **`ack_mic`** = the first 4 bytes of `full_cmac`. Because the on-wire
    ///   MIC is a prefix-truncation of the full CMAC, this equals the first
    ///   4 bytes of the acknowledged packet's on-wire MIC — a *public*
    ///   correlation handle any node that received the original packet
    ///   (including forwarding repeaters) can compute.
    /// - **`ack_tag`** = `truncate_4( AES-128-ECB(k_enc, full_cmac) )`. A keyed
    ///   value only the original sender and final destination can produce; it
    ///   authenticates the standalone ack.
    ///
    /// See the spec's *Ack Tag Construction* section.
    pub fn compute_ack_trailer(&self, full_cmac: &[u8; 16], k_enc: &[u8; 16]) -> [u8; 8] {
        let cipher = self.aes.new_cipher(k_enc);
        let mut block = *full_cmac;
        cipher.encrypt_block(&mut block);
        let mut trailer = [0u8; 8];
        trailer[..4].copy_from_slice(&full_cmac[..4]); // ack_mic (public)
        trailer[4..].copy_from_slice(&block[..4]); // ack_tag (keyed)
        trailer
    }

    /// Create a reusable incremental CMAC state.
    pub fn cmac_state(&self, key: &[u8; 16]) -> CmacState<A::Cipher> {
        CmacState::new(self.aes.new_cipher(key))
    }

    /// Convenience wrapper for AES-CMAC over concatenated slices.
    pub fn aes_cmac(&self, key: &[u8; 16], data: &[&[u8]]) -> [u8; 16] {
        let mut state = self.cmac_state(key);
        for chunk in data {
            state.update(chunk);
        }
        state.finalize()
    }

    /// Apply AES-CTR using `iv` as the initial counter block.
    pub fn aes_ctr(&self, key: &[u8; 16], iv: &[u8; 16], data: &mut [u8]) {
        let cipher = self.aes.new_cipher(key);
        let mut counter = *iv;
        for chunk in data.chunks_mut(16) {
            let mut stream = counter;
            cipher.encrypt_block(&mut stream);
            for (dst, src) in chunk.iter_mut().zip(stream.iter()) {
                *dst ^= *src;
            }
            increment_counter(&mut counter);
        }
    }

    /// Construct the CTR IV from MIC bytes and SECINFO bytes.
    ///
    /// With a 16-byte MIC the IV is the MIC alone; shorter MICs are
    /// padded from the SECINFO bytes, so the IV construction of a
    /// received packet must locate SECINFO exactly (see
    /// [`sec_info_bytes_range`]).
    pub fn build_ctr_iv(&self, mic: &[u8], sec_info_bytes: &[u8]) -> [u8; 16] {
        let mut iv = [0u8; 16];
        let mut written = 0usize;
        for byte in mic.iter().chain(sec_info_bytes.iter()).take(16) {
            iv[written] = *byte;
            written += 1;
        }
        iv
    }

    /// Run HKDF-SHA256 and write the output into `okm`.
    pub fn hkdf(&self, ikm: &[u8], salt: &[u8], info: &[u8], okm: &mut [u8]) {
        let prk = self.sha.hmac(salt, &[ikm]);
        let mut previous = [0u8; 32];
        let mut previous_len = 0usize;
        let mut written = 0usize;
        let mut counter = 1u8;
        while written < okm.len() {
            let next = self
                .sha
                .hmac(&prk, &[&previous[..previous_len], info, &[counter]]);
            let take = (okm.len() - written).min(next.len());
            okm[written..written + take].copy_from_slice(&next[..take]);
            previous = next;
            previous_len = 32;
            written += take;
            counter = counter.wrapping_add(1);
        }
    }
}

fn xor_in_place(dst: &mut [u8; 16], rhs: &[u8; 16]) {
    for (left, right) in dst.iter_mut().zip(rhs.iter()) {
        *left ^= *right;
    }
}

fn dbl(block: &[u8; 16]) -> [u8; 16] {
    let mut out = [0u8; 16];
    let mut carry = 0u8;
    for (index, byte) in block.iter().enumerate().rev() {
        out[index] = (byte << 1) | carry;
        carry = byte >> 7;
    }
    if block[0] & 0x80 != 0 {
        out[15] ^= 0x87;
    }
    out
}

/// The on-wire SECINFO byte range of a parsed secure packet. In every
/// secure layout (unicast, multicast, blind unicast) SECINFO
/// immediately precedes the options block — not the body, which the
/// options end marker or a blind address block may separate from it.
fn sec_info_bytes_range(header: &PacketHeader) -> Result<Range<usize>, CryptoError> {
    let sec_info = header.sec_info.ok_or(CryptoError::InvalidPacket)?;
    header
        .options_range
        .start
        .checked_sub(sec_info.wire_len())
        .map(|start| start..header.options_range.start)
        .ok_or(CryptoError::InvalidPacket)
}

fn increment_counter(counter: &mut [u8; 16]) {
    for byte in counter.iter_mut().rev() {
        let (next, carry) = byte.overflowing_add(1);
        *byte = next;
        if !carry {
            break;
        }
    }
}

fn constant_time_eq(left: &[u8], right: &[u8]) -> bool {
    let mut diff = left.len() ^ right.len();
    let max_len = left.len().max(right.len());
    for index in 0..max_len {
        let lhs = left.get(index).copied().unwrap_or(0);
        let rhs = right.get(index).copied().unwrap_or(0);
        diff |= usize::from(lhs ^ rhs);
    }
    diff == 0
}

#[cfg(feature = "software-crypto")]
pub mod software {
    use aes::cipher::{BlockDecrypt, BlockEncrypt, KeyInit, generic_array::GenericArray};
    use curve25519_dalek::{edwards::CompressedEdwardsY, montgomery::MontgomeryPoint};
    use ed25519_dalek::{Signer, SigningKey};
    use rand_core::CryptoRngCore;
    use sha2::{Digest, Sha256, Sha512};

    use super::*;

    pub struct SoftwareAes;

    pub struct SoftwareAesCipher(aes::Aes128);

    impl AesCipher for SoftwareAesCipher {
        fn encrypt_block(&self, block: &mut [u8; 16]) {
            self.0.encrypt_block(GenericArray::from_mut_slice(block));
        }

        fn decrypt_block(&self, block: &mut [u8; 16]) {
            self.0.decrypt_block(GenericArray::from_mut_slice(block));
        }
    }

    impl AesProvider for SoftwareAes {
        type Cipher = SoftwareAesCipher;

        fn new_cipher(&self, key: &[u8; 16]) -> Self::Cipher {
            SoftwareAesCipher(aes::Aes128::new(GenericArray::from_slice(key)))
        }
    }

    pub struct SoftwareSha256;

    impl Sha256Provider for SoftwareSha256 {
        fn hash(&self, data: &[&[u8]]) -> [u8; 32] {
            let mut hasher = Sha256::new();
            for chunk in data {
                hasher.update(chunk);
            }
            hasher.finalize().into()
        }

        fn hmac(&self, key: &[u8], data: &[&[u8]]) -> [u8; 32] {
            const BLOCK_LEN: usize = 64;
            let mut key_block = [0u8; BLOCK_LEN];
            if key.len() > BLOCK_LEN {
                key_block[..32].copy_from_slice(&self.hash(&[key]));
            } else {
                key_block[..key.len()].copy_from_slice(key);
            }

            let mut ipad = [0x36u8; BLOCK_LEN];
            let mut opad = [0x5Cu8; BLOCK_LEN];
            for index in 0..BLOCK_LEN {
                ipad[index] ^= key_block[index];
                opad[index] ^= key_block[index];
            }

            let mut inner = Sha256::new();
            inner.update(ipad);
            for chunk in data {
                inner.update(chunk);
            }
            let inner_hash = inner.finalize();

            let mut outer = Sha256::new();
            outer.update(opad);
            outer.update(inner_hash);
            outer.finalize().into()
        }
    }

    /// Cloning is deliberate: a holder that must both hand the identity to
    /// the MAC and retain signing ability (e.g. standalone node-identity
    /// bundles) keeps a clone rather than round-tripping secret bytes.
    #[derive(Clone)]
    pub struct SoftwareIdentity {
        secret: SigningKey,
        public: PublicKey,
    }

    impl SoftwareIdentity {
        pub fn generate(rng: &mut impl CryptoRngCore) -> Self {
            let secret = SigningKey::generate(rng);
            let public = PublicKey(secret.verifying_key().to_bytes());
            Self { secret, public }
        }

        pub fn from_secret_bytes(bytes: &[u8; 32]) -> Self {
            let secret = SigningKey::from_bytes(bytes);
            let public = PublicKey(secret.verifying_key().to_bytes());
            Self { secret, public }
        }

        pub fn shared_secret_with(&self, peer: &PublicKey) -> Result<SharedSecret, CryptoError> {
            let local = signing_key_to_x25519(&self.secret);
            let remote = public_key_to_x25519(peer)?;
            let shared = local.diffie_hellman(&remote);
            let bytes = shared.to_bytes();
            if bytes.iter().all(|byte| *byte == 0) {
                return Err(CryptoError::InvalidSharedSecret);
            }
            Ok(SharedSecret(bytes))
        }
    }

    impl NodeIdentity for SoftwareIdentity {
        type Error = CryptoError;

        fn public_key(&self) -> &PublicKey {
            &self.public
        }

        async fn sign(&self, message: &[u8]) -> Result<[u8; 64], Self::Error> {
            Ok(self.secret.sign(message).to_bytes())
        }

        async fn agree(&self, peer: &PublicKey) -> Result<SharedSecret, Self::Error> {
            self.shared_secret_with(peer)
        }
    }

    pub type SoftwareCryptoEngine = CryptoEngine<SoftwareAes, SoftwareSha256>;

    fn signing_key_to_x25519(secret: &SigningKey) -> x25519_dalek::StaticSecret {
        let digest = Sha512::digest(secret.to_bytes());
        let mut scalar = [0u8; 32];
        scalar.copy_from_slice(&digest[..32]);
        scalar[0] &= 248;
        scalar[31] &= 127;
        scalar[31] |= 64;
        x25519_dalek::StaticSecret::from(scalar)
    }

    fn public_key_to_x25519(public: &PublicKey) -> Result<x25519_dalek::PublicKey, CryptoError> {
        let compressed = CompressedEdwardsY(public.0);
        let edwards = compressed
            .decompress()
            .ok_or(CryptoError::InvalidPublicKey)?;
        let mont: MontgomeryPoint = edwards.to_montgomery();
        Ok(x25519_dalek::PublicKey::from(mont.to_bytes()))
    }

    /// Return `true` if `pk`'s bytes decode to a valid Ed25519 compressed
    /// public-key point on the curve. Used by the MAC layer and CLI to reject
    /// malformed peer keys before they can poison the peer registry.
    pub fn is_valid_ed25519_public_key(pk: &PublicKey) -> bool {
        CompressedEdwardsY(pk.0).decompress().is_some()
    }

    /// Verify a detached Ed25519 signature against `pk`. Used for standalone
    /// node-identity bundles (QR codes, broadcasts) whose signed range must
    /// verify before the bundle's claims are presented as authenticated.
    pub fn verify_ed25519_signature(pk: &PublicKey, message: &[u8], signature: &[u8; 64]) -> bool {
        let Ok(key) = ed25519_dalek::VerifyingKey::from_bytes(&pk.0) else {
            return false;
        };
        key.verify_strict(message, &ed25519_dalek::Signature::from_bytes(signature))
            .is_ok()
    }
}

#[cfg(feature = "software-crypto")]
pub use software::*;

#[cfg(test)]
mod tests {
    use crate::{constant_time_eq, dbl};

    #[cfg(feature = "software-crypto")]
    use super::{software::*, *};
    #[cfg(feature = "software-crypto")]
    use umsh_core::{MicSize, NodeHint, PacketBuilder, PacketHeader, PublicKey};

    #[cfg(feature = "software-crypto")]
    #[test]
    fn pairwise_hkdf_is_stable() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let keys = engine.derive_pairwise_keys(&SharedSecret([7u8; 32]));
        assert_ne!(keys.k_enc, [0u8; 16]);
        assert_ne!(keys.k_mic, [0u8; 16]);
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn aes_cmac_matches_rfc4493_example_2() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let key = hex_16("2b7e151628aed2a6abf7158809cf4f3c");
        let msg = hex_vec("6bc1bee22e409f96e93d7e117393172a");
        let expected = hex_16("070a16b46b4d4144f79bdd9dd04a287c");
        assert_eq!(engine.aes_cmac(&key, &[&msg]), expected);
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn aes_cmac_matches_rfc4493_example_1_empty() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let key = hex_16("2b7e151628aed2a6abf7158809cf4f3c");
        let expected = hex_16("bb1d6929e95937287fa37d129b756746");
        assert_eq!(engine.aes_cmac(&key, &[&[]]), expected);
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn aes_cmac_matches_rfc4493_example_3_64b() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let key = hex_16("2b7e151628aed2a6abf7158809cf4f3c");
        let msg = hex_vec(
            "6bc1bee22e409f96e93d7e117393172a\
             ae2d8a571e03ac9c9eb76fac45af8e51\
             30c81c46a35ce411e5fbc1191a0a52ef\
             f69f2445df4f9b17ad2b417be66c3710",
        );
        let expected = hex_16("51f0bebf7e3b9d92fc49741779363cfe");
        assert_eq!(engine.aes_cmac(&key, &[&msg]), expected);
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn aes_cmac_matches_rfc4493_example_4_40b() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let key = hex_16("2b7e151628aed2a6abf7158809cf4f3c");
        let msg = hex_vec(
            "6bc1bee22e409f96e93d7e117393172a\
             ae2d8a571e03ac9c9eb76fac45af8e51\
             30c81c46a35ce411",
        );
        let expected = hex_16("dfa66747de9ae63030ca32611497c827");
        assert_eq!(engine.aes_cmac(&key, &[&msg]), expected);
    }

    /// NIST SP 800-38A Section F.5.1 — AES-128 CTR mode, single block.
    #[cfg(feature = "software-crypto")]
    #[test]
    fn aes_ctr_matches_nist_sp800_38a_block_1() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let key = hex_16("2b7e151628aed2a6abf7158809cf4f3c");
        let iv = hex_16("f0f1f2f3f4f5f6f7f8f9fafbfcfdfeff");
        let mut data = hex_vec("6bc1bee22e409f96e93d7e117393172a");
        engine.aes_ctr(&key, &iv, &mut data);
        assert_eq!(data, hex_vec("874d6191b620e3261bef6864990db6ce"));
    }

    /// NIST SP 800-38A Section F.5.1 — AES-128 CTR mode, 4 blocks.
    /// Verifies counter increment across multiple blocks.
    #[cfg(feature = "software-crypto")]
    #[test]
    fn aes_ctr_matches_nist_sp800_38a_4_blocks() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let key = hex_16("2b7e151628aed2a6abf7158809cf4f3c");
        let iv = hex_16("f0f1f2f3f4f5f6f7f8f9fafbfcfdfeff");
        let mut data = hex_vec(
            "6bc1bee22e409f96e93d7e117393172a\
             ae2d8a571e03ac9c9eb76fac45af8e51\
             30c81c46a35ce411e5fbc1191a0a52ef\
             f69f2445df4f9b17ad2b417be66c3710",
        );
        let expected = hex_vec(
            "874d6191b620e3261bef6864990db6ce\
             9806f66b7970fdff8617187bb9fffdff\
             5ae4df3edbd5d35e5b4f09020db03eab\
             1e031dda2fbe03d1792170a0f3009cee",
        );
        engine.aes_ctr(&key, &iv, &mut data);
        assert_eq!(data, expected);
    }

    /// NIST SP 800-38A — CTR decrypt (symmetric operation).
    #[cfg(feature = "software-crypto")]
    #[test]
    fn aes_ctr_decrypt_matches_nist_sp800_38a() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let key = hex_16("2b7e151628aed2a6abf7158809cf4f3c");
        let iv = hex_16("f0f1f2f3f4f5f6f7f8f9fafbfcfdfeff");
        let mut data = hex_vec(
            "874d6191b620e3261bef6864990db6ce\
             9806f66b7970fdff8617187bb9fffdff\
             5ae4df3edbd5d35e5b4f09020db03eab\
             1e031dda2fbe03d1792170a0f3009cee",
        );
        let expected = hex_vec(
            "6bc1bee22e409f96e93d7e117393172a\
             ae2d8a571e03ac9c9eb76fac45af8e51\
             30c81c46a35ce411e5fbc1191a0a52ef\
             f69f2445df4f9b17ad2b417be66c3710",
        );
        engine.aes_ctr(&key, &iv, &mut data);
        assert_eq!(data, expected);
    }

    /// AES-CTR with partial final block (non-aligned length).
    #[cfg(feature = "software-crypto")]
    #[test]
    fn aes_ctr_partial_block() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let key = hex_16("2b7e151628aed2a6abf7158809cf4f3c");
        let iv = hex_16("f0f1f2f3f4f5f6f7f8f9fafbfcfdfeff");
        // Encrypt 5 bytes (less than one block)
        let mut data = hex_vec("6bc1bee22e");
        engine.aes_ctr(&key, &iv, &mut data);
        // Should match first 5 bytes of full block 1 ciphertext
        assert_eq!(data, hex_vec("874d6191b6"));
        // Decrypt back
        engine.aes_ctr(&key, &iv, &mut data);
        assert_eq!(data, hex_vec("6bc1bee22e"));
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn hmac_sha256_matches_rfc4231_case_1() {
        let sha = SoftwareSha256;
        let key = [0x0bu8; 20];
        let expected = hex_32("b0344c61d8db38535ca8afceaf0bf12b881dc200c9833da726e9376c2e32cff7");
        assert_eq!(sha.hmac(&key, &[b"Hi There"]), expected);
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn hkdf_matches_rfc5869_case_1() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let ikm = [0x0bu8; 22];
        let salt = hex_vec("000102030405060708090a0b0c");
        let info = hex_vec("f0f1f2f3f4f5f6f7f8f9");
        let mut okm = [0u8; 42];
        engine.hkdf(&ikm, &salt, &info, &mut okm);
        assert_eq!(
            okm.to_vec(),
            hex_vec(
                "3cb25f25faacd57a90434f64d0362f2a2d2d0a90cf1a5a4c5db02d56ecc4c5bf34007208d5b887185865"
            )
        );
    }

    #[test]
    fn cmac_doubling_matches_rfc4493_subkey_generation() {
        let l = hex_16("7df76b0c1ab899b33e42f047b91b546f");
        let expected_k1 = hex_16("fbeed618357133667c85e08f7236a8de");
        let expected_k2 = hex_16("f7ddac306ae266ccf90bc11ee46d513b");
        let k1 = dbl(&l);
        let k2 = dbl(&k1);
        assert_eq!(k1, expected_k1);
        assert_eq!(k2, expected_k2);
    }

    #[test]
    fn constant_time_eq_rejects_mismatch() {
        assert!(constant_time_eq(&[1, 2, 3], &[1, 2, 3]));
        assert!(!constant_time_eq(&[1, 2, 3], &[1, 2, 4]));
        assert!(!constant_time_eq(&[1, 2, 3], &[1, 2, 3, 4]));
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn unicast_seal_and_open_round_trip() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let keys = engine.derive_pairwise_keys(&SharedSecret([9u8; 32]));
        let src = PublicKey([0xA1; 32]);
        let dst = NodeHint([0xC3, 0xD4, 0x25]);
        let mut buf = [0u8; 128];
        let mut packet = PacketBuilder::new(&mut buf)
            .unicast(dst)
            .source_full(&src)
            .frame_counter(1)
            .encrypted()
            .mic_size(MicSize::Mic16)
            .payload(b"hello")
            .build()
            .unwrap();

        engine.seal_packet(&mut packet, &keys).unwrap();
        let header = PacketHeader::parse(packet.as_bytes()).unwrap();
        let mut wire = packet.as_bytes().to_vec();
        let range = engine.open_packet(&mut wire, &header, &keys).unwrap();
        assert_eq!(&wire[range], b"hello");
    }

    /// Regression: with a MIC shorter than 16 bytes the CTR IV includes
    /// SECINFO bytes, and SECINFO precedes the options block — not the
    /// body, which the options end marker separates from it. The IV of
    /// a received packet must be built from the true SECINFO position
    /// or decryption diverges from sealing.
    #[cfg(feature = "software-crypto")]
    #[test]
    fn short_mic_encrypted_unicast_round_trip() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let keys = engine.derive_pairwise_keys(&SharedSecret([9u8; 32]));
        let mut buf = [0u8; 128];
        let mut packet = PacketBuilder::new(&mut buf)
            .unicast(NodeHint([0xC3, 0xD4, 0x25]))
            .source_hint(NodeHint([0xA1, 0xA1, 0xA1]))
            .frame_counter(7)
            .encrypted()
            .mic_size(MicSize::Mic8)
            .payload(b"short mic")
            .build()
            .unwrap();
        engine.seal_packet(&mut packet, &keys).unwrap();
        let header = PacketHeader::parse(packet.as_bytes()).unwrap();
        let mut wire = packet.as_bytes().to_vec();
        let range = engine.open_packet(&mut wire, &header, &keys).unwrap();
        assert_eq!(&wire[range], b"short mic");
    }

    /// Regression companion to the above for blind unicast, where the
    /// concealed address block also sits between SECINFO and the body:
    /// address decryption and payload opening must both locate SECINFO
    /// correctly with a short MIC.
    #[cfg(feature = "software-crypto")]
    #[test]
    fn short_mic_blind_unicast_round_trip() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let channel_key = ChannelKey([0x5A; 32]);
        let channel_keys = engine.derive_channel_keys(&channel_key);
        let pairwise = engine.derive_pairwise_keys(&SharedSecret([9u8; 32]));
        let blind_keys = engine.derive_blind_keys(&pairwise, &channel_keys);
        let dst = NodeHint([0xC3, 0xD4, 0x25]);
        let src = NodeHint([0xA1, 0xA1, 0xA1]);

        let mut buf = [0u8; 128];
        let mut packet = PacketBuilder::new(&mut buf)
            .blind_unicast(channel_keys.channel_id, dst)
            .source_hint(src)
            .frame_counter(7)
            .ack_requested()
            .encrypted()
            .mic_size(MicSize::Mic8)
            .payload(b"blind")
            .build()
            .unwrap();
        engine
            .seal_blind_packet(&mut packet, &blind_keys, &channel_keys)
            .unwrap();

        let header = PacketHeader::parse(packet.as_bytes()).unwrap();
        let mut wire = packet.as_bytes().to_vec();
        let (decrypted_dst, decrypted_src) = engine
            .decrypt_blind_addr(&mut wire, &header, &channel_keys)
            .unwrap();
        assert_eq!(decrypted_dst, dst);
        assert_eq!(decrypted_src, SourceAddrRef::Hint(src));
        let range = engine.open_packet(&mut wire, &header, &blind_keys).unwrap();
        assert_eq!(&wire[range], b"blind");
    }

    /// Verify compute_ack_trailer produces a deterministic 8-byte value and
    /// that its two halves are the public `ack_mic` (CMAC prefix) and the
    /// keyed `ack_tag`.
    #[cfg(feature = "software-crypto")]
    #[test]
    fn compute_ack_trailer_is_deterministic() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let key = hex_16("2b7e151628aed2a6abf7158809cf4f3c");
        let cmac = hex_16("070a16b46b4d4144f79bdd9dd04a287c"); // RFC 4493 example 2
        let t1 = engine.compute_ack_trailer(&cmac, &key);
        let t2 = engine.compute_ack_trailer(&cmac, &key);
        assert_eq!(t1, t2);
        assert_eq!(t1.len(), 8);
        // ack_mic half is the first 4 bytes of the full CMAC (public).
        assert_eq!(t1[..4], cmac[..4]);
        // ack_tag half is the first 4 bytes of AES-ECB(key, cmac) (keyed).
        let cipher = SoftwareAes.new_cipher(&key);
        let mut block = cmac;
        cipher.encrypt_block(&mut block);
        assert_eq!(t1[4..], block[..4]);
    }

    /// Verify that compute_ack_trailer with different CMACs produces different
    /// trailers in both the mic and tag halves.
    #[cfg(feature = "software-crypto")]
    #[test]
    fn compute_ack_trailer_differs_for_different_cmacs() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let key = hex_16("2b7e151628aed2a6abf7158809cf4f3c");
        let cmac_a = hex_16("070a16b46b4d4144f79bdd9dd04a287c");
        let cmac_b = hex_16("51f0bebf7e3b9d92fc49741779363cfe");
        let t_a = engine.compute_ack_trailer(&cmac_a, &key);
        let t_b = engine.compute_ack_trailer(&cmac_b, &key);
        assert_ne!(t_a, t_b);
        assert_ne!(t_a, [0u8; 8]);
        assert_ne!(t_b, [0u8; 8]);
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn encrypted_multicast_round_trip_preserves_source_prefix() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let channel_key = ChannelKey([0x5Au8; 32]);
        let derived = engine.derive_channel_keys(&channel_key);
        let src = PublicKey([0xA1; 32]);
        let mut buf = [0u8; 160];
        let mut packet = PacketBuilder::new(&mut buf)
            .multicast(derived.channel_id)
            .source_hint(src.hint())
            .frame_counter(5)
            .encrypted()
            .mic_size(MicSize::Mic16)
            .payload(b"hello")
            .build()
            .unwrap();

        let multicast_keys = PairwiseKeys {
            k_enc: derived.k_enc,
            k_mic: derived.k_mic,
        };
        engine.seal_packet(&mut packet, &multicast_keys).unwrap();
        let header = PacketHeader::parse(packet.as_bytes()).unwrap();
        let mut wire = packet.as_bytes().to_vec();
        let range = engine
            .open_packet(&mut wire, &header, &multicast_keys)
            .unwrap();
        assert_eq!(
            &wire[header.body_range.start..header.body_range.start + 3],
            &src.hint().0
        );
        assert_eq!(&wire[range], b"hello");
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn blind_unicast_round_trip_recovers_addresses_and_payload() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let shared = SharedSecret([0x33u8; 32]);
        let pairwise = engine.derive_pairwise_keys(&shared);
        let channel_key = ChannelKey([0x5Au8; 32]);
        let channel = engine.derive_channel_keys(&channel_key);
        let blind_keys = engine.derive_blind_keys(&pairwise, &channel);
        let src = PublicKey([
            0xA1, 0xB2, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E,
            0x0F, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1A, 0x1B, 0x1C,
            0x1D, 0x1E, 0x1F, 0x20,
        ]);
        let dst = NodeHint([0xC3, 0xD4, 0x25]);
        let mut buf = [0u8; 160];
        let mut packet = PacketBuilder::new(&mut buf)
            .blind_unicast(channel.channel_id, dst)
            .source_full(&src)
            .frame_counter(5)
            .mic_size(MicSize::Mic16)
            .payload(b"hello")
            .build()
            .unwrap();

        engine
            .seal_blind_packet(&mut packet, &blind_keys, &channel)
            .unwrap();
        let header = PacketHeader::parse(packet.as_bytes()).unwrap();
        let mut wire = packet.as_bytes().to_vec();
        let (decoded_dst, decoded_src) = engine
            .decrypt_blind_addr(&mut wire, &header, &channel)
            .unwrap();
        let range = engine.open_packet(&mut wire, &header, &blind_keys).unwrap();

        assert_eq!(decoded_dst, dst);
        assert_eq!(
            decoded_src,
            SourceAddrRef::FullKeyAt {
                offset: header.body_range.start - 32
            }
        );
        assert_eq!(
            &wire[header.body_range.start - 32..header.body_range.start],
            &src.0
        );
        assert_eq!(&wire[range], b"hello");
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn software_identity_agreement_is_symmetric() {
        let alice = SoftwareIdentity::from_secret_bytes(&[
            0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E,
            0x1F, 0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28, 0x29, 0x2A, 0x2B, 0x2C,
            0x2D, 0x2E, 0x2F, 0x30,
        ]);
        let bob = SoftwareIdentity::from_secret_bytes(&[
            0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3A, 0x3B, 0x3C, 0x3D, 0x3E,
            0x3F, 0x40, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48, 0x49, 0x4A, 0x4B, 0x4C,
            0x4D, 0x4E, 0x4F, 0x50,
        ]);

        let ab = alice.shared_secret_with(bob.public_key()).unwrap();
        let ba = bob.shared_secret_with(alice.public_key()).unwrap();
        assert_eq!(ab.0, ba.0);
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn channel_tint_extends_the_channel_identifier() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let key = ChannelKey([0x5Au8; 32]);
        let tint = engine.derive_channel_tint(&key);
        // The presentation colour is the identifier derivation run one byte
        // longer, so a caller holding either can recognize the other.
        assert_eq!(&tint[..2], &engine.derive_channel_id(&key).0[..]);
        assert_eq!(tint, engine.derive_channel_tint(&key));
        assert_ne!(tint, engine.derive_channel_tint(&ChannelKey([0x5Bu8; 32])));
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn channel_tag_extends_the_channel_identifier_and_tint() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let key = ChannelKey([0x5Au8; 32]);
        let tag = engine.derive_channel_tag(&key);
        // One derivation, three lengths: whoever holds the tag can recover the
        // identifier and the tint without the key.
        assert_eq!(tag.channel_id(), engine.derive_channel_id(&key));
        assert_eq!(&tag.0[..3], &engine.derive_channel_tint(&key)[..]);
        assert_eq!(tag, engine.derive_channel_tag(&key));
        assert_ne!(tag, engine.derive_channel_tag(&ChannelKey([0x5Bu8; 32])));
    }

    // ── derive_named_channel_key ──────────────────────────────────────────────

    #[cfg(feature = "software-crypto")]
    #[test]
    fn derive_named_channel_key_is_deterministic() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let k1 = engine.derive_named_channel_key("lobby").unwrap();
        let k2 = engine.derive_named_channel_key("lobby").unwrap();
        let k3 = engine.derive_named_channel_key("other").unwrap();
        assert_eq!(k1, k2);
        assert_ne!(k1, k3);
        assert_ne!(k1, ChannelKey([0u8; 32]));
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn derive_named_channel_key_folds_ascii_case() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let lower = engine.derive_named_channel_key("public").unwrap();
        assert_eq!(engine.derive_named_channel_key("Public").unwrap(), lower);
        assert_eq!(engine.derive_named_channel_key("PUBLIC").unwrap(), lower);
        // Digits and symbols are untouched by the fold.
        assert_eq!(
            engine.derive_named_channel_key("Mesh-42!").unwrap(),
            engine.derive_named_channel_key("mesh-42!").unwrap()
        );
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn derive_named_channel_key_rejects_invalid_names() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        assert_eq!(
            engine.derive_named_channel_key("caf\u{e9}"),
            Err(ChannelNameError::NotAscii)
        );
        let too_long = "x".repeat(MAX_CHANNEL_NAME_LEN + 1);
        assert_eq!(
            engine.derive_named_channel_key(&too_long),
            Err(ChannelNameError::TooLong)
        );
        // Exactly at the limit is fine.
        let at_limit = "x".repeat(MAX_CHANNEL_NAME_LEN);
        assert!(engine.derive_named_channel_key(&at_limit).is_ok());
    }

    // ── SoftwareIdentity::generate ────────────────────────────────────────────

    #[cfg(feature = "software-crypto")]
    #[test]
    fn software_identity_generate_produces_valid_key() {
        use rand_core::{CryptoRng, RngCore};

        // Minimal deterministic RNG for testing — counter-based, not cryptographically
        // strong, but sufficient to exercise the generate() code path.
        struct CounterRng(u64);
        impl RngCore for CounterRng {
            fn next_u32(&mut self) -> u32 {
                self.next_u64() as u32
            }
            fn next_u64(&mut self) -> u64 {
                self.0 = self.0.wrapping_add(1);
                self.0
            }
            fn fill_bytes(&mut self, dest: &mut [u8]) {
                for chunk in dest.chunks_mut(8) {
                    let bytes = self.next_u64().to_le_bytes();
                    chunk.copy_from_slice(&bytes[..chunk.len()]);
                }
            }
            fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), rand_core::Error> {
                self.fill_bytes(dest);
                Ok(())
            }
        }
        impl CryptoRng for CounterRng {}

        let mut rng1 = CounterRng(0);
        let mut rng2 = CounterRng(1000);
        let id1 = SoftwareIdentity::generate(&mut rng1);
        let id2 = SoftwareIdentity::generate(&mut rng2);
        assert_ne!(id1.public_key(), id2.public_key());
        let ss1 = id1.shared_secret_with(id2.public_key()).unwrap();
        let ss2 = id2.shared_secret_with(id1.public_key()).unwrap();
        assert_eq!(ss1.0, ss2.0);
    }

    // ── seal_blind_packet wrong packet type ───────────────────────────────────

    #[cfg(feature = "software-crypto")]
    #[test]
    fn seal_blind_packet_rejects_non_blind_packet() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let shared = SharedSecret([0x11u8; 32]);
        let pairwise = engine.derive_pairwise_keys(&shared);
        let channel_key = ChannelKey([0x5Au8; 32]);
        let channel = engine.derive_channel_keys(&channel_key);
        let blind_keys = engine.derive_blind_keys(&pairwise, &channel);
        let src = PublicKey([0xA1u8; 32]);
        let dst = NodeHint([0xC3, 0xD4, 0x25]);
        let mut buf = [0u8; 128];
        // Build a regular unicast packet (not a blind unicast).
        let mut packet = PacketBuilder::new(&mut buf)
            .unicast(dst)
            .source_full(&src)
            .frame_counter(1)
            .encrypted()
            .mic_size(MicSize::Mic16)
            .payload(b"test")
            .build()
            .unwrap();
        assert!(matches!(
            engine.seal_blind_packet(&mut packet, &blind_keys, &channel),
            Err(CryptoError::InvalidPacket)
        ));
    }

    // ── open_packet authentication failure ────────────────────────────────────

    #[cfg(feature = "software-crypto")]
    #[test]
    fn open_packet_fails_on_tampered_ciphertext() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let keys = engine.derive_pairwise_keys(&SharedSecret([9u8; 32]));
        let src = PublicKey([0xA1; 32]);
        let dst = NodeHint([0xC3, 0xD4, 0x25]);
        let mut buf = [0u8; 128];
        let mut packet = PacketBuilder::new(&mut buf)
            .unicast(dst)
            .source_full(&src)
            .frame_counter(1)
            .encrypted()
            .mic_size(MicSize::Mic16)
            .payload(b"hello")
            .build()
            .unwrap();
        engine.seal_packet(&mut packet, &keys).unwrap();

        // Flip a bit in the sealed packet body.
        let mut wire = packet.as_bytes().to_vec();
        let header = PacketHeader::parse(&wire).unwrap();
        wire[header.body_range.start] ^= 0x01;

        assert!(matches!(
            engine.open_packet(&mut wire, &header, &keys),
            Err(CryptoError::AuthenticationFailed)
        ));
    }

    // ── decrypt_blind_addr: encrypted hint source (len == 3) ─────────────────

    #[cfg(feature = "software-crypto")]
    #[test]
    fn decrypt_blind_addr_encrypted_hint_source() {
        let engine = SoftwareCryptoEngine::new(SoftwareAes, SoftwareSha256);
        let shared = SharedSecret([0x33u8; 32]);
        let pairwise = engine.derive_pairwise_keys(&shared);
        let channel_key = ChannelKey([0x5Au8; 32]);
        let channel = engine.derive_channel_keys(&channel_key);
        let blind_keys = engine.derive_blind_keys(&pairwise, &channel);
        let src = PublicKey([0xA1u8; 32]);
        let dst = NodeHint([0xC3, 0xD4, 0x25]);
        let mut buf = [0u8; 128];
        // Use source_hint → produces Encrypted { len: 3 } in blind unicast.
        let mut packet = PacketBuilder::new(&mut buf)
            .blind_unicast(channel.channel_id, dst)
            .source_hint(src.hint())
            .frame_counter(5)
            .encrypted()
            .mic_size(MicSize::Mic16)
            .payload(b"hi")
            .build()
            .unwrap();
        engine
            .seal_blind_packet(&mut packet, &blind_keys, &channel)
            .unwrap();
        let mut wire = packet.as_bytes().to_vec();
        let header = PacketHeader::parse(&wire).unwrap();
        let (decoded_dst, decoded_src) = engine
            .decrypt_blind_addr(&mut wire, &header, &channel)
            .unwrap();
        assert_eq!(decoded_dst, dst);
        assert_eq!(decoded_src, SourceAddrRef::Hint(src.hint()));
    }

    // ── SoftwareAes::decrypt_block ────────────────────────────────────────────

    #[cfg(feature = "software-crypto")]
    #[test]
    fn aes_decrypt_block_inverts_encrypt_block() {
        let key = hex_16("2b7e151628aed2a6abf7158809cf4f3c");
        let cipher = SoftwareAes.new_cipher(&key);
        let original = hex_16("6bc1bee22e409f96e93d7e117393172a");
        let mut block = original;
        cipher.encrypt_block(&mut block);
        assert_ne!(block, original);
        cipher.decrypt_block(&mut block);
        assert_eq!(block, original);
    }

    // ── NodeIdentity trait: sign and agree ────────────────────────────────────

    #[cfg(feature = "software-crypto")]
    #[test]
    fn sign_and_agree_via_trait() {
        use core::future::Future;
        use core::pin::pin;
        use core::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};

        fn block_on<F: Future>(future: F) -> F::Output {
            let raw = RawWaker::new(
                core::ptr::null(),
                &RawWakerVTable::new(|_| panic!(), |_| {}, |_| {}, |_| {}),
            );
            let waker = unsafe { Waker::from_raw(raw) };
            let mut ctx = Context::from_waker(&waker);
            match pin!(future).poll(&mut ctx) {
                Poll::Ready(v) => v,
                Poll::Pending => panic!("future unexpectedly pending"),
            }
        }

        let alice = SoftwareIdentity::from_secret_bytes(&[0x11u8; 32]);
        let bob = SoftwareIdentity::from_secret_bytes(&[0x22u8; 32]);

        let sig = block_on(alice.sign(b"test message")).unwrap();
        assert_eq!(sig.len(), 64);

        let shared = block_on(alice.agree(bob.public_key())).unwrap();
        assert_ne!(shared.0, [0u8; 32]);
    }

    // ── NodeIdentity::hint default impl ───────────────────────────────────────

    #[cfg(feature = "software-crypto")]
    #[test]
    fn node_identity_hint_matches_public_key_hint() {
        let id = SoftwareIdentity::from_secret_bytes(&[0x11u8; 32]);
        // Calls the NodeIdentity::hint() default impl, which derives from public_key().
        assert_eq!(NodeIdentity::hint(&id), id.public_key().hint());
    }

    // ── uppercase hex in decode_hex ───────────────────────────────────────────

    #[test]
    fn hex_vec_accepts_uppercase() {
        assert_eq!(hex_vec("DEADBEEF"), hex_vec("deadbeef"));
        assert_eq!(hex_vec("0A1B2C3D"), hex_vec("0a1b2c3d"));
    }

    fn hex_vec(input: &str) -> std::vec::Vec<u8> {
        assert_eq!(input.len() % 2, 0);
        let mut out = std::vec::Vec::with_capacity(input.len() / 2);
        let bytes = input.as_bytes();
        for index in (0..bytes.len()).step_by(2) {
            out.push((decode_hex(bytes[index]) << 4) | decode_hex(bytes[index + 1]));
        }
        out
    }

    fn hex_16(input: &str) -> [u8; 16] {
        let bytes = hex_vec(input);
        let mut out = [0u8; 16];
        out.copy_from_slice(&bytes);
        out
    }

    #[cfg(feature = "software-crypto")]
    fn hex_32(input: &str) -> [u8; 32] {
        let bytes = hex_vec(input);
        let mut out = [0u8; 32];
        out.copy_from_slice(&bytes);
        out
    }

    fn decode_hex(byte: u8) -> u8 {
        match byte {
            b'0'..=b'9' => byte - b'0',
            b'a'..=b'f' => byte - b'a' + 10,
            b'A'..=b'F' => byte - b'A' + 10,
            _ => panic!("invalid hex"),
        }
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn is_valid_ed25519_public_key_accepts_real_key() {
        // Any verifying key produced by a SigningKey is by construction a
        // valid Ed25519 point — the validator must accept it.
        let identity = SoftwareIdentity::from_secret_bytes(&[0x11; 32]);
        assert!(is_valid_ed25519_public_key(identity.public_key()));
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn is_valid_ed25519_public_key_rejects_non_curve_bytes() {
        // Y = 2 (little-endian) is not on the Ed25519 curve: the
        // recovered x^2 from the curve equation has no square root in
        // GF(2^255 - 19). Confirm the validator rejects it — this is
        // the exact failure mode a user typo trips when they paste a
        // mistyped hex pubkey on the CLI.
        let mut bytes = [0u8; 32];
        bytes[0] = 2;
        let bogus = PublicKey(bytes);
        assert!(!is_valid_ed25519_public_key(&bogus));
    }

    #[cfg(feature = "software-crypto")]
    #[test]
    fn is_valid_ed25519_public_key_handles_all_zero() {
        // The all-zero compressed Y value decompresses to the curve
        // identity point. Whatever the library's actual behavior is,
        // pin it so a curve25519-dalek update can't silently flip the
        // contract. (Today: accepted as a valid point.)
        let zero = PublicKey([0u8; 32]);
        assert!(is_valid_ed25519_public_key(&zero));
    }
}