create-sia-app 0.1.1

package/template/rust/sia-sdk-rs/indexd/src/builder.rs

@@ -0,0 +1,354 @@
+use std::sync::Arc;
+use std::time::Duration;
+
+use chrono::{DateTime, Utc};
+use log::debug;
+use reqwest::IntoUrl;
+use sia::seed::{self, Seed};
+use sia::signing::PrivateKey;
+use sia::types::Hash256;
+use thiserror::Error;
+use url::Url;
+
+use crate::app_client::{self, AppClient, Client, RegisterAppRequest, RegisterAppResponse};
+use crate::object_encryption::derive;
+use crate::SDK;
+
+#[cfg(not(target_arch = "wasm32"))]
+use crate::quic;
+
+/// Configuration for concurrency limits (WASM only).
+#[cfg(target_arch = "wasm32")]
+#[derive(Debug, Clone, Copy)]
+pub struct ConcurrencyConfig {
+    pub max_price_fetches: usize,
+    pub max_downloads: usize,
+    pub max_uploads: usize,
+}
+
+#[cfg(target_arch = "wasm32")]
+impl Default for ConcurrencyConfig {
+    fn default() -> Self {
+        Self {
+            max_price_fetches: 10,
+            max_downloads: 20,
+            max_uploads: 16,
+        }
+    }
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+use tokio::time::sleep;
+
+#[cfg(target_arch = "wasm32")]
+use crate::wasm_time::sleep;
+
+
+/// The initial state of the SDK builder, before connecting to the indexd service.
+pub struct DisconnectedState;
+
+/// The state of the SDK builder after requesting approval for the application.
+pub struct RequestingApprovalState {
+    app_id: Hash256,
+    response_url: Url,
+    register_url: Url,
+    status_url: Url,
+    expiration: DateTime<Utc>,
+}
+
+/// The state of the SDK builder after the application has been approved.
+pub struct ApprovedState {
+    app_id: Hash256,
+    register_url: Url,
+    user_secret: Hash256,
+}
+
+/// A builder for creating an SDK instance.
+pub struct Builder<S> {
+    state: S,
+    client: Arc<dyn AppClient>,
+    // FIXME this can be removed if neccesary
+    // this is needed to allow the webapp user to set their own
+    // concurrency settings. Now being used to determine reasonable settings.
+    #[cfg(target_arch = "wasm32")]
+    concurrency: ConcurrencyConfig,
+}
+
+/// Errors that can occur during the SDK building process.
+#[derive(Error, Debug)]
+pub enum BuilderError {
+    #[error("url error: {0}")]
+    Url(#[from] url::ParseError),
+
+    #[error("client error: {0}")]
+    Client(#[from] app_client::Error),
+
+    #[cfg(not(target_arch = "wasm32"))]
+    #[error("quic error: {0}")]
+    QUIC(#[from] quic::ConnectError),
+
+    #[error("mnemonic error: {0}")]
+    Mnemonic(#[from] seed::SeedError),
+
+    #[error("request expired")]
+    RequestExpired,
+}
+
+impl Builder<DisconnectedState> {
+    /// Creates a new SDK builder with the provided indexer URL.
+    ///
+    /// After creating the builder, call [Builder::connected] to attempt
+    /// to connect using an existing app key, or [Builder::request_connection]
+    /// to request a new connection.
+    pub fn new<U: IntoUrl>(indexer_url: U) -> Result<Self, BuilderError> {
+        debug!(
+            "Creating SDK builder for indexer at {}",
+            indexer_url.as_str()
+        );
+        let client = Client::new(indexer_url)?;
+        Ok(Self {
+            state: DisconnectedState,
+            client: Arc::new(client),
+            #[cfg(target_arch = "wasm32")]
+            concurrency: ConcurrencyConfig::default(),
+        })
+    }
+
+    /// Sets the concurrency configuration (WASM only).
+    #[cfg(target_arch = "wasm32")]
+    pub fn with_concurrency(mut self, config: ConcurrencyConfig) -> Self {
+        self.concurrency = config;
+        self
+    }
+
+    /// Sets the maximum number of concurrent price fetches (WASM only).
+    #[cfg(target_arch = "wasm32")]
+    pub fn with_max_price_fetches(mut self, max: usize) -> Self {
+        self.concurrency.max_price_fetches = max;
+        self
+    }
+
+    /// Sets the maximum number of concurrent downloads (WASM only).
+    #[cfg(target_arch = "wasm32")]
+    pub fn with_max_downloads(mut self, max: usize) -> Self {
+        self.concurrency.max_downloads = max;
+        self
+    }
+
+    /// Sets the maximum number of concurrent uploads (WASM only).
+    #[cfg(target_arch = "wasm32")]
+    pub fn with_max_uploads(mut self, max: usize) -> Self {
+        self.concurrency.max_uploads = max;
+        self
+    }
+
+    /// Attempts to connect using the provided app key and TLS configuration.
+    /// If the app key is valid, returns Some([SDK]), otherwise returns None.
+    ///
+    /// If you receive None, call [Builder::request_connection] to request a new connection.
+    ///
+    /// # Arguments
+    /// * `app_key` - The application key used for authentication.
+    /// * `tls_config` - The TLS configuration for secure communication.
+    #[cfg(not(target_arch = "wasm32"))]
+    pub async fn connected(
+        &self,
+        app_key: &PrivateKey,
+        tls_config: rustls::ClientConfig,
+    ) -> Result<Option<SDK>, BuilderError> {
+        let connected = self.client.check_app_authenticated(app_key).await?;
+        if !connected {
+            return Ok(None);
+        }
+
+        let sdk = SDK::new(self.client.clone(), Arc::new(app_key.clone()), tls_config).await?;
+        Ok(Some(sdk))
+    }
+    #[cfg(target_arch = "wasm32")]
+    pub async fn connected(
+        &self,
+        app_key: &PrivateKey,
+    ) -> Result<Option<SDK>, BuilderError> {
+        let connected = self.client.check_app_authenticated(app_key).await?;
+        if !connected {
+            return Ok(None);
+        }
+
+        let sdk = SDK::new(
+            self.client.clone(),
+            Arc::new(app_key.clone()),
+            self.concurrency,
+        )
+        .await?;
+        Ok(Some(sdk))
+    }
+
+    /// Requests a new connection for the application.
+    ///
+    /// # Arguments
+    /// * `app` - Details of the application requesting connection.
+    pub async fn request_connection(
+        self,
+        app: &RegisterAppRequest,
+    ) -> Result<Builder<RequestingApprovalState>, BuilderError> {
+        let resp = self.client.request_app_connection(app).await?;
+        self.with_connection_response(app.app_id, resp)
+    }
+
+    /// Transitions to [RequestingApprovalState] using a pre-fetched
+    /// connection response. This is useful when the HTTP call to
+    /// `POST /auth/connect` was made out-of-band (e.g. via curl).
+    pub fn with_connection_response(
+        self,
+        app_id: Hash256,
+        response: RegisterAppResponse,
+    ) -> Result<Builder<RequestingApprovalState>, BuilderError> {
+        Ok(Builder {
+            state: RequestingApprovalState {
+                app_id,
+                response_url: Url::parse(&response.response_url)?,
+                register_url: Url::parse(&response.register_url)?,
+                status_url: Url::parse(&response.status_url)?,
+                expiration: response.expiration,
+            },
+            client: self.client,
+            #[cfg(target_arch = "wasm32")]
+            concurrency: self.concurrency,
+        })
+    }
+}
+
+impl Builder<RequestingApprovalState> {
+    /// Returns the response URL for the registration process. This
+    /// should be displayed to the user so they can authorize the
+    /// application.
+    pub fn response_url(&self) -> &str {
+        self.state.response_url.as_str()
+    }
+
+    /// Waits for the application registration to be approved. This
+    /// polls the status URL until the registration is approved or
+    /// rejected. This can take several minutes depending on user action.
+    ///
+    /// [Builder::response_url] should be displayed to the user
+    /// before calling this method.
+    pub async fn wait_for_approval(self) -> Result<Builder<ApprovedState>, BuilderError> {
+        loop {
+            if Utc::now() >= self.state.expiration {
+                return Err(BuilderError::RequestExpired);
+            }
+
+            if let Some(user_secret) = self
+                .client
+                .check_request_status(self.state.status_url.clone())
+                .await?
+            {
+                return Ok(Builder {
+                    state: ApprovedState {
+                        app_id: self.state.app_id,
+                        register_url: self.state.register_url.clone(),
+                        user_secret,
+                    },
+                    client: self.client,
+                    #[cfg(target_arch = "wasm32")]
+                    concurrency: self.concurrency,
+                });
+            }
+            sleep(Duration::from_secs(5)).await;
+        }
+    }
+}
+
+impl Builder<ApprovedState> {
+    /// Completes the registration process and returns an SDK instance.
+    ///
+    /// # Arguments
+    /// * `mnemonic` - The user's mnemonic phrase used to derive the application key.
+    /// * `tls_config` - The TLS configuration for secure communication.
+    ///
+    /// # Errors
+    /// Returns [BuilderError] if the registration fails or the SDK cannot be created.
+    #[cfg(not(target_arch = "wasm32"))]
+    pub async fn register(
+        self,
+        mnemonic: &str,
+        tls_config: rustls::ClientConfig,
+    ) -> Result<SDK, BuilderError> {
+        let app_key = derive_app_key(mnemonic, &self.state.app_id, &self.state.user_secret)?;
+        self.client
+            .register_app(&app_key, self.state.register_url.clone())
+            .await?;
+        SDK::new(self.client, Arc::new(app_key), tls_config).await
+    }
+
+    /// Completes the registration process and returns an SDK instance.
+    ///
+    /// # Arguments
+    /// * `mnemonic` - The user's mnemonic phrase used to derive the application key.
+    /// * `tls_config` - The TLS configuration for secure communication.
+    ///
+    /// # Errors
+    /// Returns [BuilderError] if the registration fails or the SDK cannot be created.
+    #[cfg(target_arch = "wasm32")]
+    pub async fn register(
+        self,
+        mnemonic: &str,
+    ) -> Result<SDK, BuilderError> {
+        let app_key = derive_app_key(mnemonic, &self.state.app_id, &self.state.user_secret)?;
+        self.client
+            .register_app(&app_key, self.state.register_url.clone())
+            .await?;
+        SDK::new(
+            self.client,
+            Arc::new(app_key),
+            self.concurrency,
+        )
+        .await
+    }
+}
+
+/// A helper function to derive an application key from a
+/// mnemonic, app ID, and shared secret.
+///
+/// It is exposed to be able to test the app key derivation logic.
+fn derive_app_key(
+    mnemonic: &str,
+    app_id: &Hash256,
+    shared_secret: &Hash256,
+) -> Result<PrivateKey, BuilderError> {
+    const KEY_DOMAIN: &[u8] = b"indexd app key derivation";
+    let seed = Seed::new(mnemonic)?;
+    let mut key = [0u8; 64];
+    key[..32].copy_from_slice(seed.entropy());
+    key[32..].copy_from_slice(shared_secret.as_ref());
+    let mut okm = [0u8; 32];
+    derive(&key, app_id.as_ref(), KEY_DOMAIN, &mut okm);
+    Ok(PrivateKey::from_seed(&okm))
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+    use sia::hash_256;
+    use sia::types::Hash256;
+
+    #[test]
+    fn test_app_key_derivation_golden() {
+        const MNEMONIC: &str =
+            "glare own entire dish exact open theme family harsh room scrap rose";
+        const APP_ID: Hash256 =
+            hash_256!("0e90d697f5045a6593f1c43ebf79a369e2bc72cc5c7b6282f3b5aeb0de6e4005");
+        const SHARED_SECRET: Hash256 =
+            hash_256!("cf02d945fe4bfe614d823dc13c19aa8501699e656d0f7915490c3056d5c97dc6");
+        const EXPECTED_APP_KEY: &str =
+            "b75061f34bb3aeab232b0671da2d0347c547343a0026bb5535c291d964fd09a1";
+
+        let mut seed = [0u8; 32];
+        hex::decode_to_slice(EXPECTED_APP_KEY, &mut seed).expect("decoding failed");
+        let expected_app_key = PrivateKey::from_seed(&seed);
+
+        let derived_app_key =
+            derive_app_key(MNEMONIC, &APP_ID, &SHARED_SECRET).expect("derivation failed");
+        assert_eq!(derived_app_key, expected_app_key);
+    }
+}