invar 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58a64d36feebf42e3d2e44e3cee20197683055dbb276f38701344db45a050e27
-  data.tar.gz: f39265a13a4ae8a49cb2b7944599c75bab6723422d3b92f5838b777d7fa8dfab
+  metadata.gz: 6e3d07cd5d6d704c0bec06fe0803e0a5fd553f69e54f74501ddd7e9639353172
+  data.tar.gz: 3ecb948cb3b856d9f15d0d1d985f5e59db62532a724e8c4c748287532d1efac2
 SHA512:
-  metadata.gz: c8d134ac530b0e9a2046922cc1055621d4120e92840eedee5fd5d527b1cd5a6880577a78cc4cbfa065dc751d48d9883a0edd36e661dcd83151b6967f1501cf6d
-  data.tar.gz: e27ee5476e9efcf5871f78e50dd428398306a2dc48092b56c55a04be3e98c30fd2fad2d899ed7d35fff70ef297d2ede51941dd22197eb56222155f8b5d93be48
+  metadata.gz: 66ebee132d5bc1ba58e5876594435514d19b177fda6820d1ebe05ad6908b590f48b4466c30af950127cf3178a43eeb74573535fcfd32aa9f2165e378b657f4be
+  data.tar.gz: 3972595f9f126f76707b1bf6c2d76ef6803d5056808cf06977106256524be109ed9b0975a99931cb9acf694d9e1fb934916f5de0939e6dc65fc920e61c412195

data/README.md

@@ -181,7 +181,9 @@ puts invar / :config / :database
 In your `Rakefile`, add:
 
 ```ruby
-require 'invar/rake'
+require 'invar/rake/tasks'
+
+Invar::Rake::Tasks.define namespace: 'app-name-here'
 ```
 
 Then you can use the rake tasks as reported by `rake -T`
@@ -272,6 +274,54 @@ puts invar[:config][:database][:host]
 >
 > **A**: Because key names could collide with method names, like `inspect`, `dup`, or `tap`.
 
+### Validation
+
+You may provide `:configs_schema` and `:secrets_schema` keyword arguments to `Invar.new` and it will use those schema to
+validate your `Invar::Reality`.
+
+> **Note** Invar uses dry-schema to validate its internal `configs` and `secrets` trees, not the raw file contents.
+
+`dry-schema` has a lot of shorthand which can add a lot of complexity, but here's a crash course:
+
+* Keys are declared with the `required` method while the value's validator is declared to be a general `schema` type
+  with an accompanying block.
+* In that block are the units of validation logic (*"predicates"*)
+    * They get unioned together with a **single** `&`
+      operator, **not** double `&&` like a boolean expression.
+    * There are predefined predicates for a bunch of simple properties
+
+Generally when used with Invar it will look like:
+
+```ruby
+require 'invar'
+
+cnf_schema = Dry::Schema.define do
+   required(:upload).schema do
+      required(:mysql) { str? & filled? }
+   end
+
+   required(:upload).schema do
+      required(:max_bytes) { int? & filled? & gt?(0) }
+      required(:timeout) { int? & filled? & gt?(0) }
+   end
+   # ...
+end
+
+sec_schema = Dry::Schema.define do
+   required(:email).schema do
+      required(:username) { str? & filled? }
+      required(:password) { str? & filled? }
+   end
+   # ...
+end
+
+invar = Invar.new 'my-app', configs_schema: cnf_schema, secrets_schema: sec_schema
+# ...
+```
+
+If there are any unexpected or invalid keys in the *configs* or *secrets* files, Invar will complain about it with
+a `SchemaValidationError`.
+
 ### Custom Locations
 
 You can customize the search paths by setting the environment variables `XDG_CONFIG_HOME` and/or `XDG_CONFIG_DIRS` any
@@ -280,6 +330,16 @@ time you run a Rake task or your application.
     # Looks in /tmp instead of ~/.config/ 
     XDG_CONFIG_HOME=/tmp bundle exec rake invar:paths
 
+You can also specify the Lockbox decryption keyfile (eg. for automated production environments) by using the
+`:decryption_keyfile` keyword argument to `Invar.new`. Be aware that your secrets are only as secure as the file that
+keeps the master key, so double check that its file permissions are as restricted as possible.
+
+```ruby
+require 'invar'
+
+invar = Invar.new 'my-app', decryption_keyfile: '/etc/my-app/master_key'
+```
+
 ## Alternatives
 
 Some other gems with different approaches:

data/RELEASE_NOTES.md

@@ -1,14 +1,20 @@
 # Release Notes
 
+All notable changes to this project will be documented below.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project loosely follows
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [Unreleased]
 
 ### Major Changes
 
-* none
+* Renamed `Invar::Invar` to `Invar::Reality`
+* Maintenance Rake task inclusion now requires explicit define call
 
 ### Minor Changes
 
-* none
+* Expanded docs
 
 ### Bugfixes
 

data/lib/invar/rake/tasks.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require 'invar'
+
+require 'rake'
+require 'io/console'
+require 'tempfile'
+
+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 Rake
+      # RakeTask builder class. Use Tasks.define to generate the needed tasks.
+      class Tasks
+         include ::Rake::Cloneable
+         include ::Rake::DSL
+
+         # Template config YAML file
+         CONFIG_TEMPLATE = SECRETS_TEMPLATE = <<~YML
+            ---
+         YML
+
+         # Shorthand for Invar::Rake::Tasks.new.define
+         #
+         # @param (see #define)
+         # @see Tasks#define
+         def self.define(**args, &block)
+            new.define(**args, &block)
+         end
+
+         # Defines helpful Rake tasks for the given namespace.
+         #
+         # @param namespace [String] The namespace to search for files within
+         def define(namespace: nil)
+            raise ArgumentError, ':namespace keyword argument cannot be nil' if namespace.nil?
+            raise ArgumentError, ':namespace keyword argument cannot be empty string' if namespace.empty?
+
+            define_all_tasks(namespace)
+         end
+
+         private
+
+         def define_all_tasks(app_namespace)
+            namespace :invar do
+               define_config_tasks(app_namespace)
+               define_secrets_tasks(app_namespace)
+
+               define_info_tasks(app_namespace)
+            end
+         end
+
+         def define_config_tasks(app_namespace)
+            namespace :configs do
+               desc 'Create a new configuration file'
+               task :create do
+                  ::Invar::Rake::Tasks::ConfigTask.new(app_namespace).create
+               end
+
+               desc 'Edit the config in your default editor'
+               task :edit do
+                  ::Invar::Rake::Tasks::ConfigTask.new(app_namespace).edit
+               end
+            end
+
+            # alias
+            namespace :config do
+               task create: ['configs:create']
+               task edit: ['configs:edit']
+            end
+         end
+
+         def define_secrets_tasks(app_namespace)
+            namespace :secrets do
+               desc 'Create a new encrypted secrets file'
+               task :create do
+                  ::Invar::Rake::Tasks::SecretTask.new(app_namespace).create
+               end
+
+               desc 'Edit the encrypted secrets file in your default editor'
+               task :edit do
+                  ::Invar::Rake::Tasks::SecretTask.new(app_namespace).edit
+               end
+            end
+
+            # alias
+            namespace :secret do
+               task create: ['secrets:create']
+               task edit: ['secrets:edit']
+            end
+         end
+
+         def define_info_tasks(app_namespace)
+            desc 'Show directories to be searched for the given namespace'
+            task :paths do
+               ::Invar::Rake::Tasks::StateTask.new(app_namespace).show_paths
+            end
+         end
+
+         # Tasks that use a namespace for file searching
+         class NamespacedTask
+            def initialize(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?
+                  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 = @locator.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?
+                  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
+      end
+   end
+end
+

data/lib/invar/reality.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'lockbox'
+require 'pathname'
+require 'dry/schema'
+
+require 'invar/file_locator'
+require 'invar/scope'
+
+# :nodoc:
+module Invar
+   # Stores application config, secrets, and environmental variables. Environment variables come from ENV at the time of
+   # instantiation, while configs and secrets are loaded from respective files in the appropriate location. The secrets
+   # file is kept encrypted at rest.
+   #
+   # Fetch information from a Reality by using the slash operator or square brackets:
+   #
+   #    invar = Invar::Reality.new(namespace: 'test-app')
+   #
+   #    puts invar / :config / :database / :host
+   #    puts invar[:config][:database][:host] # same as above
+   #
+   #    puts invar / :secrets / :database / :user
+   #
+   # Note: `Invar.new` is a shorthand for Invar::Reality.new
+   #
+   # Information known by a Reality is immutable. You may use the `#pretend` method to simulate different values during
+   # testing.
+   #
+   #     # In your tests, define an after_load hook
+   #    require 'invar/test'
+   #    Invar.after_load do |reality|
+   #       reality[:config][:database][:host].pretend 'example.com'
+   #    end
+   #
+   #    # then later, in your app, it will use the pretend value
+   #    invar = Invar.new namespace: 'my-app'
+   #    puts invar / :config / :database / :host # prints example.com
+   #
+   # @see Invar.new
+   # @see Reality#after_load
+   # @see Reality#pretend
+   class Reality
+      # 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)
+
+         RealityValidator.new(configs_schema, secrets_schema).validate(@configs, @secrets)
+      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)
+         env_hash = ENV.to_hash.transform_keys(&:downcase).transform_keys(&:to_sym)
+
+         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 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
+
+      # Validates a Reality object
+      class RealityValidator
+         def initialize(configs_schema, secrets_schema)
+            configs_schema ||= Dry::Schema.define
+            env_schema     = build_env_schema
+
+            @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
+         end
+
+         def validate(configs, secrets)
+            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
+
+         private
+
+         # Special schema for just the env variables, listing them explicitly allows for using validate_keys
+         def build_env_schema
+            env_keys = ENV.to_hash.transform_keys(&:downcase).transform_keys(&:to_sym).keys
+            Dry::Schema.define do
+               env_keys.each do |key|
+                  optional(key)
+               end
+            end
+         end
+      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

data/lib/invar/scope.rb

@@ -30,6 +30,9 @@ module Invar
          raise ::Invar::ImmutableRealityError, ::Invar::ImmutableRealityError::MSG
       end
 
+      # Returns a hash representation of this scope and subscopes.
+      #
+      # @return [Hash] a hash representation of this scope
       def to_h
          @data.merge(@data_override).to_h.transform_values do |value|
             case value

data/lib/invar/version.rb

@@ -2,5 +2,5 @@
 
 module Invar
    # Current version of the gem
-   VERSION = '0.4.0'
+   VERSION = '0.5.0'
 end

data/lib/invar.rb

@@ -1,216 +1,16 @@
 # frozen_string_literal: true
 
 require 'invar/version'
-require 'invar/file_locator'
-require 'invar/scope'
+require 'invar/reality'
 
-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.
+# Invar is a Ruby Gem that provides a single source of truth for application configuration, secrets, and environment
+# variables.
 module Invar
-   # Alias for Invar::Invar.new
+   # Alias for Invar::Reality.new
    #
-   # @see Invar.new
+   # @see Invar::Reality.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
+      ::Invar::Reality.new(**args)
    end
 
    class << self
@@ -220,54 +20,7 @@ module Invar
       # @yieldparam the configs from the Invar
       # @return [void]
       def after_load(&block)
-         ::Invar::Invar.__override_block__ = block
+         ::Invar::Reality.__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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: invar
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Robin Miller
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-12-08 00:00:00.000000000 Z
+date: 2022-12-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-schema
@@ -144,8 +144,8 @@ files:
 - invar.gemspec
 - lib/invar.rb
 - lib/invar/file_locator.rb
-- lib/invar/rake.rb
-- lib/invar/rake_tasks.rb
+- lib/invar/rake/tasks.rb
+- lib/invar/reality.rb
 - lib/invar/scope.rb
 - lib/invar/test.rb
 - lib/invar/version.rb

data/lib/invar/rake.rb

@@ -1,47 +0,0 @@
-# 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

@@ -1,178 +0,0 @@
-# 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