bc_envelope/base/

elide.rs

use std::collections::HashSet;

use anyhow::{ bail, Result };
use bc_components::{ DigestProvider, Digest };
#[cfg(feature = "encrypt")]
use bc_components::{ SymmetricKey, Nonce };
#[cfg(feature = "encrypt")]
use dcbor::prelude::*;

use crate::{ Assertion, Envelope, Error };

use super::envelope::EnvelopeCase;

/// Actions that can be performed on parts of an envelope to obscure them.
///
/// Gordian Envelope supports several ways to obscure parts of an envelope while
/// maintaining its semantic integrity and digest tree. This enum defines the
/// possible actions that can be taken when obscuring envelope elements.
///
/// Obscuring parts of an envelope is a key feature for privacy and selective disclosure,
/// allowing the holder of an envelope to share only specific parts while hiding,
/// encrypting, or compressing others.
pub enum ObscureAction {
    /// Elide the target, leaving only its digest.
    ///
    /// Elision replaces the targeted envelope element with just its digest,
    /// hiding its actual content while maintaining the integrity of the envelope's
    /// digest tree. This is the most basic form of selective disclosure.
    ///
    /// Elided elements can be revealed later by providing the original unelided
    /// envelope to the recipient, who can verify that the revealed content matches
    /// the digest in the elided version.
    Elide,

    /// Encrypt the target using the specified symmetric key.
    ///
    /// This encrypts the targeted envelope element using authenticated encryption
    /// with the provided key. The encrypted content can only be accessed by those
    /// who possess the symmetric key.
    ///
    /// This action is only available when the `encrypt` feature is enabled.
    #[cfg(feature = "encrypt")]
    Encrypt(SymmetricKey),

    /// Compress the target using a compression algorithm.
    ///
    /// This compresses the targeted envelope element to reduce its size while
    /// still allowing it to be decompressed by any recipient. Unlike elision or
    /// encryption, compression doesn't provide privacy but can reduce the size
    /// of large envelope components.
    ///
    /// This action is only available when the `compress` feature is enabled.
    #[cfg(feature = "compress")]
    Compress,
}

/// Support for eliding elements from envelopes.
///
/// This includes eliding, encrypting and compressing (obscuring) elements.
impl Envelope {
    /// Returns the elided variant of this envelope.
    ///
    /// Elision replaces an envelope with just its digest, hiding its content while
    /// maintaining the integrity of the envelope's digest tree. This is a fundamental
    /// privacy feature of Gordian Envelope that enables selective disclosure.
    ///
    /// Returns the same envelope if it is already elided.
    ///
    /// # Examples
    ///
    /// ```
    /// # use bc_envelope::prelude::*;
    /// # use indoc::indoc;
    /// let envelope = Envelope::new("Hello.");
    /// let elided = envelope.elide();
    ///
    /// // The elided envelope shows only "ELIDED" in formatting
    /// assert_eq!(elided.format_flat(), "ELIDED");
    ///
    /// // But it maintains the same digest as the original
    /// assert!(envelope.is_equivalent_to(&elided));
    /// ```
    pub fn elide(&self) -> Self {
        match self.case() {
            EnvelopeCase::Elided(_) => self.clone(),
            _ => Self::new_elided(self.digest().into_owned()),
        }
    }

    /// Returns a version of this envelope with elements in the `target` set elided.
    ///
    /// This function obscures elements in the envelope whose digests are in the provided target set,
    /// applying the specified action (elision, encryption, or compression) to those elements while
    /// leaving other elements intact.
    ///
    /// # Parameters
    ///
    /// * `target` - The set of digests that identify elements to be obscured
    /// * `action` - The action to perform on the targeted elements (elide, encrypt, or compress)
    ///
    /// # Examples
    ///
    /// ```
    /// # use bc_envelope::prelude::*;
    /// # use std::collections::HashSet;
    /// let envelope = Envelope::new("Alice")
    ///     .add_assertion("knows", "Bob")
    ///     .add_assertion("livesAt", "123 Main St.");
    ///
    /// // Create a set of digests targeting the "livesAt" assertion
    /// let mut target = HashSet::new();
    /// let livesAt_assertion = envelope.assertion_with_predicate("livesAt").unwrap();
    /// target.insert(livesAt_assertion.digest().into_owned());
    ///
    /// // Elide that specific assertion
    /// let elided = envelope.elide_removing_set_with_action(&target, &ObscureAction::Elide);
    ///
    /// // The result will have the "livesAt" assertion elided but "knows" still visible
    /// ```
    pub fn elide_removing_set_with_action(
        &self,
        target: &HashSet<Digest>,
        action: &ObscureAction
    ) -> Self {
        self.elide_set_with_action(target, false, action)
    }

    /// Returns a version of this envelope with elements in the `target` set elided.
    ///
    /// This is a convenience function that calls `elide_set` with `is_revealing` set to `false`,
    /// using the standard elision action. Use this when you want to simply elide elements rather
    /// than encrypt or compress them.
    ///
    /// # Parameters
    ///
    /// * `target` - The set of digests that identify elements to be elided
    ///
    /// # Examples
    ///
    /// ```
    /// # use bc_envelope::prelude::*;
    /// # use std::collections::HashSet;
    /// let envelope = Envelope::new("Alice")
    ///     .add_assertion("knows", "Bob")
    ///     .add_assertion("email", "alice@example.com");
    ///
    /// // Create a set of digests targeting the email assertion
    /// let mut target = HashSet::new();
    /// let email_assertion = envelope.assertion_with_predicate("email").unwrap();
    /// target.insert(email_assertion.digest().into_owned());
    ///
    /// // Elide the email assertion for privacy
    /// let redacted = envelope.elide_removing_set(&target);
    /// ```
    pub fn elide_removing_set(&self, target: &HashSet<Digest>) -> Self {
        self.elide_set(target, false)
    }

    /// Returns a version of this envelope with elements in the `target` set elided.
    ///
    /// - Parameters:
    ///   - target: An array of `DigestProvider`s.
    ///   - action: Perform the specified action (elision, encryption or compression).
    ///
    /// - Returns: The elided envelope.
    pub fn elide_removing_array_with_action(
        &self,
        target: &[&dyn DigestProvider],
        action: &ObscureAction
    ) -> Self {
        self.elide_array_with_action(target, false, action)
    }

    /// Returns a version of this envelope with elements in the `target` set elided.
    ///
    /// - Parameters:
    ///   - target: An array of `DigestProvider`s.
    ///   - action: Perform the specified action (elision, encryption or compression).
    ///
    /// - Returns: The elided envelope.
    pub fn elide_removing_array(&self, target: &[&dyn DigestProvider]) -> Self {
        self.elide_array(target, false)
    }

    /// Returns a version of this envelope with the target element elided.
    ///
    /// - Parameters:
    ///   - target: A `DigestProvider`.
    ///   - action: Perform the specified action (elision, encryption or compression).
    ///
    /// - Returns: The elided envelope.
    pub fn elide_removing_target_with_action(
        &self,
        target: &dyn DigestProvider,
        action: &ObscureAction
    ) -> Self {
        self.elide_target_with_action(target, false, action)
    }

    /// Returns a version of this envelope with the target element elided.
    ///
    /// - Parameters:
    ///   - target: A `DigestProvider`.
    ///
    /// - Returns: The elided envelope.
    pub fn elide_removing_target(&self, target: &dyn DigestProvider) -> Self {
        self.elide_target(target, false)
    }

    /// Returns a version of this envelope with only elements in the `target` set revealed,
    /// and all other elements elided.
    ///
    /// This function performs the opposite operation of `elide_removing_set_with_action`.
    /// Instead of specifying which elements to obscure, you specify which elements to reveal,
    /// and everything else will be obscured using the specified action.
    ///
    /// This is particularly useful for selective disclosure where you want to reveal only
    /// specific portions of an envelope while keeping the rest private.
    ///
    /// # Parameters
    ///
    /// * `target` - The set of digests that identify elements to be revealed
    /// * `action` - The action to perform on all other elements (elide, encrypt, or compress)
    ///
    /// # Examples
    ///
    /// ```
    /// # use bc_envelope::prelude::*;
    /// # use std::collections::HashSet;
    /// let envelope = Envelope::new("Alice")
    ///     .add_assertion("name", "Alice Smith")
    ///     .add_assertion("age", 30)
    ///     .add_assertion("ssn", "123-45-6789");
    ///
    /// // Create a set of digests for elements we want to reveal
    /// let mut reveal_set = HashSet::new();
    ///
    /// // Add the subject and the name assertion to the set to reveal
    /// reveal_set.insert(envelope.subject().digest().into_owned());
    /// reveal_set.insert(envelope.assertion_with_predicate("name").unwrap().digest().into_owned());
    ///
    /// // Create an envelope that only reveals name and hides age and SSN
    /// let selective = envelope.elide_revealing_set_with_action(&reveal_set, &ObscureAction::Elide);
    /// ```
    pub fn elide_revealing_set_with_action(
        &self,
        target: &HashSet<Digest>,
        action: &ObscureAction
    ) -> Self {
        self.elide_set_with_action(target, true, action)
    }

    /// Returns a version of this envelope with elements *not* in the `target` set elided.
    ///
    /// - Parameters:
    ///   - target: The target set of digests.
    ///
    /// - Returns: The elided envelope.
    pub fn elide_revealing_set(&self, target: &HashSet<Digest>) -> Self {
        self.elide_set(target, true)
    }

    /// Returns a version of this envelope with elements *not* in the `target` set elided.
    ///
    /// - Parameters:
    ///   - target: An array of `DigestProvider`s.
    ///   - action: Perform the specified action (elision, encryption or compression).
    ///
    /// - Returns: The elided envelope.
    pub fn elide_revealing_array_with_action(
        &self,
        target: &[&dyn DigestProvider],
        action: &ObscureAction
    ) -> Self {
        self.elide_array_with_action(target, true, action)
    }

    /// Returns a version of this envelope with elements *not* in the `target` set elided.
    ///
    /// - Parameters:
    ///   - target: An array of `DigestProvider`s.
    ///
    /// - Returns: The elided envelope.
    pub fn elide_revealing_array(&self, target: &[&dyn DigestProvider]) -> Self {
        self.elide_array(target, true)
    }

    /// Returns a version of this envelope with all elements *except* the target element elided.
    ///
    /// - Parameters:
    ///   - target: A `DigestProvider`.
    ///   - action: Perform the specified action (elision, encryption or compression).
    ///
    /// - Returns: The elided envelope.
    pub fn elide_revealing_target_with_action(
        &self,
        target: &dyn DigestProvider,
        action: &ObscureAction
    ) -> Self {
        self.elide_target_with_action(target, true, action)
    }

    /// Returns a version of this envelope with all elements *except* the target element elided.
    ///
    /// - Parameters:
    ///   - target: A `DigestProvider`.
    ///
    /// - Returns: The elided envelope.
    pub fn elide_revealing_target(&self, target: &dyn DigestProvider) -> Self {
        self.elide_target(target, true)
    }

    // Target Matches   isRevealing     elide
    // ----------------------------------------
    //     false           false        false
    //     false           true         true
    //     true            false        true
    //     true            true         false

    /// Returns an elided version of this envelope.
    ///
    /// - Parameters:
    ///   - target: The target set of digests.
    ///   - isRevealing: If `true`, the target set contains the digests of the elements to
    ///     leave revealed. If it is `false`, the target set contains the digests of the
    ///     elements to elide.
    ///   - action: Perform the specified action (elision, encryption or compression).
    ///
    /// - Returns: The elided envelope.
    pub fn elide_set_with_action(
        &self,
        target: &HashSet<Digest>,
        is_revealing: bool,
        action: &ObscureAction
    ) -> Self {
        let self_digest = self.digest().into_owned();
        if target.contains(&self_digest) != is_revealing {
            match action {
                ObscureAction::Elide => self.elide(),
                #[cfg(feature = "encrypt")]
                ObscureAction::Encrypt(key) => {
                    let message = key.encrypt_with_digest(
                        self.tagged_cbor().to_cbor_data(),
                        self_digest,
                        None::<Nonce>
                    );
                    Self::new_with_encrypted(message).unwrap()
                }
                #[cfg(feature = "compress")]
                ObscureAction::Compress => self.compress().unwrap(),
            }
        } else if let EnvelopeCase::Assertion(assertion) = self.case() {
            let predicate = assertion
                .predicate()
                .elide_set_with_action(target, is_revealing, action);
            let object = assertion.object().elide_set_with_action(target, is_revealing, action);
            let elided_assertion = Assertion::new(predicate, object);
            assert!(&elided_assertion == assertion);
            Self::new_with_assertion(elided_assertion)
        } else if let EnvelopeCase::Node { subject, assertions, .. } = self.case() {
            let elided_subject = subject.elide_set_with_action(target, is_revealing, action);
            assert!(elided_subject.digest() == subject.digest());
            let elided_assertions = assertions
                .iter()
                .map(|assertion| {
                    let elided_assertion = assertion.elide_set_with_action(
                        target,
                        is_revealing,
                        action
                    );
                    assert!(elided_assertion.digest() == assertion.digest());
                    elided_assertion
                })
                .collect();
            Self::new_with_unchecked_assertions(elided_subject, elided_assertions)
        } else if let EnvelopeCase::Wrapped { envelope, .. } = self.case() {
            let elided_envelope = envelope.elide_set_with_action(target, is_revealing, action);
            assert!(elided_envelope.digest() == envelope.digest());
            Self::new_wrapped(elided_envelope)
        } else {
            self.clone()
        }
    }

    /// Returns an elided version of this envelope.
    ///
    /// - Parameters:
    ///   - target: The target set of digests.
    ///   - isRevealing: If `true`, the target set contains the digests of the elements to
    ///     leave revealed. If it is `false`, the target set contains the digests of the
    ///     elements to elide.
    ///
    /// - Returns: The elided envelope.
    pub fn elide_set(&self, target: &HashSet<Digest>, is_revealing: bool) -> Self {
        self.elide_set_with_action(target, is_revealing, &ObscureAction::Elide)
    }

    /// Returns an elided version of this envelope.
    ///
    /// - Parameters:
    ///   - target: An array of `DigestProvider`s.
    ///   - isRevealing: If `true`, the target set contains the digests of the elements to
    ///     leave revealed. If it is `false`, the target set contains the digests of the
    ///     elements to elide.
    ///   - action: Perform the specified action (elision, encryption or compression).
    ///
    /// - Returns: The elided envelope.
    pub fn elide_array_with_action(
        &self,
        target: &[&dyn DigestProvider],
        is_revealing: bool,
        action: &ObscureAction
    ) -> Self {
        self.elide_set_with_action(
            &target
                .iter()
                .map(|provider| provider.digest().into_owned())
                .collect(),
            is_revealing,
            action
        )
    }

    /// Returns an elided version of this envelope.
    ///
    /// - Parameters:
    ///   - target: An array of `DigestProvider`s.
    ///   - isRevealing: If `true`, the target set contains the digests of the elements to
    ///     leave revealed. If it is `false`, the target set contains the digests of the
    ///     elements to elide.
    ///
    /// - Returns: The elided envelope.
    pub fn elide_array(&self, target: &[&dyn DigestProvider], is_revealing: bool) -> Self {
        self.elide_array_with_action(target, is_revealing, &ObscureAction::Elide)
    }

    /// Returns an elided version of this envelope.
    ///
    /// - Parameters:
    ///   - target: A `DigestProvider`.
    ///   - isRevealing: If `true`, the target is the element to leave revealed, eliding
    ///     all others. If it is `false`, the target is the element to elide, leaving all
    ///     others revealed.
    ///   - action: Perform the specified action (elision, encryption or compression).
    ///
    /// - Returns: The elided envelope.
    pub fn elide_target_with_action(
        &self,
        target: &dyn DigestProvider,
        is_revealing: bool,
        action: &ObscureAction
    ) -> Self {
        self.elide_array_with_action(&[target], is_revealing, action)
    }

    /// Returns an elided version of this envelope.
    ///
    /// - Parameters:
    ///   - target: A `DigestProvider`.
    ///   - isRevealing: If `true`, the target is the element to leave revealed, eliding
    ///     all others. If it is `false`, the target is the element to elide, leaving all
    ///     others revealed.
    ///
    /// - Returns: The elided envelope.
    pub fn elide_target(&self, target: &dyn DigestProvider, is_revealing: bool) -> Self {
        self.elide_target_with_action(target, is_revealing, &ObscureAction::Elide)
    }

    /// Returns the unelided variant of this envelope by revealing the original content.
    ///
    /// This function allows restoring an elided envelope to its original form, but only
    /// if the provided envelope's digest matches the elided envelope's digest. This ensures
    /// the integrity of the revealed content.
    ///
    /// Returns the same envelope if it is already unelided.
    ///
    /// # Errors
    ///
    /// Returns `EnvelopeError::InvalidDigest` if the provided envelope's digest doesn't match
    /// the current envelope's digest.
    ///
    /// # Examples
    ///
    /// ```
    /// # use bc_envelope::prelude::*;
    /// let original = Envelope::new("Hello.");
    /// let elided = original.elide();
    ///
    /// // Later, we can unelide the envelope if we have the original
    /// let revealed = elided.unelide(&original).unwrap();
    /// assert_eq!(revealed.format(), "\"Hello.\"");
    ///
    /// // Attempting to unelide with a different envelope will fail
    /// let different = Envelope::new("Different");
    /// assert!(elided.unelide(&different).is_err());
    /// ```
    pub fn unelide(&self, envelope: impl Into<Envelope>) -> Result<Self> {
        let envelope = envelope.into();
        if self.digest() == envelope.digest() {
            Ok(envelope)
        } else {
            bail!(Error::InvalidDigest)
        }
    }
}