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(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
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/// What restore should do with a KV entry, given its recorded expiry.
82#[derive(Debug, Clone, Copy, PartialEq, Eq)]
83enum RestoreTtl {
84    /// Store without an expiry.
85    Forever,
86    /// Store with this much lifetime left.
87    Remaining(std::time::Duration),
88    /// Expired between backup and restore: do not bring it back.
89    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
102/// AAD binding a sealed snapshot to its purpose, so a storage-layer
103/// envelope for some other record can't be replayed as a snapshot.
104const 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        // The TTL is read BEFORE the value: an entry that expires in
327        // between then yields a TTL and no value (skipped), never a value
328        // whose expiry was lost and which restore would make permanent.
329        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
408/// Which encryption (if any) protects snapshot files for `framework`.
409///
410/// A snapshot holds everything the live store does -- KV secrets, access
411/// and refresh tokens, sessions, user emails -- and is usually handled
412/// under weaker access control than the database. So whenever the
413/// framework itself encrypts at rest (the default, for every backend that
414/// persists), the whole snapshot file is sealed under the same storage
415/// key. This also covers tokens and sessions, which `EncryptedStorage`
416/// does not encrypt, so backing up the *stored* (already-encrypted) KV
417/// form alone would still leave them readable. In-memory storage is
418/// exempt, as it is for `EncryptedStorage`, and so is an explicit
419/// `storage_encryption.enabled = false`. Fails closed if encryption is
420/// expected but no key can be loaded.
421///
422/// The decision follows `config.storage`, like the storage factory does.
423/// Storage handed in through `new_with_storage` / `replace_storage` /
424/// `custom_storage` bypasses the factory, so a framework whose config still
425/// says `Memory` but whose storage is persistent gets an UNSEALED snapshot.
426fn 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        // A sealed snapshot: open it before anything is reset, so a wrong
552        // or missing key leaves the live data untouched.
553        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        // Snapshots were never written in format v0, so refuse it. A v1
559        // snapshot (sealed by the release that introduced snapshot sealing,
560        // before envelope v2) is deliberately still readable regardless of
561        // `allow_legacy_v0`: it is authenticated under SNAPSHOT_AAD and the
562        // storage key, and there is no migration tool for snapshot files.
563        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        // Sealing is the only thing that authenticates a snapshot (the
575        // checksum is unkeyed and lives inside the file), so accepting an
576        // unsealed one here would let anyone who can write the file inject
577        // users, roles, tokens and secrets.
578        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    // Decode every KV entry BEFORE anything is reset, so a bad entry
587    // cannot leave the store wiped and half-restored.
588    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    /// #121: a backup written under storage encryption must not hold any
895    /// recoverable plaintext -- not the KV secret (raw or base64), not a
896    /// stored access token, not user PII.
897    #[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        // Positive control: an unencrypted backup of the SAME state does
903        // expose each needle, so the scan below can see them.
904        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        // A different key, and no key at all, must both refuse -- and
943        // must refuse BEFORE wiping the live data.
944        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    /// With sealing expected, an unsealed snapshot is refused (it would
990    /// otherwise let anyone who can write the file inject state), and the
991    /// refusal happens before anything is reset.
992    #[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        // Plaintext snapshots still restore where no sealing is in force.
1017        restore_from_file_with(&framework, &path, false, None)
1018            .await
1019            .unwrap();
1020    }
1021
1022    /// A corrupt KV entry must be caught before the reset wipes anything.
1023    #[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    /// #121: restore must not turn an expiring entry into a permanent one.
1060    #[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}