s3s 0.13.0

S3 Service Adapter
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

//! S3 Authentication
//!
//! This module provides authentication support for S3 services, including AWS Signature
//! Version 4 and Version 2 verification.
//!
//! # Overview
//!
//! The authentication system verifies that incoming requests are signed with valid AWS
//! credentials. The main components are:
//!
//! - [`S3Auth`]: Trait for implementing authentication providers
//! - [`SimpleAuth`]: Simple in-memory authentication for testing and development
//! - [`SecretKey`]: Represents an AWS secret key
//! - [`Credentials`]: Represents authenticated credentials
//!
//! # Example
//!
//! ```
//! use s3s::auth::SimpleAuth;
//! use s3s::service::S3ServiceBuilder;
//! use s3s::{S3, S3Request, S3Response, S3Result};
//! use s3s::dto::{GetObjectInput, GetObjectOutput};
//!
//! #[derive(Clone)]
//! struct MyS3;
//!
//! #[async_trait::async_trait]
//! impl S3 for MyS3 {
//! #   async fn get_object(&self, _req: S3Request<GetObjectInput>) -> S3Result<S3Response<GetObjectOutput>> {
//! #       Err(s3s::s3_error!(NotImplemented))
//! #   }
//!     // Implement S3 operations
//! }
//!
//! // Create an auth provider with a single user
//! let auth = SimpleAuth::from_single("AKIAIOSFODNN7EXAMPLE", "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY");
//!
//! // Configure the service with authentication
//! let mut builder = S3ServiceBuilder::new(MyS3);
//! builder.set_auth(auth);
//! let service = builder.build();
//! ```
//!
//! # Custom Authentication
//!
//! You can implement custom authentication by implementing the [`S3Auth`] trait:
//!
//! ```
//! use s3s::auth::{S3Auth, SecretKey};
//! use s3s::S3Result;
//!
//! struct DatabaseAuth {
//!     // Your database connection
//! }
//!
//! #[async_trait::async_trait]
//! impl S3Auth for DatabaseAuth {
//!     async fn get_secret_key(&self, access_key: &str) -> S3Result<SecretKey> {
//!         // Query your database for the secret key
//!         // Return Err(s3_error!(InvalidAccessKeyId)) if not found
//! #       Err(s3s::s3_error!(InvalidAccessKeyId))
//!     }
//! }
//! ```
//!
//! # Security
//!
//! - Secret keys should be stored securely (e.g., in a secure database or secrets manager)
//! - Use HTTPS in production to prevent credential theft
//! - Rotate credentials regularly
//! - Use [`SimpleAuth`] only for testing, not production

mod secret_key;
pub use self::secret_key::{Credentials, SecretKey};

mod simple_auth;
pub use self::simple_auth::SimpleAuth;

use crate::error::S3Result;

/// S3 Authentication Provider
///
/// This trait defines the interface for authenticating S3 requests using AWS signatures.
/// Implementations should retrieve the secret key associated with an access key,
/// which is then used to verify the request signature.
///
/// # Example
///
/// ```
/// use s3s::auth::{S3Auth, SecretKey};
/// use s3s::S3Result;
///
/// struct MyAuth;
///
/// #[async_trait::async_trait]
/// impl S3Auth for MyAuth {
///     async fn get_secret_key(&self, access_key: &str) -> S3Result<SecretKey> {
///         // Look up the secret key for this access key
///         // This might involve a database query, API call, etc.
///         
///         if access_key == "AKIAIOSFODNN7EXAMPLE" {
///             Ok(SecretKey::from("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"))
///         } else {
///             Err(s3s::s3_error!(InvalidAccessKeyId))
///         }
///     }
/// }
/// ```
#[async_trait::async_trait]
pub trait S3Auth: Send + Sync + 'static {
    /// Gets the corresponding secret key for the given access key.
    ///
    /// This method is called during request authentication to retrieve the secret key
    /// needed to verify the request signature. Implementations typically query a
    /// database or credential store.
    ///
    /// # Arguments
    ///
    /// * `access_key` - The AWS access key ID from the request
    ///
    /// # Returns
    ///
    /// * `Ok(SecretKey)` - The secret key associated with the access key
    /// * `Err(S3Error)` - If the access key is not found or invalid
    ///
    /// # Errors
    ///
    /// Should return `InvalidAccessKeyId` error if the access key is not found.
    ///
    /// # Example
    ///
    /// ```
    /// use s3s::auth::{S3Auth, SecretKey};
    /// use s3s::S3Result;
    ///
    /// struct MyAuth;
    ///
    /// #[async_trait::async_trait]
    /// impl S3Auth for MyAuth {
    ///     async fn get_secret_key(&self, access_key: &str) -> S3Result<SecretKey> {
    ///         // In a real implementation, you might query a database:
    ///         // let secret = database.query("SELECT secret_key FROM users WHERE access_key = ?", access_key).await?;
    ///         
    ///         // For this example, just check a hardcoded key
    ///         if access_key == "test-key" {
    ///             Ok(SecretKey::from("test-secret"))
    ///         } else {
    ///             Err(s3s::s3_error!(InvalidAccessKeyId))
    ///         }
    ///     }
    /// }
    /// ```
    async fn get_secret_key(&self, access_key: &str) -> S3Result<SecretKey>;
}