feat: generate scoped searchkey

Author: haydenhoang

typesense/src/client/keys.rs

@@ -2,12 +2,15 @@
 //!
 //! An `Keys` instance is created via the `Client::keys()` method.
 
-use crate::{Client, Error};
-use std::sync::Arc;
-use typesense_codegen::{
-    apis::{configuration, keys_api},
-    models,
+use crate::{
+    models::{self, ScopedKeyParameters},
+    Client, Error,
 };
+use base64::{engine::general_purpose::STANDARD as Base64Engine, Engine};
+use hmac::{Hmac, Mac};
+use sha2::Sha256;
+use std::sync::Arc;
+use typesense_codegen::apis::{configuration, keys_api};
 
 /// Provides methods for managing a collection of Typesense API keys.
 ///
@@ -52,4 +55,25 @@ impl<'a> Keys<'a> {
             })
             .await
     }
+
+    /// Generate a scoped search API key that can have embedded search parameters in them.
+    ///
+    /// More info [here](https://typesense.org/docs/latest/api/api-keys.html#generate-scoped-search-key).
+    pub fn generate_scoped_search_key(
+        &self,
+        key: impl AsRef<str>,
+        params: &ScopedKeyParameters,
+    ) -> anyhow::Result<String> {
+        let params = serde_json::to_string(params)?;
+
+        let mut mac = Hmac::<Sha256>::new_from_slice(key.as_ref().as_bytes())?;
+        mac.update(params.as_bytes());
+        let result = mac.finalize();
+        let digest = Base64Engine.encode(result.into_bytes());
+
+        let key_prefix = &key.as_ref()[0..4];
+        let raw_scoped_key = format!("{}{}{}", digest, key_prefix, params);
+
+        Ok(Base64Engine.encode(raw_scoped_key.as_bytes()))
+    }
 }

typesense/src/keys.rs

@@ -1,6 +1,10 @@
 //! # Typesense generic models
-pub mod search_result;
+mod scoped_key_parameters;
+mod search_result;
+
+pub use scoped_key_parameters::*;
 pub use search_result::*;
+
 pub use typesense_codegen::models::{
     AnalyticsEventCreateResponse, AnalyticsEventCreateSchema, AnalyticsRuleDeleteResponse,
     AnalyticsRuleParameters, AnalyticsRuleParametersDestination, AnalyticsRuleParametersSource,
@@ -18,7 +22,7 @@ pub use typesense_codegen::models::{
     MultiSearchResultItem, MultiSearchSearchesParameter, NlSearchModelBase,
     NlSearchModelCreateSchema, NlSearchModelDeleteSchema, NlSearchModelSchema, PresetDeleteSchema,
     PresetSchema, PresetUpsertSchema, PresetUpsertSchemaValue, PresetsRetrieveSchema,
-    SchemaChangeStatus, ScopedKeyParameters, SearchGroupedHit, SearchHighlight, SearchOverride,
+    SchemaChangeStatus, SearchGroupedHit, SearchHighlight, SearchOverride,
     SearchOverrideDeleteResponse, SearchOverrideExclude, SearchOverrideInclude, SearchOverrideRule,
     SearchOverrideSchema, SearchOverridesResponse, SearchParameters, SearchResultConversation,
     SearchResultHitTextMatchInfo, SearchResultRequestParams, SearchResultRequestParamsVoiceQuery,
@@ -79,7 +83,6 @@ pub use typesense_codegen::models::{
     preset_upsert_schema_value,
     presets_retrieve_schema,
     schema_change_status,
-    scoped_key_parameters,
     search_grouped_hit,
     search_highlight,
     search_override,

typesense/src/models/mod.rs

@@ -0,0 +1,25 @@
+use crate::models::SearchParameters;
+use serde::Serialize;
+
+/// Defines the parameters for generating a scoped API key.
+///
+/// A scoped key is a temporary, client-side key that has a specific set of
+/// search restrictions and an optional expiration time embedded within it. It allows
+/// you to delegate search permissions securely without exposing your main API key.
+#[derive(Debug, Clone, Default, Serialize)]
+pub struct ScopedKeyParameters {
+    /// The search parameters to embed in the key. These parameters will be
+    /// enforced for all searches made with the generated key.
+    /// For example, you can use `filter_by` to restrict searches to a subset of documents.
+    #[serde(flatten, skip_serializing_if = "Option::is_none")]
+    pub search_params: Option<SearchParameters>,
+
+    /// The number of `multi_search` requests that can be performed using this key.
+    /// This is an optional parameter to further restrict the key's capabilities.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub limit_multi_searches: Option<i64>,
+
+    /// The Unix timestamp (in seconds) after which the generated key will expire.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub expires_at: Option<i64>,
+}

typesense/src/models/scoped_key_parameters.rs

@@ -1,5 +1,5 @@
 use super::get_client;
-use typesense::models::ApiKeySchema;
+use typesense::models::{ApiKeySchema, ScopedKeyParameters, SearchParameters};
 
 #[tokio::test]
 async fn test_keys_lifecycle() {
@@ -80,3 +80,42 @@ async fn test_keys_lifecycle() {
         "API key should not exist after deletion."
     );
 }
+
+#[test]
+fn test_generate_scoped_search_key_with_example_values() {
+    // The parent key with `documents:search` permissions.
+    let search_only_api_key = "RN23GFr1s6jQ9kgSNg2O7fYcAUXU7127";
+
+    // The parameters to be embedded in the new scoped key.
+    let params = ScopedKeyParameters {
+        search_params: Some(SearchParameters {
+            filter_by: Some("company_id:124".to_string()),
+            ..Default::default()
+        }),
+        expires_at: Some(1906054106),
+        ..Default::default()
+    };
+
+    // The known correct output from the Typesense documentation.
+    let expected_scoped_key = "OW9DYWZGS1Q1RGdSbmo0S1QrOWxhbk9PL2kxbTU1eXA3bCthdmE5eXJKRT1STjIzeyJmaWx0ZXJfYnkiOiJjb21wYW55X2lkOjEyNCIsImV4cGlyZXNfYXQiOjE5MDYwNTQxMDZ9";
+
+    let client = get_client();
+
+    let generated_key_result = client
+        .keys()
+        .generate_scoped_search_key(search_only_api_key, &params);
+
+    // First, ensure the function returned an Ok result.
+    assert!(
+        generated_key_result.is_ok(),
+        "Function returned an error: {:?}",
+        generated_key_result.err()
+    );
+
+    // Unwrap the result and compare it with the expected output.
+    let generated_key = generated_key_result.unwrap();
+    assert_eq!(
+        generated_key, expected_scoped_key,
+        "The generated key does not match the expected key."
+    );
+}