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(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}