secure-keys 1.1.6 → 1.2.0

data/lib/core/console/arguments/fetchable.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+module SecureKeys
+  module Core
+    module Console
+      module Argument
+        # Shared fetch/set behaviour for argument handler classes.
+        # Include this module inside +class << self+ so the methods become
+        # class-level accessors that check the handler's own +arguments+ hash
+        # before falling back to environment variables.
+        #
+        # The including class must expose +arguments+ as a class-level reader
+        # (via +attr_reader :arguments+ inside +class << self+).
+        module Fetchable
+          # Fetch an argument value, falling back to SECURE_KEYS_<KEY>,
+          # then the bare <KEY> environment variable, then +default+.
+          #
+          # @param key [Symbol, Array<Symbol>] The argument key (or nested key path)
+          # @param default [Object] The value to return when nothing is found
+          # @return [Object] The resolved value
+          def fetch(key:, default: nil)
+            keys = Array(key).map(&:to_sym)
+            joined_keys = keys.join('_').upcase
+            arguments.dig(*keys) || ENV["SECURE_KEYS_#{joined_keys}"] || ENV[joined_keys] || default
+          end
+
+          # Update a single argument value
+          # @param key [Symbol] The argument key to update
+          # @param value [Object] The new value
+          # @return [void]
+          def set(key:, value:)
+            arguments[key.to_sym] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/core/console/arguments/handler.rb

@@ -1,9 +1,13 @@
+require_relative 'fetchable'
+
 module SecureKeys
   module Core
     module Console
       module Argument
         class Handler
           class << self
+            include Fetchable
+
             attr_reader :arguments
           end
 
@@ -16,31 +20,11 @@ module SecureKeys
             verbose: false,
           }
 
-          # Fetch the argument value by key
-          # from CLI arguments or environment variables
-          #
-          # @param key [Array|Symbol] the argument key
-          # @param default [String] the default value
-          #
-          # @return [String] the argument value
-          def self.fetch(key:, default: nil)
-            keys = Array(key).map(&:to_sym)
-            joined_keys = keys.join('_').upcase
-            @arguments.dig(*keys) || ENV["SECURE_KEYS_#{joined_keys}"] || ENV[joined_keys] || default
-          end
-
-          # Set the value of the key
-          # @param key [Symbol] the key to be updated
-          # @param value [String] the value to be updated
-          def self.set(key:, value:)
-            @arguments[key.to_sym] = value
-          end
-
-          # Append the argument value by key
+          # Append a hash value into a nested key, initialising it when absent
           # @param key [Symbol] the argument key
-          # @param value [String] the argument value
+          # @param value [Hash] the hash to merge in
           def self.deep_merge(key:, value:)
-            @arguments[key.to_sym] ||= {} # Initialize the key if it doesn't exist
+            @arguments[key.to_sym] ||= {}
             @arguments[key.to_sym].merge!(value)
           end
         end

data/lib/core/console/arguments/parser.rb

@@ -2,8 +2,8 @@
 
 require 'optparse'
 require_relative '../../globals/globals'
-require_relative './handler'
-require_relative './xcframework/parser'
+require_relative 'handler'
+require_relative 'xcframework/parser'
 
 module SecureKeys
   module Core
@@ -15,6 +15,11 @@ module SecureKeys
             super('Usage: secure-keys [--options]')
             separator('')
 
+            # Route known subcommands before processing flags.
+            # Like --help and --version, subcommand handlers exit internally,
+            # so the generator is never reached.
+            route_subcommand!
+
             # Configure the argument parser
             configure!
             order!(into: Handler.arguments)
@@ -23,6 +28,27 @@ module SecureKeys
 
           private
 
+          # Known positional subcommands mapped to their handler lambdas.
+          # Each lambda is expected to handle its own output and exit.
+          SUBCOMMANDS = {
+            'validate' => lambda {
+              require_relative '../../../validation/console/arguments/parser'
+              Validation::Console::Argument::Parser.new.execute
+            },
+          }.freeze
+
+          # Detect a known positional subcommand as the first ARGV token and delegate
+          # to its handler. Like --help and --version, the handler exits internally so
+          # the generator is never reached.
+          # @return [void]
+          def route_subcommand!
+            token = ARGV.first
+            return unless SUBCOMMANDS.key?(token)
+
+            ARGV.shift
+            SUBCOMMANDS[token].call
+          end
+
           # Configure the argument parser
           def configure!
             on('-h', '--help', 'Use the provided commands to select the params') do

data/lib/core/console/arguments/xcframework/parser.rb

@@ -2,7 +2,7 @@
 
 require 'optparse'
 require_relative '../../../globals/globals'
-require_relative './handler'
+require_relative 'handler'
 
 module SecureKeys
   module Core

data/lib/core/console/shell.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 require 'open3'
-require_relative './logger'
+require_relative 'logger'
 require_relative '../globals/globals'
 
 module SecureKeys
@@ -49,8 +49,6 @@ module SecureKeys
           return yield(exit_status || $CHILD_STATUS, output, command) if block_given?
 
           [output, exit_status || $CHILD_STATUS, command]
-        rescue StandardError => e
-          raise e
         ensure
           Encoding.default_external = previous_encoding.first
           Encoding.default_internal = previous_encoding.last

data/lib/core/environment/ci.rb

@@ -1,5 +1,7 @@
 #!/usr/bin/env ruby
 
+require_relative '../console/logger'
+
 module SecureKeys
   module Core
     module Environment
@@ -8,9 +10,20 @@ module SecureKeys
         # @param key [String] the key of the environment variable to fetch
         # @return [String] the value of the environment variable
         def fetch(key:)
-          ENV[key]
+          normalized_key = key.to_s.tr('-', '_').upcase
+
+          ENV[key.to_s] ||
+            ENV[normalized_key] ||
+            ENV["SECURE_KEYS_#{normalized_key}"] ||
+            inline_identifier_value(key)
         rescue StandardError
-          puts "❌ Error fetching the key: #{key} from ENV variables"
+          Core::Console::Logger.error(message: "Error fetching the key '#{key}' from ENV variables")
+        end
+
+        private
+
+        def inline_identifier_value(key)
+          key if key.to_s.include?(SecureKeys::Globals.key_delimiter)
         end
       end
     end

data/lib/core/generator.rb

@@ -1,13 +1,13 @@
 #!/usr/bin/env ruby
 
-require_relative './globals/globals'
-require_relative './environment/ci'
-require_relative './environment/keychain'
-require_relative './utils/swift/writer'
-require_relative './utils/swift/package'
-require_relative './utils/swift/swift'
-require_relative './utils/swift/xcframework'
-require_relative './utils/openssl/cipher'
+require_relative 'globals/globals'
+require_relative 'environment/ci'
+require_relative 'environment/keychain'
+require_relative 'utils/swift/writer'
+require_relative 'utils/swift/package'
+require_relative 'utils/swift/swift'
+require_relative 'utils/swift/xcframework'
+require_relative 'utils/openssl/cipher'
 
 module SecureKeys
   module Core
@@ -45,10 +45,10 @@ module SecureKeys
           generate_swift_package
           write_keys
           xcframework.generate
+          post_actions
         end
 
         xcframework.configure_xcframework_to_xcodeproj
-        post_actions if Globals.generate_xcframework?
       end
 
       private

data/lib/core/utils/extensions/kernel.rb

@@ -1,5 +1,5 @@
-require_relative './string/to_bool'
-require_relative './string/camelize'
+require_relative 'string/to_bool'
+require_relative 'string/camelize'
 
 module Kernel
   include BooleanCasting

data/lib/core/utils/swift/package.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-require_relative './swift'
+require_relative 'swift'
 require_relative '../../console/shell'
 
 module SecureKeys

data/lib/core/utils/swift/writer.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # rubocop:disable Layout/HeredocIndentation
 
-require_relative './swift'
+require_relative 'swift'
 
 module SecureKeys
   module Swift
@@ -25,9 +25,7 @@ module SecureKeys
       # Write the keys to the file
       def write
         # Write the file
-        File.open("#{key_directory}/#{key_file}", 'w') do |file|
-          file.write(key_swift_file_template(content: formatted_keys))
-        end
+        File.write("#{key_directory}/#{key_file}", key_swift_file_template(content: formatted_keys))
       end
 
       # Generate the formatted keys content using Swift code format

data/lib/core/utils/swift/xcframework.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-require_relative './swift'
+require_relative 'swift'
 require_relative '../../globals/globals'
 require_relative '../../console/shell'
 require_relative '../../console/logger'

data/lib/keys.rb

@@ -1,11 +1,11 @@
 #!/usr/bin/env ruby
 
-require_relative './core/utils/extensions/kernel'
-require_relative './core/generator'
-require_relative './core/globals/globals'
-require_relative './core/console/logger'
-require_relative './core/console/arguments/parser'
-require_relative './core/utils/swift/xcframework'
+require_relative 'core/utils/extensions/kernel'
+require_relative 'core/generator'
+require_relative 'core/globals/globals'
+require_relative 'core/console/logger'
+require_relative 'core/console/arguments/parser'
+require_relative 'core/utils/swift/xcframework'
 
 module SecureKeys
   def self.run

data/lib/services/environment.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+module SecureKeys
+  module Services
+    module Environment
+      module_function
+
+      # Fetches the value of an environment variable with support for SecureKeys prefix
+      # @param key [Symbol] The environment variable key to fetch
+      # @param default [Object] The default value to return if the environment variable is not set
+      # @return [Object, nil] The value of the environment variable or the default value
+      def fetch(key:, default: nil)
+        formatted_key = key.to_s.upcase
+        ENV[formatted_key] || ENV["SECURE_KEYS_#{formatted_key}"] || default
+      end
+
+      # Fetches the integer value of an environment variable with support for SecureKeys prefix
+      # @param key [Symbol] The environment variable key to fetch
+      # @param default [Object] The default value to return if the environment variable is not set or cannot be converted to an integer
+      # @return [Integer, nil] The integer value of the environment variable or the default value
+      def integer(key:, default: nil)
+        value = fetch(key:, default:)
+        Integer(value)
+      rescue ArgumentError, TypeError
+        # Returns default if it's nil or integer, otherwise, force return nil
+        default.is_a?(Integer) || default.nil? ? default : nil
+      end
+
+      def decimal(key:, default: nil)
+        value = fetch(key:, default:)
+        Float(value)
+      rescue ArgumentError, TypeError
+        # Returns default if it's nil or float, otherwise, force return nil
+        default.is_a?(Float) || default.nil? ? default : nil
+      end
+    end
+  end
+end

data/lib/validation/actions/scan.rb

@@ -0,0 +1,126 @@
+#!/usr/bin/env ruby
+
+require 'json'
+require_relative '../console/arguments/scan/handler'
+require_relative '../../core/console/logger'
+require_relative '../scanner'
+
+module SecureKeys
+  module Validation
+    module Actions
+      # Executes the `validate scan` action: runs the scanner, prints a formatted
+      # report to the console, optionally saves a JSON report, and exits with an
+      # appropriate code (0 = clean, 1 = findings present).
+      class Scan
+        # Run the scan, print the report, and exit
+        # @return [void]
+        def run
+          result = execute_scan
+          print_result(result:)
+          save_report(result:) if Console::Argument::Scan::Handler.fetch(key: :output)
+          exit(result.clean? ? 0 : 1)
+        end
+
+        private
+
+        # Build optional scanner overrides from CLI arguments via Handler.fetch
+        # @return [Hash] A sparse options hash (only keys explicitly provided by the user)
+        def scanner_options
+          options = {}
+
+          if (extensions = Console::Argument::Scan::Handler.fetch(key: :extensions))
+            options[:extensions] = extensions.split(',').map(&:strip)
+          end
+
+          if (excludes = Console::Argument::Scan::Handler.fetch(key: :excludes))
+            options[:excludes] = excludes.split(',').map(&:strip)
+          end
+
+          options
+        end
+
+        # Run the appropriate scan based on the --staged flag
+        # @return [ScanResult] The result of the scan
+        def execute_scan
+          scanner = Scanner.new(options: scanner_options)
+
+          if Console::Argument::Scan::Handler.fetch(key: :staged, default: false)
+            Core::Console::Logger.important(message: 'Scanning staged git changes...')
+            scanner.scan_git_diff(staged_only: true)
+          else
+            path = Console::Argument::Scan::Handler.fetch(key: :path, default: '.')
+            Core::Console::Logger.important(message: "Scanning directory: #{path}")
+            scanner.scan_directory(path:)
+          end
+        end
+
+        # Print a formatted scan report to the console
+        # @param result [ScanResult] The scan result to display
+        # @return [void]
+        def print_result(result:)
+          separator = '-' * 70
+
+          Core::Console::Logger.message(message: separator)
+          Core::Console::Logger.message(message: "\tFiles scanned:  #{result.files_count}")
+          Core::Console::Logger.message(message: "\tFindings:       #{result.findings.length}")
+          Core::Console::Logger.message(message: separator)
+
+          if result.clean?
+            Core::Console::Logger.success(message: "\t✅ No secrets found")
+          else
+            print_severity_summary(result:)
+            Core::Console::Logger.message(message: separator)
+            print_findings(result:)
+          end
+
+          Core::Console::Logger.message(message: separator)
+        end
+
+        # Print a per-severity count breakdown
+        # @param result [ScanResult] The scan result
+        # @return [void]
+        def print_severity_summary(result:)
+          counts = {
+            critical: result.by_severity(severity: :critical).length,
+            high: result.by_severity(severity: :high).length,
+            medium: result.by_severity(severity: :medium).length,
+            low: result.by_severity(severity: :low).length,
+          }
+
+          Core::Console::Logger.error(message: "\t🔴 Critical:  #{counts[:critical]}") if counts[:critical].positive?
+          Core::Console::Logger.warning(message: "\t🟠 High:      #{counts[:high]}")     if counts[:high].positive?
+          Core::Console::Logger.warning(message: "\t🟡 Medium:    #{counts[:medium]}")   if counts[:medium].positive?
+          Core::Console::Logger.message(message: "\t🔵 Low:       #{counts[:low]}")      if counts[:low].positive?
+        end
+
+        # Print each finding grouped by severity level
+        # @param result [ScanResult] The scan result
+        # @return [void]
+        def print_findings(result:)
+          %i[critical high medium low].each do |severity|
+            findings = result.by_severity(severity:)
+            next if findings.empty?
+
+            Core::Console::Logger.message(message: "\t#{severity.to_s.upcase} (#{findings.length}):")
+
+            findings.each do |finding|
+              Core::Console::Logger.message(message: "\t\t#{finding}")
+              Core::Console::Logger.message(message: "\t\t└ #{finding.full_line}")
+            end
+
+            Core::Console::Logger.message(message: '')
+          end
+        end
+
+        # Save the scan result as a pretty-printed JSON report
+        # @param result [ScanResult] The scan result to serialise
+        # @return [void]
+        def save_report(result:)
+          output = Console::Argument::Scan::Handler.fetch(key: :output)
+          File.write(output, JSON.pretty_generate(result.to_h))
+          Core::Console::Logger.success(message: "Report saved to: #{output}")
+        end
+      end
+    end
+  end
+end

data/lib/validation/console/arguments/parser.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require_relative '../../../core/console/logger'
+require_relative 'scan/handler'
+require_relative 'scan/parser'
+require_relative '../../actions/scan'
+
+module SecureKeys
+  module Validation
+    module Console
+      module Argument
+        # Routes the `validate` subcommand to the appropriate sub-parser and action.
+        # The constructor reads the subcommand token from ARGV; +execute+ then
+        # delegates to the matching sub-parser and runs the action.
+        class Parser < OptionParser
+          # Initialize the validate argument parser and capture the subcommand token
+          def initialize
+            super('Usage: secure-keys validate [subcommand] [--options]')
+            separator('')
+            configure!
+            @subcommand = ARGV.shift
+          end
+
+          # Dispatch to the correct sub-parser and action based on the subcommand
+          # @return [void]
+          def execute
+            case @subcommand
+            when 'scan'
+              Scan::Parser.new
+              Actions::Scan.new.run
+            when nil, '--help', '-h'
+              puts self
+              exit(0)
+            else
+              Core::Console::Logger.error(message: "Unknown validate subcommand: '#{@subcommand}'")
+              puts self
+              exit(1)
+            end
+          end
+
+          private
+
+          # Configure the validate-level help text and available subcommands
+          # @return [void]
+          def configure!
+            on('-h', '--help', 'Show help for the validate command') do
+              puts self
+              exit(0)
+            end
+            separator('')
+            separator('Subcommands:')
+            separator("\tscan [path]   Scan a directory or staged git changes for exposed secrets")
+            separator('')
+            separator('Examples:')
+            separator("\tsecure-keys validate scan")
+            separator("\tsecure-keys validate scan ./src")
+            separator("\tsecure-keys validate scan --staged")
+            separator("\tsecure-keys validate scan --output report.json")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/validation/console/arguments/scan/handler.rb

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+
+require_relative '../../../../core/console/arguments/fetchable'
+
+module SecureKeys
+  module Validation
+    module Console
+      module Argument
+        module Scan
+          # Stores and provides access to the resolved CLI arguments for the scan subcommand
+          class Handler
+            class << self
+              include Core::Console::Argument::Fetchable
+
+              attr_reader :arguments
+            end
+
+            # Default argument values for the scan subcommand
+            @arguments = {
+              path: '.',
+              staged: false,
+              output: nil,
+              extensions: nil,
+              excludes: nil,
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/validation/console/arguments/scan/parser.rb

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require_relative 'handler'
+require_relative '../../../../core/console/arguments/handler'
+
+module SecureKeys
+  module Validation
+    module Console
+      module Argument
+        module Scan
+          # Parses CLI options for the `secure-keys validate scan` subcommand.
+          # Uses +parse!+ so options and positional arguments may appear in any order;
+          # after parsing, any remaining ARGV token is treated as the scan path.
+          class Parser < OptionParser
+            # Initialize the scan parser, process ARGV, and store results in Handler
+            def initialize
+              super('Usage: secure-keys validate scan [path] [--options]')
+              separator('')
+              configure!
+              parse!(into: Handler.arguments)
+              Handler.set(key: :path, value: ARGV.shift) unless ARGV.empty?
+            end
+
+            private
+
+            # Define all accepted options for the scan subcommand
+            # @return [void]
+            def configure!
+              on('-h', '--help', 'Show help for the scan subcommand') do
+                puts self
+                exit(0)
+              end
+              on('--staged', 'Scan staged git changes instead of a directory (default: false)') do
+                Handler.set(key: :staged, value: true)
+              end
+              on(
+                '-o', '--output FILE',
+                String,
+                'Save the scan report as JSON to FILE'
+              )
+              on(
+                '--extensions EXTENSIONS',
+                String,
+                'Comma-separated file extensions to scan (e.g. .rb,.swift)'
+              )
+              on(
+                '--excludes EXCLUDES',
+                String,
+                'Comma-separated directory names to exclude from the scan'
+              )
+              on('--verbose', 'Enable verbose output (default: false)') do
+                Core::Console::Argument::Handler.set(key: :verbose, value: true)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end