umsh_node/

identity_responder.rs

//! Built-in responder for the [Identity Request](crate::mac_command) MAC command.
//!
//! When enabled on a [`LocalNode`](crate::LocalNode), the node answers a
//! matching Identity Request with a **targeted authenticated unicast** carrying
//! its own [`NodeIdentityPayload`], echoing any request `NONCE` into identity
//! option 5. Responses are never signed and never fall back to broadcast: the
//! pairwise MIC, frame counter, and echoed nonce already make the reply
//! authentic and fresh, and a request whose source cannot be resolved to a key
//! is simply dropped by the MAC before the responder ever runs.
//!
//! The application supplies a [`NodeIdentityProfile`] (its role, capabilities,
//! and descriptive fields) and, optionally, a respond **policy** — a
//! registerable discriminator that inspects the [`IdentityRequestContext`] and
//! decides whether, and how, to answer (e.g. "known peers only", "only on a
//! given channel", "repeater → always"). No signing key is required.

use alloc::boxed::Box;
use alloc::string::String;
use alloc::vec::Vec;

use umsh_core::{ChannelId, NodeHint, PayloadType, PublicKey};
use umsh_mac::{PacketFamily, Snr};

use crate::identity::{NodeCapabilities, NodeIdentityPayload, NodeRole};
use crate::location::NodeLocation;
use crate::mac_command::IdentityRequestFilters;

/// This node's own identity, used to answer Identity Requests.
///
/// Holds descriptive fields only — **no signing key**. Config-like fields
/// (`role`, `capabilities`, `name`, `supported_regions`) are typically set once
/// at bring-up; live fields (`location`, `altitude_m`) can be refreshed at any
/// time via [`LocalNode::update_identity_profile`](crate::LocalNode::update_identity_profile),
/// e.g. from a GPS task.
#[derive(Clone, Debug)]
pub struct NodeIdentityProfile {
    /// This node's public key. Its [hint](PublicKey::hint) is matched against a
    /// request's `FILTER_NODE_HINT`; the key itself reaches the requester via
    /// the reply's MAC source address, not the identity payload.
    pub public_key: PublicKey,
    pub role: NodeRole,
    pub capabilities: NodeCapabilities,
    pub name: Option<String>,
    pub location: Option<NodeLocation>,
    pub altitude_m: Option<i32>,
    pub supported_regions: Option<Vec<u8>>,
    /// Where identity option 3 comes from: the current Unix time, or
    /// `None` on a node that does not know what time it is.
    ///
    /// A source rather than a value, because option 3 dates the *payload*
    /// and every payload is built fresh — a stored number would be the
    /// time some earlier payload was built. It lives here so that the one
    /// canonical builder stamps every framing identically; a node with no
    /// clock keeps the default and simply omits the option.
    pub clock: fn() -> Option<u32>,
}

impl NodeIdentityProfile {
    /// Create a minimal profile (role + capabilities), no descriptive options.
    pub fn new(public_key: PublicKey, role: NodeRole, capabilities: NodeCapabilities) -> Self {
        Self {
            public_key,
            role,
            capabilities,
            name: None,
            location: None,
            altitude_m: None,
            supported_regions: None,
            clock: || None,
        }
    }

    /// Set the display name (builder style).
    pub fn with_name(mut self, name: impl Into<String>) -> Self {
        self.name = Some(name.into());
        self
    }

    /// Set the geographic location (builder style).
    pub fn with_location(mut self, location: NodeLocation) -> Self {
        self.location = Some(location);
        self
    }

    /// This node's hint, derived from its public key.
    pub fn hint(&self) -> NodeHint {
        self.public_key.hint()
    }

    /// Build the (unsigned) identity payload this node advertises,
    /// stamping `nonce` into option 5.
    ///
    /// The one canonical builder, deliberately shared by both framings of
    /// a node identity: the Identity Request reply, which carries a
    /// request nonce and is authenticated by the enclosing unicast, and
    /// the standalone signed blob, which carries no nonce and is
    /// authenticated by a detached signature. They are different objects
    /// on the wire and the same statement about the node; the difference
    /// must not be able to drift into the contents.
    pub fn to_payload(&self, nonce: Option<u32>) -> NodeIdentityPayload {
        NodeIdentityPayload {
            role: self.role,
            capabilities: self.capabilities,
            name: self.name.clone(),
            location: self.location,
            altitude_m: self.altitude_m,
            // Option 3 dates this payload, so it is read now rather than
            // carried: the freshness marker exists to stop a captured
            // identity being presented indefinitely, and a stamp copied
            // from an earlier build would be exactly that capture.
            timestamp: (self.clock)(),
            supported_regions: self.supported_regions.clone(),
            nonce,
            signature: None,
        }
    }
}

/// Reception context for an incoming Identity Request, handed to the respond
/// policy so it can decide whether — and how — to answer.
///
/// The request has already passed the filter gate (its `FILTER_*` options
/// select this node) and its source has already been resolved to a key, so the
/// policy only governs the "do I want to answer *this sender*?" decision.
pub struct IdentityRequestContext<'a> {
    /// Resolved sender key. Always present: an unresolvable source is dropped
    /// before the policy runs.
    pub from_key: PublicKey,
    /// Sender hint, when the frame carried one.
    pub from_hint: Option<NodeHint>,
    /// Whether the request frame was authenticated (pairwise or channel MIC).
    pub source_authenticated: bool,
    /// Whether the request carried the sender's full 32-byte key.
    pub has_full_source: bool,
    /// The channel the request arrived on, if any (`None` for plain
    /// broadcast/unicast).
    pub channel: Option<ChannelId>,
    /// Coarse packet family (Unicast / Broadcast / Multicast / BlindUnicast).
    pub family: PacketFamily,
    /// The request's filter/option block, for policies that inspect it further.
    pub filters: IdentityRequestFilters<'a>,
    /// Received signal strength of the request, if measured.
    pub rssi: Option<i16>,
    /// Signal-to-noise ratio of the request, if measured.
    pub snr: Option<Snr>,
}

/// A respond policy's verdict for one Identity Request.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum RespondDecision {
    /// Do not answer this request.
    Ignore,
    /// Answer with an authenticated unicast identity response.
    Respond {
        /// Include our full 32-byte key in the reply's source address, so a
        /// requester that only had our hint can authenticate the reply without
        /// a prior key exchange. Set `false` only when the requester already
        /// holds our key.
        full_source: bool,
    },
}

/// A registerable respond policy: given the request context, decide the verdict.
pub type RespondPolicy = dyn FnMut(&IdentityRequestContext<'_>) -> RespondDecision;

/// The default respond policy: answer every request that reached the policy.
///
/// Includes our full source key unless the request was authenticated to us
/// (an authenticated pairwise request implies the sender already holds our
/// key). The blind-unicast-over-channel case, where a channel-authenticated
/// sender may still lack our key, is a known edge a custom policy can override.
pub fn default_respond_policy(ctx: &IdentityRequestContext<'_>) -> RespondDecision {
    RespondDecision::Respond {
        full_source: !ctx.source_authenticated,
    }
}

/// A respond policy that answers nothing.
///
/// Lets a node keep a live profile while declining to be discovered. The
/// profile is what unsolicited advertisements are built from, so silencing
/// the responder this way — rather than by uninstalling it — is what keeps
/// the two behaviours independent.
pub fn never_respond_policy(_ctx: &IdentityRequestContext<'_>) -> RespondDecision {
    RespondDecision::Ignore
}

/// Installed responder state: the profile plus the active policy.
pub(crate) struct IdentityResponder {
    pub(crate) profile: NodeIdentityProfile,
    pub(crate) policy: Box<RespondPolicy>,
}

/// A resolved plan to answer one Identity Request, produced synchronously while
/// the node state is borrowed and executed later by the async pump.
pub(crate) struct IdentityResponsePlan {
    /// Destination (the requester).
    pub(crate) to: PublicKey,
    /// Whether the reply should carry our full source key.
    pub(crate) full_source: bool,
    /// Whether the reply must be held for a random delay before transmit.
    /// Set for broadcast/multicast solicitations, where every selected node
    /// answers at once and undelayed replies would collide on the channel.
    pub(crate) delayed: bool,
    /// Whether the reply must carry no flood hop count field at all.
    /// Set for a solicitation that no `FILTER_NODE_HINT` narrowed: such a
    /// request was confined to the requester's neighbours on the way in, and
    /// its reply stays there too rather than being flooded back.
    pub(crate) no_flood: bool,
    /// The framed reply payload: `PayloadType::NodeIdentity` + encoded identity.
    pub(crate) framed: Vec<u8>,
}

impl IdentityResponder {
    /// Evaluate an incoming request against the profile and policy.
    ///
    /// Returns `Some(plan)` when the node should answer: the request's filters
    /// select this node **and** the policy returns `Respond`. Returns `None`
    /// otherwise (not selected, policy said `Ignore`, or the reply could not be
    /// encoded).
    pub(crate) fn evaluate(
        &mut self,
        ctx: &IdentityRequestContext<'_>,
    ) -> Option<IdentityResponsePlan> {
        // Filter gate: does this request target a node like us?
        let our_hint = self.profile.hint();
        if !ctx
            .filters
            .selects(self.profile.role, self.profile.capabilities, &our_hint)
            .unwrap_or(false)
        {
            return None;
        }

        // Policy gate: do we want to answer this particular sender?
        let full_source = match (self.policy)(ctx) {
            RespondDecision::Ignore => return None,
            RespondDecision::Respond { full_source } => full_source,
        };

        // Build the framed reply, echoing the request nonce into option 5.
        let nonce = ctx.filters.nonce().ok().flatten();
        let payload = self.profile.to_payload(nonce);
        let mut buf = [0u8; 192];
        buf[0] = PayloadType::NodeIdentity as u8;
        let len = 1 + payload.encode(&mut buf[1..]).ok()?;
        let solicitation = matches!(
            ctx.family,
            crate::PacketFamily::Broadcast | crate::PacketFamily::Multicast
        );
        Some(IdentityResponsePlan {
            to: ctx.from_key,
            full_source,
            delayed: solicitation,
            no_flood: solicitation && !ctx.filters.hint_filtered(),
            framed: Vec::from(&buf[..len]),
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::location::NodeLocation;

    /// A profile's position reaches the wire, and every payload built
    /// from it is dated when it was built rather than carrying a stamp
    /// from some earlier one.
    #[test]
    fn a_profile_position_reaches_the_wire_dated_at_build_time() {
        let mut profile = NodeIdentityProfile::new(
            PublicKey([9; 32]),
            NodeRole::Tracker,
            NodeCapabilities::empty(),
        );
        let here = NodeLocation::from_e7(377_749_000, -1_224_194_000, 5);
        profile.location = Some(here);
        profile.altitude_m = Some(-17);
        profile.clock = || Some(1_785_000_000);

        let payload = profile.to_payload(None);
        let mut buf = [0u8; 192];
        let len = payload.encode(&mut buf).expect("encode");
        let decoded = NodeIdentityPayload::from_bytes(&buf[..len]).expect("decode");

        assert_eq!(decoded.location, Some(here));
        assert_eq!(decoded.altitude_m, Some(-17));
        assert_eq!(decoded.timestamp, Some(1_785_000_000));
    }

    /// A node that does not know what time it is omits option 3 rather
    /// than inventing a date for the payload.
    #[test]
    fn a_clockless_node_omits_the_timestamp() {
        let profile = NodeIdentityProfile::new(
            PublicKey([9; 32]),
            NodeRole::Tracker,
            NodeCapabilities::empty(),
        );
        assert_eq!(profile.to_payload(None).timestamp, None);
    }
}