willow25 0.7.0

use core::fmt;

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

use signature::{Keypair, Signer};

use ufotofu::codec_prelude::*;

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

/// A [valid](https://willowprotocol.org/specs/meadowcap/index.html#cap_valid) read capability.
///
/// ```
/// use rand::rngs::OsRng;
/// use willow25::{prelude::*, authorisation::*};
///
/// # #[cfg(feature = "dev")] {
/// let mut csprng = OsRng;
/// let (subspace_id, secret) = randomly_generate_subspace(&mut csprng);
/// let namespace_id = NamespaceId::from_bytes(&[17; 32]);
///
/// let mut cap = ReadCapability::new_communal(
///     namespace_id,
///     subspace_id.clone(),
/// );
///
/// assert_eq!(cap.receiver(), &subspace_id);
///
/// let new_receiver = SubspaceId::from_bytes(&[18; 32]);
///
/// cap.delegate(&secret, Area::new_subspace_area(subspace_id), new_receiver.clone());
///
/// assert_eq!(cap.receiver(), &new_receiver);
/// # }
/// ```
#[derive(Clone, PartialEq, Eq)]
pub struct ReadCapability {
    pub(crate) inner: PossiblyValidReadCapability,
}

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

impl ReadCapability {
    /// Returns the [receiver](https://willowprotocol.org/specs/meadowcap/index.html#cap_receiver) of this capability.
    ///
    /// ```
    /// use willow25::{prelude::*, authorisation::*};
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let cap = ReadCapability::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).
    ///
    /// ```
    /// use willow25::{prelude::*, authorisation::*};
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let cap = ReadCapability::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), 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`](ReadCapability::granted_area).
    ///
    /// ```
    /// use rand::rngs::OsRng;
    /// use willow25::{prelude::*, authorisation::*};
    ///
    /// # #[cfg(feature = "dev")] {
    /// let mut csprng = OsRng;
    /// let (subspace_id, secret) = randomly_generate_subspace(&mut csprng);
    /// let namespace_id = NamespaceId::from_bytes(&[17; 32]);
    ///
    /// let mut cap = ReadCapability::new_communal(
    ///     namespace_id,
    ///     subspace_id.clone(),
    /// );
    ///
    /// assert_eq!(cap.granted_area_ref(), None);
    ///
    /// let new_receiver = SubspaceId::from_bytes(&[18; 32]);
    ///
    /// cap.delegate(&secret, Area::new_subspace_area(subspace_id.clone()), new_receiver.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::*, authorisation::*, authorisation::raw::AccessMode};
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let mut cap = ReadCapability::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 an owned capability.
    ///
    /// ```
    /// use rand::rngs::OsRng;
    /// use willow25::{prelude::*, authorisation::*};
    ///
    /// # #[cfg(feature = "dev")] {
    /// let mut csprng = OsRng;
    /// let (namespace_id, secret) = randomly_generate_namespace(&mut csprng);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let mut owncap = ReadCapability::new_owned(
    ///     &secret,
    ///     subspace_id.clone(),
    /// );
    ///
    /// assert!(owncap.is_owned());
    ///
    /// let comcap = ReadCapability::new_communal(namespace_id.clone(), subspace_id);
    ///
    /// 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 rand::rngs::OsRng;
    /// use willow25::{prelude::*, authorisation::*};
    ///
    /// # #[cfg(feature = "dev")] {
    /// let mut csprng = OsRng;
    /// let (subspace_id, secret) = randomly_generate_subspace(&mut csprng);
    /// let namespace_id = NamespaceId::from_bytes(&[17; 32]);
    ///
    /// let mut cap = ReadCapability::new_communal(
    ///     namespace_id,
    ///     subspace_id.clone(),
    /// );
    ///
    /// assert!(cap.delegations().is_empty());
    ///
    /// let new_receiver = SubspaceId::from_bytes(&[18; 32]);
    /// cap.delegate(&secret, Area::new_subspace_area(subspace_id.clone()), new_receiver.clone());
    ///
    /// assert_eq!(cap.delegations().len(), 1);
    /// # }
    /// ```
    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::*, authorisation::*};
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let cap = ReadCapability::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: PossiblyValidReadCapability::new_communal(namespace_key, user_key),
        }
    }

    /// Creates a new [owned](https://willowprotocol.org/specs/meadowcap/index.html#owned_capabilities) read capability with no delegations.
    ///
    /// ```
    /// use rand::rngs::OsRng;
    /// use willow25::{prelude::*, authorisation::*};
    ///
    /// # #[cfg(feature = "dev")] {
    /// let mut csprng = OsRng;
    /// let (namespace_id, secret) = randomly_generate_namespace(&mut csprng);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let mut cap = ReadCapability::new_owned(
    ///     &secret,
    ///     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::full());
    /// assert!(cap.delegations().is_empty());
    /// # }
    /// ```
    pub fn new_owned<NamespaceKeypair>(keypair: &NamespaceKeypair, user_key: SubspaceId) -> Self
    where
        NamespaceKeypair: Signer<NamespaceSignature> + Keypair<VerifyingKey = NamespaceId>,
    {
        let data_to_sign = owned_genesis_data_to_sign(AccessMode::Read, &user_key);

        let initial_authorisation = keypair.sign(&data_to_sign[..]);

        Self {
            inner: PossiblyValidReadCapability::new_owned(
                keypair.verifying_key(),
                user_key,
                initial_authorisation,
            ),
        }
    }

    /// Returns whether the given area is contained in the [granted area](ReadCapability::granted_area_ref) of this capability.
    ///
    /// ```
    /// use willow25::{prelude::*, authorisation::*};
    ///
    /// # #[cfg(feature = "dev")] {
    /// let namespace_id = NamespaceId::from_bytes(&[16; 32]);
    /// let subspace_id = SubspaceId::from_bytes(&[17; 32]);
    ///
    /// let cap = ReadCapability::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)
    }

    /// Returns by value the [area to which this grants access](https://willowprotocol.org/specs/meadowcap/index.html#cap_granted_area).
    ///
    /// Prefer using [`includes`](ReadCapability::includes), [`includes_area`](ReadCapability::includes_area) or [`granted_area_ref`](ReadCapability::granted_area_ref) whenever applicable, as these are more efficient.
    ///
    /// ```
    /// use rand::rngs::OsRng;
    /// use willow25::{prelude::*, authorisation::*};
    ///
    /// # #[cfg(feature = "dev")] {
    /// let mut csprng = OsRng;
    /// let (namespace_id, namespace_secret) = randomly_generate_namespace(&mut csprng);
    /// let (subspace_id, subspace_secret) = randomly_generate_subspace(&mut csprng);
    ///
    /// let mut cap = ReadCapability::new_owned(
    ///     &namespace_secret,
    ///     subspace_id.clone(),
    /// );
    ///
    /// assert_eq!(cap.granted_area(), Area::full());
    ///
    /// let new_receiver = SubspaceId::from_bytes(&[18; 32]);
    /// cap.delegate(&subspace_secret, Area::new_subspace_area(subspace_id.clone()), new_receiver.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 = ReadCapability::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)
    }

    /// Delegates this capability, returning an error if the resulting granted area would not be included in the previous granted area, or if the public key of the keypair was not the receiver of the capability pre-delegation.
    ///
    /// ```
    /// use rand::rngs::OsRng;
    /// use willow25::{prelude::*, authorisation::*};
    ///
    /// # #[cfg(feature = "dev")] {
    /// let mut csprng = OsRng;
    /// let (subspace_id, secret) = randomly_generate_subspace(&mut csprng);
    /// let (_subspace_id2, secret2) = randomly_generate_subspace(&mut csprng);
    /// let namespace_id = NamespaceId::from_bytes(&[17; 32]);
    /// let new_receiver = SubspaceId::from_bytes(&[18; 32]);
    ///
    /// let mut cap = ReadCapability::new_communal(
    ///     namespace_id,
    ///     subspace_id.clone(),
    /// );
    ///
    /// // Trying to delegate with an invalid secret fails.
    /// assert!(
    ///     cap.try_delegate(
    ///         &secret2,
    ///         Area::new_subspace_area(subspace_id.clone()),
    ///         new_receiver.clone(),
    ///     ).is_err()
    /// );
    ///
    /// // Trying to delegate to a greater area fails.
    /// assert!(
    ///     cap.try_delegate(
    ///         &secret,
    ///         Area::full(),
    ///         new_receiver.clone(),
    ///     ).is_err()
    /// );
    ///
    /// // Delegating with the correct secret and to a contained area succeeds.
    /// assert!(
    ///     cap.try_delegate(
    ///         &secret,
    ///         Area::new_subspace_area(subspace_id.clone()),
    ///         new_receiver.clone(),
    ///     ).is_ok()
    /// );
    /// # }
    /// ```
    pub fn try_delegate<UserKeypair>(
        &mut self,
        keypair: &UserKeypair,
        new_area: Area,
        new_receiver: SubspaceId,
    ) -> Result<(), InvalidCapability>
    where
        UserKeypair: Signer<SubspaceSignature> + Keypair<VerifyingKey = SubspaceId>,
    {
        if !self.granted_area().includes_grouping(&new_area) {
            return Err(InvalidCapability);
        }

        let handover =
            self.inner
                .inner
                .create_handover(&new_area, &new_receiver, self.delegations().last());

        let prev_receiver = self.receiver();

        if prev_receiver != &keypair.verifying_key() {
            return Err(InvalidCapability);
        }

        let signature = keypair.sign(&handover);

        let delegation = Delegation {
            area: new_area,
            user: new_receiver,
            signature,
        };

        // We already performed all required checks, so we append directly to the vec of delegations.
        self.inner.inner.delegations.push(delegation);

        Ok(())
    }

    /// Delegates this capability, panicking if the resulting granted area would not be included in the previous granted area, or if the public key of the keypair was not the receiver of the capability pre-delegation.
    ///
    /// ```
    /// use rand::rngs::OsRng;
    /// use willow25::{prelude::*, authorisation::*};
    ///
    /// # #[cfg(feature = "dev")] {
    /// let mut csprng = OsRng;
    /// let (subspace_id, secret) = randomly_generate_subspace(&mut csprng);
    /// let namespace_id = NamespaceId::from_bytes(&[17; 32]);
    /// let new_receiver = SubspaceId::from_bytes(&[18; 32]);
    ///
    /// let mut cap = ReadCapability::new_communal(
    ///     namespace_id,
    ///     subspace_id.clone(),
    /// );
    ///
    /// // This works =)
    /// cap.delegate(
    ///     &secret,
    ///     Area::new_subspace_area(subspace_id.clone()),
    ///     new_receiver.clone(),
    /// );
    /// # }
    /// ```
    ///
    /// ```should_panic
    /// use rand::rngs::OsRng;
    /// use willow25::{prelude::*, authorisation::*};
    ///
    /// # #[cfg(not(feature = "dev"))] {panic!()}
    /// # #[cfg(feature = "dev")] {
    /// let mut csprng = OsRng;
    /// let (subspace_id, secret) = randomly_generate_subspace(&mut csprng);
    /// let (_subspace_id2, secret2) = randomly_generate_subspace(&mut csprng);
    /// let namespace_id = NamespaceId::from_bytes(&[17; 32]);
    /// let new_receiver = SubspaceId::from_bytes(&[18; 32]);
    ///
    /// let mut cap = ReadCapability::new_communal(
    ///     namespace_id,
    ///     subspace_id.clone(),
    /// );
    ///
    /// // Delegating with an invalid secret panics.
    /// cap.delegate(
    ///     &secret2,
    ///     Area::new_subspace_area(subspace_id.clone()),
    ///     new_receiver.clone(),
    /// );
    /// # }
    /// ```
    ///
    /// ```should_panic
    /// use rand::rngs::OsRng;
    /// use willow25::{prelude::*, authorisation::*};
    ///
    /// # #[cfg(not(feature = "dev"))] {panic!()}
    /// # #[cfg(feature = "dev")] {
    /// let mut csprng = OsRng;
    /// let (subspace_id, secret) = randomly_generate_subspace(&mut csprng);
    /// let namespace_id = NamespaceId::from_bytes(&[17; 32]);
    /// let new_receiver = SubspaceId::from_bytes(&[18; 32]);
    ///
    /// let mut cap = ReadCapability::new_communal(
    ///     namespace_id,
    ///     subspace_id.clone(),
    /// );
    ///
    /// // Delegating to a greater area panics.
    /// cap.delegate(
    ///     &secret,
    ///     Area::full(),
    ///     new_receiver.clone(),
    /// );
    /// # }
    /// ```
    pub fn delegate<UserKeypair>(
        &mut self,
        keypair: &UserKeypair,
        new_area: Area,
        new_receiver: SubspaceId,
    ) where
        UserKeypair: Signer<SubspaceSignature> + Keypair<VerifyingKey = SubspaceId>,
    {
        self.try_delegate(keypair, new_area, new_receiver).unwrap()
    }
}

/// Implements encoding according to the [encode_mc_capability](https://willowprotocol.org/specs/encodings/index.html#encode_mc_capability) encoding function.
impl Encodable for ReadCapability {
    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 ReadCapability {
    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.
impl Decodable for ReadCapability {
    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: PossiblyValidReadCapability = producer.produce_decoded().await?;

        if decoded.is_valid() {
            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.
impl DecodableCanonic for ReadCapability {
    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: PossiblyValidReadCapability = producer.produce_decoded_canonic().await?;

        if decoded.is_valid() {
            Ok(Self { inner: decoded })
        } else {
            Err(DecodeError::Other(Blame::TheirFault))
        }
    }
}

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

        if inner_cap.is_valid() {
            Ok(Self { inner: inner_cap })
        } else {
            Err(arbitrary::Error::IncorrectFormat)
        }
    }
}