requisite 0.1.0

Data-handling requirements encoded in Rust types.
Documentation
//! Type-checked transitions from external input to trusted values.
//!
//! [`Tainted<T, Tr>`] carries a trust tag with a value. Input boundaries create
//! [`Untrusted`] values, and [`sanitize`] applies the application's cleaning
//! policy to produce [`Trusted`] values. Sinks express their requirement with a
//! parameter such as `Tainted<String, Trusted>`.
//!
//! [`widen`](Tainted::widen) converts a trusted value for use by an API with a
//! lower trust requirement. Trust tags are zero-sized [`PhantomData`] markers.

use core::marker::PhantomData;

/// A value received from an external input boundary.
#[derive(Debug, Clone, Copy, Default)]
pub struct Untrusted;

/// Cleaned: went through [`sanitize`].
#[derive(Debug, Clone, Copy, Default)]
pub struct Trusted;

/// A value `T` carrying a compile-time trust tag `Tr`.
#[must_use = "the trust-tagged value must be consumed or passed to another operation"]
#[derive(Debug, Clone, Copy)]
pub struct Tainted<T, Tr> {
    val: T,
    _tr: PhantomData<Tr>,
}

impl<T> Tainted<T, Untrusted> {
    /// Mark a value received at an input boundary as untrusted.
    pub fn from_input(val: T) -> Self {
        Tainted {
            val,
            _tr: PhantomData,
        }
    }
}

impl<T> Tainted<T, Trusted> {
    /// Unwrap a trusted value.
    pub fn into_inner(self) -> T {
        self.val
    }

    /// Adapt a value to a lower trust requirement.
    pub fn widen(self) -> Tainted<T, Untrusted> {
        Tainted {
            val: self.val,
            _tr: PhantomData,
        }
    }
}

impl<T, Tr> AsRef<T> for Tainted<T, Tr> {
    /// Borrow the wrapped value without changing its trust tag.
    fn as_ref(&self) -> &T {
        &self.val
    }
}

/// Apply a cleaning policy and mark the result as [`Trusted`].
///
/// The closure implements the destination's cleaning policy. Centralizing that
/// policy makes trust transitions explicit at call sites and reviewable at the
/// boundary.
///
/// The resulting tag records that the value passed through this transition.
/// The closure remains responsible for implementing the destination's policy.
///
/// ```
/// # use requisite::prelude::*;
/// # use requisite::trust::sanitize;
/// let raw = Tainted::<_, Untrusted>::from_input(" customer-42 ".to_string());
/// let trusted = sanitize(raw, |s| s.trim().to_ascii_lowercase());
/// assert_eq!(trusted.into_inner(), "customer-42");
/// ```
#[must_use = "sanitization returns a new trusted value"]
pub fn sanitize<T, U, F>(t: Tainted<T, Untrusted>, transform: F) -> Tainted<U, Trusted>
where
    F: FnOnce(T) -> U,
{
    Tainted {
        val: transform(t.val),
        _tr: PhantomData,
    }
}

/// Apply a fallible cleaning policy and mark successful output as [`Trusted`].
///
/// Errors are returned directly. A successful transformation produces the
/// trusted value.
///
/// ```
/// # use requisite::prelude::*;
/// # use requisite::trust::try_sanitize;
/// let raw = Tainted::<_, Untrusted>::from_input("42".to_string());
/// let trusted = try_sanitize(raw, |s| s.parse::<u64>())?;
/// assert_eq!(trusted.into_inner(), 42);
/// # Ok::<(), std::num::ParseIntError>(())
/// ```
pub fn try_sanitize<T, U, E, F>(
    t: Tainted<T, Untrusted>,
    transform: F,
) -> Result<Tainted<U, Trusted>, E>
where
    F: FnOnce(T) -> Result<U, E>,
{
    transform(t.val).map(|val| Tainted {
        val,
        _tr: PhantomData,
    })
}