iostreams 1.11.0 → 2.0.0

data/lib/io_streams/pgp.rb

@@ -1,4 +1,5 @@
 require "open3"
+require "shellwords"
 module IOStreams
   # Read/Write PGP/GPG file or stream.
   #
@@ -25,6 +26,18 @@ module IOStreams
 
     @executable = "gpg"
 
+    # Returns [Array<String>] the argv used to invoke gpg, with the supplied
+    # arguments appended.
+    #
+    # All gpg invocations are run without a shell (the multi-argument form of
+    # `Open3`) so that values such as email addresses, key ids, passphrases and
+    # file names cannot be interpreted as shell commands. The configured
+    # `executable` is split with `Shellwords` so that it may still contain
+    # additional fixed arguments (for example "gpg --homedir /path").
+    def self.gpg_command(*args)
+      Shellwords.split(executable) + args.map(&:to_s)
+    end
+
     # Generate a new ultimate trusted local public and private key.
     #
     # Returns [String] the key id for the generated key.
@@ -44,6 +57,20 @@ module IOStreams
     #   Highly Recommended.
     #   To generate a good passphrase:
     #     `SecureRandom.urlsafe_base64(128)`
+    #   Pass `nil` to generate an unprotected (passphrase-less) key.
+    #
+    # key_curve / subkey_curve [String]
+    #   Optional Elliptic Curve to use for the (sub)key, e.g. "ed25519".
+    #   When supplied the corresponding key/subkey length is ignored.
+    #   Requires GnuPG 2.1 or later.
+    #
+    # key_usage / subkey_usage [String]
+    #   Optional comma separated list of (sub)key capabilities, e.g. "sign".
+    #   Requires GnuPG 2.1 or later.
+    #
+    # creation_date [String]
+    #   Optional creation date for the key, e.g. "20240101T000000".
+    #   Requires GnuPG 2.1 or later.
     #
     # See `man gpg` for the remaining options
     def self.generate_key(name:,
@@ -54,23 +81,70 @@ module IOStreams
                           key_length: 4096,
                           subkey_type: "RSA",
                           subkey_length: key_length,
+                          key_curve: nil,
+                          key_usage: nil,
+                          subkey_curve: nil,
+                          subkey_usage: nil,
+                          creation_date: nil,
                           expire_date: nil)
       version_check
-      params = ""
+
+      # Reject newlines so that a value cannot inject additional directives into
+      # the gpg batch key-generation parameter file.
+      reject_newlines!(name: name, email: email, comment: comment, passphrase: passphrase,
+                       key_type: key_type, subkey_type: subkey_type, expire_date: expire_date,
+                       key_curve: key_curve, key_usage: key_usage,
+                       subkey_curve: subkey_curve, subkey_usage: subkey_usage,
+                       creation_date: creation_date)
+
+      # `%no-protection`, and the Elliptic Curve / usage / creation-date directives
+      # were all introduced in GnuPG 2.1. Keep older versions working by only
+      # emitting them when a 2.1+ binary is detected. `--batch --gen-key` accepts
+      # all of these on 2.1+, so there is no need for the newer `--full-gen-key`.
+      modern = pgp_version.to_f >= 2.1
+
+      unless modern
+        new_options = {
+          key_curve:     key_curve,
+          key_usage:     key_usage,
+          subkey_curve:  subkey_curve,
+          subkey_usage:  subkey_usage,
+          creation_date: creation_date
+        }.compact
+        unless new_options.empty?
+          raise(ArgumentError,
+                "IOStreams::Pgp.generate_key: #{new_options.keys.join(', ')} require GnuPG 2.1 or later " \
+                "(detected #{pgp_version})")
+        end
+      end
+
+      params = +""
+      # `%no-protection` is a control statement and must precede the key parameters.
+      # GnuPG 2.1+ requires this explicit opt-out to create an unprotected key;
+      # older versions create one simply by omitting the Passphrase directive.
+      params << "%no-protection\n" if !passphrase && modern
       params << "Key-Type: #{key_type}\n" if key_type
-      params << "Key-Length: #{key_length}\n" if key_length
+      # Key-Length and Key-Curve are mutually exclusive: curves imply their own length.
+      params << "Key-Length: #{key_length}\n" if key_length && !key_curve
+      params << "Key-Curve: #{key_curve}\n" if key_curve
+      params << "Key-Usage: #{key_usage}\n" if key_usage
       params << "Subkey-Type: #{subkey_type}\n" if subkey_type
-      params << "Subkey-Length: #{subkey_length}\n" if subkey_length
+      params << "Subkey-Length: #{subkey_length}\n" if subkey_length && !subkey_curve
+      params << "Subkey-Curve: #{subkey_curve}\n" if subkey_curve
+      params << "Subkey-Usage: #{subkey_usage}\n" if subkey_usage
       params << "Name-Real: #{name}\n" if name
       params << "Name-Comment: #{comment}\n" if comment
       params << "Name-Email: #{email}\n" if email
       params << "Expire-Date: #{expire_date}\n" if expire_date
+      params << "Creation-Date: #{creation_date}\n" if creation_date
       params << "Passphrase: #{passphrase}\n" if passphrase
       params << "%commit"
-      command = "#{executable} --batch --gen-key --no-tty"
 
-      out, err, status = Open3.capture3(command, binmode: true, stdin_data: params)
-      logger&.debug { "IOStreams::Pgp.generate_key: #{command}\n#{params}\n#{err}#{out}" }
+      command = gpg_command("--batch", "--gen-key", "--no-tty")
+
+      out, err, status = Open3.capture3(*command, binmode: true, stdin_data: params)
+      # Do not log `params`, it contains the passphrase.
+      IOStreams.logger&.debug { "IOStreams::Pgp.generate_key: #{command.shelljoin}\n#{err}#{out}" }
 
       raise(Pgp::Failure, "GPG Failed to generate key: #{err}#{out}") unless status.success?
 
@@ -127,14 +201,17 @@ module IOStreams
     #     date:       [String]
     #     name:       [String]
     #     email:      [String]
+    #     private:    [true|false]
+    #     trust:      [String]
     # Returns [] if no keys were found.
     def self.list_keys(email: nil, key_id: nil, private: false)
       version_check
-      cmd     = private ? "--list-secret-keys" : "--list-keys"
-      command = "#{executable} #{cmd} #{email || key_id}"
+      args = [private ? "--list-secret-keys" : "--list-keys"]
+      args << (email || key_id).to_s if email || key_id
+      command = gpg_command(*args)
 
-      out, err, status = Open3.capture3(command, binmode: true)
-      logger&.debug { "IOStreams::Pgp.list_keys: #{command}\n#{err}#{out}" }
+      out, err, status = Open3.capture3(*command, binmode: true)
+      IOStreams.logger&.debug { "IOStreams::Pgp.list_keys: #{command.shelljoin}\n#{err}#{out}" }
       if status.success? && out.length.positive?
         parse_list_output(out)
       else
@@ -156,12 +233,14 @@ module IOStreams
     #     date:       [String]
     #     name:       [String]
     #     email:      [String]
+    #     private:    [true|false]
+    #     trust:      [String]
     def self.key_info(key:)
       version_check
-      command = "#{executable} --batch --no-tty"
+      command = gpg_command("--batch", "--no-tty")
 
-      out, err, status = Open3.capture3(command, binmode: true, stdin_data: key)
-      logger&.debug { "IOStreams::Pgp.key_info: #{command}\n#{err}#{out}" }
+      out, err, status = Open3.capture3(*command, binmode: true, stdin_data: key)
+      IOStreams.logger&.debug { "IOStreams::Pgp.key_info: #{command.shelljoin}\n#{err}#{out}" }
 
       # Try parsing even if we get an error - some versions of GPG return non-zero status but still output key info
       unless (status.success? || err.include?("key ID") || out.include?("pub")) && out.length.positive?
@@ -186,16 +265,18 @@ module IOStreams
     def self.export(email:, ascii: true, private: false, passphrase: nil)
       version_check
 
-      command = "#{executable} "
-      command << "--pinentry-mode loopback " if pgp_version.to_f >= 2.1
-      command << "--no-symkey-cache " if pgp_version.to_f >= 2.4
-      command << "--armor " if ascii
-      command << "--no-tty  --batch --passphrase"
-      command << (passphrase ? " #{passphrase} " : "-fd 0 ")
-      command << (private ? "--export-secret-keys #{email}" : "--export #{email}")
+      args = []
+      args += ["--pinentry-mode", "loopback"] if pgp_version.to_f >= 2.1
+      args << "--no-symkey-cache" if pgp_version.to_f >= 2.4
+      args << "--armor" if ascii
+      args += ["--no-tty", "--batch"]
+      args += passphrase ? ["--passphrase", passphrase] : ["--passphrase-fd", "0"]
+      args += private ? ["--export-secret-keys", email.to_s] : ["--export", email.to_s]
+      command = gpg_command(*args)
 
-      out, err, status = Open3.capture3(command, binmode: true)
-      logger&.debug { "IOStreams::Pgp.export: #{command}\n#{err}" }
+      out, err, status = Open3.capture3(*command, binmode: true)
+      # Do not log the command, it may contain the passphrase.
+      IOStreams.logger&.debug { "IOStreams::Pgp.export: #{email}\n#{err}" }
 
       raise(Pgp::Failure, "GPG Failed reading key: #{email}: #{err}") unless status.success? && out.length.positive?
 
@@ -219,10 +300,10 @@ module IOStreams
     # * Invalidated keys must be removed manually.
     def self.import(key:)
       version_check
-      command = "#{executable} --batch --import"
+      command = gpg_command("--batch", "--import")
 
-      out, err, status = Open3.capture3(command, binmode: true, stdin_data: key)
-      logger&.debug { "IOStreams::Pgp.import: #{command}\n#{err}#{out}" }
+      out, err, status = Open3.capture3(*command, binmode: true, stdin_data: key)
+      IOStreams.logger&.debug { "IOStreams::Pgp.import: #{command.shelljoin}\n#{err}#{out}" }
 
       # Handle both old and new versions of GPG
       # For older versions, the output is in err, for newer ones it might be in out
@@ -316,11 +397,33 @@ module IOStreams
       raise(Pgp::Failure, "GPG Failed importing key: #{err}#{out}")
     end
 
-    # Returns [String] email for the supplied after importing and trusting the key
+    # Imports the supplied key and then marks it as trusted at the supplied trust level.
+    #
+    # Returns [String] email for the supplied key, or its key id when no email is present.
+    #
+    # key: [String]
+    #   The public (or private) key to import and trust.
+    #
+    # trust_level: [Integer]
+    #   The owner-trust level to assign to the imported key, the same levels used by `set_trust`:
+    #     1 : Undefined  (no opinion)
+    #     2 : Never      (do not trust)
+    #     3 : Marginal
+    #     4 : Full
+    #     5 : Ultimate
+    #   Default: 5 : Ultimate
+    #
+    # SECURITY WARNING:
+    #   Only import and trust keys received from a verified, trusted source.
+    #   The default trust level is `5` (Ultimate), which tells GPG to treat the imported key
+    #   as if it were one of your own keys. An ultimately trusted key is implicitly valid and
+    #   can in turn confer validity on other keys it has signed. Importing an attacker supplied
+    #   key at this level allows that attacker to impersonate other recipients.
+    #   When the key cannot be fully verified, supply a lower `trust_level`.
     #
     # Notes:
     # - If the same email address has multiple keys then only the first is currently trusted.
-    def self.import_and_trust(key:)
+    def self.import_and_trust(key:, trust_level: 5)
       raise(ArgumentError, "Key cannot be empty") if key.nil? || (key == "")
 
       key_info = key_info(key: key).last
@@ -330,7 +433,7 @@ module IOStreams
       raise(ArgumentError, "Recipient email or key id cannot be extracted from supplied key") unless email || key_id
 
       import(key: key)
-      set_trust(email: email, key_id: key_id)
+      set_trust(email: email, key_id: key_id, level: trust_level)
       email || key_id
     end
 
@@ -340,50 +443,65 @@ module IOStreams
     # Returns nil if the email was not found
     #
     # After importing keys, they are not trusted and the relevant trust level must be set.
+    #
+    # level: [Integer]
+    #   The owner-trust level to assign to the key:
+    #     1 : Undefined  (no opinion)
+    #     2 : Never      (do not trust)
+    #     3 : Marginal
+    #     4 : Full
+    #     5 : Ultimate
     #   Default: 5 : Ultimate
+    #
+    # SECURITY WARNING:
+    #   Only trust keys received from a verified, trusted source.
+    #   The default trust level is `5` (Ultimate), which tells GPG to treat the key
+    #   as if it were one of your own keys. An ultimately trusted key is implicitly valid and
+    #   can in turn confer validity on other keys it has signed. Trusting an attacker supplied
+    #   key at this level allows that attacker to impersonate other recipients.
+    #   When the key cannot be fully verified, supply a lower `level`.
     def self.set_trust(email: nil, key_id: nil, level: 5)
       version_check
       fingerprint = key_id || fingerprint(email: email)
       return unless fingerprint
 
-      command          = "#{executable} --import-ownertrust"
+      command          = gpg_command("--import-ownertrust")
       trust            = "#{fingerprint}:#{level + 1}:\n"
-      out, err, status = Open3.capture3(command, stdin_data: trust)
-      logger&.debug { "IOStreams::Pgp.set_trust: #{command}\n#{err}#{out}" }
+      out, err, status = Open3.capture3(*command, stdin_data: trust)
+      IOStreams.logger&.debug { "IOStreams::Pgp.set_trust: #{command.shelljoin}\n#{err}#{out}" }
 
       raise(Pgp::Failure, "GPG Failed trusting key: #{err} #{out}") unless status.success?
 
       err
     end
 
-    # DEPRECATED - Use key_ids instead of fingerprints
+    # Internal: resolve an email address to a key fingerprint.
+    # Public callers should identify keys by `key_id` (see #list_keys / #key_info).
     def self.fingerprint(email:)
       version_check
-      Open3.popen2e("#{executable} --list-keys --fingerprint --with-colons #{email}") do |_stdin, out, waith_thr|
+      command = gpg_command("--list-keys", "--fingerprint", "--with-colons", email.to_s)
+      Open3.popen2e(*command) do |_stdin, out, waith_thr|
         output = out.read.chomp
-        if !waith_thr.value.success? && !(output !~ /(public key not found|No public key)/i)
+        if !waith_thr.value.success? && output !~ /(public key not found|No public key)/i
           raise(Pgp::Failure, "GPG Failed calling #{executable} to list keys for #{email}: #{output}")
         end
 
         output.each_line do |line|
-          if (match = line.match(/\Afpr.*::([^\:]*):\Z/))
+          if (match = line.match(/\Afpr.*::([^:]*):\Z/))
             return match[1]
           end
         end
         nil
       end
     end
-
-    def self.logger=(logger)
-      @logger = logger
-    end
+    private_class_method :fingerprint
 
     # Returns [String] the version of pgp currently installed
     def self.pgp_version
       @pgp_version ||= begin
-        command          = "#{executable} --version"
-        out, err, status = Open3.capture3(command)
-        logger&.debug { "IOStreams::Pgp.version: #{command}\n#{err}#{out}" }
+        command          = gpg_command("--version")
+        out, err, status = Open3.capture3(*command)
+        IOStreams.logger&.debug { "IOStreams::Pgp.version: #{command.shelljoin}\n#{err}#{out}" }
         if status.success?
           # Sample output
           #   #{executable} (GnuPG) 2.0.30
@@ -413,12 +531,6 @@ module IOStreams
       end
     end
 
-    @logger = nil
-
-    def self.logger
-      @logger
-    end
-
     def self.version_check
       # Previously, this method raised an error for versions >= 2.4
       # Now we support versions up to and including 2.4.7
@@ -507,6 +619,13 @@ module IOStreams
       results
     end
 
+    def self.reject_newlines!(**fields)
+      fields.each_pair do |field, value|
+        next if value.nil?
+        raise(ArgumentError, "IOStreams::Pgp.generate_key: :#{field} cannot contain newlines") if value.to_s =~ /[\r\n]/
+      end
+    end
+
     def self.delete_public_or_private_keys(email: nil, key_id: nil, private: false)
       keys = private ? "secret-keys" : "keys"
 
@@ -517,9 +636,9 @@ module IOStreams
         key_id = key_info[:key_id]
         next unless key_id
 
-        command          = "#{executable} --batch --no-tty --yes --delete-#{keys} #{key_id}"
-        out, err, status = Open3.capture3(command, binmode: true)
-        logger&.debug { "IOStreams::Pgp.delete_keys: #{command}\n#{err}#{out}" }
+        command          = gpg_command("--batch", "--no-tty", "--yes", "--delete-#{keys}", key_id)
+        out, err, status = Open3.capture3(*command, binmode: true)
+        IOStreams.logger&.debug { "IOStreams::Pgp.delete_keys: #{command.shelljoin}\n#{err}#{out}" }
 
         unless status.success?
           raise(Pgp::Failure, "GPG Failed calling #{executable} to delete #{keys} for #{email || key_id}: #{err}: #{out}")
@@ -532,18 +651,27 @@ module IOStreams
     def self.delete_public_or_private_keys_v1(email: nil, key_id: nil, private: false)
       keys = private ? "secret-keys" : "keys"
 
-      command = "for i in `#{executable} --list-#{keys} --with-colons --fingerprint #{email || key_id} | grep \"^fpr\" | cut -d: -f10`; do\n"
-      command << "#{executable} --batch --no-tty --yes --delete-#{keys} \"$i\" ;\n"
-      command << "done"
+      # List the fingerprints, then delete each one. Previously this shelled out
+      # to a `for` loop, which allowed shell injection via :email / :key_id.
+      list_command        = gpg_command("--list-#{keys}", "--with-colons", "--fingerprint", (email || key_id).to_s)
+      list_out, list_err, = Open3.capture3(*list_command, binmode: true)
+      IOStreams.logger&.debug { "IOStreams::Pgp.delete_keys: #{list_command.shelljoin}\n#{list_err}: #{list_out}" }
+
+      return false if list_err =~ /(not found|no public key)/i
+
+      fingerprints = list_out.each_line.select { |line| line.start_with?("fpr") }.map { |line| line.split(":")[9] }.compact
+      return false if fingerprints.empty?
 
-      out, err, status = Open3.capture3(command, binmode: true)
-      logger&.debug { "IOStreams::Pgp.delete_keys: #{command}\n#{err}: #{out}" }
+      fingerprints.each do |fingerprint|
+        command          = gpg_command("--batch", "--no-tty", "--yes", "--delete-#{keys}", fingerprint)
+        out, err, status = Open3.capture3(*command, binmode: true)
+        IOStreams.logger&.debug { "IOStreams::Pgp.delete_keys: #{command.shelljoin}\n#{err}: #{out}" }
 
-      return false if err =~ /(not found|no public key)/i
-      unless status.success?
-        raise(Pgp::Failure, "GPG Failed calling #{executable} to delete #{keys} for #{email || key_id}: #{err}: #{out}")
+        unless status.success?
+          raise(Pgp::Failure, "GPG Failed calling #{executable} to delete #{keys} for #{email || key_id}: #{err}: #{out}")
+        end
+        raise(Pgp::Failure, "GPG Failed to delete #{keys} for #{email || key_id} #{err.strip}: #{out}") if out.include?("error")
       end
-      raise(Pgp::Failure, "GPG Failed to delete #{keys} for #{email || key_id} #{err.strip}: #{out}") if out.include?("error")
 
       true
     end

data/lib/io_streams/reader.rb

@@ -10,13 +10,13 @@ module IOStreams
     end
 
     # When a Writer supports streams, also allow it to simply support a file
-    def self.file(file_name, original_file_name: file_name, **args, &block)
-      ::File.open(file_name, "rb") { |file| stream(file, original_file_name: original_file_name, **args, &block) }
+    def self.file(file_name, **args, &block)
+      ::File.open(file_name, "rb") { |file| stream(file, **args, &block) }
     end
 
     # For processing by either a file name or an open IO stream.
-    def self.open(file_name_or_io, **args, &block)
-      file_name_or_io.is_a?(String) ? file(file_name_or_io, **args, &block) : stream(file_name_or_io, **args, &block)
+    def self.open(file_name_or_io, **args, &)
+      file_name_or_io.is_a?(String) ? file(file_name_or_io, **args, &) : stream(file_name_or_io, **args, &)
     end
 
     attr_reader :input_stream

data/lib/io_streams/record/reader.rb

@@ -16,7 +16,7 @@ module IOStreams
 
       # When reading from a file also add the line reader stream
       def self.file(file_name, original_file_name: file_name, delimiter: $/, **args)
-        IOStreams::Line::Reader.file(file_name, original_file_name: original_file_name, delimiter: delimiter) do |io|
+        IOStreams::Line::Reader.file(file_name, delimiter: delimiter) do |io|
           yield new(io, original_file_name: original_file_name, **args)
         end
       end
@@ -35,11 +35,10 @@ module IOStreams
       #   format_options: [Hash]
       #     Any specialized format specific options. For example, `:fixed` format requires the file definition.
       #
-      #   columns [Array<String>]
+      #   columns [Array<String|Symbol>]
       #     The header columns when the file does not include a header row.
       #     Note:
-      #       It is recommended to keep all columns as strings to avoid any issues when persistence
-      #       with MongoDB when it converts symbol keys to strings.
+      #       Column names are converted to strings.
       #
       #   allowed_columns [Array<String>]
       #     List of columns to allow.

data/lib/io_streams/record/writer.rb

@@ -18,7 +18,7 @@ module IOStreams
 
       # When writing to a file also add the line writer stream
       def self.file(file_name, original_file_name: file_name, delimiter: $/, **args, &block)
-        IOStreams::Line::Writer.file(file_name, original_file_name: original_file_name, delimiter: delimiter) do |io|
+        IOStreams::Line::Writer.file(file_name, delimiter: delimiter) do |io|
           yield new(io, original_file_name: original_file_name, **args, &block)
         end
       end
@@ -37,11 +37,10 @@ module IOStreams
       #   format_options: [Hash]
       #     Any specialized format specific options. For example, `:fixed` format requires the file definition.
       #
-      #   columns [Array<String>]
+      #   columns [Array<String|Symbol>]
       #     The header columns when the file does not include a header row.
       #     Note:
-      #       It is recommended to keep all columns as strings to avoid any issues when persistence
-      #       with MongoDB when it converts symbol keys to strings.
+      #       Column names are converted to strings.
       #
       #   allowed_columns [Array<String>]
       #     List of columns to allow.

data/lib/io_streams/row/reader.rb

@@ -14,7 +14,7 @@ module IOStreams
 
       # When reading from a file also add the line reader stream
       def self.file(file_name, original_file_name: file_name, delimiter: $/, **args)
-        IOStreams::Line::Reader.file(file_name, original_file_name: original_file_name, delimiter: delimiter) do |io|
+        IOStreams::Line::Reader.file(file_name, delimiter: delimiter) do |io|
           yield new(io, original_file_name: original_file_name, **args)
         end
       end

data/lib/io_streams/row/writer.rb

@@ -21,7 +21,7 @@ module IOStreams
 
       # When writing to a file also add the line writer stream
       def self.file(file_name, original_file_name: file_name, delimiter: $/, **args, &block)
-        IOStreams::Line::Writer.file(file_name, original_file_name: original_file_name, delimiter: delimiter) do |io|
+        IOStreams::Line::Writer.file(file_name, delimiter: delimiter) do |io|
           yield new(io, original_file_name: original_file_name, **args, &block)
         end
       end

data/lib/io_streams/stream.rb

@@ -18,8 +18,8 @@ module IOStreams
     # Example:
     #
     # IOStreams.path("tempfile2527").stream(:zip).stream(:pgp, passphrase: "receiver_passphrase").read
-    def stream(stream, **options)
-      builder.stream(stream, **options)
+    def stream(stream, **)
+      builder.stream(stream, **)
       self
     end
 
@@ -33,15 +33,15 @@ module IOStreams
     # IOStreams.path("keep_safe.enc").option(:pgp, passphrase: "receiver_passphrase").read
     #
     # IOStreams.path(output_file_name).option(:pgp, passphrase: "receiver_passphrase").read
-    def option(stream, **options)
-      builder.option(stream, **options)
+    def option(stream, **)
+      builder.option(stream, **)
       self
     end
 
     # Adds the options for the specified stream as an option,
     # but if streams have already been added it is instead added as a stream.
-    def option_or_stream(stream, **options)
-      builder.option_or_stream(stream, **options)
+    def option_or_stream(stream, **)
+      builder.option_or_stream(stream, **)
       self
     end
 
@@ -93,21 +93,26 @@ module IOStreams
     def each(mode = :line, **args, &block)
       raise(ArgumentError, "Invalid mode: #{mode.inspect}") if mode == :stream
 
-      #    return enum_for __method__ unless block_given?
+      # Deliberately not returning an Enumerator when no block is given.
+      # The stream pipeline manages resources via block scope: every stream is opened with an
+      # `ensure` that closes the file handle, reaps the gpg subprocess, deletes temp files, etc.
+      # A Fiber-backed Enumerator (e.g. `to_enum(__method__, mode, **args)`) would leave that block
+      # suspended; if the caller abandons a partially-consumed enumerator, none of the cleanup runs
+      # until GC collects the Fiber, leaking file descriptors, gpg processes, and temp files.
       reader(mode, **args) { |stream| stream.each(&block) }
     end
 
     # Returns a Reader for reading a file / stream
-    def reader(mode = :stream, **args, &block)
+    def reader(mode = :stream, **args, &)
       case mode
       when :stream
-        stream_reader(&block)
+        stream_reader(&)
       when :line
-        line_reader(**args, &block)
+        line_reader(**args, &)
       when :array
-        row_reader(**args, &block)
+        row_reader(**args, &)
       when :hash
-        record_reader(**args, &block)
+        record_reader(**args, &)
       else
         raise(ArgumentError, "Invalid mode: #{mode.inspect}")
       end
@@ -124,16 +129,16 @@ module IOStreams
     end
 
     # Returns a Writer for writing to a file / stream
-    def writer(mode = :stream, **args, &block)
+    def writer(mode = :stream, **args, &)
       case mode
       when :stream
-        stream_writer(&block)
+        stream_writer(&)
       when :line
-        line_writer(**args, &block)
+        line_writer(**args, &)
       when :array
-        row_writer(**args, &block)
+        row_writer(**args, &)
       when :hash
-        record_writer(**args, &block)
+        record_writer(**args, &)
       else
         raise(ArgumentError, "Invalid mode: #{mode.inspect}")
       end
@@ -171,7 +176,7 @@ module IOStreams
     # IOStreams.path("target_file.json").copy_from("source_file_name.csv.gz", convert: false)
     #
     # # Advanced copy with custom stream conversions on source and target.
-    # source = IOStreams.path("source_file").stream(encoding: "BINARY")
+    # source = IOStreams.path("source_file").stream(:encode, encoding: "BINARY")
     # IOStreams.path("target_file.pgp").option(:pgp, passphrase: "hello").copy_from(source)
     def copy_from(source, convert: true, mode: nil, **args)
       if convert
@@ -322,18 +327,19 @@ module IOStreams
       @builder ||= IOStreams::Builder.new
     end
 
-    def stream_reader(&block)
-      builder.reader(io_stream, &block)
+    def stream_reader(&)
+      builder.reader(io_stream, &)
     end
 
     def line_reader(embedded_within: nil, **args)
       embedded_within = '"' if embedded_within.nil? && builder.file_name&.include?(".csv")
 
       stream_reader do |io|
-        yield IOStreams::Line::Reader.new(io,
-                                          original_file_name: builder.file_name,
-                                          embedded_within:    embedded_within,
-                                          **args)
+        yield IOStreams::Line::Reader.new(
+          io,
+          embedded_within: embedded_within,
+          **args
+        )
       end
     end
 
@@ -363,20 +369,20 @@ module IOStreams
       end
     end
 
-    def stream_writer(&block)
-      builder.writer(io_stream, &block)
+    def stream_writer(&)
+      builder.writer(io_stream, &)
     end
 
     def line_writer(**args, &block)
-      return block.call(io_stream) if io_stream&.is_a?(IOStreams::Line::Writer)
+      return block.call(io_stream) if io_stream.is_a?(IOStreams::Line::Writer)
 
       writer do |io|
-        IOStreams::Line::Writer.stream(io, original_file_name: builder.file_name, **args, &block)
+        IOStreams::Line::Writer.stream(io, **args, &block)
       end
     end
 
     def row_writer(delimiter: $/, **args, &block)
-      return block.call(io_stream) if io_stream&.is_a?(IOStreams::Row::Writer)
+      return block.call(io_stream) if io_stream.is_a?(IOStreams::Row::Writer)
 
       line_writer(delimiter: delimiter) do |io|
         IOStreams::Row::Writer.stream(
@@ -391,7 +397,7 @@ module IOStreams
     end
 
     def record_writer(delimiter: $/, **args, &block)
-      return block.call(io_stream) if io_stream&.is_a?(IOStreams::Record::Writer)
+      return block.call(io_stream) if io_stream.is_a?(IOStreams::Record::Writer)
 
       line_writer(delimiter: delimiter) do |io|
         IOStreams::Record::Writer.stream(

data/lib/io_streams/symmetric_encryption/reader.rb

@@ -2,10 +2,10 @@ module IOStreams
   module SymmetricEncryption
     class Reader < IOStreams::Reader
       # read from a file/stream using Symmetric Encryption
-      def self.stream(input_stream, **args, &block)
+      def self.stream(input_stream, **args, &)
         Utils.load_soft_dependency("symmetric-encryption", ".enc streaming") unless defined?(SymmetricEncryption)
 
-        ::SymmetricEncryption::Reader.open(input_stream, **args, &block)
+        ::SymmetricEncryption::Reader.open(input_stream, **args, &)
       end
     end
   end