async_snmp/agent/

vacm.rs

//! View-based Access Control Model (RFC 3415).
//!
//! VACM controls access to MIB objects based on who is making the request
//! and what they are trying to access. It implements fine-grained access control
//! through a three-table architecture.
//!
//! # Overview
//!
//! VACM (View-based Access Control Model) is the standard access control mechanism
//! for `SNMPv3`, though it can also be used with SNMPv1/v2c. It answers the question:
//! "Can this user perform this operation on this OID?"
//!
//! # Architecture
//!
//! VACM controls access through three tables:
//!
//! 1. **Security-to-Group Table**: Maps (securityModel, securityName) to groupName.
//!    This groups users/communities with similar access rights.
//!
//! 2. **Access Table**: Maps (groupName, contextPrefix, securityModel, securityLevel)
//!    to view names for read, write, and notify operations.
//!
//! 3. **View Tree Family Table**: Defines views as collections of OID subtrees,
//!    with optional inclusion/exclusion and wildcard masks.
//!
//! # Basic Example
//!
//! Configure read-only access for "public" community:
//!
//! ```rust
//! use async_snmp::agent::{Agent, SecurityModel, VacmBuilder};
//! use async_snmp::oid;
//!
//! # fn example() {
//! let vacm = VacmBuilder::new()
//!     // Map "public" community to "readonly_group"
//!     .group("public", SecurityModel::V2c, "readonly_group")
//!     // Grant read access to full_view
//!     .access("readonly_group", |a| a.read_view("full_view"))
//!     // Define what OIDs are in full_view
//!     .view("full_view", |v| v.include(oid!(1, 3, 6, 1)))
//!     .build();
//! # }
//! ```
//!
//! # Read/Write Access Example
//!
//! Configure different access levels for different users:
//!
//! ```rust
//! use async_snmp::agent::{Agent, SecurityModel, VacmBuilder};
//! use async_snmp::message::SecurityLevel;
//! use async_snmp::oid;
//!
//! # fn example() {
//! let vacm = VacmBuilder::new()
//!     // Read-only community
//!     .group("public", SecurityModel::V2c, "readers")
//!     // Read-write community
//!     .group("private", SecurityModel::V2c, "writers")
//!     // SNMPv3 admin user
//!     .group("admin", SecurityModel::Usm, "admins")
//!
//!     // Readers can only read
//!     .access("readers", |a| a
//!         .read_view("system_view"))
//!
//!     // Writers can read everything and write to ifAdminStatus
//!     .access("writers", |a| a
//!         .read_view("full_view")
//!         .write_view("if_admin_view"))
//!
//!     // Admins require encryption and can read/write everything
//!     .access("admins", |a| a
//!         .security_model(SecurityModel::Usm)
//!         .security_level(SecurityLevel::AuthPriv)
//!         .read_view("full_view")
//!         .write_view("full_view"))
//!
//!     // Define views
//!     .view("system_view", |v| v
//!         .include(oid!(1, 3, 6, 1, 2, 1, 1)))  // system MIB only
//!     .view("full_view", |v| v
//!         .include(oid!(1, 3, 6, 1)))           // everything
//!     .view("if_admin_view", |v| v
//!         .include(oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 7)))  // ifAdminStatus
//!     .build();
//! # }
//! ```
//!
//! # View Exclusions
//!
//! Views can exclude specific subtrees from a broader include:
//!
//! ```rust
//! use async_snmp::agent::View;
//! use async_snmp::oid;
//!
//! // Include all of system MIB except sysServices
//! let view = View::new()
//!     .include(oid!(1, 3, 6, 1, 2, 1, 1))        // system MIB
//!     .exclude(oid!(1, 3, 6, 1, 2, 1, 1, 7));    // except sysServices
//!
//! assert!(view.contains(&oid!(1, 3, 6, 1, 2, 1, 1, 1, 0)));   // sysDescr.0 - allowed
//! assert!(!view.contains(&oid!(1, 3, 6, 1, 2, 1, 1, 7, 0)));  // sysServices.0 - blocked
//! ```
//!
//! # Wildcard Masks
//!
//! Masks allow matching OIDs with wildcards at specific positions:
//!
//! ```rust
//! use async_snmp::agent::ViewSubtree;
//! use async_snmp::oid;
//!
//! // Match ifDescr for any interface index (ifDescr.*)
//! // OID: 1.3.6.1.2.1.2.2.1.2 (10 arcs, indices 0-9)
//! // Mask: 0xFF 0xC0 = 11111111 11000000 (arcs 0-9 must match, 10+ wildcard)
//! let subtree = ViewSubtree {
//!     oid: oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 2),  // ifDescr
//!     mask: vec![0xFF, 0xC0],
//!     included: true,
//! };
//!
//! // Matches any interface index
//! assert!(subtree.matches(&oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 2, 1)));    // ifDescr.1
//! assert!(subtree.matches(&oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 2, 100)));  // ifDescr.100
//!
//! // Does not match different columns
//! assert!(!subtree.matches(&oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 3, 1)));   // ifType.1
//! ```
//!
//! # Integration with Agent
//!
//! Use [`AgentBuilder::vacm()`](super::AgentBuilder::vacm) to configure VACM:
//!
//! ```rust,no_run
//! use async_snmp::agent::{Agent, SecurityModel};
//! use async_snmp::oid;
//!
//! # async fn example() -> Result<(), Box<async_snmp::Error>> {
//! let agent = Agent::builder()
//!     .bind("0.0.0.0:161")
//!     .community(b"public")
//!     .community(b"private")
//!     .vacm(|v| v
//!         .group("public", SecurityModel::V2c, "readonly")
//!         .group("private", SecurityModel::V2c, "readwrite")
//!         .access("readonly", |a| a.read_view("all"))
//!         .access("readwrite", |a| a.read_view("all").write_view("all"))
//!         .view("all", |v| v.include(oid!(1, 3, 6, 1))))
//!     .build()
//!     .await?;
//! # Ok(())
//! # }
//! ```
//!
//! # Access Denied Behavior
//!
//! When VACM denies access:
//! - **`SNMPv1`**: Returns `noSuchName` error
//! - **SNMPv2c/v3 GET**: Returns `noAccess` error or `NoSuchObject` per RFC 3416
//! - **SNMPv2c/v3 SET**: Returns `noAccess` error

use std::collections::HashMap;

use bytes::Bytes;

use crate::message::SecurityLevel;
use crate::oid::Oid;

pub use crate::handler::SecurityModel;

/// Context matching mode for access entries.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub(crate) enum ContextMatch {
    /// Exact context name match.
    #[default]
    Exact,
    /// Context name prefix match.
    Prefix,
}

/// Result of checking whether a subtree is in a view.
///
/// This 3-state result enables optimizations for GETBULK/GETNEXT operations
/// by distinguishing between definite inclusion, definite exclusion, and
/// mixed/ambiguous subtrees that require per-OID checking.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ViewCheckResult {
    /// The queried OID and all its descendants are definitely in the view.
    Included,
    /// The queried OID and all its descendants are definitely not in the view.
    Excluded,
    /// The subtree has mixed permissions - some descendants are included,
    /// others are excluded. Per-OID access checks are required.
    Ambiguous,
}

/// A view is a collection of OID subtrees defining accessible objects.
///
/// Views are used by VACM to determine which OIDs a user can access.
/// Each view consists of included and/or excluded subtrees.
///
/// # Example
///
/// ```rust
/// use async_snmp::agent::View;
/// use async_snmp::oid;
///
/// // Create a view that includes the system MIB but excludes sysContact
/// let view = View::new()
///     .include(oid!(1, 3, 6, 1, 2, 1, 1))        // system MIB
///     .exclude(oid!(1, 3, 6, 1, 2, 1, 1, 4));    // sysContact
///
/// assert!(view.contains(&oid!(1, 3, 6, 1, 2, 1, 1, 1, 0)));   // sysDescr.0
/// assert!(!view.contains(&oid!(1, 3, 6, 1, 2, 1, 1, 4, 0)));  // sysContact.0
/// assert!(!view.contains(&oid!(1, 3, 6, 1, 2, 1, 2)));        // interfaces MIB
/// ```
#[derive(Debug, Clone, Default)]
pub struct View {
    subtrees: Vec<ViewSubtree>,
}

impl View {
    /// Create a new empty view.
    ///
    /// An empty view contains no OIDs. Add subtrees with [`include()`](View::include)
    /// or [`exclude()`](View::exclude).
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Add an included subtree to the view.
    ///
    /// All OIDs starting with `oid` will be included in the view,
    /// unless excluded by a later [`exclude()`](View::exclude) call.
    ///
    /// # Example
    ///
    /// ```rust
    /// use async_snmp::agent::View;
    /// use async_snmp::oid;
    ///
    /// let view = View::new()
    ///     .include(oid!(1, 3, 6, 1, 2, 1))  // MIB-2
    ///     .include(oid!(1, 3, 6, 1, 4, 1)); // enterprises
    ///
    /// assert!(view.contains(&oid!(1, 3, 6, 1, 2, 1, 1, 0)));
    /// assert!(view.contains(&oid!(1, 3, 6, 1, 4, 1, 99999, 1)));
    /// ```
    #[must_use]
    pub fn include(mut self, oid: Oid) -> Self {
        self.subtrees.push(ViewSubtree {
            oid,
            mask: Vec::new(),
            included: true,
        });
        self
    }

    /// Add an included subtree with a wildcard mask.
    ///
    /// The mask allows wildcards at specific OID arc positions.
    /// See [`ViewSubtree::mask`] for mask format details.
    ///
    /// # Example
    ///
    /// ```rust
    /// use async_snmp::agent::View;
    /// use async_snmp::oid;
    ///
    /// // Include ifDescr for any interface (mask makes arc 10 a wildcard)
    /// let view = View::new()
    ///     .include_masked(
    ///         oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 2),  // ifDescr
    ///         vec![0xFF, 0xC0]  // First 10 arcs must match
    ///     );
    ///
    /// assert!(view.contains(&oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 2, 1)));   // ifDescr.1
    /// assert!(view.contains(&oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 2, 100))); // ifDescr.100
    /// ```
    #[must_use]
    pub fn include_masked(mut self, oid: Oid, mask: Vec<u8>) -> Self {
        self.subtrees.push(ViewSubtree {
            oid,
            mask,
            included: true,
        });
        self
    }

    /// Add an excluded subtree to the view.
    ///
    /// OIDs starting with `oid` will be excluded, even if they match
    /// an included subtree. Exclusions take precedence.
    ///
    /// # Example
    ///
    /// ```rust
    /// use async_snmp::agent::View;
    /// use async_snmp::oid;
    ///
    /// let view = View::new()
    ///     .include(oid!(1, 3, 6, 1, 2, 1, 1))     // system MIB
    ///     .exclude(oid!(1, 3, 6, 1, 2, 1, 1, 6)); // except sysLocation
    ///
    /// assert!(view.contains(&oid!(1, 3, 6, 1, 2, 1, 1, 1, 0)));  // sysDescr
    /// assert!(!view.contains(&oid!(1, 3, 6, 1, 2, 1, 1, 6, 0))); // sysLocation
    /// ```
    #[must_use]
    pub fn exclude(mut self, oid: Oid) -> Self {
        self.subtrees.push(ViewSubtree {
            oid,
            mask: Vec::new(),
            included: false,
        });
        self
    }

    /// Add an excluded subtree with a wildcard mask.
    ///
    /// See [`include_masked()`](View::include_masked) for mask usage.
    #[must_use]
    pub fn exclude_masked(mut self, oid: Oid, mask: Vec<u8>) -> Self {
        self.subtrees.push(ViewSubtree {
            oid,
            mask,
            included: false,
        });
        self
    }

    /// Check if an OID is in this view.
    ///
    /// Per RFC 3415 Section 5, when multiple subtrees match an OID, the entry
    /// with the most sub-identifiers determines inclusion/exclusion. When
    /// several matching entries have the same number of sub-identifiers, the
    /// one with the lexicographically greatest subtree OID decides, so the
    /// result does not depend on the order subtrees were added. Identical
    /// subtree OIDs cannot coexist in a real `vacmViewTreeFamilyTable`; that
    /// degenerate collision is resolved conservatively (exclude wins).
    ///
    /// # Example
    ///
    /// ```rust
    /// use async_snmp::agent::View;
    /// use async_snmp::oid;
    ///
    /// let view = View::new()
    ///     .include(oid!(1, 3, 6, 1, 2, 1))
    ///     .exclude(oid!(1, 3, 6, 1, 2, 1, 25));  // host resources
    ///
    /// assert!(view.contains(&oid!(1, 3, 6, 1, 2, 1, 1, 0)));
    /// assert!(!view.contains(&oid!(1, 3, 6, 1, 2, 1, 25, 1, 0)));
    /// assert!(!view.contains(&oid!(1, 3, 6, 1, 4, 1)));  // not included
    /// ```
    #[must_use]
    pub fn contains(&self, oid: &Oid) -> bool {
        let mut best: Option<(&[u32], bool)> = None;

        for subtree in &self.subtrees {
            if subtree.matches(oid) {
                let arcs = subtree.oid.arcs();
                if view_match_wins(best, arcs, subtree.included) {
                    best = Some((arcs, subtree.included));
                }
            }
        }

        best.is_some_and(|(_, included)| included)
    }

    /// Check subtree access status with 3-state result.
    ///
    /// Unlike [`contains()`](View::contains) which checks a single OID,
    /// this method determines the access status for an entire subtree.
    /// This enables optimizations for GETBULK/GETNEXT operations.
    ///
    /// Returns:
    /// - [`ViewCheckResult::Included`]: OID and all descendants are accessible
    /// - [`ViewCheckResult::Excluded`]: OID and all descendants are not accessible
    /// - [`ViewCheckResult::Ambiguous`]: Mixed permissions, check each OID individually
    #[must_use]
    pub fn check_subtree(&self, oid: &Oid) -> ViewCheckResult {
        // Find the best covering match (RFC 3415: most sub-identifiers, then
        // lexicographically greatest subtree OID; see `view_match_wins`).
        let mut best_covering: Option<(&[u32], bool)> = None;
        let mut has_child_include = false;
        let mut has_child_exclude = false;

        let query_arcs = oid.arcs();

        for subtree in &self.subtrees {
            let subtree_arcs = subtree.oid.arcs();

            if subtree.matches(oid)
                && view_match_wins(best_covering, subtree_arcs, subtree.included)
            {
                best_covering = Some((subtree_arcs, subtree.included));
            }

            // A strictly longer subtree whose family (under its mask) covers a
            // descendant of the query contributes a child include/exclude.
            if subtree_arcs.len() > query_arcs.len() && subtree.prefix_matches(query_arcs) {
                if subtree.included {
                    has_child_include = true;
                } else {
                    has_child_exclude = true;
                }
            }
        }

        match best_covering {
            Some((_, false)) => {
                if has_child_include {
                    ViewCheckResult::Ambiguous
                } else {
                    ViewCheckResult::Excluded
                }
            }
            Some((_, true)) => {
                if has_child_exclude {
                    ViewCheckResult::Ambiguous
                } else {
                    ViewCheckResult::Included
                }
            }
            None => {
                if has_child_include {
                    ViewCheckResult::Ambiguous
                } else {
                    ViewCheckResult::Excluded
                }
            }
        }
    }
}

/// RFC 3415 tie-break for overlapping MIB-view subtree matches.
///
/// Given the current best matching entry (its subtree OID arcs and `included`
/// flag) and a candidate match, returns whether the candidate should replace
/// the current best:
///
/// - more sub-identifiers wins;
/// - at equal sub-identifier counts, the lexicographically greater subtree OID
///   wins (the "lexicographically greatest instance" rule of the
///   `vacmViewTreeFamilyTable` DESCRIPTION);
/// - identical subtree OIDs form an index collision that cannot occur in a real
///   table; it is resolved conservatively by letting an exclude replace an
///   include so the outcome is independent of insertion order.
fn view_match_wins(best: Option<(&[u32], bool)>, arcs: &[u32], included: bool) -> bool {
    match best {
        None => true,
        Some((best_arcs, best_included)) => {
            if arcs.len() != best_arcs.len() {
                arcs.len() > best_arcs.len()
            } else if arcs != best_arcs {
                arcs > best_arcs
            } else {
                best_included && !included
            }
        }
    }
}

/// A subtree in a view with optional mask.
#[derive(Debug, Clone)]
pub struct ViewSubtree {
    /// Base OID of subtree.
    pub oid: Oid,
    /// Bit mask for wildcard matching (empty = exact match).
    ///
    /// Each bit position corresponds to an arc in the OID:
    /// - Bit 7 (MSB) of byte 0 = arc 0
    /// - Bit 6 of byte 0 = arc 1
    /// - etc.
    ///
    /// A bit value of 1 means the arc must match exactly.
    /// A bit value of 0 means any value is accepted (wildcard).
    pub mask: Vec<u8>,
    /// Include (true) or exclude (false) this subtree.
    pub included: bool,
}

impl ViewSubtree {
    /// Whether arc position `i` requires an exact match.
    ///
    /// A mask bit of 1 (or a position past the mask) means the arc must match
    /// exactly; a bit of 0 is a wildcard. Bit 7 (MSB) of byte 0 is arc 0.
    fn arc_is_exact(&self, i: usize) -> bool {
        if i / 8 < self.mask.len() {
            (self.mask[i / 8] >> (7 - (i % 8))) & 1 == 1
        } else {
            true // Default: exact match required
        }
    }

    /// Whether the first `arcs.len()` arcs of this subtree match `arcs` under
    /// the mask. Callers guarantee `self.oid` has at least `arcs.len()` arcs.
    fn prefix_matches(&self, arcs: &[u32]) -> bool {
        let subtree_arcs = self.oid.arcs();
        arcs.iter()
            .enumerate()
            .all(|(i, &arc)| !self.arc_is_exact(i) || subtree_arcs[i] == arc)
    }

    /// Check if an OID matches this subtree (with mask).
    #[must_use]
    pub fn matches(&self, oid: &Oid) -> bool {
        let subtree_arcs = self.oid.arcs();
        let oid_arcs = oid.arcs();

        // OID must be at least as long as subtree
        if oid_arcs.len() < subtree_arcs.len() {
            return false;
        }

        // Every subtree arc must match the OID under the mask.
        self.prefix_matches(&oid_arcs[..subtree_arcs.len()])
    }
}

/// Access table entry.
#[derive(Debug, Clone)]
pub struct VacmAccessEntry {
    /// Group name this entry applies to.
    pub group_name: Bytes,
    /// Context prefix for matching.
    pub context_prefix: Bytes,
    /// Security model (or Any for wildcard).
    pub security_model: SecurityModel,
    /// Minimum security level required.
    pub security_level: SecurityLevel,
    /// Context matching mode.
    pub(crate) context_match: ContextMatch,
    /// View name for read access.
    pub read_view: Bytes,
    /// View name for write access.
    pub write_view: Bytes,
    /// View name for notify access (traps/informs).
    pub notify_view: Bytes,
}

/// Builder for access entries.
///
/// Configure what views a group can access for different operations.
/// Typically used via [`VacmBuilder::access()`].
///
/// # Example
///
/// ```rust
/// use async_snmp::agent::{SecurityModel, VacmBuilder};
/// use async_snmp::message::SecurityLevel;
/// use async_snmp::oid;
///
/// let vacm = VacmBuilder::new()
///     .group("admin", SecurityModel::Usm, "admin_group")
///     .access("admin_group", |a| a
///         .security_model(SecurityModel::Usm)
///         .security_level(SecurityLevel::AuthPriv)
///         .read_view("full_view")
///         .write_view("config_view")
///         .notify_view("trap_view"))
///     .view("full_view", |v| v.include(oid!(1, 3, 6, 1)))
///     .view("config_view", |v| v.include(oid!(1, 3, 6, 1, 4, 1)))
///     .view("trap_view", |v| v.include(oid!(1, 3, 6, 1)))
///     .build();
/// ```
pub struct AccessEntryBuilder {
    group_name: Bytes,
    context_prefix: Bytes,
    security_model: SecurityModel,
    security_level: SecurityLevel,
    context_match: ContextMatch,
    read_view: Bytes,
    write_view: Bytes,
    notify_view: Bytes,
}

impl AccessEntryBuilder {
    /// Create a new access entry builder for a group.
    pub fn new(group_name: impl Into<Bytes>) -> Self {
        Self {
            group_name: group_name.into(),
            context_prefix: Bytes::new(),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Exact,
            read_view: Bytes::new(),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        }
    }

    /// Set the context prefix for matching.
    ///
    /// Context is an `SNMPv3` concept that allows partitioning MIB views.
    /// Most deployments use an empty context (the default).
    #[must_use]
    pub fn context_prefix(mut self, prefix: impl Into<Bytes>) -> Self {
        self.context_prefix = prefix.into();
        self
    }

    /// Set the security model this entry applies to.
    ///
    /// Default is [`SecurityModel::Any`] which matches all models.
    #[must_use]
    pub fn security_model(mut self, model: SecurityModel) -> Self {
        self.security_model = model;
        self
    }

    /// Set the minimum security level required.
    ///
    /// Requests with lower security levels will be denied access.
    /// Default is [`SecurityLevel::NoAuthNoPriv`].
    ///
    /// # Example
    ///
    /// ```rust
    /// use async_snmp::agent::{SecurityModel, VacmBuilder};
    /// use async_snmp::message::SecurityLevel;
    /// use async_snmp::oid;
    ///
    /// let vacm = VacmBuilder::new()
    ///     .group("admin", SecurityModel::Usm, "secure_group")
    ///     .access("secure_group", |a| a
    ///         // Require authentication and encryption
    ///         .security_level(SecurityLevel::AuthPriv)
    ///         .read_view("full_view"))
    ///     .view("full_view", |v| v.include(oid!(1, 3, 6, 1)))
    ///     .build();
    /// ```
    #[must_use]
    pub fn security_level(mut self, level: SecurityLevel) -> Self {
        self.security_level = level;
        self
    }

    /// Set context matching to prefix mode.
    ///
    /// When enabled, the context prefix is matched against the start of
    /// the request context name rather than requiring an exact match.
    /// The default is exact matching.
    #[must_use]
    pub fn context_match_prefix(mut self) -> Self {
        self.context_match = ContextMatch::Prefix;
        self
    }

    /// Set the read view name.
    ///
    /// The view must be defined with [`VacmBuilder::view()`].
    /// If not set, read operations are denied.
    #[must_use]
    pub fn read_view(mut self, view: impl Into<Bytes>) -> Self {
        self.read_view = view.into();
        self
    }

    /// Set the write view name.
    ///
    /// The view must be defined with [`VacmBuilder::view()`].
    /// If not set, write (SET) operations are denied.
    #[must_use]
    pub fn write_view(mut self, view: impl Into<Bytes>) -> Self {
        self.write_view = view.into();
        self
    }

    /// Set the notify view name.
    ///
    /// Used for trap/inform generation (not access control).
    /// The view must be defined with [`VacmBuilder::view()`].
    #[must_use]
    pub fn notify_view(mut self, view: impl Into<Bytes>) -> Self {
        self.notify_view = view.into();
        self
    }

    /// Build the access entry.
    pub fn build(self) -> VacmAccessEntry {
        VacmAccessEntry {
            group_name: self.group_name,
            context_prefix: self.context_prefix,
            security_model: self.security_model,
            security_level: self.security_level,
            context_match: self.context_match,
            read_view: self.read_view,
            write_view: self.write_view,
            notify_view: self.notify_view,
        }
    }
}

/// VACM configuration.
#[derive(Debug, Clone, Default)]
pub struct VacmConfig {
    /// (securityModel, securityName) → groupName
    security_to_group: HashMap<(SecurityModel, Bytes), Bytes>,
    /// Access table entries.
    access_entries: Vec<VacmAccessEntry>,
    /// viewName → View
    views: HashMap<Bytes, View>,
}

impl VacmConfig {
    /// Create a new empty VACM configuration.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Map a security name to a group for a specific security model.
    pub fn add_group(
        &mut self,
        security_name: impl Into<Bytes>,
        security_model: SecurityModel,
        group_name: impl Into<Bytes>,
    ) {
        self.security_to_group
            .insert((security_model, security_name.into()), group_name.into());
    }

    /// Add an access entry.
    pub fn add_access(&mut self, entry: VacmAccessEntry) {
        self.access_entries.push(entry);
    }

    /// Add a view.
    pub fn add_view(&mut self, name: impl Into<Bytes>, view: View) {
        self.views.insert(name.into(), view);
    }

    /// Resolve group name for a request.
    #[must_use]
    pub fn get_group(&self, model: SecurityModel, name: &[u8]) -> Option<&Bytes> {
        // Try exact model match first, then fall back to Any.
        // Iterate to avoid allocating a Bytes for the lookup key.
        let mut any_match = None;
        for ((entry_model, entry_name), group) in &self.security_to_group {
            if entry_name.as_ref() == name {
                if *entry_model == model {
                    return Some(group);
                } else if *entry_model == SecurityModel::Any {
                    any_match = Some(group);
                }
            }
        }
        any_match
    }

    /// Get access entry for context.
    ///
    /// Returns the best matching entry per RFC 3415 Section 4 (vacmAccessTable DESCRIPTION).
    /// Selection uses a 4-tier preference order:
    /// 1. Prefer specific securityModel over Any
    /// 2. Prefer exact contextMatch over prefix
    /// 3. Prefer longer contextPrefix
    /// 4. Prefer higher securityLevel
    #[must_use]
    pub fn get_access(
        &self,
        group: &[u8],
        context: &[u8],
        model: SecurityModel,
        level: SecurityLevel,
    ) -> Option<&VacmAccessEntry> {
        self.access_entries
            .iter()
            .filter(|e| {
                e.group_name.as_ref() == group
                    && self.context_matches(&e.context_prefix, context, e.context_match)
                    && (e.security_model == model || e.security_model == SecurityModel::Any)
                    && level >= e.security_level
            })
            .max_by_key(|e| {
                // RFC 3415 Section 4 preference order (tuple comparison is lexicographic)
                let model_score: u8 = u8::from(e.security_model == model);
                let match_score: u8 = u8::from(e.context_match == ContextMatch::Exact);
                let prefix_len = e.context_prefix.len();
                let level_score = e.security_level as u8;
                (model_score, match_score, prefix_len, level_score)
            })
    }

    /// Check if context matches the prefix.
    fn context_matches(&self, prefix: &[u8], context: &[u8], mode: ContextMatch) -> bool {
        match mode {
            ContextMatch::Exact => prefix == context,
            ContextMatch::Prefix => context.starts_with(prefix),
        }
    }

    /// Check if OID access is permitted.
    #[must_use]
    pub fn check_access(&self, view_name: Option<&Bytes>, oid: &Oid) -> bool {
        let Some(view_name) = view_name else {
            return false;
        };

        if view_name.is_empty() {
            return false;
        }

        let Some(view) = self.views.get(view_name) else {
            return false;
        };

        view.contains(oid)
    }
}

/// Builder for VACM configuration.
///
/// Use this to configure access control for your SNMP agent. The typical
/// workflow is:
///
/// 1. Map security names (communities/usernames) to groups with [`group()`](VacmBuilder::group)
/// 2. Define access rules for groups with [`access()`](VacmBuilder::access)
/// 3. Define views (OID collections) with [`view()`](VacmBuilder::view)
/// 4. Build with [`build()`](VacmBuilder::build)
///
/// # Example
///
/// ```rust
/// use async_snmp::agent::{SecurityModel, VacmBuilder};
/// use async_snmp::message::SecurityLevel;
/// use async_snmp::oid;
///
/// let vacm = VacmBuilder::new()
///     // Step 1: Map security names to groups
///     .group("public", SecurityModel::V2c, "readers")
///     .group("admin", SecurityModel::Usm, "admins")
///
///     // Step 2: Define access for each group
///     .access("readers", |a| a
///         .read_view("system_view"))
///     .access("admins", |a| a
///         .security_level(SecurityLevel::AuthPriv)
///         .read_view("full_view")
///         .write_view("full_view"))
///
///     // Step 3: Define views
///     .view("system_view", |v| v
///         .include(oid!(1, 3, 6, 1, 2, 1, 1)))
///     .view("full_view", |v| v
///         .include(oid!(1, 3, 6, 1)))
///
///     // Step 4: Build
///     .build();
/// ```
pub struct VacmBuilder {
    config: VacmConfig,
}

impl VacmBuilder {
    /// Create a new VACM builder.
    #[must_use]
    pub fn new() -> Self {
        Self {
            config: VacmConfig::new(),
        }
    }

    /// Map a security name to a group.
    ///
    /// The security name is:
    /// - For SNMPv1/v2c: the community string
    /// - For `SNMPv3`: the USM username
    ///
    /// Multiple security names can map to the same group.
    ///
    /// # Example
    ///
    /// ```rust
    /// use async_snmp::agent::{SecurityModel, VacmBuilder};
    ///
    /// let vacm = VacmBuilder::new()
    ///     // Multiple communities in same group
    ///     .group("public", SecurityModel::V2c, "readonly")
    ///     .group("monitor", SecurityModel::V2c, "readonly")
    ///     // Different users in different groups
    ///     .group("admin", SecurityModel::Usm, "admin_group")
    ///     .build();
    /// ```
    #[must_use]
    pub fn group(
        mut self,
        security_name: impl Into<Bytes>,
        security_model: SecurityModel,
        group_name: impl Into<Bytes>,
    ) -> Self {
        self.config
            .add_group(security_name, security_model, group_name);
        self
    }

    /// Add an access entry using a builder function.
    ///
    /// Access entries define what views a group can use for read, write,
    /// and notify operations. Use the closure to configure the entry.
    ///
    /// # Example
    ///
    /// ```rust
    /// use async_snmp::agent::{SecurityModel, VacmBuilder};
    /// use async_snmp::message::SecurityLevel;
    /// use async_snmp::oid;
    ///
    /// let vacm = VacmBuilder::new()
    ///     .group("public", SecurityModel::V2c, "readers")
    ///     .access("readers", |a| a
    ///         .security_model(SecurityModel::V2c)
    ///         .security_level(SecurityLevel::NoAuthNoPriv)
    ///         .read_view("system_view")
    ///         // No write_view = read-only
    ///     )
    ///     .view("system_view", |v| v.include(oid!(1, 3, 6, 1, 2, 1, 1)))
    ///     .build();
    /// ```
    #[must_use]
    pub fn access<F>(mut self, group_name: impl Into<Bytes>, configure: F) -> Self
    where
        F: FnOnce(AccessEntryBuilder) -> AccessEntryBuilder,
    {
        let builder = AccessEntryBuilder::new(group_name);
        let entry = configure(builder).build();
        self.config.add_access(entry);
        self
    }

    /// Add a view using a builder function.
    ///
    /// Views define collections of OID subtrees. Use the closure to add
    /// included and excluded subtrees.
    ///
    /// # Example
    ///
    /// ```rust
    /// use async_snmp::agent::VacmBuilder;
    /// use async_snmp::oid;
    ///
    /// let vacm = VacmBuilder::new()
    ///     .view("system_only", |v| v
    ///         .include(oid!(1, 3, 6, 1, 2, 1, 1)))  // system MIB
    ///     .view("all_except_private", |v| v
    ///         .include(oid!(1, 3, 6, 1))
    ///         .exclude(oid!(1, 3, 6, 1, 4, 1, 99999)))  // exclude our enterprise
    ///     .build();
    /// ```
    #[must_use]
    pub fn view<F>(mut self, name: impl Into<Bytes>, configure: F) -> Self
    where
        F: FnOnce(View) -> View,
    {
        let view = configure(View::new());
        self.config.add_view(name, view);
        self
    }

    /// Build the VACM configuration.
    #[must_use]
    pub fn build(self) -> VacmConfig {
        self.config
    }
}

impl Default for VacmBuilder {
    fn default() -> Self {
        Self::new()
    }
}

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

    #[test]
    fn test_view_contains_simple() {
        let view = View::new().include(oid!(1, 3, 6, 1, 2, 1)); // system MIB

        // OID within the subtree
        assert!(view.contains(&oid!(1, 3, 6, 1, 2, 1, 1, 0)));
        assert!(view.contains(&oid!(1, 3, 6, 1, 2, 1, 2, 1, 1)));

        // OID exactly at subtree
        assert!(view.contains(&oid!(1, 3, 6, 1, 2, 1)));

        // OID outside the subtree
        assert!(!view.contains(&oid!(1, 3, 6, 1, 4, 1)));
        assert!(!view.contains(&oid!(1, 3, 6, 1, 2)));
    }

    #[test]
    fn test_view_exclude() {
        let view = View::new()
            .include(oid!(1, 3, 6, 1, 2, 1)) // system MIB
            .exclude(oid!(1, 3, 6, 1, 2, 1, 1, 7)); // sysServices

        // Included OIDs
        assert!(view.contains(&oid!(1, 3, 6, 1, 2, 1, 1, 0)));
        assert!(view.contains(&oid!(1, 3, 6, 1, 2, 1, 1, 1, 0)));

        // Excluded OID
        assert!(!view.contains(&oid!(1, 3, 6, 1, 2, 1, 1, 7)));
        assert!(!view.contains(&oid!(1, 3, 6, 1, 2, 1, 1, 7, 0)));
    }

    #[test]
    fn test_view_longest_match_wins() {
        // RFC 3415 Section 5: when multiple subtrees match, longest match wins.
        // include(1.3.6.1) + exclude(1.3.6.1.2) + include(1.3.6.1.2.1)
        // For OID 1.3.6.1.2.1.1.0, all three match. Longest is include(1.3.6.1.2.1),
        // so the OID should be accessible.
        let view = View::new()
            .include(oid!(1, 3, 6, 1))
            .exclude(oid!(1, 3, 6, 1, 2))
            .include(oid!(1, 3, 6, 1, 2, 1));

        // Longest match is include(1.3.6.1.2.1), so this should be included
        assert!(view.contains(&oid!(1, 3, 6, 1, 2, 1, 1, 0)));

        // OID under the exclude but not re-included
        assert!(!view.contains(&oid!(1, 3, 6, 1, 2, 3, 1, 0)));

        // OID only under the top-level include, not under exclude
        assert!(view.contains(&oid!(1, 3, 6, 1, 4, 1, 0)));
    }

    #[test]
    fn test_view_longest_match_exclude_wins() {
        // When longest match is an exclude, OID should be excluded
        let view = View::new()
            .include(oid!(1, 3, 6, 1))
            .exclude(oid!(1, 3, 6, 1, 2, 1));

        assert!(!view.contains(&oid!(1, 3, 6, 1, 2, 1, 1, 0)));
        assert!(view.contains(&oid!(1, 3, 6, 1, 4, 1, 0)));
    }

    #[test]
    fn test_view_equal_length_exclude_wins() {
        // When include and exclude have equal match length, exclude should win
        // (conservative interpretation: deny beats allow at same specificity)
        let view = View::new()
            .include(oid!(1, 3, 6, 1, 2, 1))
            .exclude(oid!(1, 3, 6, 1, 2, 1));

        assert!(!view.contains(&oid!(1, 3, 6, 1, 2, 1, 1, 0)));
    }

    #[test]
    fn test_view_equal_length_identical_oid_order_independent() {
        // T4 gap: an include and an exclude on the *same* subtree OID form an
        // index collision that cannot occur in a real vacmViewTreeFamilyTable.
        // Both insertion orders must resolve identically (exclude wins).
        let include_first = View::new()
            .include(oid!(1, 3, 6, 1, 2, 1))
            .exclude(oid!(1, 3, 6, 1, 2, 1));
        let exclude_first = View::new()
            .exclude(oid!(1, 3, 6, 1, 2, 1))
            .include(oid!(1, 3, 6, 1, 2, 1));

        let query = oid!(1, 3, 6, 1, 2, 1, 1, 0);
        assert_eq!(
            include_first.contains(&query),
            exclude_first.contains(&query),
            "identical-OID collision must be order-independent"
        );
        assert!(
            !include_first.contains(&query),
            "identical-OID collision resolves conservatively to excluded"
        );
    }

    #[test]
    fn test_view_equal_length_lexicographic_tie_break() {
        // Two equal-length masked subtrees that both match the same query OID
        // via a wildcard on the final arc. Per RFC 3415 the lexicographically
        // greatest matching subtree OID decides, independent of insertion order.
        //
        // Subtree A (include): 1.3.6.1.2.1.5.1, arc 7 wildcarded
        // Subtree B (exclude): 1.3.6.1.2.1.5.9, arc 7 wildcarded
        // B is lexicographically greater, so exclude wins -> contains == false.
        let query = oid!(1, 3, 6, 1, 2, 1, 5, 5);
        let mask = vec![0xFE]; // arcs 0-6 exact, arc 7 wildcard

        let a_then_b = View::new()
            .include_masked(oid!(1, 3, 6, 1, 2, 1, 5, 1), mask.clone())
            .exclude_masked(oid!(1, 3, 6, 1, 2, 1, 5, 9), mask.clone());
        let b_then_a = View::new()
            .exclude_masked(oid!(1, 3, 6, 1, 2, 1, 5, 9), mask.clone())
            .include_masked(oid!(1, 3, 6, 1, 2, 1, 5, 1), mask.clone());

        assert!(
            !a_then_b.contains(&query),
            "lexicographically greatest subtree (exclude) must win"
        );
        assert_eq!(
            a_then_b.contains(&query),
            b_then_a.contains(&query),
            "lexicographic tie-break must be order-independent"
        );

        // Swap the include/exclude flags: now the greater subtree is the
        // include, so inclusion must win in both insertion orders.
        let a_then_b_inc = View::new()
            .exclude_masked(oid!(1, 3, 6, 1, 2, 1, 5, 1), mask.clone())
            .include_masked(oid!(1, 3, 6, 1, 2, 1, 5, 9), mask.clone());
        let b_then_a_inc = View::new()
            .include_masked(oid!(1, 3, 6, 1, 2, 1, 5, 9), mask.clone())
            .exclude_masked(oid!(1, 3, 6, 1, 2, 1, 5, 1), mask.clone());

        assert!(
            a_then_b_inc.contains(&query),
            "lexicographically greatest subtree (include) must win"
        );
        assert_eq!(
            a_then_b_inc.contains(&query),
            b_then_a_inc.contains(&query),
            "lexicographic tie-break must be order-independent"
        );
    }

    #[test]
    fn test_check_subtree_equal_length_tie_break_order_independent() {
        // Same equal-length masked scenario as the contains tie-break test, via
        // check_subtree. The greater subtree OID (exclude) covers the query, so
        // the result is Excluded regardless of insertion order.
        let query = oid!(1, 3, 6, 1, 2, 1, 5, 5);
        let mask = vec![0xFE];

        let a_then_b = View::new()
            .include_masked(oid!(1, 3, 6, 1, 2, 1, 5, 1), mask.clone())
            .exclude_masked(oid!(1, 3, 6, 1, 2, 1, 5, 9), mask.clone());
        let b_then_a = View::new()
            .exclude_masked(oid!(1, 3, 6, 1, 2, 1, 5, 9), mask.clone())
            .include_masked(oid!(1, 3, 6, 1, 2, 1, 5, 1), mask.clone());

        assert_eq!(a_then_b.check_subtree(&query), ViewCheckResult::Excluded);
        assert_eq!(
            a_then_b.check_subtree(&query),
            b_then_a.check_subtree(&query),
            "check_subtree tie-break must be order-independent"
        );
    }

    #[test]
    fn test_view_subtree_mask() {
        // Create a view that matches ifDescr.* (any interface index)
        // The subtree OID is ifDescr (1.3.6.1.2.1.2.2.1.2) with 10 arcs (indices 0-9)
        // We want arcs 0-9 to match exactly, and arc 10+ to be wildcard
        // Mask: 0xFF = 11111111 (arcs 0-7 must match)
        //       0xC0 = 11000000 (arcs 8-9 must match, 10-15 wildcard)
        let subtree = ViewSubtree {
            oid: oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 2), // ifDescr
            mask: vec![0xFF, 0xC0],                  // 11111111 11000000 - arcs 0-9 must match
            included: true,
        };

        // Should match with any interface index in position 10
        assert!(subtree.matches(&oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 2, 1)));
        assert!(subtree.matches(&oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 2, 999)));

        // Should not match if arc 9 differs (the "2" in ifDescr)
        assert!(!subtree.matches(&oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 3, 1)));
    }

    #[test]
    fn test_vacm_group_lookup() {
        let mut config = VacmConfig::new();
        config.add_group("public", SecurityModel::V2c, "readonly_group");
        config.add_group("admin", SecurityModel::Usm, "admin_group");

        assert_eq!(
            config.get_group(SecurityModel::V2c, b"public"),
            Some(&Bytes::from_static(b"readonly_group"))
        );
        assert_eq!(
            config.get_group(SecurityModel::Usm, b"admin"),
            Some(&Bytes::from_static(b"admin_group"))
        );
        assert_eq!(config.get_group(SecurityModel::V1, b"public"), None);
    }

    #[test]
    fn test_vacm_group_any_model() {
        let mut config = VacmConfig::new();
        config.add_group("universal", SecurityModel::Any, "universal_group");

        // Should match any security model
        assert_eq!(
            config.get_group(SecurityModel::V1, b"universal"),
            Some(&Bytes::from_static(b"universal_group"))
        );
        assert_eq!(
            config.get_group(SecurityModel::V2c, b"universal"),
            Some(&Bytes::from_static(b"universal_group"))
        );
    }

    #[test]
    fn test_vacm_access_lookup() {
        let mut config = VacmConfig::new();
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"readonly_group"),
            context_prefix: Bytes::new(),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Exact,
            read_view: Bytes::from_static(b"full_view"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        let access = config.get_access(
            b"readonly_group",
            b"",
            SecurityModel::V2c,
            SecurityLevel::NoAuthNoPriv,
        );
        assert!(access.is_some());
        assert_eq!(access.unwrap().read_view, Bytes::from_static(b"full_view"));
    }

    #[test]
    fn test_vacm_access_security_level() {
        let mut config = VacmConfig::new();
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"admin_group"),
            context_prefix: Bytes::new(),
            security_model: SecurityModel::Usm,
            security_level: SecurityLevel::AuthPriv, // Require encryption
            context_match: ContextMatch::Exact,
            read_view: Bytes::from_static(b"full_view"),
            write_view: Bytes::from_static(b"full_view"),
            notify_view: Bytes::new(),
        });

        // Should not match with lower security level
        let access = config.get_access(
            b"admin_group",
            b"",
            SecurityModel::Usm,
            SecurityLevel::AuthNoPriv,
        );
        assert!(access.is_none());

        // Should match with required level
        let access = config.get_access(
            b"admin_group",
            b"",
            SecurityModel::Usm,
            SecurityLevel::AuthPriv,
        );
        assert!(access.is_some());
    }

    #[test]
    fn test_vacm_check_access() {
        let mut config = VacmConfig::new();
        config.add_view("full_view", View::new().include(oid!(1, 3, 6, 1)));

        assert!(config.check_access(
            Some(&Bytes::from_static(b"full_view")),
            &oid!(1, 3, 6, 1, 2, 1, 1, 0),
        ));

        // Empty view name = no access
        assert!(!config.check_access(Some(&Bytes::new()), &oid!(1, 3, 6, 1, 2, 1, 1, 0),));

        // None = no access
        assert!(!config.check_access(None, &oid!(1, 3, 6, 1, 2, 1, 1, 0),));

        // Unknown view = no access
        assert!(!config.check_access(
            Some(&Bytes::from_static(b"unknown_view")),
            &oid!(1, 3, 6, 1, 2, 1, 1, 0),
        ));
    }

    #[test]
    fn test_vacm_builder() {
        let config = VacmBuilder::new()
            .group("public", SecurityModel::V2c, "readonly_group")
            .group("admin", SecurityModel::Usm, "admin_group")
            .access("readonly_group", |a| {
                a.context_prefix("")
                    .security_model(SecurityModel::Any)
                    .security_level(SecurityLevel::NoAuthNoPriv)
                    .read_view("full_view")
            })
            .access("admin_group", |a| {
                a.security_model(SecurityModel::Usm)
                    .security_level(SecurityLevel::AuthPriv)
                    .read_view("full_view")
                    .write_view("full_view")
            })
            .view("full_view", |v| v.include(oid!(1, 3, 6, 1)))
            .build();

        assert!(config.get_group(SecurityModel::V2c, b"public").is_some());
        assert!(config.get_group(SecurityModel::Usm, b"admin").is_some());
    }

    // RFC 3415 Section 4 preference order tests
    // The vacmAccessTable DESCRIPTION specifies a 4-tier preference order:
    // 1. Prefer specific securityModel over Any
    // 2. Prefer exact contextMatch over prefix
    // 3. Prefer longer contextPrefix
    // 4. Prefer higher securityLevel

    #[test]
    fn test_vacm_access_prefers_specific_security_model_over_any() {
        // Tier 1: Specific securityModel should be preferred over Any
        let mut config = VacmConfig::new();

        // Add entry with Any security model
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::new(),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Exact,
            read_view: Bytes::from_static(b"any_view"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        // Add entry with specific V2c security model
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::new(),
            security_model: SecurityModel::V2c,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Exact,
            read_view: Bytes::from_static(b"v2c_view"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        // Query with V2c - should get the specific V2c entry
        let access = config
            .get_access(
                b"test_group",
                b"",
                SecurityModel::V2c,
                SecurityLevel::NoAuthNoPriv,
            )
            .expect("should find access entry");
        assert_eq!(
            access.read_view,
            Bytes::from_static(b"v2c_view"),
            "should prefer specific security model over Any"
        );
    }

    #[test]
    fn test_vacm_access_prefers_exact_context_match_over_prefix() {
        // Tier 2: Exact contextMatch should be preferred over prefix match
        let mut config = VacmConfig::new();

        // Add entry with prefix context match
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::from_static(b"ctx"),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Prefix,
            read_view: Bytes::from_static(b"prefix_view"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        // Add entry with exact context match (same prefix)
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::from_static(b"ctx"),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Exact,
            read_view: Bytes::from_static(b"exact_view"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        // Query with exact context "ctx" - should get the exact match entry
        let access = config
            .get_access(
                b"test_group",
                b"ctx",
                SecurityModel::V2c,
                SecurityLevel::NoAuthNoPriv,
            )
            .expect("should find access entry");
        assert_eq!(
            access.read_view,
            Bytes::from_static(b"exact_view"),
            "should prefer exact context match over prefix"
        );
    }

    #[test]
    fn test_vacm_access_prefers_longer_context_prefix() {
        // Tier 3: Longer contextPrefix should be preferred
        let mut config = VacmConfig::new();

        // Add entry with shorter context prefix
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::from_static(b"ctx"),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Prefix,
            read_view: Bytes::from_static(b"short_view"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        // Add entry with longer context prefix
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::from_static(b"ctx_longer"),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Prefix,
            read_view: Bytes::from_static(b"long_view"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        // Query with context that matches both - should get the longer prefix
        let access = config
            .get_access(
                b"test_group",
                b"ctx_longer_suffix",
                SecurityModel::V2c,
                SecurityLevel::NoAuthNoPriv,
            )
            .expect("should find access entry");
        assert_eq!(
            access.read_view,
            Bytes::from_static(b"long_view"),
            "should prefer longer context prefix"
        );
    }

    #[test]
    fn test_vacm_access_prefers_higher_security_level() {
        // Tier 4: Higher securityLevel should be preferred
        let mut config = VacmConfig::new();

        // Add entry with NoAuthNoPriv
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::new(),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Exact,
            read_view: Bytes::from_static(b"noauth_view"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        // Add entry with AuthNoPriv
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::new(),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::AuthNoPriv,
            context_match: ContextMatch::Exact,
            read_view: Bytes::from_static(b"auth_view"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        // Add entry with AuthPriv
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::new(),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::AuthPriv,
            context_match: ContextMatch::Exact,
            read_view: Bytes::from_static(b"authpriv_view"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        // Query with AuthPriv - should get the AuthPriv entry (highest matching)
        let access = config
            .get_access(
                b"test_group",
                b"",
                SecurityModel::V2c,
                SecurityLevel::AuthPriv,
            )
            .expect("should find access entry");
        assert_eq!(
            access.read_view,
            Bytes::from_static(b"authpriv_view"),
            "should prefer higher security level"
        );
    }

    #[test]
    fn test_vacm_access_preference_tier_ordering() {
        // Test that tier 1 takes precedence over tier 2, which takes precedence
        // over tier 3, which takes precedence over tier 4.
        let mut config = VacmConfig::new();

        // Entry: Any model, prefix match, short prefix, high security
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::from_static(b"ctx"),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::AuthPriv, // highest security
            context_match: ContextMatch::Prefix,
            read_view: Bytes::from_static(b"any_prefix_short_high"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        // Entry: Specific model, prefix match, short prefix, low security
        // Tier 1 (specific model) should beat tier 4 (high security)
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::from_static(b"ctx"),
            security_model: SecurityModel::V2c,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Prefix,
            read_view: Bytes::from_static(b"v2c_prefix_short_low"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        // Query - specific model (V2c) should win over Any even though Any has higher security
        let access = config
            .get_access(
                b"test_group",
                b"ctx_test",
                SecurityModel::V2c,
                SecurityLevel::AuthPriv,
            )
            .expect("should find access entry");
        assert_eq!(
            access.read_view,
            Bytes::from_static(b"v2c_prefix_short_low"),
            "tier 1 (specific model) should take precedence over tier 4 (security level)"
        );
    }

    #[test]
    fn test_vacm_access_preference_context_match_over_prefix_length() {
        // Tier 2 (exact match) should beat tier 3 (longer prefix)
        let mut config = VacmConfig::new();

        // Entry: prefix match with longer prefix
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::from_static(b"context"),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Prefix,
            read_view: Bytes::from_static(b"long_prefix_view"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        // Entry: exact match with shorter prefix
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::from_static(b"ctx"),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Exact,
            read_view: Bytes::from_static(b"short_exact_view"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        // Query with "ctx" - exact match should win even though it's shorter
        let access = config
            .get_access(
                b"test_group",
                b"ctx",
                SecurityModel::V2c,
                SecurityLevel::NoAuthNoPriv,
            )
            .expect("should find access entry");
        assert_eq!(
            access.read_view,
            Bytes::from_static(b"short_exact_view"),
            "tier 2 (exact match) should take precedence over tier 3 (longer prefix)"
        );
    }

    #[test]
    fn test_vacm_access_preference_prefix_length_over_security() {
        // Tier 3 (longer prefix) should beat tier 4 (higher security)
        let mut config = VacmConfig::new();

        // Entry: short prefix with high security
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::from_static(b"ctx"),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::AuthPriv,
            context_match: ContextMatch::Prefix,
            read_view: Bytes::from_static(b"short_high_sec"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        // Entry: longer prefix with low security
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::from_static(b"ctx_test"),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Prefix,
            read_view: Bytes::from_static(b"long_low_sec"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        // Query - longer prefix should win even though short prefix has higher security
        let access = config
            .get_access(
                b"test_group",
                b"ctx_test_suffix",
                SecurityModel::V2c,
                SecurityLevel::AuthPriv,
            )
            .expect("should find access entry");
        assert_eq!(
            access.read_view,
            Bytes::from_static(b"long_low_sec"),
            "tier 3 (longer prefix) should take precedence over tier 4 (security level)"
        );
    }

    #[test]
    fn test_vacm_access_all_tiers_combined() {
        // Test with multiple entries that differ in all tiers
        let mut config = VacmConfig::new();

        // Entry 1: Any, prefix, short, NoAuth
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::from_static(b"a"),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Prefix,
            read_view: Bytes::from_static(b"entry1"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        // Entry 2: V2c (specific), exact, short, NoAuth - should win for "a" context
        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::from_static(b"a"),
            security_model: SecurityModel::V2c,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Exact,
            read_view: Bytes::from_static(b"entry2"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        let access = config
            .get_access(
                b"test_group",
                b"a",
                SecurityModel::V2c,
                SecurityLevel::NoAuthNoPriv,
            )
            .expect("should find access entry");
        assert_eq!(
            access.read_view,
            Bytes::from_static(b"entry2"),
            "specific model + exact match should win"
        );
    }

    // Tests that verify preference ordering is independent of insertion order
    #[test]
    fn test_vacm_access_exact_wins_regardless_of_insertion_order() {
        // Add exact first, prefix second - exact should still win
        let mut config = VacmConfig::new();

        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::from_static(b"ctx"),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Exact,
            read_view: Bytes::from_static(b"exact_view"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::from_static(b"ctx"),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Prefix,
            read_view: Bytes::from_static(b"prefix_view"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        let access = config
            .get_access(
                b"test_group",
                b"ctx",
                SecurityModel::V2c,
                SecurityLevel::NoAuthNoPriv,
            )
            .expect("should find access entry");
        assert_eq!(
            access.read_view,
            Bytes::from_static(b"exact_view"),
            "exact match should win regardless of insertion order"
        );
    }

    #[test]
    fn test_vacm_access_higher_security_wins_regardless_of_insertion_order() {
        // Add higher security first, lower second - higher should still win
        let mut config = VacmConfig::new();

        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::new(),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::AuthPriv,
            context_match: ContextMatch::Exact,
            read_view: Bytes::from_static(b"authpriv_view"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        config.add_access(VacmAccessEntry {
            group_name: Bytes::from_static(b"test_group"),
            context_prefix: Bytes::new(),
            security_model: SecurityModel::Any,
            security_level: SecurityLevel::NoAuthNoPriv,
            context_match: ContextMatch::Exact,
            read_view: Bytes::from_static(b"noauth_view"),
            write_view: Bytes::new(),
            notify_view: Bytes::new(),
        });

        let access = config
            .get_access(
                b"test_group",
                b"",
                SecurityModel::V2c,
                SecurityLevel::AuthPriv,
            )
            .expect("should find access entry");
        assert_eq!(
            access.read_view,
            Bytes::from_static(b"authpriv_view"),
            "higher security level should win regardless of insertion order"
        );
    }

    // ViewCheckResult and check_subtree tests
    //
    // These tests validate the 3-state subtree check semantics from RFC 3415.
    // For GETBULK/GETNEXT operations, knowing whether a subtree has mixed
    // permissions enables optimizations:
    // - Included: Skip per-OID access checks for descendants
    // - Excluded: Early termination, no descendants accessible
    // - Ambiguous: Must check each OID individually

    #[test]
    fn test_check_subtree_empty_view_is_excluded() {
        // Empty view contains nothing
        let view = View::new();
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1)),
            ViewCheckResult::Excluded
        );
    }

    #[test]
    fn test_check_subtree_oid_within_included_subtree() {
        // OID that falls within an included subtree is included
        let view = View::new().include(oid!(1, 3, 6, 1, 2, 1));

        // OID within the subtree
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1, 1, 0)),
            ViewCheckResult::Included
        );
        // OID exactly at subtree root
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1)),
            ViewCheckResult::Included
        );
    }

    #[test]
    fn test_check_subtree_oid_within_excluded_subtree() {
        // OID within an excluded subtree (after include) is excluded
        let view = View::new()
            .include(oid!(1, 3, 6, 1, 2, 1))
            .exclude(oid!(1, 3, 6, 1, 2, 1, 1, 7));

        // OID within the excluded subtree
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1, 1, 7, 0)),
            ViewCheckResult::Excluded
        );
        // OID exactly at exclude root
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1, 1, 7)),
            ViewCheckResult::Excluded
        );
    }

    #[test]
    fn test_check_subtree_oid_outside_all_subtrees() {
        // OID completely outside any defined subtree is excluded
        let view = View::new().include(oid!(1, 3, 6, 1, 2, 1));

        // Different branch entirely
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 4, 1)),
            ViewCheckResult::Excluded
        );
    }

    #[test]
    fn test_check_subtree_parent_of_single_include_is_ambiguous() {
        // Parent OID of an included subtree is ambiguous:
        // some children (the include) are accessible, others are not
        let view = View::new().include(oid!(1, 3, 6, 1, 2, 1));

        // Parent of the included subtree
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1)),
            ViewCheckResult::Ambiguous
        );
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6)),
            ViewCheckResult::Ambiguous
        );
    }

    #[test]
    fn test_check_subtree_parent_of_include_with_nested_exclude() {
        // View with include and nested exclude: parent is ambiguous
        let view = View::new()
            .include(oid!(1, 3, 6, 1, 2, 1))
            .exclude(oid!(1, 3, 6, 1, 2, 1, 1, 7));

        // Parent of the include - ambiguous because it has included descendants
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1)),
            ViewCheckResult::Ambiguous
        );

        // The include root itself - ambiguous because it contains excluded subtree
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1)),
            ViewCheckResult::Ambiguous
        );

        // Between include root and exclude - ambiguous
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1, 1)),
            ViewCheckResult::Ambiguous
        );
    }

    #[test]
    fn test_check_subtree_fully_included_child() {
        // When querying a subtree that is fully within an include,
        // with no excludes affecting it, it should be included
        let view = View::new()
            .include(oid!(1, 3, 6, 1, 2, 1))
            .exclude(oid!(1, 3, 6, 1, 2, 1, 25)); // exclude host resources

        // sysDescr subtree - fully included, no excludes affect it
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1, 1, 1)),
            ViewCheckResult::Included
        );

        // But the system group itself is ambiguous because hrMIB is excluded
        // Wait, hrMIB is .25, not under .1 - so system group should be included
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1, 1)),
            ViewCheckResult::Included
        );
    }

    #[test]
    fn test_check_subtree_multiple_includes() {
        // Multiple disjoint includes - parent is ambiguous
        let view = View::new()
            .include(oid!(1, 3, 6, 1, 2, 1, 1)) // system
            .include(oid!(1, 3, 6, 1, 2, 1, 2)); // interfaces

        // Parent of both - ambiguous (some children included, others not)
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1)),
            ViewCheckResult::Ambiguous
        );

        // Each individual include is fully included
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1, 1)),
            ViewCheckResult::Included
        );
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1, 2)),
            ViewCheckResult::Included
        );

        // Sibling not in any include is excluded
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1, 3)),
            ViewCheckResult::Excluded
        );
    }

    #[test]
    fn test_check_subtree_exclude_only_is_excluded() {
        // An exclude without a covering include excludes nothing
        // (exclude only has effect when there's a matching include)
        // Actually, per RFC 3415, an exclude without include means the OID
        // is simply not in the view at all (excluded)
        let view = View::new().exclude(oid!(1, 3, 6, 1, 2, 1, 1, 7));

        // Everything is excluded because there's no include
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1)),
            ViewCheckResult::Excluded
        );
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1)),
            ViewCheckResult::Excluded
        );
    }

    #[test]
    fn test_check_subtree_with_mask() {
        // Masked subtree - parent is ambiguous due to partial match
        let view = View::new().include_masked(
            oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 2), // ifDescr
            vec![0xFF, 0xC0],                   // arcs 0-9 exact, 10+ wildcard
        );

        // Within the masked include - included
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 2, 1)),
            ViewCheckResult::Included
        );

        // Parent of the masked include - ambiguous
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1, 2)),
            ViewCheckResult::Ambiguous
        );

        // Sibling column (ifType) - excluded
        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 3)),
            ViewCheckResult::Excluded
        );
    }

    #[test]
    fn test_check_subtree_child_detection_honors_mask() {
        // vacm-1: a masked EXCLUDE subtree longer than the query, with a
        // wildcard arc *inside* the query prefix, still covers descendants of
        // the query. Child detection must apply the mask, otherwise the literal
        // arc compare misses the exclude and check_subtree over-grants Included.
        //
        // Excluded family: 1.3.6.1.2.*.7 (arc 5 wildcarded). This intersects the
        // included 1.3.6.1.2.1 subtree at e.g. 1.3.6.1.2.1.7, so the query
        // 1.3.6.1.2.1 has mixed permissions => Ambiguous.
        let view = View::new().include(oid!(1, 3, 6, 1, 2, 1)).exclude_masked(
            oid!(1, 3, 6, 1, 2, 99, 7),
            vec![0xFA], // arcs 0-4,6 exact; arc 5 wildcard
        );

        // The excluded family covers a descendant of the query.
        assert!(!view.contains(&oid!(1, 3, 6, 1, 2, 1, 7)));
        // A sibling descendant remains included.
        assert!(view.contains(&oid!(1, 3, 6, 1, 2, 1, 1)));

        assert_eq!(
            view.check_subtree(&oid!(1, 3, 6, 1, 2, 1)),
            ViewCheckResult::Ambiguous
        );
    }

    #[test]
    fn test_check_subtree_vs_contains_consistency() {
        // Verify that check_subtree is consistent with contains:
        // If check_subtree returns Included, contains should return true
        // If check_subtree returns Excluded, contains should return false
        let view = View::new()
            .include(oid!(1, 3, 6, 1, 2, 1))
            .exclude(oid!(1, 3, 6, 1, 2, 1, 25));

        let test_cases = [
            oid!(1, 3, 6, 1, 2, 1, 1, 0),  // included
            oid!(1, 3, 6, 1, 2, 1, 25, 1), // excluded
            oid!(1, 3, 6, 1, 4, 1),        // not in view at all
        ];

        for oid in &test_cases {
            let check_result = view.check_subtree(oid);
            let contains_result = view.contains(oid);

            match check_result {
                ViewCheckResult::Included => {
                    assert!(
                        contains_result,
                        "check_subtree=Included but contains=false for {oid:?}"
                    );
                }
                ViewCheckResult::Excluded => {
                    assert!(
                        !contains_result,
                        "check_subtree=Excluded but contains=true for {oid:?}"
                    );
                }
                ViewCheckResult::Ambiguous => {
                    // Ambiguous can be either, depending on specific OID
                }
            }
        }
    }
}