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") {
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                                && let Err(e) = state
317                                    .auth_framework
318                                    .update_user_roles(&user_id, &req.roles)
319                                    .await
320                            {
321                                tracing::warn!(
322                                    "Failed to set roles for new user {}: {}",
323                                    user_id,
324                                    e
325                                );
326                            }
327                            if !req.active
328                                && let Err(e) =
329                                    state.auth_framework.set_user_active(&user_id, false).await
330                            {
331                                tracing::warn!("Failed to deactivate new user {}: {}", user_id, e);
332                            }
333                            let new_user = UserListItem {
334                                id: user_id.clone(),
335                                username: req.username.clone(),
336                                email: req.email.clone(),
337                                roles: if req.roles.is_empty() {
338                                    vec!["user".to_string()]
339                                } else {
340                                    req.roles.clone()
341                                },
342                                active: req.active,
343                                created_at: chrono::Utc::now().to_rfc3339(),
344                                last_login: None,
345                            };
346                            tracing::info!("Admin created user: {} ({})", req.username, user_id);
347                            ApiResponse::success(new_user)
348                        }
349                        Err(e) => {
350                            let error_response = ApiResponse::<()>::from(e);
351                            ApiResponse::<UserListItem> {
352                                success: error_response.success,
353                                data: None,
354                                error: error_response.error,
355                                message: error_response.message,
356                            }
357                        }
358                    }
359                }
360                Err(e) => {
361                    // Convert AuthError to typed response
362                    let error_response = ApiResponse::<()>::from(e);
363                    ApiResponse::<UserListItem> {
364                        success: error_response.success,
365                        data: None,
366                        error: error_response.error,
367                        message: error_response.message,
368                    }
369                }
370            }
371        }
372        None => ApiResponse::<UserListItem>::unauthorized_typed(),
373    }
374}
375
376/// PUT /admin/users/{user_id}/roles
377/// Update user roles (admin only)
378pub async fn update_user_roles(
379    State(state): State<ApiState>,
380    headers: HeaderMap,
381    Path(user_id): Path<String>,
382    Json(req): Json<UpdateUserRolesRequest>,
383) -> ApiResponse<()> {
384    match extract_bearer_token(&headers) {
385        Some(token) => {
386            match validate_api_token(&state.auth_framework, &token).await {
387                Ok(auth_token) => {
388                    // Check admin permissions
389                    if let Err(resp) = verify_admin_role(&auth_token) {
390                        return resp;
391                    }
392
393                    match state
394                        .auth_framework
395                        .update_user_roles(&user_id, &req.roles)
396                        .await
397                    {
398                        Ok(()) => {
399                            tracing::info!(
400                                "Admin updated roles for user {}: {:?}",
401                                user_id,
402                                req.roles
403                            );
404                            ApiResponse::<()>::ok_with_message("User roles updated successfully")
405                        }
406                        Err(e) => e.into(),
407                    }
408                }
409                Err(e) => e.into(),
410            }
411        }
412        None => ApiResponse::unauthorized(),
413    }
414}
415
416/// DELETE /admin/users/{user_id}
417/// Delete user (admin only)
418pub async fn delete_user(
419    State(state): State<ApiState>,
420    headers: HeaderMap,
421    Path(user_id): Path<String>,
422) -> ApiResponse<()> {
423    match extract_bearer_token(&headers) {
424        Some(token) => {
425            match validate_api_token(&state.auth_framework, &token).await {
426                Ok(auth_token) => {
427                    // Check admin permissions
428                    if let Err(resp) = verify_admin_role(&auth_token) {
429                        return resp;
430                    }
431
432                    // Prevent self-deletion
433                    if auth_token.user_id == user_id {
434                        return ApiResponse::validation_error("Cannot delete your own account");
435                    }
436
437                    match state.auth_framework.get_username_by_id(&user_id).await {
438                        Ok(username) => match state.auth_framework.delete_user(&username).await {
439                            Ok(()) => {
440                                tracing::info!("Admin deleted user: {} ({})", username, user_id);
441                                ApiResponse::<()>::ok_with_message("User deleted successfully")
442                            }
443                            Err(e) => e.into(),
444                        },
445                        Err(e) => e.into(),
446                    }
447                }
448                Err(e) => e.into(),
449            }
450        }
451        None => ApiResponse::unauthorized(),
452    }
453}
454
455/// PUT /admin/users/{user_id}/activate
456/// Activate/deactivate user (admin only)
457#[derive(Debug, Deserialize)]
458pub struct ActivateUserRequest {
459    pub active: bool,
460}
461
462pub async fn activate_user(
463    State(state): State<ApiState>,
464    headers: HeaderMap,
465    Path(user_id): Path<String>,
466    Json(req): Json<ActivateUserRequest>,
467) -> ApiResponse<()> {
468    match extract_bearer_token(&headers) {
469        Some(token) => {
470            match validate_api_token(&state.auth_framework, &token).await {
471                Ok(auth_token) => {
472                    // Check admin permissions
473                    if !auth_token.roles.contains("admin") {
474                        return ApiResponse::forbidden();
475                    }
476
477                    match state
478                        .auth_framework
479                        .set_user_active(&user_id, req.active)
480                        .await
481                    {
482                        Ok(()) => {
483                            let action = if req.active {
484                                "activated"
485                            } else {
486                                "deactivated"
487                            };
488                            tracing::info!("Admin {} user {}", action, user_id);
489                            ApiResponse::<()>::ok_with_message(format!(
490                                "User {} successfully",
491                                action
492                            ))
493                        }
494                        Err(e) => e.into(),
495                    }
496                }
497                Err(e) => e.into(),
498            }
499        }
500        None => ApiResponse::unauthorized(),
501    }
502}
503
504/// GET /admin/stats
505/// Get system statistics (admin only)
506pub async fn get_system_stats(
507    State(state): State<ApiState>,
508    headers: HeaderMap,
509) -> ApiResponse<SystemStats> {
510    match extract_bearer_token(&headers) {
511        Some(token) => {
512            match validate_api_token(&state.auth_framework, &token).await {
513                Ok(auth_token) => {
514                    // Check admin permissions
515                    if !auth_token.roles.contains("admin") {
516                        return ApiResponse::forbidden_typed();
517                    }
518
519                    let storage = state.auth_framework.storage();
520                    let total_users = load_user_ids(&storage).await.len() as u64;
521                    let active_sessions = storage.count_active_sessions().await.unwrap_or(0);
522
523                    // Collect real system metrics via the sysinfo crate.
524                    let (system_uptime, memory_usage, cpu_usage) = {
525                        use sysinfo::System;
526                        let mut sys = System::new();
527                        sys.refresh_memory();
528                        sys.refresh_cpu_usage();
529                        let uptime_secs = System::uptime();
530                        let hours = uptime_secs / 3600;
531                        let mins = (uptime_secs % 3600) / 60;
532                        let secs = uptime_secs % 60;
533                        let uptime_str = format!("{hours}h {mins}m {secs}s");
534                        let used_mb = sys.used_memory() as f64 / 1_048_576.0;
535                        let total_mb = sys.total_memory() as f64 / 1_048_576.0;
536                        let mem_str = format!("{used_mb:.1} MB / {total_mb:.1} MB");
537                        let cpu_str = format!("{:.1}%", sys.global_cpu_usage());
538                        (uptime_str, mem_str, cpu_str)
539                    };
540
541                    let stats = SystemStats {
542                        total_users,
543                        active_sessions,
544                        // token count: proxy active sessions — each session
545                        // corresponds to at least one issued JWT token.
546                        total_tokens: active_sessions,
547                        // Persistent audit log not wired; cannot derive 24h
548                        // failure count from in-memory state alone.
549                        failed_logins_24h: 0,
550                        system_uptime,
551                        memory_usage,
552                        cpu_usage,
553                    };
554
555                    ApiResponse::success(stats)
556                }
557                Err(e) => {
558                    let error_response = ApiResponse::<()>::from(e);
559                    ApiResponse::<SystemStats> {
560                        success: error_response.success,
561                        data: None,
562                        error: error_response.error,
563                        message: error_response.message,
564                    }
565                }
566            }
567        }
568        None => ApiResponse::unauthorized_typed(),
569    }
570}
571
572/// GET /admin/audit-logs
573/// Get audit logs (admin only)
574#[derive(Debug, Serialize)]
575pub struct AuditLogEntry {
576    pub id: String,
577    pub timestamp: String,
578    pub user_id: String,
579    pub action: String,
580    pub resource: String,
581    pub ip_address: String,
582    pub user_agent: String,
583    pub result: String,
584    /// Risk level of the event: "low", "medium", "high", or "critical".
585    pub risk_level: String,
586    /// Outcome: "success", "failure", "partial", or "unknown".
587    pub outcome: String,
588    /// Correlation ID linking related events across the same authentication flow.
589    #[serde(skip_serializing_if = "Option::is_none")]
590    pub correlation_id: Option<String>,
591}
592
593#[derive(Debug, Serialize)]
594pub struct AuditLogResponse {
595    pub logs: Vec<AuditLogEntry>,
596    pub pagination: Pagination,
597}
598
599#[derive(Debug, Deserialize)]
600pub struct AuditLogQuery {
601    #[serde(default = "default_page")]
602    pub page: u32,
603    #[serde(default = "default_limit")]
604    pub limit: u32,
605    #[serde(default)]
606    pub user_id: Option<String>,
607    #[serde(default)]
608    pub action: Option<String>,
609    #[serde(default)]
610    pub start_date: Option<String>,
611    #[serde(default)]
612    pub end_date: Option<String>,
613    /// Filter by risk level: "low", "medium", "high", or "critical".
614    #[serde(default)]
615    pub risk_level: Option<String>,
616    /// Filter by outcome: "success" or "failure".
617    #[serde(default)]
618    pub outcome: Option<String>,
619    /// Filter by correlation ID to trace a single authentication flow.
620    #[serde(default)]
621    pub correlation_id: Option<String>,
622    /// Filter by client IP address.
623    #[serde(default)]
624    pub ip_address: Option<String>,
625}
626
627pub async fn get_audit_logs(
628    State(state): State<ApiState>,
629    headers: HeaderMap,
630    Query(query): Query<AuditLogQuery>,
631) -> ApiResponse<AuditLogResponse> {
632    match extract_bearer_token(&headers) {
633        Some(token) => {
634            match validate_api_token(&state.auth_framework, &token).await {
635                Ok(auth_token) => {
636                    // Check admin permissions
637                    if !auth_token.roles.contains("admin") {
638                        return ApiResponse::forbidden_typed();
639                    }
640
641                    let page = if query.page == 0 { 1 } else { query.page };
642                    let limit = if query.limit == 0 {
643                        20
644                    } else {
645                        query.limit.min(100)
646                    };
647                    let offset = ((page - 1) * limit) as usize;
648                    let fetch_limit = offset + limit as usize;
649
650                    match state
651                        .auth_framework
652                        .get_permission_audit_logs(
653                            query.user_id.as_deref(),
654                            query.action.as_deref(),
655                            None,
656                            Some(fetch_limit),
657                        )
658                        .await
659                    {
660                        Ok(all_logs) => {
661                            // Parse and enrich all log entries first so filtering is applied
662                            // before pagination.
663                            let mut parsed: Vec<AuditLogEntry> = all_logs
664                                .into_iter()
665                                .enumerate()
666                                .map(|(i, log_str)| {
667                                    let (ts, rest) = log_str
668                                        .strip_prefix('[')
669                                        .and_then(|s| s.split_once(']'))
670                                        .map(|(t, r)| (t.trim().to_string(), r.trim().to_string()))
671                                        .unwrap_or_else(|| {
672                                            ("unknown".to_string(), log_str.clone())
673                                        });
674                                    let uid = rest
675                                        .split_whitespace()
676                                        .find(|w| w.starts_with("user="))
677                                        .and_then(|w| w.strip_prefix("user="))
678                                        .unwrap_or("system")
679                                        .to_string();
680                                    let raw_outcome = rest
681                                        .split_whitespace()
682                                        .find(|w| w.starts_with("outcome="))
683                                        .and_then(|w| w.strip_prefix("outcome="))
684                                        .unwrap_or("unknown")
685                                        .to_string();
686                                    let ip = rest
687                                        .split_whitespace()
688                                        .find(|w| w.starts_with("ip="))
689                                        .and_then(|w| w.strip_prefix("ip="))
690                                        .unwrap_or("")
691                                        .to_string();
692                                    let ua = rest
693                                        .split_whitespace()
694                                        .find(|w| w.starts_with("ua="))
695                                        .and_then(|w| w.strip_prefix("ua="))
696                                        .unwrap_or("")
697                                        .to_string();
698                                    let corr = rest
699                                        .split_whitespace()
700                                        .find(|w| w.starts_with("correlation_id="))
701                                        .and_then(|w| w.strip_prefix("correlation_id="))
702                                        .map(str::to_string);
703                                    // Derive outcome category and risk level from the raw
704                                    // outcome token present in the log line.
705                                    let outcome = if raw_outcome.contains("success") {
706                                        "success"
707                                    } else if raw_outcome.contains("fail")
708                                        || raw_outcome.contains("error")
709                                    {
710                                        "failure"
711                                    } else {
712                                        "unknown"
713                                    };
714                                    // Risk level: failures + high index numbers treated as
715                                    // higher risk for demonstration; real implementations
716                                    // should propagate risk from the authentication path.
717                                    let risk_level = if outcome == "failure" {
718                                        "medium"
719                                    } else {
720                                        "low"
721                                    };
722                                    AuditLogEntry {
723                                        id: format!("audit_{}", i),
724                                        timestamp: ts,
725                                        user_id: uid,
726                                        action: rest,
727                                        resource: String::new(),
728                                        ip_address: ip,
729                                        user_agent: ua,
730                                        result: raw_outcome,
731                                        risk_level: risk_level.to_string(),
732                                        outcome: outcome.to_string(),
733                                        correlation_id: corr,
734                                    }
735                                })
736                                .collect();
737
738                            // Apply optional client-side filters on the enriched entries.
739                            if let Some(ref filter_ip) = query.ip_address {
740                                parsed.retain(|e| e.ip_address.contains(filter_ip.as_str()));
741                            }
742                            if let Some(ref filter_risk) = query.risk_level {
743                                parsed.retain(|e| e.risk_level == filter_risk.as_str());
744                            }
745                            if let Some(ref filter_outcome) = query.outcome {
746                                parsed.retain(|e| e.outcome == filter_outcome.as_str());
747                            }
748                            if let Some(ref filter_corr) = query.correlation_id {
749                                parsed.retain(|e| {
750                                    e.correlation_id.as_deref() == Some(filter_corr.as_str())
751                                });
752                            }
753
754                            let total = parsed.len() as u64;
755                            let total_pages = ((total as f64) / (limit as f64)).ceil() as u32;
756                            let total_pages = if total_pages == 0 { 1 } else { total_pages };
757
758                            let logs: Vec<AuditLogEntry> = parsed
759                                .into_iter()
760                                .skip(offset)
761                                .take(limit as usize)
762                                .collect();
763
764                            ApiResponse::success(AuditLogResponse {
765                                logs,
766                                pagination: Pagination {
767                                    page,
768                                    limit,
769                                    total,
770                                    pages: total_pages,
771                                },
772                            })
773                        }
774                        Err(e) => {
775                            let error_response = ApiResponse::<()>::from(e);
776                            ApiResponse::<AuditLogResponse> {
777                                success: error_response.success,
778                                data: None,
779                                error: error_response.error,
780                                message: error_response.message,
781                            }
782                        }
783                    }
784                }
785                Err(e) => {
786                    let error_response = ApiResponse::<()>::from(e);
787                    ApiResponse::<AuditLogResponse> {
788                        success: error_response.success,
789                        data: None,
790                        error: error_response.error,
791                        message: error_response.message,
792                    }
793                }
794            }
795        }
796        None => ApiResponse::unauthorized_typed(),
797    }
798}
799
800/// Summary statistics returned by `GET /admin/audit-logs/stats`.
801#[derive(Debug, Serialize)]
802pub struct AuditLogStats {
803    /// Total events recorded in the last 24 hours.
804    pub total_events_24h: u64,
805    /// Failed login events in the last 24 hours.
806    pub failed_logins_24h: u64,
807    /// Successful login events in the last 24 hours.
808    pub successful_logins_24h: u64,
809    /// Events flagged as high-risk or critical in the last 24 hours.
810    pub high_risk_events_24h: u64,
811    /// Distinct user IDs seen in the last 24 hours.
812    pub unique_users_24h: u64,
813    /// Security alerts raised in the last 24 hours.
814    pub security_alerts_24h: u64,
815}
816
817/// GET /admin/audit-logs/stats
818///
819/// Returns aggregated audit-log statistics for the last 24 hours.
820/// Requires an admin bearer token.
821pub async fn get_audit_log_stats(
822    State(state): State<ApiState>,
823    headers: HeaderMap,
824) -> ApiResponse<AuditLogStats> {
825    match extract_bearer_token(&headers) {
826        Some(token) => match validate_api_token(&state.auth_framework, &token).await {
827            Ok(auth_token) => {
828                if !auth_token.roles.contains("admin") {
829                    return ApiResponse::forbidden_typed();
830                }
831
832                match state.auth_framework.get_security_audit_stats().await {
833                    Ok(sec_stats) => ApiResponse::success(AuditLogStats {
834                        total_events_24h: sec_stats.failed_logins_24h
835                            + sec_stats.successful_logins_24h
836                            + sec_stats.admin_actions_24h,
837                        failed_logins_24h: sec_stats.failed_logins_24h,
838                        successful_logins_24h: sec_stats.successful_logins_24h,
839                        high_risk_events_24h: sec_stats.security_alerts_24h,
840                        unique_users_24h: sec_stats.unique_users_24h,
841                        security_alerts_24h: sec_stats.security_alerts_24h,
842                    }),
843                    Err(e) => {
844                        let error_response = ApiResponse::<()>::from(e);
845                        ApiResponse::<AuditLogStats> {
846                            success: error_response.success,
847                            data: None,
848                            error: error_response.error,
849                            message: error_response.message,
850                        }
851                    }
852                }
853            }
854            Err(e) => {
855                let error_response = ApiResponse::<()>::from(e);
856                ApiResponse::<AuditLogStats> {
857                    success: error_response.success,
858                    data: None,
859                    error: error_response.error,
860                    message: error_response.message,
861                }
862            }
863        },
864        None => ApiResponse::unauthorized_typed(),
865    }
866}
867
868// ─── Admin configuration endpoints ──────────────────────────────────────────
869
870/// Response body for `GET /admin/config`.
871///
872/// Only runtime-mutable fields are exposed. Security-sensitive settings (JWT
873/// secret, signing algorithm, storage backend) are intentionally omitted.
874#[derive(Debug, Serialize)]
875pub struct AdminConfigView {
876    pub token_lifetime_secs: u64,
877    pub refresh_token_lifetime_secs: u64,
878    pub enable_multi_factor: bool,
879    pub rate_limiting_enabled: bool,
880    pub rate_limit_max_requests: u32,
881    pub rate_limit_window_secs: u64,
882    pub rate_limit_burst: u32,
883    pub min_password_length: usize,
884    pub require_password_complexity: bool,
885    pub secure_cookies: bool,
886    pub csrf_protection: bool,
887    pub session_timeout_secs: u64,
888    pub audit_enabled: bool,
889    pub audit_log_success: bool,
890    pub audit_log_failures: bool,
891    pub audit_log_permissions: bool,
892    pub audit_log_tokens: bool,
893}
894
895impl From<crate::config::RuntimeConfig> for AdminConfigView {
896    fn from(c: crate::config::RuntimeConfig) -> Self {
897        Self {
898            token_lifetime_secs: c.token_lifetime_secs,
899            refresh_token_lifetime_secs: c.refresh_token_lifetime_secs,
900            enable_multi_factor: c.enable_multi_factor,
901            rate_limiting_enabled: c.rate_limiting_enabled,
902            rate_limit_max_requests: c.rate_limit_max_requests,
903            rate_limit_window_secs: c.rate_limit_window_secs,
904            rate_limit_burst: c.rate_limit_burst,
905            min_password_length: c.min_password_length,
906            require_password_complexity: c.require_password_complexity,
907            secure_cookies: c.secure_cookies,
908            csrf_protection: c.csrf_protection,
909            session_timeout_secs: c.session_timeout_secs,
910            audit_enabled: c.audit_enabled,
911            audit_log_success: c.audit_log_success,
912            audit_log_failures: c.audit_log_failures,
913            audit_log_permissions: c.audit_log_permissions,
914            audit_log_tokens: c.audit_log_tokens,
915        }
916    }
917}
918
919/// Request body for `PUT /admin/config` — all fields optional.
920///
921/// Omitted fields retain their current values.  This enables partial updates
922/// (patch semantics) without the client needing to re-send unchanged settings.
923#[derive(Debug, Deserialize)]
924pub struct AdminConfigUpdate {
925    #[serde(default)]
926    pub token_lifetime_secs: Option<u64>,
927    #[serde(default)]
928    pub refresh_token_lifetime_secs: Option<u64>,
929    #[serde(default)]
930    pub enable_multi_factor: Option<bool>,
931    #[serde(default)]
932    pub rate_limiting_enabled: Option<bool>,
933    #[serde(default)]
934    pub rate_limit_max_requests: Option<u32>,
935    #[serde(default)]
936    pub rate_limit_window_secs: Option<u64>,
937    #[serde(default)]
938    pub rate_limit_burst: Option<u32>,
939    #[serde(default)]
940    pub min_password_length: Option<usize>,
941    #[serde(default)]
942    pub require_password_complexity: Option<bool>,
943    #[serde(default)]
944    pub secure_cookies: Option<bool>,
945    #[serde(default)]
946    pub csrf_protection: Option<bool>,
947    #[serde(default)]
948    pub session_timeout_secs: Option<u64>,
949    #[serde(default)]
950    pub audit_enabled: Option<bool>,
951    #[serde(default)]
952    pub audit_log_success: Option<bool>,
953    #[serde(default)]
954    pub audit_log_failures: Option<bool>,
955    #[serde(default)]
956    pub audit_log_permissions: Option<bool>,
957    #[serde(default)]
958    pub audit_log_tokens: Option<bool>,
959}
960
961/// GET /admin/config
962///
963/// Returns the current runtime-mutable configuration.  Requires admin bearer token.
964pub async fn get_config(
965    State(state): State<ApiState>,
966    headers: HeaderMap,
967) -> ApiResponse<AdminConfigView> {
968    match extract_bearer_token(&headers) {
969        Some(token) => match validate_api_token(&state.auth_framework, &token).await {
970            Ok(auth_token) => {
971                if !auth_token.roles.contains("admin") {
972                    return ApiResponse::forbidden_typed();
973                }
974                let cfg = state.auth_framework.runtime_config().await;
975                ApiResponse::success(AdminConfigView::from(cfg))
976            }
977            Err(e) => {
978                let error_response = ApiResponse::<()>::from(e);
979                ApiResponse::<AdminConfigView> {
980                    success: error_response.success,
981                    data: None,
982                    error: error_response.error,
983                    message: error_response.message,
984                }
985            }
986        },
987        None => ApiResponse::unauthorized_typed(),
988    }
989}
990
991/// PUT /admin/config
992///
993/// Applies a partial update to the runtime-mutable configuration.  Requires admin
994/// bearer token.  Returns the updated configuration after applying all changes.
995pub async fn update_config(
996    State(state): State<ApiState>,
997    headers: HeaderMap,
998    Json(update): Json<AdminConfigUpdate>,
999) -> ApiResponse<AdminConfigView> {
1000    match extract_bearer_token(&headers) {
1001        Some(token) => match validate_api_token(&state.auth_framework, &token).await {
1002            Ok(auth_token) => {
1003                if !auth_token.roles.contains("admin") {
1004                    return ApiResponse::forbidden_typed();
1005                }
1006
1007                // Load current config, merge, then validate via update_runtime_config.
1008                let mut current = state.auth_framework.runtime_config().await;
1009                if let Some(v) = update.token_lifetime_secs {
1010                    current.token_lifetime_secs = v;
1011                }
1012                if let Some(v) = update.refresh_token_lifetime_secs {
1013                    current.refresh_token_lifetime_secs = v;
1014                }
1015                if let Some(v) = update.enable_multi_factor {
1016                    current.enable_multi_factor = v;
1017                }
1018                if let Some(v) = update.rate_limiting_enabled {
1019                    current.rate_limiting_enabled = v;
1020                }
1021                if let Some(v) = update.rate_limit_max_requests {
1022                    current.rate_limit_max_requests = v;
1023                }
1024                if let Some(v) = update.rate_limit_window_secs {
1025                    current.rate_limit_window_secs = v;
1026                }
1027                if let Some(v) = update.rate_limit_burst {
1028                    current.rate_limit_burst = v;
1029                }
1030                if let Some(v) = update.min_password_length {
1031                    current.min_password_length = v;
1032                }
1033                if let Some(v) = update.require_password_complexity {
1034                    current.require_password_complexity = v;
1035                }
1036                if let Some(v) = update.secure_cookies {
1037                    current.secure_cookies = v;
1038                }
1039                if let Some(v) = update.csrf_protection {
1040                    current.csrf_protection = v;
1041                }
1042                if let Some(v) = update.session_timeout_secs {
1043                    current.session_timeout_secs = v;
1044                }
1045                if let Some(v) = update.audit_enabled {
1046                    current.audit_enabled = v;
1047                }
1048                if let Some(v) = update.audit_log_success {
1049                    current.audit_log_success = v;
1050                }
1051                if let Some(v) = update.audit_log_failures {
1052                    current.audit_log_failures = v;
1053                }
1054                if let Some(v) = update.audit_log_permissions {
1055                    current.audit_log_permissions = v;
1056                }
1057                if let Some(v) = update.audit_log_tokens {
1058                    current.audit_log_tokens = v;
1059                }
1060
1061                match state.auth_framework.update_runtime_config(current).await {
1062                    Ok(updated) => ApiResponse::success(AdminConfigView::from(updated)),
1063                    Err(e) => {
1064                        let error_response = ApiResponse::<()>::from(e);
1065                        ApiResponse::<AdminConfigView> {
1066                            success: error_response.success,
1067                            data: None,
1068                            error: error_response.error,
1069                            message: error_response.message,
1070                        }
1071                    }
1072                }
1073            }
1074            Err(e) => {
1075                let error_response = ApiResponse::<()>::from(e);
1076                ApiResponse::<AdminConfigView> {
1077                    success: error_response.success,
1078                    data: None,
1079                    error: error_response.error,
1080                    message: error_response.message,
1081                }
1082            }
1083        },
1084        None => ApiResponse::unauthorized_typed(),
1085    }
1086}