Skip to main content

auth_framework/migration/
mod.rs

1//! Migration utilities for transitioning to role-system v1.0
2//!
3//! This module provides comprehensive migration tools to help users
4//! transition from legacy authorization systems to the unified
5//! role-system v1.0 approach with minimal disruption.
6
7use serde::{Deserialize, Serialize};
8use std::collections::{HashMap, HashSet};
9use std::path::PathBuf;
10use thiserror::Error;
11use tokio::fs;
12
13pub mod analyzers;
14pub mod converters;
15pub mod executors;
16pub mod planners;
17pub mod validators;
18
19/// Migration-related errors
20#[derive(Error, Debug)]
21pub enum MigrationError {
22    #[error("Legacy system analysis failed: {0}")]
23    AnalysisError(String),
24
25    #[error("Migration plan generation failed: {0}")]
26    PlanningError(String),
27
28    #[error("Migration execution failed: {0}")]
29    ExecutionError(String),
30
31    #[error("Migration validation failed: {0}")]
32    ValidationError(String),
33
34    #[error("Rollback operation failed: {0}")]
35    RollbackError(String),
36
37    #[error("I/O error: {0}")]
38    IoError(#[from] std::io::Error),
39
40    #[error("Serialization error: {0}")]
41    SerializationError(#[from] serde_json::Error),
42}
43
44/// Type of legacy authorization system
45#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
46pub enum LegacySystemType {
47    /// Simple permission lists
48    PermissionBased,
49    /// Basic role-based access control
50    BasicRbac,
51    /// Attribute-based access control
52    Abac,
53    /// Custom authorization implementation
54    Custom(String),
55    /// Multiple mixed systems
56    Hybrid(Vec<LegacySystemType>),
57}
58
59/// Legacy role definition
60#[derive(Debug, Clone, Serialize, Deserialize)]
61pub struct LegacyRole {
62    pub id: String,
63    pub name: String,
64    pub description: Option<String>,
65    pub permissions: Vec<String>,
66    pub parent_roles: Vec<String>,
67    pub metadata: HashMap<String, String>,
68}
69
70/// Legacy user assignment
71#[derive(Debug, Clone, Serialize, Deserialize)]
72pub struct LegacyUserAssignment {
73    pub user_id: String,
74    pub role_id: Option<String>,
75    pub permissions: Vec<String>,
76    pub attributes: HashMap<String, String>,
77    pub expiration: Option<chrono::DateTime<chrono::Utc>>,
78}
79
80/// Legacy permission definition
81#[derive(Debug, Clone, Serialize, Deserialize)]
82pub struct LegacyPermission {
83    pub id: String,
84    pub action: String,
85    pub resource: String,
86    pub conditions: HashMap<String, String>,
87    pub metadata: HashMap<String, String>,
88}
89
90/// Analysis result of legacy authorization system
91#[derive(Debug, Clone, Serialize, Deserialize)]
92pub struct LegacySystemAnalysis {
93    /// Type of legacy system detected
94    pub system_type: LegacySystemType,
95
96    /// Total number of roles found
97    pub role_count: usize,
98
99    /// Total number of permissions found
100    pub permission_count: usize,
101
102    /// Total number of user assignments
103    pub user_assignment_count: usize,
104
105    /// Discovered roles
106    pub roles: Vec<LegacyRole>,
107
108    /// Discovered permissions
109    pub permissions: Vec<LegacyPermission>,
110
111    /// User assignments
112    pub user_assignments: Vec<LegacyUserAssignment>,
113
114    /// Role hierarchy complexity (depth levels)
115    pub hierarchy_depth: usize,
116
117    /// Duplicate roles/permissions detected
118    pub duplicates_found: bool,
119
120    /// Orphaned permissions (not assigned to any role)
121    pub orphaned_permissions: Vec<String>,
122
123    /// Circular dependencies in role hierarchy
124    pub circular_dependencies: Vec<Vec<String>>,
125
126    /// Custom attributes that need special handling
127    pub custom_attributes: HashSet<String>,
128
129    /// Estimated migration complexity (1-10 scale)
130    pub complexity_score: u8,
131
132    /// Recommended migration strategy
133    pub recommended_strategy: MigrationStrategy,
134}
135
136/// Migration strategy options
137#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
138pub enum MigrationStrategy {
139    /// Direct mapping with minimal changes
140    DirectMapping,
141    /// Gradual migration with coexistence period
142    GradualMigration,
143    /// Complete rebuild with role consolidation
144    Rebuild,
145    /// Custom strategy for complex scenarios
146    Custom(String),
147}
148
149/// Migration plan for transitioning to role-system v1.0
150#[derive(Debug, Clone, Serialize, Deserialize)]
151pub struct MigrationPlan {
152    /// Unique plan identifier
153    pub id: String,
154
155    /// Source system analysis
156    pub source_analysis: LegacySystemAnalysis,
157
158    /// Selected migration strategy
159    pub strategy: MigrationStrategy,
160
161    /// Planned migration phases
162    pub phases: Vec<MigrationPhase>,
163
164    /// Role mapping from legacy to new system
165    pub role_mappings: HashMap<String, String>,
166
167    /// Permission mapping from legacy to new system
168    pub permission_mappings: HashMap<String, String>,
169
170    /// User assignment migrations
171    pub user_migrations: Vec<UserMigration>,
172
173    /// Pre-migration validation steps
174    pub pre_validation_steps: Vec<ValidationStep>,
175
176    /// Post-migration validation steps
177    pub post_validation_steps: Vec<ValidationStep>,
178
179    /// Rollback plan
180    pub rollback_plan: RollbackPlan,
181
182    /// Estimated migration time
183    pub estimated_duration: chrono::Duration,
184
185    /// Risk assessment
186    pub risk_level: RiskLevel,
187
188    /// Required downtime (if any)
189    pub downtime_required: Option<chrono::Duration>,
190}
191
192/// Individual migration phase
193#[derive(Debug, Clone, Serialize, Deserialize)]
194pub struct MigrationPhase {
195    pub id: String,
196    pub name: String,
197    pub description: String,
198    pub order: u32,
199    pub operations: Vec<MigrationOperation>,
200    pub dependencies: Vec<String>,
201    pub estimated_duration: chrono::Duration,
202    pub rollback_operations: Vec<MigrationOperation>,
203}
204
205/// Migration operation types
206#[derive(Debug, Clone, Serialize, Deserialize)]
207pub enum MigrationOperation {
208    CreateRole {
209        role_id: String,
210        name: String,
211        description: Option<String>,
212        permissions: Vec<String>,
213        parent_role: Option<String>,
214    },
215    AssignUserRole {
216        user_id: String,
217        role_id: String,
218        expiration: Option<chrono::DateTime<chrono::Utc>>,
219    },
220    CreatePermission {
221        permission_id: String,
222        action: String,
223        resource: String,
224        conditions: HashMap<String, String>,
225    },
226    MigrateCustomAttribute {
227        attribute_name: String,
228        conversion_logic: String,
229    },
230    ValidateIntegrity {
231        validation_type: String,
232        parameters: HashMap<String, String>,
233    },
234    Backup {
235        backup_location: PathBuf,
236        backup_type: BackupType,
237    },
238}
239
240/// User migration details
241#[derive(Debug, Clone, Serialize, Deserialize)]
242pub struct UserMigration {
243    pub user_id: String,
244    pub legacy_roles: Vec<String>,
245    pub legacy_permissions: Vec<String>,
246    pub new_roles: Vec<String>,
247    pub migration_notes: Option<String>,
248}
249
250/// Validation step definition
251#[derive(Debug, Clone, Serialize, Deserialize)]
252pub struct ValidationStep {
253    pub id: String,
254    pub name: String,
255    pub description: String,
256    pub validation_type: ValidationType,
257    pub parameters: HashMap<String, String>,
258    pub required: bool,
259}
260
261/// Types of validation
262#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
263pub enum ValidationType {
264    /// Check role hierarchy integrity
265    HierarchyIntegrity,
266    /// Validate permission consistency
267    PermissionConsistency,
268    /// Check user assignment validity
269    UserAssignmentValidity,
270    /// Verify no privilege escalation
271    PrivilegeEscalationCheck,
272    /// Custom validation script
273    Custom(String),
274}
275
276/// Rollback plan for migration
277#[derive(Debug, Clone, Serialize, Deserialize)]
278pub struct RollbackPlan {
279    pub phases: Vec<RollbackPhase>,
280    pub backup_locations: Vec<PathBuf>,
281    pub recovery_time_objective: chrono::Duration,
282    pub manual_steps: Vec<String>,
283}
284
285/// Rollback phase
286#[derive(Debug, Clone, Serialize, Deserialize)]
287pub struct RollbackPhase {
288    pub id: String,
289    pub name: String,
290    pub operations: Vec<MigrationOperation>,
291    pub order: u32,
292}
293
294/// Risk assessment levels
295#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord)]
296pub enum RiskLevel {
297    Low,
298    Medium,
299    High,
300    Critical,
301}
302
303/// Backup types
304#[derive(Debug, Clone, Serialize, Deserialize)]
305pub enum BackupType {
306    /// Full system backup
307    Full,
308    /// Incremental backup
309    Incremental,
310    /// Configuration only
311    ConfigOnly,
312    /// Data only
313    DataOnly,
314}
315
316/// Migration execution result
317#[derive(Debug, Clone, Serialize, Deserialize)]
318pub struct MigrationResult {
319    pub plan_id: String,
320    pub status: MigrationStatus,
321    pub started_at: chrono::DateTime<chrono::Utc>,
322    pub completed_at: Option<chrono::DateTime<chrono::Utc>>,
323    pub phases_completed: Vec<String>,
324    pub current_phase: Option<String>,
325    pub errors: Vec<String>,
326    pub warnings: Vec<String>,
327    pub metrics: MigrationMetrics,
328}
329
330/// Migration execution status
331#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
332pub enum MigrationStatus {
333    Planned,
334    InProgress,
335    Completed,
336    Failed,
337    RolledBack,
338    Paused,
339}
340
341/// Migration execution metrics
342#[derive(Debug, Clone, Serialize, Deserialize)]
343pub struct MigrationMetrics {
344    pub roles_migrated: usize,
345    pub permissions_migrated: usize,
346    pub users_migrated: usize,
347    pub errors_encountered: usize,
348    pub warnings_generated: usize,
349    pub validation_failures: usize,
350    pub rollback_count: usize,
351}
352
353/// Main migration manager
354pub struct MigrationManager {
355    /// Configuration for migration operations
356    config: MigrationConfig,
357}
358
359/// Migration manager configuration
360#[derive(Debug, Clone, Serialize, Deserialize)]
361pub struct MigrationConfig {
362    /// Working directory for migration files
363    pub working_directory: PathBuf,
364
365    /// Backup directory
366    pub backup_directory: PathBuf,
367
368    /// Maximum concurrent operations
369    pub max_concurrent_operations: usize,
370
371    /// Operation timeout
372    pub operation_timeout: chrono::Duration,
373
374    /// Enable dry-run mode
375    pub dry_run: bool,
376
377    /// Verbose logging
378    pub verbose: bool,
379}
380
381impl Default for MigrationConfig {
382    fn default() -> Self {
383        Self {
384            working_directory: PathBuf::from("./.auth-framework-migration"),
385            backup_directory: PathBuf::from("./.auth-framework-migration/backups"),
386            max_concurrent_operations: 4,
387            operation_timeout: chrono::Duration::minutes(30),
388            dry_run: false,
389            verbose: false,
390        }
391    }
392}
393
394impl MigrationConfig {
395    /// Dry-run mode: analyse the migration plan without applying changes.
396    ///
397    /// Verbose logging is enabled automatically.
398    pub fn dry_run() -> Self {
399        Self {
400            dry_run: true,
401            verbose: true,
402            ..Default::default()
403        }
404    }
405
406    /// Conservative mode: sequential execution with long timeouts.
407    ///
408    /// Best for production environments where safety is paramount.
409    pub fn conservative() -> Self {
410        Self {
411            max_concurrent_operations: 1,
412            operation_timeout: chrono::Duration::minutes(120),
413            verbose: true,
414            ..Default::default()
415        }
416    }
417
418    /// Aggressive mode: maximum parallelism for large-scale migrations.
419    pub fn aggressive() -> Self {
420        Self {
421            max_concurrent_operations: 16,
422            operation_timeout: chrono::Duration::minutes(60),
423            ..Default::default()
424        }
425    }
426
427    /// Create a builder starting from the default configuration.
428    pub fn builder() -> MigrationConfigBuilder {
429        MigrationConfigBuilder {
430            config: MigrationConfig::default(),
431        }
432    }
433}
434
435/// Fluent builder for [`MigrationConfig`].
436///
437/// # Example
438///
439/// ```rust,no_run
440/// use auth_framework::migration::MigrationConfig;
441///
442/// let config = MigrationConfig::builder()
443///     .working_directory("./my_migration")
444///     .dry_run(true)
445///     .max_concurrent(8)
446///     .build();
447/// ```
448#[derive(Debug, Clone)]
449pub struct MigrationConfigBuilder {
450    config: MigrationConfig,
451}
452
453impl MigrationConfigBuilder {
454    /// Set the working directory.
455    pub fn working_directory(mut self, dir: impl Into<PathBuf>) -> Self {
456        self.config.working_directory = dir.into();
457        self
458    }
459
460    /// Set the backup directory.
461    pub fn backup_directory(mut self, dir: impl Into<PathBuf>) -> Self {
462        self.config.backup_directory = dir.into();
463        self
464    }
465
466    /// Set maximum concurrent operations.
467    pub fn max_concurrent(mut self, count: usize) -> Self {
468        self.config.max_concurrent_operations = count;
469        self
470    }
471
472    /// Set operation timeout.
473    pub fn timeout(mut self, timeout: chrono::Duration) -> Self {
474        self.config.operation_timeout = timeout;
475        self
476    }
477
478    /// Enable or disable dry-run mode.
479    pub fn dry_run(mut self, enabled: bool) -> Self {
480        self.config.dry_run = enabled;
481        self
482    }
483
484    /// Enable or disable verbose logging.
485    pub fn verbose(mut self, enabled: bool) -> Self {
486        self.config.verbose = enabled;
487        self
488    }
489
490    /// Consume the builder and produce the config.
491    pub fn build(self) -> MigrationConfig {
492        self.config
493    }
494}
495
496impl MigrationManager {
497    /// Create new migration manager
498    pub fn new(config: MigrationConfig) -> Result<Self, MigrationError> {
499        // The default working_directory moved from "./migration" to
500        // "./.auth-framework-migration" (see MigrationConfig::default). A
501        // reader that finds no manifest at the new location treats that as
502        // "nothing recorded yet" rather than an error, so an upgrade would
503        // otherwise silently lose continuity with any pre-existing state at
504        // the old location. Surface it instead of staying silent.
505        let legacy_dir = std::path::Path::new("./migration");
506        if legacy_dir != config.working_directory && legacy_dir.exists() {
507            tracing::warn!(
508                "found a pre-existing '{}' directory, but this migration tool's default \
509                 working_directory is now '{}' -- if this holds manifest/status state from \
510                 before an upgrade, set MigrationConfig::working_directory explicitly to \
511                 '{}' to continue using it, or migrate its contents manually.",
512                legacy_dir.display(),
513                config.working_directory.display(),
514                legacy_dir.display(),
515            );
516        }
517
518        // Ensure directories exist
519        std::fs::create_dir_all(&config.working_directory)?;
520        std::fs::create_dir_all(&config.backup_directory)?;
521
522        Ok(Self { config })
523    }
524
525    /// Analyze legacy authorization system
526    pub async fn analyze_legacy_system<P: AsRef<std::path::Path>>(
527        &self,
528        config_path: P,
529    ) -> Result<LegacySystemAnalysis, MigrationError> {
530        analyzers::analyze_legacy_system(config_path, &self.config).await
531    }
532
533    /// Generate migration plan
534    pub async fn generate_migration_plan(
535        &self,
536        analysis: &LegacySystemAnalysis,
537        strategy: Option<MigrationStrategy>,
538    ) -> Result<MigrationPlan, MigrationError> {
539        planners::generate_migration_plan(analysis, strategy, &self.config).await
540    }
541
542    /// Validate migration plan
543    pub async fn validate_migration_plan(
544        &self,
545        plan: &MigrationPlan,
546    ) -> Result<Vec<String>, MigrationError> {
547        validators::validate_migration_plan(plan, &self.config).await
548    }
549
550    /// Execute migration plan
551    pub async fn execute_migration(
552        &self,
553        plan: &MigrationPlan,
554    ) -> Result<MigrationResult, MigrationError> {
555        executors::execute_migration_plan(plan, &self.config).await
556    }
557
558    /// Get migration status
559    pub async fn get_migration_status(
560        &self,
561        plan_id: &str,
562    ) -> Result<Option<MigrationResult>, MigrationError> {
563        let status_file = self
564            .config
565            .working_directory
566            .join(format!("{}_status.json", plan_id));
567
568        if !status_file.exists() {
569            return Ok(None);
570        }
571
572        let content = fs::read_to_string(status_file).await?;
573        let result: MigrationResult = serde_json::from_str(&content)?;
574        Ok(Some(result))
575    }
576
577    /// Rollback migration
578    pub async fn rollback_migration(
579        &self,
580        plan: &MigrationPlan,
581    ) -> Result<MigrationResult, MigrationError> {
582        executors::rollback_migration(plan, &self.config).await
583    }
584
585    /// List available migration plans
586    pub async fn list_migration_plans(&self) -> Result<Vec<String>, MigrationError> {
587        let mut plans = Vec::new();
588        let mut entries = fs::read_dir(&self.config.working_directory).await?;
589
590        while let Some(entry) = entries.next_entry().await? {
591            let path = entry.path();
592            if path.extension().is_some_and(|ext| ext == "json")
593                && let Some(file_name) = path.file_stem()
594                && let Some(name) = file_name.to_str()
595                && name.ends_with("_plan")
596            {
597                plans.push(name.trim_end_matches("_plan").to_string());
598            }
599        }
600
601        Ok(plans)
602    }
603
604    /// Save migration plan to disk
605    pub async fn save_migration_plan(
606        &self,
607        plan: &MigrationPlan,
608    ) -> Result<PathBuf, MigrationError> {
609        let plan_file = self
610            .config
611            .working_directory
612            .join(format!("{}_plan.json", plan.id));
613        let content = serde_json::to_string_pretty(plan)?;
614        fs::write(&plan_file, content).await?;
615        Ok(plan_file)
616    }
617
618    /// Load migration plan from disk
619    pub async fn load_migration_plan(
620        &self,
621        plan_id: &str,
622    ) -> Result<MigrationPlan, MigrationError> {
623        let plan_file = self
624            .config
625            .working_directory
626            .join(format!("{}_plan.json", plan_id));
627        let content = fs::read_to_string(plan_file).await?;
628        let plan: MigrationPlan = serde_json::from_str(&content)?;
629        Ok(plan)
630    }
631
632    /// Generate migration report
633    pub async fn generate_migration_report(
634        &self,
635        result: &MigrationResult,
636    ) -> Result<String, MigrationError> {
637        let mut report = String::new();
638
639        report.push_str("# Migration Report\n\n");
640        report.push_str(&format!("**Plan ID**: {}\n", result.plan_id));
641        report.push_str(&format!("**Status**: {:?}\n", result.status));
642        report.push_str(&format!("**Started**: {}\n", result.started_at));
643
644        if let Some(completed) = result.completed_at {
645            report.push_str(&format!("**Completed**: {}\n", completed));
646            let duration = completed - result.started_at;
647            report.push_str(&format!(
648                "**Duration**: {} minutes\n",
649                duration.num_minutes()
650            ));
651        }
652
653        report.push_str("\n## Metrics\n\n");
654        report.push_str(&format!(
655            "- Roles migrated: {}\n",
656            result.metrics.roles_migrated
657        ));
658        report.push_str(&format!(
659            "- Permissions migrated: {}\n",
660            result.metrics.permissions_migrated
661        ));
662        report.push_str(&format!(
663            "- Users migrated: {}\n",
664            result.metrics.users_migrated
665        ));
666        report.push_str(&format!(
667            "- Errors: {}\n",
668            result.metrics.errors_encountered
669        ));
670        report.push_str(&format!(
671            "- Warnings: {}\n",
672            result.metrics.warnings_generated
673        ));
674
675        if !result.errors.is_empty() {
676            report.push_str("\n## Errors\n\n");
677            for error in &result.errors {
678                report.push_str(&format!("- {}\n", error));
679            }
680        }
681
682        if !result.warnings.is_empty() {
683            report.push_str("\n## Warnings\n\n");
684            for warning in &result.warnings {
685                report.push_str(&format!("- {}\n", warning));
686            }
687        }
688
689        Ok(report)
690    }
691}
692
693#[cfg(test)]
694mod tests {
695    use super::*;
696
697    #[tokio::test]
698    async fn test_migration_manager_creation() {
699        let tmp = tempfile::tempdir().unwrap();
700        let config = MigrationConfig {
701            working_directory: tmp.path().join("migration"),
702            backup_directory: tmp.path().join("backups"),
703            ..Default::default()
704        };
705        let manager = MigrationManager::new(config);
706        assert!(manager.is_ok());
707    }
708
709    #[test]
710    fn test_legacy_system_type_serialization() {
711        let system_type = LegacySystemType::BasicRbac;
712        let serialized = serde_json::to_string(&system_type).unwrap();
713        let deserialized: LegacySystemType = serde_json::from_str(&serialized).unwrap();
714        assert_eq!(system_type, deserialized);
715    }
716
717    #[test]
718    fn test_migration_strategy_serialization() {
719        let strategy = MigrationStrategy::GradualMigration;
720        let serialized = serde_json::to_string(&strategy).unwrap();
721        let deserialized: MigrationStrategy = serde_json::from_str(&serialized).unwrap();
722        assert_eq!(strategy, deserialized);
723    }
724
725    #[test]
726    fn test_risk_level_ordering() {
727        assert!(RiskLevel::Low < RiskLevel::Medium);
728        assert!(RiskLevel::Medium < RiskLevel::High);
729        assert!(RiskLevel::High < RiskLevel::Critical);
730    }
731
732    #[test]
733    fn test_migration_config_dry_run_preset() {
734        let config = MigrationConfig::dry_run();
735        assert!(config.dry_run);
736        assert!(config.verbose);
737    }
738
739    #[test]
740    fn test_migration_config_conservative_preset() {
741        let config = MigrationConfig::conservative();
742        assert_eq!(config.max_concurrent_operations, 1);
743        assert!(config.verbose);
744        assert!(!config.dry_run);
745    }
746
747    #[test]
748    fn test_migration_config_aggressive_preset() {
749        let config = MigrationConfig::aggressive();
750        assert_eq!(config.max_concurrent_operations, 16);
751    }
752
753    #[test]
754    fn test_migration_config_builder() {
755        let config = MigrationConfig::builder()
756            .working_directory("/tmp/migration")
757            .dry_run(true)
758            .max_concurrent(8)
759            .verbose(true)
760            .build();
761        assert_eq!(config.working_directory, PathBuf::from("/tmp/migration"));
762        assert!(config.dry_run);
763        assert_eq!(config.max_concurrent_operations, 8);
764        assert!(config.verbose);
765    }
766
767    #[tokio::test]
768    async fn test_migration_manager_with_dry_run_preset() {
769        let config = MigrationConfig::dry_run();
770        let manager = MigrationManager::new(config);
771        assert!(manager.is_ok());
772    }
773}