willow25 0.7.7

#[cfg(feature = "dev")]
use arbitrary::Arbitrary;

use ufotofu::codec_prelude::*;

use super::RawCapability;

use crate::{
    authorisation::{
        ReadCapability,
        raw::{AccessMode, Delegation, Genesis, InvalidCapability},
    },
    prelude::*,
};

/// A read capability that has not been checked for [validity](https://willowprotocol.org/specs/meadowcap/index.html#cap_valid).
///
/// This is a low-level type. If possible, you should prefer using [`ReadCapability`](super::ReadCapability).
///
/// ```
/// use willow25::prelude::*;
/// use willow25::authorisation::raw::*;
///
/// # #[cfg(feature = "dev")] {
/// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
/// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
///
/// let mut cap = PossiblyValidReadCapability::new_communal(namespace_id, subspace_id.clone());
///
/// assert_eq!(cap.receiver(), &subspace_id);
///
/// let delegated_user = SubspaceId::from_bytes(&[18; 32]);
///
/// let delegation = Delegation::new(
///     Area::new_subspace_area(subspace_id),
///     delegated_user.clone(),
///     SubspaceSignature::from([19; 64]),
/// );
///
/// cap.append_delegation(delegation.clone());
///
/// assert_eq!(cap.receiver(), &delegated_user);
/// # }
/// ```
#[derive(Clone, PartialEq, Eq)]
pub struct PossiblyValidReadCapability {
    pub(crate) inner: RawCapability,
}

impl core::fmt::Debug for PossiblyValidReadCapability {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("PossiblyValidReadCapability")
            .field("genesis", &self.inner.genesis)
            .field("delegations", &self.inner.delegations)
            .finish()
    }
}

impl PossiblyValidReadCapability {
    /// Returns the [receiver](https://willowprotocol.org/specs/meadowcap/index.html#cap_receiver) of this capability (and simply assumes the capability is valid).
    ///
    /// ```
    /// use willow25::prelude::*;
    /// use willow25::authorisation::raw::*;
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let cap = PossiblyValidReadCapability::new_communal(namespace_id, subspace_id.clone());
    ///
    /// assert_eq!(cap.receiver(), &subspace_id);
    /// # }
    /// ```
    pub fn receiver(&self) -> &SubspaceId {
        self.inner.receiver()
    }

    /// Returns the [namespace id to which this grants access](https://willowprotocol.org/specs/meadowcap/index.html#cap_granted_namespace) (and simply assumes the capability is valid).
    ///
    /// ```
    /// use willow25::prelude::*;
    /// use willow25::authorisation::raw::*;
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let cap = PossiblyValidReadCapability::new_communal(namespace_id.clone(), subspace_id);
    ///
    /// assert_eq!(cap.granted_namespace(), &namespace_id);
    /// # }
    /// ```
    pub fn granted_namespace(&self) -> &NamespaceId {
        self.inner.granted_namespace()
    }

    /// Returns a reference to the [area to which this grants access](https://willowprotocol.org/specs/meadowcap/index.html#cap_granted_area) (and simply assumes the capability is valid), or `None` if there is no delegation step which restricts the initial area.
    ///
    /// This method is slightly inconvenient to work with (you need special logic if there are no delegation steps), but it is efficient because it never explicitly creates a new area value. For the more convenient version, see [`granted_area`](PossiblyValidReadCapability::granted_area).
    ///
    /// ```
    /// use willow25::prelude::*;
    /// use willow25::authorisation::raw::*;
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let mut cap = PossiblyValidReadCapability::new_communal(namespace_id, subspace_id.clone());
    ///
    /// assert_eq!(cap.granted_area_ref(), None);
    ///
    /// let delegation = Delegation::new(
    ///     Area::new_subspace_area(subspace_id.clone()),
    ///     SubspaceId::from_bytes(&[18; 32]),
    ///     SubspaceSignature::from([19; 64]),
    /// );
    ///
    /// cap.append_delegation(delegation.clone());
    ///
    /// assert_eq!(cap.granted_area_ref(), Some(&Area::new_subspace_area(subspace_id)));
    /// # }
    /// ```
    pub fn granted_area_ref(&self) -> Option<&Area> {
        self.inner.granted_area_ref()
    }

    /// Returns the [`Genesis`] of this capability.
    ///
    /// ```
    /// use willow25::prelude::*;
    /// use willow25::authorisation::raw::*;
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let mut cap = PossiblyValidReadCapability::new_communal(namespace_id.clone(), subspace_id.clone());
    ///
    /// let genesis = cap.genesis();
    ///
    /// assert_eq!(genesis.access_mode(), AccessMode::Read);
    /// assert_eq!(genesis.namespace_key(), &namespace_id);
    /// assert_eq!(genesis.user_key(), &subspace_id);
    /// # }
    /// ```
    pub fn genesis(&self) -> &Genesis {
        self.inner.genesis()
    }

    /// Returns `true` if and only if this is a capability for an owned namespace.
    ///
    /// ```
    /// use willow25::prelude::*;
    /// use willow25::authorisation::raw::*;
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let mut owncap = PossiblyValidReadCapability::new_owned(
    ///     namespace_id.clone(),
    ///     subspace_id.clone(),
    ///     NamespaceSignature::from([18; 64]),
    /// );
    ///
    /// assert!(owncap.is_owned());
    ///
    /// let mut comcap = PossiblyValidReadCapability::new_communal(
    ///     namespace_id.clone(),
    ///     subspace_id.clone(),
    /// );
    ///
    /// assert!(!comcap.is_owned());
    /// # }
    /// ```
    pub fn is_owned(&self) -> bool {
        self.inner.is_owned()
    }

    /// Returns the [`Delegations`](Delegation) of this capability as a slice.
    ///
    /// ```
    /// use willow25::prelude::*;
    /// use willow25::authorisation::raw::*;
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let mut cap = PossiblyValidReadCapability::new_communal(namespace_id, subspace_id.clone());
    ///
    /// assert!(cap.delegations().is_empty());
    ///
    /// let delegation = Delegation::new(
    ///     Area::new_subspace_area(subspace_id.clone()),
    ///     SubspaceId::from_bytes(&[18; 32]),
    ///     SubspaceSignature::from([19; 64]),
    /// );
    ///
    /// cap.append_delegation(delegation.clone());
    ///
    /// assert_eq!(cap.delegations()[0], delegation);
    /// # }
    /// ```
    pub fn delegations(&self) -> &[Delegation] {
        self.inner.delegations()
    }

    /// Creates a new [communal](https://willowprotocol.org/specs/meadowcap/index.html#communal_capabilities) read capability with no delegations.
    ///
    /// ```
    /// use willow25::prelude::*;
    /// use willow25::authorisation::raw::*;
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let mut cap = PossiblyValidReadCapability::new_communal(
    ///     namespace_id.clone(),
    ///     subspace_id.clone(),
    /// );
    ///
    /// assert!(!cap.is_owned());
    /// assert_eq!(cap.receiver(), &subspace_id);
    /// assert_eq!(cap.granted_namespace(), &namespace_id);
    /// assert_eq!(cap.granted_area(), Area::new_subspace_area(subspace_id));
    /// assert!(cap.delegations().is_empty());
    /// # }
    /// ```
    pub fn new_communal(namespace_key: NamespaceId, user_key: SubspaceId) -> Self {
        Self {
            inner: RawCapability::new_communal(super::AccessMode::Read, namespace_key, user_key),
        }
    }

    /// Creates a new [owned](https://willowprotocol.org/specs/meadowcap/index.html#owned_capabilities) read capability with no delegations.
    ///
    /// ```
    /// use willow25::prelude::*;
    /// use willow25::authorisation::raw::*;
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let mut cap = PossiblyValidReadCapability::new_owned(
    ///     namespace_id.clone(),
    ///     subspace_id.clone(),
    ///     NamespaceSignature::from([18; 64]),
    /// );
    ///
    /// assert!(cap.is_owned());
    /// assert_eq!(cap.receiver(), &subspace_id);
    /// assert_eq!(cap.granted_namespace(), &namespace_id);
    /// assert_eq!(cap.granted_area(), Area::full());
    /// assert!(cap.delegations().is_empty());
    /// # }
    /// ```
    pub fn new_owned(
        namespace_key: NamespaceId,
        user_key: SubspaceId,
        initial_authorisation: NamespaceSignature,
    ) -> Self {
        Self {
            inner: RawCapability::new_owned(
                super::AccessMode::Read,
                namespace_key,
                user_key,
                initial_authorisation,
            ),
        }
    }

    /// Converts `self` into a [`ReadCapability`] **without enforcing [validity](https://willowprotocol.org/specs/meadowcap/index.html#cap_valid)**.
    ///
    /// See [`into_read_capability`](PossiblyValidReadCapability::into_read_capability) for the safe (but less performant) version of this.
    ///
    /// #### Safety
    ///
    /// Undefined behaviour may occur if `self` is not [valid](https://willowprotocol.org/specs/meadowcap/index.html#cap_valid).
    pub unsafe fn into_read_capability_unchecked(self) -> ReadCapability {
        ReadCapability { inner: self }
    }

    /// Returns whether the given area is contained in the [granted area](PossiblyValidReadCapability::granted_area_ref) of this capability.
    ///
    /// ```
    /// use willow25::prelude::*;
    /// use willow25::authorisation::raw::*;
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let mut cap = PossiblyValidReadCapability::new_communal(
    ///     namespace_id.clone(),
    ///     subspace_id.clone(),
    /// );
    ///
    /// assert!(cap.includes_area(&Area::new_subspace_area(subspace_id)));
    /// assert!(!cap.includes_area(&Area::full()));
    /// # }
    /// ```
    pub fn includes_area(&self, area: &Area) -> bool {
        self.inner.includes_area(area)
    }

    /// Appends a new [`Delegation`] to this capability, returning an error if the resulting granted area would not be included in the previous granted area. **Does not verify any signatures.**
    ///
    /// ```
    /// use willow25::prelude::*;
    /// use willow25::authorisation::raw::*;
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let mut cap = PossiblyValidReadCapability::new_communal(namespace_id, subspace_id.clone());
    ///
    /// let contained_delegation = Delegation::new(
    ///     Area::new_subspace_area(subspace_id.clone()),
    ///     SubspaceId::from_bytes(&[18; 32]),
    ///     SubspaceSignature::from([19; 64]), // Invalid signature, but this is not checked.
    /// );
    ///
    /// assert!(cap.try_append_delegation(contained_delegation).is_ok());
    ///
    /// let invalid_delegation = Delegation::new(
    ///     Area::full(), // Greater than the granted area of `cap`.
    ///     SubspaceId::from_bytes(&[18; 32]),
    ///     SubspaceSignature::from([19; 64]), // Invalid signature, but this is not checked.
    /// );
    ///
    /// assert!(cap.try_append_delegation(invalid_delegation).is_err());
    /// # }
    /// ```
    pub fn try_append_delegation(
        &mut self,
        delegation: Delegation,
    ) -> Result<(), InvalidCapability> {
        self.inner.try_append_delegation(delegation)
    }

    /// Appends a new [`Delegation`] to this capability, panicking if the resulting granted area would not be included in the previous granted area. **Does not verify any signatures.**
    ///
    /// ```
    /// use willow25::prelude::*;
    /// use willow25::authorisation::raw::*;
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let mut cap = PossiblyValidReadCapability::new_communal(namespace_id, subspace_id.clone());
    ///
    /// let contained_delegation = Delegation::new(
    ///     Area::new_subspace_area(subspace_id.clone()),
    ///     SubspaceId::from_bytes(&[18; 32]),
    ///     SubspaceSignature::from([19; 64]), // Invalid signature, but this is not checked.
    /// );
    ///
    /// // Does not panic.
    /// cap.append_delegation(contained_delegation);
    /// # }
    /// ```
    ///
    /// ```should_panic
    /// use willow25::prelude::*;
    /// use willow25::authorisation::raw::*;
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let mut cap = PossiblyValidReadCapability::new_communal(namespace_id, subspace_id.clone());
    ///
    /// let invalid_delegation = Delegation::new(
    ///     Area::full(), // Greater than the granted area of `cap`.
    ///     SubspaceId::from_bytes(&[18; 32]),
    ///     SubspaceSignature::from([19; 64]), // Invalid signature, but this is not checked.
    /// );
    ///
    /// // Panics.
    /// cap.append_delegation(invalid_delegation)
    /// # }
    /// # #[cfg(not(feature = "dev"))] {panic!()}
    /// ```
    pub fn append_delegation(&mut self, delegation: Delegation) {
        self.inner.append_delegation(delegation)
    }

    /// Appends a new [`Delegation`] to this capability, returning an error if the resulting granted area would not be included in the previous granted area or if the signature is invalid.
    pub fn try_append_delegation_checking_validity(
        &mut self,
        delegation: Delegation,
    ) -> Result<(), InvalidCapability> {
        self.inner
            .try_append_delegation_checking_validity(delegation)
    }

    /// Appends a new [`Delegation`] to this capability, panicking if the resulting granted area would not be included in the previous granted area or if the signature is invalid.
    pub fn append_delegation_checking_validity(&mut self, delegation: Delegation) {
        self.try_append_delegation_checking_validity(delegation)
            .unwrap()
    }

    /// Returns by value the [area to which this grants access](https://willowprotocol.org/specs/meadowcap/index.html#cap_granted_area) (and simply assumes the capability is valid).
    ///
    /// Prefer using [`includes`](PossiblyValidReadCapability::includes), [`includes_area`](PossiblyValidReadCapability::includes_area) or [`granted_area_ref`](PossiblyValidReadCapability::granted_area_ref) whenever applicable, as these are more efficient.
    ///
    /// ```
    /// use willow25::prelude::*;
    /// use willow25::authorisation::raw::*;
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let mut cap = PossiblyValidReadCapability::new_owned(
    ///     namespace_id.clone(),
    ///     subspace_id.clone(),
    ///     NamespaceSignature::from([18; 64]),
    /// );
    ///
    /// assert_eq!(cap.granted_area(), Area::full());
    ///
    /// let delegation = Delegation::new(
    ///     Area::new_subspace_area(subspace_id.clone()),
    ///     SubspaceId::from_bytes(&[18; 32]),
    ///     SubspaceSignature::from([19; 64]),
    /// );
    ///
    /// cap.append_delegation(delegation.clone());
    ///
    /// assert_eq!(cap.granted_area(), Area::new_subspace_area(subspace_id));
    /// # }
    /// ```
    pub fn granted_area(&self) -> Area {
        self.inner.granted_area()
    }

    /// Returns whether the given [namespaced](Namespaced) [coordinate](Coordinatelike) is covered by this capability.
    ///
    /// ```
    /// use willow25::prelude::*;
    /// use willow25::authorisation::raw::*;
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let mut cap = PossiblyValidReadCapability::new_communal(namespace_id.clone(), subspace_id.clone());
    ///
    /// let included_entry = Entry::builder()
    ///     .namespace_id(namespace_id.clone())
    ///     .subspace_id(subspace_id.clone())
    ///     .path(path!(""))
    ///     .timestamp(12345)
    ///     .payload(b"hi")
    ///     .build();
    ///
    /// let outer_entry = Entry::prefilled_builder(&included_entry)
    ///     .subspace_id(SubspaceId::from_bytes(&[18; 32]))
    ///     .build();
    ///
    /// assert!(cap.includes(&included_entry));
    /// assert!(!cap.includes(&outer_entry));
    /// # }
    /// ```
    pub fn includes<T>(&self, t: &T) -> bool
    where
        T: Namespaced + Coordinatelike + ?Sized,
    {
        self.inner.includes(t)
    }

    /// Returns whether this capability is [valid](https://willowprotocol.org/specs/meadowcap/index.html#cap_valid).
    pub fn is_valid(&self) -> bool {
        self.inner.is_valid()
    }

    /// Converts `self` into a [`ReadCapability`], or returning `Err(self)` if `self` is not [valid](https://willowprotocol.org/specs/meadowcap/index.html#cap_valid).
    ///
    /// See [`into_read_capability_unchecked`](PossiblyValidReadCapability::into_read_capability_unchecked) for the unsafe (but more efficient) version of this.
    #[allow(clippy::result_large_err)]
    pub fn into_read_capability(self) -> Result<ReadCapability, Self> {
        if self.is_valid() {
            Ok(
                // SAFETY: this is safe if `self.is_valid()` is true, and we only enter this branch if it is.
                unsafe { self.into_read_capability_unchecked() },
            )
        } else {
            Err(self)
        }
    }
}

/// Implements encoding according to the [encode_mc_capability](https://willowprotocol.org/specs/encodings/index.html#encode_mc_capability) encoding function.
impl Encodable for PossiblyValidReadCapability {
    async fn encode<C>(&self, consumer: &mut C) -> Result<(), C::Error>
    where
        C: BulkConsumer<Item = u8> + ?Sized,
    {
        self.inner.encode(consumer).await
    }
}

impl EncodableKnownLength for PossiblyValidReadCapability {
    fn len_of_encoding(&self) -> usize {
        self.inner.len_of_encoding()
    }
}

/// Implements decoding according to the [EncodeMcCapability](https://willowprotocol.org/specs/encodings/index.html#EncodeMcCapability) encoding relation, and further errors if the decoded capability is a read capability. **Does not check the validity** of the decoded capability.
impl Decodable for PossiblyValidReadCapability {
    type ErrorReason = Blame;

    async fn decode<P>(
        producer: &mut P,
    ) -> Result<Self, DecodeError<P::Final, P::Error, Self::ErrorReason>>
    where
        P: BulkProducer<Item = u8> + ?Sized,
        Self: Sized,
    {
        let decoded: RawCapability = producer.produce_decoded().await?;

        if decoded.access_mode() == AccessMode::Read {
            Ok(Self { inner: decoded })
        } else {
            Err(DecodeError::Other(Blame::TheirFault))
        }
    }
}

/// Implements decoding according to the [encode_mc_capability](https://willowprotocol.org/specs/encodings/index.html#encode_mc_capability) encoding function, and further errors if the decoded capability is a read capability. **Does not check the validity** of the decoded capability.
impl DecodableCanonic for PossiblyValidReadCapability {
    type ErrorCanonic = Blame;

    async fn decode_canonic<P>(
        producer: &mut P,
    ) -> Result<Self, DecodeError<P::Final, P::Error, Self::ErrorCanonic>>
    where
        P: BulkProducer<Item = u8> + ?Sized,
        Self: Sized,
    {
        let decoded: RawCapability = producer.produce_decoded_canonic().await?;

        if decoded.access_mode() == AccessMode::Read {
            Ok(Self { inner: decoded })
        } else {
            Err(DecodeError::Other(Blame::TheirFault))
        }
    }
}

#[cfg(feature = "dev")]
impl<'a> Arbitrary<'a> for PossiblyValidReadCapability {
    fn arbitrary(u: &mut arbitrary::Unstructured<'a>) -> arbitrary::Result<Self> {
        let mut raw_cap: RawCapability = Arbitrary::arbitrary(u)?;

        match raw_cap.genesis {
            Genesis::Communal(super::CommunalGenesis {
                ref mut access_mode,
                ..
            }) => {
                *access_mode = AccessMode::Read;
            }
            Genesis::Owned(super::OwnedGenesis {
                ref mut access_mode,
                ..
            }) => {
                *access_mode = AccessMode::Read;
            }
        }

        Ok(Self { inner: raw_cap })
    }
}

impl From<ReadCapability> for PossiblyValidReadCapability {
    fn from(value: ReadCapability) -> Self {
        value.inner
    }
}