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