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