ruborg 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 821f1707180870ec6b2ffccda4ef4d901b3ee274d7402c26170ca294e80efb8b
-  data.tar.gz: 62e2a5ee53cd75024b78e08e32295c34cf1829cd3bd34be9d6403c7ec1dfb810
+  metadata.gz: 53e7193db767d8d7c217f89a4af6e7b4b4e18cdcc38cf0a8dff138767b561c10
+  data.tar.gz: 25c0232d3e86628d9ffb350f1d85e08f71ca032e72183e8d592108533ef2bc51
 SHA512:
-  metadata.gz: acd1bcd0b6da0914888c11d50299ea2f365e2bf5a81423edbfc7e935a17d020b841de9043900ca86ed1df2ab8e50e1359806ad2857de3bd849b8f040c2909549
-  data.tar.gz: 799d52c64a3bf858b2324f5101255a77dd428778b1eced9bfa11e54d9c2ef23642645a886902f83c05336c89a61d1a80b02ad83185fecf3cf0cac866d18e7c09
+  metadata.gz: 6149c0535369f3f3b8f9829985fe6fa47777d0e2a6bcaf87630044bb7d7d2426be02ab104c87b50bc309352f9bdb80cad123e1549fc7c941dfe60b052840c95e
+  data.tar.gz: c0b036527fe8a70f526eebf07173f740d45fb88cd1fec3cd67a70b7331d7f806346d42b51217eefe4db2e8a8a7257f378a902c7711de657d9ef1603a460aaf46

data/.ruby-version

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

data/CHANGELOG.md

@@ -7,6 +7,45 @@ 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

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 (178+ tests)
+- ✅ **Well-tested** - Comprehensive test suite with RSpec (220 examples, 0 failures)
 - 🔒 **Security-focused** - Path validation, safe YAML loading, command injection protection
 
 ## Prerequisites
@@ -188,11 +188,20 @@ ruborg validate --config ruborg.yml
 ```
 
 **Validation checks:**
-- Boolean types (must be `true` or `false`, not strings like `'true'`)
-- Valid compression values (lz4, zstd, zlib, lzma, none)
-- Valid encryption modes
-- Required repository fields (name, path)
-- Correct borg_options values
+- **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:**
 
@@ -211,6 +220,115 @@ Or with errors:
 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
@@ -350,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:

data/SECURITY.md

@@ -75,6 +75,72 @@ Ruborg implements several security measures to protect your backup operations:
 - 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`
@@ -163,6 +229,16 @@ 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

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)

data/lib/ruborg/cli.rb

@@ -38,13 +38,13 @@ module Ruborg
     def init(repository_path)
       @logger.info("Initializing repository at #{repository_path}")
       passphrase = get_passphrase(options[:passphrase], options[:passbolt_id])
-      repo = Repository.new(repository_path, passphrase: passphrase)
+      repo = Repository.new(repository_path, passphrase: passphrase, logger: @logger)
       repo.create
       @logger.info("Repository successfully initialized at #{repository_path}")
       puts "Repository initialized at #{repository_path}"
     rescue Error => e
       @logger.error("Failed to initialize repository: #{e.message}")
-      error_exit(e)
+      raise
     end
 
     desc "backup", "Create a backup using configuration file"
@@ -54,11 +54,10 @@ module Ruborg
     def backup
       @logger.info("Starting backup operation with config: #{options[:config]}")
       config = Config.new(options[:config])
-      validate_hostname(config.global_settings)
       backup_repositories(config)
     rescue Error => e
       @logger.error("Backup failed: #{e.message}")
-      error_exit(e)
+      raise
     end
 
     desc "list", "List all archives in the repository"
@@ -78,7 +77,7 @@ module Ruborg
       borg_opts = merged_config["borg_options"] || {}
       borg_path = merged_config["borg_path"]
 
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path)
+      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path, logger: @logger)
 
       # Auto-initialize repository if configured
       # Use strict boolean checking: only true enables, everything else disables
@@ -94,7 +93,7 @@ module Ruborg
       @logger.info("Successfully listed archives")
     rescue Error => e
       @logger.error("Failed to list archives: #{e.message}")
-      error_exit(e)
+      raise
     end
 
     desc "restore ARCHIVE", "Restore files from an archive"
@@ -117,11 +116,11 @@ module Ruborg
       borg_opts = merged_config["borg_options"] || {}
       borg_path = merged_config["borg_path"]
 
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path)
+      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path, logger: @logger)
 
       # Create backup config wrapper for compatibility
       backup_config = BackupConfig.new(repo_config, merged_config)
-      backup = Backup.new(repo, config: backup_config)
+      backup = Backup.new(repo, config: backup_config, logger: @logger)
 
       backup.extract(archive_name, destination: options[:destination], path: options[:path])
       @logger.info("Successfully restored #{restore_target} to #{options[:destination]}")
@@ -133,7 +132,7 @@ module Ruborg
       end
     rescue Error => e
       @logger.error("Failed to restore archive: #{e.message}")
-      error_exit(e)
+      raise
     end
 
     desc "info", "Show repository information"
@@ -156,7 +155,7 @@ module Ruborg
       borg_opts = merged_config["borg_options"] || {}
       borg_path = merged_config["borg_path"]
 
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path)
+      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path, logger: @logger)
 
       # Auto-initialize repository if configured
       # Use strict boolean checking: only true enables, everything else disables
@@ -172,7 +171,79 @@ module Ruborg
       @logger.info("Successfully retrieved repository information")
     rescue Error => e
       @logger.error("Failed to get repository info: #{e.message}")
-      error_exit(e)
+      raise
+    end
+
+    desc "validate", "Validate configuration file for errors and type issues"
+    def validate_config
+      @logger.info("Validating configuration file: #{options[:config]}")
+      config = Config.new(options[:config])
+
+      puts "\n═══════════════════════════════════════════════════════════════"
+      puts "  CONFIGURATION VALIDATION"
+      puts "═══════════════════════════════════════════════════════════════\n\n"
+
+      errors = []
+      warnings = []
+
+      # Validate global boolean settings
+      global_settings = config.global_settings
+      errors.concat(validate_boolean_setting(global_settings, "auto_init", "global"))
+      errors.concat(validate_boolean_setting(global_settings, "auto_prune", "global"))
+      errors.concat(validate_boolean_setting(global_settings, "allow_remove_source", "global"))
+
+      # Validate borg_options booleans
+      if global_settings["borg_options"]
+        warnings.concat(validate_borg_option(global_settings["borg_options"], "allow_relocated_repo", "global"))
+        warnings.concat(validate_borg_option(global_settings["borg_options"], "allow_unencrypted_repo", "global"))
+      end
+
+      # Validate per-repository settings
+      config.repositories.each do |repo|
+        repo_name = repo["name"]
+        errors.concat(validate_boolean_setting(repo, "auto_init", repo_name))
+        errors.concat(validate_boolean_setting(repo, "auto_prune", repo_name))
+        errors.concat(validate_boolean_setting(repo, "allow_remove_source", repo_name))
+
+        if repo["borg_options"]
+          warnings.concat(validate_borg_option(repo["borg_options"], "allow_relocated_repo", repo_name))
+          warnings.concat(validate_borg_option(repo["borg_options"], "allow_unencrypted_repo", repo_name))
+        end
+      end
+
+      # Display results
+      if errors.empty? && warnings.empty?
+        puts "✓ Configuration is valid"
+        puts "  No type errors or warnings found\n\n"
+      else
+        unless errors.empty?
+          puts "❌ ERRORS FOUND (#{errors.size}):"
+          errors.each do |error|
+            puts "  - #{error}"
+          end
+          puts ""
+        end
+
+        unless warnings.empty?
+          puts "⚠️  WARNINGS (#{warnings.size}):"
+          warnings.each do |warning|
+            puts "  - #{warning}"
+          end
+          puts ""
+        end
+
+        if errors.any?
+          puts "Configuration has errors that must be fixed.\n\n"
+          raise ConfigError, "Configuration validation failed"
+        else
+          puts "Configuration is valid but has warnings.\n\n"
+        end
+      end
+
+      @logger.info("Configuration validation completed")
+    rescue Error => e
+      @logger.error("Validation failed: #{e.message}")
+      raise
     end
 
     desc "validate", "Validate configuration file for errors and type issues"
@@ -276,7 +347,7 @@ module Ruborg
       end
     rescue Error => e
       @logger.error("Check failed: #{e.message}")
-      error_exit(e)
+      raise
     end
 
     private
@@ -292,7 +363,7 @@ module Ruborg
       borg_opts = merged_config["borg_options"] || {}
       borg_path = merged_config["borg_path"]
 
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path)
+      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path, logger: @logger)
 
       unless repo.exists?
         puts "  ✗ Repository does not exist at #{repo_config["path"]}"
@@ -411,16 +482,11 @@ module Ruborg
 
     def get_passphrase(passphrase, passbolt_id)
       return passphrase if passphrase
-      return Passbolt.new(resource_id: passbolt_id).get_password if passbolt_id
+      return Passbolt.new(resource_id: passbolt_id, logger: @logger).get_password if passbolt_id
 
       nil
     end
 
-    def error_exit(error)
-      puts "Error: #{error.message}"
-      exit 1
-    end
-
     def validate_log_path(log_path)
       # Expand to absolute path
       normalized_path = File.expand_path(log_path)
@@ -477,7 +543,7 @@ module Ruborg
       passphrase = fetch_passphrase_for_repo(merged_config)
       borg_opts = merged_config["borg_options"] || {}
       borg_path = merged_config["borg_path"]
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path)
+      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path, logger: @logger)
 
       # Auto-initialize if configured
       # Use strict boolean checking: only true enables, everything else disables
@@ -505,7 +571,7 @@ module Ruborg
 
       # Create backup config wrapper
       backup_config = BackupConfig.new(repo_config, merged_config)
-      backup = Backup.new(repo, config: backup_config, retention_mode: retention_mode, repo_name: repo_name)
+      backup = Backup.new(repo, config: backup_config, retention_mode: retention_mode, repo_name: repo_name, logger: @logger)
 
       archive_name = options[:name] ? sanitize_archive_name(options[:name]) : nil
       @logger.info("Creating archive#{"s" if retention_mode == "per_file"}: #{archive_name || "auto-generated"}")
@@ -543,7 +609,7 @@ module Ruborg
       passbolt_config = repo_config["passbolt"]
       return nil if passbolt_config.nil? || passbolt_config.empty?
 
-      Passbolt.new(resource_id: passbolt_config["resource_id"]).get_password
+      Passbolt.new(resource_id: passbolt_config["resource_id"], logger: @logger).get_password
     end
 
     def sanitize_archive_name(name)

data/lib/ruborg/config.rb

@@ -41,7 +41,7 @@ module Ruborg
 
     def global_settings
       @data.slice("passbolt", "compression", "encryption", "auto_init", "borg_options", "log_file", "retention",
-                  "auto_prune", "hostname", "allow_remove_source")
+                  "auto_prune", "hostname", "allow_remove_source", "borg_path")
     end
 
     private
@@ -49,6 +49,29 @@ module Ruborg
     VALID_COMPRESSION = %w[lz4 zstd zlib lzma none].freeze
     VALID_ENCRYPTION = %w[repokey keyfile none authenticated repokey-blake2
                           keyfile-blake2 authenticated-blake2].freeze
+    VALID_RETENTION_MODES = %w[standard per_file].freeze
+
+    # Valid configuration keys at each level
+    VALID_GLOBAL_KEYS = %w[
+      hostname compression encryption auto_init auto_prune allow_remove_source
+      log_file borg_path passbolt borg_options retention repositories
+    ].freeze
+
+    VALID_REPOSITORY_KEYS = %w[
+      name description path hostname retention_mode passbolt retention sources
+      compression encryption auto_init auto_prune borg_options allow_remove_source
+    ].freeze
+
+    VALID_SOURCE_KEYS = %w[name paths exclude].freeze
+
+    VALID_RETENTION_KEYS = %w[
+      keep_hourly keep_daily keep_weekly keep_monthly keep_yearly
+      keep_within keep_last keep_files_modified_within
+    ].freeze
+
+    VALID_PASSBOLT_KEYS = %w[resource_id].freeze
+
+    VALID_BORG_OPTIONS_KEYS = %w[allow_relocated_repo allow_unencrypted_repo].freeze
 
     def validate_format
       return if @data.key?("repositories")
@@ -88,19 +111,25 @@ module Ruborg
     end
 
     # Validate YAML schema for type correctness
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
     def validate_schema
       errors = []
 
+      # Validate unknown keys
+      errors.concat(validate_unknown_keys(@data, VALID_GLOBAL_KEYS, "global"))
+
       # Validate global boolean settings
       errors.concat(validate_boolean_config(@data, "auto_init", "global"))
       errors.concat(validate_boolean_config(@data, "auto_prune", "global"))
       errors.concat(validate_boolean_config(@data, "allow_remove_source", "global"))
 
-      # Validate global borg_options
-      if @data["borg_options"]
-        errors.concat(validate_boolean_config(@data["borg_options"], "allow_relocated_repo", "global/borg_options"))
-        errors.concat(validate_boolean_config(@data["borg_options"], "allow_unencrypted_repo", "global/borg_options"))
-      end
+      # Note: borg_options are validated as warnings in CLI validate command, not as errors here
+
+      # Validate global passbolt
+      errors.concat(validate_passbolt_config(@data["passbolt"], "global")) if @data["passbolt"]
+
+      # Validate global retention
+      errors.concat(validate_retention_policy(@data["retention"], "global")) if @data["retention"]
 
       # Validate compression and encryption if present
       if @data["compression"] && !VALID_COMPRESSION.include?(@data["compression"])
@@ -112,20 +141,29 @@ module Ruborg
       end
 
       # Validate per-repository settings
+      # rubocop:disable Metrics/BlockLength
       repositories.each do |repo|
         repo_name = repo["name"] || "unnamed"
 
+        # Validate unknown keys in repository
+        errors.concat(validate_unknown_keys(repo, VALID_REPOSITORY_KEYS, repo_name))
+
         errors.concat(validate_boolean_config(repo, "auto_init", repo_name))
         errors.concat(validate_boolean_config(repo, "auto_prune", repo_name))
         errors.concat(validate_boolean_config(repo, "allow_remove_source", repo_name))
 
-        if repo["borg_options"]
-          errors.concat(validate_boolean_config(repo["borg_options"], "allow_relocated_repo",
-                                                "#{repo_name}/borg_options"))
-          errors.concat(validate_boolean_config(repo["borg_options"], "allow_unencrypted_repo",
-                                                "#{repo_name}/borg_options"))
+        # Validate retention_mode
+        if repo["retention_mode"] && !VALID_RETENTION_MODES.include?(repo["retention_mode"])
+          errors << "#{repo_name}/retention_mode: invalid value '#{repo["retention_mode"]}'. " \
+                    "Must be one of: #{VALID_RETENTION_MODES.join(", ")}"
         end
 
+        # Note: borg_options are validated as warnings in CLI validate command, not as errors here
+
+        errors.concat(validate_passbolt_config(repo["passbolt"], repo_name)) if repo["passbolt"]
+
+        errors.concat(validate_retention_policy(repo["retention"], repo_name)) if repo["retention"]
+
         # Validate compression and encryption if present
         if repo["compression"] && !VALID_COMPRESSION.include?(repo["compression"])
           errors << "#{repo_name}/compression: invalid value '#{repo["compression"]}'"
@@ -138,7 +176,24 @@ module Ruborg
         # Validate repository structure
         errors << "#{repo_name}: missing 'path' key" unless repo["path"]
         errors << "#{repo_name}: 'sources' must be an array" if repo["sources"] && !repo["sources"].is_a?(Array)
+
+        # Validate sources
+        next unless repo["sources"].is_a?(Array)
+
+        repo["sources"].each_with_index do |source, idx|
+          source_context = "#{repo_name}/sources[#{idx}]"
+          source_name = source["name"] || "unnamed"
+
+          errors.concat(validate_unknown_keys(source, VALID_SOURCE_KEYS, "#{repo_name}/sources/#{source_name}"))
+          errors << "#{source_context}: missing 'name' key" unless source["name"]
+          errors << "#{source_context}: missing 'paths' key" unless source["paths"]
+          errors << "#{source_context}: 'paths' must be an array" if source["paths"] && !source["paths"].is_a?(Array)
+          if source["exclude"] && !source["exclude"].is_a?(Array)
+            errors << "#{source_context}: 'exclude' must be an array"
+          end
+        end
       end
+      # rubocop:enable Metrics/BlockLength
 
       return if errors.empty?
 
@@ -146,6 +201,7 @@ module Ruborg
             "Configuration validation failed:\n  - #{errors.join("\n  - ")}\n\n" \
             "Run 'ruborg validate' for detailed validation information."
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
     def validate_boolean_config(config, key, context)
       errors = []
@@ -159,5 +215,99 @@ module Ruborg
 
       errors
     end
+
+    def validate_unknown_keys(config, valid_keys, context)
+      errors = []
+      return errors unless config.is_a?(Hash)
+
+      unknown_keys = config.keys - valid_keys
+      unknown_keys.each do |key|
+        errors << "#{context}: unknown configuration key '#{key}'"
+      end
+
+      errors
+    end
+
+    def validate_borg_options(borg_options, context)
+      errors = []
+
+      unless borg_options.is_a?(Hash)
+        errors << "#{context}/borg_options: must be a hash"
+        return errors
+      end
+
+      errors.concat(validate_unknown_keys(borg_options, VALID_BORG_OPTIONS_KEYS, "#{context}/borg_options"))
+      errors.concat(validate_boolean_config(borg_options, "allow_relocated_repo", "#{context}/borg_options"))
+      errors.concat(validate_boolean_config(borg_options, "allow_unencrypted_repo", "#{context}/borg_options"))
+
+      errors
+    end
+
+    def validate_passbolt_config(passbolt, context)
+      errors = []
+
+      unless passbolt.is_a?(Hash)
+        errors << "#{context}/passbolt: must be a hash"
+        return errors
+      end
+
+      errors.concat(validate_unknown_keys(passbolt, VALID_PASSBOLT_KEYS, "#{context}/passbolt"))
+
+      errors << "#{context}/passbolt: missing required 'resource_id' key" unless passbolt["resource_id"]
+
+      if passbolt["resource_id"] && !passbolt["resource_id"].is_a?(String)
+        errors << "#{context}/passbolt/resource_id: must be a string"
+      end
+
+      if passbolt["resource_id"].is_a?(String) && passbolt["resource_id"].strip.empty?
+        errors << "#{context}/passbolt/resource_id: cannot be empty"
+      end
+
+      errors
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    def validate_retention_policy(retention, context)
+      errors = []
+
+      unless retention.is_a?(Hash)
+        errors << "#{context}/retention: must be a hash"
+        return errors
+      end
+
+      errors.concat(validate_unknown_keys(retention, VALID_RETENTION_KEYS, "#{context}/retention"))
+
+      # Validate integer retention values
+      %w[keep_hourly keep_daily keep_weekly keep_monthly keep_yearly keep_last].each do |key|
+        next unless retention[key]
+
+        unless retention[key].is_a?(Integer) && retention[key] >= 0
+          errors << "#{context}/retention/#{key}: must be a non-negative integer, " \
+                    "got #{retention[key].class}: #{retention[key].inspect}"
+        end
+      end
+
+      # Validate time-based retention values (strings)
+      %w[keep_within keep_files_modified_within].each do |key|
+        next unless retention[key]
+
+        unless retention[key].is_a?(String)
+          errors << "#{context}/retention/#{key}: must be a string (e.g., '7d', '30d'), " \
+                    "got #{retention[key].class}: #{retention[key].inspect}"
+        end
+
+        # Validate time format (e.g., "7d", "30d", "2w", "3m", "1y")
+        if retention[key].is_a?(String) && !retention[key].match?(/^\d+[hdwmy]$/)
+          errors << "#{context}/retention/#{key}: invalid time format '#{retention[key]}'. " \
+                    "Must be a number followed by h/d/w/m/y (e.g., '7d', '30d')"
+        end
+      end
+
+      # Warn if retention policy is empty
+      errors << "#{context}/retention: retention policy is empty" if retention.empty?
+
+      errors
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
   end
 end

data/lib/ruborg/passbolt.rb

@@ -5,19 +5,26 @@ require "json"
 module Ruborg
   # Passbolt CLI integration for password management
   class Passbolt
-    def initialize(resource_id: nil)
+    def initialize(resource_id: nil, logger: nil)
       @resource_id = resource_id
+      @logger = logger
       check_passbolt_cli
     end
 
     def get_password
       raise PassboltError, "Resource ID not configured" unless @resource_id
 
+      @logger&.info("Retrieving password from Passbolt (resource_id: #{@resource_id})")
+
       cmd = ["passbolt", "get", "resource", @resource_id, "--json"]
       output, status = execute_command(cmd)
 
-      raise PassboltError, "Failed to retrieve password from Passbolt" unless status
+      unless status
+        @logger&.error("Failed to retrieve password from Passbolt for resource #{@resource_id}")
+        raise PassboltError, "Failed to retrieve password from Passbolt"
+      end
 
+      @logger&.info("Successfully retrieved password from Passbolt")
       parse_password(output)
     end
 

data/lib/ruborg/repository.rb

@@ -6,11 +6,12 @@ module Ruborg
   class Repository
     attr_reader :path, :borg_path
 
-    def initialize(path, passphrase: nil, borg_options: {}, borg_path: nil)
+    def initialize(path, passphrase: nil, borg_options: {}, borg_path: nil, logger: nil)
       @path = validate_repo_path(path)
       @passphrase = passphrase
       @borg_options = borg_options
       @borg_path = validate_borg_path(borg_path || "borg")
+      @logger = logger
     end
 
     def exists?
@@ -20,8 +21,10 @@ module Ruborg
     def create
       raise BorgError, "Repository already exists at #{@path}" if exists?
 
+      @logger&.info("Creating Borg repository at #{@path} with repokey encryption")
       cmd = [@borg_path, "init", "--encryption=repokey", @path]
       execute_borg_command(cmd)
+      @logger&.info("Repository created successfully at #{@path}")
     end
 
     def info
@@ -74,15 +77,19 @@ module Ruborg
 
       unless keep_files_modified_within
         # Fall back to standard pruning if no file metadata retention specified
+        @logger&.info("No file metadata retention specified, using standard pruning")
         prune_standard_archives(retention_policy)
         return
       end
 
+      @logger&.info("Pruning per-file archives based on file modification time (keep within: #{keep_files_modified_within})")
+
       # Parse time duration (e.g., "30d" -> 30 days)
       cutoff_time = Time.now - parse_time_duration(keep_files_modified_within)
 
       # Get all archives with metadata
       archives = list_archives_with_metadata
+      @logger&.info("Found #{archives.size} archive(s) to evaluate for pruning")
 
       archives_to_delete = []
 
@@ -91,16 +98,23 @@ module Ruborg
         file_mtime = get_file_mtime_from_archive(archive[:name])
 
         # Delete archive if file was modified before cutoff
-        archives_to_delete << archive[:name] if file_mtime && file_mtime < cutoff_time
+        if file_mtime && file_mtime < cutoff_time
+          archives_to_delete << archive[:name]
+          @logger&.debug("Archive #{archive[:name]} marked for deletion (file mtime: #{file_mtime})")
+        end
       end
 
+      return if archives_to_delete.empty?
+
+      @logger&.info("Deleting #{archives_to_delete.size} archive(s)")
+
       # Delete archives
       archives_to_delete.each do |archive_name|
+        @logger&.debug("Deleting archive: #{archive_name}")
         delete_archive(archive_name)
       end
 
-      return if archives_to_delete.empty?
-
+      @logger&.info("Pruned #{archives_to_delete.size} archive(s) based on file modification time")
       puts "Pruned #{archives_to_delete.size} archive(s) based on file modification time"
     end
 

data/lib/ruborg/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ruborg
-  VERSION = "0.6.0"
+  VERSION = "0.6.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruborg
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Michail Pantelelis
@@ -133,6 +133,7 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- ".ruby-version"
 - CHANGELOG.md
 - CLAUDE.md
 - LICENSE
@@ -172,7 +173,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.1
 specification_version: 4
 summary: A friendly Ruby frontend for Borg backup
 test_files: []