feat: Introduce the #[classified] macro (#48)

Co-authored-by: Martin Taillefer <mataille@microsoft.com>
Co-authored-by: Ralf Biedert <rb@xr.io>

Author: 3 people

Cargo.lock

@@ -26,6 +26,7 @@ fundle_macros = { path = "crates/fundle_macros", default-features = false, versi
 fundle_macros_impl = { path = "crates/fundle_macros_impl", default-features = false, version = "0.2.0" }
 
 # external dependencies
+derive_more = { version = "2.0.1", default-features = false  }
 insta = { version = "1.42.0", default-features = false  }
 mutants = { version = "0.0.3", default-features = false  }
 once_cell = { version = "1.21.3", default-features = false  }

Cargo.toml

@@ -22,6 +22,7 @@ serde = { workspace = true, optional = true, default-features = false, features
 xxhash-rust = { workspace = true, optional = true, features = ["xxh3"] }
 
 [dev-dependencies]
+derive_more = { workspace = true, features = ["constructor", "from"] }
 once_cell = { workspace = true, features = ["std"] }
 mutants.workspace = true
 serde = { workspace = true, features = ["derive", "std"] }

crates/data_privacy/Cargo.toml

@@ -130,7 +130,7 @@ fn try_out() {
     // doesn't compile since `Sensitive` doesn't implement `Display`
     // println!("Name: {}", person.name);
 
-    // outputs: Name: <common/sensitive:REDACTED>"
+    // outputs: Name: <CLASSIFIED:common/sensitive>"
     println!("Name: {:?}", person.name);
 
     // extract the data from the `Sensitive` type and outputs: Name: John Doe
@@ -170,7 +170,7 @@ fn try_out() {
     let mut output_buffer = String::new();
 
     // Redact the sensitive data in the person's name using the redaction engine.
-    engine.display_redacted(&person.name, |s| output_buffer.write_str(s).unwrap());
+    engine.redacted_display(&person.name, |s| output_buffer.write_str(s).unwrap());
 
     // check that the data in the output buffer has indeed been redacted as expected.
     assert_eq!(output_buffer, "********");

crates/data_privacy/README.md

@@ -1,15 +1,28 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+use crate::example_taxonomy::ExampleTaxonomy;
+use data_privacy_macros::classified;
+use derive_more::{Constructor, From};
 use serde::{Deserialize, Serialize};
 
-use crate::example_taxonomy::{OrganizationallyIdentifiableInformation, PersonallyIdentifiableInformation};
+#[classified(ExampleTaxonomy::PersonallyIdentifiableInformation)]
+#[derive(Clone, Serialize, Deserialize, Constructor, From)]
+pub struct UserName(String);
+
+#[classified(ExampleTaxonomy::PersonallyIdentifiableInformation)]
+#[derive(Clone, Serialize, Deserialize, Constructor, From)]
+pub struct UserAddress(String);
+
+#[classified(ExampleTaxonomy::OrganizationallyIdentifiableInformation)]
+#[derive(Clone, Serialize, Deserialize, Constructor, From)]
+pub struct EmployeeID(String);
 
 /// Holds info about a single corporate employee.
 #[derive(Serialize, Deserialize, Clone)]
 pub struct Employee {
-    pub name: PersonallyIdentifiableInformation<String>,
-    pub address: PersonallyIdentifiableInformation<String>,
-    pub id: OrganizationallyIdentifiableInformation<String>,
+    pub name: UserName,
+    pub address: UserAddress,
+    pub id: EmployeeID,
     pub age: u32,
 }

crates/data_privacy/examples/employees/employee.rs

@@ -11,14 +11,14 @@ pub fn set_redaction_engine_for_logging(engine: RedactionEngine) {
     REDACTION_ENGINE.set(engine).unwrap();
 }
 
-pub fn classified_display<C, T>(value: &C) -> String
+pub fn classified_display<C>(value: &C) -> String
 where
-    C: Classified<T>,
-    T: Display,
+    C: Classified,
+    C::Payload: Display,
 {
     let engine = REDACTION_ENGINE.get().unwrap();
     let mut output = String::new();
-    engine.display_redacted(value, |s| output.push_str(s));
+    engine.redacted_display(value, |s| output.push_str(s));
     output
 }
 

crates/data_privacy/examples/employees/logging.rs

@@ -38,9 +38,10 @@ mod employee;
 mod example_taxonomy;
 mod logging;
 
+use crate::employee::{EmployeeID, UserAddress, UserName};
 use data_privacy::{RedactionEngineBuilder, SimpleRedactor, SimpleRedactorMode};
 use employee::Employee;
-use example_taxonomy::{ExampleTaxonomy, OrganizationallyIdentifiableInformation, PersonallyIdentifiableInformation};
+use example_taxonomy::ExampleTaxonomy;
 use logging::{log, set_redaction_engine_for_logging};
 use std::fs::{File, OpenOptions};
 use std::io::BufReader;
@@ -83,9 +84,9 @@ fn app_loop() {
 
     // pretend some UI collected some data, and we then create an Employee struct to hold this data
     let employee = Employee {
-        name: PersonallyIdentifiableInformation::new("John Doe".to_string()),
-        address: PersonallyIdentifiableInformation::new("123 Elm Street".to_string()),
-        id: OrganizationallyIdentifiableInformation::new("12345-52".to_string()),
+        name: UserName::new("John Doe".to_string()),
+        address: UserAddress::new("123 Elm Street".to_string()),
+        id: EmployeeID::new("12345-52".to_string()),
         age: 33,
     };
 

crates/data_privacy/examples/employees/main.rs

@@ -10,6 +10,8 @@ use crate::DataClass;
 /// Although instances are encapsulated, it's possible to extract the instances when
 /// classification is no longer needed.
 ///
+/// You rarely implement this trait by hand, instead use the [`classified`](data_privacy_macros::classified) macro.
+///
 /// # Example
 ///
 /// ```rust
@@ -26,43 +28,45 @@ use crate::DataClass;
 ///     }
 /// }
 ///
-/// struct ClassifiedPerson {
-///     person: Person
-/// }
+/// struct ClassifiedPerson(Person);
 ///
 /// impl ClassifiedPerson {
 ///    fn new(person: Person) -> Self {
-///        Self { person }
+///        Self(person)
 ///    }
 /// }
 ///
-/// impl Classified<Person> for ClassifiedPerson {
+/// impl Classified for ClassifiedPerson {
+///     type Payload = Person;
+///
 ///     fn declassify(self) -> Person {
-///         self.person
+///         self.0
 ///     }
 ///
-/// fn as_declassified(&self) -> &Person {
-///         &self.person
+///     fn as_declassified(&self) -> &Person {
+///         &self.0
 ///     }
 ///
-/// fn as_declassified_mut(&mut self) -> &mut Person {
-///         &mut self.person
+///     fn as_declassified_mut(&mut self) -> &mut Person {
+///         &mut self.0
 ///     }
 ///
 ///     fn data_class(&self) -> DataClass {
 ///         DataClass::new("example_taxonomy", "classified_person")
 ///     }
 /// }
 ///  ```
-pub trait Classified<T> {
+pub trait Classified {
+    type Payload;
+
     /// Exfiltrates the payload, allowing it to be used outside the classified context.
     ///
     /// Exfiltration should be done with caution, as it may expose sensitive information.
     ///
     /// # Returns
     /// The original payload.
     #[must_use]
-    fn declassify(self) -> T;
+    fn declassify(self) -> Self::Payload;
 
     /// Provides a reference to the declassified payload, allowing read access without ownership transfer.
     ///
@@ -71,7 +75,7 @@ pub trait Classified<T> {
     /// # Returns
     /// A reference to the original payload.
     #[must_use]
-    fn as_declassified(&self) -> &T;
+    fn as_declassified(&self) -> &Self::Payload;
 
     /// Provides a mutable reference to the declassified payload, allowing write access without ownership transfer.
     ///
@@ -80,15 +84,15 @@ pub trait Classified<T> {
     /// # Returns
     /// A mutable reference to the original payload.
     #[must_use]
-    fn as_declassified_mut(&mut self) -> &mut T;
+    fn as_declassified_mut(&mut self) -> &mut Self::Payload;
 
     /// Visits the payload with the provided operation.
-    fn visit(&self, operation: impl FnOnce(&T)) {
+    fn visit(&self, operation: impl FnOnce(&Self::Payload)) {
         operation(self.as_declassified());
     }
 
     /// Visits the payload with the provided operation.
-    fn visit_mut(&mut self, operation: impl FnOnce(&mut T)) {
+    fn visit_mut(&mut self, operation: impl FnOnce(&mut Self::Payload)) {
         operation(self.as_declassified_mut());
     }
 
@@ -106,7 +110,9 @@ mod tests {
         data: u32,
     }
 
-    impl Classified<u32> for ClassifiedExample {
+    impl Classified for ClassifiedExample {
+        type Payload = u32;
+
         fn declassify(self) -> u32 {
             self.data
         }

crates/data_privacy/src/classified.rs

@@ -30,11 +30,17 @@ where
     T: Debug,
 {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
-        f.write_fmt(format_args!("<{}/{}:REDACTED>", self.data_class.taxonomy(), self.data_class.name()))
+        f.write_fmt(format_args!(
+            "<CLASSIFIED:{}/{}>",
+            self.data_class.taxonomy(),
+            self.data_class.name()
+        ))
     }
 }
 
-impl<T> Classified<T> for ClassifiedWrapper<T> {
+impl<T> Classified for ClassifiedWrapper<T> {
+    type Payload = T;
+
     fn declassify(self) -> T {
         self.value
     }
@@ -114,7 +120,7 @@ mod tests {
         let classified = ClassifiedWrapper::new(42, CommonTaxonomy::Sensitive.data_class());
         assert_eq!(classified.as_declassified(), &42);
         assert_eq!(classified.data_class(), CommonTaxonomy::Sensitive.data_class());
-        assert_eq!(format!("{classified:?}"), "<common/sensitive:REDACTED>");
+        assert_eq!(format!("{classified:?}"), "<CLASSIFIED:common/sensitive>");
     }
 
     #[test]
@@ -183,6 +189,6 @@ mod tests {
         assert_eq!(classified.as_declassified(), &"hello".to_string());
         assert_eq!(classified.data_class(), CommonTaxonomy::UnknownSensitivity.data_class());
         // Debug should redact and include the correct class path
-        assert_eq!(format!("{classified:?}"), "<common/unknown_sensitivity:REDACTED>");
+        assert_eq!(format!("{classified:?}"), "<CLASSIFIED:common/unknown_sensitivity>");
     }
 }

crates/data_privacy/src/classified_wrapper.rs

@@ -52,11 +52,11 @@ mod tests {
 
     #[test]
     fn test_debug_trait() {
-        assert_eq!(format!("{:?}", Sensitive::new(2)), "<common/sensitive:REDACTED>");
-        assert_eq!(format!("{:?}", Insensitive::new("Hello")), "<common/insensitive:REDACTED>");
+        assert_eq!(format!("{:?}", Sensitive::new(2)), "<CLASSIFIED:common/sensitive>");
+        assert_eq!(format!("{:?}", Insensitive::new("Hello")), "<CLASSIFIED:common/insensitive>");
         assert_eq!(
             format!("{:?}", UnknownSensitivity::new(31.4)),
-            "<common/unknown_sensitivity:REDACTED>"
+            "<CLASSIFIED:common/unknown_sensitivity>"
         );
     }