ironclad 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e2b08a6c0985159ff7be4790655703218e7eef6428416a68eba9fe8d039d16b
-  data.tar.gz: 0d14ea6406e375cad4f6045ab1e1bf0bcfa6a85deb9a3c995b745d786ef5f823
+  metadata.gz: 3a87bf5f6911710634655b6619b79f20feec36c8c91033e4174b84f6d51eb643
+  data.tar.gz: a594caae3ea3825b7fbd5984301ad90298b163174e7ec1378274c117e1c7c05e
 SHA512:
-  metadata.gz: 2c5bee8e2a72bb805d56c58884d951008a02408e3d99ddfeef8ec4723af1a619b130c5a36f0e668de0f5ddad720116cb50ed3319f8994970e7f65fb01de501a5
-  data.tar.gz: 3bc45b204cb6f95ebe763000b13d388c5c737602b273f16380bf2e6dc1f1d4260f896e73b5e855465245ca2bd39e9c9dfc221471109d06bd8b5d2de94af3a0ba
+  metadata.gz: 2e554621354d643f0ca215b07194774d2e634ad3a6d0730029ad492f10545de281c755535b74e944f44a0926727deeb9ea392dc9618acc93404bba1af74cc4b5
+  data.tar.gz: 79fb39bfd14bcd75f312193f60484cf970ea68fea9a1ce420302955f5062a671a99c676aa2b5c9b33994a0b0818b8b5a78dd37ed1cd136340d84e1007b058933

data/README.md

@@ -11,7 +11,8 @@ Ironclad reads each environment's key (`master.key`, `production.key`) from
 Linux kernel keyring — so repeated use doesn't round-trip to 1Password. It
 ships:
 
-- a CLI for printing a key or editing credentials,
+- a CLI for printing a key, editing credentials, and keeping `git diff`
+  readable,
 - a Railtie that loads the current environment's key into `ENV` at boot,
 - Capistrano helpers so deploys need no key file, and
 - an install generator that wires it all into a Rails app.
@@ -24,8 +25,9 @@ ships:
 2. On a miss, read it from 1Password (`op read`) and seed the cache.
 
 The cache never expires. After rotating a key, refresh it with
-`bin/ironclad <env> --refresh`. Platforms with no supported keystore simply
-fetch from 1Password every call.
+`bin/ironclad refresh <env>`, or refresh every environment at once with
+`bin/ironclad refresh --all`. Platforms with no supported keystore simply fetch
+from 1Password every call.
 
 ## Requirements
 
@@ -80,10 +82,12 @@ keys:
 ### CLI
 
 ```sh
-bin/ironclad                      # print the development key
-bin/ironclad production           # print the production key
-bin/ironclad production --refresh # bypass the cache after a rotation
-bin/ironclad edit staging         # edit staging credentials in your editor
+bin/ironclad                    # print the development key
+bin/ironclad production         # print the production key
+bin/ironclad refresh            # re-cache the development key after a rotation
+bin/ironclad refresh production # re-cache production's key
+bin/ironclad refresh --all      # re-cache every configured environment's key
+bin/ironclad edit staging       # edit staging credentials in your editor
 ```
 
 ### Capistrano

data/lib/generators/ironclad/install_generator.rb

@@ -42,6 +42,7 @@ module Ironclad
 
           Print a key:      bin/ironclad [env]
           Edit credentials: bin/ironclad edit [env]
+          After a rotation: bin/ironclad refresh [env]
         MESSAGE
       end
 

data/lib/ironclad/cache/keychain.rb

@@ -22,11 +22,13 @@ module Ironclad
       def write(name, key)
         # The key passes via argv (briefly visible to the same user's `ps`); the
         # security tool has no stdin input mode. Acceptable for a local cache.
+        # system returns nil when `security` cannot be executed at all, which is
+        # a failure to cache just as much as a non-zero exit is.
         system(
           'security', 'add-generic-password', '-U',
           '-a', @account, '-s', name, '-w', key,
           out: File::NULL, err: File::NULL
-        )
+        ) || false
       end
     end
   end

data/lib/ironclad/cache/keyctl.rb

@@ -15,15 +15,46 @@ module Ironclad
       end
 
       def read(name)
-        id, status = Open3.capture2('keyctl', 'search', '@u', 'user', name)
+        id, _error, status = Open3.capture3(
+          'keyctl', 'search', '@u', 'user', name
+        )
         return unless status.success?
 
-        out, status = Open3.capture2('keyctl', 'pipe', id.chomp)
+        out, _error, status = Open3.capture3('keyctl', 'pipe', id.chomp)
         status.success? ? out : nil
       end
 
       def write(name, key)
-        Open3.capture2('keyctl', 'padd', 'user', name, '@u', stdin_data: key)
+        # `keyctl padd` creates the key with the kernel's default permissions
+        # and offers no way to set them at creation, so changing them afterwards
+        # needs setattr, which only a possessor has. @u grants the owning user
+        # link permission, so linking it into @s first guarantees possession.
+        Open3.capture3('keyctl', 'link', '@u', '@s')
+
+        id, error, status = Open3.capture3(
+          'keyctl', 'padd', 'user', name, '@u', stdin_data: key
+        )
+        return warn_failure(error, "cache #{name}") unless status.success?
+
+        # possessor 0x3f (all), user 0x2f (view, read, write, search, setattr),
+        # group and other none. A caller that does not possess the key gets only
+        # the user byte, which has to cover every operation performed here.
+        _out, error, status = Open3.capture3(
+          'keyctl', 'setperm', id.chomp, '0x3f2f0000'
+        )
+        return warn_failure(error, "set permissions on #{name}") unless status.success?
+
+        true
+      end
+
+      private
+
+      def warn_failure(error, action)
+        detail = error.strip
+        message = "ironclad: could not #{action} in the Linux keyring"
+        message += ": #{detail}" unless detail.empty?
+        warn message
+        false
       end
     end
   end

data/lib/ironclad/cache/null.rb

@@ -7,7 +7,7 @@ module Ironclad
     class Null
       def read(_name) = nil
 
-      def write(_name, _key) = nil
+      def write(_name, _key) = true
     end
   end
 end

data/lib/ironclad/cache.rb

@@ -6,7 +6,10 @@ require_relative 'cache/keyctl'
 require_relative 'cache/null'
 
 module Ironclad
-  # Selects the OS keystore backend for the current platform.
+  # Selects the OS keystore backend for the current platform. A backend responds
+  # to #read(name), returning the cached string or nil, and #write(name, key),
+  # returning true when the key is cached and false when it is not. A backend
+  # with nowhere to store keys reports true: nothing to do is not a failure.
   module Cache
     module_function
 

data/lib/ironclad/cli.rb

@@ -6,8 +6,11 @@ module Ironclad
   # Command-line entry point. Dependency-free arg parsing keeps boot cheap and
   # avoids loading Rails just to print a key.
   #
-  #   ironclad [env] [--refresh]   print the credentials key (default env)
+  #   ironclad [env]               print the credentials key (default env)
+  #   ironclad refresh [env]       re-cache one environment's key
+  #   ironclad refresh --all       re-cache every environment's key
   #   ironclad edit [env]          edit Rails credentials for env
+  #   ironclad diff <file>         git textconv: decrypt a credentials file
   class CLI
     def self.start(argv)
       new(argv).run
@@ -19,9 +22,15 @@ module Ironclad
 
     def run
       case @argv.first
+      when 'refresh'
+        @argv.shift
+        return refresh
       when 'edit'
         @argv.shift
         edit(@argv.shift || 'default')
+      when 'diff'
+        @argv.shift
+        diff(@argv.shift)
       when '-h', '--help', 'help'
         print_help
       else
@@ -36,21 +45,58 @@ module Ironclad
     private
 
     def print_key
-      refresh = @argv.delete('--refresh') ? true : false
       env = @argv.shift || 'default'
       validate_env!(env)
-      puts Ironclad.key(env, refresh: refresh)
+      puts Ironclad.key(env)
+    end
+
+    def refresh
+      return refresh_all if @argv.delete('--all')
+
+      env = @argv.shift || 'default'
+      validate_env!(env)
+      refresh_key(env) ? 0 : 1
+    end
+
+    def refresh_all
+      environments = Ironclad.config.environments
+      if environments.empty?
+        raise Error, 'No environments are configured in config/ironclad.yml.'
+      end
+
+      failed = environments.reject { |env| refresh_key(env) }
+      return 0 if failed.empty?
+
+      warn "Failed to refresh: #{failed.join(', ')}."
+      1
+    end
+
+    def refresh_key(env)
+      Ironclad.key(env, refresh: true)
+      puts "#{env}: refreshed"
+      true
+    rescue Error => e
+      warn "#{env}: #{e.message}"
+      false
     end
 
     def edit(env)
       validate_env!(env)
       ENV['RAILS_MASTER_KEY'] = Ironclad.key(env)
+      Ironclad.configure_git_diff!
 
       args = ['credentials:edit']
       args.push('-e', env) unless env == 'default'
       exec('bin/rails', *args)
     end
 
+    def diff(path)
+      raise Error, 'Usage: ironclad diff <file>' unless path
+
+      require_relative 'diff'
+      Diff.call(path)
+    end
+
     def validate_env!(env)
       return if Ironclad.config.environments.include?(env)
 
@@ -63,11 +109,14 @@ module Ironclad
         ironclad — Rails credential keys from 1Password, cached locally.
 
         Usage:
-          ironclad [env] [--refresh]   print the credentials key (env: default)
+          ironclad [env]               print the credentials key (env: default)
           ironclad edit [env]          edit Rails credentials for env
+          ironclad diff <file>         git textconv: decrypt a credentials file
+          ironclad refresh [env]       re-cache one key (env: default)
+          ironclad refresh --all       re-cache every environment's key
           ironclad --help              show this help
 
-        --refresh re-reads from the source after a key rotation.
+        refresh re-reads from the source after a key rotation.
         Environments are defined in config/ironclad.yml.
       HELP
     end

data/lib/ironclad/diff.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/encrypted_file'
+
+module Ironclad
+  module Diff
+    ENV_KEY = 'IRONCLAD_DIFF_KEY'
+
+    module_function
+
+    def call(path, out = $stdout)
+      out.write(decrypt(path) || File.read(path))
+    end
+
+    def decrypt(path)
+      key = Ironclad.key(environment_for(path))
+      return unless key
+
+      ENV[ENV_KEY] = key
+      ActiveSupport::EncryptedFile.new(
+        content_path: path, key_path: File::NULL,
+        env_key: ENV_KEY, raise_if_missing_key: true
+      ).read
+    rescue Ironclad::Error, ActiveSupport::MessageEncryptor::InvalidMessage
+      nil
+    end
+
+    def environment_for(path)
+      env = File.basename(path).delete_suffix('.yml.enc')
+      Ironclad.config.key?(env) ? env : 'default'
+    end
+  end
+end

data/lib/ironclad/key_store.rb

@@ -22,7 +22,12 @@ module Ironclad
       end
 
       fetched = @source.read(@config.reference(environment))
-      @cache.write(name, fetched)
+      cached = @cache.write(name, fetched)
+      if refresh && !cached
+        raise Error,
+              "Could not cache refreshed credentials key for #{environment}"
+      end
+
       fetched
     end
   end

data/lib/ironclad/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ironclad
-  VERSION = '0.3.0'
+  VERSION = '0.5.0'
 end

data/lib/ironclad.rb

@@ -12,6 +12,9 @@ require_relative 'ironclad/key_store'
 module Ironclad
   class Error < StandardError; end
 
+  GIT_DIFF_DRIVER = 'rails_credentials'
+  DIFF_COMMAND = 'bin/ironclad diff'
+
   class << self
     # Path to the project's ironclad.yml. Override before first use if needed.
     attr_writer :config_path
@@ -38,11 +41,26 @@ module Ironclad
       store.key(environment.to_s, refresh: refresh)
     end
 
+    def configure_git_diff!(command = DIFF_COMMAND)
+      return unless enrolled_in_git_diff?
+
+      system('git', 'config', "diff.#{GIT_DIFF_DRIVER}.textconv", command,
+             %i[out err] => File::NULL)
+    end
+
     # Reset memoized state (mainly for tests).
     def reset!
       @config = nil
       @store = nil
     end
+
+    private
+
+    def enrolled_in_git_diff?
+      attributes = File.join(Dir.pwd, '.gitattributes')
+      File.file?(attributes) &&
+        File.read(attributes).include?("diff=#{GIT_DIFF_DRIVER}")
+    end
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ironclad
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Jarrett Lusso
@@ -104,6 +104,7 @@ files:
 - lib/ironclad/capistrano.rb
 - lib/ironclad/cli.rb
 - lib/ironclad/config.rb
+- lib/ironclad/diff.rb
 - lib/ironclad/key_store.rb
 - lib/ironclad/railtie.rb
 - lib/ironclad/source.rb