invar 0.4.0

data/lib/invar/rake.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'rake'
+require 'io/console'
+require 'tempfile'
+require_relative 'rake_tasks'
+
+namespace :invar do
+   namespace :configs do
+      desc 'Create a new configuration file'
+      task :create, [:namespace] do |task, args|
+         Invar::RakeTasks::ConfigTask.new(args[:namespace], task).create
+      end
+
+      desc 'Edit the config in your default editor'
+      task :edit, [:namespace] do |task, args|
+         Invar::RakeTasks::ConfigTask.new(args[:namespace], task).edit
+      end
+   end
+
+   namespace :secrets do
+      desc 'Create a new encrypted secrets file'
+      task :create, [:namespace] do |task, args|
+         Invar::RakeTasks::SecretTask.new(args[:namespace], task).create
+      end
+
+      desc 'Edit the encrypted secrets file in your default editor'
+      task :edit, [:namespace] do |task, args|
+         Invar::RakeTasks::SecretTask.new(args[:namespace], task).edit
+      end
+   end
+
+   # aliasing
+   namespace :config do
+      task :create, [:namespace] => ['configs:create']
+      task :edit, [:namespace] => ['configs:edit']
+   end
+   namespace :secret do
+      task :create, [:namespace] => ['secrets:create']
+      task :edit, [:namespace] => ['secrets:edit']
+   end
+
+   desc 'Show directories to be searched for the given namespace'
+   task :paths, [:namespace] do |task, args|
+      Invar::RakeTasks::StateTask.new(args[:namespace], task).show_paths
+   end
+end

data/lib/invar/rake_tasks.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'invar'
+
+module Invar
+   # Rake task implementation.
+   #
+   # The actual rake tasks themselves are thinly defined in invar/rake.rb (so that the external include
+   # path is nice and short)
+   module RakeTasks
+      # Template config YAML file
+      CONFIG_TEMPLATE = SECRETS_TEMPLATE = <<~YML
+         ---
+      YML
+
+      # Tasks that use a namespace
+      class NamespacedTask
+         def initialize(namespace, task)
+            if namespace.nil?
+               raise NamespaceMissingError,
+                     "Namespace argument required. Run with: bundle exec rake #{ task.name }[namespace_here]"
+            end
+
+            @namespace = namespace
+            @locator   = FileLocator.new(@namespace)
+         end
+      end
+
+      # Configuration file actions.
+      class ConfigTask < NamespacedTask
+         # Creates a config file in the appropriate location
+         def create
+            config_dir = @locator.search_paths.first
+            config_dir.mkpath
+
+            file = config_dir / 'config.yml'
+            if file.exist?
+               warn <<~MSG
+                  Abort: File exists. (#{ file })
+                  Maybe you meant to edit the file with bundle exec rake invar:secrets:edit[#{ @namespace }]?
+               MSG
+               exit 1
+            end
+
+            file.write CONFIG_TEMPLATE
+
+            warn "Created file: #{ file }"
+         end
+
+         # Edits the existing config file in the appropriate location
+         def edit
+            configs_file = begin
+                              @locator.find('config.yml')
+                           rescue ::Invar::FileLocator::FileNotFoundError => e
+                              warn <<~ERR
+                                 Abort: #{ e.message }. Searched in: #{ @locator.search_paths.join(', ') }
+                                 Maybe you used the wrong namespace or need to create the file with bundle exec rake invar:configs:create?
+                              ERR
+                              exit 1
+                           end
+
+            system(ENV.fetch('EDITOR', 'editor'), configs_file.to_s, exception: true)
+
+            warn "File saved to: #{ configs_file }"
+         end
+      end
+
+      # Secrets file actions.
+      class SecretTask < NamespacedTask
+         # Instructions hint for how to handle secret keys.
+         SECRETS_INSTRUCTIONS = <<~INST
+            Save this key to a secure password manager. You will need it to edit the secrets.yml file.
+         INST
+
+         # Creates a new encrypted secrets file and prints the generated encryption key to STDOUT
+         def create
+            config_dir = ::Invar::FileLocator.new(@namespace).search_paths.first
+            config_dir.mkpath
+
+            file = config_dir / 'secrets.yml'
+
+            if file.exist?
+               warn <<~ERR
+                  Abort: File exists. (#{ file })
+                  Maybe you meant to edit the file with bundle exec rake invar:secrets:edit[#{ @namespace }]?
+               ERR
+               exit 1
+            end
+
+            encryption_key = Lockbox.generate_key
+
+            write_encrypted_file(file, encryption_key, SECRETS_TEMPLATE)
+
+            warn "Created file #{ file }"
+
+            warn SECRETS_INSTRUCTIONS
+            warn 'Generated key is:'
+            puts encryption_key
+         end
+
+         # Opens an editor for the decrypted contents of the secrets file. After closing the editor, the file will be
+         # updated with the new encrypted contents.
+         def edit
+            secrets_file = begin
+                              @locator.find('secrets.yml')
+                           rescue ::Invar::FileLocator::FileNotFoundError => e
+                              warn <<~ERR
+                                 Abort: #{ e.message }. Searched in: #{ @locator.search_paths.join(', ') }
+                                 Maybe you used the wrong namespace or need to create the file with bundle exec rake invar:secrets:create?
+                              ERR
+                              exit 1
+                           end
+
+            edit_encrypted_file(secrets_file)
+
+            warn "File saved to #{ secrets_file }"
+         end
+
+         private
+
+         def write_encrypted_file(file_path, encryption_key, content)
+            lockbox = Lockbox.new(key: encryption_key)
+
+            encrypted_data = lockbox.encrypt(content)
+
+            # TODO: replace File.opens with photo_path.binwrite(uri.data) once FakeFS can handle it
+            File.open(file_path.to_s, 'wb') { |f| f.write encrypted_data }
+         end
+
+         def edit_encrypted_file(file_path)
+            encryption_key = determine_key(file_path)
+
+            lockbox = build_lockbox(encryption_key)
+
+            file_str = Tempfile.create(file_path.basename.to_s) do |tmp_file|
+               decrypted = lockbox.decrypt(file_path.binread)
+
+               tmp_file.write(decrypted)
+               tmp_file.rewind # rewind needed because file does not get closed after write
+               system(ENV.fetch('EDITOR', 'editor'), tmp_file.path, exception: true)
+               tmp_file.read
+            end
+
+            write_encrypted_file(file_path, encryption_key, file_str)
+         end
+
+         def determine_key(file_path)
+            encryption_key = Lockbox.master_key
+
+            if encryption_key.nil? && $stdin.respond_to?(:noecho)
+               warn "Enter master key to decrypt #{ file_path }:"
+               encryption_key = $stdin.noecho(&:gets).strip
+            end
+
+            encryption_key
+         end
+
+         def build_lockbox(encryption_key)
+            Lockbox.new(key: encryption_key)
+         rescue ArgumentError => e
+            raise SecretsFileEncryptionError, e
+         end
+      end
+
+      # General status tasks
+      class StateTask < NamespacedTask
+         # Prints the current paths to be searched in
+         def show_paths
+            warn @locator.search_paths.join("\n")
+         end
+      end
+
+      # Raised when the namespace Rake task parameter is missing. Add it in square brackets after the task name when
+      # running Rake.
+      class NamespaceMissingError < RuntimeError
+      end
+   end
+end

data/lib/invar/scope.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Invar
+   # A set of configurations
+   class Scope
+      def initialize(data = nil)
+         @data = convert(data)
+
+         @data.freeze
+         @data_override = {}
+         freeze
+      end
+
+      # Retrieve the value for the given key
+      #
+      # @param [symbol] key
+      # @raise KeyError if no such key exists.
+      # @see #override
+      def fetch(key)
+         key = key.downcase.to_sym
+         @data_override.fetch(key, @data.fetch(key))
+      rescue KeyError => e
+         raise KeyError, "#{ e.message }. Known keys are #{ @data.keys.sort.collect { |k| ":#{ k }" }.join(', ') }"
+      end
+
+      alias / fetch
+      alias [] fetch
+
+      def pretend(**)
+         raise ::Invar::ImmutableRealityError, ::Invar::ImmutableRealityError::MSG
+      end
+
+      def to_h
+         @data.merge(@data_override).to_h.transform_values do |value|
+            case value
+            when Scope
+               value.to_h
+            else
+               value
+            end
+         end
+      end
+
+      def key?(key_name)
+         to_h.key?(key_name)
+      end
+
+      private
+
+      def convert(data)
+         (data || {}).dup.each_with_object({}) do |pair, agg|
+            key, value = pair
+
+            agg[key] = value.is_a?(Hash) ? Scope.new(value) : value
+         end
+      end
+   end
+end

data/lib/invar/test.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'invar'
+
+module Invar
+   # Extension to the standard class
+   class Scope
+      # Overrides the given set of key-value pairs. This is intended to only be used in testing environments,
+      # where you may need contextual adjustments to suit the test situation.
+      #
+      # @param [Hash] pairs the hash of pairs to override.
+      def pretend(pairs)
+         @data_override.merge!(pairs.transform_keys(&:to_sym))
+      end
+   end
+end

data/lib/invar/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Invar
+   # Current version of the gem
+   VERSION = '0.4.0'
+end

data/lib/invar.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require 'invar/version'
+require 'invar/file_locator'
+require 'invar/scope'
+
+require 'yaml'
+require 'lockbox'
+require 'pathname'
+require 'dry/schema'
+
+# Invar is a Ruby Gem that provides a single source of truth for application configuration and environment.
+module Invar
+   # Alias for Invar::Invar.new
+   #
+   # @see Invar.new
+   def self.new(**args)
+      Invar.new(**args)
+   end
+
+   # A wrapper for config and ENV variable data. It endeavours to limit your situation to a single source of truth.
+   class Invar
+      # Allowed permissions modes for lockfile. Readable or read-writable by the current user only
+      ALLOWED_LOCKFILE_MODES = [0o600, 0o400].freeze
+
+      # Name of the default key file to be searched for within config directories
+      DEFAULT_KEY_FILE_NAME = 'master_key'
+
+      # Constructs a new Invar.
+      #
+      # It will search for config, secrets, and decryption key files using the XDG specification.
+      #
+      # The secrets file is decrypted using Lockbox. The key will be requested from these locations in order:
+      #
+      #    1. the Lockbox.master_key variable
+      #    2. the LOCKBOX_MASTER_KEY environment variable.
+      #    3. saved in a secure key file (recommended)
+      #    4. manual terminal prompt entry (recommended)
+      #
+      # The :decryption_keyfile argument specifies the filename to read for option 3. It will be searched for in
+      # the same XDG locations as the secrets file. The decryption keyfile will be checked for safe permission modes.
+      #
+      # NEVER hardcode your encryption key. This class intentionally does not accept a raw string of your decryption
+      # key to discourage hardcoding your encryption key and committing it to version control.
+      #
+      # @param [String] namespace name of the subdirectory within XDG locations
+      # @param [#read] decryption_keyfile Any #read capable object referring to the decryption key file
+      def initialize(namespace:, decryption_keyfile: nil, configs_schema: nil, secrets_schema: nil)
+         locator      = FileLocator.new(namespace)
+         search_paths = locator.search_paths.join(', ')
+
+         begin
+            @configs = Scope.new(load_configs(locator))
+         rescue FileLocator::FileNotFoundError
+            raise MissingConfigFileError,
+                  "No config file found. Create config.yml in one of these locations: #{ search_paths }"
+         end
+
+         begin
+            @secrets = Scope.new(load_secrets(locator, decryption_keyfile))
+         rescue FileLocator::FileNotFoundError
+            raise MissingSecretsFileError,
+                  "No secrets file found. Create encrypted secrets.yml in one of these locations: #{ search_paths }"
+         end
+
+         freeze
+         # instance_eval(&self.class.__override_block__)
+         self.class.__override_block__&.call(self)
+
+         validate_with configs_schema, secrets_schema
+      end
+
+      class << self
+         attr_accessor :__override_block__
+      end
+
+      # Fetch from one of the two base scopes: :config or :secret.
+      # Plural names are also accepted (ie. :configs and :secrets).
+      #
+      # @param base_scope [Symbol, String]
+      def fetch(base_scope)
+         case base_scope
+         when /configs?/i
+            @configs
+         when /secrets?/i
+            @secrets
+         else
+            raise ArgumentError, 'The root scope name must be either :config or :secret.'
+         end
+      end
+
+      alias / fetch
+      alias [] fetch
+
+      private
+
+      def load_configs(locator)
+         file = locator.find('config', EXT::YAML)
+
+         configs = parse(file.read)
+
+         collision_key = configs.keys.collect(&:downcase).find { |key| env_hash.key? key }
+         if collision_key
+            hint = EnvConfigCollisionError::HINT
+            raise EnvConfigCollisionError,
+                  "Both the environment and your config file have key #{ collision_key }. #{ hint }"
+         end
+
+         configs.merge(env_hash)
+      end
+
+      def env_hash
+         ENV.to_hash.transform_keys(&:downcase).transform_keys(&:to_sym)
+      end
+
+      def load_secrets(locator, decryption_keyfile)
+         file = locator.find('secrets', EXT::YAML)
+
+         lockbox = begin
+                      decryption_key = Lockbox.master_key || resolve_key(decryption_keyfile, locator,
+                                                                         "Enter master key to decrypt #{ file }:")
+
+                      Lockbox.new(key: decryption_key)
+                   rescue Lockbox::Error => e
+                      raise SecretsFileDecryptionError, e
+                   end
+
+         bytes     = file.binread
+         file_data = begin
+                        lockbox.decrypt bytes
+                     rescue Lockbox::DecryptionError => e
+                        hint = 'Perhaps you used the wrong file decryption key?'
+                        raise SecretsFileDecryptionError, "Failed to open #{ file } (#{ e }). #{ hint }"
+                     end
+
+         parse(file_data)
+      end
+
+      def parse(file_data)
+         YAML.safe_load(file_data, symbolize_names: true) || {}
+      end
+
+      def resolve_key(pathname, locator, prompt)
+         key_file = locator.find(pathname || DEFAULT_KEY_FILE_NAME)
+
+         read_keyfile(key_file)
+      rescue FileLocator::FileNotFoundError
+         if $stdin.respond_to?(:noecho)
+            warn prompt
+            $stdin.noecho(&:gets).strip
+         else
+            raise SecretsFileDecryptionError,
+                  "Could not find file '#{ pathname }'. Searched in: #{ locator.search_paths }"
+         end
+      end
+
+      def read_keyfile(key_file)
+         permissions_mask = 0o777 # only the lowest three digits are perms, so masking
+         stat             = key_file.stat
+         file_mode        = stat.mode & permissions_mask
+         # TODO: use stat.world_readable? etc instead
+         unless ALLOWED_LOCKFILE_MODES.include? file_mode
+            hint = "Try: chmod 600 #{ key_file }"
+            raise SecretsFileDecryptionError,
+                  format("File '%<path>s' has improper permissions (%<mode>04o). %<hint>s",
+                         path: key_file,
+                         mode: file_mode,
+                         hint: hint)
+         end
+
+         key_file.read.strip
+      end
+
+      def validate_with(configs_schema, secrets_schema)
+         env_keys = env_hash.keys
+
+         configs_schema ||= Dry::Schema.define
+
+         # Special schema for just the env variables, listing them explicitly allows for using validate_keys
+         env_schema = Dry::Schema.define do
+            env_keys.each do |key|
+               optional(key)
+            end
+         end
+
+         schema = Dry::Schema.define do
+            config.validate_keys = true
+
+            required(:configs).hash(configs_schema & env_schema)
+
+            if secrets_schema
+               required(:secrets).hash(secrets_schema)
+            else
+               required(:secrets)
+            end
+         end
+
+         validation = schema.call(configs: @configs.to_h,
+                                  secrets: @secrets.to_h)
+
+         return true if validation.success?
+
+         errs = validation.errors.messages.collect do |message|
+            [message.path.collect do |p|
+               ":#{ p }"
+            end.join(' / '), message.text].join(' ')
+         end
+
+         raise SchemaValidationError, <<~ERR
+            Validation errors:
+               #{ errs.join("\n   ") }
+         ERR
+      end
+   end
+
+   class << self
+      # Block that will be run after loading from config files and prior to freezing. It is intended to allow
+      # for test suites to tweak configurations without having to duplicate the entire config file.
+      #
+      # @yieldparam the configs from the Invar
+      # @return [void]
+      def after_load(&block)
+         ::Invar::Invar.__override_block__ = block
+      end
+   end
+
+   # Raised when no config file can be found within the search paths.
+   class MissingConfigFileError < RuntimeError
+   end
+
+   # Raised when no secrets file can be found within the search paths.
+   class MissingSecretsFileError < RuntimeError
+   end
+
+   # Raised when an error is encountered during secrets file encryption
+   class SecretsFileEncryptionError < RuntimeError
+   end
+
+   # Raised when an error is encountered during secrets file decryption
+   class SecretsFileDecryptionError < RuntimeError
+   end
+
+   # Raised when a key is defined in both the environment and the configuration file.
+   class EnvConfigCollisionError < RuntimeError
+      # Message hinting at possible solution
+      HINT = 'Either rename your config entry or remove the environment variable.'
+   end
+
+   # Raised when there are config or secrets files found at multiple locations. You can resolve this by deciding on
+   # one correct location and removing the alternate file(s).
+   class AmbiguousSourceError < RuntimeError
+      # Message hinting at possible solution
+      HINT = 'Choose 1 correct one and delete the others.'
+   end
+
+   # Raised when #pretend is called but the testing extension has not been loaded.
+   #
+   # When raised during normal operation, it may mean the application is calling #pretend directly, which is strongly
+   # discouraged. The feature is meant for testing.
+   #
+   # @see Invar#pretend
+   class ImmutableRealityError < NoMethodError
+      # Message and hint for a possible solution
+      MSG = <<~MSG
+         Method 'pretend' is defined in the testing extension. Try adding this to your test suite config file:
+            require 'invar/test'
+      MSG
+   end
+
+   # Raised when schema validation fails
+   class SchemaValidationError < RuntimeError
+   end
+end