phala_tee_deploy_rs/
lib.rs

1//! # Phala TEE Deploy - Rust Client
2//!
3//! A Rust client library for deploying Docker containers to the Phala TEE Cloud platform.
4//! This library provides secure, efficient tools for managing containerized applications
5//! within Trusted Execution Environments.
6//!
7//! ## Key Features
8//!
9//! - **Secure Deployment**: Environment variables are encrypted using industry-standard cryptography
10//! - **Flexible API**: Both high-level (TeeDeployer) and low-level (TeeClient) interfaces
11//! - **Docker Compose Integration**: Direct integration with Docker Compose configurations
12//! - **TEEPod Management**: Discovery and selection of available TEE environments
13//! - **Robust Error Handling**: Comprehensive error types with detailed diagnostics
14//! - **Secure Workflows**: Support for separated operator/user deployment patterns
15//!
16//! ## Quick Start
17//!
18//! ```rust,no_run
19//! use phala_tee_deploy_rs::{Result, TeeDeployerBuilder};
20//! use std::collections::HashMap;
21//!
22//! #[tokio::main]
23//! async fn main() -> Result<()> {
24//!     // Create a deployer with your API key
25//!     let mut deployer = TeeDeployerBuilder::new()
26//!         .with_api_key("your-api-key")
27//!         .build()?;
28//!
29//!     // Discover available TEEPods
30//!     let teepods = deployer.discover_teepod().await?;
31//!
32//!     // Define environment variables (will be encrypted)
33//!     let mut env_vars = HashMap::new();
34//!     env_vars.insert("PORT".to_string(), "8080".to_string());
35//!     env_vars.insert("NODE_ENV".to_string(), "production".to_string());
36//!
37//!     // Deploy a simple NGINX service
38//!     let result = deployer.deploy_simple_service(
39//!         "nginx:latest",
40//!         "web",
41//!         "my-webapp",
42//!         env_vars,
43//!         Some(vec!["80:80".to_string()]),
44//!         None,
45//!         None,
46//!         None,
47//!         None,
48//!         None,
49//!     ).await?;
50//!
51//!     println!("Deployment successful: {:?}", result);
52//!     Ok(())
53//! }
54//! ```
55//!
56//! ## Security
57//!
58//! This library implements several security best practices:
59//!
60//! - X25519 key exchange for secure key distribution
61//! - AES-GCM for authenticated encryption of sensitive data
62//! - TLS for all API communications
63//! - Sensitive data is never logged in plaintext
64//!
65//! ## Secure Operator/User Workflow
66//!
67//! This library supports a secure workflow pattern that separates infrastructure management from sensitive data:
68//!
69//! ```rust,no_run
70//! use phala_tee_deploy_rs::{Encryptor, Result, TeeDeployerBuilder, PubkeyResponse};
71//!
72//! // OPERATOR PHASE 1: Setup infrastructure and get public key
73//! async fn operator_setup() -> Result<(serde_json::Value, String, String)> {
74//!     let mut deployer = TeeDeployerBuilder::new()
75//!         .with_api_key("operator-api-key")
76//!         .build()?;
77//!
78//!     let teepods = deployer.discover_teepod().await?;
79//!
80//!     // Create VM configuration
81//!     let vm_config = deployer.create_vm_config(
82//!         "version: '3'\nservices:\n  app:\n    image: nginx:alpine",
83//!         "secure-app",
84//!         None, None, None
85//!     )?;
86//!
87//!     // Get encryption public key
88//!     let vm_config_value = serde_json::to_value(&vm_config).unwrap();
89//!     let pubkey_response: PubkeyResponse = deployer.get_pubkey_for_config(&vm_config_value).await?;
90//!     let pubkey = pubkey_response.app_env_encrypt_pubkey;
91//!     let salt = pubkey_response.app_id_salt;
92//!
93//!     // Return VM config and encryption keys (to be sent to user)
94//!     Ok((vm_config_value, pubkey, salt))
95//! }
96//!
97//! // USER: Encrypt sensitive data
98//! fn user_encrypt_secrets(pubkey: &str) -> Result<String> {
99//!     let secrets = vec![
100//!         ("DB_PASSWORD".to_string(), "super-secret-password".to_string()),
101//!         ("API_KEY".to_string(), "secret-api-key".to_string()),
102//!     ];
103//!     
104//!     // Encrypt with public key
105//!     let encrypted_env = Encryptor::encrypt_env_vars(&secrets, pubkey)?;
106//!     
107//!     // Return encrypted data (to be sent back to operator)
108//!     Ok(encrypted_env)
109//! }
110//!
111//! // OPERATOR PHASE 2: Deploy with encrypted environment variables
112//! async fn operator_deploy(
113//!     vm_config: serde_json::Value,
114//!     encrypted_env: String,
115//!     pubkey: &str,
116//!     salt: &str
117//! ) -> Result<()> {
118//!     let mut deployer = TeeDeployerBuilder::new()
119//!         .with_api_key("operator-api-key")
120//!         .build()?;
121//!
122//!     // Deploy with encrypted environment variables
123//!     let deployment = deployer.deploy_with_encrypted_env(
124//!         vm_config, encrypted_env, &pubkey, &salt
125//!     ).await?;
126//!     
127//!     println!("Deployed successfully: {}", deployment.id);
128//!     Ok(())
129//! }
130//! ```
131//!
132//! ## Documentation
133//!
134//! For more advanced usage, see:
135//!
136//! - [`TeeDeployer`]: High-level API for most deployment scenarios
137//! - [`TeeClient`]: Low-level API for direct control over deployment details
138//! - [`DeploymentConfig`]: Configuration options for the deployment process
139//!
140//! ## Error Handling
141//!
142//! The library uses a comprehensive [`Error`] type with variants for different
143//! failure scenarios, making error diagnosis and handling straightforward.
144
145mod client;
146mod config;
147mod crypto;
148mod deployer;
149mod error;
150mod types;
151
152#[cfg(test)]
153mod tests;
154
155pub use client::TeeClient;
156pub use config::DeploymentConfig;
157pub use crypto::Encryptor;
158pub use deployer::{TeeDeployer, TeeDeployerBuilder};
159pub use error::Error;
160pub use types::*;
161
162/// Result type for Phala TEE deployment operations.
163///
164/// This is a convenience alias for `std::result::Result<T, Error>` that simplifies
165/// error handling throughout the library.
166pub type Result<T> = std::result::Result<T, Error>;
phala_tee_deploy_rs/lib.rs

phala_tee_deploy_rs/
lib.rs
