Skip to main content

auth_framework/api/
admin.rs

1//! Administrative API Endpoints
2//!
3//! Handles user management, system configuration, and admin operations.
4//!
5//! # Security Model
6//!
7//! **Every handler in this module must independently verify the caller holds the
8//! `admin` role** via [`verify_admin_role`].  There is no middleware-level admin
9//! guard on these routes — authorization is enforced per-handler so that
10//! non-admin error paths can still return proper 401/403 responses.
11//!
12//! When adding new admin endpoints, always call `verify_admin_role(&auth_token)?`
13//! immediately after token validation.
14
15use crate::api::{
16    ApiResponse, ApiState, extract_bearer_token, responses::Pagination, validate_api_token,
17};
18use crate::tokens::AuthToken;
19use axum::{
20    Json,
21    extract::{Path, Query, State},
22    http::HeaderMap,
23};
24use serde::{Deserialize, Serialize};
25
26// ---------------------------------------------------------------------------
27// Helper: verify the authenticated token carries the admin role
28// ---------------------------------------------------------------------------
29/// Checks that `auth_token` carries the `admin` role. Returns `Ok(())` on
30/// success or an `ApiResponse::forbidden_typed()` error suitable for early
31/// return from any admin handler.
32#[allow(
33    clippy::result_large_err,
34    reason = "the Err arm is the API response an admin handler returns as-is; boxing it would change every caller"
35)]
36fn verify_admin_role<T: Serialize>(auth_token: &AuthToken) -> Result<(), ApiResponse<T>> {
37    if auth_token.roles.contains("admin") {
38        Ok(())
39    } else {
40        Err(ApiResponse::<T>::forbidden_typed())
41    }
42}
43
44// ---------------------------------------------------------------------------
45// Helper: load all user IDs from the global index
46// ---------------------------------------------------------------------------
47async fn load_user_ids(storage: &std::sync::Arc<dyn crate::storage::AuthStorage>) -> Vec<String> {
48    match storage.get_kv("users:index").await {
49        Ok(Some(bytes)) => serde_json::from_slice(&bytes).unwrap_or_default(),
50        _ => vec![],
51    }
52}
53
54// ---------------------------------------------------------------------------
55// Helper: load a single user record by user_id and convert to UserListItem
56// ---------------------------------------------------------------------------
57async fn load_user_item(
58    storage: &std::sync::Arc<dyn crate::storage::AuthStorage>,
59    user_id: &str,
60) -> Option<UserListItem> {
61    let key = format!("user:{}", user_id);
62    let bytes = storage.get_kv(&key).await.ok()??;
63    let data: serde_json::Value = serde_json::from_slice(&bytes).ok()?;
64
65    let username = data["username"].as_str()?.to_string();
66    let email = data["email"].as_str().unwrap_or("").to_string();
67    let roles: Vec<String> = data["roles"]
68        .as_array()
69        .map(|arr| {
70            arr.iter()
71                .filter_map(|v| v.as_str().map(|s| s.to_string()))
72                .collect()
73        })
74        .unwrap_or_else(|| vec!["user".to_string()]);
75    let active = data["active"].as_bool().unwrap_or(true);
76    let created_at = data["created_at"].as_str().unwrap_or("").to_string();
77    let last_login = data["last_login"].as_str().map(|s| s.to_string());
78
79    Some(UserListItem {
80        id: user_id.to_string(),
81        username,
82        email,
83        roles,
84        active,
85        created_at,
86        last_login,
87    })
88}
89
90/// User list item
91#[derive(Debug, Serialize)]
92pub struct UserListItem {
93    pub id: String,
94    pub username: String,
95    pub email: String,
96    pub roles: Vec<String>,
97    pub active: bool,
98    pub created_at: String,
99    pub last_login: Option<String>,
100}
101
102/// User list response
103#[derive(Debug, Serialize)]
104pub struct UserListResponse {
105    pub users: Vec<UserListItem>,
106    pub pagination: Pagination,
107}
108
109/// User list query parameters
110#[derive(Debug, Deserialize)]
111pub struct UserListQuery {
112    #[serde(default = "default_page")]
113    pub page: u32,
114    #[serde(default = "default_limit")]
115    pub limit: u32,
116    #[serde(default)]
117    pub search: Option<String>,
118    #[serde(default)]
119    pub role: Option<String>,
120    #[serde(default)]
121    pub active: Option<bool>,
122}
123
124fn default_page() -> u32 {
125    1
126}
127fn default_limit() -> u32 {
128    20
129}
130
131/// Create user request
132#[derive(Deserialize)]
133pub struct CreateUserRequest {
134    pub username: String,
135    pub password: String,
136    pub email: String,
137    #[serde(default)]
138    pub first_name: Option<String>,
139    #[serde(default)]
140    pub last_name: Option<String>,
141    #[serde(default)]
142    pub roles: Vec<String>,
143    #[serde(default = "default_active")]
144    pub active: bool,
145}
146
147impl std::fmt::Debug for CreateUserRequest {
148    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
149        let mut d = f.debug_struct("CreateUserRequest");
150        d.field("username", &self.username);
151        d.field("password", &crate::utils::redact::redacted(&self.password));
152        d.field("email", &self.email);
153        d.field("first_name", &self.first_name);
154        d.field("last_name", &self.last_name);
155        d.field("roles", &self.roles);
156        d.field("active", &self.active);
157        d.finish()
158    }
159}
160
161fn default_active() -> bool {
162    true
163}
164
165/// Update user roles request
166#[derive(Debug, Deserialize)]
167pub struct UpdateUserRolesRequest {
168    pub roles: Vec<String>,
169}
170
171/// System stats response
172#[derive(Debug, Serialize)]
173pub struct SystemStats {
174    pub total_users: u64,
175    pub active_sessions: u64,
176    pub total_tokens: u64,
177    pub failed_logins_24h: u64,
178    pub system_uptime: String,
179    pub memory_usage: String,
180    pub cpu_usage: String,
181}
182
183/// GET /admin/users
184/// List all users (admin only)
185pub async fn list_users(
186    State(state): State<ApiState>,
187    headers: HeaderMap,
188    Query(query): Query<UserListQuery>,
189) -> ApiResponse<UserListResponse> {
190    match extract_bearer_token(&headers) {
191        Some(token) => match validate_api_token(&state.auth_framework, &token).await {
192            Ok(auth_token) => {
193                if let Err(resp) = verify_admin_role::<UserListResponse>(&auth_token) {
194                    return resp;
195                }
196
197                let storage = state.auth_framework.storage();
198                let all_ids = load_user_ids(&storage).await;
199
200                let mut users: Vec<UserListItem> = Vec::new();
201                for id in &all_ids {
202                    if let Some(item) = load_user_item(&storage, id).await {
203                        if let Some(ref search) = query.search {
204                            let s = search.to_lowercase();
205                            if !item.username.to_lowercase().contains(&s)
206                                && !item.email.to_lowercase().contains(&s)
207                            {
208                                continue;
209                            }
210                        }
211                        if let Some(ref role) = query.role
212                            && !item.roles.contains(role)
213                        {
214                            continue;
215                        }
216                        if let Some(filter_active) = query.active
217                            && item.active != filter_active
218                        {
219                            continue;
220                        }
221                        users.push(item);
222                    }
223                }
224
225                let total_users = users.len() as u64;
226                let page = if query.page == 0 { 1 } else { query.page };
227                let limit = if query.limit == 0 {
228                    20
229                } else {
230                    query.limit.min(100)
231                };
232                let offset = ((page - 1) * limit) as usize;
233                let total_pages = ((total_users as f64) / (limit as f64)).ceil() as u32;
234                let total_pages = if total_pages == 0 { 1 } else { total_pages };
235
236                let page_users: Vec<UserListItem> = users
237                    .into_iter()
238                    .skip(offset)
239                    .take(limit as usize)
240                    .collect();
241
242                let pagination = Pagination {
243                    page,
244                    limit,
245                    total: total_users,
246                    pages: total_pages,
247                };
248
249                ApiResponse::success(UserListResponse {
250                    users: page_users,
251                    pagination,
252                })
253            }
254            Err(e) => {
255                let error_response = ApiResponse::<()>::from(e);
256                ApiResponse::<UserListResponse> {
257                    success: error_response.success,
258                    data: None,
259                    error: error_response.error,
260                    message: error_response.message,
261                }
262            }
263        },
264        None => ApiResponse::<UserListResponse>::unauthorized_typed(),
265    }
266}
267
268/// POST /admin/users
269/// Create new user (admin only)
270pub async fn create_user(
271    State(state): State<ApiState>,
272    headers: HeaderMap,
273    Json(req): Json<CreateUserRequest>,
274) -> ApiResponse<UserListItem> {
275    // Validate input
276    if req.username.is_empty() || req.password.is_empty() || req.email.is_empty() {
277        return ApiResponse::<UserListItem>::validation_error_typed(
278            "Username, password, and email are required",
279        );
280    }
281
282    // Validate username format — same rules as the public registration endpoint.
283    if crate::utils::validation::validate_username(&req.username).is_err() {
284        return ApiResponse::<UserListItem>::validation_error_typed(
285            "Invalid username: must be 3-50 characters, start with a letter, and contain only letters, numbers, underscores, or hyphens",
286        );
287    }
288
289    // Enforce length limits on optional name fields.
290    if req.first_name.as_deref().is_some_and(|n| n.len() > 100) {
291        return ApiResponse::<UserListItem>::validation_error_typed(
292            "First name must be 100 characters or fewer",
293        );
294    }
295    if req.last_name.as_deref().is_some_and(|n| n.len() > 100) {
296        return ApiResponse::<UserListItem>::validation_error_typed(
297            "Last name must be 100 characters or fewer",
298        );
299    }
300
301    // Validate email format for consistency with the public registration endpoint.
302    if crate::utils::validation::validate_email(&req.email).is_err() {
303        return ApiResponse::<UserListItem>::validation_error_typed("Invalid email format");
304    }
305
306    // SECURITY (M-12): Use the same password validation as the public register endpoint
307    // so that admin-created accounts cannot bypass complexity requirements.
308    if let Err(e) = crate::utils::validation::validate_password(&req.password) {
309        // Return a generic message to avoid leaking internal validation rule details.
310        tracing::warn!("Admin create_user password validation failed: {e}");
311        return ApiResponse::<UserListItem>::validation_error_typed(
312            "Password does not meet complexity requirements",
313        );
314    }
315
316    match extract_bearer_token(&headers) {
317        Some(token) => {
318            match validate_api_token(&state.auth_framework, &token).await {
319                Ok(auth_token) => {
320                    // Check admin permissions
321                    if let Err(resp) = verify_admin_role(&auth_token) {
322                        return resp;
323                    }
324
325                    match state
326                        .auth_framework
327                        .register_user(&req.username, &req.email, &req.password)
328                        .await
329                    {
330                        Ok(user_id) => {
331                            if !(req.roles.is_empty()
332                                || req.roles.len() == 1 && req.roles[0] == "user")
333                                && let Err(e) = state
334                                    .auth_framework
335                                    .update_user_roles(&user_id, &req.roles)
336                                    .await
337                            {
338                                tracing::warn!(
339                                    "Failed to set roles for new user {}: {}",
340                                    user_id,
341                                    e
342                                );
343                            }
344                            if !req.active
345                                && let Err(e) =
346                                    state.auth_framework.set_user_active(&user_id, false).await
347                            {
348                                tracing::warn!("Failed to deactivate new user {}: {}", user_id, e);
349                            }
350                            let new_user = UserListItem {
351                                id: user_id.clone(),
352                                username: req.username.clone(),
353                                email: req.email.clone(),
354                                roles: if req.roles.is_empty() {
355                                    vec!["user".to_string()]
356                                } else {
357                                    req.roles.clone()
358                                },
359                                active: req.active,
360                                created_at: chrono::Utc::now().to_rfc3339(),
361                                last_login: None,
362                            };
363                            tracing::info!("Admin created user: {} ({})", req.username, user_id);
364                            ApiResponse::success(new_user)
365                        }
366                        Err(e) => {
367                            let error_response = ApiResponse::<()>::from(e);
368                            ApiResponse::<UserListItem> {
369                                success: error_response.success,
370                                data: None,
371                                error: error_response.error,
372                                message: error_response.message,
373                            }
374                        }
375                    }
376                }
377                Err(e) => {
378                    // Convert AuthError to typed response
379                    let error_response = ApiResponse::<()>::from(e);
380                    ApiResponse::<UserListItem> {
381                        success: error_response.success,
382                        data: None,
383                        error: error_response.error,
384                        message: error_response.message,
385                    }
386                }
387            }
388        }
389        None => ApiResponse::<UserListItem>::unauthorized_typed(),
390    }
391}
392
393/// PUT /admin/users/{user_id}/roles
394/// Update user roles (admin only)
395pub async fn update_user_roles(
396    State(state): State<ApiState>,
397    headers: HeaderMap,
398    Path(user_id): Path<String>,
399    Json(req): Json<UpdateUserRolesRequest>,
400) -> ApiResponse<()> {
401    match extract_bearer_token(&headers) {
402        Some(token) => {
403            match validate_api_token(&state.auth_framework, &token).await {
404                Ok(auth_token) => {
405                    // Check admin permissions
406                    if let Err(resp) = verify_admin_role(&auth_token) {
407                        return resp;
408                    }
409
410                    match state
411                        .auth_framework
412                        .update_user_roles(&user_id, &req.roles)
413                        .await
414                    {
415                        Ok(()) => {
416                            tracing::info!(
417                                "Admin updated roles for user {}: {:?}",
418                                user_id,
419                                req.roles
420                            );
421                            ApiResponse::<()>::ok_with_message("User roles updated successfully")
422                        }
423                        Err(e) => e.into(),
424                    }
425                }
426                Err(e) => e.into(),
427            }
428        }
429        None => ApiResponse::unauthorized(),
430    }
431}
432
433/// DELETE /admin/users/{user_id}
434/// Delete user (admin only)
435pub async fn delete_user(
436    State(state): State<ApiState>,
437    headers: HeaderMap,
438    Path(user_id): Path<String>,
439) -> ApiResponse<()> {
440    match extract_bearer_token(&headers) {
441        Some(token) => {
442            match validate_api_token(&state.auth_framework, &token).await {
443                Ok(auth_token) => {
444                    // Check admin permissions
445                    if let Err(resp) = verify_admin_role(&auth_token) {
446                        return resp;
447                    }
448
449                    // Prevent self-deletion
450                    if auth_token.user_id == user_id {
451                        return ApiResponse::validation_error("Cannot delete your own account");
452                    }
453
454                    match state.auth_framework.get_username_by_id(&user_id).await {
455                        Ok(username) => match state.auth_framework.delete_user(&username).await {
456                            Ok(()) => {
457                                tracing::info!("Admin deleted user: {} ({})", username, user_id);
458                                ApiResponse::<()>::ok_with_message("User deleted successfully")
459                            }
460                            Err(e) => e.into(),
461                        },
462                        Err(e) => e.into(),
463                    }
464                }
465                Err(e) => e.into(),
466            }
467        }
468        None => ApiResponse::unauthorized(),
469    }
470}
471
472/// PUT /admin/users/{user_id}/activate
473/// Activate/deactivate user (admin only)
474#[derive(Debug, Deserialize)]
475pub struct ActivateUserRequest {
476    pub active: bool,
477}
478
479pub async fn activate_user(
480    State(state): State<ApiState>,
481    headers: HeaderMap,
482    Path(user_id): Path<String>,
483    Json(req): Json<ActivateUserRequest>,
484) -> ApiResponse<()> {
485    match extract_bearer_token(&headers) {
486        Some(token) => {
487            match validate_api_token(&state.auth_framework, &token).await {
488                Ok(auth_token) => {
489                    // Check admin permissions
490                    if !auth_token.roles.contains("admin") {
491                        return ApiResponse::forbidden();
492                    }
493
494                    match state
495                        .auth_framework
496                        .set_user_active(&user_id, req.active)
497                        .await
498                    {
499                        Ok(()) => {
500                            let action = if req.active {
501                                "activated"
502                            } else {
503                                "deactivated"
504                            };
505                            tracing::info!("Admin {} user {}", action, user_id);
506                            ApiResponse::<()>::ok_with_message(format!(
507                                "User {} successfully",
508                                action
509                            ))
510                        }
511                        Err(e) => e.into(),
512                    }
513                }
514                Err(e) => e.into(),
515            }
516        }
517        None => ApiResponse::unauthorized(),
518    }
519}
520
521/// GET /admin/stats
522/// Get system statistics (admin only)
523pub async fn get_system_stats(
524    State(state): State<ApiState>,
525    headers: HeaderMap,
526) -> ApiResponse<SystemStats> {
527    match extract_bearer_token(&headers) {
528        Some(token) => {
529            match validate_api_token(&state.auth_framework, &token).await {
530                Ok(auth_token) => {
531                    // Check admin permissions
532                    if !auth_token.roles.contains("admin") {
533                        return ApiResponse::forbidden_typed();
534                    }
535
536                    let storage = state.auth_framework.storage();
537                    let total_users = load_user_ids(&storage).await.len() as u64;
538                    let active_sessions = storage.count_active_sessions().await.unwrap_or(0);
539
540                    // Collect real system metrics via the sysinfo crate.
541                    let (system_uptime, memory_usage, cpu_usage) = {
542                        use sysinfo::System;
543                        let mut sys = System::new();
544                        sys.refresh_memory();
545                        sys.refresh_cpu_usage();
546                        let uptime_secs = System::uptime();
547                        let hours = uptime_secs / 3600;
548                        let mins = (uptime_secs % 3600) / 60;
549                        let secs = uptime_secs % 60;
550                        let uptime_str = format!("{hours}h {mins}m {secs}s");
551                        let used_mb = sys.used_memory() as f64 / 1_048_576.0;
552                        let total_mb = sys.total_memory() as f64 / 1_048_576.0;
553                        let mem_str = format!("{used_mb:.1} MB / {total_mb:.1} MB");
554                        let cpu_str = format!("{:.1}%", sys.global_cpu_usage());
555                        (uptime_str, mem_str, cpu_str)
556                    };
557
558                    let stats = SystemStats {
559                        total_users,
560                        active_sessions,
561                        // token count: proxy active sessions — each session
562                        // corresponds to at least one issued JWT token.
563                        total_tokens: active_sessions,
564                        // Persistent audit log not wired; cannot derive 24h
565                        // failure count from in-memory state alone.
566                        failed_logins_24h: 0,
567                        system_uptime,
568                        memory_usage,
569                        cpu_usage,
570                    };
571
572                    ApiResponse::success(stats)
573                }
574                Err(e) => {
575                    let error_response = ApiResponse::<()>::from(e);
576                    ApiResponse::<SystemStats> {
577                        success: error_response.success,
578                        data: None,
579                        error: error_response.error,
580                        message: error_response.message,
581                    }
582                }
583            }
584        }
585        None => ApiResponse::unauthorized_typed(),
586    }
587}
588
589/// GET /admin/audit-logs
590/// Get audit logs (admin only)
591#[derive(Debug, Serialize)]
592pub struct AuditLogEntry {
593    pub id: String,
594    pub timestamp: String,
595    pub user_id: String,
596    pub action: String,
597    pub resource: String,
598    pub ip_address: String,
599    pub user_agent: String,
600    pub result: String,
601    /// Risk level of the event: "low", "medium", "high", or "critical".
602    pub risk_level: String,
603    /// Outcome: "success", "failure", "partial", or "unknown".
604    pub outcome: String,
605    /// Correlation ID linking related events across the same authentication flow.
606    #[serde(skip_serializing_if = "Option::is_none")]
607    pub correlation_id: Option<String>,
608}
609
610#[derive(Debug, Serialize)]
611pub struct AuditLogResponse {
612    pub logs: Vec<AuditLogEntry>,
613    pub pagination: Pagination,
614}
615
616#[derive(Debug, Deserialize)]
617pub struct AuditLogQuery {
618    #[serde(default = "default_page")]
619    pub page: u32,
620    #[serde(default = "default_limit")]
621    pub limit: u32,
622    #[serde(default)]
623    pub user_id: Option<String>,
624    #[serde(default)]
625    pub action: Option<String>,
626    #[serde(default)]
627    pub start_date: Option<String>,
628    #[serde(default)]
629    pub end_date: Option<String>,
630    /// Filter by risk level: "low", "medium", "high", or "critical".
631    #[serde(default)]
632    pub risk_level: Option<String>,
633    /// Filter by outcome: "success" or "failure".
634    #[serde(default)]
635    pub outcome: Option<String>,
636    /// Filter by correlation ID to trace a single authentication flow.
637    #[serde(default)]
638    pub correlation_id: Option<String>,
639    /// Filter by client IP address.
640    #[serde(default)]
641    pub ip_address: Option<String>,
642}
643
644pub async fn get_audit_logs(
645    State(state): State<ApiState>,
646    headers: HeaderMap,
647    Query(query): Query<AuditLogQuery>,
648) -> ApiResponse<AuditLogResponse> {
649    match extract_bearer_token(&headers) {
650        Some(token) => {
651            match validate_api_token(&state.auth_framework, &token).await {
652                Ok(auth_token) => {
653                    // Check admin permissions
654                    if !auth_token.roles.contains("admin") {
655                        return ApiResponse::forbidden_typed();
656                    }
657
658                    let page = if query.page == 0 { 1 } else { query.page };
659                    let limit = if query.limit == 0 {
660                        20
661                    } else {
662                        query.limit.min(100)
663                    };
664                    let offset = ((page - 1) * limit) as usize;
665                    let fetch_limit = offset + limit as usize;
666
667                    match state
668                        .auth_framework
669                        .get_permission_audit_logs(
670                            query.user_id.as_deref(),
671                            query.action.as_deref(),
672                            None,
673                            Some(fetch_limit),
674                        )
675                        .await
676                    {
677                        Ok(all_logs) => {
678                            // Parse and enrich all log entries first so filtering is applied
679                            // before pagination.
680                            let mut parsed: Vec<AuditLogEntry> = all_logs
681                                .into_iter()
682                                .enumerate()
683                                .map(|(i, log_str)| {
684                                    let (ts, rest) = log_str
685                                        .strip_prefix('[')
686                                        .and_then(|s| s.split_once(']'))
687                                        .map(|(t, r)| (t.trim().to_string(), r.trim().to_string()))
688                                        .unwrap_or_else(|| {
689                                            ("unknown".to_string(), log_str.clone())
690                                        });
691                                    let uid = rest
692                                        .split_whitespace()
693                                        .find(|w| w.starts_with("user="))
694                                        .and_then(|w| w.strip_prefix("user="))
695                                        .unwrap_or("system")
696                                        .to_string();
697                                    let raw_outcome = rest
698                                        .split_whitespace()
699                                        .find(|w| w.starts_with("outcome="))
700                                        .and_then(|w| w.strip_prefix("outcome="))
701                                        .unwrap_or("unknown")
702                                        .to_string();
703                                    let ip = rest
704                                        .split_whitespace()
705                                        .find(|w| w.starts_with("ip="))
706                                        .and_then(|w| w.strip_prefix("ip="))
707                                        .unwrap_or("")
708                                        .to_string();
709                                    let ua = rest
710                                        .split_whitespace()
711                                        .find(|w| w.starts_with("ua="))
712                                        .and_then(|w| w.strip_prefix("ua="))
713                                        .unwrap_or("")
714                                        .to_string();
715                                    let corr = rest
716                                        .split_whitespace()
717                                        .find(|w| w.starts_with("correlation_id="))
718                                        .and_then(|w| w.strip_prefix("correlation_id="))
719                                        .map(str::to_string);
720                                    // Derive outcome category and risk level from the raw
721                                    // outcome token present in the log line.
722                                    let outcome = if raw_outcome.contains("success") {
723                                        "success"
724                                    } else if raw_outcome.contains("fail")
725                                        || raw_outcome.contains("error")
726                                    {
727                                        "failure"
728                                    } else {
729                                        "unknown"
730                                    };
731                                    // Risk level: failures + high index numbers treated as
732                                    // higher risk for demonstration; real implementations
733                                    // should propagate risk from the authentication path.
734                                    let risk_level = if outcome == "failure" {
735                                        "medium"
736                                    } else {
737                                        "low"
738                                    };
739                                    AuditLogEntry {
740                                        id: format!("audit_{}", i),
741                                        timestamp: ts,
742                                        user_id: uid,
743                                        action: rest,
744                                        resource: String::new(),
745                                        ip_address: ip,
746                                        user_agent: ua,
747                                        result: raw_outcome,
748                                        risk_level: risk_level.to_string(),
749                                        outcome: outcome.to_string(),
750                                        correlation_id: corr,
751                                    }
752                                })
753                                .collect();
754
755                            // Apply optional client-side filters on the enriched entries.
756                            if let Some(ref filter_ip) = query.ip_address {
757                                parsed.retain(|e| e.ip_address.contains(filter_ip.as_str()));
758                            }
759                            if let Some(ref filter_risk) = query.risk_level {
760                                parsed.retain(|e| e.risk_level == filter_risk.as_str());
761                            }
762                            if let Some(ref filter_outcome) = query.outcome {
763                                parsed.retain(|e| e.outcome == filter_outcome.as_str());
764                            }
765                            if let Some(ref filter_corr) = query.correlation_id {
766                                parsed.retain(|e| {
767                                    e.correlation_id.as_deref() == Some(filter_corr.as_str())
768                                });
769                            }
770
771                            let total = parsed.len() as u64;
772                            let total_pages = ((total as f64) / (limit as f64)).ceil() as u32;
773                            let total_pages = if total_pages == 0 { 1 } else { total_pages };
774
775                            let logs: Vec<AuditLogEntry> = parsed
776                                .into_iter()
777                                .skip(offset)
778                                .take(limit as usize)
779                                .collect();
780
781                            ApiResponse::success(AuditLogResponse {
782                                logs,
783                                pagination: Pagination {
784                                    page,
785                                    limit,
786                                    total,
787                                    pages: total_pages,
788                                },
789                            })
790                        }
791                        Err(e) => {
792                            let error_response = ApiResponse::<()>::from(e);
793                            ApiResponse::<AuditLogResponse> {
794                                success: error_response.success,
795                                data: None,
796                                error: error_response.error,
797                                message: error_response.message,
798                            }
799                        }
800                    }
801                }
802                Err(e) => {
803                    let error_response = ApiResponse::<()>::from(e);
804                    ApiResponse::<AuditLogResponse> {
805                        success: error_response.success,
806                        data: None,
807                        error: error_response.error,
808                        message: error_response.message,
809                    }
810                }
811            }
812        }
813        None => ApiResponse::unauthorized_typed(),
814    }
815}
816
817/// Summary statistics returned by `GET /admin/audit-logs/stats`.
818#[derive(Debug, Serialize)]
819pub struct AuditLogStats {
820    /// Total events recorded in the last 24 hours.
821    pub total_events_24h: u64,
822    /// Failed login events in the last 24 hours.
823    pub failed_logins_24h: u64,
824    /// Successful login events in the last 24 hours.
825    pub successful_logins_24h: u64,
826    /// Events flagged as high-risk or critical in the last 24 hours.
827    pub high_risk_events_24h: u64,
828    /// Distinct user IDs seen in the last 24 hours.
829    pub unique_users_24h: u64,
830    /// Security alerts raised in the last 24 hours.
831    pub security_alerts_24h: u64,
832}
833
834/// GET /admin/audit-logs/stats
835///
836/// Returns aggregated audit-log statistics for the last 24 hours.
837/// Requires an admin bearer token.
838pub async fn get_audit_log_stats(
839    State(state): State<ApiState>,
840    headers: HeaderMap,
841) -> ApiResponse<AuditLogStats> {
842    match extract_bearer_token(&headers) {
843        Some(token) => match validate_api_token(&state.auth_framework, &token).await {
844            Ok(auth_token) => {
845                if !auth_token.roles.contains("admin") {
846                    return ApiResponse::forbidden_typed();
847                }
848
849                match state.auth_framework.get_security_audit_stats().await {
850                    Ok(sec_stats) => ApiResponse::success(AuditLogStats {
851                        total_events_24h: sec_stats.failed_logins_24h
852                            + sec_stats.successful_logins_24h
853                            + sec_stats.admin_actions_24h,
854                        failed_logins_24h: sec_stats.failed_logins_24h,
855                        successful_logins_24h: sec_stats.successful_logins_24h,
856                        high_risk_events_24h: sec_stats.security_alerts_24h,
857                        unique_users_24h: sec_stats.unique_users_24h,
858                        security_alerts_24h: sec_stats.security_alerts_24h,
859                    }),
860                    Err(e) => {
861                        let error_response = ApiResponse::<()>::from(e);
862                        ApiResponse::<AuditLogStats> {
863                            success: error_response.success,
864                            data: None,
865                            error: error_response.error,
866                            message: error_response.message,
867                        }
868                    }
869                }
870            }
871            Err(e) => {
872                let error_response = ApiResponse::<()>::from(e);
873                ApiResponse::<AuditLogStats> {
874                    success: error_response.success,
875                    data: None,
876                    error: error_response.error,
877                    message: error_response.message,
878                }
879            }
880        },
881        None => ApiResponse::unauthorized_typed(),
882    }
883}
884
885// ─── Admin configuration endpoints ──────────────────────────────────────────
886
887/// Response body for `GET /admin/config`.
888///
889/// Only runtime-mutable fields are exposed. Security-sensitive settings (JWT
890/// secret, signing algorithm, storage backend) are intentionally omitted.
891#[derive(Debug, Serialize)]
892pub struct AdminConfigView {
893    pub token_lifetime_secs: u64,
894    pub refresh_token_lifetime_secs: u64,
895    pub enable_multi_factor: bool,
896    pub rate_limiting_enabled: bool,
897    pub rate_limit_max_requests: u32,
898    pub rate_limit_window_secs: u64,
899    pub rate_limit_burst: u32,
900    pub min_password_length: usize,
901    pub require_password_complexity: bool,
902    pub secure_cookies: bool,
903    pub csrf_protection: bool,
904    pub session_timeout_secs: u64,
905    pub audit_enabled: bool,
906    pub audit_log_success: bool,
907    pub audit_log_failures: bool,
908    pub audit_log_permissions: bool,
909    pub audit_log_tokens: bool,
910}
911
912impl From<crate::config::RuntimeConfig> for AdminConfigView {
913    fn from(c: crate::config::RuntimeConfig) -> Self {
914        Self {
915            token_lifetime_secs: c.token_lifetime_secs,
916            refresh_token_lifetime_secs: c.refresh_token_lifetime_secs,
917            enable_multi_factor: c.enable_multi_factor,
918            rate_limiting_enabled: c.rate_limiting_enabled,
919            rate_limit_max_requests: c.rate_limit_max_requests,
920            rate_limit_window_secs: c.rate_limit_window_secs,
921            rate_limit_burst: c.rate_limit_burst,
922            min_password_length: c.min_password_length,
923            require_password_complexity: c.require_password_complexity,
924            secure_cookies: c.secure_cookies,
925            csrf_protection: c.csrf_protection,
926            session_timeout_secs: c.session_timeout_secs,
927            audit_enabled: c.audit_enabled,
928            audit_log_success: c.audit_log_success,
929            audit_log_failures: c.audit_log_failures,
930            audit_log_permissions: c.audit_log_permissions,
931            audit_log_tokens: c.audit_log_tokens,
932        }
933    }
934}
935
936/// Request body for `PUT /admin/config` — all fields optional.
937///
938/// Omitted fields retain their current values.  This enables partial updates
939/// (patch semantics) without the client needing to re-send unchanged settings.
940#[derive(Debug, Deserialize)]
941pub struct AdminConfigUpdate {
942    #[serde(default)]
943    pub token_lifetime_secs: Option<u64>,
944    #[serde(default)]
945    pub refresh_token_lifetime_secs: Option<u64>,
946    #[serde(default)]
947    pub enable_multi_factor: Option<bool>,
948    #[serde(default)]
949    pub rate_limiting_enabled: Option<bool>,
950    #[serde(default)]
951    pub rate_limit_max_requests: Option<u32>,
952    #[serde(default)]
953    pub rate_limit_window_secs: Option<u64>,
954    #[serde(default)]
955    pub rate_limit_burst: Option<u32>,
956    #[serde(default)]
957    pub min_password_length: Option<usize>,
958    #[serde(default)]
959    pub require_password_complexity: Option<bool>,
960    #[serde(default)]
961    pub secure_cookies: Option<bool>,
962    #[serde(default)]
963    pub csrf_protection: Option<bool>,
964    #[serde(default)]
965    pub session_timeout_secs: Option<u64>,
966    #[serde(default)]
967    pub audit_enabled: Option<bool>,
968    #[serde(default)]
969    pub audit_log_success: Option<bool>,
970    #[serde(default)]
971    pub audit_log_failures: Option<bool>,
972    #[serde(default)]
973    pub audit_log_permissions: Option<bool>,
974    #[serde(default)]
975    pub audit_log_tokens: Option<bool>,
976}
977
978/// GET /admin/config
979///
980/// Returns the current runtime-mutable configuration.  Requires admin bearer token.
981pub async fn get_config(
982    State(state): State<ApiState>,
983    headers: HeaderMap,
984) -> ApiResponse<AdminConfigView> {
985    match extract_bearer_token(&headers) {
986        Some(token) => match validate_api_token(&state.auth_framework, &token).await {
987            Ok(auth_token) => {
988                if !auth_token.roles.contains("admin") {
989                    return ApiResponse::forbidden_typed();
990                }
991                let cfg = state.auth_framework.runtime_config().await;
992                ApiResponse::success(AdminConfigView::from(cfg))
993            }
994            Err(e) => {
995                let error_response = ApiResponse::<()>::from(e);
996                ApiResponse::<AdminConfigView> {
997                    success: error_response.success,
998                    data: None,
999                    error: error_response.error,
1000                    message: error_response.message,
1001                }
1002            }
1003        },
1004        None => ApiResponse::unauthorized_typed(),
1005    }
1006}
1007
1008/// PUT /admin/config
1009///
1010/// Applies a partial update to the runtime-mutable configuration.  Requires admin
1011/// bearer token.  Returns the updated configuration after applying all changes.
1012pub async fn update_config(
1013    State(state): State<ApiState>,
1014    headers: HeaderMap,
1015    Json(update): Json<AdminConfigUpdate>,
1016) -> ApiResponse<AdminConfigView> {
1017    match extract_bearer_token(&headers) {
1018        Some(token) => match validate_api_token(&state.auth_framework, &token).await {
1019            Ok(auth_token) => {
1020                if !auth_token.roles.contains("admin") {
1021                    return ApiResponse::forbidden_typed();
1022                }
1023
1024                // Load current config, merge, then validate via update_runtime_config.
1025                let mut current = state.auth_framework.runtime_config().await;
1026                if let Some(v) = update.token_lifetime_secs {
1027                    current.token_lifetime_secs = v;
1028                }
1029                if let Some(v) = update.refresh_token_lifetime_secs {
1030                    current.refresh_token_lifetime_secs = v;
1031                }
1032                if let Some(v) = update.enable_multi_factor {
1033                    current.enable_multi_factor = v;
1034                }
1035                if let Some(v) = update.rate_limiting_enabled {
1036                    current.rate_limiting_enabled = v;
1037                }
1038                if let Some(v) = update.rate_limit_max_requests {
1039                    current.rate_limit_max_requests = v;
1040                }
1041                if let Some(v) = update.rate_limit_window_secs {
1042                    current.rate_limit_window_secs = v;
1043                }
1044                if let Some(v) = update.rate_limit_burst {
1045                    current.rate_limit_burst = v;
1046                }
1047                if let Some(v) = update.min_password_length {
1048                    current.min_password_length = v;
1049                }
1050                if let Some(v) = update.require_password_complexity {
1051                    current.require_password_complexity = v;
1052                }
1053                if let Some(v) = update.secure_cookies {
1054                    current.secure_cookies = v;
1055                }
1056                if let Some(v) = update.csrf_protection {
1057                    current.csrf_protection = v;
1058                }
1059                if let Some(v) = update.session_timeout_secs {
1060                    current.session_timeout_secs = v;
1061                }
1062                if let Some(v) = update.audit_enabled {
1063                    current.audit_enabled = v;
1064                }
1065                if let Some(v) = update.audit_log_success {
1066                    current.audit_log_success = v;
1067                }
1068                if let Some(v) = update.audit_log_failures {
1069                    current.audit_log_failures = v;
1070                }
1071                if let Some(v) = update.audit_log_permissions {
1072                    current.audit_log_permissions = v;
1073                }
1074                if let Some(v) = update.audit_log_tokens {
1075                    current.audit_log_tokens = v;
1076                }
1077
1078                match state.auth_framework.update_runtime_config(current).await {
1079                    Ok(updated) => ApiResponse::success(AdminConfigView::from(updated)),
1080                    Err(e) => {
1081                        let error_response = ApiResponse::<()>::from(e);
1082                        ApiResponse::<AdminConfigView> {
1083                            success: error_response.success,
1084                            data: None,
1085                            error: error_response.error,
1086                            message: error_response.message,
1087                        }
1088                    }
1089                }
1090            }
1091            Err(e) => {
1092                let error_response = ApiResponse::<()>::from(e);
1093                ApiResponse::<AdminConfigView> {
1094                    success: error_response.success,
1095                    data: None,
1096                    error: error_response.error,
1097                    message: error_response.message,
1098                }
1099            }
1100        },
1101        None => ApiResponse::unauthorized_typed(),
1102    }
1103}