rs_matter/

fabric.rs

/*
 *
 *    Copyright (c) 2022-2026 Project CHIP Authors
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

use core::mem::MaybeUninit;
use core::num::NonZeroU8;

use cfg_if::cfg_if;
use heapless::String;

use crate::acl::{self, AccessReq, AclEntry, AuthMode};
use crate::cert::{CertRef, MAX_CERT_TLV_LEN};
use crate::crypto::{
    CanonAeadKeyRef, CanonPkcPublicKeyRef, CanonPkcSecretKey, CanonPkcSecretKeyRef, Crypto,
    CryptoSensitive, Digest, Hash, Kdf, PKC_CANON_PUBLIC_KEY_LEN,
};
use crate::dm::Privilege;
use crate::error::{Error, ErrorCode};
use crate::group_keys::KeySet;
use crate::persist::{KvBlobStore, KvBlobStoreAccess, Persist, FABRIC_KEYS_START};
#[cfg(feature = "groups")]
use crate::tlv::Skippable;
use crate::tlv::{FromTLV, TLVElement, ToTLV};
use crate::transport::network::MatterLocalService;
use crate::utils::init::{init, Init, InitMaybeUninit, IntoFallibleInit};
use crate::utils::storage::Vec;

const COMPRESSED_FABRIC_ID_LEN: usize = 8;

/// All multicast-group fabric state: the group key sets, the group→keyset
/// mapping, and the group table. Gated as one inline module so the whole block
/// (consts, TLV structs and the `Groups` container) is compiled out with a
/// single `#[cfg]` when the `groups` feature is off, and re-exported so the rest
/// of `fabric` refers to these items unqualified.
#[cfg(feature = "groups")]
mod groups {
    use core::str::FromStr;

    use cfg_if::cfg_if;

    use heapless::String;

    use crate::dm::clusters::decl::groupcast::MulticastAddrPolicyEnum;
    use crate::error::{Error, ErrorCode};
    use crate::group_keys::GroupKeySet;
    use crate::tlv::{FromTLV, ToTLV};
    use crate::utils::init::{init, Init, InitDefault};
    use crate::utils::storage::Vec;

    cfg_if! {
        if #[cfg(feature = "max-group-keys-per-fabric-5")] {
            /// Max number of group key sets per fabric (excluding IPK at index 0).
            pub const MAX_GROUP_KEYS_PER_FABRIC: usize = 5;
        } else if #[cfg(feature = "max-group-keys-per-fabric-4")] {
            /// Max number of group key sets per fabric (excluding IPK at index 0).
            pub const MAX_GROUP_KEYS_PER_FABRIC: usize = 4;
        } else if #[cfg(feature = "max-group-keys-per-fabric-3")] {
            /// Max number of group key sets per fabric (excluding IPK at index 0).
            pub const MAX_GROUP_KEYS_PER_FABRIC: usize = 3;
        } else if #[cfg(feature = "max-group-keys-per-fabric-2")] {
            /// Max number of group key sets per fabric (excluding IPK at index 0).
            pub const MAX_GROUP_KEYS_PER_FABRIC: usize = 2;
        } else { // Matter requires a minimum of 3 group key sets per fabric
            /// Max number of group key sets per fabric (excluding IPK at index 0).
            pub const MAX_GROUP_KEYS_PER_FABRIC: usize = 3;
        }
    }

    /// Max length of a group name (per Matter spec).
    pub const MAX_GROUP_NAME_LEN: usize = 16;

    cfg_if! {
        if #[cfg(feature = "max-groups-per-fabric-32")] {
            /// Max number of group key map entries per fabric.
            pub const MAX_GROUPS_PER_FABRIC: usize = 32;
        } else if #[cfg(feature = "max-groups-per-fabric-16")] {
            /// Max number of group key map entries per fabric.
            pub const MAX_GROUPS_PER_FABRIC: usize = 16;
        } else if #[cfg(feature = "max-groups-per-fabric-12")] {
            /// Max number of group key map entries per fabric.
            pub const MAX_GROUPS_PER_FABRIC: usize = 12;
        } else if #[cfg(feature = "max-groups-per-fabric-8")] {
            /// Max number of group key map entries per fabric.
            pub const MAX_GROUPS_PER_FABRIC: usize = 9;
        } else if #[cfg(feature = "max-groups-per-fabric-7")] {
            /// Max number of group key map entries per fabric.
            pub const MAX_GROUPS_PER_FABRIC: usize = 7;
        } else if #[cfg(feature = "max-groups-per-fabric-6")] {
            /// Max number of group key map entries per fabric.
            pub const MAX_GROUPS_PER_FABRIC: usize = 6;
        } else if #[cfg(feature = "max-groups-per-fabric-5")] {
            /// Max number of group key map entries per fabric.
            pub const MAX_GROUPS_PER_FABRIC: usize = 5;
        } else if #[cfg(feature = "max-groups-per-fabric-4")] {
            /// Max number of group key map entries per fabric.
            pub const MAX_GROUPS_PER_FABRIC: usize = 4;
        } else { // Matter requires a minimum of 4 group table entries per fabric
            /// Max number of group key map entries per fabric.
            pub const MAX_GROUPS_PER_FABRIC: usize = 4;
        }
    }

    cfg_if! {
        if #[cfg(feature = "max-group-endpoints-per-fabric-5")] {
            /// Max number of endpoints per group entry.
            pub const GROUP_ENDPOINTS_PER_FABRIC: usize = 5;
        } else if #[cfg(feature = "max-group-endpoints-per-fabric-4")] {
            /// Max number of endpoints per group entry.
            pub const GROUP_ENDPOINTS_PER_FABRIC: usize = 4;
        } else if #[cfg(feature = "max-group-endpoints-per-fabric-3")] {
            /// Max number of endpoints per group entry.
            pub const GROUP_ENDPOINTS_PER_FABRIC: usize = 3;
        } else if #[cfg(feature = "max-group-endpoints-per-fabric-2")] {
            /// Max number of endpoints per group entry.
            pub const GROUP_ENDPOINTS_PER_FABRIC: usize = 2;
        } else if #[cfg(feature = "max-group-endpoints-per-fabric-1")] {
            /// Max number of endpoints per group entry.
            pub const GROUP_ENDPOINTS_PER_FABRIC: usize = 1;
        } else { // Default: 3 endpoints per group entry
            /// Max number of endpoints per group entry.
            pub const GROUP_ENDPOINTS_PER_FABRIC: usize = 3;
        }
    }

    /// A group table entry mapping a group ID to its endpoints and name.
    #[derive(Debug, FromTLV, ToTLV)]
    #[cfg_attr(feature = "defmt", derive(defmt::Format))]
    pub struct GroupEndpointMapping {
        pub group_id: u16,
        pub endpoints: Vec<u16, GROUP_ENDPOINTS_PER_FABRIC>,
        pub group_name: String<MAX_GROUP_NAME_LEN>,
        /// Whether the (Groupcast-managed) group has auxiliary ACL entries
        /// generated for its endpoints - see the Groupcast cluster's
        /// `ConfigureAuxiliaryACL` command and the `AuxiliaryACL` attribute
        /// of the Access Control cluster.
        ///
        /// `None` (in blobs persisted before the field existed) means `false`.
        pub has_aux_acl: Option<bool>,
        /// The multicast-address policy of the group, when it is managed by
        /// the Groupcast cluster.
        ///
        /// `None` means the group was created via the legacy Groups cluster,
        /// which behaves like the `PerGroup` policy (such nodes join the
        /// fabric+group-scoped multicast address) - the `PerGroup` policy
        /// exists precisely for interop with them.
        pub mcast_policy: Option<MulticastAddrPolicyEnum>,
    }

    impl GroupEndpointMapping {
        /// Whether the group has auxiliary ACL entries generated for its
        /// endpoints.
        pub fn has_aux_acl(&self) -> bool {
            self.has_aux_acl.unwrap_or(false)
        }

        /// The effective multicast-address policy of the group (legacy
        /// Groups-cluster entries behave as `PerGroup`).
        pub fn effective_mcast_policy(&self) -> MulticastAddrPolicyEnum {
            self.mcast_policy
                .unwrap_or(MulticastAddrPolicyEnum::PerGroup)
        }

        /// Whether the group is managed by the Groupcast cluster (as opposed
        /// to the legacy Groups cluster).
        pub fn groupcast_managed(&self) -> bool {
            self.mcast_policy.is_some()
        }
    }

    /// A stored group key map entry (maps group ID to key set).
    #[derive(Debug, Clone, Default, FromTLV, ToTLV)]
    #[cfg_attr(feature = "defmt", derive(defmt::Format))]
    pub struct GroupKeyMapping {
        pub group_id: u16,
        pub group_key_set_id: u16,
    }

    #[derive(Debug, FromTLV, ToTLV)]
    #[cfg_attr(feature = "defmt", derive(defmt::Format))]
    pub struct Groups {
        /// Group key sets (excluding IPK which is stored in `ipk`)
        key_sets: Vec<GroupKeySet, MAX_GROUP_KEYS_PER_FABRIC>,
        /// Groups keyset mapping
        key_map: Vec<GroupKeyMapping, MAX_GROUPS_PER_FABRIC>,
        /// Group table (group ID → endpoints + name)
        endpoint_mapping: Vec<GroupEndpointMapping, MAX_GROUPS_PER_FABRIC>,
    }

    impl Groups {
        pub(crate) const fn new() -> Self {
            Self {
                key_sets: Vec::new(),
                key_map: Vec::new(),
                endpoint_mapping: Vec::new(),
            }
        }

        pub(crate) fn init() -> impl Init<Self> {
            init!(Self {
                key_sets <- Vec::init(),
                key_map <- Vec::init(),
                endpoint_mapping <- Vec::init(),
            })
        }

        /// Return an iterator over the group key sets of the fabric
        pub fn key_set_iter(&self) -> impl Iterator<Item = &GroupKeySet> {
            self.key_sets.iter()
        }

        /// Find a group key set by ID
        pub fn key_set_get(&self, id: u16) -> Option<&GroupKeySet> {
            self.key_sets.iter().find(|e| e.group_key_set_id == id)
        }

        /// Add or update a group key set
        pub fn key_set_add(&mut self, entry: GroupKeySet) -> Result<(), Error> {
            if let Some(existing) = self
                .key_sets
                .iter_mut()
                .find(|e| e.group_key_set_id == entry.group_key_set_id)
            {
                *existing = entry;
            } else {
                self.key_sets
                    .push(entry)
                    .map_err(|_| ErrorCode::ResourceExhausted)?;
            }
            Ok(())
        }

        /// Remove a group key set by ID. Returns true if found and removed.
        pub fn key_set_remove(&mut self, id: u16) -> Result<(), Error> {
            let before = self.key_sets.len();
            self.key_sets.retain(|e| e.group_key_set_id != id);
            let removed = self.key_sets.len() < before;

            self.key_map_remove_by_key_set(id);

            // Check if element was actually removed
            if removed {
                Ok(())
            } else {
                Err(Error::new(ErrorCode::NotFound))
            }
        }

        pub fn key_map_add(&mut self, entry: GroupKeyMapping) -> Result<(), Error> {
            self.key_map.push(entry).map_err(|_| ErrorCode::Failure)?;

            Ok(())
        }

        /// Return an iterator over the group key map entries of the fabric
        pub fn key_map_iter(&self) -> impl Iterator<Item = &GroupKeyMapping> {
            self.key_map.iter()
        }

        /// Replace all group key map entries
        pub fn key_map_replace(
            &mut self,
            entries: impl Iterator<Item = GroupKeyMapping>,
        ) -> Result<(), Error> {
            self.key_map.clear();
            for entry in entries {
                self.key_map
                    .push(entry)
                    .map_err(|_| ErrorCode::ResourceExhausted)?;
            }
            Ok(())
        }

        /// Remove group key map entries that reference a specific key set ID
        pub fn key_map_remove_by_key_set(&mut self, key_set_id: u16) {
            self.key_map.retain(|e| e.group_key_set_id != key_set_id);
        }

        /// Return an iterator over the group table entries
        pub fn iter(&self) -> impl Iterator<Item = &GroupEndpointMapping> {
            self.endpoint_mapping.iter()
        }

        /// Look up a group by ID
        pub fn get(&self, group_id: u16) -> Option<&GroupEndpointMapping> {
            self.endpoint_mapping
                .iter()
                .find(|e| e.group_id == group_id)
        }

        /// Look up a group by ID, mutably
        pub fn get_mut(&mut self, group_id: u16) -> Option<&mut GroupEndpointMapping> {
            self.endpoint_mapping
                .iter_mut()
                .find(|e| e.group_id == group_id)
        }

        /// Add an endpoint to a group.
        /// Returns true if the endpoint was already a member (name still updated per spec).
        pub fn add(
            &mut self,
            endpoint_id: u16,
            group_id: u16,
            group_name: &str,
        ) -> Result<bool, Error> {
            let entry = if let Some(entry) = self
                .endpoint_mapping
                .iter_mut()
                .find(|e| e.group_id == group_id)
            {
                entry
            } else {
                self.endpoint_mapping
                    .push(GroupEndpointMapping {
                        group_id,
                        endpoints: Vec::new(),
                        group_name: String::from_str(group_name)
                            .map_err(|_| ErrorCode::ConstraintError)?,
                        has_aux_acl: None,
                        mcast_policy: None,
                    })
                    .map_err(|_| ErrorCode::ResourceExhausted)?;
                unwrap!(self.endpoint_mapping.last_mut())
            };

            // Update group name
            entry.group_name.clear();
            entry
                .group_name
                .push_str(group_name)
                .map_err(|_| ErrorCode::ConstraintError)?;

            if entry.endpoints.contains(&endpoint_id) {
                return Ok(true);
            }

            entry
                .endpoints
                .push(endpoint_id)
                .map_err(|_| ErrorCode::ResourceExhausted)?;

            Ok(false)
        }

        /// Remove an endpoint from a group, or from all groups if `group_id` is `None`.
        /// Returns true if the endpoint was removed from at least one group.
        pub fn remove(&mut self, endpoint_id: u16, group_id: Option<u16>) -> bool {
            let mut removed = false;

            for entry in self.endpoint_mapping.iter_mut() {
                if group_id.is_some_and(|id| id != entry.group_id) {
                    continue;
                }
                let before = entry.endpoints.len();
                entry.endpoints.retain(|&ep| ep != endpoint_id);
                if entry.endpoints.len() < before {
                    removed = true;
                }
            }

            // Remove entries with no endpoints left - except Groupcast-managed
            // ones, which may legitimately exist with no endpoints (a
            // sender-only membership); the Groupcast cluster removes those
            // explicitly via its `LeaveGroup` command.
            self.endpoint_mapping
                .retain(|e| !e.endpoints.is_empty() || e.groupcast_managed());

            removed
        }

        /// Join endpoints to a group on behalf of the Groupcast cluster,
        /// creating the membership if it does not exist.
        ///
        /// - `endpoints`: the endpoints to add (may be empty for a
        ///   sender-only membership); duplicates are omitted;
        /// - `replace`: when `true`, the given endpoints replace the
        ///   existing list instead of being appended;
        /// - `mcast_policy`: the multicast-address policy; applied on
        ///   creation, or updated when `Some` on an existing membership.
        ///
        /// Errors with `ResourceExhausted` when the membership or endpoint
        /// capacity is exceeded; the membership is left unchanged in that
        /// case, except that a possibly-performed `replace` clearing is
        /// rolled back by restoring nothing (the caller re-checks capacity
        /// upfront via [`Self::group_count`] and the endpoint capacity).
        pub fn groupcast_join(
            &mut self,
            group_id: u16,
            endpoints: &[u16],
            replace: bool,
            mcast_policy: Option<MulticastAddrPolicyEnum>,
        ) -> Result<(), Error> {
            let entry = if let Some(entry) = self
                .endpoint_mapping
                .iter_mut()
                .find(|e| e.group_id == group_id)
            {
                entry
            } else {
                self.endpoint_mapping
                    .push(GroupEndpointMapping {
                        group_id,
                        endpoints: Vec::new(),
                        group_name: String::new(),
                        has_aux_acl: Some(false),
                        mcast_policy: Some(
                            mcast_policy.unwrap_or(MulticastAddrPolicyEnum::IanaAddr),
                        ),
                    })
                    .map_err(|_| ErrorCode::ResourceExhausted)?;
                unwrap!(self.endpoint_mapping.last_mut())
            };

            // Joining via Groupcast upgrades a legacy entry to
            // Groupcast-managed (the default policy matches the legacy
            // behavior)
            if entry.mcast_policy.is_none() {
                entry.mcast_policy = Some(MulticastAddrPolicyEnum::PerGroup);
            }

            if let Some(mcast_policy) = mcast_policy {
                entry.mcast_policy = Some(mcast_policy);
            }

            if replace {
                entry.endpoints.clear();
            }

            for endpoint in endpoints {
                if !entry.endpoints.contains(endpoint) {
                    entry
                        .endpoints
                        .push(*endpoint)
                        .map_err(|_| ErrorCode::ResourceExhausted)?;
                }
            }

            Ok(())
        }

        /// Remove a whole group membership. Returns `true` if it existed.
        pub fn groupcast_remove(&mut self, group_id: u16) -> bool {
            let before = self.endpoint_mapping.len();
            self.endpoint_mapping.retain(|e| e.group_id != group_id);

            before != self.endpoint_mapping.len()
        }

        /// Set the `has_aux_acl` flag of a group membership.
        /// Returns `true` if the flag changed.
        pub fn set_has_aux_acl(&mut self, group_id: u16, has_aux_acl: bool) -> bool {
            let Some(entry) = self
                .endpoint_mapping
                .iter_mut()
                .find(|e| e.group_id == group_id)
            else {
                return false;
            };

            let changed = entry.has_aux_acl() != has_aux_acl;
            entry.has_aux_acl = Some(has_aux_acl);

            changed
        }

        /// The number of group memberships of this fabric.
        pub fn group_count(&self) -> usize {
            self.endpoint_mapping.len()
        }

        /// Look up the key set ID mapped to a group, if any.
        pub fn key_map_get(&self, group_id: u16) -> Option<u16> {
            self.key_map
                .iter()
                .find(|e| e.group_id == group_id)
                .map(|e| e.group_key_set_id)
        }

        /// Map a group to a key set, replacing any previous mapping of that
        /// group.
        pub fn key_map_set_group(&mut self, group_id: u16, key_set_id: u16) -> Result<(), Error> {
            if let Some(entry) = self.key_map.iter_mut().find(|e| e.group_id == group_id) {
                entry.group_key_set_id = key_set_id;
                return Ok(());
            }

            self.key_map
                .push(GroupKeyMapping {
                    group_id,
                    group_key_set_id: key_set_id,
                })
                .map_err(|_| ErrorCode::ResourceExhausted.into())
        }

        /// Remove all key-set mappings of the given group.
        pub fn key_map_remove_group(&mut self, group_id: u16) {
            self.key_map.retain(|e| e.group_id != group_id);
        }
    }

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

    impl InitDefault for Groups {
        fn init_default() -> impl Init<Self> {
            Self::init()
        }
    }
}

#[cfg(feature = "groups")]
pub use groups::*;

/// Fabric type
#[derive(Debug, ToTLV, FromTLV)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub struct Fabric {
    /// Fabric local index
    fab_idx: NonZeroU8,
    /// Fabric node ID
    node_id: u64,
    /// Fabric ID
    fabric_id: u64,
    /// Vendor ID
    vendor_id: u16,
    /// Compressed ID
    compressed_fabric_id: u64,
    /// Fabric secret key
    secret_key: CanonPkcSecretKey,
    /// Root CA certificate to be used when verifying the node's certificate
    ///
    /// Note that we deviate from the Matter spec here, in that we store the
    /// root certificate in the Fabric type itself, rather than - as the
    /// spec mandates - in a separate Root CA store
    ///
    /// This simplifies the implementation, but results in potentially multiple
    /// copies of the same Root CA used accross multiple fabrics.
    root_ca: Vec<u8, { MAX_CERT_TLV_LEN }>,
    /// Either the Intermediate CA certificate (`vvsc_set == false`) or the
    /// Vendor Verification Signing Cert (`vvsc_set == true`). The two are
    /// mutually exclusive in the cert chain (Matter Core spec) —
    /// a fabric with an ICAC cannot also carry a VVSC and vice
    /// versa — so we share one buffer instead of paying for both. Empty
    /// means neither is set; in that case `vvsc_set` is meaningless.
    icac_or_vvsc: Vec<u8, { MAX_CERT_TLV_LEN }>,
    /// Selector for what `icac_or_vvsc` holds: `false` for an ICAC,
    /// `true` for a VVSC.
    vvsc_set: bool,
    /// Node Operational Certificate
    noc: Vec<u8, { MAX_CERT_TLV_LEN }>,
    /// Identity Protection Key
    ipk: KeySet,
    /// Fabric label; unique accross all fabrics on the device
    label: String<32>,
    /// Access Control List
    acl: Vec<AclEntry, { acl::MAX_ACL_ENTRIES_PER_FABRIC }>,
    /// Fabric group information.
    #[cfg(feature = "groups")]
    #[tagval(13)]
    groups: Skippable<Groups>,
    /// VID Verification Statement (Matter Core spec).
    /// Either empty (not set) or exactly `VID_VERIFICATION_STATEMENT_LEN`
    /// bytes long; the cluster XML enforces both bounds at the schema
    /// level (`length="85" minLength="85"`).
    #[tagval(14)]
    vid_verification_statement: Vec<u8, VID_VERIFICATION_STATEMENT_LEN>,
}

/// Exact length of a non-empty VID Verification Statement.
/// Matches `length="85" minLength="85"` on
/// `OperationalCredentials::SetVIDVerificationStatement.vid_verification_statement`.
pub const VID_VERIFICATION_STATEMENT_LEN: usize = 85;

impl Fabric {
    /// Return an in-place-initializer for a Fabric type, with the
    /// provided Fabric Index and KeyPair
    ///
    /// All other fields are initialized to default values, which are NOT
    /// valid for the operation of the fabric.
    ///
    /// The Fabric must be updated with the correct values before it can be
    /// used, via `Fabric::update`.
    fn init(fab_idx: NonZeroU8) -> impl Init<Self> {
        // NOTE: the `init!` macro does not accept `#[cfg]` on its field entries,
        // so the `groups` field (present only under the `groups` feature) forces
        // two variants of the initializer that differ solely by that last field.
        #[cfg(feature = "groups")]
        let r = init!(Self {
            fab_idx,
            node_id: 0,
            fabric_id: 0,
            vendor_id: 0,
            compressed_fabric_id: 0,
            secret_key <- CanonPkcSecretKey::init(),
            root_ca <- Vec::init(),
            icac_or_vvsc <- Vec::init(),
            vvsc_set: false,
            noc <- Vec::init(),
            ipk <- KeySet::init(),
            label: String::new(),
            acl <- Vec::init(),
            vid_verification_statement <- Vec::init(),
            groups <- Skippable::init_default(),
        });

        #[cfg(not(feature = "groups"))]
        let r = init!(Self {
            fab_idx,
            node_id: 0,
            fabric_id: 0,
            vendor_id: 0,
            compressed_fabric_id: 0,
            secret_key <- CanonPkcSecretKey::init(),
            root_ca <- Vec::init(),
            icac_or_vvsc <- Vec::init(),
            vvsc_set: false,
            noc <- Vec::init(),
            ipk <- KeySet::init(),
            label: String::new(),
            acl <- Vec::init(),
            vid_verification_statement <- Vec::init(),
        });
        r
    }

    /// Update the fabric with the provided data so that it can operate.
    ///
    /// This method is supposed to be called right after `Fabric::init` or
    /// when the NOC of the fabric needs to be updated.
    ///
    /// `root_ca` is `None` when called from the `UpdateNOC` flow — Matter
    /// Core spec keeps the fabric's root cert unchanged
    /// across `UpdateNOC`, and re-passing the existing bytes here would
    /// require a (large) caller-side copy of `self.root_ca`. `Some(...)`
    /// is used by the initial `AddNOC` flow, where the cert was just
    /// staged in the fail-safe context.
    #[allow(clippy::too_many_arguments)]
    fn update<C: Crypto>(
        &mut self,
        crypto: C,
        root_ca: Option<&[u8]>,
        noc: &[u8],
        icac: &[u8],
        secret_key: CanonPkcSecretKeyRef<'_>,
        epoch_key: Option<CanonAeadKeyRef<'_>>,
        vendor_id: Option<u16>,
        case_admin_subject: Option<u64>,
    ) -> Result<(), Error> {
        if let Some(root_ca) = root_ca {
            self.root_ca.clear();
            self.root_ca
                .extend_from_slice(root_ca)
                .map_err(|_| ErrorCode::BufferTooSmall)?;
        }
        // `AddNOC` / `UpdateNOC` always replace the cert chain, so any
        // previously-staged VVSC for this fabric is implicitly cleared
        // here — the spec doesn't allow an ICAC and a VVSC to coexist.
        self.icac_or_vvsc.clear();
        self.icac_or_vvsc
            .extend_from_slice(icac)
            .map_err(|_| ErrorCode::BufferTooSmall)?;
        self.vvsc_set = false;
        self.noc.clear();
        self.noc
            .extend_from_slice(noc)
            .map_err(|_| ErrorCode::BufferTooSmall)?;

        let root_cert = CertRef::new(TLVElement::new(self.root_ca.as_slice()));
        let noc_cert = CertRef::new(TLVElement::new(noc));

        self.node_id = noc_cert.get_node_id()?;
        self.fabric_id = noc_cert.get_fabric_id()?;
        self.compressed_fabric_id = Self::compute_compressed_fabric_id(
            &crypto,
            root_cert.pubkey()?.try_into()?,
            self.fabric_id,
        );

        if let Some(epoch_key) = epoch_key {
            self.ipk
                .update(&crypto, epoch_key, &self.compressed_fabric_id)?;
        }

        if let Some(vendor_id) = vendor_id {
            self.vendor_id = vendor_id;
        }

        if let Some(case_admin_subject) = case_admin_subject {
            self.acl.clear();
            self.acl.push_init(
                AclEntry::init(None, Privilege::ADMIN, AuthMode::Case)
                    .into_fallible()
                    .chain(|e| {
                        e.fab_idx = Some(self.fab_idx);
                        e.add_subject(case_admin_subject)
                    }),
                || ErrorCode::ResourceExhausted.into(),
            )?;
        }

        self.secret_key.load(secret_key);

        Ok(())
    }

    pub fn mdns_service(&self) -> Option<MatterLocalService> {
        self.mdns_service_for(self.node_id)
    }

    pub fn mdns_service_for(&self, node_id: u64) -> Option<MatterLocalService> {
        (!self.noc.is_empty()).then_some(MatterLocalService::Commissioned {
            compressed_fabric_id: self.compressed_fabric_id,
            node_id,
        })
    }

    /// Is the fabric matching the privided destination ID
    pub fn is_dest_id<C: Crypto>(
        &self,
        crypto: C,
        random: &[u8],
        target: &[u8],
    ) -> Result<(), Error> {
        let mut mac = crypto.hmac(self.ipk.op_key())?;

        mac.update(random)?;
        mac.update(CertRef::new(TLVElement::new(self.root_ca())).pubkey()?)?;

        mac.update(&self.fabric_id.to_le_bytes())?;
        mac.update(&self.node_id.to_le_bytes())?;

        let mut id = MaybeUninit::<Hash>::uninit(); // TODO MEDIUM BUFFER
        let id = id.init_with(Hash::init());
        mac.finish(id)?;
        if id.access() == target {
            Ok(())
        } else {
            Err(ErrorCode::NotFound.into())
        }
    }

    /// Compute the destination identifier for a target node on this fabric.
    ///
    /// Used by the CASE initiator to build Sigma1 (spec).
    /// destinationMessage = initiatorRandom || rootPublicKey || fabricId(LE) || nodeId(LE)
    /// destinationIdentifier = Crypto_HMAC(key=IPK, message=destinationMessage)
    ///
    /// # Arguments
    /// - `target_node_id`: The node ID of the destination (peer) node, NOT the local node.
    pub fn compute_dest_id<C: Crypto>(
        &self,
        crypto: C,
        random: &[u8],
        target_node_id: u64,
        out: &mut Hash,
    ) -> Result<(), Error> {
        let mut mac = crypto.hmac(self.ipk.op_key())?;

        mac.update(random)?;
        mac.update(CertRef::new(TLVElement::new(self.root_ca())).pubkey()?)?;
        mac.update(&self.fabric_id.to_le_bytes())?;
        mac.update(&target_node_id.to_le_bytes())?;

        mac.finish(out)?;
        Ok(())
    }

    /// Return the secret key of the fabric
    pub fn secret_key(&self) -> CanonPkcSecretKeyRef<'_> {
        self.secret_key.reference()
    }

    /// Return the fabric's node ID
    pub fn node_id(&self) -> u64 {
        self.node_id
    }

    /// Return the fabric's fabric ID
    pub fn fabric_id(&self) -> u64 {
        self.fabric_id
    }

    /// Return the fabric's local index
    pub fn fab_idx(&self) -> NonZeroU8 {
        self.fab_idx
    }

    /// Return the fabric's compressed fabric ID
    pub fn compressed_fabric_id(&self) -> u64 {
        self.compressed_fabric_id
    }

    /// Return the fabric's Vendor ID
    pub fn vendor_id(&self) -> u16 {
        self.vendor_id
    }

    /// Return the fabric's label
    pub fn label(&self) -> &str {
        &self.label
    }

    /// Return the fabric's Root CA in encoded TLV form
    ///
    /// Use `CertRef` to decode on the fly
    pub fn root_ca(&self) -> &[u8] {
        &self.root_ca
    }

    /// Return the fabric's ICAC in encoded TLV form
    ///
    /// Use `CertRef` to decode on the fly.
    ///
    /// Note that this method might return an empty slice,
    /// which indicates that this fabric does not have an ICAC.
    /// (The shared `icac_or_vvsc` slot may instead hold a VVSC; see
    /// `vvsc()`.)
    pub fn icac(&self) -> &[u8] {
        if self.vvsc_set {
            &[]
        } else {
            &self.icac_or_vvsc
        }
    }

    /// Return the fabric's NOC
    pub fn noc(&self) -> &[u8] {
        &self.noc
    }

    /// Return the fabric's IPK
    pub fn ipk(&self) -> &KeySet {
        &self.ipk
    }

    /// Return the fabric's groups, or an empty group state if this fabric was
    /// persisted before the `groups` field existed (see [`Fabric::groups`]).
    #[cfg(feature = "groups")]
    pub fn groups(&self) -> &Groups {
        self.groups.value()
    }

    /// Return a mutable reference to the fabric's groups, materializing empty
    /// group state on first access if it was absent.
    #[cfg(feature = "groups")]
    pub fn groups_mut(&mut self) -> &mut Groups {
        self.groups.value_mut()
    }

    /// Return the fabric's VVSC bytes (Matter Core spec).
    /// Empty when `SetVIDVerificationStatement` has never been called with
    /// a non-empty VVSC for this fabric, or when the fabric instead carries
    /// an ICAC (see `icac()`) — VVSC and ICAC share storage and are
    /// mutually exclusive per spec.
    pub fn vvsc(&self) -> &[u8] {
        if self.vvsc_set {
            &self.icac_or_vvsc
        } else {
            &[]
        }
    }

    /// Return the fabric's VID Verification Statement bytes (Matter Core
    /// spec). Either empty (not set) or
    /// exactly `VID_VERIFICATION_STATEMENT_LEN` bytes.
    pub fn vid_verification_statement(&self) -> &[u8] {
        &self.vid_verification_statement
    }

    /// Apply a `SetVIDVerificationStatement` mutation to the fabric. Each
    /// field is `Some(slice)` for "replace with this value" (where an
    /// empty slice clears the value), or `None` for "leave unchanged".
    /// The caller is responsible for spec-level validation (size limits,
    /// VVSC vs ICAC mutual exclusion, "all fields absent" → INVALID_COMMAND,
    /// VendorID range, …); this method only enforces the storage
    /// invariants (heapless `Vec` capacity).
    pub fn set_vid_verification(
        &mut self,
        vendor_id: Option<u16>,
        vid_verification_statement: Option<&[u8]>,
        vvsc: Option<&[u8]>,
    ) -> Result<(), Error> {
        if let Some(vid) = vendor_id {
            self.vendor_id = vid;
        }

        if let Some(vvs) = vid_verification_statement {
            self.vid_verification_statement.clear();
            self.vid_verification_statement
                .extend_from_slice(vvs)
                .map_err(|_| ErrorCode::BufferTooSmall)?;
        }

        if let Some(v) = vvsc {
            // VVSC and ICAC share `icac_or_vvsc`. Clearing the VVSC must
            // not stomp on an existing ICAC: per spec the
            // two never coexist on the same fabric, so an empty-VVSC
            // request against a fabric that holds an ICAC is a no-op
            // here. The cluster handler still rejects a *non-empty* VVSC
            // against such a fabric upstream.
            if !v.is_empty() {
                self.icac_or_vvsc.clear();
                self.icac_or_vvsc
                    .extend_from_slice(v)
                    .map_err(|_| ErrorCode::BufferTooSmall)?;
                self.vvsc_set = true;
            } else if self.vvsc_set {
                self.icac_or_vvsc.clear();
                self.vvsc_set = false;
            }
        }

        Ok(())
    }

    /// Return an iterator over the ACL entries of the fabric
    pub fn acl_iter(&self) -> impl Iterator<Item = &AclEntry> {
        self.acl.iter()
    }

    /// Add a new ACL entry to the fabric.
    ///
    /// Return the index of the added entry.
    pub fn acl_add(&mut self, mut entry: AclEntry) -> Result<usize, Error> {
        if entry.auth_mode() == AuthMode::Pase {
            // Reserved for future use
            Err(ErrorCode::ConstraintError)?;
        }

        // Overwrite the fabric index with our accessing fabric index
        entry.fab_idx = Some(self.fab_idx);

        self.acl
            .push(entry)
            .map_err(|_| ErrorCode::ResourceExhausted)?;

        Ok(self.acl.len() - 1)
    }

    /// Add a new ACL entry to the fabric using the supplied initializer.
    ///
    /// Return the index of the added entry.
    pub fn acl_add_init<I>(&mut self, init: I) -> Result<usize, Error>
    where
        I: Init<AclEntry, Error>,
    {
        // if entry.auth_mode() == AuthMode::Pase {
        //     // Reserved for future use
        //     Err(ErrorCode::ConstraintError)?;
        // }

        self.acl
            .push_init(init, || ErrorCode::ResourceExhausted.into())?;

        let idx = self.acl.len() - 1;
        let entry = &mut self.acl[idx];

        // Overwrite the fabric index with our accessing fabric index
        entry.fab_idx = Some(self.fab_idx);

        Ok(idx)
    }

    /// Update an existing ACL entry in the fabric
    pub fn acl_update(&mut self, idx: usize, mut entry: AclEntry) -> Result<(), Error> {
        if self.acl.len() <= idx {
            return Err(ErrorCode::NotFound.into());
        }

        // Overwrite the fabric index with our accessing fabric index
        entry.fab_idx = Some(self.fab_idx);

        self.acl[idx] = entry;

        Ok(())
    }

    /// Update an existing ACL entry in the fabric using the supplied initializer
    pub fn acl_update_init<I>(&mut self, idx: usize, init: I) -> Result<(), Error>
    where
        I: Init<AclEntry, Error>,
    {
        if self.acl.len() <= idx {
            return Err(ErrorCode::NotFound.into());
        }

        // TODO: Needs #214
        let mut entry = MaybeUninit::uninit();
        let entry = entry.try_init_with(init)?.clone();

        self.acl[idx] = entry;

        // Overwrite the fabric index with our accessing fabric index
        self.acl[idx].fab_idx = Some(self.fab_idx);

        Ok(())
    }

    /// Remove an ACL entry from the fabric
    pub fn acl_remove(&mut self, idx: usize) -> Result<(), Error> {
        if self.acl.len() <= idx {
            return Err(ErrorCode::NotFound.into());
        }

        self.acl.remove(idx);

        Ok(())
    }

    /// Remove all ACL entries from the fabric
    pub fn acl_remove_all(&mut self) {
        // pub for tests
        self.acl.clear();
    }

    /// Check if the fabric allows the given access request
    ///
    /// Note that the fabric index in the access request needs to be checked before that.
    /// `aux_acl_enabled` conveys whether the node advertises the Access Control
    /// cluster's `AUXILIARY` feature - see `AclEntry::allow`.
    fn allow(&self, req: &AccessReq, aux_acl_enabled: bool) -> bool {
        for e in &self.acl {
            if e.allow(req, aux_acl_enabled) {
                return true;
            }
        }

        debug!(
            "ACL Disallow for subjects {} fab idx {}",
            req.accessor().subjects(),
            req.accessor().fab_idx
        );

        false
    }

    /// Compute the compressed fabric ID
    pub(crate) fn compute_compressed_fabric_id<C: Crypto>(
        crypto: C,
        root_pubkey: CanonPkcPublicKeyRef<'_>,
        fabric_id: u64,
    ) -> u64 {
        const COMPRESSED_FABRIC_ID_INFO: &[u8; 16] = &[
            0x43, 0x6f, 0x6d, 0x70, 0x72, 0x65, 0x73, 0x73, 0x65, 0x64, 0x46, 0x61, 0x62, 0x72,
            0x69, 0x63,
        ];

        let mut compressed_fabric_id = CryptoSensitive::<{ COMPRESSED_FABRIC_ID_LEN }>::new();
        unwrap!(unwrap!(crypto.kdf()).expand(
            &fabric_id.to_be_bytes(),
            root_pubkey.split::<1, { PKC_CANON_PUBLIC_KEY_LEN - 1 }>().1,
            COMPRESSED_FABRIC_ID_INFO,
            &mut compressed_fabric_id,
        ));

        u64::from_be_bytes(*compressed_fabric_id.access())
    }
}

cfg_if! {
    if #[cfg(feature = "max-fabrics-32")] {
        /// Max number of supported fabrics
        pub const MAX_FABRICS: usize = 32;
    } else if #[cfg(feature = "max-fabrics-16")] {
        /// Max number of supported fabrics
        pub const MAX_FABRICS: usize = 16;
    } else if #[cfg(feature = "max-fabrics-8")] {
        /// Max number of supported fabrics
        pub const MAX_FABRICS: usize = 8;
    } else if #[cfg(feature = "max-fabrics-7")] {
        /// Max number of supported fabrics
        pub const MAX_FABRICS: usize = 7;
    } else if #[cfg(feature = "max-fabrics-6")] {
        /// Max number of supported fabrics
        pub const MAX_FABRICS: usize = 6;
    } else { // Matter requires a minimum of 5 fabrics
        /// Max number of supported fabrics
        pub const MAX_FABRICS: usize = 5;
    }
}

/// All fabrics
pub struct Fabrics {
    fabrics: Vec<Fabric, MAX_FABRICS>,
}

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

impl Fabrics {
    /// Create a new Fabrics instance
    #[inline(always)]
    pub const fn new() -> Self {
        Self {
            fabrics: Vec::new(),
        }
    }

    /// Return an in-place-initializer for a Fabrics type
    pub fn init() -> impl Init<Self> {
        init!(Self {
            fabrics <- Vec::init(),
        })
    }

    /// Remove all fabrics
    pub fn reset(&mut self) {
        self.fabrics.clear();
    }

    /// Remove all fabrics from the provided BLOB store as well as from memory.
    ///
    /// # Arguments
    /// - `store`: the BLOB store to remove the fabrics from
    /// - `buf`: a temporary buffer to use for removing the fabrics
    pub fn reset_persist<S: KvBlobStore>(
        &mut self,
        mut store: S,
        buf: &mut [u8],
    ) -> Result<(), Error> {
        self.reset();

        for idx in 1..=255u8 {
            store.remove(FABRIC_KEYS_START + idx as u16, buf)?;
        }

        info!("Removed all fabrics from storage");

        Ok(())
    }

    /// Load all fabrics from the provided BLOB store
    ///
    /// # Arguments
    /// - `store`: the BLOB store to load the fabrics from
    /// - `buf`: a temporary buffer to use for loading the fabrics
    pub fn load_persist<S: KvBlobStore>(
        &mut self,
        mut store: S,
        buf: &mut [u8],
    ) -> Result<(), Error> {
        self.reset();

        for fab_idx in 1..=255u8 {
            self.add_load(fab_idx, &mut store, buf)?;
        }

        Ok(())
    }

    pub(crate) fn add_load<S: KvBlobStore>(
        &mut self,
        fab_idx: u8,
        mut store: S,
        buf: &mut [u8],
    ) -> Result<(), Error> {
        if let Some(data) = store.load(FABRIC_KEYS_START + fab_idx as u16, buf)? {
            self.fabrics
                .push_init(Fabric::init_from_tlv(TLVElement::new(data)), || {
                    ErrorCode::ResourceExhausted.into()
                })?;

            let fabric = unwrap!(self.fabrics.last());

            info!(
                "Loaded fabric {} with ID {:x} from storage",
                fabric.fab_idx(),
                fabric.compressed_fabric_id()
            );
        }

        Ok(())
    }

    /// Add a new fabric to the fabrics with the provided data and immediately updates it with the provided post-init updater.
    ///
    /// This method is unlikely to be useful outside of tests.
    ///
    /// If this operation succeeds, the fabric immediately becomes operational.
    pub fn add_with_post_init<F>(&mut self, post_init: F) -> Result<&mut Fabric, Error>
    where
        F: FnOnce(&mut Fabric) -> Result<(), Error>,
    {
        let max_fab_idx = self
            .iter()
            .map(|fabric| fabric.fab_idx().get())
            .max()
            .unwrap_or(0);
        let fab_idx = unwrap!(NonZeroU8::new(if max_fab_idx < u8::MAX - 1 {
            // First try with the next available fabric index larger than all currently used
            max_fab_idx + 1
        } else {
            // If there is already a fabric with index 254, try to find the first unused one
            let Some(fab_idx) = (1..u8::MAX)
                .find(|fab_idx| self.iter().all(|fabric| fabric.fab_idx().get() != *fab_idx))
            else {
                return Err(ErrorCode::ResourceExhausted.into());
            };

            fab_idx
        })); // We never use 0 as a fabric index, nor u8::MAX

        self.fabrics.push_init(
            Fabric::init(fab_idx)
                .into_fallible::<Error>()
                .chain(post_init),
            || ErrorCode::ResourceExhausted.into(),
        )?;

        let fabric = unwrap!(self.fabrics.last_mut());

        Ok(fabric)
    }

    /// Add a new fabric to the fabrics with the provided data.
    ///
    /// If this operation succeeds, the fabric immediately becomes operational.
    #[allow(clippy::too_many_arguments)]
    pub fn add<C: Crypto>(
        &mut self,
        crypto: C,
        secret_key: CanonPkcSecretKeyRef<'_>,
        root_ca: &[u8],
        noc: &[u8],
        icac: &[u8],
        epoch_key: Option<CanonAeadKeyRef<'_>>,
        vendor_id: u16,
        case_admin_subject: u64,
    ) -> Result<&mut Fabric, Error> {
        self.add_with_post_init(|fabric| {
            fabric.update(
                crypto,
                Some(root_ca),
                noc,
                icac,
                secret_key,
                epoch_key,
                Some(vendor_id),
                Some(case_admin_subject),
            )
        })
    }

    /// Update an existing fabric with the provided data (usually, as a result of an `UpdateNOC` IM command).
    ///
    /// The fabric's existing root cert is preserved across this call —
    /// `UpdateNOC` per Matter Core spec is not allowed
    /// to change the root, and re-passing the bytes would force the
    /// caller to take a (large) heap-less copy of `Fabric::root_ca`.
    ///
    /// If this operation succeeds, the fabric immediately becomes operational.
    /// Note however, that the caller is expected to remove all sessions associated with the fabric, as they would
    /// contain invalid keys after the NOC update.
    pub fn update<C: Crypto>(
        &mut self,
        crypto: C,
        fab_idx: NonZeroU8,
        secret_key: CanonPkcSecretKeyRef<'_>,
        noc: &[u8],
        icac: &[u8],
    ) -> Result<&mut Fabric, Error> {
        let fabric = self.fabric_mut(fab_idx)?;

        fabric.update(crypto, None, noc, icac, secret_key, None, None, None)?;

        Ok(fabric)
    }

    pub fn update_label(&mut self, fab_idx: NonZeroU8, label: &str) -> Result<&mut Fabric, Error> {
        if self.iter().any(|fabric| {
            fabric.fab_idx != fab_idx && !fabric.label.is_empty() && fabric.label == label
        }) {
            return Err(ErrorCode::Invalid.into());
        }

        let fabric = self.fabric_mut(fab_idx)?;
        fabric.label.clear();
        fabric
            .label
            .push_str(label)
            .map_err(|_| ErrorCode::ConstraintError)?;

        Ok(fabric)
    }

    /// Remove a fabric from the fabrics
    pub fn remove(&mut self, fab_idx: NonZeroU8) -> Result<(), Error> {
        let _ = self.fabric(fab_idx)?;

        self.fabrics.retain(|fabric| fabric.fab_idx != fab_idx);

        Ok(())
    }

    /// Get a fabric that matches the provided destination ID
    pub fn get_by_dest_id<C: Crypto>(
        &self,
        crypto: C,
        random: &[u8],
        target: &[u8],
    ) -> Option<&Fabric> {
        self.iter()
            .find(|fabric| fabric.is_dest_id(&crypto, random, target).is_ok())
    }

    /// Get a fabric by its local index
    pub fn get(&self, fab_idx: NonZeroU8) -> Option<&Fabric> {
        self.iter().find(|fabric| fabric.fab_idx == fab_idx)
    }

    /// Get a mutable fabric reference by its local index
    pub fn get_mut(&mut self, fab_idx: NonZeroU8) -> Option<&mut Fabric> {
        // pub for testing
        self.fabrics
            .iter_mut()
            .find(|fabric| fabric.fab_idx == fab_idx)
    }

    /// Iterate over the fabrics
    pub fn iter(&self) -> impl Iterator<Item = &Fabric> {
        self.fabrics.iter()
    }

    /// Get a fabric by its local index
    ///
    /// Returns an error if the fabric is not found
    pub fn fabric(&self, fab_idx: NonZeroU8) -> Result<&Fabric, Error> {
        self.get(fab_idx).ok_or(ErrorCode::NotFound.into())
    }

    /// Get a mutable fabric reference by its local index
    ///
    /// Returns an error if the fabric is not found
    pub fn fabric_mut(&mut self, fab_idx: NonZeroU8) -> Result<&mut Fabric, Error> {
        self.get_mut(fab_idx).ok_or(ErrorCode::NotFound.into())
    }

    /// Check if the given access request should be allowed, based on all operational fabrics
    /// and their ACLs
    ///
    /// `aux_acl_enabled` conveys whether the node advertises the Access Control
    /// cluster's `AUXILIARY` feature - see `AclEntry::allow`.
    pub fn allow(&self, req: &AccessReq, aux_acl_enabled: bool) -> bool {
        // PASE Sessions with no fabric index have implicit access grant,
        // but only as long as the ACL list is empty
        //
        // As per the spec:
        // The Access Control List is able to have an initial entry added because the Access Control Privilege
        // Granting algorithm behaves as if, over a PASE commissioning channel during the commissioning
        // phase, the following implicit Access Control Entry were present on the Commissionee (but not on
        // the Commissioner):
        // Access Control Cluster: {
        //     ACL: [
        //         0: {
        //             // implicit entry only; does not explicitly exist!
        //             FabricIndex: 0, // not fabric-specific
        //             Privilege: Administer,
        //             AuthMode: PASE,
        //             Subjects: [],
        //             Targets: [] // entire node
        //         }
        //     ],
        //     Extension: []
        // }
        if req.accessor().auth_mode() == Some(AuthMode::Pase) {
            return true;
        }

        let Ok(fab_idx) = req.accessor().fab_idx() else {
            return false;
        };

        let Some(fabric) = self.get(fab_idx) else {
            return false;
        };

        fabric.allow(req, aux_acl_enabled)
    }
}

/// A utility for persisting a fabric in a `KvBlobStore` instance.
pub struct FabricPersist<S>(Persist<S>);

impl<S> FabricPersist<S>
where
    S: KvBlobStoreAccess,
{
    /// Create a new `FabricPersist` with the given key-value store instance.
    pub const fn new(kvb: S) -> Self {
        Self(Persist::new(kvb))
    }

    /// Return a reference to the underlying `Persist` instance.
    pub fn persist_mut(&mut self) -> &mut Persist<S> {
        &mut self.0
    }

    /// Save the provided fabric in the persistent storage.
    pub fn store(&mut self, fabric: &Fabric) -> Result<(), Error> {
        self.0
            .store_tlv(FABRIC_KEYS_START + fabric.fab_idx().get() as u16, fabric)
    }

    /// Remove the fabric with the given index from the persistent storage.
    pub fn remove(&mut self, fab_idx: NonZeroU8) -> Result<(), Error> {
        self.0.remove(FABRIC_KEYS_START + fab_idx.get() as u16)
    }

    /// Call at the end when finished with everything else
    /// No-op for now
    pub fn run(self) -> Result<(), Error> {
        self.0.run()
    }
}

#[cfg(test)]
mod tests {
    use core::mem::MaybeUninit;

    use crate::cert::gen::{CertGenerator, CertType, IssuerDN, SubjectDN, Validity};
    use crate::cert::MAX_CERT_TLV_AND_ASN1_LEN;
    use crate::crypto::test_only_crypto;
    use crate::crypto::{
        CanonAeadKeyRef, CanonPkcSecretKey, Crypto, Hash, PublicKey, SecretKey, SigningSecretKey,
        AEAD_CANON_KEY_LEN,
    };
    use crate::utils::init::InitMaybeUninit;

    use core::num::NonZeroU8;

    use super::{Fabric, Fabrics};

    /// Lock the on-disk TLV tag layout of the fields whose position is sensitive
    /// to the `groups` feature. A released `rs-matter` persists `groups` at
    /// context tag 13 and `vid_verification_statement` at 14; gating `groups` in
    /// or out must not move either. Serializing an (empty) `Fabric` and checking
    /// the raw tags catches any future reorder that would silently corrupt
    /// existing persisted fabrics.
    #[test]
    fn fabric_tlv_tag_layout_is_stable() {
        use crate::tlv::{TLVElement, TLVTag, ToTLV};
        use crate::utils::init::InitMaybeUninit;
        use crate::utils::storage::WriteBuf;

        let mut fabric = core::mem::MaybeUninit::<Fabric>::uninit();
        let fabric = fabric.init_with(Fabric::init(unwrap!(NonZeroU8::new(1))));

        let mut buf = [0u8; 512];
        let mut wb = WriteBuf::new(&mut buf);
        fabric.to_tlv(&TLVTag::Anonymous, &mut wb).unwrap();
        let len = wb.get_tail();

        let root = TLVElement::new(&buf[..len]).structure().unwrap();

        // `find_ctx` returns an EMPTY element (not an error) when the tag is
        // absent, so presence is `!is_empty()` and absence is `is_empty()`.

        // `acl` (the last always-present field before the sensitive pair) is at 12.
        assert!(
            !root.find_ctx(12).unwrap().is_empty(),
            "acl must stay at TLV tag 12"
        );

        // `vid_verification_statement` must always be at context tag 14.
        assert!(
            !root.find_ctx(14).unwrap().is_empty(),
            "vid_verification_statement must stay at TLV tag 14"
        );

        // With `groups` compiled in it must be at tag 13; compiled out, tag 13 is
        // simply absent (and a reader defaults it).
        #[cfg(feature = "groups")]
        assert!(
            !root.find_ctx(13).unwrap().is_empty(),
            "groups must be at TLV tag 13 when compiled in"
        );
        #[cfg(not(feature = "groups"))]
        assert!(
            root.find_ctx(13).unwrap().is_empty(),
            "no field should occupy tag 13 when groups is compiled out"
        );
    }

    /// Verify that `compute_dest_id` and `is_dest_id` agree: the hash output by
    /// `compute_dest_id` must be accepted by `is_dest_id` on the same fabric with
    /// the same random nonce.
    ///
    /// Uses runtime-generated certs (via `CertGenerator`) with a real keypair
    /// so the fabric is in a valid state — the secret key matches the NOC's public key.
    #[test]
    fn test_compute_dest_id_matches_is_dest_id() {
        let crypto = test_only_crypto();

        let fabric_id: u64 = 1;
        let rcac_id: u64 = 1;
        let node_id: u64 = 100;

        // Generate RCAC keypair and build self-signed RCAC
        let rcac_secret_key = crypto.generate_secret_key().unwrap();
        let mut rcac_pubkey_canon = crate::crypto::CanonPkcPublicKey::new();
        rcac_secret_key
            .pub_key()
            .unwrap()
            .write_canon(&mut rcac_pubkey_canon)
            .unwrap();

        let validity = Validity {
            not_before: 0,
            not_after: 0,
        };

        let mut rcac_buf = [0u8; MAX_CERT_TLV_AND_ASN1_LEN];
        let rcac_len = CertGenerator::new(&mut rcac_buf)
            .generate(
                &crypto,
                CertType::Rcac,
                &[0x01],
                validity,
                SubjectDN {
                    node_id: None,
                    fabric_id: Some(fabric_id),
                    cat_ids: &[],
                    ca_id: Some(rcac_id),
                },
                IssuerDN {
                    ca_id: None,
                    fabric_id: None,
                    is_rcac: false,
                },
                rcac_pubkey_canon.reference(),
                None,
                &rcac_secret_key,
            )
            .unwrap();

        // Generate NOC keypair and build NOC signed by RCAC
        let noc_secret_key = crypto.generate_secret_key().unwrap();
        let mut noc_pubkey_canon = crate::crypto::CanonPkcPublicKey::new();
        noc_secret_key
            .pub_key()
            .unwrap()
            .write_canon(&mut noc_pubkey_canon)
            .unwrap();

        let mut noc_secret_key_canon = CanonPkcSecretKey::new();
        noc_secret_key
            .write_canon(&mut noc_secret_key_canon)
            .unwrap();

        let mut noc_buf = [0u8; MAX_CERT_TLV_AND_ASN1_LEN];
        let noc_len = CertGenerator::new(&mut noc_buf)
            .generate(
                &crypto,
                CertType::Noc,
                &[0x02],
                validity,
                SubjectDN {
                    node_id: Some(node_id),
                    fabric_id: Some(fabric_id),
                    cat_ids: &[],
                    ca_id: None,
                },
                IssuerDN {
                    ca_id: Some(rcac_id),
                    fabric_id: Some(fabric_id),
                    is_rcac: true,
                },
                noc_pubkey_canon.reference(),
                Some(rcac_pubkey_canon.reference()),
                &rcac_secret_key,
            )
            .unwrap();

        // Build fabric with real certs and matching secret key
        let epoch_key = [0x5a_u8; AEAD_CANON_KEY_LEN];
        let mut fabrics = Fabrics::new();
        fabrics
            .add(
                &crypto,
                noc_secret_key_canon.reference(),
                &rcac_buf[..rcac_len],
                &noc_buf[..noc_len],
                &[], // no ICAC
                Some(CanonAeadKeyRef::new(&epoch_key)),
                0x8000,
                node_id,
            )
            .expect("Fabrics::add should succeed");

        let fab_idx = core::num::NonZeroU8::new(1).unwrap();
        let fabric = fabrics
            .get(fab_idx)
            .expect("fabric at index 1 should exist");

        let random = [0xABu8; 32];

        // Compute the destination ID (targeting this fabric's own node).
        let mut dest_id = MaybeUninit::<Hash>::uninit();
        let dest_id = dest_id.init_with(Hash::init());
        fabric
            .compute_dest_id(&crypto, &random, fabric.node_id(), dest_id)
            .expect("compute_dest_id should not fail");

        // is_dest_id must accept the computed value.
        fabric
            .is_dest_id(&crypto, &random, dest_id.access())
            .expect("is_dest_id should accept hash produced by compute_dest_id");
    }
}