Skip to main content

auth_framework/
maintenance.rs

1//! Maintenance utilities: snapshots, data export, and health checks.
2//!
3//! Provides tools for operational maintenance including:
4//!
5//! - **Snapshot & restore** — Serialise the entire storage state to a
6//!   versioned, checksummed snapshot file and restore from it.
7//! - **Data export** — Export users, sessions, tokens, and audit logs as
8//!   structured JSON for compliance or migration purposes.
9//! - **Health checks** — Verify storage connectivity, token validity, and
10//!   system integrity.
11//!
12//! Most operations are available through the
13//! [`MaintenanceOperations`](crate::auth::MaintenanceOperations) facade.
14
15use crate::auth::AuthFramework;
16use crate::auth_operations::UserListQuery;
17use crate::config::{StorageConfig, app_config::AppConfig};
18use crate::errors::{AuthError, Result};
19use crate::permissions::Role;
20use crate::storage::SessionData;
21use crate::tokens::AuthToken;
22use base64::Engine;
23use base64::engine::general_purpose::STANDARD as BASE64_STANDARD;
24use chrono::{DateTime, Utc};
25use serde::{Deserialize, Serialize};
26use serde_json::{Map, Value};
27use sha2::{Digest, Sha256};
28use std::collections::HashSet;
29use std::path::{Path, PathBuf};
30
31const SNAPSHOT_FORMAT_VERSION: u32 = 1;
32
33#[derive(Debug, Clone, Serialize, Deserialize)]
34pub struct SnapshotManifest {
35    pub format_version: u32,
36    pub created_at: DateTime<Utc>,
37    pub storage_backend: String,
38    pub user_count: usize,
39    pub role_count: usize,
40    pub token_count: usize,
41    pub session_count: usize,
42    pub kv_entry_count: usize,
43    pub checksum_sha256: String,
44}
45
46#[derive(Debug, Clone, Serialize, Deserialize)]
47pub struct SnapshotUserSummary {
48    pub id: String,
49    pub username: String,
50    pub email: Option<String>,
51    pub roles: Vec<String>,
52    pub active: bool,
53}
54
55#[derive(Clone, Serialize, Deserialize)]
56pub struct SnapshotKvEntry {
57    pub key: String,
58    pub value_base64: String,
59}
60
61impl std::fmt::Debug for SnapshotKvEntry {
62    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
63        let mut d = f.debug_struct("SnapshotKvEntry");
64        d.field("key", &crate::utils::redact::redacted(&self.key));
65        d.field(
66            "value_base64",
67            &crate::utils::redact::redacted(&self.value_base64),
68        );
69        d.finish()
70    }
71}
72
73#[derive(Debug, Clone, Serialize, Deserialize)]
74pub struct MaintenanceSnapshot {
75    pub manifest: SnapshotManifest,
76    pub users: Vec<SnapshotUserSummary>,
77    pub roles: Vec<Role>,
78    pub tokens: Vec<AuthToken>,
79    pub sessions: Vec<SessionData>,
80    pub kv_entries: Vec<SnapshotKvEntry>,
81}
82
83#[derive(Debug, Clone)]
84pub struct BackupReport {
85    pub manifest: SnapshotManifest,
86    pub output_path: PathBuf,
87    pub dry_run: bool,
88}
89
90#[derive(Debug, Clone)]
91pub struct ResetReport {
92    pub users_deleted: usize,
93    pub roles_seen: usize,
94    pub tokens_deleted: usize,
95    pub sessions_deleted: usize,
96    pub kv_entries_deleted: usize,
97    pub dry_run: bool,
98}
99
100#[derive(Debug, Clone)]
101pub struct RestoreReport {
102    pub manifest: SnapshotManifest,
103    pub input_path: PathBuf,
104    pub reset_report: ResetReport,
105    pub dry_run: bool,
106}
107
108#[derive(Debug, Clone)]
109pub struct MigrationFileReport {
110    pub backend: String,
111    pub path: PathBuf,
112}
113
114#[derive(Serialize)]
115struct SnapshotChecksumPayload<'a> {
116    users: &'a [SnapshotUserSummary],
117    roles: &'a [Role],
118    tokens: &'a [AuthToken],
119    sessions: &'a [SessionData],
120    kv_entries: &'a [SnapshotKvEntry],
121}
122
123fn normalize_json_value(value: Value) -> Value {
124    match value {
125        Value::Array(values) => {
126            let mut normalized = values
127                .into_iter()
128                .map(normalize_json_value)
129                .collect::<Vec<_>>();
130            normalized.sort_by_key(|left| left.to_string());
131            Value::Array(normalized)
132        }
133        Value::Object(object) => {
134            let mut entries = object.into_iter().collect::<Vec<_>>();
135            entries.sort_by(|left, right| left.0.cmp(&right.0));
136
137            let normalized = entries
138                .into_iter()
139                .map(|(key, value)| (key, normalize_json_value(value)))
140                .collect::<Map<String, Value>>();
141            Value::Object(normalized)
142        }
143        other => other,
144    }
145}
146
147fn storage_backend_name(config: &StorageConfig) -> &'static str {
148    match config {
149        StorageConfig::Memory => "memory",
150        #[cfg(feature = "postgres-storage")]
151        StorageConfig::Postgres { .. } => "postgres",
152        #[cfg(feature = "redis-storage")]
153        StorageConfig::Redis { .. } => "redis",
154        #[cfg(feature = "sqlite-storage")]
155        StorageConfig::Sqlite { .. } => "sqlite",
156        StorageConfig::Custom(_) => "custom",
157    }
158}
159
160fn backend_name_from_database_url(database_url: &str) -> &'static str {
161    let database_url = database_url.trim().to_ascii_lowercase();
162
163    if database_url.starts_with("postgres://") || database_url.starts_with("postgresql://") {
164        "postgres"
165    } else if database_url.starts_with("mysql://") {
166        "mysql"
167    } else if database_url.starts_with("sqlite:") || database_url.ends_with(".db") {
168        "sqlite"
169    } else if database_url.starts_with("redis://") || database_url.starts_with("rediss://") {
170        "redis"
171    } else if database_url.is_empty() {
172        "memory"
173    } else {
174        "custom"
175    }
176}
177
178fn checksum_snapshot(
179    users: &[SnapshotUserSummary],
180    roles: &[Role],
181    tokens: &[AuthToken],
182    sessions: &[SessionData],
183    kv_entries: &[SnapshotKvEntry],
184) -> Result<String> {
185    let payload = SnapshotChecksumPayload {
186        users,
187        roles,
188        tokens,
189        sessions,
190        kv_entries,
191    };
192    let encoded = serde_json::to_value(&payload)
193        .map(normalize_json_value)
194        .and_then(|value| serde_json::to_vec(&value))
195        .map_err(|e| AuthError::internal(format!("Failed to serialize snapshot payload: {e}")))?;
196    let mut hasher = Sha256::new();
197    hasher.update(encoded);
198    Ok(hex::encode(hasher.finalize()))
199}
200
201fn sanitize_migration_name(name: &str) -> Result<String> {
202    let sanitized = name
203        .trim()
204        .chars()
205        .map(|character| {
206            if character.is_ascii_alphanumeric() {
207                character.to_ascii_lowercase()
208            } else {
209                '_'
210            }
211        })
212        .collect::<String>();
213
214    let collapsed = sanitized
215        .split('_')
216        .filter(|segment| !segment.is_empty())
217        .collect::<Vec<_>>()
218        .join("_");
219
220    if collapsed.is_empty() {
221        return Err(AuthError::validation(
222            "Migration name must contain at least one alphanumeric character",
223        ));
224    }
225
226    Ok(collapsed)
227}
228
229async fn collect_snapshot(framework: &AuthFramework) -> Result<MaintenanceSnapshot> {
230    let storage = framework.storage();
231
232    let mut users = framework
233        .users()
234        .list_with_query(UserListQuery::new())
235        .await?;
236    users.sort_by(|left, right| left.id.cmp(&right.id));
237
238    let mut snapshot_users = Vec::with_capacity(users.len());
239    for user in &users {
240        let mut roles: HashSet<String> = user.roles.iter().cloned().collect();
241        roles.extend(framework.authorization().roles_for_user(&user.id).await?);
242        let mut roles = roles.into_iter().collect::<Vec<_>>();
243        roles.sort();
244
245        snapshot_users.push(SnapshotUserSummary {
246            id: user.id.clone(),
247            username: user.username.clone(),
248            email: user.email.clone(),
249            roles,
250            active: user.active,
251        });
252    }
253
254    let mut roles = framework.authorization().list_roles().await;
255    roles.sort_by(|left, right| left.name.cmp(&right.name));
256
257    let mut tokens = Vec::new();
258    let mut seen_tokens = HashSet::new();
259    let mut sessions = Vec::new();
260    let mut seen_sessions = HashSet::new();
261
262    for user in &users {
263        for token in framework.tokens().list_for_user(&user.id).await? {
264            if seen_tokens.insert(token.token_id.clone()) {
265                tokens.push(token);
266            }
267        }
268
269        for session in framework.sessions().list_for_user(&user.id).await? {
270            if seen_sessions.insert(session.session_id.clone()) {
271                sessions.push(session);
272            }
273        }
274    }
275
276    tokens.sort_by(|left, right| left.token_id.cmp(&right.token_id));
277    sessions.sort_by(|left, right| left.session_id.cmp(&right.session_id));
278
279    let mut kv_keys = storage.list_kv_keys("").await?;
280    kv_keys.sort();
281    kv_keys.dedup();
282
283    let mut kv_entries = Vec::with_capacity(kv_keys.len());
284    for key in kv_keys {
285        if let Some(value) = storage.get_kv(&key).await? {
286            kv_entries.push(SnapshotKvEntry {
287                key,
288                value_base64: BASE64_STANDARD.encode(value),
289            });
290        }
291    }
292
293    let manifest = SnapshotManifest {
294        format_version: SNAPSHOT_FORMAT_VERSION,
295        created_at: Utc::now(),
296        storage_backend: storage_backend_name(&framework.config().storage).to_string(),
297        user_count: snapshot_users.len(),
298        role_count: roles.len(),
299        token_count: tokens.len(),
300        session_count: sessions.len(),
301        kv_entry_count: kv_entries.len(),
302        checksum_sha256: checksum_snapshot(
303            &snapshot_users,
304            &roles,
305            &tokens,
306            &sessions,
307            &kv_entries,
308        )?,
309    };
310
311    Ok(MaintenanceSnapshot {
312        manifest,
313        users: snapshot_users,
314        roles,
315        tokens,
316        sessions,
317        kv_entries,
318    })
319}
320
321fn validate_snapshot(snapshot: &MaintenanceSnapshot) -> Result<()> {
322    if snapshot.manifest.format_version != SNAPSHOT_FORMAT_VERSION {
323        return Err(AuthError::configuration(format!(
324            "Unsupported snapshot format version {}",
325            snapshot.manifest.format_version
326        )));
327    }
328
329    let expected_checksum = checksum_snapshot(
330        &snapshot.users,
331        &snapshot.roles,
332        &snapshot.tokens,
333        &snapshot.sessions,
334        &snapshot.kv_entries,
335    )?;
336
337    if expected_checksum != snapshot.manifest.checksum_sha256 {
338        return Err(AuthError::validation(
339            "Snapshot checksum validation failed; restore aborted",
340        ));
341    }
342
343    Ok(())
344}
345
346pub async fn backup_to_file(
347    framework: &AuthFramework,
348    output_path: impl AsRef<Path>,
349    dry_run: bool,
350) -> Result<BackupReport> {
351    let output_path = output_path.as_ref().to_path_buf();
352    let snapshot = collect_snapshot(framework).await?;
353
354    if !dry_run {
355        if let Some(parent) = output_path.parent()
356            && !parent.as_os_str().is_empty()
357        {
358            tokio::fs::create_dir_all(parent).await?;
359        }
360
361        let data = serde_json::to_vec_pretty(&snapshot).map_err(|e| {
362            AuthError::internal(format!("Failed to serialize maintenance snapshot: {e}"))
363        })?;
364        tokio::fs::write(&output_path, data).await?;
365    }
366
367    Ok(BackupReport {
368        manifest: snapshot.manifest,
369        output_path,
370        dry_run,
371    })
372}
373
374pub async fn reset_runtime_data(framework: &AuthFramework, dry_run: bool) -> Result<ResetReport> {
375    let storage = framework.storage();
376    let users = framework
377        .users()
378        .list_with_query(UserListQuery::new())
379        .await?;
380    let roles = framework.authorization().list_roles().await;
381
382    let mut token_ids = HashSet::new();
383    let mut session_ids = HashSet::new();
384    for user in &users {
385        for token in framework.tokens().list_for_user(&user.id).await? {
386            token_ids.insert(token.token_id);
387        }
388
389        for session in framework.sessions().list_for_user(&user.id).await? {
390            session_ids.insert(session.session_id);
391        }
392    }
393
394    let mut kv_keys = storage.list_kv_keys("").await?;
395    kv_keys.sort();
396    kv_keys.dedup();
397
398    if !dry_run {
399        for token_id in &token_ids {
400            storage.delete_token(token_id).await?;
401        }
402
403        for session_id in &session_ids {
404            storage.delete_session(session_id).await?;
405        }
406
407        for user in &users {
408            framework.users().delete_by_id(&user.id).await?;
409        }
410
411        for key in &kv_keys {
412            storage.delete_kv(key).await?;
413        }
414
415        framework.reset_authorization_runtime().await;
416    }
417
418    Ok(ResetReport {
419        users_deleted: users.len(),
420        roles_seen: roles.len(),
421        tokens_deleted: token_ids.len(),
422        sessions_deleted: session_ids.len(),
423        kv_entries_deleted: kv_keys.len(),
424        dry_run,
425    })
426}
427
428pub async fn restore_from_file(
429    framework: &AuthFramework,
430    input_path: impl AsRef<Path>,
431    dry_run: bool,
432) -> Result<RestoreReport> {
433    let input_path = input_path.as_ref().to_path_buf();
434    let data = tokio::fs::read(&input_path).await?;
435    let snapshot: MaintenanceSnapshot = serde_json::from_slice(&data)
436        .map_err(|e| AuthError::validation(format!("Failed to parse maintenance snapshot: {e}")))?;
437    validate_snapshot(&snapshot)?;
438
439    let reset_report = reset_runtime_data(framework, dry_run).await?;
440
441    if !dry_run {
442        let storage = framework.storage();
443
444        for entry in &snapshot.kv_entries {
445            let value = BASE64_STANDARD.decode(&entry.value_base64).map_err(|e| {
446                AuthError::validation(format!(
447                    "Snapshot KV entry '{}' is not valid base64: {e}",
448                    entry.key
449                ))
450            })?;
451            storage.store_kv(&entry.key, &value, None).await?;
452        }
453
454        for token in &snapshot.tokens {
455            storage.store_token(token).await?;
456        }
457
458        for session in &snapshot.sessions {
459            storage.store_session(&session.session_id, session).await?;
460        }
461
462        framework.reset_authorization_runtime().await;
463        for role in &snapshot.roles {
464            framework.authorization().create_role(role.clone()).await?;
465        }
466        for user in &snapshot.users {
467            for role_name in &user.roles {
468                framework
469                    .authorization()
470                    .assign_role(&user.id, role_name)
471                    .await?;
472            }
473        }
474    }
475
476    Ok(RestoreReport {
477        manifest: snapshot.manifest,
478        input_path,
479        reset_report,
480        dry_run,
481    })
482}
483
484fn build_migration_template(backend: &str, migration_name: &str, original_name: &str) -> String {
485    format!(
486        "-- AuthFramework migration template\n-- Backend: {backend}\n-- Name: {original_name}\n-- Generated at: {}\n\n-- Replace this placeholder with idempotent DDL for {migration_name}.\n-- Prefer CREATE TABLE IF NOT EXISTS / CREATE INDEX IF NOT EXISTS where supported.\n\nBEGIN;\n\n-- Add migration SQL here\n\nCOMMIT;\n",
487        Utc::now().to_rfc3339(),
488    )
489}
490
491pub async fn create_migration_file(config: &AppConfig, name: &str) -> Result<MigrationFileReport> {
492    let backend = backend_name_from_database_url(&config.database.url).to_string();
493    create_migration_template_for_backend(&backend, name).await
494}
495
496pub async fn create_migration_file_for_storage(
497    storage: &StorageConfig,
498    name: &str,
499) -> Result<MigrationFileReport> {
500    let backend = storage_backend_name(storage).to_string();
501    create_migration_template_for_backend(&backend, name).await
502}
503
504async fn create_migration_template_for_backend(
505    backend: &str,
506    name: &str,
507) -> Result<MigrationFileReport> {
508    let sanitized_name = sanitize_migration_name(name)?;
509    let directory = PathBuf::from("migrations").join(backend);
510    tokio::fs::create_dir_all(&directory).await?;
511
512    let file_name = format!(
513        "{}_{}.sql",
514        Utc::now().format("%Y%m%d%H%M%S"),
515        sanitized_name
516    );
517    let path = directory.join(file_name);
518    let template = build_migration_template(backend, &sanitized_name, name);
519    tokio::fs::write(&path, template).await?;
520
521    Ok(MigrationFileReport {
522        backend: backend.to_string(),
523        path,
524    })
525}
526
527#[cfg(test)]
528mod tests {
529    use super::*;
530    use crate::config::AuthConfig;
531    use crate::methods::{AuthMethodEnum, JwtMethod};
532    use std::time::Duration;
533    use tempfile::tempdir;
534
535    async fn create_framework() -> AuthFramework {
536        let config = AuthConfig::new()
537            .secret("0123456789abcdef0123456789abcdef")
538            .token_lifetime(Duration::from_secs(3600));
539        let mut framework = AuthFramework::new(config);
540        framework.register_method("jwt", AuthMethodEnum::Jwt(JwtMethod::new()));
541        framework.initialize().await.unwrap();
542        framework
543    }
544
545    #[tokio::test]
546    async fn backup_restore_roundtrip_preserves_runtime_state() {
547        let framework = create_framework().await;
548        let user_id = framework
549            .users()
550            .register("alice", "alice@example.com", "Password123!")
551            .await
552            .unwrap();
553        framework
554            .authorization()
555            .create_role(Role::new("auditor"))
556            .await
557            .unwrap();
558        framework
559            .authorization()
560            .assign_role(&user_id, "auditor")
561            .await
562            .unwrap();
563        framework
564            .tokens()
565            .create(&user_id, &["read"], "jwt", None)
566            .await
567            .unwrap();
568        framework
569            .sessions()
570            .create(
571                &user_id,
572                Duration::from_secs(900),
573                Some("127.0.0.1".into()),
574                None,
575            )
576            .await
577            .unwrap();
578        framework
579            .storage()
580            .store_kv("custom:test", b"value", None)
581            .await
582            .unwrap();
583
584        let dir = tempdir().unwrap();
585        let path = dir.path().join("snapshot.json");
586
587        backup_to_file(&framework, &path, false).await.unwrap();
588        reset_runtime_data(&framework, false).await.unwrap();
589        assert!(
590            framework
591                .users()
592                .list_with_query(UserListQuery::new())
593                .await
594                .unwrap()
595                .is_empty()
596        );
597
598        restore_from_file(&framework, &path, false).await.unwrap();
599
600        let restored_user = framework.users().get(&user_id).await.unwrap();
601        assert_eq!(restored_user.username, "alice");
602        assert!(
603            framework
604                .authorization()
605                .has_role(&user_id, "auditor")
606                .await
607                .unwrap()
608        );
609        assert_eq!(
610            framework
611                .tokens()
612                .list_for_user(&user_id)
613                .await
614                .unwrap()
615                .len(),
616            1
617        );
618        assert_eq!(
619            framework
620                .sessions()
621                .list_for_user(&user_id)
622                .await
623                .unwrap()
624                .len(),
625            1
626        );
627        assert_eq!(
628            framework
629                .storage()
630                .get_kv("custom:test")
631                .await
632                .unwrap()
633                .unwrap(),
634            b"value"
635        );
636    }
637
638    #[tokio::test]
639    async fn reset_dry_run_leaves_state_unchanged() {
640        let framework = create_framework().await;
641        let user_id = framework
642            .users()
643            .register("bob", "bob@example.com", "Password123!")
644            .await
645            .unwrap();
646        framework
647            .storage()
648            .store_kv("custom:dry-run", b"present", None)
649            .await
650            .unwrap();
651
652        let report = reset_runtime_data(&framework, true).await.unwrap();
653        assert!(report.dry_run);
654        assert_eq!(
655            framework.users().get(&user_id).await.unwrap().username,
656            "bob"
657        );
658        assert!(
659            framework
660                .storage()
661                .get_kv("custom:dry-run")
662                .await
663                .unwrap()
664                .is_some()
665        );
666    }
667
668    #[tokio::test]
669    async fn create_migration_file_uses_backend_directory_and_sanitized_name() {
670        let dir = tempdir().unwrap();
671        let old_dir = std::env::current_dir().unwrap();
672        std::env::set_current_dir(dir.path()).unwrap();
673
674        let outcome = async {
675            let mut config = AppConfig::default();
676            config.database.url = "sqlite::memory:".to_string();
677            let report = create_migration_file(&config, "Add Audit Table!")
678                .await
679                .unwrap();
680            assert_eq!(report.backend, "sqlite");
681            assert!(
682                report
683                    .path
684                    .starts_with(Path::new("migrations").join("sqlite"))
685            );
686            assert!(
687                report
688                    .path
689                    .file_name()
690                    .unwrap()
691                    .to_string_lossy()
692                    .contains("add_audit_table")
693            );
694        }
695        .await;
696
697        std::env::set_current_dir(old_dir).unwrap();
698        outcome
699    }
700
701    #[tokio::test]
702    async fn backup_dry_run_does_not_write_file() {
703        let dir = tempdir().unwrap();
704        let path = dir.path().join("shouldnt_exist.json");
705        let framework = create_framework().await;
706        let report = backup_to_file(&framework, &path, true).await.unwrap();
707        assert!(report.dry_run);
708        assert!(!path.exists());
709    }
710
711    #[tokio::test]
712    async fn backup_empty_framework() {
713        let dir = tempdir().unwrap();
714        let path = dir.path().join("empty.json");
715        let framework = create_framework().await;
716        let report = backup_to_file(&framework, &path, false).await.unwrap();
717        assert_eq!(report.manifest.user_count, 0);
718        assert_eq!(report.manifest.token_count, 0);
719        assert_eq!(report.manifest.session_count, 0);
720        assert!(path.exists());
721    }
722
723    #[tokio::test]
724    async fn reset_clears_all_data() {
725        let framework = create_framework().await;
726        framework
727            .users()
728            .register("clear_me", "clear@example.com", "Password123!")
729            .await
730            .unwrap();
731        framework
732            .storage()
733            .store_kv("custom:keep", b"nope", None)
734            .await
735            .unwrap();
736
737        let report = reset_runtime_data(&framework, false).await.unwrap();
738        assert!(!report.dry_run);
739        assert!(report.users_deleted >= 1);
740        assert!(
741            framework
742                .users()
743                .list_with_query(UserListQuery::new())
744                .await
745                .unwrap()
746                .is_empty()
747        );
748        assert!(
749            framework
750                .storage()
751                .get_kv("custom:keep")
752                .await
753                .unwrap()
754                .is_none()
755        );
756    }
757
758    #[tokio::test]
759    async fn restore_nonexistent_file_fails() {
760        let framework = create_framework().await;
761        let result = restore_from_file(&framework, "/definitely/not/real.json", false).await;
762        assert!(result.is_err());
763    }
764
765    #[tokio::test]
766    async fn backup_manifest_has_checksum() {
767        let dir = tempdir().unwrap();
768        let path = dir.path().join("checksummed.json");
769        let framework = create_framework().await;
770        framework
771            .users()
772            .register("chk_user", "chk@example.com", "Password123!")
773            .await
774            .unwrap();
775        let report = backup_to_file(&framework, &path, false).await.unwrap();
776        assert!(!report.manifest.checksum_sha256.is_empty());
777        assert_eq!(report.manifest.format_version, SNAPSHOT_FORMAT_VERSION);
778    }
779}