api: support for appservice-exclusive authentication

crates/ruma-common/CHANGELOG.md

@@ -10,6 +10,7 @@ Breaking changes:
   match the `.m.rule.invite_for_me` push rule because usually the `invite_state` doesn't include
   `m.room.power_levels`.
 - Add support for endpoints that take an optional authentication
+- Add support for endpoints that require authentication for appservices
 
 Improvements:
 

crates/ruma-common/src/api.rs

@@ -318,6 +318,10 @@ pub enum SendAccessToken<'a> {
     /// Always add the access token.
     Always(&'a str),
 
+    /// Add the given appservice token to the request only if the `METADATA` on the request
+    /// requires it.
+    Appservice(&'a str),
+
     /// Don't add an access token.
     ///
     /// This will lead to an error if the request endpoint requires authentication
@@ -329,7 +333,7 @@ impl<'a> SendAccessToken<'a> {
     ///
     /// Returns `Some(_)` if `self` contains an access token.
     pub fn get_required_for_endpoint(self) -> Option<&'a str> {
-        as_variant!(self, Self::IfRequired | Self::Always)
+        as_variant!(self, Self::IfRequired | Self::Appservice | Self::Always)
     }
 
     /// Get the access token for an endpoint that should not require one.
@@ -338,6 +342,14 @@ impl<'a> SendAccessToken<'a> {
     pub fn get_not_required_for_endpoint(self) -> Option<&'a str> {
         as_variant!(self, Self::Always)
     }
+
+    /// Gets the access token for an endpoint that requires one for appservices.
+    ///
+    /// Returns `Some(_)` if `self` is either `SendAccessToken::Appservice(_)`
+    /// or `SendAccessToken::Always(_)`
+    pub fn get_required_for_appservice(self) -> Option<&'a str> {
+        as_variant!(self, Self::Appservice | Self::Always)
+    }
 }
 
 /// A request type for a Matrix API endpoint, used for sending requests.
@@ -490,6 +502,12 @@ pub enum AuthScheme {
     /// It is recommended to use the header over the query parameter.
     AccessTokenOptional,
 
+    /// Authentication is only performed for appservices, by including an access token in the
+    /// `Authentication` http header, or an `access_token` query parameter.
+    ///
+    /// It is recommended to use the header over the query parameter.
+    AppserviceToken,
+
     /// Authentication is performed by including X-Matrix signatures in the request headers,
     /// as defined in the federation API.
     ServerSignatures,

crates/ruma-common/src/api/metadata.rs

@@ -79,6 +79,11 @@ impl Metadata {
                 None => None,
             },
 
+            AuthScheme::AppserviceToken => match access_token.get_required_for_appservice() {
+                Some(token) => Some((header::AUTHORIZATION, format!("Bearer {token}").try_into()?)),
+                None => None,
+            },
+
             AuthScheme::ServerSignatures => None,
         })
     }