handlers: bootstrap the admin API router

Author: sandhose

Cargo.lock

@@ -55,6 +55,11 @@ mas-templates = { path = "./crates/templates/", version = "=0.9.0" }
 mas-tower = { path = "./crates/tower/", version = "=0.9.0" }
 oauth2-types = { path = "./crates/oauth2-types/", version = "=0.9.0" }
 
+# OpenAPI schema generation and validation
+[workspace.dependencies.aide]
+version = "0.13.4"
+features = ["axum", "axum-headers", "macros"]
+
 # GraphQL server
 [workspace.dependencies.async-graphql]
 version = "7.0.7"

Cargo.toml

@@ -36,7 +36,9 @@ axum-macros = "0.4.1"
 axum-extra.workspace = true
 rustls.workspace = true
 
+aide.workspace = true
 async-graphql.workspace = true
+schemars.workspace = true
 
 # Emails
 lettre.workspace = true
@@ -65,6 +67,7 @@ zeroize = "1.8.1"
 base64ct = "1.6.0"
 camino.workspace = true
 chrono.workspace = true
+indexmap = "2.2.6"
 psl = "2.1.55"
 time = "0.3.36"
 url.workspace = true

crates/handlers/Cargo.toml

@@ -0,0 +1,94 @@
+// 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::{
+    axum::ApiRouter,
+    openapi::{OAuth2Flow, OAuth2Flows, OpenApi, SecurityScheme, Server, ServerVariable},
+};
+use axum::{Json, Router};
+use hyper::header::{ACCEPT, AUTHORIZATION, CONTENT_TYPE};
+use indexmap::IndexMap;
+use mas_http::CorsLayerExt;
+use mas_router::{OAuth2AuthorizationEndpoint, OAuth2TokenEndpoint, SimpleRoute};
+use tower_http::cors::{Any, CorsLayer};
+
+pub fn router<S>() -> (OpenApi, Router<S>)
+where
+    S: Clone + Send + Sync + 'static,
+{
+    let mut api = OpenApi::default();
+    let router = ApiRouter::<S>::new()
+        // TODO: add routes
+        .finish_api_with(&mut api, |t| {
+            t.title("Matrix Authentication Service admin API")
+                .security_scheme(
+                    "oauth2",
+                    SecurityScheme::OAuth2 {
+                        flows: OAuth2Flows {
+                            client_credentials: Some(OAuth2Flow::ClientCredentials {
+                                refresh_url: Some(OAuth2TokenEndpoint::PATH.to_owned()),
+                                token_url: OAuth2TokenEndpoint::PATH.to_owned(),
+                                scopes: IndexMap::from([(
+                                    "urn:mas:admin".to_owned(),
+                                    "Grant access to the admin API".to_owned(),
+                                )]),
+                            }),
+                            authorization_code: Some(OAuth2Flow::AuthorizationCode {
+                                authorization_url: OAuth2AuthorizationEndpoint::PATH.to_owned(),
+                                refresh_url: Some(OAuth2TokenEndpoint::PATH.to_owned()),
+                                token_url: OAuth2TokenEndpoint::PATH.to_owned(),
+                                scopes: IndexMap::from([(
+                                    "urn:mas:admin".to_owned(),
+                                    "Grant access to the admin API".to_owned(),
+                                )]),
+                            }),
+                            implicit: None,
+                            password: None,
+                        },
+                        description: None,
+                        extensions: IndexMap::default(),
+                    },
+                )
+                .security_requirement_scopes("oauth2", ["urn:mas:admin"])
+                .server(Server {
+                    url: "{base}".to_owned(),
+                    variables: IndexMap::from([(
+                        "base".to_owned(),
+                        ServerVariable {
+                            default: "/".to_owned(),
+                            ..ServerVariable::default()
+                        },
+                    )]),
+                    ..Server::default()
+                })
+        });
+
+    let router = router
+        // Serve the OpenAPI spec as JSON
+        .route(
+            "/api/spec.json",
+            axum::routing::get({
+                let res = Json(api.clone());
+                move || std::future::ready(res.clone())
+            }),
+        )
+        .layer(
+            CorsLayer::new()
+                .allow_origin(Any)
+                .allow_methods(Any)
+                .allow_otel_headers([AUTHORIZATION, ACCEPT, CONTENT_TYPE]),
+        );
+
+    (api, router)
+}

crates/handlers/src/admin/mod.rs

@@ -53,6 +53,7 @@ use sqlx::PgPool;
 use tower::util::AndThenLayer;
 use tower_http::cors::{Any, CorsLayer};
 
+mod admin;
 mod compat;
 mod graphql;
 mod health;
@@ -89,6 +90,7 @@ pub use mas_axum_utils::{
 
 pub use self::{
     activity_tracker::{ActivityTracker, Bound as BoundActivityTracker},
+    admin::router as admin_api_router,
     graphql::{
         schema as graphql_schema, schema_builder as graphql_schema_builder, Schema as GraphQLSchema,
     },