feat: return hash_ref from create_key_package_for_event (marmot-protocol#178)

Return the KeyPackage hash_ref as a third tuple element from
create_key_package_for_event and create_key_package_for_event_with_options.
This enables callers to track key packages for lifecycle management
(publish → consume → cleanup) without needing to re-parse the package.

Remove compute_key_package_hash_ref() which is now redundant — the
hash_ref is computed atomically during key package creation.

Author: mubarakcoded

README.md

@@ -136,7 +136,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let relay_url = RelayUrl::parse("wss://relay.example.com")?;
 
     // Bob creates a key package
-    let (bob_key_package, tags) = bob_mdk
+    let (bob_key_package, tags, _hash_ref) = bob_mdk
         .create_key_package_for_event(&bob_keys.public_key(), [relay_url.clone()])?;
 
     let bob_key_package_event = EventBuilder::new(Kind::MlsKeyPackage, bob_key_package)

crates/mdk-core/CHANGELOG.md

@@ -25,6 +25,7 @@
 
 ### Breaking changes
 
+- **`create_key_package_for_event` Return Type Change**: The return type changed from `(String, Vec<Tag>)` to `(String, Vec<Tag>, Vec<u8>)`. The third element is the serialized hash_ref of the key package, computed atomically during creation. This enables callers to track key packages for lifecycle management (publish → consume → cleanup) without needing to re-parse the package. Callers that don't need the hash_ref can destructure with `_`. ([#178](https://github.com/marmot-protocol/mdk/pull/178))
 - **`create_key_package_for_event` Return Type Change**: The return type changed from `(String, [Tag; 7])` to `(String, Vec<Tag>)`. Most code patterns (iteration, indexing) continue to work unchanged. This change was necessary because the protected tag is now optional. ([#173](https://github.com/marmot-protocol/mdk/pull/173), related: [#168](https://github.com/marmot-protocol/mdk/issues/168))
 - **`create_key_package_for_event` No Longer Adds Protected Tag**: The `create_key_package_for_event()` function no longer adds the NIP-70 protected tag (`["-"]`) by default. This is a behavioral change - existing code that relied on the protected tag being present will now produce key packages without it. Key packages can now be republished by third parties to any relay. This improves relay compatibility since many popular relays (Damus, Primal, nos.lol) reject protected events outright. For users who need the protected tag, use the new `create_key_package_for_event_with_options()` function with `protected: true`. ([#173](https://github.com/marmot-protocol/mdk/pull/173), related: [#168](https://github.com/marmot-protocol/mdk/issues/168))
 - **OpenMLS 0.8.0 Upgrade**: Upgraded from a git-pinned openmls 0.7.1 to the crates.io openmls 0.8.0 release. This resolves security advisory [GHSA-8x3w-qj7j-gqhf](https://github.com/openmls/openmls/security/advisories/GHSA-8x3w-qj7j-gqhf) (improper tag validation) and moves GREASE support from a git pin to an official release. Companion crates updated: `openmls_traits` 0.5, `openmls_basic_credential` 0.5, `openmls_rust_crypto` 0.5. ([#174](https://github.com/marmot-protocol/mdk/pull/174))
@@ -41,7 +42,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))
+- **KeyPackage deletion by hash_ref bytes**: Added `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 obtained at creation time (via `create_key_package_for_event`) and used for deletion later. ([#178](https://github.com/marmot-protocol/mdk/pull/178))
 - **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))
@@ -60,6 +61,8 @@
 
 ### Removed
 
+- **`compute_key_package_hash_ref` removed**: This method is no longer needed now that `create_key_package_for_event` returns the hash_ref directly as its third tuple element. Callers should use the hash_ref from `create_key_package_for_event` instead. ([#178](https://github.com/marmot-protocol/mdk/pull/178))
+
 ### Deprecated
 
 - **Unified Storage Architecture**: `MdkProvider` now uses the storage provider directly as the OpenMLS `StorageProvider`, instead of accessing it via `openmls_storage()`. This enables atomic transactions across MLS and MDK state for proper commit race resolution per MIP-03. Storage implementations must now directly implement `StorageProvider<1>`. ([#148](https://github.com/marmot-protocol/mdk/pull/148))

crates/mdk-core/examples/group_inspection.rs

@@ -63,7 +63,7 @@ async fn main() -> Result<(), Error> {
     let relay_url = RelayUrl::parse("wss://relay.example.com").unwrap();
 
     // Create key packages for members (not creator)
-    let (member1_kp_encoded, member1_tags) =
+    let (member1_kp_encoded, member1_tags, _) =
         mdk.create_key_package_for_event(&member1_keys.public_key(), [relay_url.clone()])?;
 
     let member1_event =
@@ -73,7 +73,7 @@ async fn main() -> Result<(), Error> {
             .sign(&member1_keys)
             .await?;
 
-    let (member2_kp_encoded, member2_tags) =
+    let (member2_kp_encoded, member2_tags, _) =
         mdk.create_key_package_for_event(&member2_keys.public_key(), [relay_url.clone()])?;
 
     let member2_event =

crates/mdk-core/examples/key_package_inspection.rs

@@ -42,7 +42,7 @@ async fn main() -> Result<(), Error> {
     println!("=== Creating Key Package ===\n");
 
     // Create key package with protected=true to demonstrate NIP-70 tag
-    let (key_package_encoded, tags) = mdk.create_key_package_for_event_with_options(
+    let (key_package_encoded, tags, _hash_ref) = mdk.create_key_package_for_event_with_options(
         &keys.public_key(),
         [relay_url.clone()],
         true,

crates/mdk-core/examples/mls_memory.rs

@@ -33,7 +33,7 @@ async fn main() -> Result<(), Error> {
 
     // Create key package for Bob
     // This would be published to the Nostr network for other users to find
-    let (bob_key_package_encoded, tags) =
+    let (bob_key_package_encoded, tags, _) =
         bob_mdk.create_key_package_for_event(&bob_keys.public_key(), [relay_url.clone()])?;
 
     let bob_key_package_event = EventBuilder::new(Kind::MlsKeyPackage, bob_key_package_encoded)
@@ -242,7 +242,7 @@ async fn main() -> Result<(), Error> {
     tracing::info!("Charlie identity generated");
 
     // Create key package for Charlie
-    let (charlie_key_package_encoded, charlie_tags) = charlie_mdk
+    let (charlie_key_package_encoded, charlie_tags, _) = charlie_mdk
         .create_key_package_for_event(&charlie_keys.public_key(), [relay_url.clone()])?;
 
     let charlie_key_package_event =

crates/mdk-core/examples/mls_sqlite.rs

@@ -40,7 +40,7 @@ async fn main() -> Result<(), Error> {
 
     // Create key package for Bob
     // This would be published to the Nostr network for other users to find
-    let (bob_key_package_encoded, tags) =
+    let (bob_key_package_encoded, tags, _) =
         bob_mdk.create_key_package_for_event(&bob_keys.public_key(), [relay_url.clone()])?;
 
     let bob_key_package_event = EventBuilder::new(Kind::MlsKeyPackage, bob_key_package_encoded)
@@ -254,7 +254,7 @@ async fn main() -> Result<(), Error> {
     tracing::info!("Charlie identity generated");
 
     // Create key package for Charlie
-    let (charlie_key_package_encoded, charlie_tags) = charlie_mdk
+    let (charlie_key_package_encoded, charlie_tags, _) = charlie_mdk
         .create_key_package_for_event(&charlie_keys.public_key(), [relay_url.clone()])?;
 
     let charlie_key_package_event =