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