Add key package hash_ref computation and deletion by serialized bytes (marmot-protocol#176)

* Add compute_key_package_hash_ref and delete_key_package_from_storage_by_hash_ref methods

* Update CHANGELOG with PR marmot-protocol#176 reference for key package hash_ref methods

Author: mubarakcoded

crates/mdk-core/CHANGELOG.md

@@ -41,6 +41,7 @@
 
 ### Added
 
+- **KeyPackage hash_ref computation and deletion by bytes**: Added `compute_key_package_hash_ref()` to serialize a key package's hash_ref for external caching, and `delete_key_package_from_storage_by_hash_ref()` to delete a key package using previously serialized hash_ref bytes. This enables delayed key material cleanup workflows where the hash_ref is cached at welcome-processing time and used for deletion later. ([#176](https://github.com/marmot-protocol/mdk/pull/176))
 - **Custom Message Sort Order**: `get_messages()` now supports custom sort orders via the `Pagination::sort_order` field. Added `get_last_message(group_id, sort_order)` method to retrieve the most recent message under a given sort order, enabling clients using `ProcessedAtFirst` ordering to get a consistent "last message" value. ([#171](https://github.com/marmot-protocol/mdk/pull/171))
 - **`create_key_package_for_event_with_options`**: New function that allows specifying whether to include the NIP-70 protected tag. Use this if you need to publish to relays that accept protected events. ([#173](https://github.com/marmot-protocol/mdk/pull/173), related: [#168](https://github.com/marmot-protocol/mdk/issues/168))
 - **MIP-04 Epoch Fallback for Media Decryption**: `decrypt_from_download` now resolves the correct decryption key via an O(1) epoch hint lookup instead of only using the current epoch's exporter secret. Added `NoExporterSecretForEpoch` variant to `EncryptedMediaError` for programmatic error matching. ([#167](https://github.com/marmot-protocol/mdk/pull/167))

crates/mdk-core/src/key_packages.rs

@@ -1,7 +1,9 @@
 //! Nostr MLS Key Packages
 
 use mdk_storage_traits::MdkStorageProvider;
+use mdk_storage_traits::mls_codec::JsonCodec;
 use nostr::{Event, Kind, PublicKey, RelayUrl, Tag, TagKind};
+use openmls::ciphersuite::hash_ref::HashReference;
 use openmls::key_packages::KeyPackage;
 use openmls::prelude::*;
 use openmls_basic_credential::SignatureKeyPair;
@@ -508,6 +510,36 @@ where
         Ok(())
     }
 
+    /// Computes and serializes the hash_ref for a key package.
+    ///
+    /// Returns the hash_ref as serialized bytes that can be stored externally
+    /// and later used with [`delete_key_package_from_storage_by_hash_ref`](Self::delete_key_package_from_storage_by_hash_ref)
+    /// to delete the key package from storage.
+    pub fn compute_key_package_hash_ref(&self, key_package: &KeyPackage) -> Result<Vec<u8>, Error> {
+        let hash_ref = key_package.hash_ref(self.provider.crypto())?;
+        JsonCodec::serialize(&hash_ref)
+            .map_err(|e| Error::Provider(format!("Failed to serialize hash_ref: {}", e)))
+    }
+
+    /// Deletes a key package from storage using previously serialized hash_ref bytes.
+    ///
+    /// The `hash_ref_bytes` should be bytes previously returned by
+    /// [`compute_key_package_hash_ref`](Self::compute_key_package_hash_ref).
+    pub fn delete_key_package_from_storage_by_hash_ref(
+        &self,
+        hash_ref_bytes: &[u8],
+    ) -> Result<(), Error> {
+        let hash_ref: HashReference = JsonCodec::deserialize(hash_ref_bytes)
+            .map_err(|e| Error::Provider(format!("Failed to deserialize hash_ref: {}", e)))?;
+
+        self.provider
+            .storage()
+            .delete_key_package(&hash_ref)
+            .map_err(|e| Error::Provider(e.to_string()))?;
+
+        Ok(())
+    }
+
     /// Generates a credential with a key for MLS (Messaging Layer Security) operations.
     ///
     /// This function creates a new credential and associated signature key pair for use in MLS.
@@ -943,6 +975,46 @@ mod tests {
             .expect("Failed to delete key package");
     }
 
+    #[test]
+    fn test_key_package_deletion_by_hash_ref_roundtrip() {
+        let mdk = create_test_mdk();
+        let test_pubkey =
+            PublicKey::from_hex("884704bd421671e01c13f854d2ce23ce2a5bfe9562f4f297ad2bc921ba30c3a6")
+                .unwrap();
+
+        let relays = vec![RelayUrl::parse("wss://relay.example.com").unwrap()];
+
+        // Create and parse key package
+        let (key_package_str, _) = mdk
+            .create_key_package_for_event(&test_pubkey, relays.clone())
+            .expect("Failed to create key package");
+
+        let deletion_mdk = create_test_mdk();
+        let key_package = deletion_mdk
+            .parse_serialized_key_package(&key_package_str, ContentEncoding::Base64)
+            .expect("Failed to parse key package");
+
+        // Compute hash_ref bytes (simulates what whitenoise-rs caches in DB)
+        let hash_ref_bytes = deletion_mdk
+            .compute_key_package_hash_ref(&key_package)
+            .expect("Failed to compute hash_ref");
+
+        assert!(
+            !hash_ref_bytes.is_empty(),
+            "hash_ref bytes should not be empty"
+        );
+
+        // Delete using the serialized hash_ref bytes (simulates delayed cleanup)
+        deletion_mdk
+            .delete_key_package_from_storage_by_hash_ref(&hash_ref_bytes)
+            .expect("Failed to delete key package by hash_ref");
+
+        // Deleting again should also succeed (idempotent, no-op)
+        deletion_mdk
+            .delete_key_package_from_storage_by_hash_ref(&hash_ref_bytes)
+            .expect("Second deletion should succeed (idempotent)");
+    }
+
     #[test]
     fn test_invalid_key_package_parsing() {
         let mdk = create_test_mdk();