Skip to main content

auth_framework/
maintenance.rs

1//! Maintenance utilities: snapshots, data export, and health checks.
2//!
3//! Provides tools for operational maintenance including:
4//!
5//! - **Snapshot & restore** — Serialise the entire storage state to a
6//!   versioned, checksummed snapshot file and restore from it.
7//! - **Data export** — Export users, sessions, tokens, and audit logs as
8//!   structured JSON for compliance or migration purposes.
9//! - **Health checks** — Verify storage connectivity, token validity, and
10//!   system integrity.
11//!
12//! Most operations are available through the
13//! [`MaintenanceOperations`](crate::auth::MaintenanceOperations) facade.
14
15use crate::auth::AuthFramework;
16use crate::auth_operations::UserListQuery;
17use crate::config::{StorageConfig, app_config::AppConfig};
18use crate::errors::{AuthError, Result};
19use crate::permissions::Role;
20use crate::storage::SessionData;
21use crate::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    /// Absolute expiry of the entry at backup time. `None` = the entry did
62    /// not expire. Omitted from the file when `None`, so snapshots (and
63    /// their checksums) written before this field existed stay valid.
64    #[serde(default, skip_serializing_if = "Option::is_none")]
65    pub expires_at: Option<DateTime<Utc>>,
66}
67
68/// What restore should do with a KV entry, given its recorded expiry.
69#[derive(Debug, Clone, Copy, PartialEq, Eq)]
70enum RestoreTtl {
71    /// Store without an expiry.
72    Forever,
73    /// Store with this much lifetime left.
74    Remaining(std::time::Duration),
75    /// Expired between backup and restore: do not bring it back.
76    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
89/// AAD binding a sealed snapshot to its purpose, so a storage-layer
90/// envelope for some other record can't be replayed as a snapshot.
91const 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        // The TTL is read BEFORE the value: an entry that expires in
314        // between then yields a TTL and no value (skipped), never a value
315        // whose expiry was lost and which restore would make permanent.
316        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
395/// Which encryption (if any) protects snapshot files for `framework`.
396///
397/// A snapshot holds everything the live store does -- KV secrets, access
398/// and refresh tokens, sessions, user emails -- and is usually handled
399/// under weaker access control than the database. So whenever the
400/// framework itself encrypts at rest (the default, for every backend that
401/// persists), the whole snapshot file is sealed under the same storage
402/// key. This also covers tokens and sessions, which `EncryptedStorage`
403/// does not encrypt, so backing up the *stored* (already-encrypted) KV
404/// form alone would still leave them readable. In-memory storage is
405/// exempt, as it is for `EncryptedStorage`, and so is an explicit
406/// `storage_encryption.enabled = false`. Fails closed if encryption is
407/// expected but no key can be loaded.
408///
409/// The decision follows `config.storage`, like the storage factory does.
410/// Storage handed in through `new_with_storage` / `replace_storage` /
411/// `custom_storage` bypasses the factory, so a framework whose config still
412/// says `Memory` but whose storage is persistent gets an UNSEALED snapshot.
413fn 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        // A sealed snapshot: open it before anything is reset, so a wrong
539        // or missing key leaves the live data untouched.
540        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        // Snapshots were never written in format v0, so refuse it. A v1
546        // snapshot (sealed by the release that introduced snapshot sealing,
547        // before envelope v2) is deliberately still readable regardless of
548        // `allow_legacy_v0`: it is authenticated under SNAPSHOT_AAD and the
549        // storage key, and there is no migration tool for snapshot files.
550        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        // Sealing is the only thing that authenticates a snapshot (the
562        // checksum is unkeyed and lives inside the file), so accepting an
563        // unsealed one here would let anyone who can write the file inject
564        // users, roles, tokens and secrets.
565        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    // Decode every KV entry BEFORE anything is reset, so a bad entry
574    // cannot leave the store wiped and half-restored.
575    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    /// #121: a backup written under storage encryption must not hold any
882    /// recoverable plaintext -- not the KV secret (raw or base64), not a
883    /// stored access token, not user PII.
884    #[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        // Positive control: an unencrypted backup of the SAME state does
890        // expose each needle, so the scan below can see them.
891        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        // A different key, and no key at all, must both refuse -- and
930        // must refuse BEFORE wiping the live data.
931        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    /// With sealing expected, an unsealed snapshot is refused (it would
977    /// otherwise let anyone who can write the file inject state), and the
978    /// refusal happens before anything is reset.
979    #[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        // Plaintext snapshots still restore where no sealing is in force.
1004        restore_from_file_with(&framework, &path, false, None)
1005            .await
1006            .unwrap();
1007    }
1008
1009    /// A corrupt KV entry must be caught before the reset wipes anything.
1010    #[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    /// #121: restore must not turn an expiring entry into a permanent one.
1047    #[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}