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