Auth/PM-22661 - Send Access

crates/bitwarden-auth/Cargo.toml

@@ -26,14 +26,24 @@ wasm = [
 [dependencies]
 bitwarden-core = { workspace = true, features = ["internal"] }
 bitwarden-error = { workspace = true }
+chrono = { workspace = true }
+reqwest = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
+serde_urlencoded = "0.7.1"
 serde_qs = { workspace = true }
 thiserror = { workspace = true }
 tsify = { workspace = true, optional = true }
 uniffi = { workspace = true, optional = true }
 wasm-bindgen = { workspace = true, optional = true }
 wasm-bindgen-futures = { workspace = true, optional = true }
 
+[dev-dependencies]
+tokio = { workspace = true, features = ["rt"] }
+zeroize = { version = ">=1.7.0, <2.0", features = ["derive", "aarch64"] }
+wiremock = "0.6.0"
+
 [lints]
 workspace = true
+
+

crates/bitwarden-auth/README.md

@@ -1,3 +1,7 @@
 # Bitwarden Auth
 
 Contains the implementation of the auth functionality for the Bitwarden Password Manager.
+
+# Send Access
+
+- TODO: add context

crates/bitwarden-auth/src/common/enums/grant_type.rs

@@ -0,0 +1,10 @@
+use serde::{Deserialize, Serialize};
+
+/// Add a trait to this enum to allow for serialization and deserialization of the enum values.
+#[derive(Serialize, Deserialize, Debug)]
+/// Instructs deserialization to map the string "send_access" to the `SendAccess` variant.
+#[serde(rename_all = "snake_case")]
+pub enum GrantType {
+    SendAccess,
+    // TODO: Add other grant types as needed.
+}

crates/bitwarden-auth/src/common/enums/mod.rs

@@ -0,0 +1,5 @@
+mod grant_type;
+mod scope;
+
+pub use grant_type::GrantType;
+pub use scope::Scope;

crates/bitwarden-auth/src/common/enums/scope.rs

@@ -0,0 +1,8 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug)]
+pub enum Scope {
+    #[serde(rename = "api.send")]
+    Send,
+    // TODO: Add other scopes as needed.
+}

crates/bitwarden-auth/src/common/mod.rs

@@ -0,0 +1 @@
+pub mod enums;

crates/bitwarden-auth/src/lib.rs

@@ -1,6 +1,10 @@
 #![doc = include_str!("../README.md")]
 
 mod auth_client;
-mod send_access;
+mod common;
+
+/// Module for handling Send Access token requests and responses.
+pub mod send_access;
 
 pub use auth_client::{AuthClient, AuthClientExt};
+pub use common::enums::{GrantType, Scope};

crates/bitwarden-auth/src/send_access/access_token_request.rs

@@ -0,0 +1,97 @@
+#[cfg(feature = "wasm")]
+use tsify::Tsify;
+
+/// Credentials for sending password secured access requests.
+/// Clone auto implements the standard lib's Clone trait, allowing us to create copies of this
+/// struct.
+#[derive(serde::Serialize, serde::Deserialize, Clone)]
+#[cfg_attr(feature = "wasm", derive(Tsify), tsify(into_wasm_abi, from_wasm_abi))]
+pub struct SendPasswordCredentials {
+    /// A Base64-encoded hash of the password protecting the send.
+    pub password_hash_b64: String,
+}
+
+/// Credentials for sending an OTP to the user's email address.
+/// This is used when the send requires email verification with an OTP.
+#[derive(serde::Serialize, serde::Deserialize, Clone)]
+#[cfg_attr(feature = "wasm", derive(Tsify), tsify(into_wasm_abi, from_wasm_abi))]
+pub struct SendEmailCredentials {
+    /// The email address to which the OTP will be sent.
+    pub email: String,
+}
+
+/// Credentials for getting a send access token using an email and OTP.
+#[derive(serde::Serialize, serde::Deserialize, Clone)]
+#[cfg_attr(feature = "wasm", derive(Tsify), tsify(into_wasm_abi, from_wasm_abi))]
+pub struct SendEmailOtpCredentials {
+    /// The email address to which the OTP will be sent.
+    pub email: String,
+    /// The one-time password (OTP) that the user has received via email.
+    pub otp: String,
+}
+
+/// The credentials used for send access requests.
+#[derive(serde::Serialize, serde::Deserialize, Clone)]
+#[cfg_attr(feature = "wasm", derive(Tsify), tsify(into_wasm_abi, from_wasm_abi))]
+// Use untagged so that each variant can be serialized without a type tag.
+// For example, this allows us to serialize the password credentials as just
+// {"password_hash_b64": "value"} instead of {"type": "password", "password_hash_b64": "value"}.
+#[serde(untagged)]
+pub enum SendAccessCredentials {
+    #[allow(missing_docs)]
+    Password(SendPasswordCredentials),
+    #[allow(missing_docs)]
+    Email(SendEmailCredentials),
+    #[allow(missing_docs)]
+    EmailOtp(SendEmailOtpCredentials),
+}
+
+/// A request structure for requesting a send access token from the API.
+#[derive(serde::Serialize, serde::Deserialize, Clone)]
+#[cfg_attr(feature = "wasm", derive(Tsify), tsify(into_wasm_abi, from_wasm_abi))]
+pub struct SendAccessTokenRequest {
+    /// The id of the send for which the access token is requested.
+    pub send_id: String,
+
+    /// The optional send access credentials.
+    pub send_access_credentials: Option<SendAccessCredentials>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    mod send_access_credentials_tests {
+        use serde_json;
+
+        use super::*;
+
+        #[test]
+        fn serialize_password_credentials() {
+            let creds = SendAccessCredentials::Password(SendPasswordCredentials {
+                password_hash_b64: "ha$h".into(),
+            });
+            let json = serde_json::to_string(&creds).unwrap();
+            assert_eq!(json, r#"{"password_hash_b64":"ha$h"}"#);
+        }
+
+        #[test]
+        fn serialize_email_credentials() {
+            let creds = SendAccessCredentials::Email(SendEmailCredentials {
+                email: "[email protected]".into(),
+            });
+            let json = serde_json::to_string(&creds).unwrap();
+            assert_eq!(json, r#"{"email":"[email protected]"}"#);
+        }
+
+        #[test]
+        fn serialize_email_otp_credentials() {
+            let creds = SendAccessCredentials::EmailOtp(SendEmailOtpCredentials {
+                email: "[email protected]".into(),
+                otp: "123456".into(),
+            });
+            let json = serde_json::to_string(&creds).unwrap();
+            assert_eq!(json, r#"{"email":"[email protected]","otp":"123456"}"#);
+        }
+    }
+}

crates/bitwarden-auth/src/send_access/access_token_response.rs

@@ -0,0 +1,86 @@
+use std::fmt::Debug;
+
+use crate::send_access::api::{SendAccessTokenApiErrorResponse, SendAccessTokenApiSuccessResponse};
+
+/// A send access token which can be used to access a send.
+#[derive(serde::Serialize, serde::Deserialize, Clone)]
+#[cfg_attr(
+    feature = "wasm",
+    derive(tsify::Tsify),
+    tsify(into_wasm_abi, from_wasm_abi)
+)]
+#[derive(Debug)]
+pub struct SendAccessTokenResponse {
+    /// The actual token string.
+    pub token: String,
+    /// The timestamp in milliseconds when the token expires.
+    pub expires_at: i64,
+}
+
+impl From<SendAccessTokenApiSuccessResponse> for SendAccessTokenResponse {
+    fn from(response: SendAccessTokenApiSuccessResponse) -> Self {
+        // We want to convert the expires_in from seconds to a millisecond timestamp to have a
+        // concrete time the token will expire as it is easier to build logic around a
+        // concrete time rather than a duration.
+        let expires_at =
+            chrono::Utc::now().timestamp_millis() + (response.expires_in * 1000) as i64;
+
+        SendAccessTokenResponse {
+            token: response.access_token,
+            expires_at,
+        }
+    }
+}
+
+#[allow(missing_docs)]
+// We're using the full variant of the bitwarden-error macro because we want to keep the contents of
+// SendAccessTokenApiErrorResponse
+#[bitwarden_error::bitwarden_error(full)]
+#[derive(Debug, thiserror::Error)]
+pub enum SendAccessTokenError {
+    #[error("API Error: {0:?}")]
+    Api(AuthApiError),
+
+    #[error("Send access token error response")]
+    Response(SendAccessTokenApiErrorResponse),
+}
+
+// This is just a utility function so that the ? operator works correctly without manual mapping
+impl From<reqwest::Error> for SendAccessTokenError {
+    fn from(value: reqwest::Error) -> Self {
+        Self::Api(AuthApiError(value))
+    }
+}
+
+// This wrapper needs to exist because the `bitwarden_error(full)` macro requires every variant to
+// implement serialize+tsify, which is not the case for the `Api` variant. We only really care about
+// the contents of the `Response` variant, so ideally the macro would support a way of marking the
+// `Api` variant somehow so it gets serialized as a plain string.
+// As that is not the case, we have to implement it manually.
+
+#[derive(Debug)]
+pub struct AuthApiError(reqwest::Error);
+
+#[cfg(feature = "wasm")]
+#[wasm_bindgen::prelude::wasm_bindgen(typescript_custom_section)]
+const TS_CUSTOM_TYPES: &'static str = r#"
+export type AuthApiError = string;
+"#;
+
+impl serde::Serialize for AuthApiError {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        serializer.serialize_str(&format!("{:?}", self.0))
+    }
+}
+
+impl<'de> serde::Deserialize<'de> for AuthApiError {
+    fn deserialize<D>(_deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        Err(serde::de::Error::custom("deserialization not supported"))
+    }
+}

crates/bitwarden-auth/src/send_access/api/mod.rs

@@ -0,0 +1,13 @@
+mod token_api_error_response;
+mod token_api_success_response;
+mod token_request_payload;
+
+pub use token_api_error_response::{
+    SendAccessTokenApiErrorResponse, SendAccessTokenInvalidGrantError,
+    SendAccessTokenInvalidRequestError,
+};
+pub use token_api_success_response::SendAccessTokenApiSuccessResponse;
+// Keep payload types internal to the crate
+pub(crate) use token_request_payload::{
+    SendAccessTokenPayloadCredentials, SendAccessTokenRequestPayload,
+};