invar 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62fcbaf0763469c256af4915bdae35ded8a2691c647356a24bd6e68635bf3030
-  data.tar.gz: a54dce1295a10292f208318faeefe43b0c279934154f2c6f112e5b22278126a6
+  metadata.gz: c7bb218e77d7ce1acc82bf0160cc7386529f7e32e5a56cd2eea608bd2a191ad6
+  data.tar.gz: 6b209fa6041be75736d28783d996c8fe0ee1e529bdde7d94dcb8e1bbda23423d
 SHA512:
-  metadata.gz: 5c0d9b6ae497f3e1ca0ba6701cdc99c1b8408ceabcdfd1970b67c465576f2cd0439caf92fc6413eb40db21d7289d5f5cab495adeb3499bdeef3c3a4da43a0e2b
-  data.tar.gz: 206b350e643afabd1892db2cf393b375e7555fe85f65d56705c718757ce172d4360fb9f6c4102b70da64223ee42a9d0ef960298240bce9e755b91512f7d1406a
+  metadata.gz: da15b60c94678b1dc9a5e002b3f4bba02d7b2e1a77923483a2a5427839b0cff0fd0e137ce9e1ca847e6b493bb134be97f419a20bef7903adabe8de8b0f163ae9
+  data.tar.gz: 2d60ab3a7f5374478fe2ab872083ef4159620097e0cb65575eb6e6956b669c9fceaa86a39c085c637df125cebfc33f9ba52170a1a2389dce713de9d77da09c9d

data/.rubocop.yml

@@ -4,17 +4,6 @@ AllCops:
   Exclude:
     - 'bin/*'
 
-  TargetRubyVersion: 2.7
-
-Layout/LineLength:
-  Exclude:
-    - 'spec/**/*.rb'
-
-# setting to 6 to match RubyMine autoformat
-Layout/FirstArrayElementIndentation:
-  IndentationWidth: 6
-
-
 # rspec blocks are huge by design
 Metrics/BlockLength:
   Exclude:
@@ -23,4 +12,3 @@ Metrics/BlockLength:
 Metrics/ModuleLength:
   Exclude:
     - 'spec/**/*.rb'
-

data/.ruby-version

@@ -1 +1 @@
-ruby-2.7.8
+ruby-3.1.4

data/.simplecov

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+SimpleCov.start do
+   coverage_dir '.coverage'
+   enable_coverage :branch
+
+   root __dir__
+end

data/Gemfile

@@ -2,14 +2,19 @@
 
 source 'https://rubygems.org'
 
+# Gem's dependencies in invar.gemspec
+gemspec
+
 group :development do
    gem 'bundler', '~> 2.3'
-   gem 'fakefs', '~> 2.5'
    gem 'rake', '~> 13.0'
-   gem 'rspec', '~> 3.12'
-   gem 'simplecov', '~> 0.22'
+   gem 'rubocop', '~> 1.56'
+   gem 'rubocop-performance', '~> 1.19'
    gem 'yard', '~> 0.9'
 end
 
-# Specify your gem's dependencies in invar.gemspec
-gemspec
+group :test do
+   gem 'fakefs', '~> 2.5'
+   gem 'rspec', '~> 3.12'
+   gem 'simplecov', '~> 0.22'
+end

data/README.md

@@ -26,7 +26,8 @@ variables have some downsides:
 * Cannot be easily checked against a schema for early error detection
 * Ruby's core ENV does not accept symbols as keys (a minor nuisance, but it counts)
 
-> **Fun Fact:** Invar is named for an [alloy used in clockmaking](https://en.wikipedia.org/wiki/Invar) - it's short for "**invar**iable".
+> **Fun Fact:** Invar is named for an [alloy used in clockmaking](https://en.wikipedia.org/wiki/Invar) - it's short
+> for "**invar**iable".
 
 ### Features
 
@@ -216,6 +217,10 @@ To open the file your system's default text editor (eg. nano):
 
     bundle exec rake invar:config
 
+> **Automation tip** You can provide new content over STDIN
+>
+>     bundle exec rake invar:config < config_template.yml
+
 #### Edit Secrets File
 
 To edit the secrets file, run this and provide the file's encryption key:
@@ -223,7 +228,27 @@ To edit the secrets file, run this and provide the file's encryption key:
     bundle exec rake invar:secrets
 
 The file will be decrypted and opened in your default editor like the config file. Once you have exited the editor, it
-will be re-encrypted. Remember to save your changes!
+will be re-encrypted. **Remember to save your changes!**
+
+> **Automation tip** You can set the current encryption key in the `LOCKBOX_MASTER_KEY` environment variable:
+>
+>     LOCKBOX_MASTER_KEY=sooper_sekret_key_here bundle exec rake invar:secrets
+
+> **Automation tip** Like invar:config, you can provide new content over STDIN
+>
+>     bundle exec rake invar:secrets < secrets_template.yml
+
+#### Rotating the Secrets File Encryption Key
+
+To re-encrypt the secrets file, run this and provide the file's current encryption key:
+
+    bundle exec rake invar:rotate
+
+A new encryption key will be generated just like using `invar:init`.
+
+> **Automation tip** you can set the current encryption key in the `LOCKBOX_MASTER_KEY` environment variable:
+>
+>     LOCKBOX_MASTER_KEY=sooper_sekret_key_here bundle exec rake invar:rotate
 
 ### Code
 

data/RELEASE_NOTES.md

@@ -13,6 +13,49 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Minor Changes
 
+* none
+
+### Bugfixes
+
+* none
+
+## [0.9.0] - 2023-09-24
+
+### Major Changes
+
+* none
+
+### Minor Changes
+
+* Added Rake task for secrets file key rotation
+* Added ability for invar:config and invar:secrets to take replacement content over `STDIN` instead of live editing
+
+### Bugfixes
+
+* none
+
+## [0.8.0] - 2023-09-13
+
+### Major Changes
+
+* none
+
+### Minor Changes
+
+* Increased minimum Ruby to 3.1
+
+### Bugfixes
+
+* none
+
+## [0.7.0] - 2023-08-06
+
+### Major Changes
+
+* none
+
+### Minor Changes
+
 * Tweaked file missing error messages
 * Extracted testing helper features into a separate module
 * Added support for multiple after_load hooks

data/invar.gemspec

@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
    spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
    spec.require_paths = ['lib']
 
-   spec.required_ruby_version = '>= 2.7'
+   spec.required_ruby_version = '>= 3.1'
 
    spec.add_dependency 'dry-schema', '>= 1.0'
    spec.add_dependency 'lockbox', '>= 1.0'

data/lib/invar/errors.rb

@@ -1,5 +1,7 @@
-module Invar
+# frozen_string_literal: true
 
+# :nodoc:
+module Invar
    # Raised when no config file can be found within the search paths.
    class MissingConfigFileError < RuntimeError
    end
@@ -41,11 +43,11 @@ module Invar
             require 'invar/test'
       HINT
 
-      PRETEND_MSG = "Method 'Invar::Scope#pretend' is defined in the testing extension. #{ HINT }"
-      HOOK_MSG    = "Methods 'Invar.after_load and clear_hooks' are defined in the testing extension. #{ HINT }"
+      PRETEND_MSG = "Method 'Invar::Scope#pretend' is defined in the testing extension. #{ HINT }".freeze
+      HOOK_MSG    = "Methods 'Invar.after_load and clear_hooks' are defined in the testing extension. #{ HINT }".freeze
    end
 
    # Raised when schema validation fails
    class SchemaValidationError < RuntimeError
    end
-end
+end

data/lib/invar/private_file.rb

@@ -9,7 +9,7 @@ module Invar
    # Verifies a file is secure
    class PrivateFile
       extend Forwardable
-      def_delegators :@delegate_sd_obj, :stat, :to_s, :basename, :==, :chmod
+      def_delegators :@delegate_sd_obj, :stat, :to_s, :basename, :dirname, :extname, :==, :chmod, :rename, :write
 
       # Mask for limiting to the lowest three octal digits (which store permissions)
       PERMISSIONS_MASK = 0o777

data/lib/invar/rake/tasks.rb

@@ -30,8 +30,8 @@ module Invar
          #
          # @param (see #define)
          # @see Tasks#define
-         def self.define(**args, &block)
-            new.define(**args, &block)
+         def self.define(...)
+            new.define(...)
          end
 
          # Defines helpful Rake tasks for the given namespace.
@@ -51,7 +51,7 @@ module Invar
                define_init_task(app_namespace)
 
                define_config_task(app_namespace)
-               define_secrets_task(app_namespace)
+               define_secrets_tasks(app_namespace)
 
                define_info_tasks(app_namespace)
             end
@@ -62,8 +62,8 @@ module Invar
             task :init, [:mode] do |_task, args|
                mode = args.mode
 
-               config  = ::Invar::Rake::Tasks::ConfigTask.new(app_namespace)
-               secrets = ::Invar::Rake::Tasks::SecretTask.new(app_namespace)
+               config  = ::Invar::Rake::Tasks::ConfigFileHandler.new(app_namespace)
+               secrets = ::Invar::Rake::Tasks::SecretsFileHandler.new(app_namespace)
 
                case mode
                when 'config'
@@ -71,7 +71,7 @@ module Invar
                when 'secrets'
                   config = nil
                else
-                  raise "unknown mode #{ mode }. Must be one of 'config' or 'secrets'" unless mode.nil?
+                  raise ArgumentError, "unknown mode '#{ mode }'. Must be one of 'config' or 'secrets'" unless mode.nil?
                end
 
                assert_init_conditions(config&.file_path, secrets&.file_path)
@@ -84,39 +84,44 @@ module Invar
          def define_config_task(app_namespace)
             desc 'Edit the config in your default editor'
             task :configs do
-               ::Invar::Rake::Tasks::ConfigTask.new(app_namespace).edit
+               ::Invar::Rake::Tasks::ConfigFileHandler.new(app_namespace).edit
             end
 
             # alias
             task config: ['configs']
          end
 
-         def define_secrets_task(app_namespace)
+         def define_secrets_tasks(app_namespace)
             desc 'Edit the encrypted secrets file in your default editor'
             task :secrets do
-               ::Invar::Rake::Tasks::SecretTask.new(app_namespace).edit
+               ::Invar::Rake::Tasks::SecretsFileHandler.new(app_namespace).edit
             end
 
             # alias
             task secret: ['secrets']
+
+            desc 'Encrypt the secrets file with a new generated key'
+            task :rotate do
+               ::Invar::Rake::Tasks::SecretsFileHandler.new(app_namespace).rotate
+            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
+               ::Invar::Rake::Tasks::StatusHandler.new(app_namespace).show_paths
             end
          end
 
          def assert_init_conditions(config_file, secrets_file)
             return unless config_file&.exist? || secrets_file&.exist?
 
-            msg = if !config_file&.exist?
+            msg = if !config_file.exist?
                      <<~MSG
                         Abort: Secrets file already exists (#{ secrets_file })
                         Run this to init only the config file: bundle exec rake tasks invar:init[config]
                      MSG
-                  elsif !secrets_file&.exist?
+                  elsif !secrets_file.exist?
                      <<~MSG
                         Abort: Config file already exists (#{ config_file })
                         Run this to init only the secrets file: bundle exec rake tasks invar:init[secrets]
@@ -133,7 +138,7 @@ module Invar
          end
 
          # Tasks that use a namespace for file searching
-         class NamespacedTask
+         class NamespacedFileTask
             def initialize(namespace)
                @locator = FileLocator.new(namespace)
             end
@@ -150,11 +155,9 @@ module Invar
          end
 
          # Configuration file actions.
-         class ConfigTask < NamespacedTask
+         class ConfigFileHandler < NamespacedFileTask
             # Creates a config file in the appropriate location
             def create
-               raise 'File already exists' if file_path.exist?
-
                config_dir.mkpath
                file_path.write CONFIG_TEMPLATE
                file_path.chmod 0o600
@@ -164,79 +167,108 @@ module Invar
 
             # 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(', ') }
-                                    #{ CREATE_SUGGESTION }
-                                 ERR
-                                 exit 1
-                              end
-
-               system(ENV.fetch('EDITOR', 'editor'), configs_file.to_s, exception: true)
-
-               warn "File saved to: #{ configs_file }"
+               content   = $stdin.tty? ? nil : $stdin.read
+               file_path = configs_file
+
+               if content
+                  file_path.write content
+               else
+                  system ENV.fetch('EDITOR', 'editor'), file_path.to_s, exception: true
+               end
+
+               warn "File saved to: #{ file_path }"
             end
 
             private
 
+            def configs_file
+               @locator.find 'config.yml'
+            rescue ::Invar::FileLocator::FileNotFoundError => e
+               warn <<~ERR
+                  Abort: #{ e.message }. Searched in: #{ @locator.search_paths.join(', ') }
+                  #{ CREATE_SUGGESTION }
+               ERR
+               exit 1
+            end
+
             def filename
                'config.yml'
             end
          end
 
          # Secrets file actions.
-         class SecretTask < NamespacedTask
+         class SecretsFileHandler < NamespacedFileTask
             # 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.
+               Generated key. 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
-               raise 'File already exists' if file_path.exist?
+            SWAP_EXT = 'tmp'
 
+            # Creates a new encrypted secrets file and prints the generated encryption key to STDOUT
+            def create(content: SECRETS_TEMPLATE)
                encryption_key = Lockbox.generate_key
 
                write_encrypted_file(file_path,
                                     encryption_key: encryption_key,
-                                    content:        SECRETS_TEMPLATE,
+                                    content:        content,
                                     permissions:    PrivateFile::DEFAULT_PERMISSIONS)
 
-               warn "Created file: #{ file_path }"
-
                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.
+            # Updates the file with new content.
+            #
+            # Either the content is provided over STDIN or the default editor is opened with 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(', ') }
-                                    #{ CREATE_SUGGESTION }
-                                 ERR
-                                 exit 1
-                              end
-
-               edit_encrypted_file(secrets_file)
+               content = $stdin.tty? ? nil : $stdin.read
+
+               edit_encrypted_file(secrets_file, content: content)
 
                warn "File saved to #{ secrets_file }"
             end
 
+            def rotate
+               file_path = secrets_file
+
+               decrypted = read_encrypted_file(file_path, encryption_key: determine_key(file_path))
+
+               swap_file = file_path.dirname / [file_path.basename, SWAP_EXT].join('.')
+               file_path.rename swap_file
+
+               begin
+                  create content: decrypted
+                  swap_file.delete
+               rescue StandardError
+                  swap_file.rename file_path.to_s
+               end
+            end
+
             private
 
+            def secrets_file
+               @locator.find 'secrets.yml'
+            rescue ::Invar::FileLocator::FileNotFoundError => e
+               warn <<~ERR
+                  Abort: #{ e.message }. Searched in: #{ @locator.search_paths.join(', ') }
+                  #{ CREATE_SUGGESTION }
+               ERR
+               exit 1
+            end
+
             def filename
                'secrets.yml'
             end
 
+            def read_encrypted_file(file_path, encryption_key:)
+               lockbox = build_lockbox(encryption_key)
+               lockbox.decrypt(file_path.binread)
+            end
+
             def write_encrypted_file(file_path, encryption_key:, content:, permissions: nil)
-               lockbox = Lockbox.new(key: encryption_key)
+               lockbox = build_lockbox(encryption_key)
 
                encrypted_data = lockbox.encrypt(content)
 
@@ -244,23 +276,27 @@ module Invar
                # 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 }
                file_path.chmod permissions if permissions
+
+               warn "Saved file: #{ file_path }"
             end
 
-            def edit_encrypted_file(file_path)
+            def edit_encrypted_file(file_path, content: nil)
                encryption_key = determine_key(file_path)
 
-               lockbox = build_lockbox(encryption_key)
+               content ||= invoke_editor(file_path, encryption_key: encryption_key)
+
+               write_encrypted_file(file_path, encryption_key: encryption_key, content: content)
+            end
 
-               file_str = Tempfile.create(file_path.basename.to_s) do |tmp_file|
-                  decrypted = lockbox.decrypt(file_path.binread)
+            def invoke_editor(file_path, encryption_key:)
+               Tempfile.create(file_path.basename.to_s) do |tmp_file|
+                  decrypted = read_encrypted_file(file_path, encryption_key: encryption_key)
 
                   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: encryption_key, content: file_str)
             end
 
             def determine_key(file_path)
@@ -282,7 +318,7 @@ module Invar
          end
 
          # General status tasks
-         class StateTask < NamespacedTask
+         class StatusHandler < NamespacedFileTask
             # Prints the current paths to be searched in
             def show_paths
                warn @locator.search_paths.join("\n")

data/lib/invar/reality.rb

@@ -78,8 +78,9 @@ module Invar
          begin
             @secrets = Scope.new(load_secrets(locator, decryption_keyfile || DEFAULT_KEY_FILE_NAME))
          rescue FileLocator::FileNotFoundError
+            hint = "Create encrypted secrets.yml in one of these locations: #{ search_paths }"
             raise MissingSecretsFileError,
-                  "No Invar secrets file found. Create encrypted secrets.yml in one of these locations: #{ search_paths }"
+                  "No Invar secrets file found. #{ hint }"
          end
 
          freeze

data/lib/invar/scope.rb

@@ -26,11 +26,9 @@ module Invar
       alias [] fetch
 
       def method_missing(symbol, *args)
-         if symbol == :pretend
-            raise ::Invar::ImmutableRealityError, ::Invar::ImmutableRealityError::PRETEND_MSG
-         else
-            super
-         end
+         raise ::Invar::ImmutableRealityError, ::Invar::ImmutableRealityError::PRETEND_MSG if symbol == :pretend
+
+         super
       end
 
       # Returns a hash representation of this scope and subscopes.

data/lib/invar/test.rb

@@ -1,16 +1,19 @@
 # frozen_string_literal: true
 
-# Specifically not calling require 'invar' here to force applications to need to include it themselves,
-# preventing the situation where test suites include application dependencies for them and breaking when
+# Specifically not calling require 'invar' in this file to force applications to need to include it themselves,
+# avoiding the situation where test suites include application dependencies for them and breaking when
 # the app is run without the test suite
 
+# :nodoc:
 module Invar
    # Namespace module containing mixins for parts of the main gem to enable modifications and data control
    # in automated testing, while remaining immutable in the main gem and real runtime usage.
    module TestExtension
+      # Methods to extend the Reality class
       module RealityMethods
          class << self
             attr_accessor :__after_load_hooks__
+
             RealityMethods.__after_load_hooks__ = []
          end
 

data/lib/invar/version.rb

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

data/lib/invar.rb

@@ -18,9 +18,9 @@ module Invar
       def method_missing(meth)
          if [:after_load, :clear_hooks].include? meth
             raise ::Invar::ImmutableRealityError, ::Invar::ImmutableRealityError::HOOK_MSG
-         else
-            super
          end
+
+         super
       end
    end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: invar
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Robin Miller
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-08-06 00:00:00.000000000 Z
+date: 2023-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-schema
@@ -51,6 +51,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- ".simplecov"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -80,14 +81,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.4.18
 signing_key: 
 specification_version: 4
 summary: Single source of truth for environmental configuration.