ruborg 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1233e04a2f95e8e8aadb9ad97d043b2d9b52c446821ff89495073a6a8762b6cc
-  data.tar.gz: ee3fd1ae2256299120d7f78aac3243c2de44f8f3c072c4c29dd44cb761caf769
+  metadata.gz: 53e7193db767d8d7c217f89a4af6e7b4b4e18cdcc38cf0a8dff138767b561c10
+  data.tar.gz: 25c0232d3e86628d9ffb350f1d85e08f71ca032e72183e8d592108533ef2bc51
 SHA512:
-  metadata.gz: 59d6ad7e5797cbbd964390d0425bf1392695c24f938a40978ddea371552da84604bf0a8eb189b207318ed68dba966311d45659f2b6abd3a59711f766465a5b36
-  data.tar.gz: 6c77a312c9b820dd22d7f0396dbb24fac70da4654023c89eebc94c962d367b963a448a923ce23574862276452c441e3ebd723601fd58a2634e3337d402a9c066
+  metadata.gz: 6149c0535369f3f3b8f9829985fe6fa47777d0e2a6bcaf87630044bb7d7d2426be02ab104c87b50bc309352f9bdb80cad123e1549fc7c941dfe60b052840c95e
+  data.tar.gz: c0b036527fe8a70f526eebf07173f740d45fb88cd1fec3cd67a70b7331d7f806346d42b51217eefe4db2e8a8a7257f378a902c7711de657d9ef1603a460aaf46

data/.ruby-version

@@ -0,0 +1 @@
+3.2.9

data/CHANGELOG.md

@@ -7,6 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1] - 2025-10-08
+
+### Added
+- **Enhanced Configuration Validation**: Comprehensive validation system to catch configuration errors early
+  - **Unknown Key Detection**: Detects typos and invalid configuration keys at all levels (global, repository, sources, retention, passbolt, borg_options)
+  - **Retention Policy Validation**: Validates retention policy structure and values
+    - Integer fields (keep_hourly, keep_daily, etc.) must be non-negative integers
+    - Time-based fields (keep_within, keep_files_modified_within) must use correct format (e.g., "7d", "30d")
+    - Validates time format with h/d/w/m/y suffixes
+    - Rejects empty retention policies
+    - Detects unknown retention keys
+  - **Passbolt Configuration Validation**: Validates passbolt config structure
+    - Requires non-empty `resource_id` string
+    - Type validation for resource_id field
+    - Detects unknown passbolt keys
+  - **Retention Mode Validation**: Validates `retention_mode` values (must be "standard" or "per_file")
+  - **Source Validation**: Validates source structure (name, paths, exclude fields)
+- **Comprehensive Logging**: Added logging throughout backup, restore, and deletion operations
+  - Repository operations (initialization, pruning, archive management)
+  - Backup operations (file counts, progress in per-file mode)
+  - Restore operations (extraction start/completion)
+  - Source file deletion tracking (with `--remove-source`)
+  - Passbolt integration events (resource ID logged, never passwords)
+  - All sensitive data (passwords, encryption keys) protected from logs
+- **Enhanced Test Suite**: Expanded test coverage to 220 examples (67 new tests added)
+  - 23 new configuration validation tests
+  - 28 new logging integration tests
+  - 10 new CLI validation tests
+  - 6 new type checking tests for boolean configurations
+  - All tests passing with 0 failures
+
+### Changed
+- `global_settings` now includes `borg_path` (previously was in whitelist but not propagated)
+- Validation errors are collected and reported together for better user experience
+- All validation runs automatically on configuration load
+
+### Fixed
+- **Configuration Consistency**: Fixed inconsistency where `borg_path` was allowed in VALID_GLOBAL_KEYS but not returned by `global_settings` method
+
+## [0.6.0] - 2025-10-08
+
+### Added
+- **Configuration Validation Command**: New `ruborg validate` command to check configuration files for type errors
+- **Automatic Schema Validation**: All commands now validate configuration on startup to catch errors early
+- **Strict Boolean Type Checking**: All boolean config values (auto_init, auto_prune, allow_remove_source, etc.) now require actual boolean types
+  - Prevents type confusion attacks where strings like `'true'` or `"false"` bypass security checks
+  - Clear error messages show actual type vs expected type
+  - Validation runs automatically on config load
+- Comprehensive validation test suite (10 new test cases)
+- Documentation for configuration validation in README
+
+### Changed
+- Boolean configuration values now use strict type checking throughout the codebase
+  - `auto_init`: only boolean `true` enables, everything else disables
+  - `auto_prune`: only boolean `true` enables, everything else disables
+  - `allow_remove_source`: strict checking - only `TrueClass` enables (security-critical)
+  - `allow_relocated_repo`: permissive normalization - only `false` disables (backward compatible)
+  - `allow_unencrypted_repo`: permissive normalization - only `false` disables (backward compatible)
+- Config class now validates schema by default (can be disabled with `validate_types: false`)
+
+### Security
+- **Type Confusion Protection (CWE-843)**: Strict boolean type checking prevents configuration bypass attacks
+  - Before: `allow_remove_source: 'false'` (string) would be truthy and enable deletion
+  - After: Only `allow_remove_source: true` (boolean) enables the dangerous operation
+- Enhanced error messages guide users to fix type errors correctly
+- SECURITY.md updated with type confusion findings and mitigations
+
 ## [0.5.0] - 2025-10-08
 
 ### Added

data/README.md

@@ -17,7 +17,7 @@ A friendly Ruby frontend for [Borg Backup](https://www.borgbackup.org/). Ruborg
 - 📊 **Logging** - Comprehensive logging with daily rotation
 - 🗄️ **Multi-Repository** - Manage multiple backup repositories with different sources
 - 🔄 **Auto-initialization** - Automatically initialize repositories on first use
-e- ⏰ **Retention Policies** - Configure backup retention (hourly, daily, weekly, monthly, yearly)
+- ⏰ **Retention Policies** - Configure backup retention (hourly, daily, weekly, monthly, yearly)
 - 🗑️ **Automatic Pruning** - Automatically remove old backups based on retention policies
 - 📁 **Per-File Backup Mode** - NEW! Backup each file as a separate archive with metadata-based retention
 - 🕒 **File Metadata Retention** - NEW! Prune based on file modification time, works even after files are deleted
@@ -25,7 +25,7 @@ e- ⏰ **Retention Policies** - Configure backup retention (hourly, daily, weekl
 - 📈 **Summary View** - Quick overview of all repositories and their configurations
 - 🔧 **Custom Borg Path** - Support for custom Borg executable paths per repository
 - 🏠 **Hostname Validation** - NEW! Restrict backups to specific hosts (global or per-repository)
-- ✅ **Well-tested** - Comprehensive test suite with RSpec (153 tests)
+- ✅ **Well-tested** - Comprehensive test suite with RSpec (220 examples, 0 failures)
 - 🔒 **Security-focused** - Path validation, safe YAML loading, command injection protection
 
 ## Prerequisites
@@ -162,15 +162,173 @@ repositories:
 ```
 
 **Configuration Features:**
+- **Automatic Type Validation**: Configuration is validated on startup to catch type errors early
+- **Validation Command**: Run `ruborg validate` to check configuration files for errors
 - **Descriptions**: Add `description` field to document each repository's purpose
 - **Hostname Validation**: Optional `hostname` field to restrict backups to specific hosts (global or per-repository)
-- **Global Settings**: Hostname, compression, encryption, auto_init, log_file, borg_path, borg_options, and retention apply to all repositories
-- **Per-Repository Overrides**: Any global setting can be overridden at the repository level (including hostname and custom borg_path)
+- **Source Deletion Safety**: `allow_remove_source` flag to explicitly enable `--remove-source` option (default: disabled)
+- **Type-Safe Booleans**: Strict boolean validation prevents configuration errors (must use `true`/`false`, not strings)
+- **Global Settings**: Hostname, compression, encryption, auto_init, allow_remove_source, log_file, borg_path, borg_options, and retention apply to all repositories
+- **Per-Repository Overrides**: Any global setting can be overridden at the repository level (including hostname, allow_remove_source, and custom borg_path)
 - **Custom Borg Path**: Specify a custom Borg executable path if borg is not in PATH or to use a specific version
 - **Retention Policies**: Define how many backups to keep (hourly, daily, weekly, monthly, yearly)
 - **Multiple Sources**: Each repository can have multiple backup sources with their own exclude patterns
 - **Flexible Organization**: Organize backups by type (documents, databases, media) with different policies
 
+## Configuration Validation
+
+Ruborg automatically validates your configuration on startup. All commands check for type errors and structural issues before executing.
+
+### Validate Configuration
+
+Check your configuration file for errors:
+
+```bash
+ruborg validate --config ruborg.yml
+```
+
+**Validation checks:**
+- **Unknown configuration keys**: Detects typos and invalid keys at all levels (catches `auto_prun` vs `auto_prune`)
+- **Boolean types**: Must be `true` or `false`, not strings like `'true'`
+- **Retention policies**: Validates structure and values
+  - Integer fields (keep_hourly, keep_daily, etc.) must be non-negative integers
+  - Time-based fields (keep_within, keep_files_modified_within) must use format like "7d", "30d"
+  - Rejects empty retention policies
+  - Detects unknown retention keys
+- **Passbolt configuration**: Validates resource_id is non-empty string
+- **Retention mode**: Must be "standard" or "per_file"
+- **Compression values**: Must be one of: lz4, zstd, zlib, lzma, none
+- **Encryption modes**: Must be valid Borg encryption mode
+- **Repository structure**: Required fields (name, path, sources)
+- **Source structure**: Required fields (name, paths), validates exclude arrays
+- **Borg options**: Validates allow_relocated_repo and allow_unencrypted_repo
+
+**Example validation output:**
+
+```
+✓ Configuration is valid
+  No type errors or warnings found
+```
+
+Or with errors:
+
+```
+❌ ERRORS FOUND (2):
+  - global/auto_init: must be boolean (true or false), got String: "true"
+  - test-repo/allow_remove_source: must be boolean (true or false), got Integer: 1
+
+Configuration has errors that must be fixed.
+```
+
+## Logging
+
+Ruborg v0.6.1 includes comprehensive logging to help you track backup operations, troubleshoot issues, and maintain audit trails. Logs are written to `~/.ruborg/logs/ruborg.log` by default, or to a custom location specified in your configuration.
+
+### What Gets Logged
+
+Ruborg logs operational information at various levels to help you monitor and debug backup operations:
+
+#### Repository Operations
+- Repository creation and initialization
+- Repository path and encryption mode
+- Per-file pruning operations (archive counts, file modification times)
+- Archive deletion during pruning
+
+#### Backup Operations
+- Number of files found for backup (per-file mode)
+- Individual file backup progress (per-file mode)
+- Backup completion status
+- Archive names (user-provided or auto-generated)
+
+#### Restore Operations
+- Archive extraction start (archive name, destination path)
+- Specific paths being restored (if using `--path` option)
+- Extraction completion status
+
+#### Source File Deletion (when using `--remove-source`)
+- Start of source file removal process
+- Each file/directory being removed (with full resolved path)
+- Warnings for non-existent or missing paths
+- Errors when attempting to delete system directories (with path)
+- Count of items successfully removed
+
+#### Passbolt Integration
+- Password retrieval start (includes Passbolt resource UUID)
+- Password retrieval failures (includes resource UUID)
+
+### What Is NOT Logged
+
+To protect sensitive information, the following are **never logged**:
+
+- ✅ **Passwords and passphrases** - Neither from command line nor from Passbolt
+- ✅ **File contents** - Only file paths and metadata
+- ✅ **Encryption keys** - Repository encryption passphrases are never written to logs
+- ✅ **Passbolt passwords** - Only resource IDs (UUIDs) are logged, never the actual passwords retrieved
+
+### Log Levels
+
+- **INFO**: Normal operation events (backups, restores, deletions)
+- **WARN**: Non-critical issues (missing paths, skipped operations)
+- **ERROR**: Critical errors (system path deletion attempts, command failures)
+- **DEBUG**: Detailed information for troubleshooting (requires DEBUG level configuration)
+
+### Configuring Logging
+
+```yaml
+# Log to default location: ~/.ruborg/logs/ruborg.log
+log_file: default
+
+# OR custom log file path
+log_file: /var/log/ruborg/backup.log
+
+# OR disable file logging (stdout only)
+log_file: stdout
+```
+
+You can also override the log file location using the `--log` command-line option:
+
+```bash
+ruborg backup --repository documents --log /tmp/debug.log
+```
+
+### Log Security Considerations
+
+- **File Paths**: Logs contain file and directory paths being backed up. Secure your log files with appropriate permissions (recommended: `chmod 600` or `640`)
+- **Passbolt Resource IDs**: UUID identifiers for Passbolt resources are logged. These are safe to log as they are unguessable and don't expose credentials, but logs should still be protected
+- **Archive Names**: User-provided or auto-generated archive names are logged for audit purposes
+- **System Paths**: When `--remove-source` attempts to delete system directories, the full path is logged in error messages for security auditing
+
+### Best Practices
+
+1. **Secure Log Files**: Set restrictive permissions on log files
+   ```bash
+   chmod 600 ~/.ruborg/logs/ruborg.log
+   ```
+
+2. **Log Rotation**: Configure log rotation to prevent logs from consuming excessive disk space
+   ```bash
+   # Example logrotate configuration
+   /home/user/.ruborg/logs/ruborg.log {
+       weekly
+       rotate 4
+       compress
+       missingok
+       notifempty
+   }
+   ```
+
+3. **Monitoring**: Review logs regularly to detect:
+   - Failed backup operations
+   - Unauthorized deletion attempts
+   - Passbolt password retrieval failures
+   - Unexpected file paths
+
+4. **Audit Trail**: Logs provide an audit trail for compliance purposes:
+   - What was backed up and when
+   - What was restored and where
+   - What was deleted (with `--remove-source`)
+   - Any errors or security-related events
+
 ## Usage
 
 ### Initialize a Repository
@@ -198,10 +356,48 @@ ruborg backup --repository databases --name "db-backup-2025-10-05"
 # Using custom configuration file
 ruborg backup --config /path/to/config.yml --repository documents
 
-# Remove source files after successful backup
+# Remove source files after successful backup (requires allow_remove_source: true)
 ruborg backup --repository documents --remove-source
 ```
 
+**IMPORTANT: Source File Deletion Safety**
+
+The `--remove-source` option is disabled by default for safety. To use it, you must explicitly enable it in your configuration:
+
+```yaml
+# Global setting - applies to all repositories
+allow_remove_source: true
+
+# OR per-repository setting
+repositories:
+  - name: temp-backups
+    allow_remove_source: true  # Only for this repository
+    ...
+```
+
+**⚠️ TYPE SAFETY WARNING:** The value MUST be a boolean `true`, not a string:
+
+```yaml
+# ✅ CORRECT - Boolean true
+allow_remove_source: true
+
+# ❌ WRONG - String 'true' (will be rejected)
+allow_remove_source: 'true'
+allow_remove_source: "true"
+
+# ❌ WRONG - Other truthy values (will be rejected)
+allow_remove_source: 1
+allow_remove_source: yes
+```
+
+Ruborg uses strict type checking to prevent configuration errors. Only the boolean value `true` (unquoted) will enable source deletion. Any other value, including string `'true'` or `"true"`, will be rejected with a detailed error message showing the actual type received.
+
+Without `allow_remove_source: true` configured, using `--remove-source` will result in an error:
+```
+Error: Cannot use --remove-source: 'allow_remove_source' must be true (boolean).
+Current value: "true" (String). Set 'allow_remove_source: true' in configuration.
+```
+
 ### List Archives
 
 ```bash
@@ -272,31 +468,6 @@ Borg version: 1.2.8
     Please upgrade Borg or migrate the repository
 ```
 
-## Logging
-
-Ruborg automatically logs all operations with daily rotation. Log file location priority:
-
-1. **CLI option** (highest priority): `--log /path/to/custom.log`
-2. **Config file**: `log_file: /path/to/log.log`
-3. **Default**: `~/.ruborg/logs/ruborg.log`
-
-**Examples:**
-
-```bash
-# Use CLI option (overrides config)
-ruborg backup --log /var/log/ruborg.log
-
-# Or set in config file
-log_file: /var/log/ruborg.log
-```
-
-**Logs include:**
-- Operation start/completion timestamps
-- Paths being backed up
-- Archive names created
-- Success and error messages
-- Source file removal actions
-
 ## Passbolt Integration
 
 Ruborg can retrieve encryption passphrases from Passbolt using the Passbolt CLI:
@@ -437,6 +608,7 @@ See [SECURITY.md](SECURITY.md) for detailed security information and best practi
 | Command | Description | Options |
 |---------|-------------|---------|
 | `init REPOSITORY` | Initialize a new Borg repository | `--passphrase`, `--passbolt-id`, `--log` |
+| `validate` | Validate configuration file for type errors | `--config`, `--log` |
 | `backup` | Create a backup using config file | `--config`, `--repository`, `--all`, `--name`, `--remove-source`, `--log` |
 | `list` | List all archives in repository | `--config`, `--repository`, `--log` |
 | `restore ARCHIVE` | Restore files from archive | `--config`, `--repository`, `--destination`, `--path`, `--log` |

data/SECURITY.md

@@ -66,6 +66,81 @@ Ruborg implements several security measures to protect your backup operations:
 - Integrated into development workflow
 - Run: `bundle exec bundle-audit check`
 
+### 13. Boolean Type Safety (Type Confusion Protection)
+- **Critical safety flag validation** for `allow_remove_source` configuration
+- Uses strict type checking (`is_a?(TrueClass)`) to prevent type confusion attacks
+- Rejects truthy values like strings `'true'`, `"false"`, integers `1`, or `"yes"`
+- Only boolean `true` enables dangerous operations like `--remove-source`
+- Provides detailed error messages showing actual type received vs expected
+- Prevents configuration errors that could lead to unintended data loss
+- **CWE-843 Mitigation**: Protects against type confusion vulnerabilities
+
+### 14. Logging Security (v0.6.1+)
+- **Comprehensive logging** of backup operations for audit trails and troubleshooting
+- **Sensitive data protection**: Passwords and passphrases are NEVER logged
+- **Safe operational logging**: File paths, archive names, and operation status are logged
+- **Passbolt resource IDs** (UUIDs) are logged but actual passwords are not
+- **System path protection**: Failed deletion attempts are logged with full paths for security auditing
+- **Log level support**: INFO, WARN, ERROR, DEBUG levels for appropriate detail
+
+#### What Is Logged (Safe)
+- Repository creation and initialization events
+- Backup operation start/completion with file counts
+- Individual file paths being backed up (per-file mode)
+- Archive names (user-provided or auto-generated)
+- Restore operations with destination paths
+- Source file deletion events (when using `--remove-source`)
+- Passbolt resource IDs (UUIDs) for password retrieval attempts
+- System path deletion refusals with full path (security audit)
+- Pruning operations with archive counts
+
+#### What Is NEVER Logged (Protected)
+- ✅ **Passwords and passphrases** - Neither from CLI nor Passbolt
+- ✅ **Encryption keys** - Repository encryption keys never written to logs
+- ✅ **Passbolt passwords** - Only resource UUIDs logged, not actual retrieved passwords
+- ✅ **File contents** - Only paths and metadata, never file contents
+- ✅ **Environment variables** with sensitive data
+
+#### Log Security Recommendations
+1. **Protect log files** with restrictive permissions:
+   ```bash
+   chmod 600 ~/.ruborg/logs/ruborg.log
+   # Or for shared access with backup group:
+   chmod 640 ~/.ruborg/logs/ruborg.log
+   chown user:backup ~/.ruborg/logs/ruborg.log
+   ```
+
+2. **Configure log rotation** to prevent log files from growing indefinitely:
+   ```bash
+   # /etc/logrotate.d/ruborg
+   /home/user/.ruborg/logs/ruborg.log {
+       weekly
+       rotate 4
+       compress
+       missingok
+       notifempty
+       create 0600 user user
+   }
+   ```
+
+3. **Review logs regularly** for:
+   - Failed backup or restore operations
+   - Unauthorized `--remove-source` attempts
+   - Passbolt password retrieval failures
+   - System path deletion attempts (potential security issues)
+   - Unexpected file paths being backed up
+
+4. **Secure log storage locations**:
+   - Use absolute paths in `log_file` configuration
+   - Avoid logging to world-readable directories
+   - Consider logging to `/var/log/ruborg/` with proper permissions
+
+5. **Passbolt Resource IDs in Logs**:
+   - Resource IDs (UUIDs) are logged for operational debugging
+   - These are identifiers, not credentials - safe to log
+   - They cannot be used to access Passbolt without proper authentication
+   - Still, protect logs as they reveal which Passbolt resources are used
+
 ## Security Best Practices
 
 ### When Using `--remove-source`
@@ -76,6 +151,16 @@ Ruborg implements several security measures to protect your backup operations:
 2. **Never use on symlinks** to critical system directories
 3. **Verify backups** before using this flag in production
 4. **Use absolute paths** in configuration to avoid ambiguity
+5. **Use boolean values** for `allow_remove_source` - NEVER use quoted strings:
+   ```yaml
+   # ✅ CORRECT
+   allow_remove_source: true
+
+   # ❌ WRONG - Will be rejected
+   allow_remove_source: 'true'
+   allow_remove_source: "true"
+   allow_remove_source: 1
+   ```
 
 ### Configuration File Security
 
@@ -144,6 +229,29 @@ We will respond within 48 hours and work with you to address the issue.
 
 ## Security Audit History
 
+- **v0.6.1** (2025-10-08): Enhanced logging with sensitive data protection
+  - **NEW FEATURE**: Comprehensive logging for backup operations, restoration, and deletion
+  - Passwords and passphrases are NEVER logged (neither CLI nor Passbolt passwords)
+  - Passbolt resource IDs (UUIDs) logged for debugging - identifiers only, not credentials
+  - File paths and archive names logged for audit trails
+  - System path deletion attempts logged with full paths for security monitoring
+  - Log levels: INFO, WARN, ERROR, DEBUG for appropriate detail
+  - Documentation added for logging security best practices
+  - Enhanced configuration validation with unknown key detection across all levels
+
+- **v0.6.0** (2025-10-08): Configuration validation and type confusion protection
+  - **SECURITY FIX**: Implemented strict boolean type checking for `allow_remove_source`
+  - Prevents type confusion attacks (CWE-843) where string values bypass safety checks
+  - Added configuration validation command (`ruborg validate`) for proactive error detection
+  - Automatic schema validation on config load catches type errors early
+  - Added 10 comprehensive test cases for validation and type confusion scenarios
+  - Enhanced error messages to show actual type vs expected type
+  - Updated documentation with type safety warnings and examples
+
+- **v0.5.0** (2025-10-08): Hostname validation
+  - Added hostname validation feature (optional global or per-repository)
+  - Prevents accidental execution of backups on wrong machines
+
 - **v0.4.0** (2025-10-06): Complete command injection elimination
   - **CRITICAL**: Fixed all remaining command injection vulnerabilities in repository.rb
   - Replaced all backtick execution with Open3.capture3/capture2e methods
@@ -210,3 +318,5 @@ Before deploying ruborg in production:
 - [ ] Configure borg_options for your security requirements
 - [ ] Use default archive names or sanitized custom names only
 - [ ] Ensure backup paths don't contain empty or nil values
+- [ ] Use boolean `true` (not strings) for `allow_remove_source` configuration
+- [ ] Configure hostname validation for multi-server environments

data/exe/ruborg

@@ -3,4 +3,12 @@
 
 require_relative "../lib/ruborg"
 
-Ruborg::CLI.start(ARGV)
+begin
+  Ruborg::CLI.start(ARGV)
+rescue Ruborg::Error => e
+  warn "Error: #{e.message}"
+  exit 1
+rescue Interrupt
+  warn "\nInterrupted"
+  exit 130
+end

data/lib/ruborg/backup.rb

@@ -3,11 +3,12 @@
 module Ruborg
   # Backup operations using Borg
   class Backup
-    def initialize(repository, config:, retention_mode: "standard", repo_name: nil)
+    def initialize(repository, config:, retention_mode: "standard", repo_name: nil, logger: nil)
       @repository = repository
       @config = config
       @retention_mode = retention_mode
       @repo_name = repo_name
+      @logger = logger
     end
 
     def create(name: nil, remove_source: false)
@@ -37,19 +38,25 @@ module Ruborg
 
       raise BorgError, "No files found to backup" if files_to_backup.empty?
 
+      @logger&.info("Per-file mode: Found #{files_to_backup.size} file(s) to backup")
+
       timestamp = Time.now.strftime("%Y-%m-%d_%H-%M-%S")
 
-      files_to_backup.each do |file_path|
+      files_to_backup.each_with_index do |file_path, index|
         # Generate hash-based archive name
         path_hash = generate_path_hash(file_path)
         archive_name = name_prefix || "#{@repo_name}-#{path_hash}-#{timestamp}"
 
+        @logger&.info("Backing up file #{index + 1}/#{files_to_backup.size}: #{file_path}")
+
         # Create archive for single file with original path as comment
         cmd = build_per_file_create_command(archive_name, file_path)
 
         execute_borg_command(cmd)
       end
 
+      @logger&.info("Per-file backup completed: #{files_to_backup.size} file(s) backed up")
+
       # NOTE: remove_source handled per file after successful backup
       remove_source_files if remove_source
     end
@@ -108,6 +115,9 @@ module Ruborg
     def extract(archive_name, destination: ".", path: nil)
       raise BorgError, "Repository does not exist" unless @repository.exists?
 
+      extract_target = path ? "#{path} from #{archive_name}" : archive_name
+      @logger&.info("Extracting #{extract_target} to #{destination}")
+
       cmd = [@repository.borg_path, "extract", "#{@repository.path}::#{archive_name}"]
       cmd << path if path
 
@@ -125,6 +135,8 @@ module Ruborg
           execute_borg_command(cmd)
         end
       end
+
+      @logger&.info("Extraction completed successfully")
     end
 
     def list_archives
@@ -132,8 +144,10 @@ module Ruborg
     end
 
     def delete(archive_name)
+      @logger&.info("Deleting archive: #{archive_name}")
       cmd = [@repository.borg_path, "delete", "#{@repository.path}::#{archive_name}"]
       execute_borg_command(cmd)
+      @logger&.info("Archive deleted successfully: #{archive_name}")
     end
 
     private
@@ -171,29 +185,45 @@ module Ruborg
     def remove_source_files
       require "fileutils"
 
+      @logger&.info("Removing source files after successful backup")
+
+      removed_count = 0
+
       @config.backup_paths.each do |path|
         # Resolve symlinks and validate path
         begin
           real_path = File.realpath(path)
         rescue Errno::ENOENT
           # Path doesn't exist, skip
+          @logger&.warn("Source path does not exist, skipping: #{path}")
           next
         end
 
         # Security check: ensure path hasn't been tampered with
-        next unless File.exist?(real_path)
+        unless File.exist?(real_path)
+          @logger&.warn("Source path no longer exists, skipping: #{real_path}")
+          next
+        end
 
         # Additional safety: don't delete root or system directories
         if real_path == "/" || real_path.start_with?("/bin", "/sbin", "/usr", "/etc", "/sys", "/proc")
+          @logger&.error("Refusing to delete system path: #{real_path}")
           raise BorgError, "Refusing to delete system path: #{real_path}"
         end
 
+        file_type = File.directory?(real_path) ? "directory" : "file"
+        @logger&.info("Removing #{file_type}: #{real_path}")
+
         if File.directory?(real_path)
           FileUtils.rm_rf(real_path, secure: true)
         elsif File.file?(real_path)
           FileUtils.rm(real_path)
         end
+
+        removed_count += 1
       end
+
+      @logger&.info("Source file removal completed: #{removed_count} item(s) removed")
     end
 
     def validate_destination_path(destination)