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::storage::encryption::StorageEncryption;
22use crate::tokens::AuthToken;
23use base64::Engine;
24use base64::engine::general_purpose::STANDARD as BASE64_STANDARD;
25use chrono::{DateTime, Utc};
26use serde::{Deserialize, Serialize};
27use serde_json::{Map, Value};
28use sha2::{Digest, Sha256};
29use std::collections::HashSet;
30use std::path::{Path, PathBuf};
31use zeroize::Zeroize;
32
33const SNAPSHOT_FORMAT_VERSION: u32 = 1;
34
35#[derive(Debug, Clone, Serialize, Deserialize)]
36pub struct SnapshotManifest {
37 pub format_version: u32,
38 pub created_at: DateTime<Utc>,
39 pub storage_backend: String,
40 pub user_count: usize,
41 pub role_count: usize,
42 pub token_count: usize,
43 pub session_count: usize,
44 pub kv_entry_count: usize,
45 pub checksum_sha256: String,
46}
47
48#[derive(Debug, Clone, Serialize, Deserialize)]
49pub struct SnapshotUserSummary {
50 pub id: String,
51 pub username: String,
52 pub email: Option<String>,
53 pub roles: Vec<String>,
54 pub active: bool,
55}
56
57#[derive(Debug, Clone, Serialize, Deserialize)]
58pub struct SnapshotKvEntry {
59 pub key: String,
60 pub value_base64: String,
61 #[serde(default, skip_serializing_if = "Option::is_none")]
65 pub expires_at: Option<DateTime<Utc>>,
66}
67
68#[derive(Debug, Clone, Copy, PartialEq, Eq)]
70enum RestoreTtl {
71 Forever,
73 Remaining(std::time::Duration),
75 Expired,
77}
78
79fn restore_ttl(expires_at: Option<DateTime<Utc>>, now: DateTime<Utc>) -> RestoreTtl {
80 match expires_at {
81 None => RestoreTtl::Forever,
82 Some(expires_at) => match (expires_at - now).to_std() {
83 Ok(remaining) if !remaining.is_zero() => RestoreTtl::Remaining(remaining),
84 _ => RestoreTtl::Expired,
85 },
86 }
87}
88
89const SNAPSHOT_AAD: &[u8] = b"auth-framework:maintenance-snapshot:v1";
92
93#[derive(Debug, Clone, Serialize, Deserialize)]
94pub struct MaintenanceSnapshot {
95 pub manifest: SnapshotManifest,
96 pub users: Vec<SnapshotUserSummary>,
97 pub roles: Vec<Role>,
98 pub tokens: Vec<AuthToken>,
99 pub sessions: Vec<SessionData>,
100 pub kv_entries: Vec<SnapshotKvEntry>,
101}
102
103#[derive(Debug, Clone)]
104pub struct BackupReport {
105 pub manifest: SnapshotManifest,
106 pub output_path: PathBuf,
107 pub dry_run: bool,
108}
109
110#[derive(Debug, Clone)]
111pub struct ResetReport {
112 pub users_deleted: usize,
113 pub roles_seen: usize,
114 pub tokens_deleted: usize,
115 pub sessions_deleted: usize,
116 pub kv_entries_deleted: usize,
117 pub dry_run: bool,
118}
119
120#[derive(Debug, Clone)]
121pub struct RestoreReport {
122 pub manifest: SnapshotManifest,
123 pub input_path: PathBuf,
124 pub reset_report: ResetReport,
125 pub dry_run: bool,
126}
127
128#[derive(Debug, Clone)]
129pub struct MigrationFileReport {
130 pub backend: String,
131 pub path: PathBuf,
132}
133
134#[derive(Serialize)]
135struct SnapshotChecksumPayload<'a> {
136 users: &'a [SnapshotUserSummary],
137 roles: &'a [Role],
138 tokens: &'a [AuthToken],
139 sessions: &'a [SessionData],
140 kv_entries: &'a [SnapshotKvEntry],
141}
142
143fn normalize_json_value(value: Value) -> Value {
144 match value {
145 Value::Array(values) => {
146 let mut normalized = values
147 .into_iter()
148 .map(normalize_json_value)
149 .collect::<Vec<_>>();
150 normalized.sort_by_key(|left| left.to_string());
151 Value::Array(normalized)
152 }
153 Value::Object(object) => {
154 let mut entries = object.into_iter().collect::<Vec<_>>();
155 entries.sort_by(|left, right| left.0.cmp(&right.0));
156
157 let normalized = entries
158 .into_iter()
159 .map(|(key, value)| (key, normalize_json_value(value)))
160 .collect::<Map<String, Value>>();
161 Value::Object(normalized)
162 }
163 other => other,
164 }
165}
166
167fn storage_backend_name(config: &StorageConfig) -> &'static str {
168 match config {
169 StorageConfig::Memory => "memory",
170 #[cfg(feature = "postgres-storage")]
171 StorageConfig::Postgres { .. } => "postgres",
172 #[cfg(feature = "redis-storage")]
173 StorageConfig::Redis { .. } => "redis",
174 #[cfg(feature = "sqlite-storage")]
175 StorageConfig::Sqlite { .. } => "sqlite",
176 StorageConfig::Custom(_) => "custom",
177 }
178}
179
180fn backend_name_from_database_url(database_url: &str) -> &'static str {
181 let database_url = database_url.trim().to_ascii_lowercase();
182
183 if database_url.starts_with("postgres://") || database_url.starts_with("postgresql://") {
184 "postgres"
185 } else if database_url.starts_with("mysql://") {
186 "mysql"
187 } else if database_url.starts_with("sqlite:") || database_url.ends_with(".db") {
188 "sqlite"
189 } else if database_url.starts_with("redis://") || database_url.starts_with("rediss://") {
190 "redis"
191 } else if database_url.is_empty() {
192 "memory"
193 } else {
194 "custom"
195 }
196}
197
198fn checksum_snapshot(
199 users: &[SnapshotUserSummary],
200 roles: &[Role],
201 tokens: &[AuthToken],
202 sessions: &[SessionData],
203 kv_entries: &[SnapshotKvEntry],
204) -> Result<String> {
205 let payload = SnapshotChecksumPayload {
206 users,
207 roles,
208 tokens,
209 sessions,
210 kv_entries,
211 };
212 let encoded = serde_json::to_value(&payload)
213 .map(normalize_json_value)
214 .and_then(|value| serde_json::to_vec(&value))
215 .map_err(|e| AuthError::internal(format!("Failed to serialize snapshot payload: {e}")))?;
216 let mut hasher = Sha256::new();
217 hasher.update(encoded);
218 Ok(hex::encode(hasher.finalize()))
219}
220
221fn sanitize_migration_name(name: &str) -> Result<String> {
222 let sanitized = name
223 .trim()
224 .chars()
225 .map(|character| {
226 if character.is_ascii_alphanumeric() {
227 character.to_ascii_lowercase()
228 } else {
229 '_'
230 }
231 })
232 .collect::<String>();
233
234 let collapsed = sanitized
235 .split('_')
236 .filter(|segment| !segment.is_empty())
237 .collect::<Vec<_>>()
238 .join("_");
239
240 if collapsed.is_empty() {
241 return Err(AuthError::validation(
242 "Migration name must contain at least one alphanumeric character",
243 ));
244 }
245
246 Ok(collapsed)
247}
248
249async fn collect_snapshot(framework: &AuthFramework) -> Result<MaintenanceSnapshot> {
250 let storage = framework.storage();
251
252 let mut users = framework
253 .users()
254 .list_with_query(UserListQuery::new())
255 .await?;
256 users.sort_by(|left, right| left.id.cmp(&right.id));
257
258 let mut snapshot_users = Vec::with_capacity(users.len());
259 for user in &users {
260 let mut roles: HashSet<String> = user.roles.iter().cloned().collect();
261 roles.extend(framework.authorization().roles_for_user(&user.id).await?);
262 let mut roles = roles.into_iter().collect::<Vec<_>>();
263 roles.sort();
264
265 snapshot_users.push(SnapshotUserSummary {
266 id: user.id.clone(),
267 username: user.username.clone(),
268 email: user.email.clone(),
269 roles,
270 active: user.active,
271 });
272 }
273
274 let mut roles = framework.authorization().list_roles().await;
275 roles.sort_by(|left, right| left.name.cmp(&right.name));
276
277 let mut tokens = Vec::new();
278 let mut seen_tokens = HashSet::new();
279 let mut sessions = Vec::new();
280 let mut seen_sessions = HashSet::new();
281
282 for user in &users {
283 for token in framework.tokens().list_for_user(&user.id).await? {
284 if seen_tokens.insert(token.token_id.clone()) {
285 tokens.push(token);
286 }
287 }
288
289 for session in framework.sessions().list_for_user(&user.id).await? {
290 if seen_sessions.insert(session.session_id.clone()) {
291 sessions.push(session);
292 }
293 }
294 }
295
296 tokens.sort_by(|left, right| left.token_id.cmp(&right.token_id));
297 sessions.sort_by(|left, right| left.session_id.cmp(&right.session_id));
298
299 if !storage.tracks_kv_ttl() {
300 tracing::warn!(
301 "This storage backend does not report KV TTLs: the snapshot cannot record them, \
302 so every KV entry restored from it becomes permanent, including ones that were \
303 meant to expire (one-time codes, rate-limit windows, expiring API keys)."
304 );
305 }
306
307 let mut kv_keys = storage.list_kv_keys("").await?;
308 kv_keys.sort();
309 kv_keys.dedup();
310
311 let mut kv_entries = Vec::with_capacity(kv_keys.len());
312 for key in kv_keys {
313 let expires_at = match storage.get_kv_ttl(&key).await? {
317 Some(remaining) => Some(
318 Utc::now()
319 + chrono::Duration::from_std(remaining)
320 .map_err(|e| AuthError::internal(format!("Invalid KV TTL: {e}")))?,
321 ),
322 None => None,
323 };
324 if let Some(value) = storage.get_kv(&key).await? {
325 kv_entries.push(SnapshotKvEntry {
326 key,
327 value_base64: BASE64_STANDARD.encode(value),
328 expires_at,
329 });
330 }
331 }
332
333 let manifest = SnapshotManifest {
334 format_version: SNAPSHOT_FORMAT_VERSION,
335 created_at: Utc::now(),
336 storage_backend: storage_backend_name(&framework.config().storage).to_string(),
337 user_count: snapshot_users.len(),
338 role_count: roles.len(),
339 token_count: tokens.len(),
340 session_count: sessions.len(),
341 kv_entry_count: kv_entries.len(),
342 checksum_sha256: checksum_snapshot(
343 &snapshot_users,
344 &roles,
345 &tokens,
346 &sessions,
347 &kv_entries,
348 )?,
349 };
350
351 Ok(MaintenanceSnapshot {
352 manifest,
353 users: snapshot_users,
354 roles,
355 tokens,
356 sessions,
357 kv_entries,
358 })
359}
360
361fn validate_snapshot(snapshot: &MaintenanceSnapshot) -> Result<()> {
362 if snapshot.manifest.format_version != SNAPSHOT_FORMAT_VERSION {
363 return Err(AuthError::configuration(format!(
364 "Unsupported snapshot format version {}",
365 snapshot.manifest.format_version
366 )));
367 }
368
369 let expected_checksum = checksum_snapshot(
370 &snapshot.users,
371 &snapshot.roles,
372 &snapshot.tokens,
373 &snapshot.sessions,
374 &snapshot.kv_entries,
375 )?;
376
377 if expected_checksum != snapshot.manifest.checksum_sha256 {
378 return Err(AuthError::validation(
379 "Snapshot checksum validation failed; restore aborted",
380 ));
381 }
382
383 Ok(())
384}
385
386pub async fn backup_to_file(
387 framework: &AuthFramework,
388 output_path: impl AsRef<Path>,
389 dry_run: bool,
390) -> Result<BackupReport> {
391 let encryption = snapshot_encryption(framework)?;
392 backup_to_file_with(framework, output_path, dry_run, encryption.as_ref()).await
393}
394
395fn snapshot_encryption(framework: &AuthFramework) -> Result<Option<StorageEncryption>> {
414 let config = framework.config();
415 if !config.storage_encryption.enabled || matches!(config.storage, StorageConfig::Memory) {
416 tracing::warn!(
417 "Maintenance snapshot is NOT encrypted (config.storage is Memory, or \
418 storage_encryption.enabled = false): it holds tokens, sessions and KV \
419 secrets in plaintext."
420 );
421 return Ok(None);
422 }
423 StorageEncryption::from_env().map(Some).map_err(|e| {
424 AuthError::configuration(format!(
425 "Snapshots are encrypted with the storage encryption key, but none could be \
426 loaded: {e}. Configure AUTH_STORAGE_ENCRYPTION_KEY / \
427 AUTH_STORAGE_ENCRYPTION_KEYS_FILE."
428 ))
429 })
430}
431
432async fn backup_to_file_with(
433 framework: &AuthFramework,
434 output_path: impl AsRef<Path>,
435 dry_run: bool,
436 encryption: Option<&StorageEncryption>,
437) -> Result<BackupReport> {
438 let output_path = output_path.as_ref().to_path_buf();
439 let snapshot = collect_snapshot(framework).await?;
440
441 if !dry_run {
442 if let Some(parent) = output_path.parent()
443 && !parent.as_os_str().is_empty()
444 {
445 tokio::fs::create_dir_all(parent).await?;
446 }
447
448 let mut data = serde_json::to_vec_pretty(&snapshot).map_err(|e| {
449 AuthError::internal(format!("Failed to serialize maintenance snapshot: {e}"))
450 })?;
451 if let Some(encryption) = encryption {
452 let sealed = encryption.encrypt_for_storage(&data, SNAPSHOT_AAD);
453 data.zeroize();
454 data = sealed?;
455 }
456 tokio::fs::write(&output_path, data).await?;
457 }
458
459 Ok(BackupReport {
460 manifest: snapshot.manifest,
461 output_path,
462 dry_run,
463 })
464}
465
466pub async fn reset_runtime_data(framework: &AuthFramework, dry_run: bool) -> Result<ResetReport> {
467 let storage = framework.storage();
468 let users = framework
469 .users()
470 .list_with_query(UserListQuery::new())
471 .await?;
472 let roles = framework.authorization().list_roles().await;
473
474 let mut token_ids = HashSet::new();
475 let mut session_ids = HashSet::new();
476 for user in &users {
477 for token in framework.tokens().list_for_user(&user.id).await? {
478 token_ids.insert(token.token_id);
479 }
480
481 for session in framework.sessions().list_for_user(&user.id).await? {
482 session_ids.insert(session.session_id);
483 }
484 }
485
486 let mut kv_keys = storage.list_kv_keys("").await?;
487 kv_keys.sort();
488 kv_keys.dedup();
489
490 if !dry_run {
491 for token_id in &token_ids {
492 storage.delete_token(token_id).await?;
493 }
494
495 for session_id in &session_ids {
496 storage.delete_session(session_id).await?;
497 }
498
499 for user in &users {
500 framework.users().delete_by_id(&user.id).await?;
501 }
502
503 for key in &kv_keys {
504 storage.delete_kv(key).await?;
505 }
506
507 framework.reset_authorization_runtime().await;
508 }
509
510 Ok(ResetReport {
511 users_deleted: users.len(),
512 roles_seen: roles.len(),
513 tokens_deleted: token_ids.len(),
514 sessions_deleted: session_ids.len(),
515 kv_entries_deleted: kv_keys.len(),
516 dry_run,
517 })
518}
519
520pub async fn restore_from_file(
521 framework: &AuthFramework,
522 input_path: impl AsRef<Path>,
523 dry_run: bool,
524) -> Result<RestoreReport> {
525 let encryption = snapshot_encryption(framework)?;
526 restore_from_file_with(framework, input_path, dry_run, encryption.as_ref()).await
527}
528
529async fn restore_from_file_with(
530 framework: &AuthFramework,
531 input_path: impl AsRef<Path>,
532 dry_run: bool,
533 encryption: Option<&StorageEncryption>,
534) -> Result<RestoreReport> {
535 let input_path = input_path.as_ref().to_path_buf();
536 let mut data = tokio::fs::read(&input_path).await?;
537 if let Some(envelope) = StorageEncryption::parse_envelope(&data) {
538 let encryption = encryption.ok_or_else(|| {
541 AuthError::validation(
542 "Snapshot is encrypted but no storage encryption key is available to open it",
543 )
544 })?;
545 if envelope.v == 0 {
551 return Err(AuthError::validation(
552 "Snapshot uses an unsupported legacy encryption format",
553 ));
554 }
555 data = encryption.decrypt(&envelope, SNAPSHOT_AAD).map_err(|e| {
556 AuthError::validation(format!(
557 "Failed to decrypt snapshot (wrong key or corrupted file): {e}"
558 ))
559 })?;
560 } else if encryption.is_some() {
561 return Err(AuthError::validation(
566 "Snapshot is not encrypted but storage encryption is enabled; refusing to restore it",
567 ));
568 }
569 let snapshot: MaintenanceSnapshot = serde_json::from_slice(&data)
570 .map_err(|e| AuthError::validation(format!("Failed to parse maintenance snapshot: {e}")))?;
571 validate_snapshot(&snapshot)?;
572
573 let now = Utc::now();
576 let mut kv_to_restore = Vec::with_capacity(snapshot.kv_entries.len());
577 for entry in &snapshot.kv_entries {
578 let value = BASE64_STANDARD.decode(&entry.value_base64).map_err(|e| {
579 AuthError::validation(format!(
580 "Snapshot KV entry '{}' is not valid base64: {e}",
581 entry.key
582 ))
583 })?;
584 let ttl = match restore_ttl(entry.expires_at, now) {
585 RestoreTtl::Forever => None,
586 RestoreTtl::Remaining(remaining) => Some(remaining),
587 RestoreTtl::Expired => continue,
588 };
589 kv_to_restore.push((entry.key.as_str(), value, ttl));
590 }
591
592 let reset_report = reset_runtime_data(framework, dry_run).await?;
593
594 if !dry_run {
595 let storage = framework.storage();
596
597 for (key, value, ttl) in &kv_to_restore {
598 storage.store_kv(key, value, *ttl).await?;
599 }
600
601 for token in &snapshot.tokens {
602 storage.store_token(token).await?;
603 }
604
605 for session in &snapshot.sessions {
606 storage.store_session(&session.session_id, session).await?;
607 }
608
609 framework.reset_authorization_runtime().await;
610 for role in &snapshot.roles {
611 framework.authorization().create_role(role.clone()).await?;
612 }
613 for user in &snapshot.users {
614 for role_name in &user.roles {
615 framework
616 .authorization()
617 .assign_role(&user.id, role_name)
618 .await?;
619 }
620 }
621 }
622
623 Ok(RestoreReport {
624 manifest: snapshot.manifest,
625 input_path,
626 reset_report,
627 dry_run,
628 })
629}
630
631fn build_migration_template(backend: &str, migration_name: &str, original_name: &str) -> String {
632 format!(
633 "-- 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",
634 Utc::now().to_rfc3339(),
635 )
636}
637
638pub async fn create_migration_file(config: &AppConfig, name: &str) -> Result<MigrationFileReport> {
639 let backend = backend_name_from_database_url(&config.database.url).to_string();
640 create_migration_template_for_backend(&backend, name).await
641}
642
643pub async fn create_migration_file_for_storage(
644 storage: &StorageConfig,
645 name: &str,
646) -> Result<MigrationFileReport> {
647 let backend = storage_backend_name(storage).to_string();
648 create_migration_template_for_backend(&backend, name).await
649}
650
651async fn create_migration_template_for_backend(
652 backend: &str,
653 name: &str,
654) -> Result<MigrationFileReport> {
655 let sanitized_name = sanitize_migration_name(name)?;
656 let directory = PathBuf::from("migrations").join(backend);
657 tokio::fs::create_dir_all(&directory).await?;
658
659 let file_name = format!(
660 "{}_{}.sql",
661 Utc::now().format("%Y%m%d%H%M%S"),
662 sanitized_name
663 );
664 let path = directory.join(file_name);
665 let template = build_migration_template(backend, &sanitized_name, name);
666 tokio::fs::write(&path, template).await?;
667
668 Ok(MigrationFileReport {
669 backend: backend.to_string(),
670 path,
671 })
672}
673
674#[cfg(test)]
675mod tests {
676 use super::*;
677 use crate::config::AuthConfig;
678 use crate::methods::{AuthMethodEnum, JwtMethod};
679 use std::time::Duration;
680 use tempfile::tempdir;
681
682 async fn create_framework() -> AuthFramework {
683 let config = AuthConfig::new()
684 .secret("0123456789abcdef0123456789abcdef")
685 .token_lifetime(Duration::from_secs(3600));
686 let mut framework = AuthFramework::new(config);
687 framework.register_method("jwt", AuthMethodEnum::Jwt(JwtMethod::new()));
688 framework.initialize().await.unwrap();
689 framework
690 }
691
692 #[tokio::test]
693 async fn backup_restore_roundtrip_preserves_runtime_state() {
694 let framework = create_framework().await;
695 let user_id = framework
696 .users()
697 .register("alice", "alice@example.com", "Password123!")
698 .await
699 .unwrap();
700 framework
701 .authorization()
702 .create_role(Role::new("auditor"))
703 .await
704 .unwrap();
705 framework
706 .authorization()
707 .assign_role(&user_id, "auditor")
708 .await
709 .unwrap();
710 framework
711 .tokens()
712 .create(&user_id, &["read"], "jwt", None)
713 .await
714 .unwrap();
715 framework
716 .sessions()
717 .create(
718 &user_id,
719 Duration::from_secs(900),
720 Some("127.0.0.1".into()),
721 None,
722 )
723 .await
724 .unwrap();
725 framework
726 .storage()
727 .store_kv("custom:test", b"value", None)
728 .await
729 .unwrap();
730
731 let dir = tempdir().unwrap();
732 let path = dir.path().join("snapshot.json");
733
734 backup_to_file(&framework, &path, false).await.unwrap();
735 reset_runtime_data(&framework, false).await.unwrap();
736 assert!(
737 framework
738 .users()
739 .list_with_query(UserListQuery::new())
740 .await
741 .unwrap()
742 .is_empty()
743 );
744
745 restore_from_file(&framework, &path, false).await.unwrap();
746
747 let restored_user = framework.users().get(&user_id).await.unwrap();
748 assert_eq!(restored_user.username, "alice");
749 assert!(
750 framework
751 .authorization()
752 .has_role(&user_id, "auditor")
753 .await
754 .unwrap()
755 );
756 assert_eq!(
757 framework
758 .tokens()
759 .list_for_user(&user_id)
760 .await
761 .unwrap()
762 .len(),
763 1
764 );
765 assert_eq!(
766 framework
767 .sessions()
768 .list_for_user(&user_id)
769 .await
770 .unwrap()
771 .len(),
772 1
773 );
774 assert_eq!(
775 framework
776 .storage()
777 .get_kv("custom:test")
778 .await
779 .unwrap()
780 .unwrap(),
781 b"value"
782 );
783 }
784
785 #[tokio::test]
786 async fn reset_dry_run_leaves_state_unchanged() {
787 let framework = create_framework().await;
788 let user_id = framework
789 .users()
790 .register("bob", "bob@example.com", "Password123!")
791 .await
792 .unwrap();
793 framework
794 .storage()
795 .store_kv("custom:dry-run", b"present", None)
796 .await
797 .unwrap();
798
799 let report = reset_runtime_data(&framework, true).await.unwrap();
800 assert!(report.dry_run);
801 assert_eq!(
802 framework.users().get(&user_id).await.unwrap().username,
803 "bob"
804 );
805 assert!(
806 framework
807 .storage()
808 .get_kv("custom:dry-run")
809 .await
810 .unwrap()
811 .is_some()
812 );
813 }
814
815 #[tokio::test]
816 async fn create_migration_file_uses_backend_directory_and_sanitized_name() {
817 let dir = tempdir().unwrap();
818 let old_dir = std::env::current_dir().unwrap();
819 std::env::set_current_dir(dir.path()).unwrap();
820
821 let outcome = async {
822 let mut config = AppConfig::default();
823 config.database.url = "sqlite::memory:".to_string();
824 let report = create_migration_file(&config, "Add Audit Table!")
825 .await
826 .unwrap();
827 assert_eq!(report.backend, "sqlite");
828 assert!(
829 report
830 .path
831 .starts_with(Path::new("migrations").join("sqlite"))
832 );
833 assert!(
834 report
835 .path
836 .file_name()
837 .unwrap()
838 .to_string_lossy()
839 .contains("add_audit_table")
840 );
841 }
842 .await;
843
844 std::env::set_current_dir(old_dir).unwrap();
845 outcome
846 }
847
848 const CANARY: &[u8] = b"totp-seed-PLAINTEXT-CANARY-7f3a91";
849
850 async fn framework_with_secrets() -> (AuthFramework, String) {
851 let framework = create_framework().await;
852 let user_id = framework
853 .users()
854 .register("alice", "alice@example.com", "Password123!")
855 .await
856 .unwrap();
857 framework
858 .tokens()
859 .create(&user_id, &["read"], "jwt", None)
860 .await
861 .unwrap();
862 framework
863 .storage()
864 .store_kv("totp:alice", CANARY, None)
865 .await
866 .unwrap();
867 let access_token = framework
868 .tokens()
869 .list_for_user(&user_id)
870 .await
871 .unwrap()
872 .remove(0)
873 .access_token;
874 (framework, access_token)
875 }
876
877 fn contains(haystack: &[u8], needle: &[u8]) -> bool {
878 haystack.windows(needle.len()).any(|w| w == needle)
879 }
880
881 #[tokio::test]
885 async fn encrypted_backup_contains_no_plaintext() {
886 let (framework, access_token) = framework_with_secrets().await;
887 let dir = tempdir().unwrap();
888
889 let plain_path = dir.path().join("plain.json");
892 backup_to_file_with(&framework, &plain_path, false, None)
893 .await
894 .unwrap();
895 let plain = tokio::fs::read(&plain_path).await.unwrap();
896 let canary_b64 = BASE64_STANDARD.encode(CANARY);
897 assert!(contains(&plain, canary_b64.as_bytes()));
898 assert!(contains(&plain, access_token.as_bytes()));
899 assert!(contains(&plain, b"alice@example.com"));
900
901 let encryption = StorageEncryption::new_random();
902 let enc_path = dir.path().join("encrypted.json");
903 backup_to_file_with(&framework, &enc_path, false, Some(&encryption))
904 .await
905 .unwrap();
906 let bytes = tokio::fs::read(&enc_path).await.unwrap();
907 assert!(!contains(&bytes, CANARY), "raw KV secret in backup");
908 assert!(
909 !contains(&bytes, canary_b64.as_bytes()),
910 "base64 KV secret in backup"
911 );
912 assert!(
913 !contains(&bytes, access_token.as_bytes()),
914 "access token in backup"
915 );
916 assert!(!contains(&bytes, b"alice@example.com"), "PII in backup");
917 }
918
919 #[tokio::test]
920 async fn encrypted_backup_roundtrips_and_rejects_wrong_or_missing_key() {
921 let (framework, _) = framework_with_secrets().await;
922 let dir = tempdir().unwrap();
923 let path = dir.path().join("encrypted.json");
924 let encryption = StorageEncryption::new_random();
925 backup_to_file_with(&framework, &path, false, Some(&encryption))
926 .await
927 .unwrap();
928
929 let other = StorageEncryption::new_random();
932 assert!(
933 restore_from_file_with(&framework, &path, false, Some(&other))
934 .await
935 .is_err()
936 );
937 assert!(
938 restore_from_file_with(&framework, &path, false, None)
939 .await
940 .is_err()
941 );
942 assert_eq!(
943 framework
944 .storage()
945 .get_kv("totp:alice")
946 .await
947 .unwrap()
948 .as_deref(),
949 Some(CANARY),
950 "a refused restore must not have reset the live data"
951 );
952
953 reset_runtime_data(&framework, false).await.unwrap();
954 assert!(
955 framework
956 .storage()
957 .get_kv("totp:alice")
958 .await
959 .unwrap()
960 .is_none()
961 );
962 restore_from_file_with(&framework, &path, false, Some(&encryption))
963 .await
964 .unwrap();
965 assert_eq!(
966 framework
967 .storage()
968 .get_kv("totp:alice")
969 .await
970 .unwrap()
971 .as_deref(),
972 Some(CANARY)
973 );
974 }
975
976 #[tokio::test]
980 async fn restore_refuses_an_unsealed_snapshot_when_sealing_is_expected() {
981 let (framework, _) = framework_with_secrets().await;
982 let dir = tempdir().unwrap();
983 let path = dir.path().join("plain.json");
984 backup_to_file_with(&framework, &path, false, None)
985 .await
986 .unwrap();
987
988 let encryption = StorageEncryption::new_random();
989 assert!(
990 restore_from_file_with(&framework, &path, false, Some(&encryption))
991 .await
992 .is_err()
993 );
994 assert!(
995 framework
996 .storage()
997 .get_kv("totp:alice")
998 .await
999 .unwrap()
1000 .is_some(),
1001 "a refused restore must not have reset the live data"
1002 );
1003 restore_from_file_with(&framework, &path, false, None)
1005 .await
1006 .unwrap();
1007 }
1008
1009 #[tokio::test]
1011 async fn restore_with_a_corrupt_kv_entry_leaves_live_data_untouched() {
1012 let (framework, _) = framework_with_secrets().await;
1013 let dir = tempdir().unwrap();
1014 let path = dir.path().join("snapshot.json");
1015 let mut snapshot = collect_snapshot(&framework).await.unwrap();
1016 snapshot.kv_entries[0].value_base64 = "!!not base64!!".to_string();
1017 snapshot.manifest.checksum_sha256 = checksum_snapshot(
1018 &snapshot.users,
1019 &snapshot.roles,
1020 &snapshot.tokens,
1021 &snapshot.sessions,
1022 &snapshot.kv_entries,
1023 )
1024 .unwrap();
1025 tokio::fs::write(&path, serde_json::to_vec(&snapshot).unwrap())
1026 .await
1027 .unwrap();
1028
1029 assert!(
1030 restore_from_file_with(&framework, &path, false, None)
1031 .await
1032 .is_err()
1033 );
1034 assert_eq!(
1035 framework
1036 .users()
1037 .list_with_query(UserListQuery::new())
1038 .await
1039 .unwrap()
1040 .len(),
1041 1,
1042 "a refused restore must not have reset the live data"
1043 );
1044 }
1045
1046 #[tokio::test]
1048 async fn backup_restore_preserves_kv_ttl() {
1049 let framework = create_framework().await;
1050 let storage = framework.storage();
1051 storage
1052 .store_kv("otp:code", b"123456", Some(Duration::from_secs(3600)))
1053 .await
1054 .unwrap();
1055 storage.store_kv("keep:forever", b"x", None).await.unwrap();
1056 assert!(
1057 storage.get_kv_ttl("otp:code").await.unwrap().is_some(),
1058 "precondition: the backend must report the TTL it was given"
1059 );
1060
1061 let dir = tempdir().unwrap();
1062 let path = dir.path().join("snapshot.json");
1063 backup_to_file_with(&framework, &path, false, None)
1064 .await
1065 .unwrap();
1066 reset_runtime_data(&framework, false).await.unwrap();
1067 restore_from_file_with(&framework, &path, false, None)
1068 .await
1069 .unwrap();
1070
1071 let ttl = storage.get_kv_ttl("otp:code").await.unwrap().unwrap();
1072 assert!(
1073 ttl > Duration::from_secs(3500) && ttl <= Duration::from_secs(3600),
1074 "restored TTL was {ttl:?}"
1075 );
1076 assert_eq!(storage.get_kv_ttl("keep:forever").await.unwrap(), None);
1077 assert!(storage.get_kv("keep:forever").await.unwrap().is_some());
1078 }
1079
1080 #[test]
1081 fn restore_ttl_maps_expiry_to_action() {
1082 let now = Utc::now();
1083 assert_eq!(restore_ttl(None, now), RestoreTtl::Forever);
1084 assert_eq!(
1085 restore_ttl(Some(now + chrono::Duration::seconds(90)), now),
1086 RestoreTtl::Remaining(Duration::from_secs(90))
1087 );
1088 assert_eq!(
1089 restore_ttl(Some(now - chrono::Duration::seconds(1)), now),
1090 RestoreTtl::Expired
1091 );
1092 assert_eq!(restore_ttl(Some(now), now), RestoreTtl::Expired);
1093 }
1094
1095 #[tokio::test]
1096 async fn backup_dry_run_does_not_write_file() {
1097 let dir = tempdir().unwrap();
1098 let path = dir.path().join("shouldnt_exist.json");
1099 let framework = create_framework().await;
1100 let report = backup_to_file(&framework, &path, true).await.unwrap();
1101 assert!(report.dry_run);
1102 assert!(!path.exists());
1103 }
1104
1105 #[tokio::test]
1106 async fn backup_empty_framework() {
1107 let dir = tempdir().unwrap();
1108 let path = dir.path().join("empty.json");
1109 let framework = create_framework().await;
1110 let report = backup_to_file(&framework, &path, false).await.unwrap();
1111 assert_eq!(report.manifest.user_count, 0);
1112 assert_eq!(report.manifest.token_count, 0);
1113 assert_eq!(report.manifest.session_count, 0);
1114 assert!(path.exists());
1115 }
1116
1117 #[tokio::test]
1118 async fn reset_clears_all_data() {
1119 let framework = create_framework().await;
1120 framework
1121 .users()
1122 .register("clear_me", "clear@example.com", "Password123!")
1123 .await
1124 .unwrap();
1125 framework
1126 .storage()
1127 .store_kv("custom:keep", b"nope", None)
1128 .await
1129 .unwrap();
1130
1131 let report = reset_runtime_data(&framework, false).await.unwrap();
1132 assert!(!report.dry_run);
1133 assert!(report.users_deleted >= 1);
1134 assert!(
1135 framework
1136 .users()
1137 .list_with_query(UserListQuery::new())
1138 .await
1139 .unwrap()
1140 .is_empty()
1141 );
1142 assert!(
1143 framework
1144 .storage()
1145 .get_kv("custom:keep")
1146 .await
1147 .unwrap()
1148 .is_none()
1149 );
1150 }
1151
1152 #[tokio::test]
1153 async fn restore_nonexistent_file_fails() {
1154 let framework = create_framework().await;
1155 let result = restore_from_file(&framework, "/definitely/not/real.json", false).await;
1156 assert!(result.is_err());
1157 }
1158
1159 #[tokio::test]
1160 async fn backup_manifest_has_checksum() {
1161 let dir = tempdir().unwrap();
1162 let path = dir.path().join("checksummed.json");
1163 let framework = create_framework().await;
1164 framework
1165 .users()
1166 .register("chk_user", "chk@example.com", "Password123!")
1167 .await
1168 .unwrap();
1169 let report = backup_to_file(&framework, &path, false).await.unwrap();
1170 assert!(!report.manifest.checksum_sha256.is_empty());
1171 assert_eq!(report.manifest.format_version, SNAPSHOT_FORMAT_VERSION);
1172 }
1173}