rails_nexus 2.0.6 → 2.1.2

data/app/services/rails_nexus/backup_service.rb

@@ -3,6 +3,8 @@
 require "open3"
 require "json"
 require "fileutils"
+require "shellwords"
+require "tempfile"
 
 module RailsNexus
   class BackupService
@@ -20,28 +22,34 @@ module RailsNexus
 
     def run
       @record = RailsNexus::Backup.start!(
-        model_name: @config.name,
+        config_name: @config.name,
         triggered_by: "service"
       )
 
       begin
-        FileUtils.mkdir_p(@config.storage_path_expanded)
+        @stage = "preparing storage"
+        validate_identifier!(@config.name, "backup name")
+        FileUtils.mkdir_p(validated_path(@config.storage_path_expanded, "storage path"))
 
         # Step 1: Dump database
+        @stage = "database dump"
         dump_path = dump_database
         raise "Database dump failed" unless dump_path
 
         # Step 2: Create archive if enabled (tar additional files/dirs)
+        @stage = "archive creation"
         if @config.archive_enabled? && @config.archive_paths_list.any?
           dump_path = create_archive(dump_path)
         end
 
         # Step 3: Split into chunks if enabled
+        @stage = "file splitting"
         if @config.split_chunks? && File.size(dump_path) > 50_000_000 # 50MB
           dump_path = split_file(dump_path)
         end
 
         # Step 4: Compress
+        @stage = "compression"
         if @config.compress? && !@config.split_chunks?
           dump_path = compress(dump_path)
         elsif @config.bzip2_compress? && !@config.split_chunks?
@@ -49,6 +57,7 @@ module RailsNexus
         end
 
         # Step 5: Encrypt
+        @stage = "encryption"
         if @config.encrypted?
           dump_path = encrypt_openssl(dump_path)
         elsif @config.gpg_enabled?
@@ -56,26 +65,32 @@ module RailsNexus
         end
 
         # Step 6: Sync to S3
+        @stage = "S3 sync"
         sync_s3(dump_path) if @config.s3_enabled?
 
         # Step 7: Sync to remote
-        rsync_result = sync_remote(dump_path) if @config.rsync_enabled?
+        @stage = "remote sync"
+        sync_remote(dump_path) if @config.rsync_enabled?
 
         # Step 8: Cleanup old backups
+        @stage = "retention cleanup"
         cleanup_old_backups
 
         # Step 9: Record success
+        @stage = "recording success"
         file_size = calculate_size(dump_path)
         @record.succeed!(file_path: dump_path, file_size: file_size)
 
         # Step 10: Notify
+        @stage = "success notification"
         notify_success
 
         { success: true, record: @record, file_path: dump_path }
       rescue StandardError => e
-        @record&.fail!(error_message: e.message)
-        notify_failure(e.message)
-        { success: false, error: e.message, record: @record }
+        full_error = failure_message(e)
+        @record&.fail!(error_message: full_error)
+        notify_failure(full_error)
+        { success: false, error: full_error, record: @record }
       ensure
         cleanup_temp_files
       end
@@ -100,11 +115,14 @@ module RailsNexus
 
     # ─── MySQL ─────────────────────────────────────────────────────
     def dump_mysql
+      validate_identifier!(@config.database_name, "database name")
+      validate_host!(@config.host) if @config.host.present?
+      validate_port!(@config.port) if @config.port.present?
       raw_path = @config.dump_filepath.gsub(/\.(gz|bz2|enc)$/, "")
+      password = resolve_password(@config.password)
       cmd = ["mysqldump"]
-      cmd << "--user=#{@config.username}"  if @config.username.present?
-      cmd << "--password=#{@config.password}" if @config.password.present?
-      cmd << "--host=#{@config.host}"      if @config.host.present?
+      cmd << "--user=#{resolve_env(@config.username)}" if @config.username.present?
+      cmd << "--host=#{resolve_env(@config.host)}"      if @config.host.present?
       cmd << "--port=#{@config.port}"      if @config.port.present?
       cmd << "--result-file=#{raw_path}"
       cmd << "--single-transaction"
@@ -112,16 +130,27 @@ module RailsNexus
       cmd << "--routines"
       cmd << "--triggers"
       cmd << "--events"
+      # Additional MySQL options (e.g. --defaults-extra-file)
+      additional_options = if @config.respond_to?(:mysql_additional_options)
+        @config.mysql_additional_options
+      end
+      if additional_options.present?
+        cmd.concat(validated_mysql_options(additional_options))
+      end
 
       # Skip tables
-      @config.skip_tables_list.each { |t| cmd << "--ignore-table=#{@config.database_name}.#{t}" }
+      @config.skip_tables_list.each do |table|
+        validate_identifier!(table, "table name")
+        cmd << "--ignore-table=#{@config.database_name}.#{table}"
+      end
 
       cmd << @config.database_name
 
-      stdout, stderr, status = Open3.capture3(cmd.join(" "))
+      env = {}
+      env["MYSQL_PWD"] = password if password.present?
+      stdout, stderr, status = capture_command(env, *cmd)
       unless status.success?
-        @errors << "mysqldump failed: #{stderr}"
-        return nil
+        raise "mysqldump failed (exit #{status.exitstatus}):\n#{stderr}\n#{stdout}"
       end
       register_temp_file(raw_path)
       raw_path
@@ -129,10 +158,14 @@ module RailsNexus
 
     # ─── PostgreSQL ────────────────────────────────────────────────
     def dump_postgresql
+      validate_identifier!(@config.database_name, "database name")
+      validate_host!(@config.host) if @config.host.present?
+      validate_port!(@config.port) if @config.port.present?
       raw_path = @config.dump_filepath.gsub(/\.(gz|bz2|enc)$/, "")
+      password = resolve_password(@config.password)
       cmd = ["pg_dump"]
-      cmd << "--username=#{@config.username}" if @config.username.present?
-      cmd << "--host=#{@config.host}"         if @config.host.present?
+      cmd << "--username=#{resolve_env(@config.username)}" if @config.username.present?
+      cmd << "--host=#{resolve_env(@config.host)}"         if @config.host.present?
       cmd << "--port=#{@config.port}"         if @config.port.present?
       cmd << "--file=#{raw_path}"
       cmd << "--format=plain"
@@ -140,36 +173,40 @@ module RailsNexus
       cmd << "--no-privileges"
 
       # Skip tables
-      @config.skip_tables_list.each { |t| cmd << "--exclude-table=#{t}" }
+      @config.skip_tables_list.each do |table|
+        validate_identifier!(table, "table name")
+        cmd << "--exclude-table=#{table}"
+      end
 
       cmd << @config.database_name
 
       env = {}
-      env["PGPASSWORD"] = @config.password if @config.password.present?
+      env["PGPASSWORD"] = password if password.present?
 
-      stdout, stderr, status = Open3.capture3(env, cmd.join(" "))
+      stdout, stderr, status = capture_command(env, *cmd)
       unless status.success?
-        @errors << "pg_dump failed: #{stderr}"
-        return nil
+        raise "pg_dump failed (exit #{status.exitstatus}):\n#{stderr}\n#{stdout}"
       end
       register_temp_file(raw_path)
       raw_path
     end
 
+    def capture_command(*command, **options)
+      Open3.capture3(*command, **options)
+    end
+
     # ─── SQLite ────────────────────────────────────────────────────
     def dump_sqlite
       raw_path = @config.dump_filepath.gsub(/\.(gz|bz2|enc)$/, "")
-      db_path = @config.database_name
+      db_path = validated_path(@config.database_name, "SQLite database path")
 
       unless File.exist?(db_path)
-        @errors << "SQLite database not found: #{db_path}"
-        return nil
+        raise "SQLite database not found: #{db_path}"
       end
 
-      stdout, stderr, status = Open3.capture3("sqlite3 \"#{db_path}\" .dump")
+      stdout, stderr, status = capture_command("sqlite3", db_path, ".dump")
       unless status.success?
-        @errors << "sqlite3 dump failed: #{stderr}"
-        return nil
+        raise "sqlite3 dump failed (exit #{status.exitstatus}):\n#{stderr}\n#{stdout}"
       end
 
       File.write(raw_path, stdout)
@@ -179,35 +216,47 @@ module RailsNexus
 
     # ─── MongoDB ───────────────────────────────────────────────────
     def dump_mongodb
+      validate_identifier!(@config.database_name, "database name")
+      validate_host!(@config.host.presence || "localhost")
+      validate_port!(@config.port || 27_017)
       raw_path = @config.dump_filepath.gsub(/\.(gz|bz2|enc)$/, "")
       dir_path = raw_path.gsub(/\.sql$/, "")
       FileUtils.mkdir_p(dir_path)
 
+      password = resolve_password(@config.password)
       cmd = ["mongodump"]
-      cmd << "--host=#{@config.host || 'localhost'}"
+      cmd << "--host=#{resolve_env(@config.host) || 'localhost'}"
       cmd << "--port=#{@config.port || 27017}"
       cmd << "--db=#{@config.database_name}"
       cmd << "--out=#{dir_path}"
-      cmd << "--username=#{@config.username}" if @config.username.present?
-      cmd << "--password=#{@config.password}" if @config.password.present?
+      cmd << "--username=#{resolve_env(@config.username)}" if @config.username.present?
       cmd << "--authenticationDatabase=admin" if @config.username.present?
 
       # Skip collections
-      @config.skip_tables_list.each { |t| cmd << "--excludeCollection=#{t}" }
+      @config.skip_tables_list.each do |collection|
+        validate_identifier!(collection, "collection name")
+        cmd << "--excludeCollection=#{collection}"
+      end
 
-      stdout, stderr, status = Open3.capture3(cmd.join(" "))
+      stdout, stderr, status = if password.present?
+        with_secret_file("rails_nexus_mongo", "password: #{password.to_json}\n") do |config_path|
+          capture_command(*cmd, "--config=#{config_path}")
+        end
+      else
+        capture_command(*cmd)
+      end
       unless status.success?
-        @errors << "mongodump failed: #{stderr}"
-        FileUtils.rm_rf(dir_path) if Dir.exist?(dir_path)
-        return nil
+        FileUtils.rm_rf(dir_path)
+        raise "mongodump failed (exit #{status.exitstatus}):\n#{stderr}\n#{stdout}"
       end
 
       # Tar the dump directory
       tar_path = "#{dir_path}.tar"
-      stdout, stderr, status = Open3.capture3("tar -cf \"#{tar_path}\" -C \"#{File.dirname(dir_path)}\" \"#{File.basename(dir_path)}\"")
+      stdout, stderr, status = capture_command(
+        "tar", "-cf", tar_path, "-C", File.dirname(dir_path), File.basename(dir_path)
+      )
       unless status.success?
-        @errors << "tar failed: #{stderr}"
-        return nil
+        raise "tar failed (exit #{status.exitstatus}):\n#{stderr}\n#{stdout}"
       end
 
       FileUtils.rm_rf(dir_path)
@@ -220,16 +269,14 @@ module RailsNexus
       raw_path = @config.dump_filepath.gsub(/\.(gz|bz2|enc)$/, "")
       raw_path = raw_path.gsub(/\.sql$/, ".rdb")
 
-      host = @config.host || "localhost"
+      host = @config.host.presence || "localhost"
       port = @config.port || 6379
-      password = @config.password
+      password = resolve_password(@config.password)
+      validate_host!(host)
+      validate_port!(port)
 
       # Trigger BGSAVE first
-      cmd = "redis-cli -h #{host} -p #{port}"
-      cmd += " -a #{password}" if password.present?
-      cmd += " BGSAVE"
-
-      stdout, stderr, status = Open3.capture3(cmd)
+      _, stderr, status = capture_redis(host, port, password, "BGSAVE")
       unless status.success?
         @errors << "redis BGSAVE failed: #{stderr}"
         return nil
@@ -240,8 +287,7 @@ module RailsNexus
 
       # Try to find the dump.rdb on the server or use redis-cli to copy
       # If local Redis, copy the dump.rdb directly
-      redis_dir_cmd = "#{cmd.gsub(' BGSAVE', '')} CONFIG GET dir"
-      dir_out, = Open3.capture3(redis_dir_cmd)
+      dir_out, = capture_redis(host, port, password, "CONFIG", "GET", "dir")
       redis_dir = dir_out.split("\n").last || "/var/lib/redis"
 
       redis_rdb = File.join(redis_dir, "dump.rdb")
@@ -257,23 +303,20 @@ module RailsNexus
     end
 
     def dump_all_keys(host, port, password, output_path)
-      cmd = "redis-cli -h #{host} -p #{port}"
-      cmd += " -a #{password}" if password.present?
-
-      keys_out, = Open3.capture3("#{cmd} KEYS '*'")
+      keys_out, = capture_redis(host, port, password, "KEYS", "*")
       keys = keys_out.split("\n").reject { |k| k.start_with?("redis") }
 
       File.open(output_path, "w") do |f|
         keys.each do |key|
-          type_out, = Open3.capture3("#{cmd} TYPE \"#{key}\"")
+          type_out, = capture_redis(host, port, password, "TYPE", key)
           type = type_out.strip.split("\n").last
 
           val_out, = case type
-          when "string" then Open3.capture3("#{cmd} GET \"#{key}\"")
-          when "list"   then Open3.capture3("#{cmd} LRANGE \"#{key}\" 0 -1")
-          when "set"    then Open3.capture3("#{cmd} SMEMBERS \"#{key}\"")
-          when "hash"   then Open3.capture3("#{cmd} HGETALL \"#{key}\"")
-          else Open3.capture3("#{cmd} DUMP \"#{key}\"")
+          when "string" then capture_redis(host, port, password, "GET", key)
+          when "list"   then capture_redis(host, port, password, "LRANGE", key, "0", "-1")
+          when "set"    then capture_redis(host, port, password, "SMEMBERS", key)
+          when "hash"   then capture_redis(host, port, password, "HGETALL", key)
+          else capture_redis(host, port, password, "DUMP", key)
           end
 
           f.puts("SET #{key.inspect} #{val_out.strip.inspect}")
@@ -305,14 +348,19 @@ module RailsNexus
         @temp_files << dump_path
       end
 
-      @config.archive_paths_list.each { |p| cmd << p }
+      @config.archive_paths_list.each do |path|
+        cmd << validated_path(path, "archive path")
+      end
 
       # Exclude patterns
       if @config.archive_excludes_list.any?
-        @config.archive_excludes_list.each { |e| cmd << "--exclude=#{e}" }
+        @config.archive_excludes_list.each do |pattern|
+          validate_text_argument!(pattern, "archive exclusion")
+          cmd << "--exclude=#{pattern}"
+        end
       end
 
-      stdout, stderr, status = Open3.capture3(cmd.join(" "))
+      _, stderr, status = capture_command(*cmd)
       unless status.success?
         @errors << "archive tar failed: #{stderr}"
         return dump_path
@@ -338,7 +386,7 @@ module RailsNexus
 
     def compress_bzip2(file_path)
       bz2_path = "#{file_path}.bz2"
-      stdout, stderr, status = Open3.capture3("bzip2 -zk \"#{file_path}\"")
+      _, stderr, status = capture_command("bzip2", "-zk", file_path)
       unless status.success?
         @errors << "bzip2 failed: #{stderr}"
         return file_path
@@ -353,13 +401,18 @@ module RailsNexus
 
     def encrypt_openssl(file_path)
       enc_path = "#{file_path}.enc"
-      password = @config.encryption_password
+      password = resolve_secret(@config.encryption_password)
 
-      cmd = "openssl aes-256-cbc -salt -pbkdf2 -iter 100000 " \
-            "-in \"#{file_path}\" -out \"#{enc_path}\" " \
-            "-pass pass:#{password}"
+      # Best practice: AES-256-CBC + PBKDF2 + 600K iterations + random salt
+      # (AES-GCM not available in all OpenSSL builds)
+      env = { "RAILS_NEXUS_OPENSSL_PASSWORD" => password.to_s }
+      cmd = [
+        "openssl", "enc", "-aes-256-cbc", "-pbkdf2", "-iter", "600000",
+        "-salt", "-in", file_path, "-out", enc_path,
+        "-pass", "env:RAILS_NEXUS_OPENSSL_PASSWORD"
+      ]
 
-      stdout, stderr, status = Open3.capture3(cmd)
+      _, stderr, status = capture_command(env, *cmd)
       unless status.success?
         @errors << "OpenSSL encryption failed: #{stderr}"
         return file_path
@@ -371,14 +424,18 @@ module RailsNexus
 
     def encrypt_gpg(file_path)
       enc_path = "#{file_path}.gpg"
-      password = @config.gpg_password
-
-      cmd = "echo #{password} | gpg --batch --yes --symmetric " \
-            "--cipher-algo AES256 " \
-            "--passphrase-fd 0 " \
-            "-o \"#{enc_path}\" \"#{file_path}\""
-
-      stdout, stderr, status = Open3.capture3(cmd)
+      password = resolve_secret(@config.gpg_password)
+
+      # Best practice: AES256 with an iteration-counted S2K. The passphrase is
+      # provided through a mode-0600 temporary file, never process arguments.
+      _, stderr, status = with_secret_file("rails_nexus_gpg", password.to_s) do |password_path|
+        capture_command(
+          "gpg", "--batch", "--yes", "--symmetric",
+          "--cipher-algo", "AES256", "--s2k-mode", "3",
+          "--s2k-count", "65011712", "--passphrase-file", password_path,
+          "-o", enc_path, file_path
+        )
+      end
       unless status.success?
         @errors << "GPG encryption failed: #{stderr}"
         return file_path
@@ -397,8 +454,7 @@ module RailsNexus
       FileUtils.mkdir_p(chunk_dir)
 
       # Split 50MB chunks
-      cmd = "split -b 50m \"#{file_path}\" \"#{chunk_dir}/part_\""
-      stdout, stderr, status = Open3.capture3(cmd)
+      _, stderr, status = capture_command("split", "-b", "50m", file_path, File.join(chunk_dir, "part_"))
 
       unless status.success?
         @errors << "split failed: #{stderr}"
@@ -417,18 +473,44 @@ module RailsNexus
       return unless @config.rsync_enabled?
       return unless @config.rsync_host.present?
 
+      validate_host!(@config.rsync_host)
+      validate_port!(@config.rsync_port.presence || 22)
+      validate_remote_component!(@config.rsync_user, "rsync user")
+      validate_remote_path!(@config.rsync_path)
       remote = "#{@config.rsync_user}@#{@config.rsync_host}:#{@config.rsync_path}/"
 
-      cmd = [
-        "rsync",
-        "-avz",
-        "--progress",
-        "-e", "ssh -p #{@config.rsync_port}",
-        "\"#{file_path}\"",
-        remote
-      ].join(" ")
-
-      stdout, stderr, status = Open3.capture3(cmd)
+      # Build rsync command
+      cmd = ["rsync"]
+      cmd << "-a"
+      cmd << "-z"  # compress
+      cmd << "--progress"
+      cmd << "--archive" if @config.respond_to?(:rsync_archive?) && @config.rsync_archive?
+      cmd << "--delete" if @config.respond_to?(:rsync_mirror?) && @config.rsync_mirror?
+      cmd << "-e"
+      cmd << "ssh -p #{@config.rsync_port.presence || 22}"
+
+      # Add the dump file
+      cmd << file_path
+
+      # Add additional directories if configured
+      if @config.respond_to?(:rsync_directories) && @config.rsync_directories.present?
+        @config.rsync_directories.split(",").map(&:strip).reject(&:blank?).each do |dir|
+          expanded = dir.gsub("~", Dir.home)
+          cmd << expanded
+        end
+      end
+
+      # Add excludes
+      if @config.respond_to?(:rsync_excludes) && @config.rsync_excludes.present?
+        @config.rsync_excludes.split(",").map(&:strip).reject(&:blank?).each do |excl|
+          validate_text_argument!(excl, "rsync exclusion")
+          cmd << "--exclude=#{excl}"
+        end
+      end
+
+      cmd << remote
+
+      stdout, stderr, status = capture_command(*cmd)
       unless status.success?
         @errors << "RSync failed: #{stderr}"
       end
@@ -451,16 +533,20 @@ module RailsNexus
     end
 
     def sync_s3_aws(file_path)
+      validate_s3_bucket!(@config.s3_bucket)
       bucket = @config.s3_bucket
       prefix = @config.s3_prefix.present? ? "#{@config.s3_prefix}/" : ""
 
-      cmd = "AWS_ACCESS_KEY_ID=#{@config.s3_access_key} " \
-            "AWS_SECRET_ACCESS_KEY=#{@config.s3_secret_key} " \
-            "aws s3 cp \"#{file_path}\" " \
-            "s3://#{bucket}/#{prefix}" \
-            "--region #{@config.s3_region || 'us-east-1'}"
+      env = {
+        "AWS_ACCESS_KEY_ID" => @config.s3_access_key.to_s,
+        "AWS_SECRET_ACCESS_KEY" => @config.s3_secret_key.to_s
+      }
+      cmd = [
+        "aws", "s3", "cp", file_path, "s3://#{bucket}/#{prefix}",
+        "--region", @config.s3_region.presence || "us-east-1"
+      ]
 
-      stdout, stderr, status = Open3.capture3(cmd)
+      stdout, stderr, status = capture_command(env, *cmd)
       unless status.success?
         @errors << "S3 upload failed: #{stderr}"
       end
@@ -469,16 +555,20 @@ module RailsNexus
     end
 
     def sync_s3_s3cmd(file_path)
+      validate_s3_bucket!(@config.s3_bucket)
       bucket = @config.s3_bucket
       prefix = @config.s3_prefix.present? ? "#{@config.s3_prefix}/" : ""
 
-      cmd = "s3cmd put \"#{file_path}\" " \
-            "s3://#{bucket}/#{prefix} " \
-            "--access_key=#{@config.s3_access_key} " \
-            "--secret_key=#{@config.s3_secret_key} " \
-            "--region=#{@config.s3_region || 'us-east-1'}"
+      env = {
+        "AWS_ACCESS_KEY" => @config.s3_access_key.to_s,
+        "AWS_SECRET_KEY" => @config.s3_secret_key.to_s
+      }
+      cmd = [
+        "s3cmd", "put", file_path, "s3://#{bucket}/#{prefix}",
+        "--region=#{@config.s3_region.presence || 'us-east-1'}"
+      ]
 
-      stdout, stderr, status = Open3.capture3(cmd)
+      stdout, stderr, status = capture_command(env, *cmd)
       unless status.success?
         @errors << "S3 upload (s3cmd) failed: #{stderr}"
       end
@@ -499,22 +589,12 @@ module RailsNexus
 
       while files.size > @config.keep_count
         old_file = files.shift
-        if File.directory?(old_file)
-          FileUtils.rm_rf(old_file)
-        else
-          File.delete(old_file) if File.exist?(old_file)
-        end
+        FileUtils.rm_rf(old_file)
       end
     end
 
     def cleanup_temp_files
-      @temp_files.each do |f|
-        if File.directory?(f)
-          FileUtils.rm_rf(f)
-        else
-          File.delete(f) if File.exist?(f)
-        end
-      end
+      @temp_files.each { |file| FileUtils.rm_rf(file) }
     end
 
     # ════════════════════════════════════════════════════════════════
@@ -536,13 +616,23 @@ module RailsNexus
     def execute_notify_command(status, error = nil)
       return if @config.notify_command.blank?
 
-      cmd = @config.notify_command
-        .gsub("{STATUS}", status.to_s)
-        .gsub("{MODEL}", @config.name)
-        .gsub("{ERROR}", error.to_s)
-        .gsub("{TIME}", Time.current.iso8601)
+      command = Shellwords.split(@config.notify_command.to_s)
+      raise ArgumentError, "notify command is empty" if command.empty?
+      if %w[sh bash dash zsh ksh fish env].include?(File.basename(command.first))
+        raise ArgumentError, "shell-based notify commands are not supported"
+      end
 
-      Open3.capture3(cmd)
+      replacements = {
+        "{STATUS}" => status.to_s,
+        "{MODEL}" => @config.name.to_s,
+        "{ERROR}" => error.to_s,
+        "{TIME}" => Time.current.iso8601
+      }
+      command.map! do |argument|
+        replacements.reduce(argument) { |value, (placeholder, replacement)| value.gsub(placeholder, replacement) }
+      end
+
+      capture_command(*command)
     rescue StandardError
       # Don't fail backup because notification failed
     end
@@ -559,12 +649,10 @@ module RailsNexus
 
       # Build mail command based on available MTA
       if command_exists?("mail")
-        cmd = "echo #{body.shellescape} | mail -s #{subject.shellescape} #{@config.email_to}"
-        Open3.capture3(cmd)
+        capture_command("mail", "-s", subject, @config.email_to.to_s, stdin_data: body)
       elsif command_exists?("sendmail")
         mail_content = "To: #{@config.email_to}\nSubject: #{subject}\n\n#{body}"
-        cmd = "echo #{mail_content.shellescape} | sendmail -t"
-        Open3.capture3(cmd)
+        capture_command("sendmail", "-t", stdin_data: mail_content)
       else
         @errors << "No mail command found (mail/sendmail)"
       end
@@ -588,8 +676,142 @@ module RailsNexus
       @temp_files << path unless @temp_files.include?(path)
     end
 
+    # ─── Password Resolution ──────────────────────────────────────
+    # Supports:
+    #   "plain_text"              → used as-is
+    #   "ENV[MY_VAR]"             → resolved from ENV
+    #   "${MY_VAR}"               → resolved from ENV
+    #   "credentials[:key]"       → from Rails encrypted credentials
+    #   "credentials[:a][:b]"     → nested credentials key
+    def resolve_password(value)
+      return nil if value.blank?
+      resolve_secret(value)
+    end
+
+    alias_method :resolve_env, :resolve_password
+
+    def resolve_secret(value)
+      return nil if value.blank?
+      case value
+      when /^ENV\[(.+?)\]$/, /^\$\{(.+?)\}$/
+        ENV[$1]
+      when /^credentials\[/
+        # credentials[:key] or credentials[:key][:subkey]
+        keys = value.scan(/\[:([^\]]+)\]/).flatten.map(&:to_sym)
+        Rails.application.credentials.dig(*keys)
+      else
+        value
+      end
+    end
+
     def command_exists?(cmd)
-      system("which #{cmd} > /dev/null 2>&1")
+      executable = cmd.to_s
+      return false unless executable.match?(/\A[a-zA-Z0-9_.+-]+\z/)
+
+      ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |directory|
+        path = File.join(directory, executable)
+        File.file?(path) && File.executable?(path)
+      end
+    end
+
+    def capture_redis(host, port, password, *arguments)
+      env = {}
+      env["REDISCLI_AUTH"] = password if password.present?
+      capture_command(env, "redis-cli", "-h", host.to_s, "-p", port.to_s, *arguments.map(&:to_s))
+    end
+
+    def with_secret_file(prefix, contents)
+      Tempfile.create([prefix, ".conf"]) do |file|
+        file.chmod(0o600)
+        file.write(contents)
+        file.flush
+        yield file.path
+      end
+    end
+
+    def validated_mysql_options(value)
+      allowed = %r{\A(?:
+        --ssl-mode=(?:DISABLED|PREFERRED|REQUIRED|VERIFY_CA|VERIFY_IDENTITY)|
+        --ssl-(?:ca|cert|key)=\S+|
+        --protocol=(?:TCP|SOCKET)|
+        --socket=\S+|
+        --default-character-set=[a-zA-Z0-9_-]+|
+        --max-allowed-packet=\d+[KMG]?|
+        --set-gtid-purged=(?:OFF|ON|AUTO)|
+        --column-statistics=[01]|
+        --no-tablespaces|
+        --skip-lock-tables
+      )\z}x
+
+      Shellwords.split(value.to_s).tap do |options|
+        invalid = options.reject { |option| option.match?(allowed) }
+        raise ArgumentError, "unsupported MySQL option: #{invalid.first}" if invalid.any?
+      end
+    rescue ArgumentError => error
+      raise ArgumentError, "invalid MySQL additional options: #{error.message}"
+    end
+
+    def validate_identifier!(value, label)
+      candidate = value.to_s
+      unless candidate.match?(/\A[a-zA-Z0-9_$][a-zA-Z0-9_$.-]*\z/) && !candidate.include?("..")
+        raise ArgumentError, "invalid #{label}"
+      end
+      candidate
+    end
+
+    def validate_port!(value)
+      port = Integer(value)
+      raise ArgumentError, "invalid port" unless port.between?(1, 65_535)
+      port
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "invalid port"
+    end
+
+    def validate_host!(value)
+      host = value.to_s
+      unless host.match?(/\A[a-zA-Z0-9](?:[a-zA-Z0-9.-]*[a-zA-Z0-9])?\z/)
+        raise ArgumentError, "invalid host"
+      end
+      host
+    end
+
+    def validated_path(value, label)
+      validate_text_argument!(value, label)
+      File.expand_path(value.to_s)
+    end
+
+    def validate_remote_component!(value, label)
+      candidate = value.to_s
+      raise ArgumentError, "invalid #{label}" unless candidate.match?(/\A[a-zA-Z0-9_.-]+\z/)
+      candidate
+    end
+
+    def validate_remote_path!(value)
+      path = value.to_s
+      raise ArgumentError, "invalid rsync path" unless path.start_with?("/")
+      validate_text_argument!(path, "rsync path")
+    end
+
+    def validate_s3_bucket!(value)
+      bucket = value.to_s
+      unless bucket.length.between?(3, 63) && bucket.match?(/\A[a-z0-9][a-z0-9.-]*[a-z0-9]\z/) && !bucket.include?("..")
+        raise ArgumentError, "invalid S3 bucket"
+      end
+      bucket
+    end
+
+    def validate_text_argument!(value, label)
+      candidate = value.to_s
+      if candidate.empty? || candidate.include?("\0") || candidate.include?("\n") || candidate.include?("\r")
+        raise ArgumentError, "invalid #{label}"
+      end
+      candidate
+    end
+
+    def failure_message(exception)
+      heading = "#{@stage || 'backup'} failed: #{exception.class}: #{exception.message}"
+      trace = Array(exception.backtrace).first(5).join("\n")
+      [heading, trace.presence, @errors.join("\n").presence].compact.join("\n\n")
     end
   end
 end