1use 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}