Skip to main content

auth_framework/api/
server.rs

1//! REST API Server Implementation
2//!
3//! Main server that hosts all API endpoints
4
5use crate::AuthFramework;
6#[cfg(feature = "saml")]
7use crate::api::saml;
8use crate::api::{
9    ApiState, admin, advanced_protocols, auth, email_verification, health, mfa, middleware,
10    oauth_advanced, oauth2, openapi, users, webauthn,
11};
12use axum::{
13    Router,
14    extract::DefaultBodyLimit,
15    http::Method,
16    middleware as axum_middleware,
17    routing::{delete, get, post, put},
18};
19use std::net::SocketAddr;
20use std::sync::Arc;
21use tower::ServiceBuilder;
22use tower_http::{cors::CorsLayer, trace::TraceLayer};
23use tracing::info;
24
25/// REST API server configuration.
26///
27/// Use [`ApiServerConfig::builder()`] for ergonomic construction:
28///
29/// ```rust,ignore
30/// let config = ApiServerConfig::builder()
31///     .host("0.0.0.0")
32///     .port(3000)
33///     .enable_cors(true)
34///     .allow_origin("https://example.com")
35///     .build();
36/// ```
37///
38/// Default values bind to `127.0.0.1:8080` with tracing enabled, CORS disabled,
39/// and a 1 MB maximum request body.
40#[derive(Debug, Clone)]
41pub struct ApiServerConfig {
42    /// Address to bind the server to (default: `"127.0.0.1"`).
43    pub host: String,
44    /// TCP port to listen on (default: `8080`).
45    pub port: u16,
46    /// Centralized CORS configuration. Enable and set `allowed_origins` to
47    /// permit cross-origin requests. Origins are validated strictly — wildcard
48    /// (`"*"`) is never accepted.
49    pub cors: crate::config::CorsConfig,
50    /// Maximum allowed request body size in bytes (default: 1 MB).
51    pub max_body_size: usize,
52    /// Whether to attach a `tower_http::TraceLayer` for structured request/response logging.
53    pub enable_tracing: bool,
54}
55
56impl ApiServerConfig {
57    /// Convenience: is CORS enabled?
58    pub fn enable_cors(&self) -> bool {
59        self.cors.enabled
60    }
61}
62
63impl Default for ApiServerConfig {
64    fn default() -> Self {
65        Self {
66            host: "127.0.0.1".to_string(),
67            port: 8080,
68            cors: crate::config::CorsConfig::default(), // disabled by default
69            max_body_size: 1024 * 1024,                 // 1MB
70            enable_tracing: true,
71        }
72    }
73}
74
75/// REST API Server
76impl ApiServerConfig {
77    /// Create a new builder for `ApiServerConfig`
78    pub fn builder() -> ApiServerConfigBuilder {
79        ApiServerConfigBuilder::default()
80    }
81}
82
83/// Fluent builder for [`ApiServerConfig`].
84///
85/// Obtain via [`ApiServerConfig::builder()`].  All fields start with the same
86/// defaults as `ApiServerConfig::default()`.
87#[derive(Default)]
88pub struct ApiServerConfigBuilder {
89    config: ApiServerConfig,
90}
91
92impl ApiServerConfigBuilder {
93    /// Set the address to bind to (e.g. `"0.0.0.0"`).
94    pub fn host(mut self, host: impl Into<String>) -> Self {
95        self.config.host = host.into();
96        self
97    }
98
99    /// Set the TCP port (e.g. `3000`).
100    pub fn port(mut self, port: u16) -> Self {
101        self.config.port = port;
102        self
103    }
104
105    /// Enable or disable CORS (default: disabled).
106    pub fn enable_cors(mut self, enable: bool) -> Self {
107        self.config.cors.enabled = enable;
108        self
109    }
110
111    /// Append a single allowed origin for CORS (e.g. `"https://example.com"`).
112    pub fn allow_origin(mut self, origin: impl Into<String>) -> Self {
113        self.config.cors.allowed_origins.push(origin.into());
114        self
115    }
116
117    /// Replace the allowed origins list for CORS.
118    pub fn allowed_origins(mut self, origins: Vec<String>) -> Self {
119        self.config.cors.allowed_origins = origins;
120        self
121    }
122
123    /// Set the maximum request body size in bytes (default: 1 MB).
124    pub fn max_body_size(mut self, size: usize) -> Self {
125        self.config.max_body_size = size;
126        self
127    }
128
129    /// Enable or disable structured request/response tracing (default: enabled).
130    pub fn enable_tracing(mut self, enable: bool) -> Self {
131        self.config.enable_tracing = enable;
132        self
133    }
134
135    /// Consume the builder and return the finished [`ApiServerConfig`].
136    pub fn build(self) -> ApiServerConfig {
137        self.config
138    }
139}
140
141/// The REST API server that hosts all authentication, user-management,
142/// and health-check endpoints.
143///
144/// # Example
145///
146/// ```rust,ignore
147/// let server = ApiServer::with_config(auth.clone(), config);
148/// server.start().await?;
149/// ```
150pub struct ApiServer {
151    config: ApiServerConfig,
152    auth_framework: Arc<AuthFramework>,
153}
154
155impl ApiServer {
156    /// Create a server with the default [`ApiServerConfig`].
157    pub fn new(auth_framework: Arc<AuthFramework>) -> Self {
158        Self {
159            config: ApiServerConfig::default(),
160            auth_framework,
161        }
162    }
163
164    /// Create a server with a custom [`ApiServerConfig`].
165    pub fn with_config(auth_framework: Arc<AuthFramework>, config: ApiServerConfig) -> Self {
166        Self {
167            config,
168            auth_framework,
169        }
170    }
171
172    /// Assemble the Axum [`Router`] with all route groups and middleware.
173    pub async fn build_router(&self) -> crate::errors::Result<Router> {
174        let state = ApiState::new(self.auth_framework.clone()).await?;
175
176        // Create nested router for API v1
177        let api_v1 = Router::new()
178            // Health and monitoring endpoints (public)
179            .route("/health", get(health::health_check))
180            .route("/health/detailed", get(health::detailed_health_check))
181            .route("/metrics", get(health::metrics))
182            .route("/readiness", get(health::readiness_check))
183            .route("/liveness", get(health::liveness_check))
184            // Authentication endpoints (public)
185            .route("/auth/login", post(auth::login))
186            .route("/auth/register", post(auth::register))
187            .route("/auth/refresh", post(auth::refresh_token))
188            .route("/auth/logout", post(auth::logout))
189            .route("/auth/validate", get(auth::validate_token))
190            .route("/auth/providers", get(auth::list_providers))
191            .route("/api-keys", post(auth::create_api_key))
192            // Email verification endpoints
193            .route(
194                "/auth/verify-email/send",
195                post(email_verification::send_verification),
196            )
197            .route("/auth/verify-email", post(email_verification::verify_email))
198            .route(
199                "/auth/resend-verification",
200                post(email_verification::resend_verification),
201            )
202            // OAuth 2.0 endpoints
203            .route("/oauth/authorize", get(oauth2::authorize))
204            .route("/oauth/token", post(oauth2::token))
205            .route("/oauth/revoke", post(oauth2::revoke))
206            // RFC 7662: Token Introspection (form-encoded, client auth required)
207            .route("/oauth/introspect", post(oauth_advanced::introspect_token))
208            // RFC 9126: Pushed Authorization Requests
209            .route(
210                "/oauth/par",
211                post(oauth_advanced::pushed_authorization_request),
212            )
213            .route("/oauth/clients/{client_id}", get(oauth2::get_client_info))
214            // RFC 8628: Device Authorization Grant
215            .route("/oauth/device", post(oauth_advanced::device_authorization))
216            // OpenID Connect CIBA (Client Initiated Backchannel Auth)
217            .route("/oauth/ciba", post(oauth_advanced::ciba_backchannel_auth))
218            // OIDC UserInfo endpoint
219            .route("/oauth/userinfo", get(oauth2::userinfo))
220            // OIDC RP-Initiated Logout
221            .route("/oauth/end_session", get(oauth2::end_session))
222            // RFC 7591: Dynamic Client Registration
223            .route("/oauth/register", post(oauth2::register_client))
224            // OpenID Connect Discovery
225            .route(
226                "/.well-known/openid-configuration",
227                get(oauth2::openid_configuration),
228            )
229            // JWKS endpoint
230            .route("/.well-known/jwks.json", get(oauth2::jwks))
231            // User management endpoints (authenticated)
232            .route("/users/me", get(oauth2::users_me))
233            .route("/users/profile", get(users::get_profile))
234            .route("/users/profile", put(users::update_profile))
235            .route("/users/change-password", post(users::change_password))
236            .route("/users/sessions", get(users::get_sessions))
237            .route(
238                "/users/sessions/{session_id}",
239                delete(users::revoke_session),
240            )
241            .route("/users/{user_id}/profile", get(users::get_user_profile))
242            // Multi-factor authentication endpoints (authenticated)
243            .route("/mfa/setup", post(mfa::setup_mfa))
244            .route("/mfa/verify", post(mfa::verify_mfa))
245            .route("/mfa/disable", post(mfa::disable_mfa))
246            .route("/mfa/status", get(mfa::get_mfa_status))
247            .route(
248                "/mfa/regenerate-backup-codes",
249                post(mfa::regenerate_backup_codes),
250            )
251            .route("/mfa/verify-backup-code", post(mfa::verify_backup_code))
252            // Administrative endpoints (admin only)
253            .route("/admin/users", get(admin::list_users))
254            .route("/admin/users", post(admin::create_user))
255            .route(
256                "/admin/users/{user_id}/roles",
257                put(admin::update_user_roles),
258            )
259            .route("/admin/users/{user_id}", delete(admin::delete_user))
260            .route("/admin/users/{user_id}/activate", put(admin::activate_user))
261            .route("/admin/stats", get(admin::get_system_stats))
262            .route("/admin/audit-logs", get(admin::get_audit_logs))
263            .route("/admin/audit-logs/stats", get(admin::get_audit_log_stats))
264            .route(
265                "/admin/config",
266                get(admin::get_config).put(admin::update_config),
267            )
268            // WebAuthn endpoints
269            .route(
270                "/webauthn/registration/init",
271                post(webauthn::webauthn_registration_init),
272            )
273            .route(
274                "/webauthn/registration/complete",
275                post(webauthn::webauthn_registration_complete),
276            )
277            .route(
278                "/webauthn/authentication/init",
279                post(webauthn::webauthn_authentication_init),
280            )
281            .route(
282                "/webauthn/authentication/complete",
283                post(webauthn::webauthn_authentication_complete),
284            )
285            .route(
286                "/webauthn/credentials/{username}",
287                get(webauthn::list_webauthn_credentials),
288            )
289            .route(
290                "/webauthn/credentials/{username}/{credential_id}",
291                delete(webauthn::delete_webauthn_credential),
292            );
293
294        // Build the router with conditional SAML routes
295        let api_v1 = {
296            let router = api_v1;
297
298            #[cfg(feature = "saml")]
299            {
300                router
301                    .route("/saml/metadata", get(saml::get_saml_metadata))
302                    .route("/saml/sso", post(saml::initiate_saml_sso))
303                    .route("/saml/acs", post(saml::handle_saml_acs))
304                    .route("/saml/slo", post(saml::initiate_saml_slo))
305                    .route("/saml/slo/response", get(saml::handle_saml_slo_response))
306                    .route("/saml/assertion", post(saml::create_saml_assertion))
307                    .route("/saml/idps", get(saml::list_saml_idps))
308            }
309
310            #[cfg(not(feature = "saml"))]
311            {
312                router
313            }
314        };
315
316        // Create the main router with all routes
317        let router = Router::new()
318            .route("/api/openapi.json", get(openapi::serve_openapi_json))
319            .route("/docs", get(openapi::serve_swagger_ui))
320            .nest("/api/v1", api_v1)
321            .merge(advanced_protocols::router())
322            .with_state(state.clone());
323
324        // Add middleware layers
325        let middleware_stack = ServiceBuilder::new()
326            .layer(axum_middleware::from_fn(middleware::timeout_middleware))
327            .layer(axum_middleware::from_fn(
328                middleware::security_headers_middleware,
329            ))
330            .layer(axum_middleware::from_fn({
331                let state = state.clone();
332                move |request, next| {
333                    let state = state.clone();
334                    async move {
335                        middleware::rate_limit_middleware_with_state(state, request, next).await
336                    }
337                }
338            }))
339            .layer(axum_middleware::from_fn(middleware::logging_middleware));
340
341        let router = if self.config.cors.enabled {
342            if self.config.cors.allowed_origins.is_empty() {
343                tracing::warn!(
344                    "SECURITY/CORS: CORS is enabled but allowed_origins is empty. All cross-origin requests will be rejected! Disable CORS or add allowed origins."
345                );
346            }
347
348            let header_origins: Vec<axum::http::HeaderValue> = self
349                .config
350                .cors
351                .allowed_origins
352                .iter()
353                .filter_map(|o| o.parse::<axum::http::HeaderValue>().ok())
354                .collect();
355
356            if header_origins.is_empty() && !self.config.cors.allowed_origins.is_empty() {
357                tracing::warn!(
358                    "CORS: none of the configured allowed_origins could be parsed as valid HTTP \
359                     header values; cross-origin requests will be rejected"
360                );
361            }
362
363            let allow_origin = tower_http::cors::AllowOrigin::list(header_origins);
364
365            let allowed_methods: Vec<Method> = self
366                .config
367                .cors
368                .allowed_methods
369                .iter()
370                .filter_map(|m| m.parse::<Method>().ok())
371                .collect();
372
373            let allowed_headers: Vec<axum::http::HeaderName> = self
374                .config
375                .cors
376                .allowed_headers
377                .iter()
378                .filter_map(|h| h.parse::<axum::http::HeaderName>().ok())
379                .collect();
380
381            router.layer(
382                CorsLayer::new()
383                    .allow_origin(allow_origin)
384                    .allow_methods(allowed_methods)
385                    .allow_headers(allowed_headers)
386                    .max_age(std::time::Duration::from_secs(
387                        self.config.cors.max_age_secs as u64,
388                    )),
389            )
390        } else {
391            router
392        };
393
394        let router = if self.config.enable_tracing {
395            router.layer(TraceLayer::new_for_http())
396        } else {
397            router
398        };
399
400        Ok(router
401            .layer(middleware_stack)
402            .layer(DefaultBodyLimit::max(self.config.max_body_size)))
403    }
404
405    /// Start the API server
406    pub async fn start(&self) -> Result<(), Box<dyn std::error::Error>> {
407        let app = self.build_router().await?;
408
409        let addr = SocketAddr::new(self.config.host.parse()?, self.config.port);
410
411        info!("🚀 AuthFramework API server starting on http://{}", addr);
412        info!("📖 API documentation available at http://{}/docs", addr);
413        info!(
414            "📘 OpenAPI JSON available at http://{}/api/openapi.json",
415            addr
416        );
417        info!("🏥 Health check available at http://{}/health", addr);
418        info!("📊 Metrics available at http://{}/metrics", addr);
419
420        let listener = tokio::net::TcpListener::bind(addr).await?;
421        axum::serve(listener, app).await?;
422
423        Ok(())
424    }
425
426    /// Get server configuration
427    pub fn config(&self) -> &ApiServerConfig {
428        &self.config
429    }
430
431    /// Get server address
432    pub fn address(&self) -> String {
433        format!("{}:{}", self.config.host, self.config.port)
434    }
435}
436
437/// Create a basic API server with default configuration
438pub async fn create_api_server(auth_framework: Arc<AuthFramework>) -> ApiServer {
439    ApiServer::new(auth_framework)
440}
441
442/// Create an API server with custom host and port
443pub async fn create_api_server_with_address(
444    auth_framework: Arc<AuthFramework>,
445    host: impl Into<String>,
446    port: u16,
447) -> ApiServer {
448    let config = ApiServerConfig {
449        host: host.into(),
450        port,
451        ..Default::default()
452    };
453    ApiServer::with_config(auth_framework, config)
454}
455
456#[cfg(test)]
457mod tests {
458    use super::*;
459    use crate::storage::memory::InMemoryStorage;
460    use crate::{AuthConfig, AuthFramework};
461    use axum::body::Body;
462    use axum::http::{Request, StatusCode};
463    use tower::ServiceExt;
464
465    async fn create_test_api_server() -> ApiServer {
466        let _storage = Arc::new(InMemoryStorage::new());
467        let config = AuthConfig::default();
468        let auth_framework = Arc::new(AuthFramework::new(config));
469        ApiServer::new(auth_framework)
470    }
471
472    #[tokio::test]
473    async fn test_health_endpoint() {
474        let api_server = create_test_api_server().await;
475        let router = api_server.build_router().await.unwrap();
476
477        let request = Request::builder()
478            .uri("/api/v1/health")
479            .method("GET")
480            .body(Body::empty())
481            .unwrap();
482
483        let response = router.oneshot(request).await.unwrap();
484        assert_eq!(response.status(), StatusCode::OK);
485    }
486
487    #[tokio::test]
488    async fn test_auth_required_endpoints() {
489        let api_server = create_test_api_server().await;
490        let router = api_server.build_router().await.unwrap();
491
492        let request = Request::builder()
493            .uri("/api/v1/users/profile")
494            .method("GET")
495            .body(Body::empty())
496            .unwrap();
497
498        let response = router.oneshot(request).await.unwrap();
499        // Protected endpoint should reject request without auth
500        assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
501    }
502
503    #[tokio::test]
504    async fn test_cors_headers() {
505        let config = AuthConfig::default();
506        let auth_framework = Arc::new(AuthFramework::new(config));
507        let api_config = ApiServerConfig {
508            cors: crate::config::CorsConfig {
509                enabled: true,
510                allowed_origins: vec!["http://localhost:3000".to_string()],
511                ..crate::config::CorsConfig::default()
512            },
513            ..ApiServerConfig::default()
514        };
515        let api_server = ApiServer::with_config(auth_framework, api_config);
516        let router = api_server.build_router().await.unwrap();
517
518        let request = Request::builder()
519            .uri("/api/v1/health")
520            .method("GET")
521            .header("Origin", "http://localhost:3000")
522            .body(Body::empty())
523            .unwrap();
524
525        let response = router.oneshot(request).await.unwrap();
526        assert_eq!(response.status(), StatusCode::OK);
527
528        // Check CORS headers are present when a matching Origin is sent
529        assert!(
530            response
531                .headers()
532                .contains_key("access-control-allow-origin")
533        );
534    }
535
536    #[tokio::test]
537    async fn test_readiness_endpoint() {
538        let api_server = create_test_api_server().await;
539        let router = api_server.build_router().await.unwrap();
540
541        let request = Request::builder()
542            .uri("/api/v1/readiness")
543            .method("GET")
544            .body(Body::empty())
545            .unwrap();
546
547        let response = router.oneshot(request).await.unwrap();
548        // Should be OK or SERVICE_UNAVAILABLE, not a 404
549        assert!(
550            response.status() == StatusCode::OK
551                || response.status() == StatusCode::SERVICE_UNAVAILABLE
552        );
553    }
554
555    #[tokio::test]
556    async fn test_liveness_endpoint() {
557        let api_server = create_test_api_server().await;
558        let router = api_server.build_router().await.unwrap();
559
560        let request = Request::builder()
561            .uri("/api/v1/liveness")
562            .method("GET")
563            .body(Body::empty())
564            .unwrap();
565
566        let response = router.oneshot(request).await.unwrap();
567        assert_eq!(response.status(), StatusCode::OK);
568    }
569
570    #[tokio::test]
571    async fn test_metrics_endpoint() {
572        let api_server = create_test_api_server().await;
573        let router = api_server.build_router().await.unwrap();
574
575        let request = Request::builder()
576            .uri("/api/v1/metrics")
577            .method("GET")
578            .body(Body::empty())
579            .unwrap();
580
581        let response = router.oneshot(request).await.unwrap();
582        assert_eq!(response.status(), StatusCode::OK);
583    }
584
585    #[tokio::test]
586    async fn test_nonexistent_route_returns_404() {
587        let api_server = create_test_api_server().await;
588        let router = api_server.build_router().await.unwrap();
589
590        let request = Request::builder()
591            .uri("/api/v1/this-does-not-exist")
592            .method("GET")
593            .body(Body::empty())
594            .unwrap();
595
596        let response = router.oneshot(request).await.unwrap();
597        assert_eq!(response.status(), StatusCode::NOT_FOUND);
598    }
599
600    #[tokio::test]
601    async fn test_login_with_empty_body() {
602        let api_server = create_test_api_server().await;
603        let router = api_server.build_router().await.unwrap();
604
605        let request = Request::builder()
606            .uri("/api/v1/auth/login")
607            .method("POST")
608            .header("Content-Type", "application/json")
609            .body(Body::from("{}"))
610            .unwrap();
611
612        let response = router.oneshot(request).await.unwrap();
613        // Should return an error (400 or 422), not 200
614        assert_ne!(response.status(), StatusCode::OK);
615    }
616
617    #[tokio::test]
618    async fn test_register_endpoint_accessible() {
619        let api_server = create_test_api_server().await;
620        let router = api_server.build_router().await.unwrap();
621
622        let body = serde_json::json!({
623            "username": "newuser",
624            "password": "StrongP@ssw0rd123!",
625            "email": "test@example.com"
626        });
627
628        let request = Request::builder()
629            .uri("/api/v1/auth/register")
630            .method("POST")
631            .header("Content-Type", "application/json")
632            .body(Body::from(serde_json::to_string(&body).unwrap()))
633            .unwrap();
634
635        let response = router.oneshot(request).await.unwrap();
636        // It should process the request (not 404 or 405)
637        assert_ne!(response.status(), StatusCode::NOT_FOUND);
638        assert_ne!(response.status(), StatusCode::METHOD_NOT_ALLOWED);
639    }
640
641    #[tokio::test]
642    async fn test_server_config_defaults() {
643        let config = ApiServerConfig::default();
644        assert_eq!(config.host, "127.0.0.1");
645        assert_eq!(config.port, 8080);
646        assert!(!config.enable_cors());
647    }
648
649    #[tokio::test]
650    async fn test_server_address() {
651        let api_server = create_test_api_server().await;
652        assert_eq!(api_server.address(), "127.0.0.1:8080");
653    }
654
655    #[tokio::test]
656    async fn test_create_api_server_with_address() {
657        let config = AuthConfig::default();
658        let auth_framework = Arc::new(AuthFramework::new(config));
659        let api_server = create_api_server_with_address(auth_framework, "0.0.0.0", 8080).await;
660        assert_eq!(api_server.address(), "0.0.0.0:8080");
661    }
662
663    #[tokio::test]
664    async fn test_admin_endpoints_require_auth() {
665        let api_server = create_test_api_server().await;
666        let router = api_server.build_router().await.unwrap();
667
668        let request = Request::builder()
669            .uri("/api/v1/admin/users")
670            .method("GET")
671            .body(Body::empty())
672            .unwrap();
673
674        let response = router.oneshot(request).await.unwrap();
675        assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
676    }
677
678    #[tokio::test]
679    async fn test_security_headers_present() {
680        let api_server = create_test_api_server().await;
681        let router = api_server.build_router().await.unwrap();
682
683        let request = Request::builder()
684            .uri("/api/v1/health")
685            .method("GET")
686            .body(Body::empty())
687            .unwrap();
688
689        let response = router.oneshot(request).await.unwrap();
690        assert_eq!(response.status(), StatusCode::OK);
691
692        let headers = response.headers();
693        assert_eq!(
694            headers
695                .get("x-content-type-options")
696                .map(|v| v.to_str().unwrap()),
697            Some("nosniff")
698        );
699        assert_eq!(
700            headers.get("x-frame-options").map(|v| v.to_str().unwrap()),
701            Some("DENY")
702        );
703    }
704}