admin: lock user API

crates/handlers/src/admin/v1/mod.rs

@@ -49,6 +49,10 @@ where
             "/users/:id/deactivate",
             post_with(self::users::deactivate, self::users::deactivate_doc),
         )
+        .api_route(
+            "/users/:id/lock",
+            post_with(self::users::lock, self::users::lock_doc),
+        )
         .api_route(
             "/users/:id/unlock",
             post_with(self::users::unlock, self::users::unlock_doc),

crates/handlers/src/admin/v1/users/lock.rs

@@ -0,0 +1,185 @@
+// Copyright 2024 The Matrix.org Foundation C.I.C.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use aide::{transform::TransformOperation, OperationIo};
+use axum::{response::IntoResponse, Json};
+use hyper::StatusCode;
+use ulid::Ulid;
+
+use crate::{
+    admin::{
+        call_context::CallContext,
+        model::{Resource, User},
+        params::UlidPathParam,
+        response::{ErrorResponse, SingleResponse},
+    },
+    impl_from_error_for_route,
+};
+
+#[derive(Debug, thiserror::Error, OperationIo)]
+#[aide(output_with = "Json<ErrorResponse>")]
+pub enum RouteError {
+    #[error(transparent)]
+    Internal(Box<dyn std::error::Error + Send + Sync + 'static>),
+
+    #[error("User ID {0} not found")]
+    NotFound(Ulid),
+}
+
+impl_from_error_for_route!(mas_storage::RepositoryError);
+
+impl IntoResponse for RouteError {
+    fn into_response(self) -> axum::response::Response {
+        let error = ErrorResponse::from_error(&self);
+        let status = match self {
+            Self::Internal(_) => StatusCode::INTERNAL_SERVER_ERROR,
+            Self::NotFound(_) => StatusCode::NOT_FOUND,
+        };
+        (status, Json(error)).into_response()
+    }
+}
+
+pub fn doc(operation: TransformOperation) -> TransformOperation {
+    operation
+        .id("lockUser")
+        .summary("Lock a user")
+        .description("Calling this endpoint will lock the user, preventing them from doing any action.
+This DOES NOT invalidate any existing session, meaning that all their existing sessions will work again as soon as they get unlocked.")
+        .tag("user")
+        .response_with::<200, Json<SingleResponse<User>>, _>(|t| {
+            // In the samples, the third user is the one locked
+            let [_alice, _bob, charlie, ..] = User::samples();
+            let id = charlie.id();
+            let response = SingleResponse::new(charlie, format!("/api/admin/v1/users/{id}/lock"));
+            t.description("User was locked").example(response)
+        })
+        .response_with::<404, RouteError, _>(|t| {
+            let response = ErrorResponse::from_error(&RouteError::NotFound(Ulid::nil()));
+            t.description("User ID not found").example(response)
+        })
+}
+
+#[tracing::instrument(name = "handler.admin.v1.users.lock", skip_all, err)]
+pub async fn handler(
+    CallContext {
+        mut repo, clock, ..
+    }: CallContext,
+    id: UlidPathParam,
+) -> Result<Json<SingleResponse<User>>, RouteError> {
+    let id = *id;
+    let mut user = repo
+        .user()
+        .lookup(id)
+        .await?
+        .ok_or(RouteError::NotFound(id))?;
+
+    if user.locked_at.is_none() {
+        user = repo.user().lock(&clock, user).await?;
+    }
+
+    repo.save().await?;
+
+    Ok(Json(SingleResponse::new(
+        User::from(user),
+        format!("/api/admin/v1/users/{id}/lock"),
+    )))
+}
+
+#[cfg(test)]
+mod tests {
+    use chrono::Duration;
+    use hyper::{Request, StatusCode};
+    use mas_storage::{user::UserRepository, Clock, RepositoryAccess};
+    use sqlx::PgPool;
+
+    use crate::test_utils::{setup, RequestBuilderExt, ResponseExt, TestState};
+
+    #[sqlx::test(migrator = "mas_storage_pg::MIGRATOR")]
+    async fn test_lock_user(pool: PgPool) {
+        setup();
+        let mut state = TestState::from_pool(pool).await.unwrap();
+        let token = state.token_with_scope("urn:mas:admin").await;
+
+        let mut repo = state.repository().await.unwrap();
+        let user = repo
+            .user()
+            .add(&mut state.rng(), &state.clock, "alice".to_owned())
+            .await
+            .unwrap();
+        repo.save().await.unwrap();
+
+        let request = Request::post(format!("/api/admin/v1/users/{}/lock", user.id))
+            .bearer(&token)
+            .empty();
+        let response = state.request(request).await;
+        response.assert_status(StatusCode::OK);
+        let body: serde_json::Value = response.json();
+
+        // The locked_at timestamp should be the same as the current time
+        assert_eq!(
+            body["data"]["attributes"]["locked_at"],
+            serde_json::json!(state.clock.now())
+        );
+    }
+
+    #[sqlx::test(migrator = "mas_storage_pg::MIGRATOR")]
+    async fn test_lock_user_twice(pool: PgPool) {
+        setup();
+        let mut state = TestState::from_pool(pool).await.unwrap();
+        let token = state.token_with_scope("urn:mas:admin").await;
+
+        let mut repo = state.repository().await.unwrap();
+        let user = repo
+            .user()
+            .add(&mut state.rng(), &state.clock, "alice".to_owned())
+            .await
+            .unwrap();
+        let user = repo.user().lock(&state.clock, user).await.unwrap();
+        repo.save().await.unwrap();
+
+        // Move the clock forward to make sure the locked_at timestamp doesn't change
+        state.clock.advance(Duration::try_minutes(1).unwrap());
+
+        let request = Request::post(format!("/api/admin/v1/users/{}/lock", user.id))
+            .bearer(&token)
+            .empty();
+        let response = state.request(request).await;
+        response.assert_status(StatusCode::OK);
+        let body: serde_json::Value = response.json();
+
+        // The locked_at timestamp should be different from the current time
+        assert_ne!(
+            body["data"]["attributes"]["locked_at"],
+            serde_json::json!(state.clock.now())
+        );
+    }
+
+    #[sqlx::test(migrator = "mas_storage_pg::MIGRATOR")]
+    async fn test_lock_unknown_user(pool: PgPool) {
+        setup();
+        let mut state = TestState::from_pool(pool).await.unwrap();
+        let token = state.token_with_scope("urn:mas:admin").await;
+
+        let request = Request::post("/api/admin/v1/users/01040G2081040G2081040G2081/lock")
+            .bearer(&token)
+            .empty();
+        let response = state.request(request).await;
+        response.assert_status(StatusCode::NOT_FOUND);
+        let body: serde_json::Value = response.json();
+        assert_eq!(
+            body["errors"][0]["title"],
+            "User ID 01040G2081040G2081040G2081 not found"
+        );
+    }
+}

crates/handlers/src/admin/v1/users/mod.rs

@@ -17,6 +17,7 @@ mod by_username;
 mod deactivate;
 mod get;
 mod list;
+mod lock;
 mod unlock;
 
 pub use self::{
@@ -25,5 +26,6 @@ pub use self::{
     deactivate::{doc as deactivate_doc, handler as deactivate},
     get::{doc as get_doc, handler as get},
     list::{doc as list_doc, handler as list},
+    lock::{doc as lock_doc, handler as lock},
     unlock::{doc as unlock_doc, handler as unlock},
 };

docs/api/spec.json

@@ -448,6 +448,75 @@
         }
       }
     },
+    "/api/admin/v1/users/{id}/lock": {
+      "post": {
+        "tags": [
+          "user"
+        ],
+        "summary": "Lock a user",
+        "description": "Calling this endpoint will lock the user, preventing them from doing any action.\nThis DOES NOT invalidate any existing session, meaning that all their existing sessions will work again as soon as they get unlocked.",
+        "operationId": "lockUser",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": {
+              "title": "The ID of the resource",
+              "$ref": "#/components/schemas/ULID"
+            },
+            "style": "simple"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "User was locked",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SingleResponse_for_User"
+                },
+                "example": {
+                  "data": {
+                    "type": "user",
+                    "id": "030C1G60R30C1G60R30C1G60R3",
+                    "attributes": {
+                      "username": "charlie",
+                      "created_at": "1970-01-01T00:00:00Z",
+                      "locked_at": "1970-01-01T00:00:00Z",
+                      "can_request_admin": false
+                    },
+                    "links": {
+                      "self": "/api/admin/v1/users/030C1G60R30C1G60R30C1G60R3"
+                    }
+                  },
+                  "links": {
+                    "self": "/api/admin/v1/users/030C1G60R30C1G60R30C1G60R3/lock"
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "User ID not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "example": {
+                  "errors": [
+                    {
+                      "title": "User ID 00000000000000000000000000 not found"
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/admin/v1/users/{id}/unlock": {
       "post": {
         "tags": [