Auth/PM-22661 - Send Access

crates/bitwarden-auth/Cargo.toml

@@ -23,17 +23,28 @@ wasm = [
     "dep:wasm-bindgen-futures"
 ] # WASM support
 
+# Note: dependencies must be alphabetized to pass the cargo sort check in the CI pipeline..
 [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_qs = { workspace = true }
+serde_urlencoded = "0.7.1"
 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"] }
+wiremock = "0.6.0"
+zeroize = { version = ">=1.7.0, <2.0", features = ["derive", "aarch64"] }
+
 [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,16 @@
+use serde::{Deserialize, Serialize};
+
+/// Represents the OAuth 2.0 grant types recognized by the Bitwarden API.
+/// A grant type specifies the method a client uses to obtain an access token,
+/// as defined in [RFC 6749, Section 4](https://datatracker.ietf.org/doc/html/rfc6749#section-4)
+/// or by custom Bitwarden extensions. The value is sent in the `grant_type` parameter
+/// of a token request.
+#[derive(Serialize, Deserialize, Debug)]
+/// Instructs deserialization to map the string "send_access" to the `SendAccess` variant.
+#[serde(rename_all = "snake_case")]
+pub enum GrantType {
+    /// A custom extension grant type for requesting send access tokens outside the context of a
+    /// Bitwarden user.
+    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,13 @@
+use serde::{Deserialize, Serialize};
+
+/// The OAuth 2.0 scopes recognized by the Bitwarden API.
+/// Scopes define the specific permissions an access token grants to the client.
+/// They are requested by the client during token acquisition and enforced by the
+/// resource server when the token is used.
+#[derive(Serialize, Deserialize, Debug)]
+pub enum Scope {
+    /// The scope for accessing send resources outside the context of a Bitwarden user.
+    #[serde(rename = "api.send.access")]
+    ApiSendAccess,
+    // 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,251 @@
+#[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, Debug)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+#[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, Debug)]
+#[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, Debug)]
+#[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, Debug)]
+#[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, Debug)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+#[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,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "wasm", tsify(optional))]
+    /// The optional send access credentials.
+    pub send_access_credentials: Option<SendAccessCredentials>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    mod send_access_token_request_tests {
+        use serde_json::{from_str, to_string};
+
+        use super::*;
+
+        #[test]
+        fn deserialize_camelcase_request() {
+            let json = r#"
+        {
+          "sendId": "abc123",
+          "sendAccessCredentials": { "passwordHashB64": "ha$h" }
+        }"#;
+
+            let req: SendAccessTokenRequest = from_str(json).unwrap();
+            assert_eq!(req.send_id, "abc123");
+
+            let creds = req.send_access_credentials.expect("expected Some");
+            match creds {
+                SendAccessCredentials::Password(p) => assert_eq!(p.password_hash_b64, "ha$h"),
+                _ => panic!("expected Password variant"),
+            }
+        }
+
+        #[test]
+        fn serialize_camelcase_request_with_credentials() {
+            let req = SendAccessTokenRequest {
+                send_id: "abc123".into(),
+                send_access_credentials: Some(SendAccessCredentials::Password(
+                    SendPasswordCredentials {
+                        password_hash_b64: "ha$h".into(),
+                    },
+                )),
+            };
+            let json = to_string(&req).unwrap();
+            assert_eq!(
+                json,
+                r#"{"sendId":"abc123","sendAccessCredentials":{"passwordHashB64":"ha$h"}}"#
+            );
+        }
+
+        #[test]
+        fn serialize_omits_optional_credentials_when_none() {
+            let req = SendAccessTokenRequest {
+                send_id: "abc123".into(),
+                send_access_credentials: None,
+            };
+            let json = to_string(&req).unwrap();
+            assert_eq!(json, r#"{"sendId":"abc123"}"#);
+        }
+
+        #[test]
+        fn roundtrip_camel_in_to_camel_out() {
+            let in_json = r#"
+        {
+          "sendId": "abc123",
+          "sendAccessCredentials": { "passwordHashB64": "ha$h" }
+        }"#;
+
+            let req: SendAccessTokenRequest = from_str(in_json).unwrap();
+            let out_json = to_string(&req).unwrap();
+            assert_eq!(
+                out_json,
+                r#"{"sendId":"abc123","sendAccessCredentials":{"passwordHashB64":"ha$h"}}"#
+            );
+        }
+
+        #[test]
+        fn snakecase_top_level_keys_are_rejected() {
+            let json = r#"
+        {
+          "send_id": "abc123",
+          "sendAccessCredentials": { "passwordHashB64": "ha$h" }
+        }"#;
+            let err = from_str::<SendAccessTokenRequest>(json).unwrap_err();
+            let msg = err.to_string();
+            assert!(
+                msg.contains("unknown field") && msg.contains("send_id"),
+                "unexpected: {msg}"
+            );
+        }
+
+        #[test]
+        fn extra_top_level_key_is_rejected() {
+            let json = r#"
+        {
+          "sendId": "abc123",
+          "sendAccessCredentials": { "passwordHashB64": "ha$h" },
+          "extra": "nope"
+        }"#;
+            let err = from_str::<SendAccessTokenRequest>(json).unwrap_err();
+            let msg = err.to_string();
+            assert!(
+                msg.contains("unknown field") && msg.contains("extra"),
+                "unexpected: {msg}"
+            );
+        }
+
+        #[test]
+        fn snakecase_nested_keys_are_rejected() {
+            let json = r#"
+    {
+      "sendId": "abc123",
+      "sendAccessCredentials": { "password_hash_b64": "ha$h" }
+    }"#;
+
+            let err = serde_json::from_str::<SendAccessTokenRequest>(json).unwrap_err();
+            let msg = err.to_string();
+            assert!(
+                msg.contains("did not match any variant"),
+                "unexpected: {msg}"
+            );
+        }
+
+        #[test]
+        fn extra_nested_key_is_rejected() {
+            let json = r#"
+        {
+          "sendId": "abc123",
+          "sendAccessCredentials": {
+            "passwordHashB64": "ha$h",
+            "extra": "nope"
+          }
+        }"#;
+            let err = from_str::<SendAccessTokenRequest>(json).unwrap_err();
+            let msg = err.to_string();
+            assert!(
+                msg.contains("did not match any variant"),
+                "unexpected: {msg}"
+            );
+        }
+    }
+
+    mod send_access_credentials_tests {
+        use super::*;
+
+        mod send_access_password_credentials_tests {
+            use serde_json::{from_str, to_string};
+
+            use super::*;
+            #[test]
+            fn deserializes_camelcase_from_ts() {
+                let json = r#"{ "passwordHashB64": "ha$h" }"#;
+                let s: SendPasswordCredentials = from_str(json).unwrap();
+                assert_eq!(s.password_hash_b64, "ha$h");
+            }
+
+            #[test]
+            fn serializes_camelcase_to_wire() {
+                let s = SendPasswordCredentials {
+                    password_hash_b64: "ha$h".into(),
+                };
+                let json = to_string(&s).unwrap();
+                assert_eq!(json, r#"{"passwordHashB64":"ha$h"}"#);
+            }
+
+            #[test]
+            fn roundtrip_camel_in_to_camel_out() {
+                let in_json = r#"{ "passwordHashB64": "ha$h" }"#;
+                let parsed: SendPasswordCredentials = from_str(in_json).unwrap();
+                let out_json = to_string(&parsed).unwrap();
+                assert_eq!(out_json, r#"{"passwordHashB64":"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"}"#);
+        }
+    }
+}