security 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d010aca28c455caae65e0063ab5ee35336eace64fd8049012c66f77edc634f20
-  data.tar.gz: a46b316771d171579e241b7c875b99bdaaa0f0cc6e7f9312d1627767b90c3c9e
+  metadata.gz: c157bfbd48ec870177f4a269569efc87edad32606bc9a7332b4d26644a13edf9
+  data.tar.gz: 275fbb21545cde55939d4512cec08d3c52bcff6a96d5300cb746941813685bed
 SHA512:
-  metadata.gz: 106ba3c86bc5254bd1d589d1de99ea992b4cb12731761ff79faeed1cbe48f495451520b6ebbf91c50f6fb41b838ecd01de11eec9ca08d97e39c853cc457844e5
-  data.tar.gz: 636bfaf6e7a5b88eb38112008d3a46ed13da71cd13e8e16bb9891a24b5fbd8fca85dd58017f505d1c0df45264a1be3773f9bf15e973b688f0069135463407cf6
+  metadata.gz: 0f8a12a0decc2ab2e277816af45860be94894bf2b01dc307e5f4d3b88251d8a6676dbf5c0469af862c19a73679a8d444eb1b8502345756ac3595c35d7e38e9fb
+  data.tar.gz: e2b77b3d17ec02afb5c99d1a69d638633ab83026777fbb7c883fe4c8ae4b6896f269f38df28208508e15af937ea549eb7a9f95ecd82a32472956b3334605b13c

data/Gemfile

@@ -3,8 +3,9 @@
 source 'https://rubygems.org'
 
 gem 'rake', '~> 13.4'
-gem 'rspec'
-gem 'rubocop'
-gem 'simplecov'
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.90'
+# simplecov 1.x requires Ruby >= 3.2; hold at 0.x while Ruby 3.1 is supported
+gem 'simplecov', '~> 0.22'
 
 gemspec

data/Gemfile.lock

@@ -1,17 +1,18 @@
 PATH
   remote: .
   specs:
-    security (0.2.0)
+    security (0.3.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
     diff-lcs (1.6.2)
-    json (2.21.2)
+    docile (1.4.1)
+    json (3.0.2)
     language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
-    parallel (2.1.0)
+    parallel (2.2.0)
     parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
@@ -33,8 +34,8 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.89.0)
-      json (~> 2.3)
+    rubocop (1.91.0)
+      json (>= 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
       parallel (>= 1.10)
@@ -48,7 +49,12 @@ GEM
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     ruby-progressbar (1.13.0)
-    simplecov (1.1.1)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
@@ -59,10 +65,10 @@ PLATFORMS
 
 DEPENDENCIES
   rake (~> 13.4)
-  rspec
-  rubocop
+  rspec (~> 3.13)
+  rubocop (~> 1.90)
   security!
-  simplecov
+  simplecov (~> 0.22)
 
 BUNDLED WITH
    2.6.9

data/README.md

@@ -1,6 +1,6 @@
 # Security
 
-[![Build Status][build status badge]][build status]
+[![CI](https://github.com/fastlane-community/security/actions/workflows/ci.yml/badge.svg)](https://github.com/fastlane-community/security/actions/workflows/ci.yml)
 [![Gem](https://img.shields.io/gem/v/security.svg?style=flat)](https://rubygems.org/gems/security)
 [![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat)](https://github.com/fastlane-community/security/blob/main/LICENSE.md)
 
@@ -14,14 +14,54 @@
 ```ruby
 require 'security'
 
-Security::Keychain::default_keychain.filename #=> "/Users/jappleseed/Library/Keychains/login.keychain"
+Security::Keychain.default_keychain.filename #=> "/Users/jappleseed/Library/Keychains/login.keychain-db"
 
-Security::InternetPassword.find(server: "itunesconnect.apple.com").password #=> "p4ssw0rd"
+item = Security::InternetPassword.find(server: "itunesconnect.apple.com")
+item&.password #=> "p4ssw0rd"
 ```
 
-## License
+## Keychains
+
+`find`, `add` and `delete` all take an optional `keychain:`, naming the keychain
+to act on. It accepts a `Security::Keychain` or a path. Without one, `security`
+adds to the default keychain and searches the default search list.
+
+```ruby
+keychain = Security::Keychain.new("/path/to/build.keychain-db")
+
+Security::InternetPassword.add("example.com", "jappleseed", "p4ssw0rd", keychain: keychain)
+Security::InternetPassword.find(server: "example.com", keychain: keychain)
+Security::InternetPassword.delete(server: "example.com", keychain: keychain)
+```
+
+## Errors
+
+The `security` command line tool reports failures through its exit status, and
+this library distinguishes the two cases a caller needs to tell apart:
 
-MIT
+- **Nothing matched.** `find` returns `nil`. The keychain answered, and it holds
+  no such item.
+- **The question could not be answered.** `find` raises `Security::Error`,
+  carrying the tool's exit `status` and its `output`. A locked keychain, a
+  keychain this process is not allowed to read, or a malformed request all
+  land here.
+
+```ruby
+begin
+  item = Security::InternetPassword.find(server: "itunesconnect.apple.com")
+rescue Security::Error => e
+  warn "could not read the keychain: #{e.message}"
+  item = nil
+end
+```
+
+`Keychain.list`, `Keychain.default_keychain` and `Keychain.login_keychain`
+raise `Security::Error` on failure in the same way.
+
+The methods that change the keychain — `add`, `delete`, and the `Keychain`
+instance methods — return `true` or `false` and print what the tool reported,
+the way `Kernel#system` does.
+
+## License
 
-[build status]: https://github.com/mattt/Security/actions?query=workflow%3ACI
-[build status badge]: https://github.com/mattt/Security/workflows/CI/badge.svg
+[MIT](https://github.com/fastlane-community/security/blob/main/LICENSE.md)

data/UPGRADE.md

@@ -0,0 +1,7 @@
+# Upgrade Guide
+
+## Upgrading from 0.2 to 0.3
+
+In previous versions, `find` attempted to detect failures by searching for a `security: ` prefix in the output. This approach was unreliable: certain errors (like ACL issues) produced no output, while others (like malformed requests) returned a usage banner. These cases would incorrectly result in a `Password` object with `nil` attributes, making it impossible for callers to distinguish a failed request from a successful one. Additionally, failures that *did* have the prefix returned `nil`, which was indistinguishable from a missing item.
+
+Starting with version 0.3, both cases now raise a `Security::Error`. If your code relies on `nil` to handle missing keychain items, you should now rescue `Security::Error` to prevent a locked or misconfigured keychain from being treated as empty.

data/lib/security/command.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'English'
+require 'open3'
+
+module Security
+  # :nodoc:
+  module Command
+    # TODO: replace with Data.define once Ruby 3.1 support is dropped.
+    # :nodoc:
+    Result = Struct.new(:stdout, :stderr, :status) do
+      def success?
+        !status.nil? && status.success?
+      end
+
+      def exitstatus
+        status&.exitstatus
+      end
+
+      # `security` splits what it has to say across both streams: find-*-password
+      # prints the attributes on stdout and the password on stderr.
+      def output
+        stdout + stderr
+      end
+    end
+
+    module_function
+
+    # Runs a `security` subcommand and captures what it produced. A missing
+    # `security` is a failed result rather than an exception: the tool is only
+    # present on macOS, and callers elsewhere should see the same failure they
+    # would get from a keychain that could not answer.
+    def run(command)
+      Result.new(*Open3.capture3(command))
+    rescue Errno::ENOENT => e
+      # Nothing ran, but the child Ruby forked exited 127 before exec, which is
+      # what a shell reports for a missing command, and what this library
+      # produced while it still went through one.
+      Result.new('', "#{e.message}\n", $CHILD_STATUS)
+    end
+
+    # Runs a `security` subcommand and lets the caller see what it said. The
+    # tool reports on stderr whether or not it succeeded: show-keychain-info
+    # prints its result there on exit 0.
+    def relay(command)
+      result = run(command)
+      warn result.stderr.chomp unless result.stderr.empty?
+
+      result
+    end
+  end
+end

data/lib/security/error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Security
+  # :nodoc:
+  class Error < StandardError
+    attr_reader :status, :output
+
+    def initialize(status, output)
+      @status = status
+      @output = output
+
+      details = output.strip
+      super(details.empty? ? "`security` exited with status #{status}" : "#{details} (status #{status})")
+    end
+  end
+end

data/lib/security/keychain.rb

@@ -14,19 +14,19 @@ module Security
     end
 
     def info
-      system %(security show-keychain-info #{@filename.shellescape})
+      Command.relay(%(security show-keychain-info #{@filename.shellescape})).success?
     end
 
     def lock
-      system %(security lock-keychain #{@filename.shellescape})
+      Command.relay(%(security lock-keychain #{@filename.shellescape})).success?
     end
 
     def unlock(password)
-      system %(security unlock-keychain -p #{password.shellescape} #{@filename.shellescape})
+      Command.relay(%(security unlock-keychain -p #{password.shellescape} #{@filename.shellescape})).success?
     end
 
     def delete
-      system %(security delete-keychain #{@filename.shellescape})
+      Command.relay(%(security delete-keychain #{@filename.shellescape})).success?
     end
 
     class << self
@@ -35,29 +35,36 @@ module Security
       end
 
       def list(domain = :user)
-        raise ArgumentError "Invalid domain #{domain}, expected one of: #{DOMAINS}" unless DOMAINS.include?(domain)
+        raise ArgumentError, "Invalid domain #{domain}, expected one of: #{DOMAINS}" unless DOMAINS.include?(domain)
 
-        keychains_from_output(`security list-keychains -d #{domain}`)
+        keychains_from_command("security list-keychains -d #{domain}")
       end
 
       def lock
-        system %(security lock-keychain -a)
+        Command.relay(%(security lock-keychain -a)).success?
       end
 
       def unlock(password)
-        system %(security unlock-keychain -p #{password.shellescape})
+        Command.relay(%(security unlock-keychain -p #{password.shellescape})).success?
       end
 
       def default_keychain
-        keychains_from_output(`security default-keychain`).first
+        keychains_from_command('security default-keychain').first
       end
 
       def login_keychain
-        keychains_from_output(`security login-keychain`).first
+        keychains_from_command('security login-keychain').first
       end
 
       private
 
+      def keychains_from_command(command)
+        result = Command.run(command)
+        raise Error.new(result.exitstatus, result.stderr) unless result.success?
+
+        keychains_from_output(result.stdout)
+      end
+
       def keychains_from_output(output)
         output.split("\n").collect { |line| new(line.strip.gsub(/^"|"$/, '')) }
       end

data/lib/security/password.rb

@@ -5,6 +5,10 @@ require 'shellwords'
 module Security
   # :nodoc:
   class Password
+    # `security` reports a missing item with this exit status. Every other
+    # non-zero status is a failure the caller needs to know about.
+    ITEM_NOT_FOUND = 44
+
     attr_reader :keychain, :attributes, :password
 
     private_class_method :new
@@ -18,9 +22,15 @@ module Security
     class << self
       private
 
-      def password_from_output(output)
-        return nil if output.match?(/^security: /)
+      def password_from_command(command)
+        result = Command.run(command)
+        return nil if result.exitstatus == ITEM_NOT_FOUND
+        raise Error.new(result.exitstatus, result.stderr) unless result.success?
 
+        password_from_output(result.output)
+      end
+
+      def password_from_output(output)
         keychain = nil
         attributes = {}
         password = nil
@@ -44,6 +54,7 @@ module Security
 
       def flags_for_options(options = {})
         flags = options.dup
+        keychain = flags.delete(:keychain)
         flags[:a] ||= flags.delete(:account)
         flags[:c] ||= flags.delete(:creator)
         flags[:C] ||= flags.delete(:type)
@@ -51,7 +62,18 @@ module Security
         flags[:G] ||= flags.delete(:value)
         flags[:j] ||= flags.delete(:comment)
 
-        flags.delete_if { |_k, v| v.nil? }.collect { |k, v| "-#{k} #{v.shellescape}".strip }.join(' ')
+        arguments = flags.compact.collect { |k, v| "-#{k} #{v.shellescape}".strip }
+        arguments << filename_for_keychain(keychain) if keychain
+
+        arguments.join(' ')
+      end
+
+      # `security` takes the keychain to act on as a trailing argument. Without
+      # one it uses the default keychain, or the default search list.
+      def filename_for_keychain(keychain)
+        filename = keychain.is_a?(Keychain) ? keychain.filename : keychain
+
+        filename.shellescape
       end
 
       def decode_hex_blob(string)
@@ -68,15 +90,15 @@ module Security
         options[:s] = service
         options[:w] = password
 
-        system "security add-generic-password #{flags_for_options(options)}"
+        Command.relay("security add-generic-password #{flags_for_options(options)}").success?
       end
 
       def find(options)
-        password_from_output(`security 2>&1 find-generic-password -g #{flags_for_options(options)}`)
+        password_from_command("security find-generic-password -g #{flags_for_options(options)}")
       end
 
       def delete(options)
-        system "security delete-generic-password #{flags_for_options(options)}"
+        Command.run("security delete-generic-password #{flags_for_options(options)}").success?
       end
 
       private
@@ -95,16 +117,15 @@ module Security
         options[:a] = account
         options[:s] = server
         options[:w] = password
-
-        system "security add-internet-password #{flags_for_options(options)}"
+        Command.relay("security add-internet-password #{flags_for_options(options)}").success?
       end
 
       def find(options)
-        password_from_output(`security 2>&1 find-internet-password -g #{flags_for_options(options)}`)
+        password_from_command("security find-internet-password -g #{flags_for_options(options)}")
       end
 
       def delete(options)
-        system "security delete-internet-password #{flags_for_options(options)}"
+        Command.run("security delete-internet-password #{flags_for_options(options)}").success?
       end
 
       private

data/lib/security/version.rb

@@ -2,5 +2,5 @@
 
 # :nodoc:
 module Security
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/security.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'security/version'
+require 'security/error'
+require 'security/command'
 require 'security/keychain'
 require 'security/certificate'
 require 'security/password'

data/security.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |s|
   s.files         = Dir['./**/*'].grep_v(%r{\./(bin|log|pkg|script|spec|test|vendor)})
   s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
   s.require_paths = ['lib']
-  s.required_ruby_version = '>= 3.0.0'
+  s.required_ruby_version = '>= 3.1.0'
 
   s.metadata['rubygems_mfa_required'] = 'true'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: security
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Josh Holtz
@@ -21,8 +21,11 @@ files:
 - "./LICENSE.md"
 - "./README.md"
 - "./Rakefile"
+- "./UPGRADE.md"
 - "./lib/security.rb"
 - "./lib/security/certificate.rb"
+- "./lib/security/command.rb"
+- "./lib/security/error.rb"
 - "./lib/security/keychain.rb"
 - "./lib/security/password.rb"
 - "./lib/security/version.rb"
@@ -39,7 +42,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="