privacy: make OpaquePointer.digest optional; add runtime validate() invariants for low-entropy class; update tests

Author: flyingrobots

Cargo.lock

@@ -9,4 +9,4 @@ serde_json = { workspace = true }
 blake3 = { workspace = true }
 hex = { workspace = true }
 anyhow = { workspace = true }
-
+thiserror = "1"

crates/gatos-privacy/Cargo.toml

@@ -17,7 +17,8 @@ use serde_json::Value;
 pub struct OpaquePointer {
     pub kind: Kind,
     pub algo: Algo,
-    pub digest: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub digest: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub ciphertext_digest: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -39,3 +40,44 @@ pub enum Kind {
 pub enum Algo {
     Blake3,
 }
+
+impl OpaquePointer {
+    /// Validate invariants beyond serde schema mapping.
+    pub fn validate(&self) -> Result<(), PointerError> {
+        let has_plain = self.digest.as_ref().map(|s| !s.is_empty()).unwrap_or(false);
+        let has_cipher = self
+            .ciphertext_digest
+            .as_ref()
+            .map(|s| !s.is_empty())
+            .unwrap_or(false);
+        if !(has_plain || has_cipher) {
+            return Err(PointerError::MissingDigest);
+        }
+        let low_entropy = self
+            .extensions
+            .as_ref()
+            .and_then(|v| v.get("class"))
+            .and_then(|c| c.as_str())
+            .map(|s| s == "low-entropy")
+            .unwrap_or(false);
+        if low_entropy {
+            if !has_cipher {
+                return Err(PointerError::LowEntropyNeedsCiphertextDigest);
+            }
+            if has_plain {
+                return Err(PointerError::LowEntropyForbidsPlainDigest);
+            }
+        }
+        Ok(())
+    }
+}
+
+#[derive(Debug, thiserror::Error, PartialEq, Eq)]
+pub enum PointerError {
+    #[error("at least one of digest or ciphertext_digest is required")]
+    MissingDigest,
+    #[error("low-entropy class requires ciphertext_digest")]
+    LowEntropyNeedsCiphertextDigest,
+    #[error("low-entropy class forbids plaintext digest")]
+    LowEntropyForbidsPlainDigest,
+}

crates/gatos-privacy/src/lib.rs

@@ -17,8 +17,7 @@ fn ciphertext_only_pointer_should_deserialize() {
 fn both_digests_allowed_when_not_low_entropy() {
     let json = read_example("privacy/opaque_pointer_min.json");
     let ptr: OpaquePointer = serde_json::from_str(&json).unwrap();
-    let has_digest = !ptr.digest.is_empty();
+    let has_digest = ptr.digest.as_ref().map(|s| !s.is_empty()).unwrap_or(false);
     assert!(has_digest);
     assert!(ptr.ciphertext_digest.is_some());
 }
-